javax.ws.rs.core
Interface Link.Builder

All Known Implementing Classes:

JerseyLink.Builder

Enclosing class:

Link

public static interface Link.Builder

Builder class for hypermedia links.

Since:

2.0

See Also:

Link

Method Summary

Link	build(Object... values) Finish building this link using the supplied values as URI parameters.
Link	buildRelativized(URI uri, Object... values) Finish building this link using the supplied values as URI parameters and relativize the result with respect to a supplied URI.
Link	buildResolved(URI uri, Object... values) Finish building this link using the supplied values as URI parameters and resolve the result using a base URI.
Link.Builder	link(Link link) Initialize builder using another link.
Link.Builder	link(String link) Initialize builder using another link represented as a string.
Link.Builder	param(String name, String value) Set an arbitrary parameter on this link.
Link.Builder	rel(String rel) Convenience method to set a link relation.
Link.Builder	title(String title) Convenience method to set a title on this link.
Link.Builder	type(String type) Convenience method to set a type on this link.
Link.Builder	uri(String uri) Set underlying string representing URI template for the link being constructed.
Link.Builder	uri(URI uri) Set underlying URI template for the link being constructed.
Link.Builder	uriBuilder(UriBuilder uriBuilder) Set underlying URI builder representing the URI template for the link being constructed.

Method Detail

link

Link.Builder link(Link link)

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

Parameters:

link - other link from which to initialize.

Returns:

the updated builder.

link

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 '>' (';' link-param)*
 link-param ::= name '=' quoted-string
 

See RFC 5988 for more information.

Parameters:

link - other link in string representation.

Returns:

the updated builder.

Throws:

IllegalArgumentException - if string representation of URI is invalid.

uri

Link.Builder uri(URI uri)

Set underlying URI template for the link being constructed.

Parameters:

uri - underlying URI for link

Returns:

the updated builder.

uri

Link.Builder uri(String uri)

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

Parameters:

uri - underlying URI for link.

Returns:

the updated builder.

Throws:

IllegalArgumentException - if string representation of URI is invalid.

uriBuilder

Link.Builder uriBuilder(UriBuilder uriBuilder)

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

Parameters:

uriBuilder - underlying URI builder.

Returns:

the updated builder.

rel

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 - relation name.

Returns:

the updated builder.

Throws:

IllegalArgumentException - if the name is null.

title

Link.Builder title(String title)

Convenience method to set a title on this link.

Parameters:

title - title parameter of this link.

Returns:

the updated builder.

Throws:

IllegalArgumentException - if the title is null.

type

Link.Builder type(String type)

Convenience method to set a type on this link.

Parameters:

type - type parameter of this link.

Returns:

the updated builder.

Throws:

IllegalArgumentException - if the type is null.

param

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 - the name of the parameter.

value - the value set for the parameter.

Returns:

the updated builder.

Throws:

IllegalArgumentException - if either the name or value are null.

build

Link build(Object... values)

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

Parameters:

values - parameters used to build underlying URI.

Returns:

newly built link.

Throws:

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.

buildRelativized

Link buildRelativized(URI uri,
                      Object... values)

Finish building this link using the supplied values as URI parameters and relativize the result with respect to a supplied URI. Link relativization is described in UriInfo.relativize(java.net.URI). If the two links do not share a prefix, the relativization step is skipped and this method is equivalent to calling build(java.lang.Object[]).

Parameters:

uri - URI used for relativization.

values - parameters used to build underlying URI.

Returns:

newly built link.

Throws:

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.

IllegalStateException - if the request URI is not available in context.

See Also:

UriInfo.relativize(java.net.URI), UriInfo.getRequestUri()

buildResolved

Link buildResolved(URI uri,
                   Object... values)

Finish building this link using the supplied values as URI parameters and resolve the result using a base URI. If the underlying URI is already absolute, the resolution step is omitted and this method is equivalent to calling build(java.lang.Object[]).

Parameters:

uri - base URI used for resolution.

values - parameters used to build underlying URI.

Returns:

newly built link.

Throws:

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:

UriInfo.resolve(java.net.URI), UriInfo.getBaseUri()