Package org.sdase.commons.server.jackson.hal

Class HalLinkProvider

java.lang.Object
org.sdase.commons.server.jackson.hal.HalLinkProvider
All Implemented Interfaces:
jakarta.ws.rs.core.Feature
public class HalLinkProvider extends Object implements jakarta.ws.rs.core.Feature
Helper utility which is registered as singleton instance in the jersey environment via the JacksonConfigurationBundle. It provides the context-based HALLink for a JAX-RS interface using the PathParam and QueryParam annotations.

Usage: 

 @Path("")
 interface TestApi {
  @Path("/testPath/{testArg}")
  @GET
  String testMethod(@PathParam("testArg") String testArg, @QueryParam("query") query);
 }

 // Get the generated HALLink
 HALLink HalLink = linkTo(methodOn(TestApi.class).testMethod("ResourceID", "detailed")).asHalLink();
 // Get the generated URI
 URI Uri = linkTo(methodOn(TestApi.class).testMethod("ResourceID", "detailed")).asURI();

The example would create the following URI: "baseUri/testPath/ResourceID?query=detailed"

The builder will use the `UriInfo` of the current request context to create absolute URIs. If no request context is available, it will fall back to a simple path without host that does not include any configured root or context path.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    configure(jakarta.ws.rs.core.FeatureContext context)
     
    static HalLinkProvider
    getInstance()
    Returns the singleton instance of the HalLinkProvider
    static LinkResult
    linkTo(Object invocation)
    Creates a HALLink based on JAX-RS annotated parameters of an interface.
    static <T> T
    methodOn(Class<T> type)
    Creates and returns a proxy instance based on the passed type parameter with a method invocation handler, which processes and saves the needed method invocation information in the current thread.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • linkTo

      public static LinkResult linkTo(Object invocation)
      Creates a HALLink based on JAX-RS annotated parameters of an interface. This method requires a second entrypoint with HalLinkInvocationStateUtility.methodOn(Class) to process the annotated JAX-RS interface with the corresponding PathParam and QueryParam and the passed arguments to the proxied method invocation.

      Example: 

       @Path("")
 interface TestApi {
  @Path("/testPath/{testArg}")
  @GET
  String testMethod(@PathParam("testArg") String testArg, @QueryParam("query") query);
 }

 // Get the generated HALLink
 HALLink halLink = linkTo(methodOn(TestApi.class).testMethod("ResourceID", "detailed")).asHalLink();
 // Get the generated URI
 URI uri = linkTo(methodOn(TestApi.class).testMethod("ResourceID", "detailed")).asURI();

      The example would create the following URI: "baseUri/testPath/ResourceID?query=detailed"

      The builder will use the `UriInfo` of the current request context to create absolute URIs. If no request context is available, it will fall back to a simple path without host that does not include any configured root or context path.

      Parameters:
      invocation - the invocation placeholder.
      Returns:
      the generated LinkResult based on the method invocation
      Throws:
      HalLinkMethodInvocationException - - If no method invocation is provided via methodOn(Class)

    • methodOn

      public static <T> T methodOn(Class<T> type)
      Creates and returns a proxy instance based on the passed type parameter with a method invocation handler, which processes and saves the needed method invocation information in the current thread. Parameters in the afterwards called method of the proxy will be used to resolve the URI template of the corresponding method. The called method of the interface must have a return type, which means it should not be of type void.

      After the method invocation of the proxy instance the outer method linkTo(Object) will process the derived information of the invocation to create the HALLink.

      It should be ensured that the parameters are annotated with PathParam or with QueryParam. The passed class type must represent interfaces, not classes or primitive types.

      Type Parameters:
      T - the type parameter based on the passed type.
      Parameters:
      type - the type on which the method should be invoked must be an interface.
      Returns:
      the proxy instance
      Throws:
      HalLinkMethodInvocationException - if the proxy instance could not be created

    • configure

      public boolean configure(jakarta.ws.rs.core.FeatureContext context)
      Specified by:
      configure in interface jakarta.ws.rs.core.Feature

    • getInstance

      public static HalLinkProvider getInstance()
      Returns the singleton instance of the HalLinkProvider
      Returns:
      the HalLinProvider instance