javax.ws.rs.core

## Class Link

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

- Direct Known Subclasses:
    LinkImpl

      public abstract 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. Links in responses can be followed by creating an `Invocation.Builder` or a `WebTarget`.

  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)`, `Client.target(javax.ws.rs.core.Link)`, `Response.getLink(java.lang.String)`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Constructor and Description
    `Link()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Link.Builder` | `fromLink(Link link)` Create a new builder instance initialized from another link.
    `static Link.Builder` | `fromMethod(Class<?> resource, String method)` Convenience method to build a link from a resource.
    `static Link.Builder` | `fromPath(String path)` Convenience method to build a link from a path.
    `static Link.Builder` | `fromResource(Class<?> resource)` Convenience method to build a link from a resource.
    `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.
    `static Link.Builder` | `fromUriBuilder(UriBuilder uriBuilder)` Create a new builder instance initialized from a URI builder.
    `abstract Map<String,String>` | `getParams()` Returns an immutable map that includes all the link parameters defined on this link.
    `abstract String` | `getRel()` Returns the value associated with the link `rel` param, or `null` if this param is not specified.
    `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.
    `abstract String` | `getTitle()` Returns the value associated with the link `title` param, or `null` if this param is not specified.
    `abstract String` | `getType()` Returns the value associated with the link `type` param, or `null` if this param is not specified.
    `abstract URI` | `getUri()` Returns the underlying URI associated with this link.
    `abstract UriBuilder` | `getUriBuilder()` Convenience method that returns a `UriBuilder` initialized with this link's underlying URI.
    `abstract 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, equals, finalize, getClass, hashCode, 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 abstract URI getUri()

      Returns the underlying URI associated with this link.
      Returns:
        underlying URI.

    - #### getUriBuilder

          public abstract UriBuilder getUriBuilder()

      Convenience method that returns a `UriBuilder` initialized with this link's underlying URI.
      Returns:
        UriBuilder initialized using underlying URI.

    - #### getRel

          public abstract 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 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:
        relation types as list of strings or empty list.

    - #### getTitle

          public abstract 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 abstract 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 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:
        immutable map of link parameters.

    - #### toString

          public abstract 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)

      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.
      See Also:
        `Link.Builder.link(java.lang.String)`

    - #### fromUri

          public static Link.Builder fromUri(URI uri)

      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)

      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`.

    - #### fromUriBuilder

          public static Link.Builder fromUriBuilder(UriBuilder uriBuilder)

      Create a new builder instance initialized from a URI builder.
      Parameters:
        `uriBuilder` - instance of URI builder.
      Returns:
        a new builder.

    - #### 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.

    - #### fromPath

          public static Link.Builder fromPath(String path)

      Convenience method to build a link from a path. Equivalent to `fromUriBuilder(UriBuilder.fromPath(path))`.
      Parameters:
        `path` - a URI path that will be used to initialize the Link, may contain URI template parameters.
      Returns:
        a new Link.Builder.
      Throws:
        `IllegalArgumentException` - if path is `null`.

    - #### fromResource

          public static Link.Builder fromResource(Class<?> resource)

      Convenience method to build a link from a resource. Equivalent to `Link.fromUriBuilder(`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` - a root resource whose `Path` value will be used to initialize the builder.
      Returns:
        a new `link builder` instance.
      Throws:
        `IllegalArgumentException` - if resource is not annotated with `Path` or resource is `null`.
      See Also:
        `UriInfo.getBaseUri()`

    - #### fromMethod

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

      Convenience method to build a link from a resource. Equivalent to `Link.fromUriBuilder(`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` - the resource containing the method.
        `method` - the name of the method whose `Path` value will be used to obtain the path to append.
      Returns:
        the updated Link.Builder.
      Throws:
        `IllegalArgumentException` - if resource or method is `null`, or there is more than or less than one variant of the method annotated with `Path`.
      See Also:
        `UriInfo.getBaseUri()`

Copyright © 2014. All Rights Reserved.