|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.restlet.data.Reference
public class Reference
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.
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 |
---|
public Reference()
public Reference(Reference ref)
ref
- The reference to clone.public Reference(Reference baseRef, String uriReference)
baseRef
- The base reference.uriReference
- The URI reference, either absolute or relative.public Reference(Reference baseRef, String relativePart, String query, String fragment)
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.public Reference(String uriReference)
uriReference
- The URI reference, either absolute or relative.public Reference(String identifier, String fragment)
identifier
- The resource identifier.fragment
- The fragment identifier.public Reference(String scheme, String hostName, int hostPort, String path, String query, String fragment)
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 |
---|
public static String decode(String toDecode)
toDecode
- The string to decode.
public static String encode(String toEncode)
toEncode
- The string to encode.
public static String encode(String toEncode, CharacterSet characterSet)
toEncode
- The string to encode.characterSet
- The supported character encoding.
public static String decode(String toDecode, CharacterSet characterSet)
toDecode
- The string to decode.characterSet
- The name of a supported character encoding.
public static String toString(String scheme, String hostName, Integer hostPort, String path, String query, String fragment)
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.public static String toString(String relativePart, String query, String fragment)
relativePart
- The relative part component.query
- The optional query component for hierarchical identifiers.fragment
- The optional fragment identifier.public static String toString(String scheme, String host, String path, String query, String fragment)
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.public boolean equals(Object object)
equals
in class Object
object
- The object to compare to.
public String getAuthority()
public Reference getBaseRef()
public String getFragment()
public String getHierarchicalPart()
public String getHostDomain()
public String getHostIdentifier()
public int getHostPort()
public String getIdentifier()
public String getLastSegment()
public Reference getParentRef()
public String getPath()
public String getQuery()
public Form getQueryAsForm()
IOException
public Form getQueryAsForm(CharacterSet characterSet)
characterSet
- The supported character encoding.
IOException
public String getRelativePart()
public String getRemainingPart()
public Reference getRelativeRef()
getRelativeRef(Reference)
public Reference getRelativeRef(Reference base)
base
- The base reference to use.
IllegalArgumentException
- If the relative reference is computed although the
reference or the base reference are not absolute or not
hierarchical.public String getScheme()
public Protocol getSchemeProtocol()
public String getSchemeSpecificPart()
public List<String> getSegments()
public Reference getTargetRef()
IllegalArgumentException
- If the base reference (after resolution) is not absolute.
IllegalArgumentException
- If the reference is relative and not base reference has
been provided.public String getUserInfo()
public int hashCode()
hashCode
in class Object
public boolean isAbsolute()
public boolean isEquivalentTo(Reference ref)
ref
- The reference to compare.
public boolean isHierarchical()
public boolean isOpaque()
public boolean isParent(Reference childRef)
childRef
- The hierarchical reference.
public boolean isRelative()
public Reference normalize()
public void setAuthority(String authority)
authority
- The authority component for hierarchical identifiers.public void setBaseRef(String baseUri)
baseUri
- The base URI for relative references.public void setBaseRef(Reference baseRef)
baseRef
- The base reference for relative references.public void setFragment(String fragment)
fragment
- The fragment identifier.
IllegalArgumentException
- if the fragment parameter contains the fragment delimiter
('#').public void setHostDomain(String domain)
domain
- The host component for server based hierarchical
identifiers.public void setHostPort(Integer port)
port
- The optional port number for server based hierarchical
identifiers.
IllegalArgumentException
- If the autority has not been defined.public void setIdentifier(String identifier)
identifier
- The absolute resource identifier.
IllegalArgumentException
- If the identifier parameter contains the fragment
delimiter ('#').public void setPath(String path)
path
- The path component for hierarchical identifiers.public void setProtocol(Protocol protocol)
protocol
- The protocol of the scheme component.public void setQuery(String query)
query
- The query component for hierarchical identifiers.public void setRelativePart(String relativePart)
relativePart
- The relative part to set.public void setScheme(String scheme)
scheme
- The scheme component.public void setSchemeSpecificPart(String schemeSpecificPart)
schemeSpecificPart
- The scheme specific part.public void setSegments(List<String> segments)
segments
- The segments of the hierarchical path.public void setUserInfo(String userInfo)
userInfo
- The user info component for server based hierarchical
identifiers.
IllegalArgumentException
- If the autority part has not been defined.public String toString()
toString
in class Object
public String toString(boolean query, boolean fragment)
query
- Indicates if the query should be included;fragment
- Indicates if the fragment should be included;
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |