Package org.apache.juneau.marshall.swap.spi

Class ObjectSwap<T,S>

java.lang.Object
org.apache.juneau.marshall.swap.spi.ObjectSwap<T,S>
Type Parameters:
T - The normal form of the class.
S - The swapped form of the class.
Direct Known Subclasses:
AutoListSwap, AutoMapSwap, AutoNumberSwap, AutoObjectSwap, FunctionalSwap, HalLinkOrArraySwap, HalResourceOrArraySwap, JsonApiLinkOrStringSwap, JsonSchema.BooleanOrSchemaArraySwap, JsonSchema.BooleanOrSchemaSwap, JsonSchema.JsonSchemaOrSchemaArraySwap, JsonSchema.JsonTypeOrJsonTypeArraySwap, MapSwap, MatchResultSwap, OpenApiUI, ParsedReaderSwap, RedocUI, StackTraceElementSwap, StringSwap, SurrogateSwap, SwaggerUI
public abstract class ObjectSwap<T,S> extends Object
Used to swap out non-serializable objects with serializable replacements during serialization, and vis-versa during parsing.
Description

ObjectSwaps are used to extend the functionality of the serializers and parsers to be able to handle objects that aren't automatically handled by the serializers or parsers.
For example, JSON does not have a standard representation for rendering dates. By defining a special Date swap and associating it with a serializer and parser, you can convert a Date object to a String during serialization, and convert that String object back into a Date object during parsing.

Swaps MUST declare a public no-arg constructor so that the bean context can instantiate them.

ObjectSwaps are associated with serializers and parsers through the following:

ObjectSwaps have two parameters:

  1. <T> - The normal representation of an object.
  2. <S> - The swapped representation of an object.

Serializers use swaps to convert objects of type T into objects of type S, and on calls to BeanMap.get(Object).
Parsers use swaps to convert objects of type S into objects of type T, and on calls to BeanMap.put(String,Object).
Swap Class Type <S>

For normal serialization, the swapped object representation of an object must be an object type that the serializers can natively convert to JSON (or language-specific equivalent).
The list of valid transformed types are as follows...

  • String
  • Number
  • Boolean
  • Collection containing anything on this list.
  • Map containing anything on this list.
  • A java bean with properties of anything on this list.
  • An array of anything on this list.

For OpenAPI serialization, the valid swapped types also include byte[] and Calendar.

Normal Class Type <T>

The normal object representation of an object.

