org.eclipse.emf.common.util

Class URI

java.lang.Object

org.eclipse.emf.common.util.URI

Direct Known Subclasses:

URI.Fragment, URI.Hierarchical, URI.Opaque

public abstract class URI
extends java.lang.Object

A representation of a Uniform Resource Identifier (URI), as specified by RFC 2396, with certain enhancements. A URI instance can be created by specifying values for its components, or by providing a single URI string, which is parsed into its components. Static factory methods whose names begin with "create" are used for both forms of object creation. No public or protected constructors are provided; this class can not be subclassed.

Like String, URI is an immutable class; a URI instance offers several by-value methods that return a new URI object based on its current state. Most useful, a relative URI can be resolved against a base absolute URI -- the latter typically identifies the document in which the former appears. The inverse to this is deresolve, which answers the question, "what relative URI will resolve, against the given base, to this absolute URI?"

In the RFC, much attention is focused on a hierarchical naming system used widely to locate resources via common protocols such as HTTP, FTP, and Gopher, and to identify files on a local file system. 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!

Nested Class Summary

Nested Classes

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.

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	URI(int hashCode)

Method Summary

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() Returns true if this is a current document reference with no fragment component; false otherwise.
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)
static void	main(java.lang.String[] args)
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() If this URI may refer directly to a locally accessible file, as determined by isFile, decodes and formats the URI as a pathname to that file; returns null otherwise.
java.lang.String	toPlatformString(boolean decode) If this is a platform URI, as determined by isPlatform(), returns the workspace-relative or plug-in-based path to the resource, optionally decoding the segments in the process.
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)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBUG

protected static final boolean DEBUG

See Also:

Constant Field Values

hashCode

protected int hashCode

The cached hash code of the URI. This is always equal to the hash code of Object.toString()

POOL

protected static final URI.URIPool POOL

A pool for managing URI instances.

ARCHIVE_SCHEMES

protected static final java.lang.String[] ARCHIVE_SCHEMES

SCHEME_FILE

protected static final java.lang.String SCHEME_FILE

See Also:

Constant Field Values

SCHEME_JAR

protected static final java.lang.String SCHEME_JAR

See Also:

Constant Field Values

SCHEME_ZIP

protected static final java.lang.String SCHEME_ZIP

See Also:

Constant Field Values

SCHEME_ARCHIVE

protected static final java.lang.String SCHEME_ARCHIVE

See Also:

Constant Field Values

SCHEME_PLATFORM

protected static final java.lang.String SCHEME_PLATFORM

See Also:

Constant Field Values

SCHEME_HTTP

protected static final java.lang.String SCHEME_HTTP

See Also:

Constant Field Values

SCHEME_FILE_HASH_CODE

protected static final int SCHEME_FILE_HASH_CODE

SCHEME_JAR_HASH_CODE

protected static final int SCHEME_JAR_HASH_CODE

SCHEME_ZIP_HASH_CODE

protected static final int SCHEME_ZIP_HASH_CODE

SCHEME_ARCHIVE_HASH_CODE

protected static final int SCHEME_ARCHIVE_HASH_CODE

SCHEME_PLATFORM_HASH_CODE

protected static final int SCHEME_PLATFORM_HASH_CODE

SCHEME_HTTP_HASH_CODE

protected static final int SCHEME_HTTP_HASH_CODE

SEGMENT_EMPTY

protected static final java.lang.String SEGMENT_EMPTY

See Also:

Constant Field Values

SEGMENT_SELF

protected static final java.lang.String SEGMENT_SELF

See Also:

Constant Field Values

SEGMENT_PARENT

protected static final java.lang.String SEGMENT_PARENT

See Also:

Constant Field Values

SEGMENT_PLUGIN

protected static final java.lang.String SEGMENT_PLUGIN

See Also:

Constant Field Values

SEGMENT_RESOURCE

protected static final java.lang.String SEGMENT_RESOURCE

See Also:

Constant Field Values

NO_SEGMENTS

protected static final java.lang.String[] NO_SEGMENTS

ONE_EMPTY_SEGMENT

protected static final java.lang.String[] ONE_EMPTY_SEGMENT

ONE_SELF_SEGMENT

protected static final java.lang.String[] ONE_SELF_SEGMENT

SCHEME_SEPARATOR

protected static final char SCHEME_SEPARATOR

See Also:

Constant Field Values

AUTHORITY_SEPARATOR

protected static final java.lang.String AUTHORITY_SEPARATOR

See Also:

Constant Field Values

AUTHORITY_SEPARATOR_HASH_CODE

protected static final int AUTHORITY_SEPARATOR_HASH_CODE

DEVICE_IDENTIFIER

protected static final char DEVICE_IDENTIFIER

See Also:

Constant Field Values

SEGMENT_SEPARATOR

protected static final char SEGMENT_SEPARATOR

See Also:

Constant Field Values

QUERY_SEPARATOR

protected static final char QUERY_SEPARATOR

See Also:

Constant Field Values

FRAGMENT_SEPARATOR

protected static final char FRAGMENT_SEPARATOR

See Also:

Constant Field Values

USER_INFO_SEPARATOR

protected static final char USER_INFO_SEPARATOR

See Also:

Constant Field Values

PORT_SEPARATOR

protected static final char PORT_SEPARATOR

See Also:

Constant Field Values

FILE_EXTENSION_SEPARATOR

protected static final char FILE_EXTENSION_SEPARATOR

See Also:

Constant Field Values

ARCHIVE_IDENTIFIER

protected static final char ARCHIVE_IDENTIFIER

See Also:

Constant Field Values

ARCHIVE_SEPARATOR

protected static final java.lang.String ARCHIVE_SEPARATOR

See Also:

Constant Field Values

ESCAPE

protected static final char ESCAPE

See Also:

Constant Field Values

HEX_DIGITS

protected static final char[] HEX_DIGITS

ALPHA_HI

protected static final long ALPHA_HI

ALPHA_LO

protected static final long ALPHA_LO

DIGIT_HI

protected static final long DIGIT_HI

DIGIT_LO

protected static final long DIGIT_LO

ALPHANUM_HI

protected static final long ALPHANUM_HI

ALPHANUM_LO

protected static final long ALPHANUM_LO

HEX_HI

protected static final long HEX_HI

HEX_LO

protected static final long HEX_LO

UNRESERVED_HI

protected static final long UNRESERVED_HI

UNRESERVED_LO

protected static final long UNRESERVED_LO

RESERVED_HI

protected static final long RESERVED_HI

RESERVED_LO

protected static final long RESERVED_LO

URIC_HI

protected static final long URIC_HI

URIC_LO

protected static final long URIC_LO

SEGMENT_CHAR_HI

protected static final long SEGMENT_CHAR_HI

SEGMENT_CHAR_LO

protected static final long SEGMENT_CHAR_LO

PATH_CHAR_HI

protected static final long PATH_CHAR_HI

PATH_CHAR_LO

protected static final long PATH_CHAR_LO

MAJOR_SEPARATOR_HI

protected static final long MAJOR_SEPARATOR_HI

MAJOR_SEPARATOR_LO

protected static final long MAJOR_SEPARATOR_LO

SEGMENT_END_HI

protected static final long SEGMENT_END_HI

SEGMENT_END_LO

protected static final long SEGMENT_END_LO

PLATFORM_SEGMENT_RESERVED_HI

protected static final long PLATFORM_SEGMENT_RESERVED_HI

PLATFORM_SEGMENT_RESERVED_LO

protected static final long PLATFORM_SEGMENT_RESERVED_LO

ENCODE_PLATFORM_RESOURCE_URIS

protected static final boolean ENCODE_PLATFORM_RESOURCE_URIS

FRAGMENT_NONE

public static final int FRAGMENT_NONE

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

See Also:

createURI(String, boolean, int), Constant Field Values

FRAGMENT_FIRST_SEPARATOR

public static final int FRAGMENT_FIRST_SEPARATOR

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

See Also:

createURI(String, boolean, int), Constant Field Values

FRAGMENT_LAST_SEPARATOR

public static final int FRAGMENT_LAST_SEPARATOR

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

See Also:

createURI(String, boolean, int), Constant Field Values

Constructor Detail

URI

protected URI(int hashCode)

Method Detail

lowBitmask

protected static long lowBitmask(char c)

highBitmask

protected static long highBitmask(char c)

lowBitmask

