Package org.apache.juneau.marshall

Class MarshallingTraverseSession

java.lang.Object
org.apache.juneau.marshall.ContextSession
org.apache.juneau.marshall.MarshallingSession
org.apache.juneau.marshall.MarshallingTraverseSession
All Implemented Interfaces:
BeanSession, ConverterSession
Direct Known Subclasses:
JsonSchemaGeneratorSession, SerializerSession
public class MarshallingTraverseSession extends MarshallingSession
ContextSession that lives for the duration of a single use of MarshallingTraverseContext.

Used by serializers and other classes that traverse POJOs 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.
Notes:
  • This class is not thread safe and is typically discarded after one use.

  • Field Details

    • indent

      public int indent
      The current indentation depth into the model.

  • Constructor Details

  • Method Details

    • getInitialDepth

      public final int getInitialDepth()
      Initial depth.
      Returns:
      The initial indentation level at the root.
      See Also:

    • getLastLocation

      public final JsonMap getLastLocation()
      Returns information used to determine at what location in the parse a failure occurred.
      Returns:
      A map, typically containing something like {line:123,column:456,currentProperty:"foobar"}

    • getMaxDepth

      public final int getMaxDepth()
      Max traversal depth.
      Returns:
      The depth beyond which nodes in the POJO tree are dropped (truncated) from the output.
      Values deeper than this limit are silently omitted rather than causing an exception to be thrown.
      This is a size guard, not a cycle detector.
      See Also:

    • isDetectRecursions

      public final boolean isDetectRecursions()
      Automatically detect POJO recursions.
      Returns:
      true if recursions should be checked for during traversal.
      See Also:

    • isIgnoreRecursions

      public final boolean isIgnoreRecursions()
      Ignore recursion errors.
      Returns:
      true if when we encounter the same object when traversing a tree, we set the value to null.
      Otherwise, a MarshallingRecursionException is thrown with the message "Recursion occurred, stack=...".
      See Also:

    • getOptionalType

      protected final ClassMeta<?> getOptionalType(ClassMeta<?> cm)
      Returns the inner type of an Optional.
      Parameters:
      cm - The meta to check. Must not be null.
      Returns:
      The inner type of an Optional.

    • getOptionalValue

      protected final Object getOptionalValue(Object o)
      If the specified object is an Optional, returns the inner object.
      Parameters:
      o - The object to check. Can be null (returns null).
      Returns:
      The inner object if it's an Optional, null if it's null, or else the same object.

    • getStack

      protected String getStack(boolean full)
      Returns the current stack trace.
      Parameters:
      full - If true, returns a full stack trace.
      Returns:
      The current stack trace.

    • isOptional

      protected static final boolean isOptional(ClassMeta<?> cm)
      Same as ClassMeta.isOptional() but gracefully handles a null ClassMeta.
      Parameters:
      cm - The meta to check. Can be null (returns false).
      Returns:
      true if the specified meta is an Optional.

    • isRoot

      protected final boolean isRoot()
      Returns true if we're processing the root node.

      Must be called after push(String, Object, ClassMeta) and before pop().

      Returns:
      true if we're processing the root node.

    • onError

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

    • pop

      protected final void pop()
      Pop an object off the stack.

    • 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 MarshallingSession
      Returns:
      The properties on this bean as a map for debugging.

    • push

      protected final ClassMeta<?> push(String attrName, Object o, ClassMeta<?> eType) throws MarshallingRecursionException
      Push the specified object onto the stack.

      When the current depth exceeds maxDepth, this method returns null so that the over-depth node is dropped (truncated) from the output rather than traversed further. Exceeding maxDepth does not throw an exception — it is a size guard that truncates deeply-nested (or cyclic) models, not a cycle detector. To fail-fast on genuine cycles, enable detectRecursions; to omit repeated nodes as null, enable ignoreRecursions.

      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).
      Returns null when the object is null, when maxDepth is exceeded (over-depth node dropped), or when a recursion is detected under ignoreRecursions.
      Throws:
      MarshallingRecursionException - If recursion occurred while detectRecursions is enabled without ignoreRecursions.

    • setCurrentClass

      protected final void setCurrentClass(ClassMeta<?> currentClass)
      Sets the current class being traversed for proper error messages.
      Parameters:
      currentClass - The current class being traversed.

    • setCurrentProperty

      protected final void setCurrentProperty(BeanPropertyMeta currentProperty)
      Sets the current bean property being traversed for proper error messages.
      Parameters:
      currentProperty - The current property being traversed.

    • willExceedDepth

      protected final boolean willExceedDepth()
      Returns true if we're about to exceed the max depth for the document.

      When this returns true, the over-depth value is dropped (truncated) from the output rather than causing an exception to be thrown — exceeding maxDepth is a size guard, not a cycle detector.

      Returns:
      true if we're about to exceed the max depth for the document.

    • willRecurse

      protected final boolean willRecurse(String attrName, Object o, ClassMeta<?> cm) throws MarshallingRecursionException
      Returns true if MarshallingTraverseContext.Builder.detectRecursions() is enabled, and the specified object is already higher up in the traversal chain.
      Parameters:
      attrName - The bean property attribute name, or some other identifier.
      o - The object to check for recursion.
      cm - The metadata on the object class.
      Returns:
      true if recursion detected.
      Throws:
      MarshallingRecursionException - If recursion occurred.