Package org.kiwiproject.jaxrs

Class KiwiStandardResponses

  • public class KiwiStandardResponses
extends Object
    A set of "standard" JAX-RS responses for various HTTP methods. The "standard" is simply Kiwi's view of what should be in responses for common HTTP methods in a REST-based interface using JSON as the primary data format.

    These utilities are intended for use within JAX-RS resource classes.

    One specific thing to note is that the content type is always set to MediaType.APPLICATION_JSON, since the primary use case of this class assumes JSON-based REST interfaces. You can change the content type by using the methods that return a response builder and call one of the type() methods with a MediaType or String argument. This will let you override the default JSON content type in situations where you need to return a different content type.

    See Also:
    KiwiResources, KiwiResponses
    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 Detail

      • KiwiStandardResponses

        public KiwiStandardResponses()

    • Method Detail

      • standardGetResponse

        public static <T> javax.ws.rs.core.Response standardGetResponse​(String identifierField,
                                                                Object identifier,
                                                                @Nullable
                                                                T entity,
                                                                Class<T> entityType)
        Returns a 200 OK response if the entity is non-null. Otherwise, returns a 404 Not Found response with a message stating that the entity having type "entityType" was not found using the given identifier field and value.
        Type Parameters:
        T - the entity type
        Parameters:
        identifierField - the field which identifies the entity being looked up, e.g. "id"
        identifier - the value of the identifier field, e.g. 42 the value of the identifier field, e.g. 42
        entity - the entity or null
        entityType - the entity type
        Returns:
        a 200 or 404 response with application/json content type

      • standardGetResponse

        public static <T> javax.ws.rs.core.Response standardGetResponse​(String identifierField,
                                                                Object identifier,
                                                                Optional<T> entity,
                                                                Class<T> entityType)
        Returns a 200 OK response if the entity contains a value. Otherwise, returns a 404 Not Found response with a message stating that the entity having type "entityType" was not found using the given identifier field and value.
        Type Parameters:
        T - the entity type
        Parameters:
        identifierField - the field which identifies the entity being looked up, e.g. "id"
        identifier - the value of the identifier field, e.g. 42
        entity - an Optional that may or may not contain an entity
        entityType - the entity type
        Returns:
        a 200 or 404 response with application/json content type

      • standardGetResponse

        public static <T> javax.ws.rs.core.Response standardGetResponse​(String identifierField,
                                                                Object identifier,
                                                                @Nullable
                                                                T entity)
        Returns a 200 OK response if the entity is non-null. Otherwise, returns a 404 Not Found response with a message stating that the entity was not found using the given identifier field and value.
        Type Parameters:
        T - the entity type
        Parameters:
        identifierField - the field which identifies the entity being looked up, e.g. "id"
        identifier - the value of the identifier field, e.g. 42
        entity - the entity or null
        Returns:
        a 200 or 404 response with application/json content type

      • standardGetResponse

        public static <T> javax.ws.rs.core.Response standardGetResponse​(String identifierField,
                                                                Object identifier,
                                                                Optional<T> entity)
        Returns a 200 OK response if the entity contains a value. Otherwise, returns a 404 Not Found response with a message stating that the entity was not found using the given identifier field and value.
        Type Parameters:
        T - the entity type
        Parameters:
        identifierField - the field which identifies the entity being looked up, e.g. "id"
        identifier - the value of the identifier field, e.g. 42
        entity - an Optional that may or may not contain an entity
        Returns:
        a 200 or 404 response with application/json content type

      • standardGetResponse

        public static <T> javax.ws.rs.core.Response standardGetResponse​(@Nullable
                                                                T entity,
                                                                String notFoundMessage)
        Returns a 200 OK response if the entity is non-null. Otherwise, returns a 404 Not Found response with the given detail message.
        Type Parameters:
        T - the entity type
        Parameters:
        entity - the entity or null
        notFoundMessage - the specific message to use in the 404 response (if entity is null)
        Returns:
        a 200 or 404 response with application/json content type

      • standardGetResponse

        public static <T> javax.ws.rs.core.Response standardGetResponse​(Optional<T> entity,
                                                                String notFoundMessage)
        Returns a 200 OK response if the entity contains a value. Otherwise, returns a 404 Not Found response with the given detail message.
        Type Parameters:
        T - the entity type
        Parameters:
        entity - an Optional that may or may not contain an entity
        notFoundMessage - the specific message to use in the 404 response (if entity Optional is empty)
        Returns:
        a 200 or 404 response with application/json content type

      • standardPostResponse

        public static javax.ws.rs.core.Response standardPostResponse​(URI location,
                                                             Object entity)
        Returns a 201 Created response having the specified Location header and response entity.
        Parameters:
        location - the value for the Location header
        entity - the new entity
        Returns:
        a 201 response with application/json content type

      • standardPostResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardPostResponseBuilder​(URI location,
                                                                                    Object entity)
        Returns a 201 Created response builder having the specified Location header and response entity.
        Parameters:
        location - the value for the Location header
        entity - the new entity
        Returns:
        a 201 response builder with application/json content type

      • standardPutResponse

        public static javax.ws.rs.core.Response standardPutResponse​(Object entity)
        Returns a 200 OK response having the specified response entity.
        Parameters:
        entity - the updated entity
        Returns:
        a 200 response with application/json content type

      • standardPutResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardPutResponseBuilder​(Object entity)
        Returns a 200 OK response builder having the specified response entity.
        Parameters:
        entity - the updated entity
        Returns:
        a 200 response builder with application/json content type

      • standardPatchResponse

        public static javax.ws.rs.core.Response standardPatchResponse​(Object entity)
        Returns a 200 OK response having the specified response entity.
        Parameters:
        entity - the updated/patched entity
        Returns:
        a 200 response with application/json content type

      • standardPatchResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardPatchResponseBuilder​(Object entity)
        Returns a 200 OK response builder having the specified response entity.
        Parameters:
        entity - the updated/patched entity
        Returns:
        a 200 response builder with application/json content type

      • standardDeleteResponse

        public static javax.ws.rs.core.Response standardDeleteResponse()
        Returns a 204 No Content response for DELETE requests that do not return an entity.
        Returns:
        a 204 response with application/json content type

      • standardDeleteResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardDeleteResponseBuilder()
        Returns a 204 No Content response builder for DELETE requests that do not return an entity.
        Returns:
        a 204 response builder with application/json content type

      • standardDeleteResponse

        public static javax.ws.rs.core.Response standardDeleteResponse​(Object deletedEntity)
        Returns a 200 OK response for DELETE requests that return an entity.
        Parameters:
        deletedEntity - the deleted entity
        Returns:
        a 200 response with application/json content type

      • standardDeleteResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardDeleteResponseBuilder​(Object deletedEntity)
        Returns a 200 OK response builder for DELETE requests that return an entity.
        Parameters:
        deletedEntity - the deleted entity
        Returns:
        a 200 response builder with application/json content type

      • standardBadRequestResponse

        public static javax.ws.rs.core.Response standardBadRequestResponse​(String errorDetails)
        Returns a 400 Bad Request response containing an ErrorMessage entity which uses errorDetails as the detailed error message.
        Parameters:
        errorDetails - the error message to use
        Returns:
        a 400 response with application/json content type

      • standardBadRequestResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardBadRequestResponseBuilder​(String errorDetails)
        Returns a 400 Bad Request response builder containing an ErrorMessage entity which uses errorDetails as the detailed error message.
        Parameters:
        errorDetails - the error message to use
        Returns:
        a 400 response builder with application/json content type

      • standardUnauthorizedResponse

        public static javax.ws.rs.core.Response standardUnauthorizedResponse​(String errorDetails)
        Returns a 401 Unauthorized response containing an ErrorMessage entity which uses errorDetails as the detailed error message.
        Parameters:
        errorDetails - the error message to use
        Returns:
        a 401 response with application/json content type

      • standardUnauthorizedResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardUnauthorizedResponseBuilder​(String errorDetails)
        Returns a 401 Unauthorized response builder containing an ErrorMessage entity which uses errorDetails as the detailed error message.
        Parameters:
        errorDetails - the error message to use
        Returns:
        a 401 response builder with application/json content type

      • standardNotFoundResponse

        public static javax.ws.rs.core.Response standardNotFoundResponse​(String errorDetails)
        Returns a 404 Not Found response containing an ErrorMessage entity which uses errorDetails as the detailed error message.
        Parameters:
        errorDetails - the error message to use
        Returns:
        a 404 response with application/json content type

      • standardNotFoundResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardNotFoundResponseBuilder​(String errorDetails)
        Returns a 404 Not Found response builder containing an ErrorMessage entity which uses errorDetails as the detailed error message.
        Parameters:
        errorDetails - the error message to use
        Returns:
        a 404 response builder with application/json content type

      • standardErrorResponse

        public static javax.ws.rs.core.Response standardErrorResponse​(javax.ws.rs.core.Response.Status status,
                                                              String errorDetails)
        Returns a response having the given status and an ErrorMessage entity which uses errorDetails as the detailed error message.

        Does not verify that the given status is actually an error status.

        Parameters:
        status - the error status to use
        errorDetails - the error message to use
        Returns:
        a response with the given status code and application/json content type

      • standardErrorResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardErrorResponseBuilder​(javax.ws.rs.core.Response.Status status,
                                                                                     String errorDetails)
        Returns a response builder having the given status and an ErrorMessage entity which uses errorDetails as the detailed error message.

        Does not verify that the given status is actually an error status.

        Parameters:
        status - the error status to use
        errorDetails - the error message to use
        Returns:
        a response builder with the given status code and application/json content type

      • standardAcceptedResponse

        public static javax.ws.rs.core.Response standardAcceptedResponse​(Object entity)
        Returns a 202 Accepted response having the specified response entity.

        This generally applies to POST, PUT, and PATCH requests that might take a while and are processed asynchronously.

        Parameters:
        entity - the accepted entity
        Returns:
        a 202 response with application/json content type

      • standardAcceptedResponseBuilder

        public static javax.ws.rs.core.Response.ResponseBuilder standardAcceptedResponseBuilder​(Object entity)
        Returns a 202 Accepted response builder having the specified response entity.

        This generally applies to POST, PUT, and PATCH requests that might take a while and are processed asynchronously.

        Parameters:
        entity - the accepted entity
        Returns:
        a 202 response builder with application/json content type