See Also:

  • Field Details

    • NULL

      public static final ObjectSwap NULL
      Represents a non-existent object swap.

  • Constructor Details

    • ObjectSwap

      protected ObjectSwap()
      Constructor.

    • ObjectSwap

      protected ObjectSwap(Class<T> normalClass, Class<?> swapClass)
      Constructor for when the normal and transformed classes are already known.
      Parameters:
      normalClass - The normal class (cannot be serialized).
      swapClass - The transformed class (serializable).

  • Method Details

    • forMediaTypes

      public MediaType[] forMediaTypes()
      Returns the media types that this swap is applicable to.

      This method can be overridden to programmatically specify what media types it applies to.

      This method is the programmatic equivalent to the @Swap(mediaTypes) annotation.

      See Also:
      Returns:
      The media types that this swap is applicable to, or null if it's applicable for all media types.

    • forMediaTypes

      public ObjectSwap<T,?> forMediaTypes(MediaType[] mediaTypes)
      Sets the media types that this swap is associated with.
      See Also:
      Parameters:
      mediaTypes - The media types that this swap is associated with. Can be null to make this swap applicable to all media types.
      Returns:
      This object.

    • getNormalClass

      public ClassInfo getNormalClass()
      Returns the T class, the normalized form of the class.
      Returns:
      The normal form of this class.

    • getSwapClass

      public ClassInfo getSwapClass()
      Returns the G class, the generalized form of the class.

      Subclasses must override this method if the generalized class is Object, meaning it can produce multiple generalized forms.

      Returns:
      The transformed form of this class.

    • getSwapClassMeta

      public ClassMeta<?> getSwapClassMeta(MarshallingSession session)
      Returns the ClassMeta of the transformed class type.

      This value is cached for quick lookup.

      Parameters:
      session - The bean context to use to get the class meta. This is always going to be the same bean context that created this swap. Must not be null on the first (uncached) call.
      Returns:
      The ClassMeta of the transformed class type.

    • isNormalObject

      public boolean isNormalObject(Object o)
      Checks if the specified object is an instance of the normal class defined on this swap.
      Parameters:
      o - The object to check. Can be null (returns false).
      Returns:
      true if the specified object is a subclass of the normal class defined on this transform. A null value always returns false.

    • isSwappedObject

      public boolean isSwappedObject(Object o)
      Checks if the specified object is an instance of the swap class defined on this swap.
      Parameters:
      o - The object to check. Can be null (returns false).
      Returns:
      true if the specified object is a subclass of the transformed class defined on this transform. A null value always returns false.

    • match

      public int match(MarshallingSession session)
      Returns a number indicating how well this swap matches the specified session.

      Uses the MediaType.match(MediaType, boolean) method algorithm to produce a number whereby a larger value indicates a "better match". The idea being that if multiple swaps are associated with a given object, we want to pick the best one.

      For example, if the session media type is "text/json", then the match values are shown below:

      • "text/json" = 100,000
      • "*/json" = 5,100
      • "*/*" = 5,000
      • No media types specified on swap = 1
      • "text/xml" = 0
      Parameters:
      session - The bean session. Can be null (returns 0, or 1 if this swap has no media types configured).
      Returns:
      Zero if swap doesn't match the session, or a positive number if it does.

    • swap

      public S swap(MarshallingSession session, T o) throws Exception
      If this transform is to be used to serialize non-serializable objects, it must implement this method.

      The object must be converted into one of the following serializable types:

      • String
      • Number
      • Boolean
      • Collection containing anything on this list.
      • Map containing anything on this list.
      • A java bean with properties of anything on this list.
      • An array of anything on this list.
      Parameters:
      session - The bean session to use to get the class meta. This is always going to be the same bean context that created this swap.
      o - The object to be transformed.
      Returns:
      The transformed object.
      Throws:
      Exception - If a problem occurred trying to convert the output.

    • swap

      public S swap(MarshallingSession session, T o, String template) throws Exception
      Same as swap(MarshallingSession, Object), but can be used if your swap has a template associated with it.
      Parameters:
      session - The bean session to use to get the class meta. This is always going to be the same bean context that created this swap.
      o - The object to be transformed.
      template - The template string associated with this swap.
      Returns:
      The transformed object.
      Throws:
      Exception - If a problem occurred trying to convert the output.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • unswap

      public T unswap(MarshallingSession session, S f, ClassMeta<?> hint) throws Exception
      If this transform is to be used to reconstitute objects that aren't true Java beans, it must implement this method.
      Parameters:
      session - The bean session to use to get the class meta. This is always going to be the same bean context that created this swap.
      f - The transformed object.
      hint - If possible, the parser will try to tell you the object type being created. For example, on a serialized date, this may tell you that the object being created must be of type GregorianCalendar.
      This may be null if the parser cannot make this determination.
      Returns:
      The narrowed object.
      Throws:
      Exception - If this method is not implemented.

    • unswap

      public T unswap(MarshallingSession session, S f, ClassMeta<?> hint, String template) throws Exception
      Same as unswap(MarshallingSession, Object, ClassMeta), but can be used if your swap has a template associated with it.
      Parameters:
      session - The bean session to use to get the class meta. This is always going to be the same bean context that created this swap.
      f - The transformed object.
      hint - If possible, the parser will try to tell you the object type being created. For example, on a serialized date, this may tell you that the object being created must be of type GregorianCalendar.
      This may be null if the parser cannot make this determination.
      template - The template string associated with this swap.
      Returns:
      The transformed object.
      Throws:
      Exception - If a problem occurred trying to convert the output.

    • withTemplate

      public String withTemplate()
      Returns additional context information for this swap.

      Typically this is going to be used to specify a template name, such as a FreeMarker template file name.

      This method can be overridden to programmatically specify a template value.

      This method is the programmatic equivalent to the @Swap(template) annotation.

      See Also:
      Returns:
      Additional context information, or null if not specified.

    • withTemplate

      public ObjectSwap<T,?> withTemplate(String template)
      Sets the template string on this swap.
      See Also:
      Parameters:
      template - The template string on this swap. Can be null to unset the template.
      Returns:
      This object.