Apache NetBeans Wiki Index

Note: These pages are being reviewed.

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 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

Apache Migration Information

The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.

This page was exported from http://wiki.netbeans.org/DevFaqUriVsUrl , that was last modified by NetBeans user Tboudreau on 2010-01-24T05:45:04Z.

NOTE: This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed.