org.apache.juneau.transform

Class PojoSwap<T,S>

java.lang.Object

org.apache.juneau.transform.PojoSwap<T,S>

Type Parameters:

T - The normal form of the class.

S - The swapped form of the class.

Direct Known Subclasses:

CalendarLongSwap, CalendarMapSwap, DateLongSwap, DateMapSwap, EnumerationSwap, IteratorSwap, MapSwap, ReaderSwap, Schema.BooleanOrSchemaArraySwap, Schema.BooleanOrSchemaSwap, Schema.JsonTypeOrJsonTypeArraySwap, Schema.SchemaOrSchemaArraySwap, StringSwap, SurrogateSwap

@BeanIgnore
public abstract class PojoSwap<T,S>
extends Object

Used to swap out non-serializable objects with serializable replacements during serialization, and vis-versa during parsing.

Description

PojoSwaps are used to extend the functionality of the serializers and parsers to be able to handle POJOs 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.

PojoSwaps are associated with serializers and parsers through the following:

• @Swap
• @Swaps
• BeanContextBuilder.pojoSwaps(Object...)
• BeanContextBuilder.pojoSwaps(Class...)
• BeanContextBuilder.pojoSwaps(boolean, Object...)
• BeanContextBuilder.pojoSwapsRemove(Object...)

PojoSwaps 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>

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.

Normal Class Type <T>

The normal object representation of an object.

See Also:

• Overview > juneau-marshall > PojoSwaps
• Overview > juneau-marshall > @Swap Annotation

Field Summary

Fields

Modifier and Type	Field and Description
static PojoSwap	NULL Represents a non-existent pojo swap.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PojoSwap() Constructor.
protected	PojoSwap(Class<T> normalClass, Class<?> swapClass) Constructor for when the normal and transformed classes are already known.

Method Summary

Modifier and Type	Method and Description
MediaType[]	forMediaTypes() Returns the media types that this swap is applicable to.
PojoSwap<T,?>	forMediaTypes(MediaType[] mediaTypes) Sets the media types that this swap is associated with.
Class<T>	getNormalClass() Returns the T class, the normalized form of the class.
Class<?>	getSwapClass() Returns the G class, the generalized form of the class.
ClassMeta<?>	getSwapClassMeta(BeanSession session) Returns the ClassMeta of the transformed class type.
boolean	isNormalObject(Object o) Checks if the specified object is an instance of the normal class defined on this swap.
boolean	isSwappedObject(Object o) Checks if the specified object is an instance of the swap class defined on this swap.
int	match(BeanSession session) Returns a number indicating how well this swap matches the specified session.
S	swap(BeanSession session, T o) If this transform is to be used to serialize non-serializable POJOs, it must implement this method.
S	swap(BeanSession session, T o, String template) Same as swap(BeanSession, Object), but can be used if your swap has a template associated with it.
String	toString()
T	unswap(BeanSession session, S f, ClassMeta<?> hint) If this transform is to be used to reconstitute POJOs that aren't true Java beans, it must implement this method.
T	unswap(BeanSession session, S f, ClassMeta<?> hint, String template) Same as unswap(BeanSession, Object, ClassMeta), but can be used if your swap has a template associated with it.
String	withTemplate() Returns additional context information for this swap.
PojoSwap<T,?>	withTemplate(String template) Sets the template string on this swap.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NULL

public static final PojoSwap NULL

Represents a non-existent pojo swap.

Constructor Detail

PojoSwap

protected PojoSwap()

Constructor.

PojoSwap

protected PojoSwap(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 Detail

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.

Documentation

• Overview > juneau-marshall > Per-media-type PojoSwaps

Returns:

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

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:

• Overview > juneau-marshall > Templated Swaps

Returns:

Additional context information, or null if not specified.

forMediaTypes

public PojoSwap<T,?> forMediaTypes(MediaType[] mediaTypes)

Sets the media types that this swap is associated with.

Documentation

• Overview > juneau-marshall > Per-media-type PojoSwaps

Parameters:

mediaTypes - The media types that this swap is associated with.

Returns:

This object (for method chaining).

withTemplate

public PojoSwap<T,?> withTemplate(String template)

Sets the template string on this swap.

See Also:

• Overview > juneau-marshall > Templated Swaps

Parameters:

template - The template string on this swap.

Returns:

This object (for method chaining).

match

public int match(BeanSession 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 POJO, 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.

Returns:

Zero if swap doesn't match the session, or a positive number if it does.

swap

public S swap(BeanSession session,
              T o)
       throws Exception

If this transform is to be used to serialize non-serializable POJOs, 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(BeanSession session,
              T o,
              String template)
       throws Exception

Same as swap(BeanSession, 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.

unswap

public T unswap(BeanSession session,
                S f,
                ClassMeta<?> hint)
         throws Exception

If this transform is to be used to reconstitute POJOs 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(BeanSession session,
                S f,
                ClassMeta<?> hint,
                String template)
         throws Exception

Same as unswap(BeanSession, 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.

getNormalClass

public Class<T> getNormalClass()

Returns the T class, the normalized form of the class.

Returns:

The normal form of this class.

getSwapClass

public Class<?> 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(BeanSession 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.

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.

Returns:

true if the specified object is a subclass of the normal class defined on this transform. null always return 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.

Returns:

true if the specified object is a subclass of the transformed class defined on this transform. null always return false.

toString

public String toString()

Overrides:

toString in class Object