Package org.apache.juneau.serializer

Class SerializerSession

java.lang.Object
org.apache.juneau.ContextSession
org.apache.juneau.BeanSession
org.apache.juneau.BeanTraverseSession
org.apache.juneau.serializer.SerializerSession
Direct Known Subclasses:
OutputStreamSerializerSession, WriterSerializerSession
public class SerializerSession extends BeanTraverseSession
Serializer session that lives for the duration of a single use of Serializer.

Used by serializers for the following purposes:

  • Keeping track of how deep it is in a model for indentation purposes.
  • Ensuring infinite loops don't occur by setting a limit on how deep to traverse a model.
  • Ensuring infinite loops don't occur from loops in the model (when detectRecursions is enabled.
  • Allowing serializer properties to be overridden on method calls.
Notes:
  • This class is not thread safe and is typically discarded after one use.
See Also:

  • Constructor Details

  • Method Details

    • create

      public static SerializerSession.Builder create(Serializer ctx)
      Creates a new builder for this object.
      Parameters:
      ctx - The context creating this session.
      Cannot be null.
      Returns:
      A new builder.

    • createBeanTypeNameProperty

      protected static final BeanPropertyValue createBeanTypeNameProperty(BeanMap<?> m, String typeName)
      Create a "_type" property that contains the dictionary name of the bean.
      Parameters:
      m - The bean map to create a class property on.
      typeName - The type name of the bean.
      Returns:
      A new bean property value.

    • handleThrown

      protected static <T extends Throwable> void handleThrown(T causedBy)
      Converts the specified throwable to either a RuntimeException or SerializeException.
      Type Parameters:
      T - The throwable type.
      Parameters:
      causedBy - The exception to cast or wrap.

    • toList

      protected static final List<Object> toList(Class<?> type, Object array)
      Converts the contents of the specified object array to a list.

      Works on both object and primitive arrays.

      In the case of multi-dimensional arrays, the outgoing list will contain elements of type n-1 dimension. i.e. if type is int[][] then list will have entries of type int[].

      Parameters:
      type - The type of array.
      array - The array being converted.
      Returns:
      The array as a list.

    • addVarBean

      public <T> SerializerSession addVarBean(Class<T> c, T value)
      Adds a session object to the VarResolverSession in this session.
      Type Parameters:
      T - The bean type.
      Parameters:
      c - The bean type being added.
      value - The bean being added.
      Returns:
      This object.

    • canIgnoreValue

      public final boolean canIgnoreValue(ClassMeta<?> cm, String attrName, Object value) throws SerializeException
      Returns true if the specified value should not be serialized.
      Parameters:
      cm - The class type of the object being serialized.
      attrName - The bean attribute name, or null if this isn't a bean attribute.
      value - The object being serialized.
      Returns:
      true if the specified value should not be serialized.
      Throws:
      SerializeException - If recursion occurred.

    • forEachEntry

      public final <E> void forEachEntry(Collection<E> c, Consumer<E> consumer)
      Consumes each entry in the list.
      Type Parameters:
      E - The element type.
      Parameters:
      c - The collection being sorted.
      consumer - The entry consumer.

    • forEachEntry

      public final <K, V> void forEachEntry(Map<K,V> m, Consumer<Map.Entry<K,V>> consumer)
      Consumes each map entry in the map.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      m - The map being consumed.
      consumer - The map entry consumer.

    • getListener

      public SerializerListener getListener()
      Returns the listener associated with this session.
      Returns:
      The listener associated with this session, or null if there is no listener.

    • getListener

      public <T extends SerializerListener> T getListener(Class<T> c)
      Returns the listener associated with this session.
      Type Parameters:
      T - The listener type.
      Parameters:
      c - The listener class to cast to.
      Returns:
      The listener associated with this session, or null if there is no listener.

    • getResponseHeaders

      public Map<String,String> getResponseHeaders()
      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).

      The default implementation of this method simply calls Serializer.getResponseHeaders(SerializerSession).

      Returns:
      The HTTP headers to set on HTTP requests. Never null.

    • getSchema

      public final HttpPartSchema getSchema()
      HTTP part schema of object being serialized.
      Returns:
      HTTP part schema of object being serialized, or null if not specified.

    • getVarResolver

      public VarResolverSession getVarResolver()
      Returns the variable resolver session.
      Returns:
      The variable resolver session.

    • isWriterSerializer

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

    • resolve

      public String resolve(String string)
      Resolves any variables in the specified string.
      Parameters:
      string - The string to resolve values in.
      Returns:
      The string with variables resolved.

    • resolveUri

      public final String resolveUri(Object uri)
      Converts a String to an absolute URI based on the UriContext on this session.
      Parameters:
      uri - The input URI. Can be any of the following: URI can be any of the following forms:
      • "foo://foo" - Absolute URI.
      • "/foo" - Root-relative URI.
      • "/" - Root URI.
      • "context:/foo" - Context-root-relative URI.
      • "context:/" - Context-root URI.
      • "servlet:/foo" - Servlet-path-relative URI.
      • "servlet:/" - Servlet-path URI.
      • "request:/foo" - Request-path-relative URI.
      • "request:/" - Request-path URI.
      • "foo" - Path-info-relative URI.
      • "" - Path-info URI.
      Returns:
      The resolved URI.

    • 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.

    • serialize

      public final void serialize(Object o, Object out) throws SerializeException, IOException
      Serialize the specified object using the specified session.
      Parameters:
      out - Where to send the output from the serializer.
      o - The object to serialize.
      Throws:
      SerializeException - If a problem occurred trying to convert the output.
      IOException - Thrown by the underlying stream.

    • serializeToString

      public String serializeToString(Object o) throws SerializeException
      Shortcut method for serializing an object to a String.
      Parameters:
      o - The object to serialize.
      Returns:
      The serialized object.
      Character-based serializers will return a String
      Stream-based serializers will return a byte[] converted to a string based on the OutputStreamSerializer.Builder.binaryFormat(BinaryFormat) setting.
      Throws:
      SerializeException - If a problem occurred trying to convert the output.

    • sort

      public final <E> Collection<E> sort(Collection<E> c)
      Sorts the specified collection if isSortCollections() returns true.
      Type Parameters:
      E - The element type.
      Parameters:
      c - The collection being sorted.
      Returns:
      A new sorted TreeSet.

    • sort

      public final <E> List<E> sort(List<E> c)
      Sorts the specified collection if isSortCollections() returns true.
      Type Parameters:
      E - The element type.
      Parameters:
      c - The collection being sorted.
      Returns:
      A new sorted TreeSet.

    • sort

      public final <K, V> Map<K,V> sort(Map<K,V> m)
      Sorts the specified map if isSortMaps() returns true.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      m - The map being sorted.
      Returns:
      A new sorted TreeMap.

    • toString

      public final String toString(Object o)
      Converts the specified object to a String.

      Also has the following effects:

      • Class object is converted to a readable name. See ClassInfo.getNameFull().
      • Whitespace is trimmed if the trim-strings setting is enabled.
      Parameters:
      o - The object to convert to a String.
      Returns:
      The object converted to a String, or null if the input was null.

    • trim

      public final String trim(Object o)
      Trims the specified string if isTrimStrings() returns true.
      Parameters:
      o - The input string to trim.
      Returns:
      The trimmed string, or null if the input was null.

    • createDefaultVarResolverSession

      protected VarResolverSession createDefaultVarResolverSession()
      Adds a session object to the VarResolverSession in this session.
      Returns:
      This object.

    • createPipe

      protected SerializerPipe createPipe(Object output)
      Wraps the specified input object into a ParserPipe object so that it can be easily converted into a stream or reader.
      Parameters:
      output - The output location.
      For character-based serializers, this can be any of the following types:
      For byte-based serializers, this can be any of the following types:
      Returns:
      A new ParserPipe wrapper around the specified input object.

    • doSerialize

      protected void doSerialize(SerializerPipe pipe, Object o) throws IOException, SerializeException
      Serializes a POJO to the specified pipe.

      This method should NOT close the context object.

      The default implementation of this method simply calls Serializer.doSerialize(SerializerSession,SerializerPipe,Object).

      Parameters:
      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.

    • generalize

      protected final Object generalize(Object o, ClassMeta<?> type) throws SerializeException
      Generalize the specified object if a POJO swap is associated with it.
      Parameters:
      o - The object to generalize.
      type - The type of object.
      Returns:
      The generalized object, or null if the object is null.
      Throws:
      SerializeException - If a problem occurred trying to convert the output.

    • getBeanTypeName

      protected final String getBeanTypeName(SerializerSession session, ClassMeta<?> eType, ClassMeta<?> aType, BeanPropertyMeta pMeta)
      Resolves the dictionary name for the actual type.
      Parameters:
      session - The current serializer session.
      eType - The expected type of the bean property.
      aType - The actual type of the bean property.
      pMeta - The current bean property being serialized.
      Returns:
      The bean dictionary name, or null if a name could not be found.

    • getExpectedRootType

      protected final ClassMeta<?> getExpectedRootType(Object o)
      Returns the parser-side expected type for the object.

      The return value depends on the Serializer.Builder.addRootType() setting. When disabled, the parser already knows the Java POJO type being parsed, so there is no reason to add "_type" attributes to the root-level object.

      Parameters:
      o - The object to get the expected type on.
      Returns:
      The expected type.

    • getJavaMethod

      protected final Method getJavaMethod()
      Returns the Java method that invoked this serializer.

      When using the REST API, this is the Java method invoked by the REST call. Can be used to access annotations defined on the method or class.

      Returns:
      The Java method that invoked this serializer.

    • 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:

    • getUriResolver

      protected final UriResolver getUriResolver()
      Returns the URI resolver.
      Returns:
      The URI resolver.

    • 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:

    • 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:

    • 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:

    • isTrimStrings

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

    • onBeanGetterException

      protected final void onBeanGetterException(BeanPropertyMeta p, Throwable t) throws SerializeException
      Specialized warning when an exception is thrown while executing a bean getter.
      Parameters:
      p - The bean map entry representing the bean property.
      t - The throwable that the bean getter threw.
      Throws:
      SerializeException - Thrown if ignoreInvocationExceptionOnGetters is false.

    • onError

      protected void onError(Throwable t, String msg, Object... args)
      Logs a warning message.
      Overrides:
      onError in class BeanTraverseSession
      Parameters:
      t - The throwable that was thrown (if there was one).
      msg - The warning message.
      args - Optional MessageFormat-style arguments.

    • properties

      protected FluentMap<String,Object> properties()
      Description copied from class: ContextSession
      Returns the properties on this bean as a map for debugging.
      Overrides:
      properties in class BeanTraverseSession
      Returns:
      The properties on this bean as a map for debugging.

    • push2

      protected final ClassMeta<?> push2(String attrName, Object o, ClassMeta<?> eType) throws SerializeException
      Same as BeanTraverseSession.push(String, Object, ClassMeta) but wraps BeanRecursionException inside SerializeException.
      Parameters:
      attrName - The attribute name.
      o - The current object being traversed.
      eType - The expected class type.
      Returns:
      The ClassMeta of the object so that instanceof operations only need to be performed once (since they can be expensive).
      Throws:
      SerializeException - If recursion occurred.

    • relativizeUri

      protected final String relativizeUri(Object relativeTo, Object uri)
      Opposite of resolveUri(Object).

      Converts the URI to a value relative to the specified relativeTo parameter.

      Both parameters can be any of the following:

      Both URIs can be any of the following forms:

      • "foo://foo" - Absolute URI.
      • "/foo" - Root-relative URI.
      • "/" - Root URI.
      • "context:/foo" - Context-root-relative URI.
      • "context:/" - Context-root URI.
      • "servlet:/foo" - Servlet-path-relative URI.
      • "servlet:/" - Servlet-path URI.
      • "request:/foo" - Request-path-relative URI.
      • "request:/" - Request-path URI.
      • "foo" - Path-info-relative URI.
      • "" - Path-info URI.
      Parameters:
      relativeTo - The URI to relativize against.
      uri - The URI to relativize.
      Returns:
      The relativized URI.

    • swap

      protected Object swap(ObjectSwap swap, Object o) throws SerializeException
      Invokes the specified swap on the specified object if the swap is not null.
      Parameters:
      swap - The swap to invoke. Can be null.
      o - The input object.
      Returns:
      The swapped object.
      Throws:
      SerializeException - If swap method threw an exception.