Class URI
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 char
and String
representations, and
makes no attempt to encode characters 0xA0 and above. Characters in the
range 0x80-0x9F are still escaped. In this respect, EMF's notion of a URI
is actually more like an IRI (Internationalized Resource Identifier), for
which an RFC is now in draft
form.
Finally, note the difference between a null
parameter to
the static factory methods and an empty string. The former signifies the
absence of a given URI component, while the latter simply makes the
component blank. This can have a significant effect when resolving. For
example, consider the following two URIs: /bar
(with no
authority) and ///bar
(with a blank authority). Imagine
resolving them against a base with an authority, such as
http://www.eclipse.org/
. The former case will yield
http://www.eclipse.org/bar
, as the base authority will be
preserved. In the latter case, the empty authority will override the
base authority, resulting in http:///bar
!
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
When specified as the last argument tocreateURI
, indicates that the first#
character should be taken as the fragment separator, and any others should be encoded.static final int
When specified as the last argument tocreateURI
, indicates that the last#
character should be taken as the fragment separator, and any others should be encoded.static final int
When specified as the last argument tocreateURI
, indicates that there is no fragment, so any#
characters should be encoded. -
Method Summary
Modifier and TypeMethodDescriptionappendFileExtension
(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.appendFragment
(String fragment) Returns the URI formed from this URI and the given fragment.appendQuery
(String query) Returns the URI formed from this URI and the given query.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.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.If this is a hierarchical URI with an authority component, returns it;null
otherwise.static URI
createDeviceURI
(String uri) Deprecated.static URI
createFileURI
(String pathName) Static factory method based on parsing aFile
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
createPlatformPluginURI
(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
(String pathName) Deprecated.UsecreatePlatformResourceURI(String, boolean)
instead.static URI
createPlatformResourceURI
(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
Static factory method based on parsing a URI string, with explicit device support and handling for archive URIs enabled.static URI
Static factory method that encodes and parses the given URI string.static URI
Static factory method that encodes and parses the given URI string.static URI
createURIWithCache
(String uri) Deprecated.Please usecreateURI
instead.static String
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.Finds the shortest relative or, if necessary, the absolute URI that, when resolved against the givenbase
absolute hierarchical URI usingresolve
, will yield this absolute URI.Finds an absolute URI that, when resolved against the givenbase
absolute hierarchical URI usingresolve
, will yield this absolute URI.device()
If this is a hierarchical URI with a device component, returns it;null
otherwise.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
Returnstrue
ifobject
is an instance ofURI
equal to this one;false
otherwise.If this is a hierarchical URI whose path includes a file extension, that file extension is returned; null otherwise.fragment()
If this URI has a fragment component, returns it;null
otherwise.boolean
Returnstrue
if this is a hierarchical URI with an absolute path, orfalse
if it is non-hierarchical, has no path, or has a relative path.boolean
Returnstrue
if this is a hierarchical URI with an authority component;false
otherwise.boolean
Returnstrue
if this is a hierarchical URI with a device component;false
otherwise.boolean
Returnstrue
if this is a hierarchical URI with an empty relative path;false
otherwise.boolean
Returnstrue
if this URI has a fragment component;false
otherwise.int
hashCode()
Returns the hash code.boolean
Returnstrue
if this is a non-hierarchical URI with an opaque part component;false
otherwise.boolean
hasPath()
Returnstrue
if this is a hierarchical URI with an absolute or relative path;false
otherwise.boolean
hasQuery()
Returnstrue
if this is a hierarchical URI with a query component;false
otherwise.boolean
Returnstrue
if this is a hierarchical URI with a relative path, orfalse
if it is non-hierarchical, has no path, or has an absolute path.boolean
Returnstrue
if this is a hierarchical URI that has a path that ends with a trailing separator;false
otherwise.host()
If this is a hierarchical URI with an authority component that has a host portion, returns it;null
otherwise.boolean
Returnstrue
if this is an archive URI.static boolean
isArchiveScheme
(String value) Returnstrue
if the specifiedvalue
would be valid as the scheme of an archive URI;false
otherwise.boolean
Returnstrue
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()
boolean
isFile()
Returnstrue
if this is a hierarchical URI that may refer directly to a locally accessible file.boolean
Returnstrue
if this a a hierarchical URI, orfalse
if it is of the generic form.boolean
Returnstrue
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
Returnstrue
if this is a platform plug-in URI, that is, aplatform URI
whose first segment is "plugin";false
is returned otherwise.boolean
Returnstrue
if this is a platform resource URI, that is, aplatform URI
whose first segment is "resource";false
is returned otherwise.boolean
isPrefix()
Returnstrue
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
Returnstrue
if this is a relative URI, orfalse
if it is an absolute URI.Returns the last segment in the segment array, ornull
.If this is a non-hierarchical URI, returns the opaque part component;null
otherwise.path()
If this is a hierarchical URI with a path, returns a string representation of the path;null
otherwise.port()
If this is a hierarchical URI with an authority component that has a port portion, returns it;null
otherwise.query()
If this is a hierarchical URI with a query component, returns it;null
otherwise.replacePrefix
(URI oldPrefix, URI newPrefix) If this is a hierarchical URI reference andoldPrefix
is a prefix of it, this returns the URI formed by replacing it bynewPrefix
;null
otherwise.Resolves this URI reference against abase
absolute hierarchical URI, returning the resulting absolute URI.Resolves this URI reference against abase
absolute hierarchical URI, returning the resulting absolute URI.scheme()
If this is an absolute URI, returns the scheme component;null
otherwise.segment
(int i) Provides fast, indexed access to individual segments in the path segment array.int
Returns the number of elements in the segment array that would be returned bysegments
.String[]
segments()
If this is a hierarchical URI with a path, returns an array containing the segments of the path; an empty array otherwise.Returns an unmodifiable list containing the same segments as the array returned bysegments
.toPlatformString
(boolean decode) If this is a platform URI, as determined byisPlatform()
, returns the workspace-relative or plug-in-based path to the resource, optionallydecoding
the segments in the process.toString()
Returns the string representation of this URI.If this URI has a non-nullfileExtension
, returns the URI formed by removing it; this URI unchanged, otherwise.If this URI has a non-nullfragment
, returns the URI formed by removing it; this URI unchanged, otherwise.If this URI has a non-nullquery
, returns the URI formed by removing it; this URI unchanged, otherwise.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.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) Returnstrue
if the specifiedvalue
would be valid as the authority component of an archive URI;false
otherwise.static boolean
validAuthority
(String value) Returnstrue
if the specifiedvalue
would be valid as the authority component of a URI;false
otherwise.static boolean
validDevice
(String value) Returnstrue
if the specifiedvalue
would be valid as the device component of a URI;false
otherwise.static boolean
validFragment
(String value) Returnstrue
if the specifiedvalue
would be valid as the fragment component of a URI;false
otherwise.static boolean
validJarAuthority
(String value) Deprecated.As of EMF 2.0, replaced byvalidArchiveAuthority
.static boolean
validOpaquePart
(String value) Returnstrue
if the specifiedvalue
would be valid as the opaque part component of a URI;false
otherwise.static boolean
validQuery
(String value) Returnstrue
if the specifiedvalue
would be valid as the query component of a URI;false
otherwise.static boolean
validScheme
(String value) Returnstrue
if the specifiedvalue
would be valid as the scheme component of a URI;false
otherwise.static boolean
validSegment
(String value) Returnstrue
if the specifiedvalue
would be a valid path segment of a URI;false
otherwise.static boolean
validSegments
(String[] value) Returnstrue
if the specifiedvalue
would be a valid path segment array of a URI;false
otherwise.
-
Field Details
-
FRAGMENT_NONE
public static final int FRAGMENT_NONEWhen specified as the last argument tocreateURI
, indicates that there is no fragment, so any#
characters should be encoded. -
FRAGMENT_FIRST_SEPARATOR
public static final int FRAGMENT_FIRST_SEPARATORWhen specified as the last argument tocreateURI
, indicates that the first#
character should be taken as the fragment separator, and any others should be encoded. -
FRAGMENT_LAST_SEPARATOR
public static final int FRAGMENT_LAST_SEPARATORWhen specified as the last argument tocreateURI
, indicates that the last#
character should be taken as the fragment separator, and any others should be encoded.
-
-
Method Details
-
createGenericURI
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:
IllegalArgumentException
- ifscheme
is null, ifscheme
is an archive URI scheme, or ifscheme
,opaquePart
, orfragment
is not valid according tovalidScheme
,validOpaquePart
, orvalidFragment
, respectively.
-
createHierarchicalURI
public static URI createHierarchicalURI(String scheme, String authority, String device, String query, String fragment) Static factory method for a hierarchical URI with no path. The URI will be relative ifscheme
is non-null, and absolute otherwise. An absolute URI with no path requires a non-nullauthority
and/ordevice
.- Throws:
IllegalArgumentException
- ifscheme
is non-null whileauthority
anddevice
are null, ifscheme
is an archive URI scheme, or ifscheme
,authority
,device
,query
, orfragment
is not valid according tovalidSheme
,validAuthority
,validDevice
,validQuery
, orvalidFragment
, respectively.
-
createHierarchicalURI
public 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. The URI will be relative ifscheme
is non-null, and absolute otherwise.- Parameters:
segments
- an array of non-null strings, each representing one segment of the path. As an absolute path, it is automatically preceded by a/
separator. If desired, a trailing separator should be represented by an empty-string segment as the last element of the array.- Throws:
IllegalArgumentException
- ifscheme
is an archive URI scheme anddevice
is non-null, or ifscheme
,authority
,device
,segments
,query
, orfragment
is not valid according tovalidScheme
,validAuthority
orvalidArchiveAuthority
,validDevice
,validSegments
,validQuery
, orvalidFragment
, as appropriate.
-
createHierarchicalURI
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:
IllegalArgumentException
- ifsegments
,query
, orfragment
is not valid according tovalidSegments
,validQuery
, orvalidFragment
, respectively.
-
createURI
Static factory method based on parsing a URI string, with explicit device support and handling for archive URIs enabled. The specified string is parsed as described in RFC 2396, and an appropriateURI
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.- Throws:
IllegalArgumentException
- if any component parsed fromuri
is not valid according tovalidScheme
,validOpaquePart
,validAuthority
,validArchiveAuthority
,validDevice
,validSegments
,validQuery
, orvalidFragment
, as appropriate.
-
createURI
Static factory method that encodes and parses the given URI string. Appropriate encoding is performed for each component of the URI. If more than one#
is in the string, the last one is assumed to be the fragment's separator, and any others are encoded. This method is the simplest way to safely parse an arbitrary URI string.- Parameters:
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 specifyfalse
to perform ordinary encoding.- Throws:
IllegalArgumentException
- if any component parsed fromuri
is not valid according tovalidScheme
,validOpaquePart
,validAuthority
,validArchiveAuthority
,validDevice
,validSegments
,validQuery
, orvalidFragment
, as appropriate.
-
createURI
Static factory method that encodes and parses the given URI string. Appropriate encoding is performed for each component of the URI. Control is provided over which, if any,#
should be taken as the fragment separator and which should be encoded. 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.- Parameters:
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 specifyfalse
to perform ordinary encoding.fragmentLocationStyle
- one ofFRAGMENT_NONE
,FRAGMENT_FIRST_SEPARATOR
, orFRAGMENT_LAST_SEPARATOR
, indicating which, if any, of the#
characters should be considered the fragment separator. Any others will be encoded.- Throws:
IllegalArgumentException
- if any component parsed fromuri
is not valid according tovalidScheme
,validOpaquePart
,validAuthority
,validArchiveAuthority
,validDevice
,validSegments
,validQuery
, orvalidFragment
, as appropriate.
-
createDeviceURI
Deprecated.UsecreateURI
, which now has explicit device support enabled. The two methods now operate identically.Static factory method based on parsing a URI string, with explicit device support enabled. Note that validity testing is not a strict as in the RFC; essentially, only separator characters are considered. So, for example, non-Latin alphabet characters appearing in the scheme would not be considered an error.- Throws:
IllegalArgumentException
- if any component parsed fromuri
is not valid according tovalidScheme
,validOpaquePart
,validAuthority
,validArchiveAuthority
,validDevice
,validSegments
,validQuery
, orvalidFragment
, as appropriate.
-
createURIWithCache
Deprecated.Please usecreateURI
instead.This method was included in the public API by mistake. -
createFileURI
Static factory method based on parsing aFile
path string. ThepathName
is converted into an appropriate form, as follows: platform specific path separators are converted to/
; the path is encoded; and a "file" scheme and, if missing, a leading/
, are added to an absolute path. The result is then parsed usingcreateURI
.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 bytoFileString
, and can be applied to the values returned by other accessors by via the staticdecode
method.A relative path with a specified device (something like
C:myfile.txt
) cannot be expressed as a valid URI.- Throws:
IllegalArgumentException
- ifpathName
specifies a device and a relative path, or if any component of the path is not valid according tovalidAuthority
,validDevice
, orvalidSegments
,validQuery
, orvalidFragment
.
-
createPlatformResourceURI
Deprecated.UsecreatePlatformResourceURI(String, boolean)
instead.Static factory method based on parsing a workspace-relative path string.The
pathName
must be of the form:/project-name/path
Platform-specific path separators will be converted to slashes. If not included, the leading path separator will be added. The result will be of this form, which is parsed using
createURI
:platform:/resource/project-name/path
This scheme supports relocatable projects in Eclipse and in stand-alone EMF.
Path encoding is performed only if the
org.eclipse.emf.common.util.URI.encodePlatformResourceURIs
system property is set to "true". Decoding can be performed with the staticdecode
method.- Throws:
IllegalArgumentException
- if any component parsed from the path is not valid according tovalidDevice
,validSegments
,validQuery
, orvalidFragment
.- See Also:
-
createPlatformResourceURI
Static factory method based on parsing a workspace-relative path string, with an option to encode the created URI.The
pathName
must be of the form:/project-name/path
Platform-specific path separators will be converted to slashes. If not included, the leading path separator will be added. The result will be of this form, which is parsed using
createURI
:platform:/resource/project-name/path
This scheme supports relocatable projects in Eclipse and in stand-alone EMF.
Depending on the
encode
argument, the path may be automatically encoded to escape all spaces,#
characters, and other characters disallowed in URIs, as well as?
, which would delimit a path from a query. Decoding can be performed with the staticdecode
method. It is strongly recommended to specifytrue
to enable encoding, unless the path string has already been encoded.- Throws:
IllegalArgumentException
- if any component parsed from the path is not valid according tovalidDevice
,validSegments
,validQuery
, orvalidFragment
.- See Also:
-
createPlatformPluginURI
Static factory method based on parsing a plug-in-based path string, with an option to encode the created URI.The
pathName
must be of the form:/plugin-id/path
Platform-specific path separators will be converted to slashes. If not included, the leading path separator will be added. The result will be of this form, which is parsed using
createURI
:platform:/plugin/plugin-id/path
This scheme supports relocatable plug-in content in Eclipse.
Depending on the
encode
argument, the path may be automatically encoded to escape all spaces,#
characters, and other characters disallowed in URIs, as well as?
, which would delimit a path from a query. Decoding can be performed with the staticdecode
method. It is strongly recommended to specifytrue
to enable encoding, unless the path string has already been encoded.- Throws:
IllegalArgumentException
- if any component parsed from the path is not valid according tovalidDevice
,validSegments
,validQuery
, orvalidFragment
.- Since:
- org.eclipse.emf.common 2.3
- See Also:
-
validScheme
Returnstrue
if the specifiedvalue
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
Returnstrue
if the specifiedvalue
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
Returnstrue
if the specifiedvalue
would be valid as the authority component of a URI;false
otherwise.A valid authority may be null or contain any characters except for the following:
/ ? #
-
validArchiveAuthority
Returnstrue
if the specifiedvalue
would be valid as the authority component of an archive URI;false
otherwise.To be valid, the authority, itself, must be a URI with no fragment, followed by the character
!
. -
validJarAuthority
Deprecated.As of EMF 2.0, replaced byvalidArchiveAuthority
.Tests whether the specifiedvalue
would be valid as the authority component of an archive URI. This method has been replaced byvalidArchiveAuthority
since the same form of URI is now supported for schemes other than "jar". This now simply calls that method. -
validDevice
Returnstrue
if the specifiedvalue
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
Returnstrue
if the specifiedvalue
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
Returnstrue
if the specifiedvalue
would be a valid path segment array of a URI;false
otherwise.A valid path segment array must be non-null and contain only path segments that are valid according to
validSegment
. -
validQuery
Returnstrue
if the specifiedvalue
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
Returnstrue
if the specifiedvalue
would be valid as the fragment component of a URI;false
otherwise.A fragment is taken to be unconditionally valid.
-
isRelative
public boolean isRelative()Returnstrue
if this is a relative URI, orfalse
if it is an absolute URI. -
isHierarchical
public boolean isHierarchical()Returnstrue
if this a a hierarchical URI, orfalse
if it is of the generic form. -
hasAuthority
public boolean hasAuthority()Returnstrue
if this is a hierarchical URI with an authority component;false
otherwise. -
hasOpaquePart
public boolean hasOpaquePart()Returnstrue
if this is a non-hierarchical URI with an opaque part component;false
otherwise. -
hasDevice
public boolean hasDevice()Returnstrue
if this is a hierarchical URI with a device component;false
otherwise. -
hasPath
public boolean hasPath()Returnstrue
if this is a hierarchical URI with an absolute or relative path;false
otherwise. -
hasAbsolutePath
public boolean hasAbsolutePath()Returnstrue
if this is a hierarchical URI with an absolute path, orfalse
if it is non-hierarchical, has no path, or has a relative path. -
hasRelativePath
public boolean hasRelativePath()Returnstrue
if this is a hierarchical URI with a relative path, orfalse
if it is non-hierarchical, has no path, or has an absolute path. -
hasEmptyPath
public boolean hasEmptyPath()Returnstrue
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()Returnstrue
if this is a hierarchical URI with a query component;false
otherwise. -
hasFragment
public boolean hasFragment()Returnstrue
if this URI has a fragment component;false
otherwise. -
isCurrentDocumentReference
public boolean isCurrentDocumentReference()Returnstrue
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()- See Also:
-
isFile
public boolean isFile()Returnstrue
if this is a hierarchical URI that may refer directly to a locally accessible file. This is considered to be the case for a file-scheme absolute URI, or for a relative URI with no query;false
is returned otherwise. -
isPlatform
public boolean isPlatform()Returnstrue
if this is a platform URI, that is, an absolute, hierarchical URI, with "platform" scheme, no authority, and at least two segments;false
is returned otherwise.- Since:
- org.eclipse.emf.common 2.3
-
isPlatformResource
public boolean isPlatformResource()Returnstrue
if this is a platform resource URI, that is, aplatform URI
whose first segment is "resource";false
is returned otherwise.- Since:
- org.eclipse.emf.common 2.3
- See Also:
-
isPlatformPlugin
public boolean isPlatformPlugin()Returnstrue
if this is a platform plug-in URI, that is, aplatform URI
whose first segment is "plugin";false
is returned otherwise.- Since:
- org.eclipse.emf.common 2.3
- See Also:
-
isArchive
public boolean isArchive()Returnstrue
if this is an archive URI. If so, it is also hierarchical, with an authority (consisting of an absolute URI followed by "!"), no device, and an absolute path. -
isArchiveScheme
Returnstrue
if the specifiedvalue
would be valid as the scheme of an archive URI;false
otherwise. -
hashCode
public int hashCode()Returns the hash code. -
equals
Returnstrue
ifobject
is an instance ofURI
equal to this one;false
otherwise.Equality is determined strictly by comparing components, not by attempting to interpret what resource is being identified. The comparison of schemes is case-insensitive.
-
scheme
If this is an absolute URI, returns the scheme component;null
otherwise. -
opaquePart
If this is a non-hierarchical URI, returns the opaque part component;null
otherwise. -
authority
If this is a hierarchical URI with an authority component, returns it;null
otherwise. -
userInfo
If this is a hierarchical URI with an authority component that has a user info portion, returns it;null
otherwise. -
host
If this is a hierarchical URI with an authority component that has a host portion, returns it;null
otherwise. -
port
If this is a hierarchical URI with an authority component that has a port portion, returns it;null
otherwise. -
device
If this is a hierarchical URI with a device component, returns it;null
otherwise. -
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
Returns an unmodifiable list containing the same segments as the array returned bysegments
. -
segmentCount
public int segmentCount()Returns the number of elements in the segment array that would be returned bysegments
. -
segment
Provides fast, indexed access to individual segments in the path segment array.- Throws:
IndexOutOfBoundsException
- ifi < 0
ori >= segmentCount()
.
-
lastSegment
Returns the last segment in the segment array, ornull
. -
path
If this is a hierarchical URI with a path, returns a string representation of the path;null
otherwise. The path consists of a leading segment separator character (a slash), if the path is absolute, followed by the slash-separated path segments. If this URI has a separate device component, it is not included in the path. -
devicePath
If this is a hierarchical URI with a path, returns a string representation of the path, including the authority and the device component;null
otherwise.If there is no authority, the format of this string is:
device/pathSegment1/pathSegment2...
If there is an authority, it is:
//authority/device/pathSegment1/pathSegment2...
For an archive URI, it's just:
authority/pathSegment1/pathSegment2...
-
query
If this is a hierarchical URI with a query component, returns it;null
otherwise. -
appendQuery
Returns the URI formed from this URI and the given query.- Throws:
IllegalArgumentException
- ifquery
is not a valid query (portion) according tovalidQuery
.
-
trimQuery
If this URI has a non-nullquery
, returns the URI formed by removing it; this URI unchanged, otherwise. -
fragment
If this URI has a fragment component, returns it;null
otherwise. -
appendFragment
Returns the URI formed from this URI and the given fragment.- Throws:
IllegalArgumentException
- iffragment
is not a valid fragment (portion) according tovalidFragment
.
-
trimFragment
If this URI has a non-nullfragment
, returns the URI formed by removing it; this URI unchanged, otherwise. -
resolve
Resolves this URI reference against abase
absolute hierarchical URI, returning the resulting absolute URI. If already absolute, the URI itself is returned. URI resolution is described in detail in section 5.2 of RFC 2396, "Resolving Relative References to Absolute Form."During resolution, empty segments, self references ("."), and parent references ("..") are interpreted, so that they can be removed from the path. Step 6(g) gives a choice of how to handle the case where parent references point to a path above the root: the offending segments can be preserved or discarded. This method preserves them. To have them discarded, please use the two-parameter form of
resolve
.- Throws:
IllegalArgumentException
- ifbase
is non-hierarchical or is relative.
-
resolve
Resolves this URI reference against abase
absolute hierarchical URI, returning the resulting absolute URI. If already absolute, the URI itself is returned. URI resolution is described in detail in section 5.2 of RFC 2396, "Resolving Relative References to Absolute Form."During resolution, empty segments, self references ("."), and parent references ("..") are interpreted, so that they can be removed from the path. Step 6(g) gives a choice of how to handle the case where parent references point to a path above the root: the offending segments can be preserved or discarded. This method can do either.
- Parameters:
preserveRootParents
-true
if segments referring to the parent of the root path are to be preserved;false
if they are to be discarded.- Throws:
IllegalArgumentException
- ifbase
is non-hierarchical or is relative.
-
deresolve
Finds the shortest relative or, if necessary, the absolute URI that, when resolved against the givenbase
absolute hierarchical URI usingresolve
, will yield this absolute URI. Ifbase
is non-hierarchical or is relative, orthis
is non-hierarchical or is relative,this
will be returned. -
deresolve
public URI deresolve(URI base, boolean preserveRootParents, boolean anyRelPath, boolean shorterRelPath) Finds an absolute URI that, when resolved against the givenbase
absolute hierarchical URI usingresolve
, will yield this absolute URI. Ifbase
is non-hierarchical or is relative, orthis
is non-hierarchical or is relative,this
will be returned.- Parameters:
preserveRootParents
- the boolean argument toresolve(URI, boolean)
for which the returned URI should resolve to this URI.anyRelPath
- iftrue
, the returned URI's path (if any) will be relative, if possible. Iffalse
, the form of the result's path will depend upon the next parameter.shorterRelPath
- ifanyRelPath
isfalse
and this parameter istrue
, 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 bothanyRelPath
and this parameter arefalse
, it will be absolute.
-
toString
Returns the string representation of this URI. For a generic, non-hierarchical URI, this looks like:scheme:opaquePart#fragment
For a hierarchical URI, it looks like:
scheme://authority/device/pathSegment1/pathSegment2...?query#fragment
For an archive URI, it's just:
scheme:authority/pathSegment1/pathSegment2...?query#fragment
Of course, absent components and their separators will be omitted.
-
toFileString
If this URI may refer directly to a locally accessible file, as determined byisFile
,decodes
and formats the URI as a pathname to that file; returns null otherwise.If there is no authority, the format of this string is:
device/pathSegment1/pathSegment2...
If there is an authority, it is:
//authority/device/pathSegment1/pathSegment2...
However, the character used as a separator is system-dependent and obtained from
File.separatorChar
. -
toPlatformString
If this is a platform URI, as determined byisPlatform()
, returns the workspace-relative or plug-in-based path to the resource, optionallydecoding
the segments in the process.- Since:
- org.eclipse.emf.common 2.3
- See Also:
-
appendSegment
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:
IllegalArgumentException
- ifsegment
is not a valid segment according tovalidSegment(java.lang.String)
.
-
appendSegments
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:
IllegalArgumentException
- ifsegments
is not a valid segment array according tovalidSegments(java.lang.String[])
.
-
trimSegments
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()Returnstrue
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
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
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:
IllegalArgumentException
- iffileExtension
is not a valid segment (portion) according tovalidSegment(java.lang.String)
.
-
trimFileExtension
If this URI has a non-nullfileExtension
, returns the URI formed by removing it; this URI unchanged, otherwise. -
isPrefix
public boolean isPrefix()Returnstrue
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
If this is a hierarchical URI reference andoldPrefix
is a prefix of it, this returns the URI formed by replacing it bynewPrefix
;null
otherwise.In order to be a prefix, the
oldPrefix
'sisPrefix
must returntrue
, and it must match this URI's scheme, authority, and device. Also, the paths must match, up to prefix's end.- Throws:
IllegalArgumentException
- if eitheroldPrefix
ornewPrefix
is not a prefix URI according toisPrefix()
.
-
encodeOpaquePart
Encodes a string so as to produce a valid opaque part value, as defined by the RFC. All excluded characters, such as space and#
, are escaped, as is/
if it is the first character.- Parameters:
ignoreEscaped
-true
to leave%
characters unescaped if they already begin a valid three-character escape sequence;false
to encode all%
characters. Note that if a%
is not followed by 2 hex digits, it will always be escaped.
-
encodeAuthority
Encodes a string so as to produce a valid authority, as defined by the RFC. All excluded characters, such as space and#
, are escaped, as are/
and?
- Parameters:
ignoreEscaped
-true
to leave%
characters unescaped if they already begin a valid three-character escape sequence;false
to encode all%
characters. Note that if a%
is not followed by 2 hex digits, it will always be escaped.
-
encodeSegment
Encodes a string so as to produce a valid segment, as defined by the RFC. All excluded characters, such as space and#
, are escaped, as are/
and?
- Parameters:
ignoreEscaped
-true
to leave%
characters unescaped if they already begin a valid three-character escape sequence;false
to encode all%
characters. Note that if a%
is not followed by 2 hex digits, it will always be escaped.
-
encodeQuery
Encodes a string so as to produce a valid query, as defined by the RFC. Only excluded characters, such as space and#
, are escaped.- Parameters:
ignoreEscaped
-true
to leave%
characters unescaped if they already begin a valid three-character escape sequence;false
to encode all%
characters. Note that if a%
is not followed by 2 hex digits, it will always be escaped.
-
encodeFragment
Encodes a string so as to produce a valid fragment, as defined by the RFC. Only excluded characters, such as space and#
, are escaped.- Parameters:
ignoreEscaped
-true
to leave%
characters unescaped if they already begin a valid three-character escape sequence;false
to encode all%
characters. Note that if a%
is not followed by 2 hex digits, it will always be escaped.
-
decode
Decodes the given string by interpreting three-digit escape sequences as the bytes of a UTF-8 encoded character and replacing them with the characters they represent. Incomplete escape sequences are ignored and invalid UTF-8 encoded bytes are treated as extended ASCII characters.
-
createURI
, which now has explicit device support enabled.