Package org.kiwiproject.jaxrs

Class KiwiResources

  • public class KiwiResources
extends Object
    Static utilities for use in JAX-RS resource classes. Contains utilities for verifying entities (e.g. obtained from a service or data access class), factories for creating new responses, and for validating query parameters.
    See Also:
    KiwiResponses, KiwiStandardResponses
    API Note:
    Some methods in this class accept Optional arguments, which we know is considered a code smell by various people and analysis tools such as IntelliJ's inspections, Sonar, etc. However, we also like to return Optional from data access code (e.g. a DAO "findById" method where the object might not exist if it was recently deleted). In such cases, we can simply take the Optional returned by those finder methods and pass them directly to the utilities provided here without needing to call additional methods, for example without needing to call orElse(null). So, we acknowledge that it is generally not good to accept Optional arguments, but we're trading off convenience in this class against "generally accepted" practice.

    • Constructor Summary

      Constructors 
      Constructor Description
      KiwiResources()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static javax.ws.rs.core.Response createdResponse​(URI location, Object entity)
      Builds a Response with 201 Created status and a specified Location header and entity.
      static javax.ws.rs.core.Response.ResponseBuilder createdResponseBuilder​(URI location, Object entity)
      Creates a Response.ResponseBuilder having 201 Created status and a specified Location header and entity.
      static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status, Object entity)
      Builds a Response having the given status and entity.
      static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status, Object entity, String contentType)
      Builds a Response having the given status, entity, and content type.
      static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status, Object entity, Map<String,​Object> singleValuedHeaders)
      Builds a Response having the given status, entity, and (single-valued) headers.
      static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status, Object entity, javax.ws.rs.core.MultivaluedMap<String,​Object> headers)
      Builds a Response having the given status, entity, and headers.
      static javax.ws.rs.core.Response newResponseBufferingEntityFrom​(javax.ws.rs.core.Response originalResponse)
      Convenience wrapper around Response.fromResponse(Response) that also buffers the response entity by calling Response.bufferEntity() on the given response.
      static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status, Object entity)
      Creates a Response.ResponseBuilder having the given status and entity.
      static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status, Object entity, String contentType)
      Creates a Response.ResponseBuilder having the given status, entity, and content type.
      static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status, Object entity, Map<String,​Object> singleValuedHeaders)
      Creates a Response.ResponseBuilder having the given status, entity, and (single-valued) headers.
      static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status, Object entity, javax.ws.rs.core.MultivaluedMap<String,​Object> headers)
      Creates a Response.ResponseBuilder having the given status, entity, and headers.
      static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilderBufferingEntityFrom​(javax.ws.rs.core.Response originalResponse)
      Convenience wrapper around Response.fromResponse(Response) that also buffers the response entity by calling Response.bufferEntity() on the given response.
      static javax.ws.rs.core.Response okResponse​(Object entity)
      Builds a Response with 200 OK status and a specified entity.
      static javax.ws.rs.core.Response.ResponseBuilder okResponseBuilder​(Object entity)
      Creates a Response.ResponseBuilder having 200 OK status and a specified entity.
      static int validateIntParameter​(Map<String,​Object> parameters, String parameterName)
      Checks whether parameters contains parameter named parameterName that is an integer or something that can be converted into an integer.
      static long validateLongParameter​(Map<String,​Object> parameters, String parameterName)
      Checks whether parameters contains parameter named parameterName that is a long or something that can be converted into a long.
      static <T> T verifyExistence​(Optional<T> resourceEntity)
      Verifies that resourceEntity contains a value, otherwise throws a JaxrsNotFoundException.
      static <T> T verifyExistence​(Optional<T> resourceEntity, Class<T> entityType, Object identifier)
      Verifies that resourceEntity contains a value, otherwise throws JaxrsNotFoundException.
      static <T> T verifyExistence​(Optional<T> resourceEntity, String notFoundMessage)
      Verifies that resourceEntity contains a value, otherwise throws JaxrsNotFoundException.
      static <T> void verifyExistence​(T resourceEntity)
      Verifies that resourceEntity is not null, otherwise throws a JaxrsNotFoundException.
      static <T> void verifyExistence​(T resourceEntity, Class<T> entityType, Object identifier)
      Verifies that resourceEntity is not null, otherwise throws a JaxrsNotFoundException.
      static <T> void verifyExistence​(T resourceEntity, String notFoundMessage)
      Verifies that resourceEntity is not null, otherwise throws JaxrsNotFoundException.

    • Constructor Detail

      • KiwiResources

        public KiwiResources()

    • Method Detail

      • verifyExistence

        public static <T> void verifyExistence​(T resourceEntity)
        Verifies that resourceEntity is not null, otherwise throws a JaxrsNotFoundException.
        Type Parameters:
        T - the object type
        Parameters:
        resourceEntity - the resource entity to verify
        Throws:
        JaxrsNotFoundException - if the entity is null

      • verifyExistence

        public static <T> T verifyExistence​(Optional<T> resourceEntity)
        Verifies that resourceEntity contains a value, otherwise throws a JaxrsNotFoundException.
        Type Parameters:
        T - the object type
        Parameters:
        resourceEntity - the resource entity to verify
        Returns:
        the entity if the Optional contains a value
        Throws:
        JaxrsNotFoundException - if the entity is empty

      • verifyExistence

        public static <T> void verifyExistence​(T resourceEntity,
                                       Class<T> entityType,
                                       Object identifier)
        Verifies that resourceEntity is not null, otherwise throws a JaxrsNotFoundException.
        Type Parameters:
        T - the object type
        Parameters:
        resourceEntity - the resource entity to verify
        entityType - a Class representing the entity type, used in error messages
        identifier - the unique identifier of the resource identity
        Throws:
        JaxrsNotFoundException - if the entity is null

      • verifyExistence

        public static <T> T verifyExistence​(Optional<T> resourceEntity,
                                    Class<T> entityType,
                                    Object identifier)
        Verifies that resourceEntity contains a value, otherwise throws JaxrsNotFoundException.
        Type Parameters:
        T - the object type
        Parameters:
        resourceEntity - the resource entity to verify
        entityType - a Class representing the entity type, used in error messages
        identifier - the unique identifier of the resource identity
        Returns:
        the entity if the Optional contains a value
        Throws:
        JaxrsNotFoundException - if the entity is empty

      • verifyExistence

        public static <T> void verifyExistence​(T resourceEntity,
                                       String notFoundMessage)
        Verifies that resourceEntity is not null, otherwise throws JaxrsNotFoundException.
        Type Parameters:
        T - the object type
        Parameters:
        resourceEntity - the resource entity to verify
        notFoundMessage - the error message to include in the response entity
        Throws:
        JaxrsNotFoundException - if the entity is null

      • verifyExistence

        public static <T> T verifyExistence​(Optional<T> resourceEntity,
                                    String notFoundMessage)
        Verifies that resourceEntity contains a value, otherwise throws JaxrsNotFoundException.
        Type Parameters:
        T - the object type
        Parameters:
        resourceEntity - the resource entity to verify
        notFoundMessage - the error message to include in the response entity
        Returns:
        the entity if the Optional contains a value
        Throws:
        JaxrsNotFoundException - if the entity is empty

      • newResponse

        public static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status,
                                                    Object entity)
        Builds a Response having the given status and entity.
        Parameters:
        status - the response status
        entity - the response entity
        Returns:
        a response

      • newResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status,
                                                                           Object entity)
        Creates a Response.ResponseBuilder having the given status and entity. You can further modify the returned build, e.g. add custom headers, set cookies. etc.
        Parameters:
        status - the response status
        entity - the response entity
        Returns:
        a response builder

      • newResponse

        public static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status,
                                                    Object entity,
                                                    String contentType)
        Builds a Response having the given status, entity, and content type.
        Parameters:
        status - the response status
        entity - the response entity
        contentType - the value for the Content-Type header
        Returns:
        a response

      • newResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status,
                                                                           Object entity,
                                                                           String contentType)
        Creates a Response.ResponseBuilder having the given status, entity, and content type. You can further modify the returned build, e.g. add custom headers, set cookies. etc.
        Parameters:
        status - the response status
        entity - the response entity
        contentType - the value for the Content-Type header
        Returns:
        a response builder

      • newResponse

        public static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status,
                                                    Object entity,
                                                    Map<String,​Object> singleValuedHeaders)
        Builds a Response having the given status, entity, and (single-valued) headers.
        Parameters:
        status - the response status
        entity - the response entity
        singleValuedHeaders - map containing single-valued response headers
        Returns:
        a response

      • newResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status,
                                                                           Object entity,
                                                                           Map<String,​Object> singleValuedHeaders)
        Creates a Response.ResponseBuilder having the given status, entity, and (single-valued) headers. You can further modify the returned build, e.g. add custom headers, set cookies. etc.
        Parameters:
        status - the response status
        entity - the response entity
        singleValuedHeaders - map containing single-valued response headers
        Returns:
        a response builder

      • newResponse

        public static javax.ws.rs.core.Response newResponse​(javax.ws.rs.core.Response.Status status,
                                                    Object entity,
                                                    javax.ws.rs.core.MultivaluedMap<String,​Object> headers)
        Builds a Response having the given status, entity, and headers.
        Parameters:
        status - the response status
        entity - the response entity
        headers - map containing response headers
        Returns:
        a response

      • newResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilder​(javax.ws.rs.core.Response.Status status,
                                                                           Object entity,
                                                                           javax.ws.rs.core.MultivaluedMap<String,​Object> headers)
        Creates a Response.ResponseBuilder having the given status, entity, and headers. You can further modify the returned build, e.g. add custom headers, set cookies. etc.
        Parameters:
        status - the response status
        entity - the response entity
        headers - map containing response headers
        Returns:
        a response builder

      • createdResponse

        public static javax.ws.rs.core.Response createdResponse​(URI location,
                                                        Object entity)
        Builds a Response with 201 Created status and a specified Location header and entity.
        Parameters:
        location - the value for the Location header
        entity - the response entity
        Returns:
        a 202 Created response

      • createdResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder createdResponseBuilder​(URI location,
                                                                               Object entity)
        Creates a Response.ResponseBuilder having 201 Created status and a specified Location header and entity. You can further modify the returned build, e.g. add custom headers, set cookies. etc.
        Parameters:
        location - the value for the Location header
        entity - the response entity
        Returns:
        a 201 Created response builder

      • okResponse

        public static javax.ws.rs.core.Response okResponse​(Object entity)
        Builds a Response with 200 OK status and a specified entity.
        Parameters:
        entity - the response entity
        Returns:
        a 200 OK response

      • okResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder okResponseBuilder​(Object entity)
        Creates a Response.ResponseBuilder having 200 OK status and a specified entity. You can further modify the returned build, e.g. add custom headers, set cookies. etc.
        Parameters:
        entity - the response entity
        Returns:
        a 200 OK response builder

      • newResponseBufferingEntityFrom

        public static javax.ws.rs.core.Response newResponseBufferingEntityFrom​(javax.ws.rs.core.Response originalResponse)
        Convenience wrapper around Response.fromResponse(Response) that also buffers the response entity by calling Response.bufferEntity() on the given response. This returns a Response instead of a response builder.

        NOTE: The reason this method exists is due to the note in the Javadoc of Response.fromResponse(Response) which states: "Note that if the entity is backed by an un-consumed input stream, the reference to the stream is copied. In such case make sure to buffer the entity stream of the original response instance before passing it to this method." So, rather than having the same boilerplate code in various locations (or as we've seen many times, people forgetting to buffer the response entity), this provides a single method to perform the same logic and ensure the entity is buffered.

        Parameters:
        originalResponse - a Response from which the status code, entity and response headers will be copied.
        Returns:
        a new response
        See Also:
        Response.fromResponse(Response), Response.bufferEntity()

      • newResponseBuilderBufferingEntityFrom

        public static javax.ws.rs.core.Response.ResponseBuilder newResponseBuilderBufferingEntityFrom​(javax.ws.rs.core.Response originalResponse)
        Convenience wrapper around Response.fromResponse(Response) that also buffers the response entity by calling Response.bufferEntity() on the given response.

        NOTE: The reason this method exists is due to the note in the Javadoc of Response.fromResponse(Response) which states: "Note that if the entity is backed by an un-consumed input stream, the reference to the stream is copied. In such case make sure to buffer the entity stream of the original response instance before passing it to this method." So, rather than having the same boilerplate code in various locations (or as we've seen many times, people forgetting to buffer the response entity), this provides a single method to perform the same logic and ensure the entity is buffered.

        Parameters:
        originalResponse - a Response from which the status code, entity and response headers will be copied.
        Returns:
        a new response builder
        See Also:
        Response.fromResponse(Response), Response.bufferEntity()

      • validateIntParameter

        public static int validateIntParameter​(Map<String,​Object> parameters,
                                       String parameterName)
        Checks whether parameters contains parameter named parameterName that is an integer or something that can be converted into an integer.
        Parameters:
        parameters - the parameters to check
        parameterName - name of the parameter which should be present
        Returns:
        the int value of the validated parameter
        Throws:
        JaxrsBadRequestException - if the specified parameter is not present, or is not an integer

      • validateLongParameter

        public static long validateLongParameter​(Map<String,​Object> parameters,
                                         String parameterName)
        Checks whether parameters contains parameter named parameterName that is a long or something that can be converted into a long.
        Parameters:
        parameters - the parameters to check
        parameterName - name of the parameter which should be present
        Returns:
        the long value of the validated parameter
        Throws:
        JaxrsBadRequestException - if the specified parameter is not present, or is not long