URI (EMF Javadoc)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.emf.common.util
Class URI

java.lang.Object
  org.eclipse.emf.common.util.URI

public final class URI
extends java.lang.Object
extends java.lang.Object

A representation of a Uniform Resource Identifier (URI), as specified by 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 resolved against a base absolute URI -- the latter typically identifies the document in which the former appears. The inverse to this is 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 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 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 no-path or the 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 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 creating, validating, getting the path from, and displaying archive URIs. In all other operations, including resolving and 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 createURI to have parsed them correctly from a single URI 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 decode encoded strings. An escaped character is represented as a 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!

Field Summary
`static int`	`FRAGMENT_FIRST_SEPARATOR` When specified as the last argument to `createURI`, indicates that the first `#` character should be taken as the fragment separator, and any others should be encoded.
`static int`	`FRAGMENT_LAST_SEPARATOR` When specified as the last argument to `createURI`, indicates that the last `#` character should be taken as the fragment separator, and any others should be encoded.
`static int`	`FRAGMENT_NONE` When specified as the last argument to `createURI`, indicates that there is no fragment, so any `#` characters should be encoded.

Method Summary
`URI`	`appendFileExtension(java.lang.String fileExtension)` Returns the URI formed by appending a period (".") followed by the specified file extension to the last path segment of this URI, if it is hierarchical with a non-empty path ending in a non-empty segment; otherwise, this URI is returned unchanged.
`URI`	`appendFragment(java.lang.String fragment)` Returns the URI formed from this URI and the given fragment.
`URI`	`appendQuery(java.lang.String query)` Returns the URI formed from this URI and the given query.
`URI`	`appendSegment(java.lang.String segment)` Returns the URI formed by appending the specified segment on to the end of the path of this URI, if hierarchical; this URI unchanged, otherwise.
`URI`	`appendSegments(java.lang.String[] segments)` Returns the URI formed by appending the specified segments on to the end of the path of this URI, if hierarchical; this URI unchanged, otherwise.
`java.lang.String`	`authority()` If this is a hierarchical URI with an authority component, returns it; `null` otherwise.
`static URI`	`createDeviceURI(java.lang.String uri)` Deprecated. Use `createURI`, which now has explicit device support enabled. The two methods now operate identically.
`static URI`	`createFileURI(java.lang.String pathName)` Static factory method based on parsing a `File` path string.
`static URI`	`createGenericURI(java.lang.String scheme, java.lang.String opaquePart, java.lang.String fragment)` Static factory method for a generic, non-hierarchical URI.
`static URI`	`createHierarchicalURI(java.lang.String[] segments, java.lang.String query, java.lang.String fragment)` Static factory method for a relative hierarchical URI with relative path.
`static URI`	`createHierarchicalURI(java.lang.String scheme, java.lang.String authority, java.lang.String device, java.lang.String[] segments, java.lang.String query, java.lang.String fragment)` Static factory method for a hierarchical URI with absolute path.
`static URI`	`createHierarchicalURI(java.lang.String scheme, java.lang.String authority, java.lang.String device, java.lang.String query, java.lang.String fragment)` Static factory method for a hierarchical URI with no path.
`static URI`	`createPlatformPluginURI(java.lang.String pathName, boolean encode)` Static factory method based on parsing a plug-in-based path string, with an option to encode the created URI.
`static URI`	`createPlatformResourceURI(java.lang.String pathName)` Deprecated. org.eclipse.emf.common 2.3 Use `createPlatformResourceURI(String, boolean)` instead.
`static URI`	`createPlatformResourceURI(java.lang.String pathName, boolean encode)` Static factory method based on parsing a workspace-relative path string, with an option to encode the created URI.
`static URI`	`createURI(java.lang.String uri)` Static factory method based on parsing a URI string, with explicit device support and handling for archive URIs enabled.
`static URI`	`createURI(java.lang.String uri, boolean ignoreEscaped)` Static factory method that encodes and parses the given URI string.
`static URI`	`createURI(java.lang.String uri, boolean ignoreEscaped, int fragmentLocationStyle)` Static factory method that encodes and parses the given URI string.
`static URI`	`createURIWithCache(java.lang.String uri)` Deprecated. Please use `createURI` instead.
`static java.lang.String`	`decode(java.lang.String value)` Decodes the given string by interpreting three-digit escape sequences as the bytes of a UTF-8 encoded character and replacing them with the characters they represent.
`URI`	`deresolve(URI base)` Finds the shortest relative or, if necessary, the absolute URI that, when resolved against the given `base` absolute hierarchical URI using `resolve`, will yield this absolute URI.
`URI`	`deresolve(URI base, boolean preserveRootParents, boolean anyRelPath, boolean shorterRelPath)` Finds an absolute URI that, when resolved against the given `base` absolute hierarchical URI using `resolve`, will yield this absolute URI.
`java.lang.String`	`device()` If this is a hierarchical URI with a device component, returns it; `null` otherwise.
`java.lang.String`	`devicePath()` If this is a hierarchical URI with a path, returns a string representation of the path, including the authority and the device component; `null` otherwise.
`static java.lang.String`	`encodeAuthority(java.lang.String value, boolean ignoreEscaped)` Encodes a string so as to produce a valid authority, as defined by the RFC.
`static java.lang.String`	`encodeFragment(java.lang.String value, boolean ignoreEscaped)` Encodes a string so as to produce a valid fragment, as defined by the RFC.
`static java.lang.String`	`encodeOpaquePart(java.lang.String value, boolean ignoreEscaped)` Encodes a string so as to produce a valid opaque part value, as defined by the RFC.
`static java.lang.String`	`encodeQuery(java.lang.String value, boolean ignoreEscaped)` Encodes a string so as to produce a valid query, as defined by the RFC.
`static java.lang.String`	`encodeSegment(java.lang.String value, boolean ignoreEscaped)` Encodes a string so as to produce a valid segment, as defined by the RFC.
`boolean`	`equals(java.lang.Object object)` Returns `true` if `object` is an instance of `URI` equal to this one; `false` otherwise.
`java.lang.String`	`fileExtension()` If this is a hierarchical URI whose path includes a file extension, that file extension is returned; null otherwise.
`java.lang.String`	`fragment()` If this URI has a fragment component, returns it; `null` otherwise.
`boolean`	`hasAbsolutePath()` Returns `true` if this is a hierarchical URI with an absolute path, or `false` if it is non-hierarchical, has no path, or has a relative path.
`boolean`	`hasAuthority()` Returns `true` if this is a hierarchical URI with an authority component; `false` otherwise.
`boolean`	`hasDevice()` Returns `true` if this is a hierarchical URI with a device component; `false` otherwise.
`boolean`	`hasEmptyPath()` Returns `true` if this is a hierarchical URI with an empty relative path; `false` otherwise.
`boolean`	`hasFragment()` Returns `true` if this URI has a fragment component; `false` otherwise.
`int`	`hashCode()` Returns the hash code.
`boolean`	`hasOpaquePart()` Returns `true` if this is a non-hierarchical URI with an opaque part component; `false` otherwise.
`boolean`	`hasPath()` Returns `true` if this is a hierarchical URI with an absolute or relative path; `false` otherwise.
`boolean`	`hasQuery()` Returns `true` if this is a hierarchical URI with a query component; `false` otherwise.
`boolean`	`hasRelativePath()` Returns `true` if this is a hierarchical URI with a relative path, or `false` if it is non-hierarchical, has no path, or has an absolute path.
`boolean`	`hasTrailingPathSeparator()` Returns `true` if this is a hierarchical URI that has a path that ends with a trailing separator; `false` otherwise.
`java.lang.String`	`host()` If this is a hierarchical URI with an authority component that has a host portion, returns it; `null` otherwise.
`boolean`	`isArchive()` Returns `true` if this is an archive URI.
`static boolean`	`isArchiveScheme(java.lang.String value)` Returns `true` if the specified `value` would be valid as the scheme of an archive URI; `false` otherwise.
`boolean`	`isCurrentDocumentReference()` Returns `true` if this is a current document reference; that is, if it is a relative hierarchical URI with no authority, device or query components, and no path segments; `false` is returned otherwise.
`boolean`	`isEmpty()` Returns `true` if this is a `current document reference` with no fragment component; `false` otherwise.
`boolean`	`isFile()` Returns `true` if this is a hierarchical URI that may refer directly to a locally accessible file.
`boolean`	`isHierarchical()` Returns `true` if this a a hierarchical URI, or `false` if it is of the generic form.
`boolean`	`isPlatform()` Returns `true` if this is a platform URI, that is, an absolute, hierarchical URI, with "platform" scheme, no authority, and at least two segments; `false` is returned otherwise.
`boolean`	`isPlatformPlugin()` Returns `true` if this is a platform plug-in URI, that is, a `platform URI` whose first segment is "plugin"; `false` is returned otherwise.
`boolean`	`isPlatformResource()` Returns `true` if this is a platform resource URI, that is, a `platform URI` whose first segment is "resource"; `false` is returned otherwise.
`boolean`	`isPrefix()` Returns `true` if this is a hierarchical URI that ends in a slash; that is, it has a trailing path separator or is the root absolute path, and has no query and no fragment; `false` is returned otherwise.
`boolean`	`isRelative()` Returns `true` if this is a relative URI, or `false` if it is an absolute URI.
`java.lang.String`	`lastSegment()` Returns the last segment in the segment array, or `null`.
`java.lang.String`	`opaquePart()` If this is a non-hierarchical URI, returns the opaque part component; `null` otherwise.
`java.lang.String`	`path()` If this is a hierarchical URI with a path, returns a string representation of the path; `null` otherwise.
`java.lang.String`	`port()` If this is a hierarchical URI with an authority component that has a port portion, returns it; `null` otherwise.
`java.lang.String`	`query()` If this is a hierarchical URI with a query component, returns it; `null` otherwise.
`URI`	`replacePrefix(URI oldPrefix, URI newPrefix)` If this is a hierarchical URI reference and `oldPrefix` is a prefix of it, this returns the URI formed by replacing it by `newPrefix`; `null` otherwise.
`URI`	`resolve(URI base)` Resolves this URI reference against a `base` absolute hierarchical URI, returning the resulting absolute URI.
`URI`	`resolve(URI base, boolean preserveRootParents)` Resolves this URI reference against a `base` absolute hierarchical URI, returning the resulting absolute URI.
`java.lang.String`	`scheme()` If this is an absolute URI, returns the scheme component; `null` otherwise.
`java.lang.String`	`segment(int i)` Provides fast, indexed access to individual segments in the path segment array.
`int`	`segmentCount()` Returns the number of elements in the segment array that would be returned by `segments`.
`java.lang.String[]`	`segments()` If this is a hierarchical URI with a path, returns an array containing the segments of the path; an empty array otherwise.
`java.util.List<java.lang.String>`	`segmentsList()` Returns an unmodifiable list containing the same segments as the array returned by `segments`.
`java.lang.String`	`toFileString()` If this URI may refer directly to a locally accessible file, as determined by `isFile`, `decodes` and formats the URI as a pathname to that file; returns null otherwise.
`java.lang.String`	`toPlatformString(boolean decode)` If this is a platform URI, as determined by `isPlatform()`, returns the workspace-relative or plug-in-based path to the resource, optionally `decoding` the segments in the process.
`java.lang.String`	`toString()` Returns the string representation of this URI.
`URI`	`trimFileExtension()` If this URI has a non-null `fileExtension`, returns the URI formed by removing it; this URI unchanged, otherwise.
`URI`	`trimFragment()` If this URI has a non-null `fragment`, returns the URI formed by removing it; this URI unchanged, otherwise.
`URI`	`trimQuery()` If this URI has a non-null `query`, returns the URI formed by removing it; this URI unchanged, otherwise.
`URI`	`trimSegments(int i)` Returns the URI formed by trimming the specified number of segments (including empty segments, such as one representing a trailing separator) from the end of the path of this URI, if hierarchical; otherwise, this URI is returned unchanged.
`java.lang.String`	`userInfo()` If this is a hierarchical URI with an authority component that has a user info portion, returns it; `null` otherwise.
`static boolean`	`validArchiveAuthority(java.lang.String value)` Returns `true` if the specified `value` would be valid as the authority component of an archive URI; `false` otherwise.
`static boolean`	`validAuthority(java.lang.String value)` Returns `true` if the specified `value` would be valid as the authority component of a URI; `false` otherwise.
`static boolean`	`validDevice(java.lang.String value)` Returns `true` if the specified `value` would be valid as the device component of a URI; `false` otherwise.
`static boolean`	`validFragment(java.lang.String value)` Returns `true` if the specified `value` would be valid as the fragment component of a URI; `false` otherwise.
`static boolean`	`validJarAuthority(java.lang.String value)` Deprecated. As of EMF 2.0, replaced by `validArchiveAuthority`.
`static boolean`	`validOpaquePart(java.lang.String value)` Returns `true` if the specified `value` would be valid as the opaque part component of a URI; `false` otherwise.
`static boolean`	`validQuery(java.lang.String value)` Returns `true` if the specified `value` would be valid as the query component of a URI; `false` otherwise.
`static boolean`	`validScheme(java.lang.String value)` Returns `true` if the specified `value` would be valid as the scheme component of a URI; `false` otherwise.
`static boolean`	`validSegment(java.lang.String value)` Returns `true` if the specified `value` would be a valid path segment of a URI; `false` otherwise.
`static boolean`	`validSegments(java.lang.String[] value)` Returns `true` if the specified `value` would be a valid path segment array of a URI; `false` otherwise.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