protected static long lowBitmask(char from,
                                 char to)

highBitmask

protected static long highBitmask(char from,
                                  char to)

lowBitmask

protected static long lowBitmask(java.lang.String chars)

highBitmask

protected static long highBitmask(java.lang.String chars)

matches

protected static boolean matches(char c,
                                 long highBitmask,
                                 long lowBitmask)

createGenericURI

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

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

Throws:

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

createHierarchicalURI

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

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

Throws:

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

createHierarchicalURI

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

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

Parameters:

segments - an array of non-null strings, each representing one segment of the path. As an absolute path, it is automatically preceded by a / separator. If desired, a trailing separator should be represented by an empty-string segment as the last element of the array.

Throws:

java.lang.IllegalArgumentException - if scheme is an archive URI scheme and device is non-null, or if scheme, authority, device, segments, query, or fragment is not valid according to validScheme, validAuthority or validArchiveAuthority, validDevice, validSegments, validQuery, or validFragment, as appropriate.

createHierarchicalURI

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

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

Parameters:

segments - an array of non-null strings, each representing one segment of the path. A trailing separator is represented by an empty-string segment at the end of the array.

Throws:

java.lang.IllegalArgumentException - if segments, query, or fragment is not valid according to validSegments, validQuery, or validFragment, respectively.

createURI

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

Static factory method based on parsing a URI string, with explicit device support and handling for archive URIs enabled. The specified string is parsed as described in RFC 2396, and an appropriate URI is created and returned. Note that validity testing is not as strict as in the RFC; essentially, only separator characters are considered. 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:

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

createURI

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

Static factory method that encodes and parses the given URI string. Appropriate encoding is performed for each component of the URI. If more than one # is in the string, the last one is assumed to be the fragment's separator, and any others are encoded. 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 specify false to perform ordinary encoding.

Throws:

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

createURI

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

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

Throws:

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

createDeviceURI

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

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

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

Throws:

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

createURIWithCache

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

Deprecated. Please use createURI instead.

This method was included in the public API by mistake.

createFileURI

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

Static factory method based on parsing a File path string. The pathname may be either absolute or relative. A relative path should be avoided and can be converted to an absolute path using new File(pathname).getAbsolutePath().

• An absolute path is converted into an appropriate form starting with "file:" scheme, followed by a /, if pathname doesn't start with a platform-specific separator, followed by the pathname modified to use / as the separator and modified to encode the segments.
• A relative path is converted into an appropriate form simply by modifying the pathname to use / as the separator and modifying the segments to encode them.

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.

Callers are generally recommended to call this method using URI.createFileURI(new File(pathname).getAbsolutePath()) for the following reasons:

• On Windows, a relative path with a specified device, e.g., C:myfile.txt</code>, cannot be expressed as a valid file URI.
• On Windows, C:/myfile.text is an absolute path, but on a Unix-style file system, it is a relative path.
• On Windows, /myfile.text is a relative path, but on a Unix-style file system, it is an absolute path.

Furthermore, any application that uses a relative URI to locate some associated resource will generally map the relative URI to an absolute URI in some manner, likely depending on the system's state, e.g., the current user directory that can change over time, exactly as is the case for new File(path).getAbsolutePath(). Not only that, when an accessed resource itself contains URIs, the general XML interpretation of any such contained relative URI is to resolve it to an absolute URI based on the absolute URI of the containing resource; that resolution isn't possible (well-defined) unless the base URI of the resource is an absolute URI.

Throws:

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

createPlatformResourceURI

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

Deprecated. Use createPlatformResourceURI(String, boolean) instead.

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

The pathName must be of the form:

   /project-name/path

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

   platform:/resource/project-name/path

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

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

Throws:

java.lang.IllegalArgumentException - if any component parsed from the path is not valid according to validDevice, validSegments, validQuery, or validFragment.

See Also:

org.eclipse.core.runtime.Platform#resolve, createPlatformResourceURI(String, boolean)

createPlatformResourceURI

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

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

The pathName must be of the form:

   /project-name/path

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

   platform:/resource/project-name/path

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

Depending on the encode argument, the path may be automatically encoded to escape all spaces, # characters, and other characters disallowed in URIs, as well as ?, which would delimit a path from a query. Decoding can be performed with the static decode method. It is strongly recommended to specify true to enable encoding, unless the path string has already been encoded.

