URIs and URLs
Note: These pages are being reviewed.
Q: What is the difference?
A: A URL is a kind of URI. URNs such as
urn:oasis:foo are URIs but not URLs.
Q: Should I use
A: Whichever is more convenient.
URL`s must use a registered
URL protocol and cannot handle URNs; there is slightly more overhead
in making a URL than a URI, but not much. `URI provides better methods
for relativizing and canonicalizing URLs as well as other operations
on the syntactic structure. To directly load content you need to use a
URI seems to have difficulty with the
Q: Can I interconvert `URI`s and `URL`s?
A: Yes, use
Q: Can I interconvert `File`s and `URI`s?
A: Easily. Use
file.toURI(). In the other
URL`s, go through `URI. Never use
file.toURL(); it does not handle unusual characters
Careful with file URLs/URIs denoting directories. NetBeans
APIs generally expect these to end in a slash
file.toURI() will not end in a
slash if the file does not currently exist! Be sure to check if the
URI ends in a slash and add one if not, if you in fact know that the
File is intended to represent a directory.
Q: Can I interconvert `FileObject`s and URLs?
URLMapper methods for more control over the kind of
returned protocol; in the other direction, use
For URIs, go through URL.
Q: How do
jar URLs work?
A: Unlike e.g.
URLClassLoader, in the NetBeans
file:/tmp/foo.jar refers to the raw byte contents of
foo.jar. To refer to the root entry of the JAR (e.g. for
use as a classpath entry) you must use
isArchiveFile) to help you convert between these
Q: Which URL protocols are used in NetBeans?
A: Several, including some custom protocols:
file- for representing files on disk.
jar- for representing entries inside JARs and ZIPs, including the root directory entry.
nbres- a resource loaded from a NetBeans module (or technically the cross-module class loader), e.g.
nbres:/org/netbeans/modules/foo/resources/foo.dtdmay load the same thing as
nbresloc- same, but transparently localized and branded according to the usual conventions, e.g.
nbresloc:/org/netbeans/modules/foo/resources/foo.htmlmay actually load the same thing as
nbdocs- same as
nbreslocbut also searches in
docs/subfolders of installation directories, e.g.
nbdocs:/org/netbeans/modules/usersguide/ide.cssmay work like
nbinst- loads installation files using
InstalledFileLocatorin installation directories, e.g.
nbinst:///modules/ext/some-lib.jarmay load the same thing as
nbfs- refers to a file object. As of NetBeans 4.0 there are no user-mounted filesystems so this is only useful to refer to file objects in the system filesystem (XML layers). For example,
nbfs:/SystemFileSystem/Templates/Other/html.htmlrefers to an HTML file templates installed in the IDE.
Also note that, unlike
URI.equals() does not make a network connection to determine equality. Never put URLs into a HashSet or similar equality-testing collection for this reason.
Applies to: NetBeans 4.0, 4.1, 5.0, 5.5, 6.0, 6.1, 6.5, 6.7