FRAGMENT_NONE

public static final int FRAGMENT_NONE

When specified as the last argument to createURI, indicates that there is no fragment, so any # characters should be encoded.

See Also:: createURI(String, boolean, int), Constant Field Values

FRAGMENT_FIRST_SEPARATOR

public static final int FRAGMENT_FIRST_SEPARATOR

When specified as the last argument to createURI, indicates that the first # character should be taken as the fragment separator, and any others should be encoded.

See Also:: createURI(String, boolean, int), Constant Field Values

FRAGMENT_LAST_SEPARATOR

public static final int FRAGMENT_LAST_SEPARATOR

When specified as the last argument to createURI, indicates that the last # character should be taken as the fragment separator, and any others should be encoded.

See Also:: createURI(String, boolean, int), Constant Field Values

Method Detail

createGenericURI

public static URI createGenericURI(java.lang.String scheme,
                                   java.lang.String opaquePart,
                                   java.lang.String fragment)

Static factory method for a generic, non-hierarchical URI. There is no concept of a relative non-hierarchical URI; such an object cannot be created.

Throws:: java.lang.IllegalArgumentException - if scheme is null, if scheme is an archive URI scheme, or if scheme, opaquePart, or fragment is not valid according to validScheme, validOpaquePart, or validFragment, respectively.

