Link Builders

The LinkBuilders interface enables access to two types of links builders, the SystemLinksBuilder and the SingleLinkBuilder. An instance of LinkBuilders is injected into a class field or method parameter using the @Context annotation.

Upon creation, the LinkBuilders automatically detects if the target method being invoked is a resource method or a sub-resource method. The "resource" and "subResource" properties of the builder are initialized accordingly. The link builder interfaces reside in the com.hp.symphony.server.utils package.

Link Builders Overview

The JAX-RS specification defines the UriBuilder interface used to construct a URI from a template, but does not specify any mechanism that can automatically generate all resource links.
Apache Wink provides the SystemLinksBuilder for automatic generation of all the alternate links to a resource, one link per every supported media type. For example, this is useful for an application that produces Atom feeds to include in the feed all the alternate representations of the resource.

Apache Wink provides a mechanism for defining if the generated links should be absolute links or relative to a base URI. For example, links embedded in an Atom feed should be as short as possible in order to optimize the payload size.

The "alt" Query Parameter

Apache Wink supports the special query parameter "alt" that is used to override the value of the request Accept header. When the link builders generate a link that specifies the "type" attribute, then the "alt" query parameter is automatically added to the generated link. This is controlled by setting the symphony.addAltParam key of the configuration properties file or by calling the LinksBuilder#addAltParam() method.

Reference

For more information on the Configuration Properties File refer to section 5.1 Registration and Configuration.

System Links Builder

The SystemLinksBuilder interface enables the generation of all, or a subset of, the system links to a resource or its sub-resources. The links are generated as absolute URIs or as relative to the base URI according to the SystemLinksBuilder state, request information or the application configuration.

Example

@Path("defects/{id}")
public class DefectResource {
@GET
@Produces("application/atom+xml")
public SyndEntry getAtom() {     ...   }
@GET
@Produces("application/json")
public JSONObject getJson() {    ...  }
}
@GET
@Produces("application/xml")
public Defect getXml(@Context LinkBuilders linkBuilders) {     SystemLinksBuilder builder = linkBuilders.systemLinksBuilder();     ListsystemLinks = builder.build(null);     ...   }
}

Explanation

The DefectResource#getXml() method is invoked when a GET request for application/xml is made to /defects/3. The Apache Wink runtime injects an instance of LinkBuilders to the linkBuilder parameter and a new instance of a SystemLinksBuilder is created by invoking the systemLinksBuilder() method.
The call to the build() method of the SystemLinksBuilder generates three alternate links to the DefectResource and the self link:

<link rel="self" href="/defects/3"/>

<link rel="alternate" type="application/json" href="/defects/3"/>

<link rel="alternate" type="application/xml" href="/defects/3"/>

<link rel="alternate" type="application/xtom+xml" href="/defects/3"/>

Single Link Builder

The SingleLinkBuilder interface enables the generation of a single link referencing a resource or a sub-resource, allowing the specification of the 'rel' and 'type' attributes of the generated link. The links are generated as absolute URIs or as relative to the base URI according to the SingleLinkBuilder state, request information or the application configuration.
Generating Absolute or Relative Links
The link builders generate absolute or relative links based on the following algorithm:

Use the value that was passed to the relativize() method of the builder.
If the relativize() method was not called, then use the value of the "relative-urls" query parameter from the request. The value must be either true or false.
If the request does not contain the "relative-urls" query parameter, then use the value of the wink.defaultUrisRelative key set in the application configuration properties file. The value must be either true or false.
If the configuration key does not exist, then use true.