javax.ws.rs.core
Class Link

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

public final class Link
extends java.lang.Object

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

The methods toString() and valueOf(java.lang.String) can be used to serialize and deserialize 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 java.lang.String	CONSUMES
static java.lang.String	METHOD
static java.lang.String	PRODUCES
static java.lang.String	REL
static java.lang.String	TITLE
static java.lang.String	TYPE

Constructor Summary

Link()

Method Summary

boolean	equals(java.lang.Object other) Equality test for links.
static Link.Builder	fromLink(Link link) Create a new instance initialized from another link.
static Link.Builder	fromResourceMethod(java.lang.Class<?> resource, java.lang.String method) Generate a link by introspecting a resource method.
static Link.Builder	fromResourceMethod(java.lang.Class<?> resource, java.lang.String method, java.lang.String rel) Generate a link by introspecting a resource method.
static Link.Builder	fromUri(java.lang.String uri) Create a new instance initialized from an existing URI.
static Link.Builder	fromUri(java.net.URI uri) Create a new instance initialized from an existing URI.
java.util.List<java.lang.String>	getConsumes() Returns an immutable list containing all the types defined on this link via the "consumes" parameter.
java.lang.String	getMethod() Returns the value associated with the link "method" param, or null if this param is not specified.
MultivaluedMap<java.lang.String,java.lang.String>	getParams() Returns an immutable map that includes all the link parameters defined on this link.
java.util.List<java.lang.String>	getProduces() Returns an immutable list containing all the types defined on this link via the "produces" parameter.
java.util.List<java.lang.String>	getRel() Returns an immutable list containing all the relation types defined on this link via the "rel" parameter.
java.lang.String	getTitle() Returns the value associated with the link "title" param, or null if this param is not specified.
java.lang.String	getType() Returns the value associated with the link "type" param, or null if this param is not specified.
java.net.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.
java.lang.String	toString() Returns a string representation as a link header (RFC 5988).
static Link	valueOf(java.lang.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

CONSUMES

public static final java.lang.String CONSUMES

See Also:

Constant Field Values

METHOD

public static final java.lang.String METHOD

See Also:

Constant Field Values

PRODUCES

public static final java.lang.String PRODUCES

See Also:

Constant Field Values

TITLE

public static final java.lang.String TITLE

See Also:

Constant Field Values

REL

public static final java.lang.String REL

See Also:

Constant Field Values

TYPE

public static final java.lang.String TYPE

See Also:

Constant Field Values

Constructor Detail

Link

public Link()

Method Detail

getUri

public java.net.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 java.util.List<java.lang.String> getRel()

Returns an immutable list containing all the relation types defined on this link via the "rel" parameter. If no relation types are defined, this method returns an empty list.

Returns:

list of relation types

getTitle

public java.lang.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 java.lang.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

getMethod

public java.lang.String getMethod()

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

Returns:

value of "method" parameter or null

getProduces

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

Returns an immutable list containing all the types defined on this link via the "produces" parameter. If no produces types are defined, this method returns an empty list.

Returns:

list of produces types

getConsumes

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

Returns an immutable list containing all the types defined on this link via the "consumes" parameter. If no consumes types are defined, this method returns an empty list.

Returns:

list of consumes types

getParams

public MultivaluedMap<java.lang.String,java.lang.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(java.lang.Object other)

Equality test for links.

Overrides:

equals in class java.lang.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 java.lang.Object

Returns:

Hash code for this link

toString

public java.lang.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 list of space-separated tokens. For example, ; title="employee"; rel="manager friend"

Overrides:

toString in class java.lang.Object

Returns:

string link header representation for this link

valueOf

public static Link valueOf(java.lang.String value)
                    throws java.lang.IllegalArgumentException

Simple parser to convert link header string representations into a link. link ::= '<' uri '>' (';' link-param)* link-param ::= name '=' quoted-string The resulting language is similar to that defined in RFC 5988.

Parameters:

value - String representation

Returns:

newly parsed link

Throws:

java.lang.IllegalArgumentException - if a syntax error is found

fromUri

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

Create a new instance initialized from an existing URI.

Parameters:

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

Returns:

a new builder

Throws:

java.lang.IllegalArgumentException - if uri is null

fromUri

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

Create a new instance initialized from an existing URI.

Parameters:

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

Returns:

a new builder

Throws:

java.lang.IllegalArgumentException - if uri is null

fromLink

public static Link.Builder fromLink(Link link)

Create a new 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(java.lang.Class<?> resource,
                                              java.lang.String method)
                                       throws java.lang.IllegalArgumentException

Generate a link by introspecting a resource method. This method is a shorthand for fromResourceMethod(resource, method, method).

Parameters:

resource - resource class

method - name of resource method

Returns:

link builder to further configure link

Throws:

java.lang.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(java.lang.Class<?> resource,
                                              java.lang.String method,
                                              java.lang.String rel)
                                       throws java.lang.IllegalArgumentException

Generate a link by introspecting a resource method. Finds the first method of a given name and generates a link that includes parameters "method", "produces" and "consumes". If "produces" is not defined, MediaType.WILDCARD is used. Likewise, if "consumes" is not defined, MediaType.WILDCARD is used but only when the HTTP method is POST or PUT. The value of "rel" must be specified as an argument.

Parameters:

resource - resource class

method - name of resource method

rel - value of "rel" parameter

Returns:

link builder to further configure link

Throws:

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