javax.ws.rs.core
Class Link

java.lang.Object
  javax.ws.rs.core.Link

public final class Link
extends Object

Class representing hypermedia links. A hypermedia link may include additional parameters beyond its underlying URI. Parameters such as "rel" or "type" provide additional meta-data and can be used to create instances of Invocation.Builder in order to follow links.

The methods toString() and valueOf(java.lang.String) can be used to serialize and de-serialize a link into a link header (RFC 5988).

Since:

2.0

Author:

Marek Potociar, Santiago Pericas-Geertsen

See Also:

Client.invocation(javax.ws.rs.core.Link)

Nested Class Summary

static class	Link.Builder Builder class for hypermedia links.
static class	Link.JaxbAdapter An implementation of JAXB XmlAdapter that maps the JAX-RS Link type to a value that can be marshalled and unmarshalled by JAXB.
static class	Link.JaxbLink Value type for Link that can be marshalled and unmarshalled by JAXB.

Field Summary

static String	REL Rel link param from RFC 5988.
static String	TITLE Title link param from RFC 5988.
static String	TYPE Type link param from RFC 5988.

Constructor Summary

Link()

Method Summary

boolean	equals(Object other) Equality test for links.
static Link.Builder	fromLink(Link link) Create a new builder instance initialized from another link.
static Link.Builder	fromResourceMethod(Class<?> resource, String method) Generate a link by introspecting a resource method.
static Link.Builder	fromResourceMethod(Class<?> resource, String method, String rel) Generate a link by introspecting a resource method.
static Link.Builder	fromUri(String uri) Create a new builder instance initialized from an existing URI represented as a string.
static Link.Builder	fromUri(URI uri) Create a new builder instance initialized from an existing URI.
Map<String,String>	getParams() Returns an immutable map that includes all the link parameters defined on this link.
String	getRel() Returns the value associated with the link "rel" param, or null if this param is not specified.
List<String>	getRels() Returns the value associated with the link "rel" param as a list of strings or the empty list if "rel" is not defined.
String	getTitle() Returns the value associated with the link "title" param, or null if this param is not specified.
String	getType() Returns the value associated with the link "type" param, or null if this param is not specified.
URI	getUri() Returns the underlying URI associated with this link.
UriBuilder	getUriBuilder() Convenience method that returns a UriBuilder initialized with this link's underlying URI.
int	hashCode() Hash code computation for links.
String	toString() Returns a string representation as a link header (RFC 5988).
static Link	valueOf(String value) Simple parser to convert link header string representations into a link.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TITLE

public static final String TITLE

Title link param from RFC 5988.

See Also:

Constant Field Values

REL

public static final String REL

Rel link param from RFC 5988.

See Also:

Constant Field Values

TYPE

public static final String TYPE

Type link param from RFC 5988.

See Also:

Constant Field Values

Constructor Detail

Link

public Link()

Method Detail

getUri

public URI getUri()

Returns the underlying URI associated with this link.

Returns:

underlying URI.

getUriBuilder

public UriBuilder getUriBuilder()

Convenience method that returns a UriBuilder initialized with this link's underlying URI.

Returns:

UriBuilder initialized using underlying URI.

getRel

public String getRel()

Returns the value associated with the link "rel" param, or null if this param is not specified.

Returns:

relation types as string or null.

getRels

public List<String> getRels()

Returns the value associated with the link "rel" param as a list of strings or the empty list if "rel" is not defined.

Returns:

relation types as list of strings or empty list.

getTitle

public String getTitle()

Returns the value associated with the link "title" param, or null if this param is not specified.

Returns:

value of "title" parameter or null.

getType

public String getType()

Returns the value associated with the link "type" param, or null if this param is not specified.

Returns:

value of "type" parameter or null.

getParams

public Map<String,String> getParams()

Returns an immutable map that includes all the link parameters defined on this link. If defined, this map will include entries for "rel", "title" and "type".

Returns:

immutable map of link parameters.

equals

public boolean equals(Object other)

Equality test for links.

Overrides:

equals in class Object

Parameters:

other - Object to compare against.

Returns:

true if equal, false otherwise.

hashCode

public int hashCode()

Hash code computation for links.

Overrides:

hashCode in class Object

Returns:

Hash code for this link.

toString

public String toString()

Returns a string representation as a link header (RFC 5988). All link params are serialized as link-param="value" where value is a quoted-string. For example, ; title="employee"; rel="manager friend"

Overrides:

toString in class Object

Returns:

string link header representation for this link.

valueOf

public static Link valueOf(String value)
                    throws IllegalArgumentException

Simple parser to convert link header string representations into a link.

 link ::= '<' uri '>' (';' link-param)*
 link-param ::= name '=' quoted-string
 

See RFC 5988 for more information.

Parameters:

value - String representation.

Returns:

newly parsed link.

Throws:

IllegalArgumentException - if a syntax error is found.

fromUri

public static Link.Builder fromUri(URI uri)
                            throws IllegalArgumentException

Create a new builder instance initialized from an existing URI.

Parameters:

uri - a URI that will be used to initialize the builder.

Returns:

a new builder.

Throws:

IllegalArgumentException - if uri is null.

fromUri

public static Link.Builder fromUri(String uri)
                            throws IllegalArgumentException

Create a new builder instance initialized from an existing URI represented as a string.

Parameters:

uri - a URI that will be used to initialize the builder.

Returns:

a new builder.

Throws:

IllegalArgumentException - if uri is null.

fromLink

public static Link.Builder fromLink(Link link)

Create a new builder instance initialized from another link.

Parameters:

link - other link used for initialization.

Returns:

a new builder.

Since:

2.0

fromResourceMethod

public static Link.Builder fromResourceMethod(Class<?> resource,
                                              String method)
                                       throws IllegalArgumentException

Generate a link by introspecting a resource method. This method is a shorthand for fromResourceMethod(resource, method, method) where the method name is used as the value of the "rel" parameter.

Parameters:

resource - resource class.

method - name of resource method.

Returns:

link builder to further configure link.

Throws:

IllegalArgumentException - if any argument is null or no method is found.

See Also:

fromResourceMethod(java.lang.Class, java.lang.String, java.lang.String)

fromResourceMethod

public static Link.Builder fromResourceMethod(Class<?> resource,
                                              String method,
                                              String rel)
                                       throws IllegalArgumentException

Generate a link by introspecting a resource method. Finds the first method of a given name and generates a link with the appropriate URI and values for "type" and "rel".

The value of "type" is set to be the first media-type in @Produces, and is omitted if that annotation is not present on the method. The value of "rel" must be specified as an argument to this method.

Parameters:

resource - resource class.

method - name of resource method.

rel - value of "rel" parameter.

Returns:

link builder to further configure link.

Throws:

IllegalArgumentException - if any argument is null or no method is found.