URIs and URLs

Apache NetBeans Wiki Index

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 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 as jar: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 as nbres:/org/netbeans/modules/foo/resources/foo''nb''ja.html.

  • nbdocs - same as nbresloc but also searches in docs/ subfolders of installation directories, e.g. nbdocs:/org/netbeans/modules/usersguide/ide.css may work like file:/opt/netbeans/ide4/docs/org/netbeans/modules/usersguide/ide.css.

  • nbinst - loads installation files using InstalledFileLocator in installation directories, e.g. nbinst:///modules/ext/some-lib.jar may load the same thing as file:/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