Examples of org.eclipse.emf.common.util.URI

• org.eclipse.emf.common.util.URI
  etf.org/rfc/rfc2396.txt">RFC 2396, with certain enhancements. A URI instance can be created by specifying values for its components, or by providing a single URI string, which is parsed into its components. Static factory methods whose names begin with "create" are used for both forms of object creation. No public or protected constructors are provided; this class can not be subclassed.

  Like String, URI is an immutable class; a URI instance offers several by-value methods that return a new URI object based on its current state. Most useful, a relative URI can be {@link #resolve(URI) resolve}d against a base absolute URI -- the latter typically identifies the document in which the former appears. The inverse to this is {@link #deresolve(URI) deresolve}, which answers the question, "what relative URI will resolve, against the given base, to this absolute URI?"

  In the RFC, much attention is focused on a hierarchical naming system used widely to locate resources via common protocols such as HTTP, FTP, and Gopher, and to identify files on a local file system. Accordingly, most of this class's functionality is for handling such URIs, which can be identified via {@link #isHierarchical isHierarchical}.

  The primary enhancement beyond the RFC description is an optional device component. Instead of treating the device as just another segment in the path, it can be stored as a separate component (almost a sub-authority), with the root below it. For example, resolving /bar against file:///c:/foo would result in file:///c:/bar being returned. Also, you cannot take the parent of a device, so resolving .. against file:///c:/ would not yield file:///, as you might expect. This feature is useful when working with file-scheme URIs, as devices do not typically occur in protocol-based ones. A device-enabled URI is created by parsing a string with {@link #createURI(String) createURI}; if the first segment of the path ends with the : character, it is stored (including the colon) as the device, instead. Alternately, either the {@link #createHierarchicalURI(String,String,String,String,String) no-path}or the {@link #createHierarchicalURI(String,String,String,String[],String,String) absolute-path} form of createHierarchicalURI()can be used, in which a non-null device parameter can be specified.

  The other enhancement provides support for the almost-hierarchical form used for files within archives, such as the JAR scheme, defined for the Java Platform in the documentation for {@link java.net.JarURLConnection}. By default, this support is enabled for absolute URIs with scheme equal to "jar", "zip", or "archive" (ignoring case), and is implemented by a hierarchical URI, whose authority includes the entire URI of the archive, up to and including the ! character. The URI of the archive must have no fragment. The whole archive URI must have no device and an absolute path. Special handling is supported for {@link #createURI(String) creating}, {@link #validArchiveAuthority validating}, {@link #devicePath getting the path}from, and {@link #toString() displaying} archive URIs. In all otheroperations, including {@link #resolve(URI) resolving} and {@link #deresolve(URI) deresolving}, they are handled like any ordinary URI. The schemes that identify archive URIs can be changed from their default by setting the org.eclipse.emf.common.util.URI.archiveSchemes system property. Multiple schemes should be space separated, and the test of whether a URI's scheme matches is always case-insensitive.

  This implementation does not impose all of the restrictions on character validity that are specified in the RFC. Static methods whose names begin with "valid" are used to test whether a given string is valid value for the various URI components. Presently, these tests place no restrictions beyond what would have been required in order for {@link #createURI(String) createURI} to have parsed them correctly from a singleURI string. If necessary in the future, these tests may be made more strict, to better conform to the RFC.

  Another group of static methods, whose names begin with "encode", use percent escaping to encode any characters that are not permitted in the various URI components. Another static method is provided to {@link #decode decode} encoded strings. An escaped character is represented asa percent symbol (%), followed by two hex digits that specify the character code. These encoding methods are more strict than the validation methods described above. They ensure validity according to the RFC, with one exception: non-ASCII characters.

  The RFC allows only characters that can be mapped to 7-bit US-ASCII representations. Non-ASCII, single-byte characters can be used only via percent escaping, as described above. This implementation uses Java's Unicode char and String representations, and makes no attempt to encode characters 0xA0 and above. Characters in the range 0x80-0x9F are still escaped. In this respect, EMF's notion of a URI is actually more like an IRI (Internationalized Resource Identifier), for which an RFC is now in draft form.

  Finally, note the difference between a null parameter to the static factory methods and an empty string. The former signifies the absence of a given URI component, while the latter simply makes the component blank. This can have a significant effect when resolving. For example, consider the following two URIs: /bar (with no authority) and ///bar (with a blank authority). Imagine resolving them against a base with an authority, such as http://www.eclipse.org/. The former case will yield http://www.eclipse.org/bar, as the base authority will be preserved. In the latter case, the empty authority will override the base authority, resulting in http:///bar!

Related Classes of org.eclipse.emf.common.util.URI