Package org.apache.juneau.serializer

Class Serializer

java.lang.Object
org.apache.juneau.Context
org.apache.juneau.BeanContextable
org.apache.juneau.BeanTraverseContext
org.apache.juneau.serializer.Serializer
All Implemented Interfaces:
AnnotationProvider
Direct Known Subclasses:
OutputStreamSerializer, Serializer.Null, SerializerSet.Inherit, SerializerSet.NoInherit, WriterSerializer
public class Serializer extends BeanTraverseContext
Parent class for all Juneau serializers.
Description

Base serializer class that serves as the parent class for all serializers.

The purpose of this class is:

  • Maintain a read-only configuration state of a serializer.
  • Create session objects used for serializing POJOs (i.e. SerializerSession).
  • Provide convenience methods for serializing POJOs without having to construct session objects.

Subclasses should (but are not required to) extend directly from OutputStreamSerializer or WriterSerializer depending on whether it's a stream or character based serializer.

Subclasses must implement parsing via one of the following methods:


Notes:
  • This class is thread safe and reusable.
See Also:

  • Constructor Details

  • Method Details

    • create

      public static Serializer.Builder create()
      Creates a new builder for this object.
      Returns:
      A new builder.

    • createSerializerBuilder

      public static Serializer.Builder createSerializerBuilder(Class<? extends Serializer> c)
      Instantiates a builder of the specified serializer class.

      Looks for a public static method called create that returns an object that can be passed into a public or protected constructor of the class.

      Parameters:
      c - The builder to create.
      Returns:
      A new builder.

    • copy

      public Serializer.Builder copy()
      Description copied from class: Context
      Creates a builder from this context object.

      Builders are used to define new contexts (e.g. serializers, parsers) based on existing configurations.

      Specified by:
      copy in class BeanTraverseContext
      Returns:
      A new Builder object.

    • createSession

      public SerializerSession.Builder createSession()
      Description copied from class: Context
      Create a session builder based on the properties defined on this context.

      Use this method for creating sessions where you want to override basic settings. Otherwise, use Context.getSession() directly.

      Overrides:
      createSession in class Context
      Returns:
      A new session builder.

    • getSession

      public SerializerSession getSession()
      Description copied from class: Context
      Returns a session to use for this context.

      Note that subclasses may opt to return a reusable non-modifiable session.

      Overrides:
      getSession in class Context
      Returns:
      A new session object.

    • isWriterSerializer

      public boolean isWriterSerializer()
      Returns true if this serializer subclasses from WriterSerializer.
      Returns:
      true if this serializer subclasses from WriterSerializer.

    • serialize

      public final void serialize(Object o, Object output) throws SerializeException, IOException
      Serializes a POJO to the specified output stream or writer.

      Equivalent to calling serializer.createSession().serialize(o, output);

      Parameters:
      o - The object to serialize.
      output - The output object.
      Character-based serializers can handle the following output class types:
      • Writer
      • OutputStream - Output will be written as UTF-8 encoded stream.
      • File - Output will be written as system-default encoded stream.
      • StringBuilder - Output will be written to the specified string builder.

      Stream-based serializers can handle the following output class types:
      Throws:
      SerializeException - If a problem occurred trying to convert the output.
      IOException - Thrown by the underlying stream.

    • serialize

      public Object serialize(Object o) throws SerializeException
      Shortcut method for serializing objects directly to either a String or byte[] depending on the serializer type.
      Parameters:
      o - The object to serialize.
      Returns:
      The serialized object.
      Character-based serializers will return a String
      Stream-based serializers will return a byte[]
      Throws:
      SerializeException - If a problem occurred trying to convert the output.

    • serializeToString

      public final String serializeToString(Object o) throws SerializeException
      Convenience method for serializing an object to a String.

      For writer-based serializers, this is identical to calling serialize(Object).
      For stream-based serializers, this converts the returned byte array to a string based on the OutputStreamSerializer.Builder.binaryFormat(BinaryFormat) setting.

      Parameters:
      o - The object to serialize.
      Returns:
      The output serialized to a string.
      Throws:
      SerializeException - If a problem occurred trying to convert the output.

    • doSerialize

      protected void doSerialize(SerializerSession session, SerializerPipe pipe, Object o) throws IOException, SerializeException
      Serializes a POJO to the specified pipe.
      Parameters:
      session - The current session.
      pipe - Where to send the output from the serializer.
      o - The object to serialize.
      Throws:
      IOException - Thrown by underlying stream.
      SerializeException - Problem occurred trying to serialize object.

    • getResponseHeaders

      public Map<String,String> getResponseHeaders(SerializerSession session)
      Optional method that specifies HTTP request headers for this serializer.

      For example, SoapXmlSerializer needs to set a SOAPAction header.

      This method is typically meaningless if the serializer is being used stand-alone (i.e. outside of a REST server or client).

      Parameters:
      session - The current session.
      Returns:
      The HTTP headers to set on HTTP requests. Never null.

    • getMediaTypeRanges

      public final MediaRanges getMediaTypeRanges()
      Returns the media types handled based on the value of the accept parameter passed into the constructor.

      Note that the order of these ranges are from high to low q-value.

      Returns:
      The list of media types. Never null.

    • getPrimaryMediaType

      public final MediaType getPrimaryMediaType()
      Returns the first entry in the accept parameter passed into the constructor.

      This signifies the 'primary' media type for this serializer.

      Returns:
      The media type. Never null.

    • forEachAcceptMediaType

      public final Serializer forEachAcceptMediaType(Consumer<MediaType> action)
      Performs an action on the media types handled based on the value of the accept parameter passed into the constructor.

      The order of the media types are the same as those in the accept parameter.

      Parameters:
      action - The action to perform on the media types.
      Returns:
      This object.

    • getResponseContentType

      public final MediaType getResponseContentType()
      Optional method that returns the response Content-Type for this serializer if it is different from the matched media type.

      This method is specified to override the content type for this serializer. For example, the Json5Serializer class returns that it handles media type "text/json5", but returns "text/json" as the actual content type. This allows clients to request specific 'flavors' of content using specialized Accept header values.

      This method is typically meaningless if the serializer is being used stand-alone (i.e. outside of a REST server or client).

      Returns:
      The response content type. If null, then the matched media type is used.

    • isAddBeanTypes

      protected boolean isAddBeanTypes()
      Add "_type" properties when needed.
      Returns:
      true if "_type" properties added to beans if their type cannot be inferred through reflection.
      See Also:

    • isAddRootType

      protected final boolean isAddRootType()
      Add type attribute to root nodes.
      Returns:
      true if type property should be added to root node.
      See Also:

    • getListener

      protected final Class<? extends SerializerListener> getListener()
      Serializer listener.
      Returns:
      Class used to listen for errors and warnings that occur during serialization.
      See Also:

    • isSortCollections

      protected final boolean isSortCollections()
      Sort arrays and collections alphabetically.
      Returns:
      true if arrays and collections are copied and sorted before serialization.
      See Also:

    • isSortMaps

      protected final boolean isSortMaps()
      Sort maps alphabetically.
      Returns:
      true if maps are copied and sorted before serialization.
      See Also:

    • isTrimEmptyCollections

      protected final boolean isTrimEmptyCollections()
      Trim empty lists and arrays.
      Returns:
      true if empty lists and arrays are not serialized to the output.
      See Also:

    • isTrimEmptyMaps

      protected final boolean isTrimEmptyMaps()
      Trim empty maps.
      Returns:
      true if empty map values are not serialized to the output.
      See Also:

    • isKeepNullProperties

      protected final boolean isKeepNullProperties()
      Don't trim null bean property values.
      Returns:
      true if null bean values are serialized to the output.
      See Also:

    • isTrimStrings

      protected final boolean isTrimStrings()
      Trim strings.
      Returns:
      true if string values will be trimmed of whitespace using String.trim() before being serialized.
      See Also:

    • getUriContext

      protected final UriContext getUriContext()
      URI context bean.
      Returns:
      Bean used for resolution of URIs to absolute or root-relative form.
      See Also:

    • getUriRelativity

      protected final UriRelativity getUriRelativity()
      URI relativity.
      Returns:
      Defines what relative URIs are relative to when serializing any of the following:
      See Also:

    • getUriResolution

      protected final UriResolution getUriResolution()
      URI resolution.
      Returns:
      Defines the resolution level for URIs when serializing URIs.
      See Also:

    • properties

      protected JsonMap properties()
      Description copied from class: Context
      Returns the properties on this bean as a map for debugging.
      Overrides:
      properties in class BeanTraverseContext
      Returns:
      The properties on this bean as a map for debugging.