createHierarchicalURI

public static URI createHierarchicalURI(java.lang.String scheme,
                                        java.lang.String authority,
                                        java.lang.String device,
                                        java.lang.String query,
                                        java.lang.String fragment)

Static factory method for a hierarchical URI with no path. The URI will be relative if scheme is non-null, and absolute otherwise. An absolute URI with no path requires a non-null authority and/or device.

Throws:: java.lang.IllegalArgumentException - if scheme is non-null while authority and device are null, if scheme is an archive URI scheme, or if scheme, authority, device, query, or fragment is not valid according to validSheme, validAuthority, validDevice, validQuery, or validFragment, respectively.

createHierarchicalURI

public static URI createHierarchicalURI(java.lang.String scheme,
                                        java.lang.String authority,
                                        java.lang.String device,
                                        java.lang.String[] segments,
                                        java.lang.String query,
                                        java.lang.String fragment)

Static factory method for a hierarchical URI with absolute path. The URI will be relative if scheme is non-null, and absolute otherwise.

Parameters:: segments - an array of non-null strings, each representing one segment of the path. As an absolute path, it is automatically preceded by a / separator. If desired, a trailing separator should be represented by an empty-string segment as the last element of the array.
Throws:: java.lang.IllegalArgumentException - if scheme is an archive URI scheme and device is non-null, or if scheme, authority, device, segments, query, or fragment is not valid according to validScheme, validAuthority or validArchiveAuthority, validDevice, validSegments, validQuery, or validFragment, as appropriate.

createHierarchicalURI

public static URI createHierarchicalURI(java.lang.String[] segments,
                                        java.lang.String query,
                                        java.lang.String fragment)

Static factory method for a relative hierarchical URI with relative path.

Parameters:: segments - an array of non-null strings, each representing one segment of the path. A trailing separator is represented by an empty-string segment at the end of the array.
Throws:: java.lang.IllegalArgumentException - if segments, query, or fragment is not valid according to validSegments, validQuery, or validFragment, respectively.

