Package org.apache.juneau.marshall.serializer

Class SerializerSession

java.lang.Object
org.apache.juneau.marshall.ContextSession
org.apache.juneau.marshall.MarshallingSession
org.apache.juneau.marshall.MarshallingTraverseSession
org.apache.juneau.marshall.serializer.SerializerSession
All Implemented Interfaces:
BeanSession, ConverterSession
Direct Known Subclasses:
OutputStreamSerializerSession, WriterSerializerSession
public class SerializerSession extends MarshallingTraverseSession
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.
      Must not be null.
      typeName - The type name of the bean.
      Can be null (the created property's value is null).
      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.
      Must not be null.

    • 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.
      Must not be null.
      array - The array being converted.
      Must not be null.
      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.

      A value is also omitted (dropped) when it would exceed maxDepth (via MarshallingTraverseSession.willExceedDepth()) — over-depth values are silently truncated from the output rather than throwing. Exceeding maxDepth is a size guard, not a cycle detector; when detectRecursions is enabled, an actual recursion instead throws a SerializeException.

      Parameters:
      cm - The class type of the object being serialized.
      Can be null (treated as the Object type).
      attrName - The bean attribute name, or null if this isn't a bean attribute.
      value - The object being serialized.
      Can be null, in which case the result depends on keepNullProperties (ignored unless that setting is enabled).
      Returns:
      true if the specified value should not be serialized.
      Throws:
      SerializeException - If recursion occurred.

    • canIgnoreValue

      public final boolean canIgnoreValue(BeanPropertyMeta pMeta, String attrName, Object value) throws SerializeException
      Per-bean-property variant of canIgnoreValue(ClassMeta, String, Object).

      Applies the same standard inclusion rules (keepNullProperties, trimEmptyCollections / trimEmptyMaps, recursion detection), then additionally:

      • Treats Optional.empty() (and its primitive cousins OptionalInt/OptionalLong/OptionalDouble) as a null property value for inclusion purposes — the shared Optional/absent contract.
      • Applies nonDefault by comparing the surviving value against a cached reference instance of the property's containing bean. When no reference instance can be built (no accessible no-arg ctor / instantiation throws), nonDefault is silently skipped for that bean — the property is emitted normally rather than failing.

      Precedence (first "omit" wins): (1) null / empty Optional, (2) trimEmpty*, (3) value-equals-default.

      Parameters:
      pMeta - The bean property meta for the value being considered. Must not be null.
      attrName - The bean attribute name. Must not be null.
      value - The current property value.
      Can be null (treated as an absent value; whether it's omitted depends on keepNullProperties).
      Returns:
      true if the property should be omitted from the output.
      Throws:
      SerializeException - If recursion occurred.
      Since:
      10.0.0

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

    • forEachStreamableEntry

      public final void forEachStreamableEntry(Object o, ClassMeta<?> type, Consumer consumer)
      Iterates over a streamable object (Iterator, Iterable, or Stream), consuming each entry.

      For collections, delegates to forEachEntry(Collection, Consumer) which supports sorting. For other streamable types, iterates lazily without materializing into a List.

      Parameters:
      o - The streamable object.
      type - The class meta for the object.
      consumer - The entry consumer.
      Since:
      9.2.1

    • toListFromStreamable

      public final List<Object> toListFromStreamable(Object o, ClassMeta<?> type)
      Converts a streamable object (Iterator, Iterable, or Stream) to a List.

      Used by serializers that need to know the collection size or inspect elements before serializing (e.g. MsgPack, HTML, CSV).

      Parameters:
      o - The streamable object.
      type - The class meta for the object.
      Returns:
      A new list containing all elements.
      Since:
      9.2.1

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

    • write

      public Object write(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.

    • write

      public final void write(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.

    • unwrapSupplier

      protected final Object unwrapSupplier(Object o, int depth) throws SerializeException
      Recursively unwraps nested Supplier chains to their underlying value.

      Supports chains of the form Supplier<Supplier<T>> → T with a maximum depth of 10 to prevent infinite loops. Note that BeanSupplier instances are NOT unwrapped here — they are treated as Iterable sequences by the serializer.

      Parameters:
      o - The object to unwrap.
      depth - The current recursion depth (must be 0 on initial call).
      Returns:
      The unwrapped value, or the original object if it is not a Supplier.
      Throws:
      SerializeException - If the Supplier chain exceeds 10 levels.

    • writeToString

      public String writeToString(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 MarshallingContextable.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.
      Can be null (returns null unchanged).
      Returns:
      The sorted collection, or the input collection unchanged if sorting is disabled or the collection isn't sortable.

    • 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.
      Can be null (returns null unchanged).
      Returns:
      The sorted list, or the input list unchanged if sorting is disabled or the list isn't sortable.

    • 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.
      Can be null (returns null unchanged).
      Returns:
      A new sorted TreeMap, or the input map unchanged if sorting is disabled or the keys aren't sortable.

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

    • writeDuration

      protected final String writeDuration(Duration d)
      Formats a Duration value using this session's configured duration format.
      Parameters:
      d - The value to format. null returns null.
      Returns:
      The formatted value, or null if d is null.

    • writePeriod

      protected final String writePeriod(Period p)
      Formats a Period value using this session's configured period format.
      Parameters:
      p - The value to format. null returns null.
      Returns:
      The formatted value, or null if p is null.

    • writeDate

      protected final String writeDate(Date d, ClassMeta<?> cm)
      Formats a Date value using this session's configured date format and time zone.
      Parameters:
      d - The value to format. null returns null.
      cm - The class metadata for the value (kept for symmetry with Iso8601Utils.formatDate(java.util.Date, org.apache.juneau.marshall.ClassMeta<?>, org.apache.juneau.marshall.DateFormat, java.util.TimeZone)).
      Returns:
      The formatted value, or null if d is null.

    • writeCalendar

      protected final String writeCalendar(Object c, ClassMeta<?> cm)
      Formats a Calendar or XMLGregorianCalendar value using this session's configured calendar format and time zone.

      XMLGregorianCalendar values always emit their XMLGregorianCalendar.toXMLFormat() form regardless of the configured format, mirroring the parse-side rule.

      Parameters:
      c - The value to format. Must be a Calendar or XMLGregorianCalendar. null returns null.
      cm - The class metadata for the value (kept for symmetry with Iso8601Utils.formatCalendar(java.lang.Object, org.apache.juneau.marshall.ClassMeta<?>, org.apache.juneau.marshall.CalendarFormat, java.util.TimeZone)).
      Returns:
      The formatted value, or null if c is null.

    • writeTemporal

      protected final String writeTemporal(TemporalAccessor t, ClassMeta<?> cm)
      Formats a TemporalAccessor value using this session's configured temporal format and time zone.
      Parameters:
      t - The value to format. Must be a Temporal subtype. null returns null.
      cm - The class metadata for the value (kept for symmetry with Iso8601Utils.formatTemporal(java.time.temporal.TemporalAccessor, org.apache.juneau.marshall.ClassMeta<?>, org.apache.juneau.marshall.TemporalFormat, java.util.TimeZone)).
      Returns:
      The formatted value, or null if t is 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 output object into a SerializerPipe object so that it can be easily converted into a stream or writer.
      Parameters:
      output - The output location.
      For character-based serializers, this can be any of the following types:
      For byte-based serializers, this must be an OutputStream.
      Returns:
      A new SerializerPipe wrapper around the specified output object.

    • doWrite

      protected void doWrite(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.doWrite(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.
      Can be null (returns null).
      type - The type of object.
      Can be null (the object's actual runtime class's swap, if any, is used instead).
      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.
      Can be null (the bean-property-level dictionary lookup tier is skipped).
      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.
      Can be null (returns null unless root typing is enabled, in which case the generic Object type is returned).
      Returns:
      The expected type, or null if the object was null and root typing is disabled.

    • 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, or null if not specified.

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

    • getDurationFormat

      protected final DurationFormat getDurationFormat()
      Returns the configured default duration wire format.
      Returns:
      The configured default duration wire format.

    • getPeriodFormat

      protected final PeriodFormat getPeriodFormat()
      Returns the configured default period wire format.
      Returns:
      The configured default period wire format.

    • getCalendarFormat

      protected final CalendarFormat getCalendarFormat()
      Returns the configured default calendar wire format.
      Returns:
      The configured default calendar wire format.

    • getDateFormat

      protected final DateFormat getDateFormat()
      Returns the configured default date wire format.
      Returns:
      The configured default date wire format.

    • getTemporalFormat

      protected final TemporalFormat getTemporalFormat()
      Returns the configured default temporal wire format.
      Returns:
      The configured default temporal wire format.

    • getTimeZoneFormat

      protected final TimeZoneFormat getTimeZoneFormat()
      Returns the configured default time-zone wire format.
      Returns:
      The configured default time-zone wire format.

    • getLocaleFormat

      protected final LocaleFormat getLocaleFormat()
      Returns the configured default locale wire format.
      Returns:
      The configured default locale wire format.

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

    • isNonDefault

      protected final boolean isNonDefault()
      Don't serialize bean properties whose values equal the default for their type.
      Returns:
      true if bean properties whose value equals the type / bean-constructed default are omitted.
      Since:
      10.0.0
      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.
      Must not be null.
      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 MarshallingTraverseSession
      Parameters:
      t - The throwable that was thrown (if there was one).
      msg - The warning message.
      args - Optional String.format-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 MarshallingTraverseSession
      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 MarshallingTraverseSession.push(String, Object, ClassMeta) but wraps MarshallingRecursionException inside SerializeException.
      Parameters:
      attrName - The attribute name.
      Can be null for unnamed entries (e.g. array elements); used only for stack-trace labeling.
      o - The current object being traversed.
      Can be null (returns null).
      eType - The expected class type.
      Can be null, in which case the object's actual runtime type is used instead.
      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 (no-op; the input object is returned unchanged).
      o - The input object.
      Returns:
      The swapped object.
      Throws:
      SerializeException - If swap method threw an exception.