Throws:

java.lang.IllegalArgumentException - if any component parsed from the path is not valid according to validDevice, validSegments, validQuery, or validFragment.

See Also:

org.eclipse.core.runtime.Platform#resolve

createPlatformPluginURI

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

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

The pathName must be of the form:

   /plugin-id/path

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

   platform:/plugin/plugin-id/path

This scheme supports relocatable plug-in content in Eclipse.

Depending on the encode argument, the path may be automatically encoded to escape all spaces, # characters, and other characters disallowed in URIs, as well as ?, which would delimit a path from a query. Decoding can be performed with the static decode method. It is strongly recommended to specify true to enable encoding, unless the path string has already been encoded.

Throws:

java.lang.IllegalArgumentException - if any component parsed from the path is not valid according to validDevice, validSegments, validQuery, or validFragment.

Since:

org.eclipse.emf.common 2.3

See Also:

org.eclipse.core.runtime.Platform#resolve

splitInternFragment

protected static java.lang.CharSequence splitInternFragment(java.lang.String fragment)

validateURI

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)

validScheme

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

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

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

validOpaquePart

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

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

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

validAuthority

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

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

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

validArchiveAuthority

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

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

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

validJarAuthority

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

Deprecated. As of EMF 2.0, replaced by validArchiveAuthority.

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

validDevice

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

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

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

validSegment

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

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

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

validSegments

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

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

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

firstInvalidSegment

protected static java.lang.String firstInvalidSegment(java.lang.String[] value)

validQuery

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

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

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

validFragment

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

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

A fragment is taken to be unconditionally valid.

contains

protected static boolean contains(java.lang.String s,
                                  long highBitmask,
                                  long lowBitmask)

flushCachedString

protected void flushCachedString()

cacheString

protected void cacheString(java.lang.String string)

getCachedString

protected java.lang.String getCachedString()

isRelative

public boolean isRelative()

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

isBase

protected boolean isBase()

isHierarchical

public boolean isHierarchical()

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

hasAuthority

public boolean hasAuthority()

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

hasOpaquePart

public boolean hasOpaquePart()

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

hasDevice

public boolean hasDevice()

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

hasDeviceOrPath

protected boolean hasDeviceOrPath()

hasPath

public boolean hasPath()

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

hasAbsolutePath

public boolean hasAbsolutePath()

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

hasRelativePath

public boolean hasRelativePath()

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

hasEmptyPath

public boolean hasEmptyPath()

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

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

hasQuery

public boolean hasQuery()

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

hasFragment

public boolean hasFragment()

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

isCurrentDocumentReference

public boolean isCurrentDocumentReference()

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

isEmpty

public boolean isEmpty()

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

See Also:

isCurrentDocumentReference()

isFile

public boolean isFile()

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

isPlatform

public boolean isPlatform()

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

Since:

org.eclipse.emf.common 2.3

isPlatformResource

public boolean isPlatformResource()

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

Since:

org.eclipse.emf.common 2.3

See Also:

isPlatform()

isPlatformPlugin

public boolean isPlatformPlugin()

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

Since:

org.eclipse.emf.common 2.3

See Also:

isPlatform()

isArchive

public boolean isArchive()

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

isArchiveScheme

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

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

hashCode

public int hashCode()

Returns the hash code.

Overrides:

hashCode in class java.lang.Object

segmentsEqual

protected boolean segmentsEqual(URI uri)

equals

protected static boolean equals(java.lang.Object o1,
                                java.lang.Object o2)

scheme

public java.lang.String scheme()

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

opaquePart

public java.lang.String opaquePart()

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

authority

public java.lang.String authority()

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

userInfo

public java.lang.String userInfo()

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

host

public java.lang.String host()

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

port

public java.lang.String port()

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

device

public java.lang.String device()

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

segments

public java.lang.String[] segments()

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

rawSegments

protected java.lang.String[] rawSegments()

segmentsList

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

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

segmentCount

public int segmentCount()

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

segment

public java.lang.String segment(int i)

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

Throws:

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

lastSegment

public java.lang.String lastSegment()

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

path

public java.lang.String path()

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