createURI

public static URI createURI(java.lang.String uri)

Static factory method based on parsing a URI string, with explicit device support and handling for archive URIs enabled. The specified string is parsed as described in RFC 2396, and an appropriate URI is created and returned. Note that validity testing is not as strict as in the RFC; essentially, only separator characters are considered. So, for example, non-Latin alphabet characters appearing in the scheme would not be considered an error.

Throws:: java.lang.IllegalArgumentException - if any component parsed from uri is not valid according to validScheme, validOpaquePart, validAuthority, validArchiveAuthority, validDevice, validSegments, validQuery, or validFragment, as appropriate.

createURI

public static URI createURI(java.lang.String uri,
                            boolean ignoreEscaped)

Static factory method that encodes and parses the given URI string. Appropriate encoding is performed for each component of the URI. If more than one # is in the string, the last one is assumed to be the fragment's separator, and any others are encoded.

Parameters:: ignoreEscaped - true to leave % characters unescaped if they already begin a valid three-character escape sequence; false to encode all % characters. Note that if a % is not followed by 2 hex digits, it will always be escaped.
Throws:: java.lang.IllegalArgumentException - if any component parsed from uri is not valid according to validScheme, validOpaquePart, validAuthority, validArchiveAuthority, validDevice, validSegments, validQuery, or validFragment, as appropriate.

createURI

public static URI createURI(java.lang.String uri,
                            boolean ignoreEscaped,
                            int fragmentLocationStyle)

Static factory method that encodes and parses the given URI string. Appropriate encoding is performed for each component of the URI. Control is provided over which, if any, # should be taken as the fragment separator and which should be encoded.

Parameters:: ignoreEscaped - true to leave % characters unescaped if they already begin a valid three-character escape sequence; false to encode all % characters. Note that if a % is not followed by 2 hex digits, it will always be escaped.; fragmentLocationStyle - one of FRAGMENT_NONE, FRAGMENT_FIRST_SEPARATOR, or FRAGMENT_LAST_SEPARATOR, indicating which, if any, of the # characters should be considered the fragment separator. Any others will be encoded.
Throws:: java.lang.IllegalArgumentException - if any component parsed from uri is not valid according to validScheme, validOpaquePart, validAuthority, validArchiveAuthority, validDevice, validSegments, validQuery, or validFragment, as appropriate.

createDeviceURI

@Deprecated
public static URI createDeviceURI(java.lang.String uri)

Deprecated. Use createURI, which now has explicit device support enabled. The two methods now operate identically.

Static factory method based on parsing a URI string, with explicit device support enabled. Note that validity testing is not a strict as in the RFC; essentially, only separator characters are considered. So, for example, non-Latin alphabet characters appearing in the scheme would not be considered an error.

Throws:: java.lang.IllegalArgumentException - if any component parsed from uri is not valid according to validScheme, validOpaquePart, validAuthority, validArchiveAuthority, validDevice, validSegments, validQuery, or validFragment, as appropriate.

createURIWithCache

@Deprecated
public static URI createURIWithCache(java.lang.String uri)

Deprecated. Please use createURI instead.

This method was included in the public API by mistake.

createFileURI

public static URI createFileURI(java.lang.String pathName)

Static factory method based on parsing a File path string. The pathName is converted into an appropriate form, as follows: platform specific path separators are converted to

/; the path is encoded; and a "file" scheme and, if missing,
 a leading /, are added to an absolute path.  The result
 is then parsed using createURI.

 The encoding step escapes all spaces, # characters, and
 other characters disallowed in URIs, as well as ?, which
 would delimit a path from a query.  Decoding is automatically performed
 by toFileString, and can be applied to the values
 returned by other accessors by via the static decode method.

 
A relative path with a specified device (something like
 C:myfile.txt) cannot be expressed as a valid URI.

Throws:: java.lang.IllegalArgumentException - if pathName specifies a device and a relative path, or if any component of the path is not valid according to validAuthority, validDevice, or validSegments, validQuery, or validFragment.





createPlatformResourceURI
@Deprecated
public static URI createPlatformResourceURI(java.lang.String pathName)

Deprecated. org.eclipse.emf.common 2.3 Use createPlatformResourceURI(String, boolean) instead.

Static factory method based on parsing a workspace-relative path string.

 The pathName must be of the form:
 
   /project-name/path

 Platform-specific path separators will be converted to slashes.
 If not included, the leading path separator will be added.  The
 result will be of this form, which is parsed using createURI:
 
   platform:/resource/project-name/path

 This scheme supports relocatable projects in Eclipse and in
 stand-alone EMF.

 
Path encoding is performed only if the
 org.eclipse.emf.common.util.URI.encodePlatformResourceURIs 
 system property is set to "true". Decoding can be performed with the
 static decode method.



Throws:
java.lang.IllegalArgumentException - if any component parsed
 from the path is not valid according to validDevice,
 validSegments, validQuery, or
 validFragment.
See Also:
Platform.resolve(java.net.URL), 
createPlatformResourceURI(String, boolean)





createPlatformResourceURI
public static URI createPlatformResourceURI(java.lang.String pathName,
                                            boolean encode)

Static factory method based on parsing a workspace-relative path string,
 with an option to encode the created URI.

 The pathName must be of the form:
 
   /project-name/path

 Platform-specific path separators will be converted to slashes.
 If not included, the leading path separator will be added.  The
 result will be of this form, which is parsed using createURI:
 
   platform:/resource/project-name/path

 This scheme supports relocatable projects in Eclipse and in
 stand-alone EMF.

 
Depending on the encode argument, the path may be
 automatically encoded to escape all spaces, # characters,
 and other characters disallowed in URIs, as well as ?,
 which would delimit a path from a query.  Decoding can be performed with
 the static decode method.



