URIs 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.dtd
may 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.html
may actually load the same thing asnbres:/org/netbeans/modules/foo/resources/foo''nb''ja.html
. -
nbdocs
- same asnbresloc
but also searches indocs/
subfolders of installation directories, e.g.nbdocs:/org/netbeans/modules/usersguide/ide.css
may work likefile:/opt/netbeans/ide4/docs/org/netbeans/modules/usersguide/ide.css
. -
nbinst
- loads installation files usingInstalledFileLocator
in installation directories, e.g.nbinst:///modules/ext/some-lib.jar
may 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.html
refers 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