Package org.apache.fulcrum.json

Interface JsonService

All Known Implementing Classes:

GSONBuilderService, Jackson2MapperService

public interface JsonService

This class defines custom methods needed to serialize and deserialize and helper methods if needed. Some methods expect a class parameter. If you want to call these methods from an environment, where you could only provide strings (e.g. velocity context), just wrap the method and call Class clazz = Class.forName(className); for the parameter.

Version:

$Id$

Author:

Georg Kallidis

Field Summary

Fields

Modifier and Type	Field	Description
static String	ROLE	Avalon Identifier
static String	SERVICE_NAME

Method Summary

Modifier and Type	Method	Description
JsonService	addAdapter(String name, Class target, Class mixin)	Adds an adapter (mixin, serializer,..) for the target class depending on the JsonService implementation.
JsonService	addAdapter(String name, Class target, Object mixin)	Add an adapter (mixin, serializer,..) for the target class depending on the JsonService implementation.
<T> T	deSer(String src, Class<T> type)	Deserializing a JSON string
<T> Collection<T>	deSerCollection(String json, Object collectionType, Class<T> elementType)	This is to deserialize collections.
String	ser(Object src)	Serializes a Java object
String	ser(Object src, Boolean cleanCache)
<T> String	ser(Object src, Class<T> type)	Serializes a Java object
<T> String	ser(Object src, Class<T> type, Boolean cleanCache)	Serialize an object
String	serializeAllExceptFilter(Object src, Boolean cleanFilter, String... filterAttr)	Class Filter is derived from param src object class.
<T> String	serializeAllExceptFilter(Object src, Class<T> filterClass, Boolean cleanFilter, String... filterAttr)	Serialize all object properties excluding provided filters attributes.
<T> String	serializeAllExceptFilter(Object src, Class<T> filterClass, String... filterAttr)	Class Filter is derived from param src object class.
String	serializeAllExceptFilter(Object src, String... filterAttr)
String	serializeOnlyFilter(Object src, Boolean cleanFilter, String... filterAttr)	Custom method.
<T> String	serializeOnlyFilter(Object src, Class<T> filterClass, Boolean cleanFilter, String... filterAttr)	Serialize only object properties where filter attributes are provided.
<T> String	serializeOnlyFilter(Object src, Class<T> filterClass, String... filterAttr)
String	serializeOnlyFilter(Object src, String... filterAttr)	Custom method without caching.
void	setDateFormat(DateFormat df)

Field Detail

ROLE

static final String ROLE

Avalon Identifier

SERVICE_NAME

static final String SERVICE_NAME

Method Detail

ser

String ser(Object src)
    throws Exception

Serializes a Java object

Parameters:

src - the java object to be serialized, not null.

Returns:

JSON string

Throws:

Exception - if JSON serialization fails

ser

String ser(Object src,
           Boolean cleanCache)
    throws Exception

Parameters:

src - the java object to be serialized, not null.

cleanCache - a boolean value, not null. If true, try to refresh cache after serialization

Returns:

serialized object

Throws:

Exception - generic exception

ser

<T> String ser(Object src,
               Class<T> type)
        throws Exception

Serializes a Java object

Type Parameters:

T - The class type

Parameters:

src - The Java object to be serialized

type - the Java Type, which should be used for the provided object

Returns:

JSON string

Throws:

Exception - If JSON serialization fails

ser

<T> String ser(Object src,
               Class<T> type,
               Boolean cleanCache)
        throws Exception

Serialize an object

Type Parameters:

T - class type of the object

Parameters:

src - The source object

type - The class type of the object

cleanCache - If true, try to clean cache after serialization For other attributes @see ser(Object, Class)

Returns:

the serialized class

Throws:

Exception - if the JSON serialization fails

deSer

<T> T deSer(String src,
            Class<T> type)
     throws Exception

Deserializing a JSON string

Type Parameters:

T - class type of the object

Parameters:

src - the JSON string to be deserialized

type - the Java Type to be used as a class

Returns:

the Java Object

Throws:

Exception - if JSON deserialization fails

deSerCollection

<T> Collection<T> deSerCollection(String json,
                                  Object collectionType,
                                  Class<T> elementType)
                           throws Exception

This is to deserialize collections. Depending on the implementation either both collectiontype and elementType is needed or the elementType will be derived from the typed collectiontype.

Type Parameters:

T - class type of the object

Parameters:

json - The JSON string to be deserialized

collectionType - It could be just the collection or the typed collection. It may then be used to get the type for element type too. Cft. implementation tests for more details (GSON).

elementType - The element type. This is need in any case to assure the generic checking.

Returns:

the generated Java Collection.

Throws:

Exception - if serialize collection fails

serializeOnlyFilter

String serializeOnlyFilter(Object src,
                           String... filterAttr)
                    throws Exception

Custom method without caching. Caching is set to false for this method call.

Parameters:

src - the source object

filterAttr - filter attributes

Returns:

JSON string

Throws:

Exception - if fails

See Also:

refreshFilter is set to true for this method call.

serializeOnlyFilter

String serializeOnlyFilter(Object src,
                           Boolean cleanFilter,
                           String... filterAttr)
                    throws Exception

Custom method. Caching key is derived from param src object class.

Parameters:

src - The Java object to serialize

cleanFilter - The Boolean value, not null. If it is true, cleans cache and the custom filter after serialization. refreshFilter is set to true for this method call.

filterAttr - filter attributes

Returns:

JSON string

Throws:

Exception - if fails

See Also:

serializeOnlyFilter(Object, Class, Boolean, String...)

serializeOnlyFilter

<T> String serializeOnlyFilter(Object src,
                               Class<T> filterClass,
                               String... filterAttr)
                        throws Exception

Type Parameters:

T - class type of the object

Parameters:

src - The Java object to serialize

filterClass - The filter class

filterAttr - filter attributes

Returns:

JSON string

Throws:

Exception - if fails

See Also:

Caching is set to false for this method call.

serializeOnlyFilter

<T> String serializeOnlyFilter(Object src,
                               Class<T> filterClass,
                               Boolean cleanFilter,
                               String... filterAttr)
                        throws Exception

Serialize only object properties where filter attributes are provided. If no filter is set, no attributes should be returned.

Type Parameters:

T - class type of the object

Parameters:

src - The Java object to serialize

filterClass - By default filterClass is a) the class to be filtered (required for filtering list elements) b) the key in the filter object cached.

cleanFilter - The Boolean value, not null. If it is true, cleans cache and the custom filter after serialization.

filterAttr - The class bean attributes which should be serialized

Returns:

JSON string

Throws:

Exception - If JSON serialization or filter registration fails

serializeAllExceptFilter

<T> String serializeAllExceptFilter(Object src,
                                    Class<T> filterClass,
                                    Boolean cleanFilter,
                                    String... filterAttr)
                             throws Exception

Serialize all object properties excluding provided filters attributes. If no filter is set, all attributes should be returned.

Type Parameters:

T - class type of the object

Parameters:

src - The Java object to serialize. By default the filtering is applied for this class. By default the class of the src object is the key for the filter object cached.

filterClass - The class, which should be filtered out, if found as a property type.

cleanFilter - If true cleans filter (clean cache and custom filter for this filterClass) after serialization.

filterAttr - The bean attributes which should not be serialized

Returns:

JSON string

Throws:

Exception - If JSON serialization or filter registration fails

serializeAllExceptFilter

<T> String serializeAllExceptFilter(Object src,
                                    Class<T> filterClass,
                                    String... filterAttr)
                             throws Exception

Class Filter is derived from param src object class. refreshFilter is set to false for this method call.

Type Parameters:

T - class type of the object

Parameters:

src - The Java object to serialize. By default the filtering is applied for this class. By default the class of the src object is the key for the filter object cached.

filterClass - The class, which should be filtered out, if found as a property type.

filterAttr - The bean attributes which should not be serialized

Returns:

JSON string

Throws:

Exception - If JSON serialization or filter registration fails

See Also:

refreshFilter is false.

serializeAllExceptFilter

String serializeAllExceptFilter(Object src,
                                Boolean cleanFilter,
                                String... filterAttr)
                         throws Exception

Class Filter is derived from param src object class.

Parameters:

src - The Java object to serialize. By default the filtering is applied for this class. By default the class of the src object is the key for the filter object cached.

cleanFilter - If true cleans filter (clean cache and custom filter for this filterClass) after serialization.

filterAttr - The bean attributes which should not be serialized

Returns:

JSON string

Throws:

Exception - If JSON serialization or filter registration fails

See Also:

serializeAllExceptFilter(Object, Class, Boolean, String...)

serializeAllExceptFilter

String serializeAllExceptFilter(Object src,
                                String... filterAttr)
                         throws Exception

Parameters:

src - The Java object to serialize. By default the filtering is applied for this class. By default the class of the src object is the key for the filter object cached.

filterAttr - The bean attributes which should not be serialized

Returns:

JSON string

Throws:

Exception - If JSON serialization or filter registration fails

See Also:

serializeAllExceptFilter(Object, Class, Boolean, String...)

addAdapter

JsonService addAdapter(String name,
                       Class target,
                       Class mixin)
                throws Exception

Adds an adapter (mixin, serializer,..) for the target class depending on the JsonService implementation. Cft. to addAdapter(String, Class, Object)

Parameters:

name - The name of the adapter

target - The target class for this adapter

mixin - The adapter/mixin for the target class

Returns:

the JsonService instance

Throws:

Exception - If adapter registration fails

addAdapter

JsonService addAdapter(String name,
                       Class target,
                       Object mixin)
                throws Exception

Add an adapter (mixin, serializer,..) for the target class depending on the JsonService implementation. Adapters could by default not deregistered. If you want to get rid of them, you may try to reinit the service (or overwrite with the same target type, depending on implementation)

Parameters:

name - The name of the adapter

target - The target class for this adapter

mixin - The adapter/mixin for the target object (module/serializer/deserializer)

Returns:

A JsonService instance

Throws:

Exception - if adapter registration fails

setDateFormat

void setDateFormat(DateFormat df)

Parameters:

df - The DateFormat to be used by the JsonService, not null. It could be provided by component configuration too.