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

Class HalLinkProvider

  • All Implemented Interfaces:
    javax.ws.rs.core.Feature
    public class HalLinkProvider
extends java.lang.Object
implements javax.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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean configure​(javax.ws.rs.core.FeatureContext context)  
      static HalLinkProvider getInstance()
      Returns the singleton instance of the HalLinkProvider
      static LinkResult linkTo​(java.lang.Object invocation)
      Creates a HALLink based on JAX-RS annotated parameters of an interface.
      static <T> T methodOn​(java.lang.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 Detail

      • linkTo

        public static LinkResult linkTo​(java.lang.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​(java.lang.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​(javax.ws.rs.core.FeatureContext context)
        Specified by:
        configure in interface javax.ws.rs.core.Feature

      • getInstance

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