Top Description Inners Fields Constructors Methods
jakarta.ws.rs.core

public abstract Class Link

extends Object
Class Inheritance
Imports
java.net.URI, java.util.List, .Map, jakarta.ws.rs.ext.RuntimeDelegate

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. Links in responses can be followed by creating an jakarta.ws.rs.client.Invocation.Builder or a jakarta.ws.rs.client.WebTarget.

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

Authors
Marek Potociar, Santiago Pericas-Geertsen
Since
2.0
See Also
jakarta.ws.rs.client.Client#invocation, jakarta.ws.rs.client.Client#target(jakarta.ws.rs.core.Link), jakarta.ws.rs.core.Response#getLink(java.lang.String)

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
Link.Builder

Builder class for hypermedia links.

Field Summary

Modifier and TypeField and Description
public static final String
REL

Rel link param from RFC 5988.

public static final String
TITLE

Title link param from RFC 5988.

public static final String
TYPE

Type link param from RFC 5988.

Constructor Summary

AccessConstructor and Description

Method Summary

Modifier and TypeMethod and Description
public static Link.Builder

Returns:

the updated Link.Builder.
fromMethod(final Class<?>
the resource containing the method.
resource, final String
the name of the method whose jakarta.ws.rs.Path value will be used to obtain the path to append.
method)

Convenience method to build a link from a resource.

public static Link.Builder

Returns:

a new Link.Builder.
fromPath(final String
a URI path that will be used to initialize the Link, may contain URI template parameters.
path)

Convenience method to build a link from a path.

public static Link.Builder

Returns:

a new link builder instance.
fromResource(final Class<?>
a root resource whose jakarta.ws.rs.Path value will be used to initialize the builder.
resource)

Convenience method to build a link from a resource.

public static Link.Builder

Returns:

a new builder.
fromUri(final URI
a URI that will be used to initialize the builder.
uri)

Create a new builder instance initialized from an existing URI.

public static Link.Builder

Returns:

a new builder.
fromUri(final String
a URI that will be used to initialize the builder.
uri)

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

public static Link.Builder

Returns:

a new builder.
fromUriBuilder(final UriBuilder
instance of URI builder.
uriBuilder)

Create a new builder instance initialized from a URI builder.

public abstract Map<String, String>

Returns:

immutable map of link parameters.
getParams()

Returns an immutable map that includes all the link parameters defined on this link.

public abstract String

Returns:

relation types as string or null.
getRel()

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

public abstract List<String>

Returns:

relation types as list of strings or empty list.
getRels()

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

public abstract String

Returns:

value of title parameter or null.
getTitle()

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

public abstract String

Returns:

value of type parameter or null.
getType()

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

public abstract URI

Returns:

underlying URI.
getUri()

Returns the underlying URI associated with this link.

public abstract UriBuilder

Returns:

UriBuilder initialized using underlying URI.
getUriBuilder()

Convenience method that returns a jakarta.ws.rs.core.UriBuilder initialized with this link's underlying URI.

public abstract String

Returns:

string link header representation for this link.
toString()

Overrides java.lang.Object.toString.

Returns a string representation as a link header (RFC 5988).

public static Link

Returns:

newly parsed link.
valueOf(final String
String representation.
value)

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

RELback to summary
public static final String REL

Rel link param from RFC 5988.

TITLEback to summary
public static final String TITLE

Title link param from RFC 5988.

TYPEback to summary
public static final String TYPE

Type link param from RFC 5988.

Constructor Detail

Linkback to summary
public Link()

Method Detail

fromLinkback to summary
public static Link.Builder fromLink(final Link link)

Create a new builder instance initialized from another link.

Parameters
link:Link

other link used for initialization.

Returns:Link.Builder

a new builder.

fromMethodback to summary
public static Link.Builder fromMethod(final Class<?> resource, final String method)

