org.eclipse.emf.common.util
Class URI

java.lang.Object
  |
  +--org.eclipse.emf.common.util.URI

public final class URI
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. Acordingly, 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 can be created by parsing a string with createURI(java.lang.String) or by specifying a non-null device paramter for either the no-path or the absolute-path form of createHierarchicalURI().

Compared to the RFC description, this implementation is quite relaxed about validity. Static methods whose names begin with "valid" test whether a given string is a valid value for the various URI components. Presently, these tests place no restrictions beyond what would have been required in order for createURI(java.lang.String) to have parsed them correctly from a single URI string. Note that all of the static factory methods invoke the appropriate validation methods and throw exceptions in response to a negative result, ensuring that invalid URIs are never created.

Finally, note the difference between a null parameter to the static factory methods and an empty string. The former signifies the absense 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!


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.  
static URI createFileURI(java.lang.String pathName)
          Static factory method based on parsing File path string, with explicit device support enabled.
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 createPlatformResourceURI(java.lang.String pathName)
          Static factory method based on parsing a platform-relative path string.
static URI createURI(java.lang.String uri)
          Static factory method based on parsing a URI string, with explicit device support enabled.
 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(URI), 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(URI, boolean), 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.
 boolean equals(java.lang.Object obj)
          Returns true if obj 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 hierarcical 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 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 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 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(), returns the URI formatted as a pathname to that file; null otherwise.
 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 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 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
 

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, or if scheme, opaquePart, or fragment is not valid according to validScheme(java.lang.String), validOpaquePart(java.lang.String), or validFragment(java.lang.String), 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, or if scheme, authority, device, query, or fragment is not valid according to validScheme(java.lang.String), validAuthority(java.lang.String), validDevice(java.lang.String), validQuery(java.lang.String), or validFragment(java.lang.String), 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 preceeded 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, authority, device, segments, query, or fragment is not valid according to validScheme(java.lang.String), validAuthority(java.lang.String), validDevice(java.lang.String), validSegments(java.lang.String[]), validQuery(java.lang.String), or validFragment(java.lang.String), respectively.

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(java.lang.String[]), validQuery(java.lang.String), or validFragment(java.lang.String), respectively.

createURI

public static URI createURI(java.lang.String uri)
Static factory method based on parsing a URI string, with explicit device support 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(java.lang.String), validOpaquePart(java.lang.String), validAuthority(java.lang.String), validDevice(java.lang.String), validSegments(java.lang.String[]), validQuery(java.lang.String), or validFragment(java.lang.String), as appropriate.

createDeviceURI

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

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(java.lang.String), validOpaquePart(java.lang.String), validAuthority(java.lang.String), validDevice(java.lang.String), validSegments(java.lang.String[]), validQuery(java.lang.String), or validFragment(java.lang.String), as appropriate.

createFileURI

public static URI createFileURI(java.lang.String pathName)
Static factory method based on parsing File path 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 a path segment would not be considered an error.
Throws:
java.lang.IllegalArgumentException - if any component parsed from uri is not valid according to validScheme(java.lang.String), validOpaquePart(java.lang.String), validAuthority(java.lang.String), validDevice(java.lang.String), validSegments(java.lang.String[]), validQuery(java.lang.String), or validFragment(java.lang.String), as appropriate.

createPlatformResourceURI

public static URI createPlatformResourceURI(java.lang.String pathName)
Static factory method based on parsing a platform-relative path string. The pathName must be of the form
  /project-name/path
and the result will be of the form
  platform:/resource/project-name/path
The leading separator of the path will be provided if not present. This scheme supports relocatable projects in Eclipse and in stand-alone EMF.
Throws:
java.lang.IllegalArgumentException - if any component parsed from uri is not valid according to validScheme(java.lang.String), validOpaquePart(java.lang.String), validAuthority(java.lang.String), validDevice(java.lang.String), validSegments(java.lang.String[]), validQuery(java.lang.String), or validFragment(java.lang.String), as appropriate.
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: / ? #


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 segements that are valid, according to validSegment(java.lang.String).


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

hashCode

public int hashCode()
Returns the hash code.
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Returns true if obj 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.

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 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. If it has a device stored as a path segment, it is included.

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.

The format of this string is

   //authority/device/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(java.lang.String).

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(java.lang.String).

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 resolve(URI, boolean) method.

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 resultion, 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:
preserveRootParent - true if segments refering 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(URI), 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(URI, boolean), 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

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(), returns the URI formatted as a pathname to that file; null otherwise.

The format of this string is

   //authority/device/pathSegment1/pathSegment2...

However, the character used as a separator is system-dependant and obtained from File.separatorChar.


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().

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