Skip to content

8294872: Document "resource" protocol #2251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sashamatveev wants to merge 2 commits into
base: master
Choose a base branch
from
Open

8294872: Document "resource" protocol #2251

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
da41091
8294872: Document "resource" protocol
sashamatveev Aug 6, 2026
c3b97eb
8294872: Document "resource" protocol [v2]
sashamatveev Aug 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions modules/javafx.media/src/main/java/javafx/scene/media/Media.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2010, 2024, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2010, 2026, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -336,7 +336,7 @@ public final ObservableMap<String, Duration> getMarkers() {
/**
* Constructs a <code>Media</code> instance. This is the only way to
* specify the media source. The source must represent a valid <code>URI</code>
* and is immutable. Only HTTP, HTTPS, FILE, and JAR <code>URL</code>s are supported. If the
* and is immutable. Only HTTP, HTTPS, FILE, JAR, and RESOURCE <code>URL</code>s are supported. If the

@andy-goryachev-oracle andy-goryachev-oracle Aug 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just out of curiosity, could we use the actual codes ("https:", "jar:", ...) instead of HTTPS, JAR, ...?

* provided URL is invalid then an exception will be thrown. If an
* asynchronous error occurs, the {@link #errorProperty error} property will be set. Listen
* to this property to be notified of any such errors.
Expand All @@ -352,13 +352,15 @@ public final ObservableMap<String, Duration> getMarkers() {
* <p>Constraints:
* <ul>
* <li>The supplied URI must conform to RFC-2396 as required by
* <A href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</A>.</li>
* <li>Only HTTP, HTTPS, FILE, and JAR URIs are supported.</li>
* <a href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</a>.</li>

@andy-goryachev-oracle andy-goryachev-oracle Aug 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why are we referencing java8 docs?
shouldn't it be a relative ref?

@sashamatveev sashamatveev Aug 6, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

URI is not part of JavaFX, so we cannot use relative ref. Also, I found that JavaFX docs a published in several places, so using something like "../../URI.html" will not work.

I can update Java 8 links to latest, but I am not sure what policy we have in term of referencing old JDK releases and should we keep updating it to latest docs with each release. For example JavaFX 27 will point to JDK 27 docs.

@AnirvanSarkar AnirvanSarkar Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gradle is configured to generate Javadocs with links to the documentation for the supported JDK version.

See:

Therefore, you should be able to replace:

<a href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</a>

with:

{@link java.net.URI}

* <li>Only HTTP, HTTPS, FILE, JAR, and RESOURCE URIs are supported.
* RESOURCE URIs are supported only in statically linked applications.</li>
* </ul>
*
* <p>See <A href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</A>
* <p>See <a href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</a>
* for more information about URI formatting in general.
* JAR URL syntax is specified in <a href="https://docs.oracle.com/javase/8/docs/api/java/net/JarURLConnection.html">java.net.JarURLConnection</A>.
* JAR URL syntax is specified in <a href="https://docs.oracle.com/javase/8/docs/api/java/net/JarURLConnection.html">java.net.JarURLConnection</a>.
* RESOURCE URL syntax is specified in <a href="https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/URLProtocols/">URL Protocols in Native Image</a>.

@andy-goryachev-oracle andy-goryachev-oracle Aug 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

similar question: why refer to graalvm.org?
shouldn't we point to some authoritative document instead?

@sashamatveev sashamatveev Aug 7, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found this one https://docs.oracle.com/en/graalvm/jdk/25/docs/reference-manual/native-image/dynamic-features/URLProtocols/, but it does not point to latest as graalvm.org. I do not see any problems with pointing to graalvm.org. Is there any concerns?

*
* @param source The URI of the source media.
* @throws NullPointerException if the URI string is <code>null</code>.
Expand Down
7 changes: 6 additions & 1 deletion modules/javafx.media/src/main/java/javafx/scene/media/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2013, 2025, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2013, 2026, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -138,6 +138,11 @@
* <td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/JarURLConnection.html">java.net.JarURLConnection</a></td>
* </tr>
* <tr>
* <th scope="row">RESOURCE</th>
* <td>Representation of media resources bundled in a statically linked application image</td>
* <td><a href="https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/URLProtocols/">URL Protocols in Native Image</a></td>
* </tr>
* <tr>
* <th scope="row">HTTP Live Streaming (HLS)</th>
* <td>Playlist-based media streaming via HTTP or HTTPS</td>
* <td><a href="https://datatracker.ietf.org/doc/html/rfc8216">HTTP Live Streaming (RFC 8216)</a></td>
Expand Down