Package com.sodius.oslc.core.util

Class OslcStreams

java.lang.Object
com.sodius.oslc.core.util.OslcStreams
public class OslcStreams extends Object
Transforms an OSLC entity into a stream and vice-verse.

This capability is usually the responsibility of the JAX-RS framework. However there are cases where the list of providers used or the priority of those providers cannot be controlled. This class uses a fixed list of providers that does not depend on the ones registered at JAX-RS level, thus complete independence on the deployment.

The providers used here are the ones that can handle OSLC resources (service provider catalog, change request, etc.) for the following well known formats:

  • application/rdf+xml
  • application/xml
  • text/xml
  • application/json
  • text/turtle
  • application/x-oslc-compact+xml
  • application/x-oslc-compact+json

Jakarta JSON providers are also registered, as they are used by some OSLC services, to handle JsonObject and JsonArray instances for following formats:

  • application/json
  • application/javascript

Any other type of entity or format is unsupported and methods will throw an exception, as it's considered a developer error to use OslcStreams in such case.

Since:
1.13.0

  • Method Details

    • toEntity

      public static <T> T toEntity(Class<T> type, HttpServletRequest request, HttpHeaders headers) throws WebApplicationException
      Reads a type from the request stream. This method can be used for implementing a JAX-RS PUT or POST service that must extract an entity from the stream of the request. Both the servlet request and headers should be injected as fields of the service class.
      Type Parameters:
      T - the type of entity to read.
      Parameters:
      type - the type that is to be read from the entity stream.
      request - the servlet request from which an entity must be read.
      headers - the HTTP headers associated with HTTP entity.
      Returns:
      the entity that was read from the stream. This method never returns null; an exception is raised if the entity cannot be deserialized.
      Throws:
      WebApplicationException - if the underlying MessageBodyReader provider raises one or a I/O error occurs. The exception embeds a Bad Request response if the entity cannot be deserialized from the request input stream, e.g. when the stream is empty or contains bytes that are not valid regarding the content type.
      IllegalArgumentException - if either the type or format is not supported by this class.
      See Also:

    • toEntity

      public static <T> T toEntity(Class<T> type, Type genericType, HttpServletRequest request, HttpHeaders headers) throws WebApplicationException
      Reads a type from the request stream. This method can be used for implementing a JAX-RS PUT or POST service that must extract an entity from the stream of the request. Both the servlet request and headers should be injected as fields of the service class.
      Type Parameters:
      T - the type of entity to read.
      Parameters:
      type - the type that is to be read from the entity stream.
      genericType - the genericType parameter gives the java.lang.reflect.Type of the object that should be produced.
      request - the servlet request from which an entity must be read.
      headers - the HTTP headers associated with HTTP entity.
      Returns:
      the entity that was read from the stream. This method never returns null; an exception is raised if the entity cannot be deserialized.
      Throws:
      WebApplicationException - if the underlying MessageBodyReader provider raises one or a I/O error occurs. The exception embeds a Bad Request response if the entity cannot be deserialized from the request input stream, e.g. when the stream is empty or contains bytes that are not valid regarding the content type.
      IllegalArgumentException - if either the type or format is not supported by this class.
      Since:
      3.0.0
      See Also:

    • toEntity

      public static <T> T toEntity(Class<T> type, InputStream entityStream, MediaType mediaType) throws IOException
      Reads a type from the request stream. This method can be used on client side to extract an entity from the stream of a response.
      Type Parameters:
      T - the type of entity to read.
      Parameters:
      type - the type that is to be read from the entity stream.
      entityStream - the stream containing an entity to de-serialize.
      mediaType - the format of the stream.
      Returns:
      the type that was read from the stream.
      Throws:
      IOException - if an IO error arises or to wrap an exception raised by the underlying MessageBodyReader provider.
      IllegalArgumentException - if either the type or format is not supported by this class.
      See Also:

    • toEntity

      public static <T> T toEntity(Class<T> type, Type genericType, InputStream entityStream, MediaType mediaType) throws IOException
      Reads a type from the request stream. This method can be used on client side to extract an entity from the stream of a response.
      Type Parameters:
      T - the type of entity to read.
      Parameters:
      type - the type that is to be read from the entity stream.
      genericType - the genericType parameter gives the java.lang.reflect.Type of the object that should be produced.
      entityStream - the stream containing an entity to de-serialize.
      mediaType - the format of the stream.
      Returns:
      the type that was read from the stream.
      Throws:
      IOException - if an IO error arises or to wrap an exception raised by the underlying MessageBodyReader provider.
      IllegalArgumentException - if either the type or format is not supported by this class.
      Since:
      3.0.0
      See Also:

    • toStream

      public static StreamingOutput toStream(Object entity, HttpServletRequest request, HttpHeaders headers)
      Converts an entity to a StreamingOutput, ready to serialize into a response. This method can be used for implementing a JAX-RS service that must respond with an entity. Both the servlet request and headers should be injected as fields of the service class.
      Parameters:
      entity - the instance to write.
      request - the servlet request to inject into providers.
      headers - the HTTP headers to inject into providers.
      Returns:
      a StreamingOutput instance ready to be written in an output stream.
      Throws:
      IllegalArgumentException - if either the entity type or media type is not supported by this class.
      See Also:

    • toStream

      public static StreamingOutput toStream(Object entity, MediaType contentType)
      Converts an entity to a StreamingOutput, ready to serialize into a request. This method can be used on client side to serialize an entity to send as request.
      Parameters:
      entity - the instance to write.
      contentType - the format to use for serialization.
      Returns:
      a StreamingOutput instance ready to be written in an output stream.
      Throws:
      IllegalArgumentException - if either the entity type or media type is not supported by this class.
      See Also: