org.fudgemsg.mapping
Class FudgeObjectDictionary

java.lang.Object
  org.fudgemsg.mapping.FudgeObjectDictionary

Direct Known Subclasses:

ImmutableFudgeObjectDictionary

public class FudgeObjectDictionary
extends Object

Extensible dictionary of types that Fudge can convert to and from wire format.

This class contains a cache of mappings from Java types to Fudge messages. There is one instance of the dictionary per context.

Mappings may be added in three main ways.

The simplest way is to create an instance of FudgeBuilder and call the addBuilder method. This will register an instance of the builder for a specific type. Subclasses of the type will not use the builder.

The second mechanism is classpath scanning. Simply annotate the builder class with FudgeBuilderFor, and call addAllClasspathBuilders. The method can be slow when operating on a large classpath. The system property org.fudgemsg.autoscan allows this to be done automatically.

The third method is generic builders. This class contains a single instance of FudgeBuilderFactory, which is capable of creating builders on demand. See FudgeDefaultBuilderFactory for the default list of handled types. Further generic builders can be registered with the factory. These generic builders will handle subclasses of the registered type.

All builder caching is done in this class. The factory is not responsible for caching.

Registering a different factory, or registering additional/different generic builders can change the default behavior for unrecognized types. As such, it is recommended to only initialize the dictionary at system startup. However, the cache is concurrent, so will handle later additions.

Field Summary

static String

AUTO_CLASSPATH_SCAN_PROPERTY The name of the property to be set (to any value) to automatically scan the classpath for builders on startup.

Constructor Summary

FudgeObjectDictionary()
Constructs a new (initially empty) FudgeObjectDictionary.

FudgeObjectDictionary(FudgeObjectDictionary other)
Constructs a new FudgeObjectDictionary as a clone of another.

Method Summary

void	addAllAnnotatedBuilders() Scans all files available to common classpath loading system heuristics to determine which ones have the FudgeBuilderFor annotation, and registers those as appropriate builders.
void	addAnnotatedBuilderClass(String className) Add a class which is known to have a FudgeBuilderFor annotation as an object or message builder (or both).
void	addAnnotatedGenericBuilderClass(String className) Add a class which is known to have a GenericFudgeBuilderFor annotation as builder.
<T> void	addBuilder(Class<T> clazz, FudgeBuilder<T> builder) Registers a new FudgeBuilder with this dictionary to be used for a given class.
<T> void	addMessageBuilder(Class<T> clazz, FudgeMessageBuilder<? super T> builder) Registers a new FudgeMessageBuilder with this dictionary to be used for a given class.
<T> void	addObjectBuilder(Class<T> clazz, FudgeObjectBuilder<? extends T> builder) Registers a new FudgeObjectBuilder with this dictionary to be used for a given class.
FudgeBuilderFactory	getDefaultBuilderFactory() Returns the current builder factory for unregistered types.
Class<?>	getDefaultObjectClass(int maxOrdinal) Returns the class indicated by a default serialization scheme.
<T> FudgeMessageBuilder<T>	getMessageBuilder(Class<T> clazz) Returns a FudgeMessageBuilder for the given class to convert a Fudge message to a Java object.
<T> FudgeObjectBuilder<T>	getObjectBuilder(Class<T> clazz) Returns a FudgeObjectBuilder for the given class to convert a Fudge message to a Java object.
boolean	isDefaultObject(Class<?> clazz) Tests if the specification requires a default serialization, for example lists, maps, sets and arrays.
void	setDefaultBuilderFactory(FudgeBuilderFactory defaultBuilderFactory) Sets the builder factory to use for types that are not explicitly registered here.

Methods inherited from class java.lang.Object

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

Field Detail

AUTO_CLASSPATH_SCAN_PROPERTY

public static final String AUTO_CLASSPATH_SCAN_PROPERTY

The name of the property to be set (to any value) to automatically scan the classpath for builders on startup.

See Also:

Constant Field Values

Constructor Detail

FudgeObjectDictionary

public FudgeObjectDictionary()

Constructs a new (initially empty) FudgeObjectDictionary.

FudgeObjectDictionary

public FudgeObjectDictionary(FudgeObjectDictionary other)

Constructs a new FudgeObjectDictionary as a clone of another.

Parameters:

other - the FudgeObjectDictionary to clone

Method Detail

getDefaultBuilderFactory

public FudgeBuilderFactory getDefaultBuilderFactory()