devicePath

public java.lang.String devicePath()

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

If there is no authority, the format of this string is:

   device/pathSegment1/pathSegment2...

If there is an authority, it is:

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

For an archive URI, it's just:

   authority/pathSegment1/pathSegment2...

query

public java.lang.String query()

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

appendQuery

public URI appendQuery(java.lang.String query)

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

Throws:

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

trimQuery

public URI trimQuery()

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

fragment

public java.lang.String fragment()

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

appendFragment

public URI appendFragment(java.lang.String fragment)

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

Throws:

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

rawAppendFragment

protected URI rawAppendFragment(java.lang.CharSequence fragment)

trimFragment

public URI trimFragment()

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

resolve

public URI resolve(URI base)

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

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

Throws:

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

resolve

public URI resolve(URI base,
                   boolean preserveRootParents)

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

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

Parameters:

preserveRootParents - true if segments referring to the parent of the root path are to be preserved; false if they are to be discarded.

Throws:

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

deresolve

public URI deresolve(URI base)

Finds the shortest relative or, if necessary, the absolute URI that, when resolved against the given base absolute hierarchical URI using resolve, will yield this absolute URI. If base is non-hierarchical or is relative, or this 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 given 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.

Parameters:

preserveRootParents - the boolean argument to resolve(URI, boolean) for which the returned URI should resolve to this URI.

anyRelPath - if true, the returned URI's path (if any) will be relative, if possible. If false, the form of the result's path will depend upon the next parameter.

shorterRelPath - if anyRelPath is false and this parameter is true, the returned URI's path (if any) will be relative, if one can be found that is no longer (by number of segments) than the absolute path. If both anyRelPath and this parameter are false, it will be absolute.

collapseSegments

protected java.lang.String[] collapseSegments(boolean preserveRootParents)

matches

protected boolean matches(java.lang.String string)

matches

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)

matches

protected boolean matches(java.lang.String base,
                          java.lang.String path)

toFileString

public java.lang.String toFileString()

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

If there is no authority, the format of this string is:

   device/pathSegment1/pathSegment2...

If there is an authority, it is:

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

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

toPlatformString

public java.lang.String toPlatformString(boolean decode)

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

Since:

org.eclipse.emf.common 2.3

See Also:

createPlatformResourceURI(String, boolean), createPlatformPluginURI(java.lang.String, boolean)

appendSegment

public URI appendSegment(java.lang.String segment)

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

Throws:

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

appendSegments

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

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

Parameters:

segments - an array of non-null strings, each representing one segment of the path. If desired, a trailing separator should be represented by an empty-string segment as the last element of the array.

Throws:

java.lang.IllegalArgumentException - if segments is not a valid segment array according to validSegments(java.lang.String[]).

trimSegments

public URI trimSegments(int i)

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

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

Parameters:

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

hasTrailingPathSeparator

public boolean hasTrailingPathSeparator()

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

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

fileExtension

public java.lang.String fileExtension()

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

appendFileExtension

public URI appendFileExtension(java.lang.String fileExtension)

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

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

Throws:

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

trimFileExtension

public URI trimFileExtension()

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

isPrefix

public boolean isPrefix()

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

replacePrefix

public URI replacePrefix(URI oldPrefix,
                         URI newPrefix)

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

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

Throws:

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

encodeOpaquePart

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

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

Parameters:

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

encodeAuthority

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

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

Parameters:

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

encodeSegment

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

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

Parameters:

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

encodeQuery

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

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

Parameters:

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

encodeFragment

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

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

Parameters:

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

encodeURI

protected static java.lang.String encodeURI(java.lang.String uri,
                                            boolean ignoreEscaped,
                                            int fragmentLocationStyle)

encode

protected static java.lang.String encode(java.lang.String value,
                                         long highBitmask,
                                         long lowBitmask,
                                         boolean ignoreEscaped)

isEscaped

protected static boolean isEscaped(java.lang.String s,
                                   int i)

appendEscaped

protected static void appendEscaped(java.lang.StringBuffer result,
                                    byte b)

decode

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

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

unescape

protected static char unescape(char highHexDigit,
                               char lowHexDigit)

valueOf

protected static int valueOf(char hexDigit)

main

public static void main(java.lang.String[] args)