Package org.kiwiproject.jaxrs

Class KiwiStandardResponses

java.lang.Object
org.kiwiproject.jaxrs.KiwiStandardResponses
public final class KiwiStandardResponses extends Object
A set of "standard" Jakarta REST 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 Jakarta REST 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:
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.

  • Method Details

    • standardGetResponse

      public static <T> jakarta.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> jakarta.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> jakarta.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> jakarta.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> jakarta.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> jakarta.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 jakarta.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 jakarta.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 response builder with status code 201 and application/json content type

    • standardPutResponse

      public static jakarta.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 jakarta.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 response builder with status code 200 and application/json content type

    • standardPatchResponse

      public static jakarta.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 jakarta.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 response builder with status code 200 and application/json content type

    • standardDeleteResponse

      public static jakarta.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 jakarta.ws.rs.core.Response.ResponseBuilder standardDeleteResponseBuilder()
      Returns a 204 No Content response builder for DELETE requests that do not return an entity.
      Returns:
      a response builder with status code 204 and application/json content type

    • standardDeleteResponse

      public static jakarta.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 jakarta.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 response builder with a 200 status code and application/json content type

    • standardBadRequestResponse

      public static jakarta.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 jakarta.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 response builder with status code 400 and application/json content type

    • standardUnauthorizedResponse

      public static jakarta.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 jakarta.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 response builder with status code 401 and application/json content type

    • standardNotFoundResponse

      public static jakarta.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 jakarta.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 response builder with status code 404 and application/json content type

    • standardInternalServerErrorResponse

      public static jakarta.ws.rs.core.Response standardInternalServerErrorResponse(String errorDetails)
      Returns a 500 Internal Server Error response containing an ErrorMessage entity which uses errorDetails as the detailed error message.
      Parameters:
      errorDetails - the error message to use
      Returns:
      a 500 Internal Server Error response with application/json content type

    • standardInternalServerErrorResponseBuilder

      public static jakarta.ws.rs.core.Response.ResponseBuilder standardInternalServerErrorResponseBuilder(String errorDetails)
      Returns a response builder with 500 Internal Server Error status and an ErrorMessage entity which uses errorDetails as the detailed error message.
      Parameters:
      errorDetails - the error message to use
      Returns:
      a response builder with a 500 status code and application/json content type

    • standardErrorResponse

      public static jakarta.ws.rs.core.Response standardErrorResponse(jakarta.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.

      Verifies that the given status is actually an error status (4xx or 5xx).

      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
      Throws:
      IllegalArgumentException - if the given status is not a client or server error

    • standardErrorResponseBuilder

      public static jakarta.ws.rs.core.Response.ResponseBuilder standardErrorResponseBuilder(jakarta.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.

      Verifies that the given status is actually an error status (4xx or 5xx).

      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
      Throws:
      IllegalArgumentException - if the given status is not a client or server error

    • standardAcceptedResponse

      public static jakarta.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 jakarta.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 response builder with status code 202 and application/json content type