Returns the current builder factory for unregistered types.

Returns:

the current FudgeBuilderFactory.

setDefaultBuilderFactory

public void setDefaultBuilderFactory(FudgeBuilderFactory defaultBuilderFactory)

Sets the builder factory to use for types that are not explicitly registered here. It is recommended that FudgeBuilderFactory implementations are made using the FudgeBuilderFactoryAdapter, constructed with the previously set factory so that the behaviours can be chained.

Parameters:

defaultBuilderFactory - the FudgeBuilderFactory to use

addObjectBuilder

public <T> void addObjectBuilder(Class<T> clazz,
                                 FudgeObjectBuilder<? extends T> builder)

Registers a new FudgeObjectBuilder with this dictionary to be used for a given class. The same builder can be registered against multiple classes. A class can only have one registered FudgeObjectBuilder - registering a second will overwrite the previous registration.

Type Parameters:

T - Java type of the objects created by the builder

Parameters:

clazz - the Java class to register the builder against

builder - the builder to register

addMessageBuilder

public <T> void addMessageBuilder(Class<T> clazz,
                                  FudgeMessageBuilder<? super T> builder)

Registers a new FudgeMessageBuilder with this dictionary to be used for a given class. The same builder can be registered against multiple classes. A class can only have one registered FudgeMessageBuilder - registering a second will overwrite the previous registration.

Type Parameters:

T - Java type of the objects processed by the builder

Parameters:

clazz - the Java class to register the builder against

builder - builder to register

addBuilder

public <T> void addBuilder(Class<T> clazz,
                           FudgeBuilder<T> builder)

Registers a new FudgeBuilder with this dictionary to be used for a given class. A FudgeBuilder is simply a combined FudgeMessageBuilder and FudgeObjectBuilder so this method is the same as calling addMessageBuilder(Class,FudgeMessageBuilder) and addObjectBuilder(Class,FudgeObjectBuilder).

Type Parameters:

T - Java type of the objects processed by the builder

Parameters:

clazz - the Java class to register the builder against

builder - builder to register

getObjectBuilder

public <T> FudgeObjectBuilder<T> getObjectBuilder(Class<T> clazz)

Returns a FudgeObjectBuilder for the given class to convert a Fudge message to a Java object. If none is already registered for the class, it will attempt to create one using the registered FudgeBuilderFactory. If it is not possible to create a builder (e.g. for an interface) returns null.

Type Parameters:

T - Java type of the objects to be built

Parameters:

clazz - the Java class to look up

Returns:

the builder, or null if none is available

getMessageBuilder

public <T> FudgeMessageBuilder<T> getMessageBuilder(Class<T> clazz)

Returns a FudgeMessageBuilder for the given class to convert a Fudge message to a Java object. If none is already registered for the class, it will attempt to create one using the registered FudgeBuilderFactory. If it is not possible to create a builder returns null.

Type Parameters:

T - Java type of the objects to be built

Parameters:

clazz - the Java class to look up

Returns:

the builder, or null if none is available

isDefaultObject

public boolean isDefaultObject(Class<?> clazz)

Tests if the specification requires a default serialization, for example lists, maps, sets and arrays. Class headers are never needed and must be suppressed for default objects. The objects are just written with ordinal field values greater than 0.

Parameters:

clazz - the class to test, not null

Returns:

true if the object has a default serialization scheme.

getDefaultObjectClass

public Class<?> getDefaultObjectClass(int maxOrdinal)

Returns the class indicated by a default serialization scheme.

Parameters:

maxOrdinal - the highest ordinal used, or 0 if no field ordinals were present.

Returns:

the class to deserialize to, or null if the ordinal is not recognised

addAllAnnotatedBuilders

public void addAllAnnotatedBuilders()

Scans all files available to common classpath loading system heuristics to determine which ones have the FudgeBuilderFor annotation, and registers those as appropriate builders. This is potentially a very expensive operation, and as such is optional.

addAnnotatedBuilderClass

public void addAnnotatedBuilderClass(String className)

Add a class which is known to have a FudgeBuilderFor annotation as an object or message builder (or both).

Parameters:

className - The fully qualified name of the builder class.

addAnnotatedGenericBuilderClass

public void addAnnotatedGenericBuilderClass(String className)

Add a class which is known to have a GenericFudgeBuilderFor annotation as builder.

Parameters:

className - The fully qualified name of the builder class.