Chapter 13. Declarative Hyperlinking

To use Declarative Linking you need to add jersey-declarative-linking module to your pom.xml file:

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-declarative-linking</artifactId>
    <version>2.29</version>
</dependency>

Additionally you will need to add the following dependencies, if you are not deploying into a container that is already including them:

<dependency>
    <groupId>javax.el</groupId>
    <artifactId>javax.el-api</artifactId>
    <version>3.0.3</version>
</dependency>

<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>javax.el</artifactId>
    <version>3.0.2</version>
</dependency>

If you're not using Maven make sure to have all needed dependencies (see jersey-declarative-linking) on the classpath.

Links are added to representations using the @InjectLink annotation on entity class fields. The Jersey runtime is responsible for injecting the appropriate URI into the field prior to serialization by a message body writer. E.g. consider the following resource and entity classes:

@Path("widgets")
public class WidgetsResource {
    @GET
    public Widgets get() {
        return new Widgets();
    }
}

public class Widgets {
    @InjectLink(resource=WidgetsResource.class)
    URI u;
}

After a call toWidgetsResource#get, the Jersey runtime will inject the value "/context/widgets" ^[1] into the returned Widgets instance. If an absolute URI is desired instead of an absolute path then the annotation can be changed to @InjectLink(resource=WidgetsResource.class, style=ABSOLUTE).

The above usage works nicely when there's already a URI template on a class that you want to reuse. If there's no such template available then you can use a literal value instead of a reference. E.g. the following is equivalent to the earlier example: @InjectLink(value="widgets", style=ABSOLUTE).

You can inject multiple links into an array or a List collection type. E.g.:

@InjectLinks({@InjectLink(resource=WidgetsResource.class, rel = "self")})
List<Link> links

The field doesn't need to be initialized. However, if it already contains a collection with manually created links, then it will merge those with the generated links into a new collection which then replaces the field value.

As an alternative to defining the links in the entity class, they can also be defined in the resource classes by annotating the resource methods with @ProvideLink. This has the benefit, that the target method is already known and doesn't need to be referenced. Other than that it has the same parameters and behaviors as @InjectLink. The entity classes need to have a field annotated with @InjectLinks, which can be empty.

The @ProvideLink annotation can be repeated to add links to different entities using different options. Entities are defined via the value property. If the entities are similar in structure they can also declared as an array. @ProvideLink also works with class hierarchies, e.g., contributions defined for a superclass will also be injected into the derived classes (interfaces are not supported).

@ProvideLink(value = Order.class,rel = "self",
     bindings = @Binding(name = "orderId", value = "${instance.id}"))
@ProvideLink(value = PaymentConfirmation.class, rel = "order",
     bindings = @Binding(name = "orderId", value = "${instance.orderId}"))
@GET
@Path("/{orderId}")
public Response get(@PathParam("orderId") String orderId)

Referenced or literal templates may contain parameters. Two forms of parameters are supported:

Parameter values can be extracted from three implicit beans:

By default URI template parameter values are extracted from the implicit instance bean, i.e. the following two annotations are equivalent:

@InjectLink("widgets/{id}")

@InjectLink("widgets/${instance.id}")

The source for URI template parameter values can be changed using the @Binding annotation, E.g. the following three annotations are equivalent:

@InjectLink(value="widgets/{id}", bindings={
    @Binding(name="id" value="${resource.id}"}
)

@InjectLink(value="widgets/{value}", bindings={
    @Binding("${resource.id}")})
@InjectLink("widgets/${resource.id}")

Link value injection can be made conditional by use of the condition property. The value of this property is a boolean EL expression and a link will only be injected if the condition expression evaluates to true. E.g.:

@InjectLink(value="widgets/${instance.id}/offers",
    condition="${instance.offers}")
URI offers;

In the above, a URI will only be injected into the offers field if the offers property of the instance is true.

HTTP Link headers can also be added to responses using annotations. Instead of annotating the fields of an entity class with @InjectLink, you instead annotate the entity class itself with @InjectLinks. E.g.:

@InjectLinks(
    @InjectLink(value="widgets/${resource.nextId}", rel="next")
)

The above would insert a HTTP Link header into any response whose entity was thus annotated. The @InjectLink annotation contains properties that map to the parameters of the HTTP Link header. The above specifies the link relation as next. All properties of the @InjectLink annotation may be used as described above.

Multiple link headers can be added by use of the @InjectLinks annotation which can contain multiple @InjectLink annotations.

Resource links via @ProvideLink are currently not supported for link headers.

By default, Jersey will try to recursively find all @InjectionLink annotations in the members of your object unless this member is annotated with @XmlTransient. But in some cases, you might want to control which member will be introspected regardless of the @XmlTransient annotation. You can prevent Jersey to look into an object by adding @InjectLinkNoFollow to a field.

@InjectLinkNoFollow
Context context;

The @ProvideLink annotation can be used as a meta-annotation, i.e., annotating your own annotation. This enables you to create custom annotations to reuse @ProvideLink configurations instead of copy pasting them on each method. There is a special marker class ProvideLink.InheritFromAnnotation that can be used in place of the actual entity class, this indicates that the Class<?> value() from the custom annotation should be used instead. Repeated annotations are currently unsupported for this feature. Also the Class<?> value() method must return a single class and not an array of classes.

Here is an example (getter/setter omitted for brevity) of how a meta annotation can be used. The example app uses a Page class as a base class for all entities that contain paged data.

public class Page {
    private int number;

    private int size;

    private boolean isPreviousPageAvailable;

    private boolean isNextPageAvailable;

    @InjectLinks
    private List<Link> links;
}

Instead of duplicating the @ProvideLink annotations for the next and previous links on every method, we create the following @PageLinks annotation.

@ProvideLink(value = ProvideLink.InheritFromAnnotation.class, rel = "next",
    bindings = {
        @Binding(name = "page", value = "${instance.number + 1}"),
        @Binding(name = "size", value = "${instance.size}"),
    }, condition = "${instance.nextPageAvailable}")
@ProvideLink(value = ProvideLink.InheritFromAnnotation.class, rel = "prev",
    bindings = {
        @Binding(name = "page", value = "${instance.number - 1}"),
        @Binding(name = "size", value = "${instance.size}"),
    }, condition = "${instance.previousPageAvailable}")
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface PageLinks {
  Class<?> value();
}

The annotation can the then be used on the resource methods with the actual entity class as value.

@PageLinks(OrderPage.class)
@GET
public Response list(@QueryParam("page") @DefaultValue("0") int page,
                     @QueryParam("size") @DefaultValue("20") int size)

The entity just extends from Page and declares its content. It is necessary to use distinct classes instead of just a generic page to have a unique target for @ProvideLink, otherwise every method annotated with @ProvideLink(value=Page.class) would contribute to the entity.

public class OrderPage extends Page {
    private List<Order> orders;
}

In order to add the Declarative Linking feature register DeclarativeLinkingFeature

// Create JAX-RS application.
final Application application = new ResourceConfig()
        .packages("org.glassfish.jersey.examples.linking")
        .register(DeclarativeLinkingFeature.class);