Throws:
java.lang.IllegalArgumentException - if any component parsed
 from the path is not valid according to validDevice,
 validSegments, validQuery, or
 validFragment.
See Also:
Platform.resolve(java.net.URL)





createPlatformPluginURI
public static URI createPlatformPluginURI(java.lang.String pathName,
                                          boolean encode)

Static factory method based on parsing a plug-in-based path string,
 with an option to encode the created URI.

 The pathName must be of the form:
 
   /plugin-id/path

 Platform-specific path separators will be converted to slashes.
 If not included, the leading path separator will be added.  The
 result will be of this form, which is parsed using createURI:
 
   platform:/plugin/plugin-id/path

 This scheme supports relocatable plug-in content in Eclipse.

 
Depending on the encode argument, the path may be
 automatically encoded to escape all spaces, # characters,
 and other characters disallowed in URIs, as well as ?,
 which would delimit a path from a query.  Decoding can be performed with
 the static decode method.



Throws:
java.lang.IllegalArgumentException - if any component parsed
 from the path is not valid according to validDevice,
 validSegments, validQuery, or
 validFragment.
Since:
  org.eclipse.emf.common 2.3
See Also:
Platform.resolve(java.net.URL)





validScheme
public static boolean validScheme(java.lang.String value)

Returns true if the specified value would be
 valid as the scheme component of a URI; false otherwise.

 A valid scheme may be null or contain any characters except for the
 following: : / ? #








validOpaquePart
public static boolean validOpaquePart(java.lang.String value)

Returns true if the specified value would be
 valid as the opaque part component of a URI; false
 otherwise.

 A valid opaque part must be non-null, non-empty, and not contain the
 # character.  In addition, its first character must not be
 /








validAuthority
public static boolean validAuthority(java.lang.String value)

Returns true if the specified value would be
 valid as the authority component of a URI; false otherwise.

 A valid authority may be null or contain any characters except for
 the following: / ? #








validArchiveAuthority
public static boolean validArchiveAuthority(java.lang.String value)

Returns true if the specified value would be
 valid as the authority component of an archive URI; false
 otherwise.

 To be valid, the authority, itself, must be a URI with no fragment,
 followed by the character !.








validJarAuthority
@Deprecated
public static boolean validJarAuthority(java.lang.String value)

Deprecated. As of EMF 2.0, replaced by validArchiveAuthority.

Tests whether the specified value would be valid as the
 authority component of an archive
 URI. This method has been replaced by validArchiveAuthority since the same form of URI is now supported
 for schemes other than "jar". This now simply calls that method.








validDevice
public static boolean validDevice(java.lang.String value)

Returns true if the specified value would be
 valid as the device component of a URI; false otherwise.

 A valid device may be null or non-empty, containing any characters
 except for the following: / ? #  In addition, its last
 character must be :








validSegment
public static boolean validSegment(java.lang.String value)

Returns true if the specified value would be
 a valid path segment of a URI; false otherwise.

 A valid path segment must be non-null and not contain any of the
 following characters: / ? #








validSegments
public static boolean validSegments(java.lang.String[] value)

Returns true if the specified value would be
 a valid path segment array of a URI; false otherwise.

 A valid path segment array must be non-null and contain only path
 segments that are valid according to validSegment.








validQuery
public static boolean validQuery(java.lang.String value)

Returns true if the specified value would be
 valid as the query component of a URI; false otherwise.

 A valid query may be null or contain any characters except for
 #








validFragment
public static boolean validFragment(java.lang.String value)

Returns true if the specified value would be
 valid as the fragment component of a URI; false otherwise.

 A fragment is taken to be unconditionally valid.








isRelative
public boolean isRelative()

Returns true if this is a relative URI, or
 false if it is an absolute URI.








isHierarchical
public boolean isHierarchical()

Returns true if this a a hierarchical URI, or
 false if it is of the generic form.








hasAuthority
public boolean hasAuthority()

Returns true if this is a hierarchical URI with an authority
 component; false otherwise.








hasOpaquePart
public boolean hasOpaquePart()

Returns true if this is a non-hierarchical URI with an
 opaque part component; false otherwise.








hasDevice
public boolean hasDevice()

Returns true if this is a hierarchical URI with a device
 component; false otherwise.








hasPath
public boolean hasPath()

Returns true if this is a hierarchical URI with an
 absolute or relative path; false otherwise.








hasAbsolutePath
public boolean hasAbsolutePath()

Returns true if this is a hierarchical URI with an
 absolute path, or false if it is non-hierarchical, has no
 path, or has a relative path.








hasRelativePath
public boolean hasRelativePath()

Returns true if this is a hierarchical URI with a relative
 path, or false if it is non-hierarchical, has no path, or
 has an absolute path.








hasEmptyPath
public boolean hasEmptyPath()

Returns true if this is a hierarchical URI with an empty
 relative path; false otherwise.  

 Note that !hasEmpty() does not imply that this
 URI has any path segments; however, hasRelativePath &&
 !hasEmptyPath() does.








hasQuery
public boolean hasQuery()

Returns true if this is a hierarchical URI with a query
 component; false otherwise.








hasFragment
public boolean hasFragment()

Returns true if this URI has a fragment component;
 false otherwise.








isCurrentDocumentReference
public boolean isCurrentDocumentReference()

Returns true if this is a current document reference; that
 is, if it is a relative hierarchical URI with no authority, device or
 query components, and no path segments; false is returned
 otherwise.








isEmpty
public boolean isEmpty()

Returns true if this is a current document reference with no
 fragment component; false otherwise.


See Also:
isCurrentDocumentReference()