Convenience method to build a link from a resource. Equivalent to Link.fromUriBuilder({@link UriBuilder#fromMethod(Class, String) UriBuilder.fromMethod(resource, method)}). Note that the link URI passed to the Link.Builder instance returned by this method is relative. Should the link be built as absolute, a base URI has to be specified in the builder prior to building the new link instance. For example, on a server side a UriInfo#getBaseUri() may be typically used to define the base URI of a link created using this method.

Parameters
resource:Class<?>

the resource containing the method.

method:String

the name of the method whose jakarta.ws.rs.Path value will be used to obtain the path to append.

Returns:Link.Builder

the updated Link.Builder.

Exceptions
IllegalArgumentException:
if resource or method is null, or there is more than or less than one variant of the method annotated with jakarta.ws.rs.Path.
See Also
UriInfo#getBaseUri()
fromPathback to summary
public static Link.Builder fromPath(final String path)

Convenience method to build a link from a path. Equivalent to fromUriBuilder(UriBuilder.fromPath(path)).

Parameters
path:String

a URI path that will be used to initialize the Link, may contain URI template parameters.

Returns:Link.Builder

a new Link.Builder.

Exceptions
IllegalArgumentException:
if path is null.
fromResourceback to summary
public static Link.Builder fromResource(final Class<?> resource)

Convenience method to build a link from a resource. Equivalent to Link.fromUriBuilder({@link UriBuilder#fromResource UriBuilder.fromResource(resource)}). Note that the link URI passed to the Link.Builder instance returned by this method is relative. Should the link be built as absolute, a base URI has to be specified in the builder prior to building the new link instance. For example, on a server side a UriInfo#getBaseUri() may be typically used to define the base URI of a link created using this method.

Parameters
resource:Class<?>

a root resource whose jakarta.ws.rs.Path value will be used to initialize the builder.

Returns:Link.Builder

a new link builder instance.

Exceptions
IllegalArgumentException:
if resource is not annotated with jakarta.ws.rs.Path or resource is null.
See Also
UriInfo#getBaseUri()
fromUriback to summary
public static Link.Builder fromUri(final URI uri)

Create a new builder instance initialized from an existing URI.

Parameters
uri:URI

a URI that will be used to initialize the builder.

Returns:Link.Builder

a new builder.

Exceptions
IllegalArgumentException:
if uri is null.
fromUriback to summary
public static Link.Builder fromUri(final String uri)

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

Parameters
uri:String

a URI that will be used to initialize the builder.

Returns:Link.Builder

a new builder.

Exceptions
IllegalArgumentException:
if uri is null.
fromUriBuilderback to summary
public static Link.Builder fromUriBuilder(final UriBuilder uriBuilder)

Create a new builder instance initialized from a URI builder.

Parameters
uriBuilder:UriBuilder

instance of URI builder.

Returns:Link.Builder

a new builder.

getParamsback to summary
public abstract 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:Map<String, String>

immutable map of link parameters.

getRelback to summary
public abstract String getRel()

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

Returns:String

relation types as string or null.

getRelsback to summary
public abstract 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:List<String>

relation types as list of strings or empty list.

getTitleback to summary
public abstract String getTitle()

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

Returns:String

value of title parameter or null.

getTypeback to summary
public abstract String getType()

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

Returns:String

value of type parameter or null.

getUriback to summary
public abstract URI getUri()

Returns the underlying URI associated with this link.

Returns:URI

underlying URI.

getUriBuilderback to summary
public abstract UriBuilder getUriBuilder()

Convenience method that returns a jakarta.ws.rs.core.UriBuilder initialized with this link's underlying URI.

Returns:UriBuilder

UriBuilder initialized using underlying URI.

toStringback to summary
public abstract String toString()

Overrides java.lang.Object.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, <http://foo.bar/employee/john>; title="employee"; rel="manager friend"

Returns:String

string link header representation for this link.

Annotations
@Override
valueOfback to summary
public static Link valueOf(final String value)

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

link ::= '<' uri 'gt;' (';' link-param)*
link-param ::= name '=' quoted-string
See RFC 5988 for more information.
Parameters
value:String

String representation.

Returns:Link

newly parsed link.

Exceptions
IllegalArgumentException:
if a syntax error is found.
See Also
Link.Builder#link(java.lang.String)
jakarta.ws.rs.core back to summary

public Interface Link.Builder

Builder class for hypermedia links.
Since
2.0
See Also
Link

Method Summary

Modifier and TypeMethod and Description
public Link.Builder

Returns:

the updated builder.
baseUri(URI
base URI for relative links.
uri)

Set the base URI for resolution of relative URIs.

public Link.Builder

Returns:

the updated builder.
baseUri(String
base URI for relative links.
uri)

Set the base URI as a string for resolution of relative URIs.

public Link

Returns:

newly built link.
build(Object...
parameters used to build underlying URI.
values)

Finish building this link using the supplied values as URI parameters.

public Link

Returns:

newly built link.
buildRelativized(URI
URI used for relativization.
uri, Object...
parameters used to build underlying URI.
values)

Finish building this link using the supplied values as URI parameters and relativize the result with respect to the supplied URI.

public Link.Builder

Returns:

the updated builder.
param(String
the name of the parameter.
name, String
the value set for the parameter.
value)

Set an arbitrary parameter on this link.

public Link.Builder

Returns:

the updated builder.
rel(String
relation name.
rel)

Convenience method to set a link relation.

public Link.Builder

Returns:

the updated builder.
title(String
title parameter of this link.
title)

Convenience method to set a title on this link.

public Link.Builder

Returns:

the updated builder.
type(String
type parameter of this link.
type)

Convenience method to set a type on this link.

public Link.Builder

Returns:

the updated builder.
uri(URI
underlying URI for link
uri)

Set underlying URI template for the link being constructed.

public Link.Builder

Returns:

the updated builder.
uri(String
underlying URI for link.
uri)

Set underlying string representing URI template for the link being constructed.

public Link.Builder

Returns:

the updated builder.
uriBuilder(UriBuilder
underlying URI builder.
uriBuilder)

Set underlying URI builder representing the URI template for the link being constructed.

Method Detail

baseUriback to summary
public Link.Builder baseUri(URI uri)

Set the base URI for resolution of relative URIs. If the underlying URI is already absolute, the base URI is ignored.

Parameters
uri:URI

base URI for relative links.

Returns:Link.Builder

the updated builder.

See Also
Link#fromPath(java.lang.String), Link#fromResource(java.lang.Class), Link#fromMethod(java.lang.Class, java.lang.String)
baseUriback to summary
public Link.Builder baseUri(String uri)

Set the base URI as a string for resolution of relative URIs. If the underlying URI is already absolute, the base URI is ignored.

Parameters
uri:String

base URI for relative links.

Returns:Link.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if string representation of URI is invalid.
See Also
Link#fromPath(java.lang.String), Link#fromResource(java.lang.Class), Link#fromMethod(java.lang.Class, java.lang.String)
buildback to summary
public Link build(Object... values)

Finish building this link using the supplied values as URI parameters. The state of the builder is unaffected; this method may be called multiple times on the same builder instance.

Parameters
values:Object[]

parameters used to build underlying URI.

Returns:Link

newly built link.

Exceptions
IllegalArgumentException:
if there are any URI template parameters without a supplied value, or if a value is null.
UriBuilderException:
if a URI cannot be constructed based on the current state of the underlying URI builder.
buildRelativizedback to summary
public Link buildRelativized(URI uri, Object... values)

Finish building this link using the supplied values as URI parameters and relativize the result with respect to the supplied URI. If the underlying link is already relative or if it is absolute but does not share a prefix with the supplied URI, this method is equivalent to calling Link.Builder#build(java.lang.Object[]). Note that a base URI can be set on a relative link using Link.Builder#baseUri(java.net.URI). The state of the builder is unaffected; this method may be called multiple times on the same builder instance.

Parameters
uri:URI

URI used for relativization.

values:Object[]

parameters used to build underlying URI.

Returns:Link

newly built link.

Exceptions
IllegalArgumentException:
if there are any URI template parameters without a supplied value, or if a value is null.
UriBuilderException:
if a URI cannot be constructed based on the current state of the underlying URI builder.
See Also
baseUri(java.lang.String), baseUri(java.net.URI)
linkback to summary
public Link.Builder link(Link link)

Initialize builder using another link. Sets underlying URI and copies all parameters.

Parameters
link:Link

other link from which to initialize.

Returns:Link.Builder

the updated builder.

linkback to summary
public Link.Builder link(String link)

Initialize builder using another link represented as a string. Uses simple parser to convert string representation into a link. 

link ::= '<' uri 'gt;' (';' link-param)*
link-param ::= name '=' quoted-string
See RFC 5988 for more information.
Parameters
link:String

other link in string representation.

Returns:Link.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if string representation of URI is invalid.
paramback to summary
public Link.Builder param(String name, String value)

Set an arbitrary parameter on this link. Note that link parameters are those defined in RFC 5988 and should not be confused with URI parameters which can be specified when calling build(Object...).

Parameters
name:String

the name of the parameter.

value:String

the value set for the parameter.

Returns:Link.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if either the name or value are null.
relback to summary
public Link.Builder rel(String rel)

Convenience method to set a link relation. More than one rel value can be specified by using one or more whitespace characters as delimiters according to RFC 5988. The effect of calling this method is cumulative; relations are appended using a single space character as separator.

Parameters
rel:String

relation name.

Returns:Link.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if the name is null.
titleback to summary
public Link.Builder title(String title)

Convenience method to set a title on this link.

Parameters
title:String

title parameter of this link.

Returns:Link.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if the title is null.
typeback to summary
public Link.Builder type(String type)

Convenience method to set a type on this link.

Parameters
type:String

type parameter of this link.

Returns:Link.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if the type is null.
uriback to summary
public Link.Builder uri(URI uri)

Set underlying URI template for the link being constructed.

Parameters
uri:URI

underlying URI for link

Returns:Link.Builder

the updated builder.

uriback to summary
public Link.Builder uri(String uri)

Set underlying string representing URI template for the link being constructed.

Parameters
uri:String

underlying URI for link.

Returns:Link.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if string representation of URI is invalid.
uriBuilderback to summary
public Link.Builder uriBuilder(UriBuilder uriBuilder)

Set underlying URI builder representing the URI template for the link being constructed.

Parameters
uriBuilder:UriBuilder

underlying URI builder.

Returns:Link.Builder

the updated builder.