Apache NetBeansURIs and URLs
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 java.net.URI or java.net.URL?
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
URL. URI seems to have difficulty with the jar protocol.
Q: Can I interconvert `URI`s and `URL`s?
A: Yes, use uri.toURL() and
URI.create(url.toExternalForm()).
Q: Can I interconvert `File`s and `URI`s?
A: Easily. Use file.toURI(). In the other
direction, use new File(uri).
For URL`s, go through `URI. Never use
file.toURL(); it does not handle unusual characters
correctly.
Careful with file URLs/URIs denoting directories. NetBeans
APIs generally expect these to end in a slash
(/). However 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?
A: Use fileObject.getURL(), or
URLMapper methods for more control over the kind of
returned protocol; in the other direction, use
URLMapper.findFileObject(url).
For URIs, go through URL.
Q: How do jar URLs work?
A: Unlike e.g. URLClassLoader, in the NetBeans
APIs 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
jar:file:/tmp/foo.jar!/. FileUtil has
methods (getArchiveFile, getArchiveRoot, and
isArchiveFile) to help you convert between these
representations.
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 asjar:file:/opt/netbeans/ide4/modules/org-netbeans-modules-foo.jar!/org/netbeans/modules/foo/resources/foo.dtd. -
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 asnbres:/org/netbeans/modules/foo/resources/foo''nb''ja.html. -
nbdocs- same asnbreslocbut also searches indocs/subfolders of installation directories, e.g.nbdocs:/org/netbeans/modules/usersguide/ide.cssmay work likefile:/opt/netbeans/ide4/docs/org/netbeans/modules/usersguide/ide.css. -
nbinst- loads installation files usingInstalledFileLocatorin installation directories, e.g.nbinst:///modules/ext/some-lib.jarmay load the same thing asfile:/opt/netbeans/ide4/modules/ext/some-lib.jar. -
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 java.net.URL, 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