isFile
public boolean isFile()

Returns true if this is a hierarchical URI that may refer
 directly to a locally accessible file.  This is considered to be the
 case for a file-scheme absolute URI, or for a relative URI with no query;
 false is returned otherwise.








isPlatform
public boolean isPlatform()

Returns true if this is a platform URI, that is, an absolute,
 hierarchical URI, with "platform" scheme, no authority, and at least two
 segments; false is returned otherwise.


Since:
  org.eclipse.emf.common 2.3






isPlatformResource
public boolean isPlatformResource()

Returns true if this is a platform resource URI, that is,
 a platform URI whose first segment is "resource";
 false is returned otherwise.


Since:
  org.eclipse.emf.common 2.3
See Also:
isPlatform()





isPlatformPlugin
public boolean isPlatformPlugin()

Returns true if this is a platform plug-in URI, that is,
 a platform URI whose first segment is "plugin";
 false is returned otherwise.


Since:
  org.eclipse.emf.common 2.3
See Also:
isPlatform()





isArchive
public boolean isArchive()

Returns true if this is an archive URI.  If so, it is also
 hierarchical, with an authority (consisting of an absolute URI followed
 by "!"), no device, and an absolute path.








isArchiveScheme
public static boolean isArchiveScheme(java.lang.String value)

Returns true if the specified value would be
 valid as the scheme of an archive URI; false
 otherwise.








hashCode
public int hashCode()

Returns the hash code.


Overrides:
hashCode in class java.lang.Object








equals
public boolean equals(java.lang.Object object)

Returns true if object is an instance of
 URI equal to this one; false otherwise.

 Equality is determined strictly by comparing components, not by
 attempting to interpret what resource is being identified.  The
 comparison of schemes is case-insensitive.


Overrides:
equals in class java.lang.Object








scheme
public java.lang.String scheme()

If this is an absolute URI, returns the scheme component;
 null otherwise.








opaquePart
public java.lang.String opaquePart()

If this is a non-hierarchical URI, returns the opaque part component;
 null otherwise.








authority
public java.lang.String authority()

If this is a hierarchical URI with an authority component, returns it;
 null otherwise.








userInfo
public java.lang.String userInfo()

If this is a hierarchical URI with an authority component that has a
 user info portion, returns it; null otherwise.








host
public java.lang.String host()

If this is a hierarchical URI with an authority component that has a
 host portion, returns it; null otherwise.








port
public java.lang.String port()

If this is a hierarchical URI with an authority component that has a
 port portion, returns it; null otherwise.








device
public java.lang.String device()

If this is a hierarchical URI with a device component, returns it;
 null otherwise.








segments
public java.lang.String[] segments()

If this is a hierarchical URI with a path, returns an array containing
 the segments of the path; an empty array otherwise.  The leading
 separator in an absolute path is not represented in this array, but a
 trailing separator is represented by an empty-string segment as the
 final element.








segmentsList
public java.util.List<java.lang.String> segmentsList()

Returns an unmodifiable list containing the same segments as the array
 returned by segments.








segmentCount
public int segmentCount()

Returns the number of elements in the segment array that would be
 returned by segments.








segment
public java.lang.String segment(int i)

Provides fast, indexed access to individual segments in the path
 segment array.



Throws:
java.lang.IndexOutOfBoundsException - if i < 0 or
 i >= segmentCount().





lastSegment
public java.lang.String lastSegment()

Returns the last segment in the segment array, or null.








path
public java.lang.String path()

If this is a hierarchical URI with a path, returns a string
 representation of the path; null otherwise.  The path
 consists of a leading segment separator character (a slash), if the
 path is absolute, followed by the slash-separated path segments.  If
 this URI has a separate device
 component, it is not included in the path.








devicePath
public java.lang.String devicePath()

If this is a hierarchical URI with a path, returns a string
 representation of the path, including the authority and the 
 device component; 
 null otherwise.  

 If there is no authority, the format of this string is:
 
   device/pathSegment1/pathSegment2...

 If there is an authority, it is:
 
   //authority/device/pathSegment1/pathSegment2...

 For an archive URI, it's just:
 
   authority/pathSegment1/pathSegment2...








query
public java.lang.String query()

If this is a hierarchical URI with a query component, returns it;
 null otherwise.








appendQuery
public URI appendQuery(java.lang.String query)

Returns the URI formed from this URI and the given query.



Throws:
java.lang.IllegalArgumentException - if
 query is not a valid query (portion) according
 to validQuery.





trimQuery
public URI trimQuery()

If this URI has a non-null query, returns the URI
 formed by removing it; this URI unchanged, otherwise.








fragment
public java.lang.String fragment()

If this URI has a fragment component, returns it; null
 otherwise.








appendFragment
public URI appendFragment(java.lang.String fragment)

Returns the URI formed from this URI and the given fragment.



Throws:
java.lang.IllegalArgumentException - if
 fragment is not a valid fragment (portion) according
 to validFragment.





trimFragment
public URI trimFragment()

If this URI has a non-null fragment, returns the URI
 formed by removing it; this URI unchanged, otherwise.








resolve
public URI resolve(URI base)

Resolves this URI reference against a base absolute
 hierarchical URI, returning the resulting absolute URI.  If already
 absolute, the URI itself is returned.  URI resolution is described in
 detail in section 5.2 of RFC
 2396, "Resolving Relative References to Absolute Form."

 During resolution, empty segments, self references ("."), and parent
 references ("..") are interpreted, so that they can be removed from the
 path.  Step 6(g) gives a choice of how to handle the case where parent
 references point to a path above the root: the offending segments can
 be preserved or discarded.  This method preserves them.  To have them
 discarded, please use the two-parameter form of resolve.



