org.restlet.data
Class Reference

java.lang.Object
  extended by 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.

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.

Author:
Jerome Louvel (contact@noelios.com)
See Also:
RFC 3986

Constructor Summary
Reference()
          Empty constructor.
Reference(Reference ref)
          Clone constructor.
Reference(Reference baseRef, String uriReference)
          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.
 
Method Summary
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, 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.
 Reference getBaseRef()
          Returns the base reference for relative references.
 String getFragment()
          Returns the fragment identifier.
 String getHierarchicalPart()
          Returns the hierarchical part which is equivalent to the scheme specific part less the query component.
 String getHostDomain()
          Returns the host domain name component for server based hierarchical identifiers.
 String getHostIdentifier()
          Returns the host identifier.
 int getHostPort()
          Returns the optional port number for server based hierarchical identifiers.
 String getIdentifier()
          Returns the absolute resource identifier, without the fragment.
 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.
 Reference getParentRef()
          Returns the parent reference of a hierarchical reference.
 String getPath()
          Returns the path component for hierarchical identifiers.
 String getQuery()
          Returns the optional query component for hierarchical identifiers.
 Form getQueryAsForm()
          Returns the optional query component as a form submission.
 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.
 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 getScheme()
          Returns the scheme component.
 Protocol getSchemeProtocol()
          Returns the protocol associated with the scheme component.
 String getSchemeSpecificPart()
          Returns the scheme specific part.
 List<String> getSegments()
          Returns the segments of a hierarchical path.
A new list is created for each call.
 Reference getTargetRef()
          Returns the target reference.
 String getUserInfo()
          Returns the user info component for server based hierarchical identifiers.
 int hashCode()
          Returns a hash code value for the object.
 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.
 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.
 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 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 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.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Reference

public Reference()
Empty constructor.


Reference

public Reference(Reference ref)
Clone constructor.

Parameters:
ref - The reference to clone.

Reference

public Reference(Reference baseRef,
                 String 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 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.

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,
                            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 incompatibilites.

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.

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 incompatibilites.

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.

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.

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.

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.

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.

Returns:
The authority component for hierarchical identifiers.

getBaseRef

public Reference getBaseRef()
Returns the base reference for relative references.

Returns:
The base reference for relative references.

getFragment

public String getFragment()
Returns the fragment identifier.

Returns:
The fragment identifier.

getHierarchicalPart

public String getHierarchicalPart()
Returns the hierarchical part which is equivalent to the scheme specific part less the query component.

Returns:
The hierarchical part .

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.

Returns:
The host domain name component for server based hierarchical identifiers.

getHostIdentifier

public String getHostIdentifier()
Returns the host identifier. Includes the scheme, the host name and the host port number.

Returns:
The host identifier.

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.

Returns:
The absolute resource identifier, without the fragment.

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.

Returns:
The last segment of a hierarchical path.

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.

Returns:
The path component for hierarchical identifiers.

getQuery

public String getQuery()
Returns the optional query component for hierarchical identifiers.

Returns:
The optional query component for hierarchical identifiers.

getQueryAsForm

public Form getQueryAsForm()
Returns the optional query component as a form submission.

Returns:
The optional query component as a form submission.
Throws:
IOException

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.
Throws:
IOException

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.

Returns:
The relative part.

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:

Returns:
The remaining resource part or null if the prerequisites are not satisfied.

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.

getScheme

public String getScheme()
Returns the scheme component.

Returns:
The scheme component.

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.

Returns:
The scheme specific part.

getSegments

public List<String> getSegments()
Returns the segments of a hierarchical path.
A new list is created for each call.

Returns:
The segments of a hierarchical path.

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.

Returns:
The user info component for server based hierarchical identifiers.

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.

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(String baseUri)
Sets the base reference for relative references.

Parameters:
baseUri - The base URI for relative references.

setBaseRef

public void setBaseRef(Reference baseRef)
Sets the base reference for relative references.

Parameters:
baseRef - The base reference for relative references.

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 ('#').

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.


Copyright © 2005-2007 Noelios Consulting.