org.eclipse.emf.common.util.URI
| |||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
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 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" or "zip" (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 the 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 coform 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 sybol (%), 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 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!
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.
The pathName must be of the form:
If not included, the leading path separator will be added. The
result will be of this form, which is parsed using createURI:
This scheme supports relocatable projects in Eclipse and in
stand-alone EMF.
If the org.eclipse.emf.common.util.URI.encodePlatformResourceURIs
system property is set to "true", the path is 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.
A valid scheme may be null or contain any characters except for the
following: : / ? #
A valid opaque part must be non-null, non-empty, and not contain the
# character. In addition, its first character must not be
/
A valid authority may be null or contain any characters except for
the following: / ? #
To be valid, the authority, itself, must be a URI with no fragment,
followed by the character !.
A valid device may be null or non-empty, containing any characters
except for the following: / ? # In addition, its last
character must be :
A valid path segment must be non-null and not contain any of the
following characters: / ? #
A valid path segment array must be non-null and contain only path
segements that are valid according to validSegment.
A valid query may be null or contain any characters except for
#
A fragment is taken to be unconditionally valid.
Note that !hasEmpty() does not imply that this
URI has any path segments; however, hasRelativePath &&
!hasEmptyPath() does.
Equality is determined strictly by comparing components, not by
attempting to interpret what resource is being identified. The
comparison of schemes is case-insensitive.
If there is no authority, the format of this string is:
If there is an authority, it is:
For an archive URI, it's just:
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.
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.
For a hierarchical URI, it looks like:
For an archive URI, it's just:
Of course, absent components and their separators will be omitted.
If there is no authority, the format of this string is:
If there is an authority, it is:
However, the character used as a separator is system-dependant and
obtained from File.separatorChar.
Note that if all segments are trimmed from an absolute path, the
root absolute path remains.
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.
The extension is appended regardless of whether the segment already
contains an extension.
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.
Method Summary
URI
appendFileExtension(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(String fragment)
Returns the URI formed from this URI and the given fragment.
URI
appendQuery(String query)
Returns the URI formed from this URI and the given query.
URI
appendSegment(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(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.
String
authority()
If this is a hierarchical URI with an authority component, returns it;
null otherwise.
static URI
createDeviceURI(String uri)
Deprecated. Use createURI, which now has explicit
device support enabled. The two methods now operate identically.
static URI
createFileURI(String pathName)
Static factory method based on parsing a File path
string.
static URI
createGenericURI(String scheme,
String opaquePart,
String fragment)
Static factory method for a generic, non-hierarchical URI.
static URI
createHierarchicalURI(String[] segments,
String query,
String fragment)
Static factory method for a relative hierarchical URI with relative
path.
static URI
createHierarchicalURI(String scheme,
String authority,
String device,
String[] segments,
String query,
String fragment)
Static factory method for a hierarchical URI with absolute path.
static URI
createHierarchicalURI(String scheme,
String authority,
String device,
String query,
String fragment)
Static factory method for a hierarchical URI with no path.
static URI
createPlatformResourceURI(String pathName)
Static factory method based on parsing a platform-relative path string.
static URI
createURI(String uri)
Static factory method based on parsing a URI string, with
explicit device support and handling
for archive URIs enabled.
static URI
createURI(String uri,
boolean ignoreEscaped)
Static factory method that encodes and parses the given URI string.
static URI
createURIWithCache(String uri)
Deprecated. Please use createURI instead.
static String
decode(String value)
Decodes the given string, replacing each three-digit escape sequence by
the character that it represents.
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.
String
device()
If this is a hierarchical URI with a device component, returns it;
null otherwise.
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 String
encodeAuthority(String value,
boolean ignoreEscaped)
Encodes a string so as to produce a valid authority, as defined by the
RFC.
static String
encodeFragment(String value,
boolean ignoreEscaped)
Encodes a string so as to produce a valid fragment, as defined by the
RFC.
static String
encodeOpaquePart(String value,
boolean ignoreEscaped)
Encodes a string so as to produce a valid opaque part value, as defined
by the RFC.
static String
encodeQuery(String value,
boolean ignoreEscaped)
Encodes a string so as to produce a valid query, as defined by the RFC.
static String
encodeSegment(String value,
boolean ignoreEscaped)
Encodes a string so as to produce a valid segment, as defined by the
RFC.
boolean
equals(Object obj)
Returns true if obj is an instance of
URI equal to this one; false otherwise.
String
fileExtension()
If this is a hierarchical URI whose path includes a file extension,
that file extension is returned; null otherwise.
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.
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.
String
lastSegment()
Returns the last segment in the segment array, or null.
String
opaquePart()
If this is a non-hierarchical URI, returns the opaque part component;
null otherwise.
String
path()
If this is a hierarchical URI with a path, returns a string
representation of the path; null otherwise.
String
port()
If this is a hierarchical URI with an authority component that has a
port portion, returns it; null otherwise.
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.
String
scheme()
If this is an absolute URI, returns the scheme component;
null otherwise.
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.
String[]
segments()
If this is a hierarchical URI with a path, returns an array containing
the segments of the path; an empty array otherwise.
List
segmentsList()
Returns an unmodifiable list containing the same segments as the array
returned by segments.
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.
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.
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(String value)
Returns true if the specified value would be
valid as the authority component of an archive URI; false
otherwise.
static boolean
validAuthority(String value)
Returns true if the specified value would be
valid as the authority component of a URI; false otherwise.
static boolean
validDevice(String value)
Returns true if the specified value would be
valid as the device component of a URI; false otherwise.
static boolean
validFragment(String value)
Returns true if the specified value would be
valid as the fragment component of a URI; false otherwise.
static boolean
validJarAuthority(String value)
Deprecated. As of EMF 2.0, replaced by validArchiveAuthority.
static boolean
validOpaquePart(String value)
Returns true if the specified value would be
valid as the opaque part component of a URI; false
otherwise.
static boolean
validQuery(String value)
Returns true if the specified value would be
valid as the query component of a URI; false otherwise.
static boolean
validScheme(String value)
Returns true if the specified value would be
valid as the scheme component of a URI; false otherwise.
static boolean
validSegment(String value)
Returns true if the specified value would be
a valid path segment of a URI; false otherwise.
static boolean
validSegments(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(String scheme,
String opaquePart,
String fragment)
createHierarchicalURI
public static URI createHierarchicalURI(String scheme,
String authority,
String device,
String query,
String fragment)
createHierarchicalURI
public static URI createHierarchicalURI(String scheme,
String authority,
String device,
String[] segments,
String query,
String fragment)
createHierarchicalURI
public static URI createHierarchicalURI(String[] segments,
String query,
String fragment)
createURI
public static URI createURI(String uri)
createURI
public static URI createURI(String uri,
boolean ignoreEscaped)
createDeviceURI
public static URI createDeviceURI(String uri)
createURIWithCache
public static URI createURIWithCache(String uri)
createFileURI
public static URI createFileURI(String pathName)
createPlatformResourceURI
public static URI createPlatformResourceURI(String pathName)
/project-name/path
platform:/resource/project-name/path
validScheme
public static boolean validScheme(String value)
validOpaquePart
public static boolean validOpaquePart(String value)
validAuthority
public static boolean validAuthority(String value)
validArchiveAuthority
public static boolean validArchiveAuthority(String value)
validJarAuthority
public static boolean validJarAuthority(String value)
validDevice
public static boolean validDevice(String value)
validSegment
public static boolean validSegment(String value)
validSegments
public static boolean validSegments(String[] value)
validQuery
public static boolean validQuery(String value)
validFragment
public static boolean validFragment(String value)
isRelative
public boolean isRelative()
isHierarchical
public boolean isHierarchical()
hasAuthority
public boolean hasAuthority()
hasOpaquePart
public boolean hasOpaquePart()
hasDevice
public boolean hasDevice()
hasPath
public boolean hasPath()
hasAbsolutePath
public boolean hasAbsolutePath()
hasRelativePath
public boolean hasRelativePath()
hasEmptyPath
public boolean hasEmptyPath()
hasQuery
public boolean hasQuery()
hasFragment
public boolean hasFragment()
isCurrentDocumentReference
public boolean isCurrentDocumentReference()
isEmpty
public boolean isEmpty()
isFile
public boolean isFile()
hashCode
public int hashCode()
equals
public boolean equals(Object obj)
scheme
public String scheme()
opaquePart
public String opaquePart()
authority
public String authority()
userInfo
public String userInfo()
host
public String host()
port
public String port()
device
public String device()
segments
public String[] segments()
segmentsList
public List segmentsList()
segmentCount
public int segmentCount()
segment
public String segment(int i)
lastSegment
public String lastSegment()
path
public String path()
devicePath
public String devicePath()
device/pathSegment1/pathSegment2...
//authority/device/pathSegment1/pathSegment2...
authority/pathSegment1/pathSegment2...
query
public String query()
appendQuery
public URI appendQuery(String query)
trimQuery
public URI trimQuery()
fragment
public String fragment()
appendFragment
public URI appendFragment(String fragment)
trimFragment
public URI trimFragment()
resolve
public URI resolve(URI base)
resolve
public URI resolve(URI base,
boolean preserveRootParents)
deresolve
public URI deresolve(URI base)
deresolve
public URI deresolve(URI base,
boolean preserveRootParents,
boolean anyRelPath,
boolean shorterRelPath)
toString
public String toString()
scheme:opaquePart#fragment
scheme://authority/device/pathSegment1/pathSegment2...?query#fragment
scheme:authority/pathSegment1/pathSegment2...?query#fragment
toFileString
public String toFileString()
device/pathSegment1/pathSegment2...
//authority/device/pathSegment1/pathSegment2...
appendSegment
public URI appendSegment(String segment)
appendSegments
public URI appendSegments(String[] segments)
trimSegments
public URI trimSegments(int i)
hasTrailingPathSeparator
public boolean hasTrailingPathSeparator()
fileExtension
public String fileExtension()
appendFileExtension
public URI appendFileExtension(String fileExtension)
trimFileExtension
public URI trimFileExtension()
isPrefix
public boolean isPrefix()
replacePrefix
public URI replacePrefix(URI oldPrefix,
URI newPrefix)
encodeOpaquePart
public static String encodeOpaquePart(String value,
boolean ignoreEscaped)
encodeAuthority
public static String encodeAuthority(String value,
boolean ignoreEscaped)
encodeSegment
public static String encodeSegment(String value,
boolean ignoreEscaped)
encodeQuery
public static String encodeQuery(String value,
boolean ignoreEscaped)
encodeFragment
public static String encodeFragment(String value,
boolean ignoreEscaped)
decode
public static String decode(String value)
Overview
Package
Class
Use
Tree
Deprecated
Index
Help
Copyright 2001-2004 IBM Corporation and others.
All Rights Reserved.
PREV CLASS
NEXT CLASS
FRAMES
NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD