netbeans.apache.org/src/content/wiki/DevFaqUriVsUrl.asciidoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= DevFaqUriVsUrl
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:jbake-status: published
:keywords: Apache NetBeans wiki DevFaqUriVsUrl
:description: Apache NetBeans wiki DevFaqUriVsUrl
:toc: left
:toc-title:
:syntax: true

=== 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 link:http://wiki.netbeans.org/DevFaqUriVsUrl[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.