public abstract class URI
extends java.lang.Object
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 resolve
d 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 Finally, note the difference between a 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 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
!
Modifier and Type | Class and Description |
---|---|
protected static class |
URI.Fragment
A subclass for representing a URI with a fragment.
|
protected static class |
URI.Hierarchical
A subclass for representing a hierarchical URI.
|
protected static class |
URI.Opaque
A subclass for representing an opaque URI.
|
protected static class |
URI.URIPool
A pool for caching URIs.
|
Modifier and Type | Field and Description |
---|---|
protected static long |
ALPHA_HI |
protected static long |
ALPHA_LO |
protected static long |
ALPHANUM_HI |
protected static long |
ALPHANUM_LO |
protected static char |
ARCHIVE_IDENTIFIER |
protected static java.lang.String[] |
ARCHIVE_SCHEMES |
protected static java.lang.String |
ARCHIVE_SEPARATOR |
protected static java.lang.String |
AUTHORITY_SEPARATOR |
protected static int |
AUTHORITY_SEPARATOR_HASH_CODE |
protected static boolean |
DEBUG |
protected static char |
DEVICE_IDENTIFIER |
protected static long |
DIGIT_HI |
protected static long |
DIGIT_LO |
protected static boolean |
ENCODE_PLATFORM_RESOURCE_URIS |
protected static char |
ESCAPE |
protected static char |
FILE_EXTENSION_SEPARATOR |
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. |
protected static char |
FRAGMENT_SEPARATOR |
protected int |
hashCode
The cached hash code of the URI.
|
protected static char[] |
HEX_DIGITS |
protected static long |
HEX_HI |
protected static long |
HEX_LO |
protected static long |
MAJOR_SEPARATOR_HI |
protected static long |
MAJOR_SEPARATOR_LO |
protected static java.lang.String[] |
NO_SEGMENTS |
protected static java.lang.String[] |
ONE_EMPTY_SEGMENT |
protected static java.lang.String[] |
ONE_SELF_SEGMENT |
protected static long |
PATH_CHAR_HI |
protected static long |
PATH_CHAR_LO |
protected static long |
PLATFORM_SEGMENT_RESERVED_HI |
protected static long |
PLATFORM_SEGMENT_RESERVED_LO |
protected static URI.URIPool |
POOL
A pool for managing
URI instances. |
protected static char |
PORT_SEPARATOR |
protected static char |
QUERY_SEPARATOR |
protected static long |
RESERVED_HI |
protected static long |
RESERVED_LO |
protected static java.lang.String |
SCHEME_ARCHIVE |
protected static int |
SCHEME_ARCHIVE_HASH_CODE |
protected static java.lang.String |
SCHEME_FILE |
protected static int |
SCHEME_FILE_HASH_CODE |
protected static java.lang.String |
SCHEME_HTTP |
protected static int |
SCHEME_HTTP_HASH_CODE |
protected static java.lang.String |
SCHEME_JAR |
protected static int |
SCHEME_JAR_HASH_CODE |
protected static java.lang.String |
SCHEME_PLATFORM |
protected static int |
SCHEME_PLATFORM_HASH_CODE |
protected static char |
SCHEME_SEPARATOR |
protected static java.lang.String |
SCHEME_ZIP |
protected static int |
SCHEME_ZIP_HASH_CODE |
protected static long |
SEGMENT_CHAR_HI |
protected static long |
SEGMENT_CHAR_LO |
protected static java.lang.String |
SEGMENT_EMPTY |
protected static long |
SEGMENT_END_HI |
protected static long |
SEGMENT_END_LO |
protected static java.lang.String |
SEGMENT_PARENT |
protected static java.lang.String |
SEGMENT_PLUGIN |
protected static java.lang.String |
SEGMENT_RESOURCE |
protected static java.lang.String |
SEGMENT_SELF |
protected static char |
SEGMENT_SEPARATOR |
protected static long |
UNRESERVED_HI |
protected static long |
UNRESERVED_LO |
protected static long |
URIC_HI |
protected static long |
URIC_LO |
protected static char |
USER_INFO_SEPARATOR |
Modifier | Constructor and Description |
---|---|
protected |
URI(int hashCode) |
Modifier and Type | Method and Description |
---|---|
protected static void |
appendEscaped(java.lang.StringBuffer result,
byte b) |
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. |
protected void |
cacheString(java.lang.String string) |
protected java.lang.String[] |
collapseSegments(boolean preserveRootParents) |
protected static boolean |
contains(java.lang.String s,
long highBitmask,
long lowBitmask) |
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.
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. |
protected static java.lang.String |
encode(java.lang.String value,
long highBitmask,
long lowBitmask,
boolean ignoreEscaped) |
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.
|
protected static java.lang.String |
encodeURI(java.lang.String uri,
boolean ignoreEscaped,
int fragmentLocationStyle) |
protected static boolean |
equals(java.lang.Object o1,
java.lang.Object o2) |
java.lang.String |
fileExtension()
If this is a hierarchical URI whose path includes a file extension,
that file extension is returned; null otherwise.
|
protected static java.lang.String |
firstInvalidSegment(java.lang.String[] value) |
protected void |
flushCachedString() |
java.lang.String |
fragment()
If this URI has a fragment component, returns it;
null otherwise. |
protected java.lang.String |
getCachedString() |
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. |
protected boolean |
hasDeviceOrPath() |
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. |
protected static long |
highBitmask(char c) |
protected static long |
highBitmask(char from,
char to) |
protected static long |
highBitmask(java.lang.String chars) |
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. |
protected boolean |
isBase() |
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()
|
protected static boolean |
isEscaped(java.lang.String s,
int i) |
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 . |
protected static long |
lowBitmask(char c) |
protected static long |
lowBitmask(char from,
char to) |
protected static long |
lowBitmask(java.lang.String chars) |
protected static boolean |
matches(char c,
long highBitmask,
long lowBitmask) |
protected boolean |
matches(int validate,
boolean hierarchical,
java.lang.String scheme,
java.lang.String authority,
java.lang.String device,
boolean absolutePath,
java.lang.String[] segments,
java.lang.String query) |
protected boolean |
matches(java.lang.String string) |
protected boolean |
matches(java.lang.String base,
java.lang.String path) |
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. |
protected URI |
rawAppendFragment(java.lang.CharSequence fragment) |
protected java.lang.String[] |
rawSegments() |
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.
|
protected boolean |
segmentsEqual(URI uri) |
java.util.List<java.lang.String> |
segmentsList()
Returns an unmodifiable list containing the same segments as the array
returned by
segments . |
protected static java.lang.CharSequence |
splitInternFragment(java.lang.String fragment) |
java.lang.String |
toFileString()
|
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. |
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.
|
protected static char |
unescape(char highHexDigit,
char lowHexDigit) |
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. |
protected static boolean |
validateURI(boolean hierarchical,
java.lang.String scheme,
java.lang.String authority,
java.lang.String device,
boolean absolutePath,
java.lang.String[] segments,
java.lang.String query,
java.lang.String fragment) |
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. |
protected static int |
valueOf(char hexDigit) |
protected static final boolean DEBUG
protected int hashCode
Object.toString()
protected static final URI.URIPool POOL
URI
instances.protected static final java.lang.String[] ARCHIVE_SCHEMES
protected static final java.lang.String SCHEME_FILE
protected static final java.lang.String SCHEME_JAR
protected static final java.lang.String SCHEME_ZIP
protected static final java.lang.String SCHEME_ARCHIVE
protected static final java.lang.String SCHEME_PLATFORM
protected static final java.lang.String SCHEME_HTTP
protected static final int SCHEME_FILE_HASH_CODE
protected static final int SCHEME_JAR_HASH_CODE
protected static final int SCHEME_ZIP_HASH_CODE
protected static final int SCHEME_ARCHIVE_HASH_CODE
protected static final int SCHEME_PLATFORM_HASH_CODE
protected static final int SCHEME_HTTP_HASH_CODE
protected static final java.lang.String SEGMENT_EMPTY
protected static final java.lang.String SEGMENT_SELF
protected static final java.lang.String SEGMENT_PARENT
protected static final java.lang.String SEGMENT_PLUGIN
protected static final java.lang.String SEGMENT_RESOURCE
protected static final java.lang.String[] NO_SEGMENTS
protected static final java.lang.String[] ONE_EMPTY_SEGMENT
protected static final java.lang.String[] ONE_SELF_SEGMENT
protected static final char SCHEME_SEPARATOR
protected static final java.lang.String AUTHORITY_SEPARATOR
protected static final int AUTHORITY_SEPARATOR_HASH_CODE
protected static final char DEVICE_IDENTIFIER
protected static final char SEGMENT_SEPARATOR
protected static final char QUERY_SEPARATOR
protected static final char FRAGMENT_SEPARATOR
protected static final char USER_INFO_SEPARATOR
protected static final char PORT_SEPARATOR
protected static final char FILE_EXTENSION_SEPARATOR
protected static final char ARCHIVE_IDENTIFIER
protected static final java.lang.String ARCHIVE_SEPARATOR
protected static final char ESCAPE
protected static final char[] HEX_DIGITS
protected static final long ALPHA_HI
protected static final long ALPHA_LO
protected static final long DIGIT_HI
protected static final long DIGIT_LO
protected static final long ALPHANUM_HI
protected static final long ALPHANUM_LO
protected static final long HEX_HI
protected static final long HEX_LO
protected static final long UNRESERVED_HI
protected static final long UNRESERVED_LO
protected static final long RESERVED_HI
protected static final long RESERVED_LO
protected static final long URIC_HI
protected static final long URIC_LO
protected static final long SEGMENT_CHAR_HI
protected static final long SEGMENT_CHAR_LO
protected static final long PATH_CHAR_HI
protected static final long PATH_CHAR_LO
protected static final long MAJOR_SEPARATOR_HI
protected static final long MAJOR_SEPARATOR_LO
protected static final long SEGMENT_END_HI
protected static final long SEGMENT_END_LO
protected static final long PLATFORM_SEGMENT_RESERVED_HI
protected static final long PLATFORM_SEGMENT_RESERVED_LO
protected static final boolean ENCODE_PLATFORM_RESOURCE_URIS
public static final int FRAGMENT_NONE
createURI
, indicates that there is no fragment, so any #
characters
should be encoded.public static final int FRAGMENT_FIRST_SEPARATOR
createURI
, indicates that the first #
character should be taken as
the fragment separator, and any others should be encoded.public static final int FRAGMENT_LAST_SEPARATOR
createURI
, indicates that the last #
character should be taken as
the fragment separator, and any others should be encoded.protected static long lowBitmask(char c)
protected static long highBitmask(char c)
protected static long lowBitmask(char from, char to)
protected static long highBitmask(char from, char to)
protected static long lowBitmask(java.lang.String chars)
protected static long highBitmask(java.lang.String chars)
protected static boolean matches(char c, long highBitmask, long lowBitmask)
public static URI createGenericURI(java.lang.String scheme, java.lang.String opaquePart, java.lang.String fragment)
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.public static URI createHierarchicalURI(java.lang.String scheme, java.lang.String authority, java.lang.String device, java.lang.String query, java.lang.String fragment)
scheme
is non-null, and absolute
otherwise. An absolute URI with no path requires a non-null
authority
and/or device
.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.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)
scheme
is non-null, and
absolute otherwise.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.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.public static URI createHierarchicalURI(java.lang.String[] segments, java.lang.String query, java.lang.String fragment)
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.java.lang.IllegalArgumentException
- if segments
,
query
, or fragment
is not valid according to
validSegments
, validQuery
, or
validFragment
, respectively.public static URI createURI(java.lang.String uri)
URI
is created and returned. Note that
validity testing is not as strict as in the RFC; essentially, only
separator characters are considered. This method also does not perform
encoding of invalid characters, so it should only be used when the URI
string is known to have already been encoded, so as to avoid double
encoding.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.public static URI createURI(java.lang.String uri, boolean ignoreEscaped)
#
is in the string, the last one is
assumed to be the fragment's separator, and any others are encoded.
This method is the simplest way to safely parse an arbitrary URI string.ignoreEscaped
- true
to leave %
characters
unescaped if they already begin a valid three-character escape sequence;
false
to encode all %
characters. This
capability is provided to allow partially encoded URIs to be "fixed",
while avoiding adding double encoding; however, it is usual just to
specify false
to perform ordinary encoding.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.public static URI createURI(java.lang.String uri, boolean ignoreEscaped, int fragmentLocationStyle)
#
should be
taken as the fragment separator and which should be encoded.
This method is the preferred way to safely parse an arbitrary URI string
that is known to contain #
characters in the fragment or to
have no fragment at all.ignoreEscaped
- true
to leave %
characters
unescaped if they already begin a valid three-character escape sequence;
false
to encode all %
characters. This
capability is provided to allow partially encoded URIs to be "fixed",
while avoiding adding double encoding; however, it is usual just to
specify false
to perform ordinary encoding.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.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.@Deprecated public static URI createDeviceURI(java.lang.String uri)
createURI
, which now has explicit
device support enabled. The two methods now operate identically.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.@Deprecated public static URI createURIWithCache(java.lang.String uri)
createURI
instead.public static URI createFileURI(java.lang.String pathName)
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, if the path is absolute
, and, if missing,
a leading /
, are added to an absolute path. The result
is then parsed the same as if 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 via the static decode
method.
A relative path with a specified device (something like
C:myfile.txt
) cannot be expressed as a valid URI.
An absolute URI, i.e., one with file:
will only be returned if the pathName
itself is absolute
.
In other words, a relative path will yield a relative
URI,
and in particular on Windows, a path is absolute only if the device is specified,
e.g., C:/myfile.text
is absolute but /myfile.text
is relative on Windows though absolute on Unix-style file systems.
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
.@Deprecated public static URI createPlatformResourceURI(java.lang.String pathName)
createPlatformResourceURI(String, boolean)
instead.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.
java.lang.IllegalArgumentException
- if any component parsed
from the path is not valid according to validDevice
,
validSegments
, validQuery
, or
validFragment
.org.eclipse.core.runtime.Platform#resolve
,
createPlatformResourceURI(String, boolean)
public static URI createPlatformResourceURI(java.lang.String pathName, boolean encode)
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. It is strongly
recommended to specify true
to enable encoding, unless the
path string has already been encoded.
java.lang.IllegalArgumentException
- if any component parsed
from the path is not valid according to validDevice
,
validSegments
, validQuery
, or
validFragment
.org.eclipse.core.runtime.Platform#resolve
public static URI createPlatformPluginURI(java.lang.String pathName, boolean encode)
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. It is strongly
recommended to specify true
to enable encoding, unless the
path string has already been encoded.
java.lang.IllegalArgumentException
- if any component parsed
from the path is not valid according to validDevice
,
validSegments
, validQuery
, or
validFragment
.org.eclipse.core.runtime.Platform#resolve
protected static java.lang.CharSequence splitInternFragment(java.lang.String fragment)
protected static boolean validateURI(boolean hierarchical, java.lang.String scheme, java.lang.String authority, java.lang.String device, boolean absolutePath, java.lang.String[] segments, java.lang.String query, java.lang.String fragment)
public static boolean validScheme(java.lang.String value)
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: : / ? #
public static boolean validOpaquePart(java.lang.String value)
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
/
public static boolean validAuthority(java.lang.String value)
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: / ? #
public static boolean validArchiveAuthority(java.lang.String value)
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 or query,
followed by the character !
.
@Deprecated public static boolean validJarAuthority(java.lang.String value)
validArchiveAuthority
.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.public static boolean validDevice(java.lang.String value)
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 :
public static boolean validSegment(java.lang.String value)
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: / ? #
public static boolean validSegments(java.lang.String[] value)
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
.
protected static java.lang.String firstInvalidSegment(java.lang.String[] value)
public static boolean validQuery(java.lang.String value)
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
#
public static boolean validFragment(java.lang.String value)
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.
protected static boolean contains(java.lang.String s, long highBitmask, long lowBitmask)
protected void flushCachedString()
protected void cacheString(java.lang.String string)
protected java.lang.String getCachedString()
public boolean isRelative()
true
if this is a relative URI, or
false
if it is an absolute URI.protected boolean isBase()
public boolean isHierarchical()
true
if this a a hierarchical URI, or
false
if it is of the generic form.public boolean hasAuthority()
true
if this is a hierarchical URI with an authority
component; false
otherwise.public boolean hasOpaquePart()
true
if this is a non-hierarchical URI with an
opaque part component; false
otherwise.public boolean hasDevice()
true
if this is a hierarchical URI with a device
component; false
otherwise.protected boolean hasDeviceOrPath()
public boolean hasPath()
true
if this is a hierarchical URI with an
absolute or relative path; false
otherwise.public boolean hasAbsolutePath()
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.public boolean hasRelativePath()
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.public boolean hasEmptyPath()
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.
public boolean hasQuery()
true
if this is a hierarchical URI with a query
component; false
otherwise.public boolean hasFragment()
true
if this URI has a fragment component;
false
otherwise.public boolean isCurrentDocumentReference()
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.public boolean isEmpty()
isCurrentDocumentReference()
public boolean isFile()
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.public boolean isPlatform()
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.public boolean isPlatformResource()
true
if this is a platform resource URI, that is,
a platform URI
whose first segment is "resource";
false
is returned otherwise.isPlatform()
public boolean isPlatformPlugin()
true
if this is a platform plug-in URI, that is,
a platform URI
whose first segment is "plugin";
false
is returned otherwise.isPlatform()
public boolean isArchive()
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.public static boolean isArchiveScheme(java.lang.String value)
true
if the specified value
would be
valid as the scheme of an archive URI; false
otherwise.public int hashCode()
hashCode
in class java.lang.Object
protected boolean segmentsEqual(URI uri)
protected static boolean equals(java.lang.Object o1, java.lang.Object o2)
public java.lang.String scheme()
null
otherwise.public java.lang.String opaquePart()
null
otherwise.public java.lang.String authority()
null
otherwise.public java.lang.String userInfo()
null
otherwise.public java.lang.String host()
null
otherwise.public java.lang.String port()
null
otherwise.public java.lang.String device()
null
otherwise.public java.lang.String[] segments()
protected java.lang.String[] rawSegments()
public java.util.List<java.lang.String> segmentsList()
segments
.public int segmentCount()
segments
.public java.lang.String segment(int i)
java.lang.IndexOutOfBoundsException
- if i < 0
or
i >= segmentCount()
.public java.lang.String lastSegment()
null
.public java.lang.String 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.public java.lang.String devicePath()
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...
public java.lang.String query()
null
otherwise.public URI appendQuery(java.lang.String query)
java.lang.IllegalArgumentException
- if
query
is not a valid query (portion) according
to validQuery
.public URI trimQuery()
query
, returns the URI
formed by removing it; this URI unchanged, otherwise.public java.lang.String fragment()
null
otherwise.public URI appendFragment(java.lang.String fragment)
java.lang.IllegalArgumentException
- if
fragment
is not a valid fragment (portion) according
to validFragment
.protected URI rawAppendFragment(java.lang.CharSequence fragment)
public URI trimFragment()
fragment
, returns the URI
formed by removing it; this URI unchanged, otherwise.public URI resolve(URI base)
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
.
java.lang.IllegalArgumentException
- if base
is
non-hierarchical or is relative.public URI resolve(URI base, boolean preserveRootParents)
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.
preserveRootParents
- true
if segments referring to the
parent of the root path are to be preserved; false
if they
are to be discarded.java.lang.IllegalArgumentException
- if base
is
non-hierarchical or is relative.public URI deresolve(URI base)
base
absolute hierarchical
URI using resolve
, will yield this absolute URI.
If base
is non-hierarchical or is relative,
or this
is non-hierarchical or is relative,
this
will be returned.public URI deresolve(URI base, boolean preserveRootParents, boolean anyRelPath, boolean shorterRelPath)
base
absolute hierarchical URI using resolve
, will yield this absolute URI.
If base
is non-hierarchical or is relative,
or this
is non-hierarchical or is relative,
this
will be returned.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.protected java.lang.String[] collapseSegments(boolean preserveRootParents)
protected boolean matches(java.lang.String string)
protected boolean matches(int validate, boolean hierarchical, java.lang.String scheme, java.lang.String authority, java.lang.String device, boolean absolutePath, java.lang.String[] segments, java.lang.String query)
protected boolean matches(java.lang.String base, java.lang.String path)
public java.lang.String toFileString()
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
.
public java.lang.String toPlatformString(boolean decode)
isPlatform()
, returns
the workspace-relative or plug-in-based path to the resource, optionally
decoding
the segments in the process.createPlatformResourceURI(String, boolean)
,
createPlatformPluginURI(java.lang.String, boolean)
public URI appendSegment(java.lang.String segment)
java.lang.IllegalArgumentException
- if segment
is not a valid segment according to validSegment(java.lang.String)
.public URI appendSegments(java.lang.String[] segments)
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.java.lang.IllegalArgumentException
- if segments
is not a valid segment array according to validSegments(java.lang.String[])
.public URI trimSegments(int i)
Note that if all segments are trimmed from an absolute path, the root absolute path remains.
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.public boolean hasTrailingPathSeparator()
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.
public java.lang.String fileExtension()
public URI appendFileExtension(java.lang.String fileExtension)
The extension is appended regardless of whether the segment already contains an extension.
java.lang.IllegalArgumentException
- if
fileExtension
is not a valid segment (portion) according
to validSegment(java.lang.String)
.public URI trimFileExtension()
fileExtension
,
returns the URI formed by removing it; this URI unchanged, otherwise.public boolean isPrefix()
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.public URI replacePrefix(URI oldPrefix, URI newPrefix)
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.
java.lang.IllegalArgumentException
- if either
oldPrefix
or newPrefix
is not a prefix URI
according to isPrefix()
.public static java.lang.String encodeOpaquePart(java.lang.String value, boolean ignoreEscaped)
#
,
are escaped, as is /
if it is the first character.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.public static java.lang.String encodeAuthority(java.lang.String value, boolean ignoreEscaped)
#
,
are escaped, as are /
and ?
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.public static java.lang.String encodeSegment(java.lang.String value, boolean ignoreEscaped)
#
,
are escaped, as are /
and ?
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.public static java.lang.String encodeQuery(java.lang.String value, boolean ignoreEscaped)
#
, are escaped.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.public static java.lang.String encodeFragment(java.lang.String value, boolean ignoreEscaped)
#
, are
escaped.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.protected static java.lang.String encodeURI(java.lang.String uri, boolean ignoreEscaped, int fragmentLocationStyle)
protected static java.lang.String encode(java.lang.String value, long highBitmask, long lowBitmask, boolean ignoreEscaped)
protected static boolean isEscaped(java.lang.String s, int i)
protected static void appendEscaped(java.lang.StringBuffer result, byte b)
public static java.lang.String decode(java.lang.String value)
protected static char unescape(char highHexDigit, char lowHexDigit)
protected static int valueOf(char hexDigit)