Throws:
java.lang.IllegalArgumentException - if base is
 non-hierarchical or is relative.





resolve
public URI resolve(URI base,
                   boolean preserveRootParents)

Resolves this URI reference against a base absolute
 hierarchical URI, returning the resulting absolute URI.  If already
 absolute, the URI itself is returned.  URI resolution is described in
 detail in section 5.2 of RFC
 2396, "Resolving Relative References to Absolute Form."

 During resolution, empty segments, self references ("."), and parent
 references ("..") are interpreted, so that they can be removed from the
 path.  Step 6(g) gives a choice of how to handle the case where parent
 references point to a path above the root: the offending segments can
 be preserved or discarded.  This method can do either.


Parameters:
preserveRootParents - true if segments referring to the
 parent of the root path are to be preserved; false if they
 are to be discarded.
Throws:
java.lang.IllegalArgumentException - if base is
 non-hierarchical or is relative.





deresolve
public URI deresolve(URI base)

Finds the shortest relative or, if necessary, the absolute URI that,
 when resolved against the given base absolute hierarchical
 URI using resolve, will yield this absolute URI.



Throws:
java.lang.IllegalArgumentException - if base is
 non-hierarchical or is relative.
java.lang.IllegalStateException - if this is
 relative.





deresolve
public URI deresolve(URI base,
                     boolean preserveRootParents,
                     boolean anyRelPath,
                     boolean shorterRelPath)

Finds an absolute URI that, when resolved against the given
 base absolute hierarchical URI using resolve, will yield this absolute URI.


Parameters:
preserveRootParents - the boolean argument to resolve(URI,
 boolean) for which the returned URI should resolve to this URI.
anyRelPath - if true, the returned URI's path (if
 any) will be relative, if possible.  If false, the form of
 the result's path will depend upon the next parameter.
shorterRelPath - if anyRelPath is false
 and this parameter is true, the returned URI's path (if
 any) will be relative, if one can be found that is no longer (by number
 of segments) than the absolute path.  If both anyRelPath
 and this parameter are false, it will be absolute.
Throws:
java.lang.IllegalArgumentException - if base is
 non-hierarchical or is relative.
java.lang.IllegalStateException - if this is
 relative.





toString
public java.lang.String toString()

Returns the string representation of this URI.  For a generic,
 non-hierarchical URI, this looks like:
    scheme:opaquePart#fragment
 
 For a hierarchical URI, it looks like:
 
   scheme://authority/device/pathSegment1/pathSegment2...?query#fragment

 For an archive URI, it's just:
 
   scheme:authority/pathSegment1/pathSegment2...?query#fragment
 Of course, absent components and their separators will be omitted.


Overrides:
toString in class java.lang.Object








toFileString
public java.lang.String toFileString()

If this URI may refer directly to a locally accessible file, as
 determined by isFile, decodes and formats  
 the URI as a pathname to that file; returns null otherwise.

 If there is no authority, the format of this string is:
 
   device/pathSegment1/pathSegment2...

 If there is an authority, it is:
 
   //authority/device/pathSegment1/pathSegment2...
 
 However, the character used as a separator is system-dependent and
 obtained from File.separatorChar.








toPlatformString
public java.lang.String toPlatformString(boolean decode)

If this is a platform URI, as determined by isPlatform(), returns
 the workspace-relative or plug-in-based path to the resource, optionally
 decoding the segments in the process.


Since:
  org.eclipse.emf.common 2.3
See Also:
createPlatformResourceURI(String, boolean), 
createPlatformPluginURI(java.lang.String, boolean)





appendSegment
public URI appendSegment(java.lang.String segment)

Returns the URI formed by appending the specified segment on to the end
 of the path of this URI, if hierarchical; this URI unchanged,
 otherwise.  If this URI has an authority and/or device, but no path,
 the segment becomes the first under the root in an absolute path.



Throws:
java.lang.IllegalArgumentException - if segment
 is not a valid segment according to validSegment(java.lang.String).





appendSegments
public URI appendSegments(java.lang.String[] segments)

Returns the URI formed by appending the specified segments on to the
 end of the path of this URI, if hierarchical; this URI unchanged,
 otherwise.  If this URI has an authority and/or device, but no path,
 the segments are made to form an absolute path.


Parameters:
segments - an array of non-null strings, each representing one
 segment of the path.  If desired, a trailing separator should be
 represented by an empty-string segment as the last element of the
 array.
Throws:
java.lang.IllegalArgumentException - if segments
 is not a valid segment array according to validSegments(java.lang.String[]).





trimSegments
public URI trimSegments(int i)

Returns the URI formed by trimming the specified number of segments
 (including empty segments, such as one representing a trailing
 separator) from the end of the path of this URI, if hierarchical;
 otherwise, this URI is returned unchanged.

 Note that if all segments are trimmed from an absolute path, the
 root absolute path remains.


Parameters:
i - the number of segments to be trimmed in the returned URI.  If
 less than 1, this URI is returned unchanged; if equal to or greater
 than the number of segments in this URI's path, all segments are
 trimmed.





hasTrailingPathSeparator
public boolean hasTrailingPathSeparator()

Returns true if this is a hierarchical URI that has a path
 that ends with a trailing separator; false otherwise.

 A trailing separator is represented as an empty segment as the
 last segment in the path; note that this definition does not
 include the lone separator in the root absolute path.








fileExtension
public java.lang.String fileExtension()

If this is a hierarchical URI whose path includes a file extension,
 that file extension is returned; null otherwise.  We define a file
 extension as any string following the last period (".") in the final
 path segment.  If there is no path, the path ends in a trailing
 separator, or the final segment contains no period, then we consider
 there to be no file extension.  If the final segment ends in a period,
 then the file extension is an empty string.








appendFileExtension
public URI appendFileExtension(java.lang.String fileExtension)

Returns the URI formed by appending a period (".") followed by the
 specified file extension to the last path segment of this URI, if it is
 hierarchical with a non-empty path ending in a non-empty segment;
 otherwise, this URI is returned unchanged.

 The extension is appended regardless of whether the segment already
 contains an extension.



Throws:
java.lang.IllegalArgumentException - if
 fileExtension is not a valid segment (portion) according
 to validSegment(java.lang.String).





trimFileExtension
public URI trimFileExtension()

If this URI has a non-null fileExtension,
 returns the URI formed by removing it; this URI unchanged, otherwise.








isPrefix
public boolean isPrefix()

Returns true if this is a hierarchical URI that ends in a
 slash; that is, it has a trailing path separator or is the root
 absolute path, and has no query and no fragment; false
 is returned otherwise.








replacePrefix
public URI replacePrefix(URI oldPrefix,
                         URI newPrefix)

If this is a hierarchical URI reference and oldPrefix is a
 prefix of it, this returns the URI formed by replacing it by
 newPrefix; null otherwise.

 In order to be a prefix, the oldPrefix's
 isPrefix must return true, and it must
 match this URI's scheme, authority, and device.  Also, the paths must
 match, up to prefix's end.



Throws:
java.lang.IllegalArgumentException - if either
 oldPrefix or newPrefix is not a prefix URI
 according to isPrefix().





encodeOpaquePart
public static java.lang.String encodeOpaquePart(java.lang.String value,
                                                boolean ignoreEscaped)

Encodes a string so as to produce a valid opaque part value, as defined
 by the RFC.  All excluded characters, such as space and #,
 are escaped, as is / if it is the first character.


Parameters:
ignoreEscaped - true to leave % characters
 unescaped if they already begin a valid three-character escape sequence;
 false to encode all % characters.  Note that
 if a % is not followed by 2 hex digits, it will always be
 escaped.





encodeAuthority
public static java.lang.String encodeAuthority(java.lang.String value,
                                               boolean ignoreEscaped)

Encodes a string so as to produce a valid authority, as defined by the
 RFC.  All excluded characters, such as space and #,
 are escaped, as are / and ?


Parameters:
ignoreEscaped - true to leave % characters
 unescaped if they already begin a valid three-character escape sequence;
 false to encode all % characters.  Note that
 if a % is not followed by 2 hex digits, it will always be
 escaped.





encodeSegment
public static java.lang.String encodeSegment(java.lang.String value,
                                             boolean ignoreEscaped)

Encodes a string so as to produce a valid segment, as defined by the
 RFC.  All excluded characters, such as space and #,
 are escaped, as are / and ?


Parameters:
ignoreEscaped - true to leave % characters
 unescaped if they already begin a valid three-character escape sequence;
 false to encode all % characters.  Note that
 if a % is not followed by 2 hex digits, it will always be
 escaped.





encodeQuery
public static java.lang.String encodeQuery(java.lang.String value,
                                           boolean ignoreEscaped)

Encodes a string so as to produce a valid query, as defined by the RFC.
 Only excluded characters, such as space and #, are escaped.


Parameters:
ignoreEscaped - true to leave % characters
 unescaped if they already begin a valid three-character escape sequence;
 false to encode all % characters.  Note that
 if a % is not followed by 2 hex digits, it will always be
 escaped.





encodeFragment
public static java.lang.String encodeFragment(java.lang.String value,
                                              boolean ignoreEscaped)

Encodes a string so as to produce a valid fragment, as defined by the
 RFC.  Only excluded characters, such as space and #, are
 escaped.


Parameters:
ignoreEscaped - true to leave % characters
 unescaped if they already begin a valid three-character escape sequence;
 false to encode all % characters.  Note that
 if a % is not followed by 2 hex digits, it will always be
 escaped.





decode
public static java.lang.String decode(java.lang.String value)

Decodes the given string by interpreting three-digit escape sequences as the bytes of a UTF-8 encoded character
 and replacing them with the characters they represent.
 Incomplete escape sequences are ignored and invalid UTF-8 encoded bytes are treated as extended ASCII characters.

















  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  



Copyright 2001-2006 IBM Corporation and others.
 All Rights Reserved.





 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.emf.common.util Class URI

FRAGMENT_NONE

FRAGMENT_FIRST_SEPARATOR

FRAGMENT_LAST_SEPARATOR

createGenericURI

createHierarchicalURI

createHierarchicalURI

createHierarchicalURI

createURI

createURI

createURI

createDeviceURI

createURIWithCache

createFileURI

createPlatformResourceURI

createPlatformResourceURI

createPlatformPluginURI

validScheme

validOpaquePart

validAuthority

validArchiveAuthority

validJarAuthority

validDevice

validSegment

validSegments

validQuery

validFragment

isRelative

isHierarchical

hasAuthority

hasOpaquePart

hasDevice

hasPath

hasAbsolutePath

hasRelativePath

hasEmptyPath

hasQuery

hasFragment

isCurrentDocumentReference

isEmpty

isFile

isPlatform

isPlatformResource

isPlatformPlugin

isArchive

isArchiveScheme

hashCode

equals

scheme

opaquePart

authority

userInfo

host

port

device

segments

segmentsList

segmentCount

segment

lastSegment

path

devicePath

query

appendQuery

trimQuery

fragment

appendFragment

trimFragment

resolve

resolve

deresolve

deresolve

toString

toFileString

toPlatformString

appendSegment

appendSegments

trimSegments

hasTrailingPathSeparator

fileExtension

org.eclipse.emf.common.util
Class URI