Reference (Restlet core org.restlet 3.0 Milestone 1

java.lang.Object
- org.restlet.data.Reference

Direct Known Subclasses:

LocalReference
```
public class Reference
extends Object
```
Reference to a Uniform Resource Identifier (URI). Contrary to the java.net.URI class, this interface represents mutable references. It strictly conforms to the RFC 3986 specifying URIs and follow its naming conventions.
```
 URI reference        = absolute-reference | relative-reference
 
 absolute-reference   = scheme ":" scheme-specific-part [ "#" fragment ]
 scheme-specific-part = ( hierarchical-part [ "?" query ] ) | opaque-part
 hierarchical-part    = ( "//" authority path-abempty ) | path-absolute | path-rootless | path-empty
 authority            = [ user-info "@" ] host-domain [ ":" host-port ]
 
 relative-reference   = relative-part [ "?" query ] [ "#" fragment ]
 relative-part        = ( "//" authority path-abempty ) | path-absolute | path-noscheme | path-empty
 
 path-abempty         = begins with "/" or is empty
 path-absolute        = begins with "/" but not "//"
 path-noscheme        = begins with a non-colon segment
 path-rootless        = begins with a segment
 path-empty           = zero characters
 
```
Note that this class doesn't encode or decode the reserved characters. It assumes that the URIs or the URI parts passed in are properly encoded using the standard URI encoding mechanism. You can use the static "encode()" and "decode()" methods for this purpose. Note that if an invalid URI character is detected by the constructor or one of the setters, a trace will be logged and the character will be automatically encoded.

The fundamental point to underline is the difference between an URI "reference" and an URI. Contrary to an URI (the target identifier of a REST resource), an URI reference can be relative (with or without query and fragment part). This relative URI reference can then be resolved against a base reference via the getTargetRef() method which will return a new resolved Reference instance, an absolute URI reference with no base reference and with no dot-segments (the path segments "." and "..").

You can also apply the getTargetRef() method on absolute references in order to solve the dot-segments. Note that applying the getRelativeRef() method on an absolute reference returns the current reference relatively to a base reference, if any, and solves the dot-segments.

The Reference stores its data as a single string, the one passed to the constructor. This string can always be obtained using the toString() method. A couple of integer indexes are maintained to improve the extraction time of various reference properties (URI components).

When you modify a specific component of the URI reference, via the setPath() method for example, the internal string is simply regenerated by updating only the relevant part. We try as much as possible to protect the bytes given to the Reference class instead of transparently parsing and normalizing the URI data. Our idea is to protect encodings and special characters in all case and reduce the memory size taken by this class while making Reference instances mutable.

Because the base reference is only a property of the Reference ("baseRef"). When you use the "Reference(base, path)" constructor, it is equivalent to doing:
ref = new Reference(path);
ref.setBaseRef(base);

The base ref is not automatically resolved or "merged" with the rest of the reference information (the path here). For example, this let's you reuse a single reference as the base of several relative references. If you modify the base reference, all relative references are still accurate.
Note that the name and value properties are thread safe, stored in volatile members.
Author:

Jerome Louvel

See Also:
RFC 3986

Constructor Summary

Constructors
Constructor and Description
`Reference()` Empty constructor.
`Reference(Protocol protocol, String hostName)` Constructor for a protocol and host name.
`Reference(Protocol protocol, String hostName, int hostPort)` Constructor for a protocol, host name and host port
`Reference(Reference ref)` Clone constructor.
`Reference(Reference baseRef, Reference uriReference)` Constructor from an URI reference (most likely relative).
`Reference(Reference baseRef, String uriRef)` Constructor from an URI reference (most likely relative).
`Reference(Reference baseRef, String relativePart, String query, String fragment)` Constructor of relative reference from its parts.
`Reference(String uriReference)` Constructor from an URI reference.
`Reference(String identifier, String fragment)` Constructor from an identifier and a fragment.
`Reference(String scheme, String hostName, int hostPort, String path, String query, String fragment)` Constructor of absolute reference from its parts.
`Reference(URI uri)` Constructor from an `URI` instance.
`Reference(URI baseUri, URI uri)` Constructor from an `URI` instance.
`Reference(URL url)` Constructor from an `URL` instance.

Method Summary

Methods
Modifier and Type	Method and Description
`Reference`	`addQueryParameter(Parameter parameter)` Adds a parameter to the query component.
`Reference`	`addQueryParameter(String name, String value)` Adds a parameter to the query component.
`Reference`	`addQueryParameters(Iterable<Parameter> parameters)` Adds several parameters to the query component.
`Reference`	`addSegment(String value)` Adds a segment at the end of the path.
`Reference`	`clone()`
`static String`	`decode(String toDecode)` Decodes a given string using the standard URI encoding mechanism and the UTF-8 character set.
`static String`	`decode(String toDecode, CharacterSet characterSet)` Decodes a given string using the standard URI encoding mechanism.
`static String`	`encode(String toEncode)` Encodes a given string using the standard URI encoding mechanism and the UTF-8 character set.
`static String`	`encode(String toEncode, boolean queryString)` Encodes a given string using the standard URI encoding mechanism and the UTF-8 character set.
`static String`	`encode(String toEncode, boolean queryString, CharacterSet characterSet)` Encodes a given string using the standard URI encoding mechanism and the UTF-8 character set.
`static String`	`encode(String toEncode, CharacterSet characterSet)` Encodes a given string using the standard URI encoding mechanism.
`boolean`	`equals(Object object)` Indicates whether some other object is "equal to" this one.
`String`	`getAuthority()` Returns the authority component for hierarchical identifiers.
`String`	`getAuthority(boolean decode)` Returns the optionnally decoded authority component.
`Reference`	`getBaseRef()` Returns the base reference for relative references.
`String`	`getExtensions()` Returns the optional extensions for hierarchical identifiers.
`String[]`	`getExtensionsAsArray()` Returns the extensions as an array or null if no extension is found.
`String`	`getFragment()` Returns the fragment identifier. Note that no URI decoding is done by this method.
`String`	`getFragment(boolean decode)` Returns the optionnally decoded fragment identifier.
`String`	`getHierarchicalPart()` Returns the hierarchical part which is equivalent to the scheme specific part less the query component. Note that no URI decoding is done by this method.
`String`	`getHierarchicalPart(boolean decode)` Returns the optionnally decoded hierarchical part.
`String`	`getHostDomain()` Returns the host domain name component for server based hierarchical identifiers.
`String`	`getHostDomain(boolean decode)` Returns the optionnally decoded host domain name component.
`String`	`getHostIdentifier()` Returns the host identifier.
`String`	`getHostIdentifier(boolean decode)` Returns the optionnally decoded host identifier.
`int`	`getHostPort()` Returns the optional port number for server based hierarchical identifiers.
`String`	`getIdentifier()` Returns the absolute resource identifier, without the fragment. Note that no URI decoding is done by this method.
`String`	`getIdentifier(boolean decode)` Returns the optionnally decoded absolute resource identifier.
`String`	`getLastSegment()` Returns the last segment of a hierarchical path. For example the "/a/b/c" and "/a/b/c/" paths have the same segments: "a", "b", "c. Note that no URI decoding is done by this method.
`String`	`getLastSegment(boolean decode)` Returns the optionnally decoded last segment.
`String`	`getLastSegment(boolean decode, boolean excludeMatrix)` Returns the optionnally decoded last segment.
`String`	`getMatrix()` Returns the optional matrix for hierarchical identifiers.
`String`	`getMatrix(boolean decode)` Returns the optionnally decoded matrix.
`Form`	`getMatrixAsForm()` Returns the optional matrix as a form.
`Form`	`getMatrixAsForm(CharacterSet characterSet)` Returns the optional matrix as a form submission.
`Reference`	`getParentRef()` Returns the parent reference of a hierarchical reference.
`String`	`getPath()` Returns the path component for hierarchical identifiers.
`String`	`getPath(boolean decode)` Returns the optionnally decoded path component.
`String`	`getQuery()` Returns the optional query component for hierarchical identifiers. Note that no URI decoding is done by this method.
`String`	`getQuery(boolean decode)` Returns the optionnally decoded query component.
`Form`	`getQueryAsForm()` Returns the optional query component as a form.
`Form`	`getQueryAsForm(boolean decode)` Returns the optional query component as a form.
`Form`	`getQueryAsForm(CharacterSet characterSet)` Returns the optional query component as a form submission.
`String`	`getRelativePart()` Returns the relative part of relative references, without the query and fragment.
`String`	`getRelativePart(boolean decode)` Returns the optionnally decoded relative part.
`Reference`	`getRelativeRef()` Returns the current reference as a relative reference to the current base reference.
`Reference`	`getRelativeRef(Reference base)` Returns the current reference relatively to a base reference.
`String`	`getRemainingPart()` Returns the part of the resource identifier remaining after the base reference.
`String`	`getRemainingPart(boolean decode)` Returns the optionally decoded remaining part.
`String`	`getRemainingPart(boolean decode, boolean query)` Returns the optionally decoded remaining part with or without the query part of the reference.
`String`	`getScheme()` Returns the scheme component. Note that no URI decoding is done by this method.
`String`	`getScheme(boolean decode)` Returns the optionnally decoded scheme component.
`Protocol`	`getSchemeProtocol()` Returns the protocol associated with the scheme component.
`String`	`getSchemeSpecificPart()` Returns the scheme specific part. Note that no URI decoding is done by this method.
`String`	`getSchemeSpecificPart(boolean decode)` Returns the optionnally decoded scheme specific part.
`List<String>`	`getSegments()` Returns the list of segments in a hierarchical path. A new list is created for each call. Note that no URI decoding is done by this method.
`List<String>`	`getSegments(boolean decode)` Returns the optionnally decoded list of segments.
`Reference`	`getTargetRef()` Returns the target reference.
`String`	`getUserInfo()` Returns the user info component for server based hierarchical identifiers. Note that no URI decoding is done by this method.
`String`	`getUserInfo(boolean decode)` Returns the optionnally decoded user info component.
`boolean`	`hasExtensions()` Indicates if this reference has file-like extensions on its last path segment.
`boolean`	`hasFragment()` Indicates if this reference has a fragment identifier.
`int`	`hashCode()` Returns a hash code value for the object.
`boolean`	`hasMatrix()` Indicates if this reference has a matrix.
`boolean`	`hasQuery()` Indicates if this reference has a query component.
`boolean`	`hasScheme()` Indicates if this reference has a scheme component.
`boolean`	`isAbsolute()` Indicates if the reference is absolute.
`boolean`	`isEquivalentTo(Reference ref)` Returns true if both reference are equivalent, meaning that they resolve to the same target reference.
`static boolean`	`isGenericDelimiter(int character)` Indicates if the given character is a generic URI component delimiter character.
`boolean`	`isHierarchical()` Indicates if the identifier is hierarchical.
`boolean`	`isOpaque()` Indicates if the identifier is opaque.
`boolean`	`isParent(Reference childRef)` Indicates if the reference is a parent of the hierarchical child reference.
`boolean`	`isRelative()` Indicates if the reference is relative.
`static boolean`	`isReserved(int character)` Indicates if the given character is a reserved URI character.
`static boolean`	`isSubDelimiter(int character)` Indicates if the given character is an URI subcomponent delimiter character.
`static boolean`	`isUnreserved(int character)` Indicates if the given character is an unreserved URI character.
`static boolean`	`isValid(int character)` Indicates if the given character is a valid URI character.
`Reference`	`normalize()` Normalizes the reference.
`void`	`setAuthority(String authority)` Sets the authority component for hierarchical identifiers.
`void`	`setBaseRef(Reference baseRef)` Sets the base reference for relative references.
`void`	`setBaseRef(String baseUri)` Sets the base reference for relative references.
`void`	`setExtensions(String extensions)` Sets the extensions for hierarchical identifiers.
`void`	`setExtensions(String[] extensions)` Sets the extensions based on an array of extension tokens (without dots).
`void`	`setFragment(String fragment)` Sets the fragment identifier.
`void`	`setHostDomain(String domain)` Sets the host domain component for server based hierarchical identifiers.
`void`	`setHostPort(Integer port)` Sets the optional port number for server based hierarchical identifiers.
`void`	`setIdentifier(String identifier)` Sets the absolute resource identifier.
`void`	`setLastSegment(String lastSegment)` Sets the last segment of the path.
`void`	`setPath(String path)` Sets the path component for hierarchical identifiers.
`void`	`setProtocol(Protocol protocol)` Sets the scheme component based on this protocol.
`void`	`setQuery(String query)` Sets the query component for hierarchical identifiers.
`void`	`setRelativePart(String relativePart)` Sets the relative part for relative references only.
`void`	`setScheme(String scheme)` Sets the scheme component.
`void`	`setSchemeSpecificPart(String schemeSpecificPart)` Sets the scheme specific part.
`void`	`setSegments(List<String> segments)` Sets the segments of a hierarchical path. A new absolute path will replace any existing one.
`void`	`setUserInfo(String userInfo)` Sets the user info component for server based hierarchical identifiers.
`String`	`toString()` Returns the reference as an URI string.
`String`	`toString(boolean query, boolean fragment)` Returns the URI reference string.
`static String`	`toString(String scheme, String hostName, Integer hostPort, String path, String query, String fragment)` Creates a reference string from its parts.
`static String`	`toString(String relativePart, String query, String fragment)` Creates a relative reference string from its parts.
`static String`	`toString(String scheme, String host, String path, String query, String fragment)` Creates a reference string from its parts.
`URI`	`toUri()` Converts to a `URI` instance.
`URL`	`toUrl()` Converts to a `URL` instance.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Reference
```
public Reference()
```
    Empty constructor.
  - Reference
```
public Reference(URI uri)
```
    Constructor from an URI instance.
    
    Parameters:
    uri - The URI instance.
  - Reference
```
public Reference(URI baseUri,
         URI uri)
```
    Constructor from an URI instance.
    
    Parameters:
    baseUri - The base URI instance.
    uri - The URI instance.
  - Reference
```
public Reference(URL url)
```
    Constructor from an URL instance.
    
    Parameters:
    url - The URL instance.
  - Reference
```
public Reference(Protocol protocol,
         String hostName)
```
    Constructor for a protocol and host name. Uses the default port for the given protocol.
    
    Parameters:
    protocol - Protocol/scheme to use
    hostName - The host name or IP address.
  - Reference
```
public Reference(Protocol protocol,
         String hostName,
         int hostPort)
```
    Constructor for a protocol, host name and host port
    
    Parameters:
    protocol - Protocol/scheme to use
    hostName - The host name or IP address.
    hostPort - The host port (default ports are correctly ignored).
  - Reference
```
public Reference(Reference ref)
```
    Clone constructor.
    
    Parameters:
    ref - The reference to clone.
  - Reference
```
public Reference(Reference baseRef,
         Reference uriReference)
```
    Constructor from an URI reference (most likely relative).
    
    Parameters:
    baseRef - The base reference.
    uriReference - The URI reference, either absolute or relative.
  - Reference
```
public Reference(Reference baseRef,
         String uriRef)
```
    Constructor from an URI reference (most likely relative).
    
    Parameters:
    baseRef - The base reference.
    uriRef - The URI reference, either absolute or relative.
  - Reference
```
public Reference(Reference baseRef,
         String relativePart,
         String query,
         String fragment)
```
    Constructor of relative reference from its parts.
    
    Parameters:
    baseRef - The base reference.
    relativePart - The relative part component (most of the time it is the path component).
    query - The optional query component for hierarchical identifiers.
    fragment - The optional fragment identifier.
  - Reference
```
public Reference(String uriReference)
```
    Constructor from an URI reference.
    
    Parameters:
    uriReference - The URI reference, either absolute or relative.
  - Reference
```
public Reference(String identifier,
         String fragment)
```
    Constructor from an identifier and a fragment.
    
    Parameters:
    identifier - The resource identifier.
    fragment - The fragment identifier.
  - Reference
```
public Reference(String scheme,
         String hostName,
         int hostPort,
         String path,
         String query,
         String fragment)
```
    Constructor of absolute reference from its parts.
    
    Parameters:
    scheme - The scheme ("http", "https" or "ftp").
    hostName - The host name or IP address.
    hostPort - The host port (default ports are correctly ignored).
    path - The path component for hierarchical identifiers.
    query - The optional query component for hierarchical identifiers.
    fragment - The optional fragment identifier.
- Method Detail
  - decode
```
public static String decode(String toDecode)
```
    Decodes a given string using the standard URI encoding mechanism and the UTF-8 character set.
    
    Parameters:
    toDecode - The string to decode.
    
    Returns:
    The decoded string.
  - decode
```
public static String decode(String toDecode,
            CharacterSet characterSet)
```
    Decodes a given string using the standard URI encoding mechanism. If the provided character set is null, the string is returned but not decoded. Note: The World Wide Web Consortium Recommendation states that UTF-8 should be used. Not doing so may introduce incompatibilities.
    
    Parameters:
    toDecode - The string to decode.
    characterSet - The name of a supported character encoding.
    
    Returns:
    The decoded string or null if the named character encoding is not supported.
  - encode
```
public static String encode(String toEncode)
```
    Encodes a given string using the standard URI encoding mechanism and the UTF-8 character set.
    
    Parameters:
    toEncode - The string to encode.
    
    Returns:
    The encoded string.
  - encode
```
public static String encode(String toEncode,
            boolean queryString)
```
    Encodes a given string using the standard URI encoding mechanism and the UTF-8 character set. Useful to prevent the usage of '+' to encode spaces (%20 instead). The '*' characters are encoded as %2A and %7E are replaced by '~'.
    
    Parameters:
    toEncode - The string to encode.
    queryString - True if the string to encode is part of a query string instead of a HTML form post.
    
    Returns:
    The encoded string.
  - encode
```
public static String encode(String toEncode,
            boolean queryString,
            CharacterSet characterSet)
```
    Encodes a given string using the standard URI encoding mechanism and the UTF-8 character set. Useful to prevent the usage of '+' to encode spaces (%20 instead). The '*' characters are encoded as %2A and %7E are replaced by '~'.
    
    Parameters:
    toEncode - The string to encode.
    queryString - True if the string to encode is part of a query string instead of a HTML form post.
    characterSet - The supported character encoding.
    
    Returns:
    The encoded string.
  - encode
```
public static String encode(String toEncode,
            CharacterSet characterSet)
```
    Encodes a given string using the standard URI encoding mechanism. If the provided character set is null, the string is returned but not encoded. Note: The World Wide Web Consortium Recommendation states that UTF-8 should be used. Not doing so may introduce incompatibilities.
    
    Parameters:
    toEncode - The string to encode.
    characterSet - The supported character encoding.
    
    Returns:
    The encoded string or null if the named character encoding is not supported.
  - isGenericDelimiter
```
public static boolean isGenericDelimiter(int character)
```
    Indicates if the given character is a generic URI component delimiter character.
    
    Parameters:
    character - The character to test.
    
    Returns:
    True if the given character is a generic URI component delimiter character.
  - isReserved
```
public static boolean isReserved(int character)
```
    Indicates if the given character is a reserved URI character.
    
    Parameters:
    character - The character to test.
    
    Returns:
    True if the given character is a reserved URI character.
  - isSubDelimiter
```
public static boolean isSubDelimiter(int character)
```
    Indicates if the given character is an URI subcomponent delimiter character.
    
    Parameters:
    character - The character to test.
    
    Returns:
    True if the given character is an URI subcomponent delimiter character.
  - isUnreserved
```
public static boolean isUnreserved(int character)
```
    Indicates if the given character is an unreserved URI character.
    
    Parameters:
    character - The character to test.
    
    Returns:
    True if the given character is an unreserved URI character.
  - isValid
```
public static boolean isValid(int character)
```
    Indicates if the given character is a valid URI character.
    
    Parameters:
    character - The character to test.
    
    Returns:
    True if the given character is a valid URI character.
  - toString
```
public static String toString(String scheme,
              String hostName,
              Integer hostPort,
              String path,
              String query,
              String fragment)
```
    Creates a reference string from its parts.
    
    Parameters:
    scheme - The scheme ("http", "https" or "ftp").
    hostName - The host name or IP address.
    hostPort - The host port (default ports are correctly ignored).
    path - The path component for hierarchical identifiers.
    query - The optional query component for hierarchical identifiers.
    fragment - The optional fragment identifier.
    
    Returns:
    The reference as String.
  - toString
```
public static String toString(String relativePart,
              String query,
              String fragment)
```
    Creates a relative reference string from its parts.
    
    Parameters:
    relativePart - The relative part component.
    query - The optional query component for hierarchical identifiers.
    fragment - The optional fragment identifier.
    
    Returns:
    The relative reference as a String.
  - toString
```
public static String toString(String scheme,
              String host,
              String path,
              String query,
              String fragment)
```
    Creates a reference string from its parts.
    
    Parameters:
    scheme - The scheme ("http", "https" or "ftp").
    host - The host name or IP address plus the optional port number.
    path - The path component for hierarchical identifiers.
    query - The optional query component for hierarchical identifiers.
    fragment - The optional fragment identifier.
    
    Returns:
    The reference a String.
  - addQueryParameter
```
public Reference addQueryParameter(Parameter parameter)
```
    Adds a parameter to the query component. The name and value are automatically URL encoded if necessary.
    
    Parameters:
    parameter - The parameter to add.
    
    Returns:
    The updated reference.
  - addQueryParameter
```
public Reference addQueryParameter(String name,
                          String value)
```
    Adds a parameter to the query component. The name and value are automatically URL encoded if necessary.
    
    Parameters:
    name - The parameter name.
    value - The optional parameter value.
    
    Returns:
    The updated reference.
  - addQueryParameters
```
public Reference addQueryParameters(Iterable<Parameter> parameters)
```
    Adds several parameters to the query component. The name and value are automatically URL encoded if necessary.
    
    Parameters:
    parameters - The parameters to add.
    
    Returns:
    The updated reference.
  - addSegment
```
public Reference addSegment(String value)
```
    Adds a segment at the end of the path. If the current path doesn't end with a slash character, one is inserted before the new segment value. The value is automatically encoded if necessary.
    
    Parameters:
    value - The segment value to add.
    
    Returns:
    The updated reference.
  - clone
```
public Reference clone()
```
    Overrides:
    
    clone in class Object
  - equals
```
public boolean equals(Object object)
```
    Indicates whether some other object is "equal to" this one.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    object - The object to compare to.
    
    Returns:
    True if this object is the same as the obj argument.
  - getAuthority
```
public String getAuthority()
```
    Returns the authority component for hierarchical identifiers. Includes the user info, host name and the host port number.
    Note that no URI decoding is done by this method.
    
    Returns:
    The authority component for hierarchical identifiers.
  - getAuthority
```
public String getAuthority(boolean decode)
```
    Returns the optionnally decoded authority component.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded authority component.
    See Also:
    getAuthority()
  - getBaseRef
```
public Reference getBaseRef()
```
    Returns the base reference for relative references.
    
    Returns:
    The base reference for relative references.
  - getExtensions
```
public String getExtensions()
```
    Returns the optional extensions for hierarchical identifiers. An extensions part starts after the first '.' character of the last path segment and ends with either the end of the segment of with the first ';' character (matrix start). It is a token similar to file extensions separated by '.' characters. The value can be ommited.
    Note that no URI decoding is done by this method.
    
    Returns:
    The extensions or null.
    See Also:
    getExtensionsAsArray(), setExtensions(String)
  - getExtensionsAsArray
```
public String[] getExtensionsAsArray()
```
    Returns the extensions as an array or null if no extension is found.
    
    Returns:
    The extensions as an array or null if no extension is found.
    See Also:
    getExtensions()
  - getFragment
```
public String getFragment()
```
    Returns the fragment identifier.
    Note that no URI decoding is done by this method.
    
    Returns:
    The fragment identifier.
  - getFragment
```
public String getFragment(boolean decode)
```
    Returns the optionnally decoded fragment identifier.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded fragment identifier.
    See Also:
    getFragment()
  - getHierarchicalPart
```
public String getHierarchicalPart()
```
    Returns the hierarchical part which is equivalent to the scheme specific part less the query component.
    Note that no URI decoding is done by this method.
    
    Returns:
    The hierarchical part .
  - getHierarchicalPart
```
public String getHierarchicalPart(boolean decode)
```
    Returns the optionnally decoded hierarchical part.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded hierarchical part.
    See Also:
    getHierarchicalPart()
  - getHostDomain
```
public String getHostDomain()
```
    Returns the host domain name component for server based hierarchical identifiers. It can also be replaced by an IP address when no domain name was registered.
    Note that no URI decoding is done by this method.
    
    Returns:
    The host domain name component for server based hierarchical identifiers.
  - getHostDomain
```
public String getHostDomain(boolean decode)
```
    Returns the optionnally decoded host domain name component.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded host domain name component.
    See Also:
    getHostDomain()
  - getHostIdentifier
```
public String getHostIdentifier()
```
    Returns the host identifier. Includes the scheme, the host name and the host port number.
    Note that no URI decoding is done by this method.
    
    Returns:
    The host identifier.
  - getHostIdentifier
```
public String getHostIdentifier(boolean decode)
```
    Returns the optionnally decoded host identifier.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded host identifier.
    See Also:
    getHostIdentifier()
  - getHostPort
```
public int getHostPort()
```
    Returns the optional port number for server based hierarchical identifiers.
    
    Returns:
    The optional port number for server based hierarchical identifiers or -1 if the port number does not exist.
  - getIdentifier
```
public String getIdentifier()
```
    Returns the absolute resource identifier, without the fragment.
    Note that no URI decoding is done by this method.
    
    Returns:
    The absolute resource identifier, without the fragment.
  - getIdentifier
```
public String getIdentifier(boolean decode)
```
    Returns the optionnally decoded absolute resource identifier.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded absolute resource identifier.
    See Also:
    getIdentifier()
  - getLastSegment
```
public String getLastSegment()
```
    Returns the last segment of a hierarchical path.
    For example the "/a/b/c" and "/a/b/c/" paths have the same segments: "a", "b", "c.
    Note that no URI decoding is done by this method.
    
    Returns:
    The last segment of a hierarchical path.
  - getLastSegment
```
public String getLastSegment(boolean decode)
```
    Returns the optionnally decoded last segment.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded last segment.
    See Also:
    getLastSegment()
  - getLastSegment
```
public String getLastSegment(boolean decode,
                    boolean excludeMatrix)
```
    Returns the optionnally decoded last segment.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    excludeMatrix -
    
    Returns:
    The optionnally decoded last segment.
    See Also:
    getLastSegment()
  - getMatrix
```
public String getMatrix()
```
    Returns the optional matrix for hierarchical identifiers. A matrix part starts after the first ';' character of the last path segment. It is a sequence of 'name=value' parameters separated by ';' characters. The value can be ommitted.
    Note that no URI decoding is done by this method.
    
    Returns:
    The matrix or null.
  - getMatrix
```
public String getMatrix(boolean decode)
```
    Returns the optionnally decoded matrix.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded matrix.
    See Also:
    getMatrix()
  - getMatrixAsForm
```
public Form getMatrixAsForm()
```
    Returns the optional matrix as a form.
    
    Returns:
    The optional matrix component as a form.
  - getMatrixAsForm
```
public Form getMatrixAsForm(CharacterSet characterSet)
```
    Returns the optional matrix as a form submission.
    
    Parameters:
    characterSet - The supported character encoding.
    
    Returns:
    The optional matrix as a form.
  - getParentRef
```
public Reference getParentRef()
```
    Returns the parent reference of a hierarchical reference. The last slash of the path will be considered as the end of the parent path.
    
    Returns:
    The parent reference of a hierarchical reference.
  - getPath
```
public String getPath()
```
    Returns the path component for hierarchical identifiers. If not path is available it returns null.
    Note that no URI decoding is done by this method.
    
    Returns:
    The path component for hierarchical identifiers.
  - getPath
```
public String getPath(boolean decode)
```
    Returns the optionnally decoded path component. If not path is available it returns null.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded path component.
    See Also:
    getPath()
  - getQuery
```
public String getQuery()
```
    Returns the optional query component for hierarchical identifiers.
    Note that no URI decoding is done by this method.
    
    Returns:
    The query component or null.
  - getQuery
```
public String getQuery(boolean decode)
```
    Returns the optionnally decoded query component.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded query component.
    See Also:
    getQuery()
  - getQueryAsForm
```
public Form getQueryAsForm()
```
    Returns the optional query component as a form.
    
    Returns:
    The optional query component as a form.
  - getQueryAsForm
```
public Form getQueryAsForm(boolean decode)
```
    Returns the optional query component as a form.
    
    Parameters:
    decode - Indicates if the names and values should be automatically decoded.
    
    Returns:
    The optional query component as a form.
  - getQueryAsForm
```
public Form getQueryAsForm(CharacterSet characterSet)
```
    Returns the optional query component as a form submission.
    
    Parameters:
    characterSet - The supported character encoding.
    
    Returns:
    The optional query component as a form submission.
  - getRelativePart
```
public String getRelativePart()
```
    Returns the relative part of relative references, without the query and fragment. If the reference is absolute, then null is returned.
    Note that no URI decoding is done by this method.
    
    Returns:
    The relative part.
  - getRelativePart
```
public String getRelativePart(boolean decode)
```
    Returns the optionnally decoded relative part.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded relative part.
    See Also:
    getRelativePart()
  - getRelativeRef
```
public Reference getRelativeRef()
```
    Returns the current reference as a relative reference to the current base reference. This method should only be invoked for absolute references, otherwise an IllegalArgumentException will be raised.
    
    Returns:
    The current reference as a relative reference to the current base reference.
    See Also:
    getRelativeRef(Reference)
  - getRelativeRef
```
public Reference getRelativeRef(Reference base)
```
    Returns the current reference relatively to a base reference. This method should only be invoked for absolute references, otherwise an IllegalArgumentException will be raised.
    
    Parameters:
    base - The base reference to use.
    
    Returns:
    The current reference relatively to a base reference.
    
    Throws:
    
    IllegalArgumentException - If the relative reference is computed although the reference or the base reference are not absolute or not hierarchical.
  - getRemainingPart
```
public String getRemainingPart()
```
    Returns the part of the resource identifier remaining after the base reference. Note that the optional fragment is not returned by this method. Must be used with the following prerequisites:
    - the reference is absolute
    - the reference identifier starts with the resource baseRef
    Note that no URI decoding is done by this method.
    Returns:
    The remaining resource part or null if the prerequisites are not satisfied.
    See Also:
    getRemainingPart(boolean)
  - getRemainingPart
```
public String getRemainingPart(boolean decode)
```
    Returns the optionally decoded remaining part.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionally decoded remaining part.
    See Also:
    getRemainingPart()
  - getRemainingPart
```
public String getRemainingPart(boolean decode,
                      boolean query)
```
    Returns the optionally decoded remaining part with or without the query part of the reference.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    query - True if the query part should be returned, false otherwise.
    
    Returns:
    The optionally decoded remaining part.
    See Also:
    getRemainingPart()
  - getScheme
```
public String getScheme()
```
    Returns the scheme component.
    Note that no URI decoding is done by this method.
    
    Returns:
    The scheme component.
  - getScheme
```
public String getScheme(boolean decode)
```
    Returns the optionnally decoded scheme component.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded scheme component.
    See Also:
    getScheme()
  - getSchemeProtocol
```
public Protocol getSchemeProtocol()
```
    Returns the protocol associated with the scheme component.
    
    Returns:
    The protocol associated with the scheme component.
  - getSchemeSpecificPart
```
public String getSchemeSpecificPart()
```
    Returns the scheme specific part.
    Note that no URI decoding is done by this method.
    
    Returns:
    The scheme specific part.
  - getSchemeSpecificPart
```
public String getSchemeSpecificPart(boolean decode)
```
    Returns the optionnally decoded scheme specific part.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded scheme specific part.
    See Also:
    getSchemeSpecificPart()
  - getSegments
```
public List<String> getSegments()
```
    Returns the list of segments in a hierarchical path.
    A new list is created for each call.
    Note that no URI decoding is done by this method.
    
    Returns:
    The segments of a hierarchical path.
  - getSegments
```
public List<String> getSegments(boolean decode)
```
    Returns the optionnally decoded list of segments.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded list of segments.
    See Also:
    getSegments()
  - getTargetRef
```
public Reference getTargetRef()
```
    Returns the target reference. This method resolves relative references against the base reference then normalize them.
    
    Returns:
    The target reference.
    
    Throws:
    
    IllegalArgumentException - If the base reference (after resolution) is not absolute.
    
    IllegalArgumentException - If the reference is relative and not base reference has been provided.
  - getUserInfo
```
public String getUserInfo()
```
    Returns the user info component for server based hierarchical identifiers.
    Note that no URI decoding is done by this method.
    
    Returns:
    The user info component for server based hierarchical identifiers.
  - getUserInfo
```
public String getUserInfo(boolean decode)
```
    Returns the optionnally decoded user info component.
    
    Parameters:
    decode - Indicates if the result should be decoded using the decode(String) method.
    
    Returns:
    The optionnally decoded user info component.
    See Also:
    getUserInfo()
  - hasExtensions
```
public boolean hasExtensions()
```
    Indicates if this reference has file-like extensions on its last path segment.
    
    Returns:
    True if there is are extensions.
    See Also:
    getExtensions()
  - hasFragment
```
public boolean hasFragment()
```
    Indicates if this reference has a fragment identifier.
    
    Returns:
    True if there is a fragment identifier.
  - hashCode
```
public int hashCode()
```
    Returns a hash code value for the object.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    A hash code value for the object.
  - hasMatrix
```
public boolean hasMatrix()
```
    Indicates if this reference has a matrix.
    
    Returns:
    True if there is a matrix.
    See Also:
    getMatrix()
  - hasQuery
```
public boolean hasQuery()
```
    Indicates if this reference has a query component.
    
    Returns:
    True if there is a query.
  - hasScheme
```
public boolean hasScheme()
```
    Indicates if this reference has a scheme component.
    
    Returns:
    True if there is a scheme component.
  - isAbsolute
```
public boolean isAbsolute()
```
    Indicates if the reference is absolute.
    
    Returns:
    True if the reference is absolute.
  - isEquivalentTo
```
public boolean isEquivalentTo(Reference ref)
```
    Returns true if both reference are equivalent, meaning that they resolve to the same target reference.
    
    Parameters:
    ref - The reference to compare.
    
    Returns:
    True if both reference are equivalent.
  - isHierarchical
```
public boolean isHierarchical()
```
    Indicates if the identifier is hierarchical.
    
    Returns:
    True if the identifier is hierarchical, false if it is opaque.
  - isOpaque
```
public boolean isOpaque()
```
    Indicates if the identifier is opaque.
    
    Returns:
    True if the identifier is opaque, false if it is hierarchical.
  - isParent
```
public boolean isParent(Reference childRef)
```
    Indicates if the reference is a parent of the hierarchical child reference.
    
    Parameters:
    childRef - The hierarchical reference.
    
    Returns:
    True if the reference is a parent of the hierarchical child reference.
  - isRelative
```
public boolean isRelative()
```
    Indicates if the reference is relative.
    
    Returns:
    True if the reference is relative.
  - normalize
```
public Reference normalize()
```
    Normalizes the reference. Useful before comparison between references or when building a target reference from a base and a relative references.
    
    Returns:
    The current reference.
  - setAuthority
```
public void setAuthority(String authority)
```
    Sets the authority component for hierarchical identifiers.
    
    Parameters:
    authority - The authority component for hierarchical identifiers.
  - setBaseRef
```
public void setBaseRef(Reference baseRef)
```
    Sets the base reference for relative references.
    
    Parameters:
    baseRef - The base reference for relative references.
  - setBaseRef
```
public void setBaseRef(String baseUri)
```
    Sets the base reference for relative references.
    
    Parameters:
    baseUri - The base URI for relative references.
  - setExtensions
```
public void setExtensions(String extensions)
```
    Sets the extensions for hierarchical identifiers. An extensions part starts after the first '.' character of the last path segment and ends with either the end of the segment of with the first ';' character (matrix start). It is a token similar to file extensions separated by '.' characters. The value can be ommited.
    Note that no URI decoding is done by this method.
    
    Parameters:
    extensions - The extensions to set or null (without leading or trailing dots).
    See Also:
    getExtensions(), getExtensionsAsArray(), setExtensions(String[])
  - setExtensions
```
public void setExtensions(String[] extensions)
```
    Sets the extensions based on an array of extension tokens (without dots).
    
    Parameters:
    extensions - The array of extensions.
    See Also:
    getExtensions(), getExtensionsAsArray(), setExtensions(String)
  - setFragment
```
public void setFragment(String fragment)
```
    Sets the fragment identifier.
    
    Parameters:
    fragment - The fragment identifier.
    
    Throws:
    
    IllegalArgumentException - if the fragment parameter contains the fragment delimiter ('#').
  - setHostDomain
```
public void setHostDomain(String domain)
```
    Sets the host domain component for server based hierarchical identifiers.
    
    Parameters:
    domain - The host component for server based hierarchical identifiers.
  - setHostPort
```
public void setHostPort(Integer port)
```
    Sets the optional port number for server based hierarchical identifiers.
    
    Parameters:
    port - The optional port number for server based hierarchical identifiers.
    
    Throws:
    
    IllegalArgumentException - If the autority has not been defined.
  - setIdentifier
```
public void setIdentifier(String identifier)
```
    Sets the absolute resource identifier.
    
    Parameters:
    identifier - The absolute resource identifier.
    
    Throws:
    
    IllegalArgumentException - If the identifier parameter contains the fragment delimiter ('#').
  - setLastSegment
```
public void setLastSegment(String lastSegment)
```
    Sets the last segment of the path. If no path is available, then it creates one and adds a slash in front of the given last segmetn.
    Note that no URI decoding is done by this method.
    
    Parameters:
    lastSegment - The last segment of a hierarchical path.
  - setPath
```
public void setPath(String path)
```
    Sets the path component for hierarchical identifiers.
    
    Parameters:
    path - The path component for hierarchical identifiers.
  - setProtocol
```
public void setProtocol(Protocol protocol)
```
    Sets the scheme component based on this protocol.
    
    Parameters:
    protocol - The protocol of the scheme component.
  - setQuery
```
public void setQuery(String query)
```
    Sets the query component for hierarchical identifiers.
    
    Parameters:
    query - The query component for hierarchical identifiers.
  - setRelativePart
```
public void setRelativePart(String relativePart)
```
    Sets the relative part for relative references only.
    
    Parameters:
    relativePart - The relative part to set.
  - setScheme
```
public void setScheme(String scheme)
```
    Sets the scheme component.
    
    Parameters:
    scheme - The scheme component.
  - setSchemeSpecificPart
```
public void setSchemeSpecificPart(String schemeSpecificPart)
```
    Sets the scheme specific part.
    
    Parameters:
    schemeSpecificPart - The scheme specific part.
  - setSegments
```
public void setSegments(List<String> segments)
```
    Sets the segments of a hierarchical path.
    A new absolute path will replace any existing one.
    
    Parameters:
    segments - The segments of the hierarchical path.
  - setUserInfo
```
public void setUserInfo(String userInfo)
```
    Sets the user info component for server based hierarchical identifiers.
    
    Parameters:
    userInfo - The user info component for server based hierarchical identifiers.
    
    Throws:
    
    IllegalArgumentException - If the autority part has not been defined.
  - toString
```
public String toString()
```
    Returns the reference as an URI string.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    The reference as an URI string.
  - toString
```
public String toString(boolean query,
              boolean fragment)
```
    Returns the URI reference string.
    
    Parameters:
    query - Indicates if the query should be included;
    fragment - Indicates if the fragment should be included;
    
    Returns:
    The URI reference string.
  - toUri
```
public URI toUri()
```
    Converts to a URI instance. Note that relative references are resolved before conversion using the getTargetRef() method.
    
    Returns:
    A URI instance.
  - toUrl
```
public URL toUrl()
```
    Converts to a URL instance. Note that relative references are resolved before conversion using the getTargetRef() method.
    
    Returns:
    A URL instance.

Class Reference

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Reference

Reference

Reference

Reference

Reference

Reference

Reference

Reference

Reference

Reference

Reference

Reference

Reference

Method Detail

decode

decode

encode

encode

encode

encode

isGenericDelimiter

isReserved

isSubDelimiter

isUnreserved

isValid

toString

toString

toString

addQueryParameter

addQueryParameter

addQueryParameters

addSegment

clone

equals

getAuthority

getAuthority

getBaseRef

getExtensions

getExtensionsAsArray

getFragment

getFragment

getHierarchicalPart

getHierarchicalPart

getHostDomain

getHostDomain

getHostIdentifier

getHostIdentifier

getHostPort

getIdentifier

getIdentifier

getLastSegment

getLastSegment

getLastSegment

getMatrix

getMatrix

getMatrixAsForm

getMatrixAsForm

getParentRef

getPath

getPath

getQuery

getQuery

getQueryAsForm

getQueryAsForm

getQueryAsForm

getRelativePart

getRelativePart

getRelativeRef

getRelativeRef

getRemainingPart

getRemainingPart

getRemainingPart

getScheme

getScheme

getSchemeProtocol