org.fudgemsg
Class FudgeContext

java.lang.Object
  org.fudgemsg.FudgeContext

All Implemented Interfaces:

FudgeMessageFactory

Direct Known Subclasses:

ImmutableFudgeContext

public class FudgeContext
extends Object
implements FudgeMessageFactory

The primary entry-point for code to interact with the rest of the Fudge system. For performance reasons, there are many options that are passed around as parameters inside static methods for encoding and decoding, and many lightweight objects that ideally don't know of their configuration context. However, in a large application, it is often desirable to collect all configuration parameters in one location and inject options into it.

FudgeContext allows application developers to have a single location to inject dependent parameters and instances, and make them available through simple method invocations. In addition, because it wraps all checked exceptions into instances of FudgeRuntimeException, it is the ideal way to use the Fudge encoding system from within Spring applications.

While most applications will have a single instance of FudgeContext, some applications will have one instance per unit of encoding/decoding parameters. For example, if an application is consuming data from two messaging feeds, each of which reuses the same taxonomy ID to represent a different FudgeTaxonomy, it would configure two different instances of FudgeContext, one per feed.

Field Summary

static FudgeFieldContainer	EMPTY_MESSAGE A global empty FudgeFieldContainer.
static FudgeMsgEnvelope	EMPTY_MESSAGE_ENVELOPE A global empty FudgeMsgEnvelope.
static FudgeContext	GLOBAL_DEFAULT A default global FudgeContext for getting code up and running quickly.

Constructor Summary

FudgeContext()
Constructs a new FudgeContext with a default type and object dictionary.

FudgeContext(FudgeContext other)
Constructs a new FudgeContext with copies of the supplied context's type and object dictionaries.

Method Summary

FudgeMsgReader	createMessageReader(DataInput dataInput) Creates a new reader for extracting whole Fudge messages from a DataInput source.
FudgeMsgReader	createMessageReader(InputStream inputStream) Creates a new reader for extracting whole Fudge messages from a InputStream source.
FudgeMsgWriter	createMessageWriter(DataOutput dataOutput) Creates a new writer for sending whole Fudge messages to a DataOutput target.
FudgeMsgWriter	createMessageWriter(OutputStream outputStream) Creates a new writer for sending whole Fudge messages to a OutputStream target.
FudgeObjectReader	createObjectReader(DataInput dataInput) Creates a new reader for deserialising Java objects from a Fudge data source.
FudgeObjectReader	createObjectReader(InputStream inputStream) Creates a new reader for deserialising Java objects from a Fudge data source.
FudgeObjectWriter	createObjectWriter(DataOutput dataOutput) Creates a new writer for serialising Java objects to a Fudge stream.
FudgeObjectWriter	createObjectWriter(OutputStream outputStream) Creates a new writer for serialising Java objects to a Fudge stream.
FudgeStreamReader	createReader(DataInput di) Creates a new reader for extracting Fudge stream elements from a DataInput.
FudgeStreamReader	createReader(InputStream is) Creates a new reader for extracting Fudge stream elements from an InputStream.
FudgeStreamWriter	createWriter(DataOutput dataOutput) Creates a new writer for encoding Fudge stream elements to a DataOutput.
FudgeStreamWriter	createWriter(OutputStream outputStream) Creates a new writer for encoding Fudge stream elements to a OutputStream.
FudgeMsgEnvelope	deserialize(byte[] bytes) Decodes a Fudge message from a byte array.
FudgeMsgEnvelope	deserialize(InputStream is) Decodes a Fudge message from an InputStream.
<T> T	fromFudgeMsg(Class<T> clazz, FudgeFieldContainer message) Deserializes a FudgeFieldContainer message to a Java object of type clazz.
Object	fromFudgeMsg(FudgeFieldContainer message) Deserializes a FudgeFieldContainer message to a Java object, trying to determine the type of the object automatically.
<T> T	getFieldValue(Class<T> clazz, FudgeField field) Type conversion for secondary types using information registered in the current type dictionary.
FudgeObjectDictionary	getObjectDictionary() Returns the current FudgeObjectDictionary used by the context for object/Fudge message serialisation and deserialisation.
TaxonomyResolver	getTaxonomyResolver() Returns the current TaxonomyResolver used by this context.
FudgeTypeDictionary	getTypeDictionary() Returns the current FudgeTypeDictionary used by this context and any messages created or decoded through it.
MutableFudgeFieldContainer	newMessage() Creates an initially empty message.
MutableFudgeFieldContainer	newMessage(FudgeFieldContainer fromMessage) Creates a new message initially populated with the supplied message.
<T> T	readObject(Class<T> objectClass, InputStream inputStream) Reads a Java object from an InputStream using the Fudge serialization framework.
void	serialize(FudgeFieldContainer msg, OutputStream os) Encodes a Fudge message object to an OutputStream without any taxonomy reference.
void	serialize(FudgeFieldContainer msg, Short taxonomyId, OutputStream os) Encodes a Fudge message object to an OutputStream with an optional taxonomy reference.
void	setConfiguration(FudgeContextConfiguration... configurations) Passes this context to the configuration objects supplied to update the type and object dictionaries.
void	setObjectDictionary(FudgeObjectDictionary objectDictionary) Sets the current FudgeObjectDictionary to be used for object/Fudge message serialisation and deserialisation.
void	setTaxonomyResolver(TaxonomyResolver taxonomyResolver) Sets the TaxonomyResolver to be used by this context when expanding field names for incoming Fudge messages.
void	setTypeDictionary(FudgeTypeDictionary typeDictionary) Sets the current FudgeTypeDictionary to be used by the context and any messages created or decoded through it.
byte[]	toByteArray(FudgeFieldContainer msg) Returns the Fudge encoded form of a FudgeFieldContainer as a byte array without a taxonomy reference.
byte[]	toByteArray(FudgeFieldContainer msg, Short taxonomyId) Returns the Fudge encoded form of a FudgeFieldContainer as a byte array with a taxonomy reference.
<T> FudgeMsgEnvelope	toFudgeMsg(T obj) Converts a Java object to a FudgeMsgEnvelope using the Fudge serialization framework.
void	writeObject(Object object, OutputStream outputStream) Writes a Java object to an OutputStream using the Fudge serialization framework.

Methods inherited from class java.lang.Object

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

Field Detail

GLOBAL_DEFAULT

public static final FudgeContext GLOBAL_DEFAULT

A default global FudgeContext for getting code up and running quickly. The context cannot be modified in any way so can only be used for the core Fudge data types and will not support a taxonomy resolver. This should be used for trivial projects and code only.

EMPTY_MESSAGE

public static final FudgeFieldContainer EMPTY_MESSAGE

A global empty FudgeFieldContainer.

EMPTY_MESSAGE_ENVELOPE

public static final FudgeMsgEnvelope EMPTY_MESSAGE_ENVELOPE

A global empty FudgeMsgEnvelope.

Constructor Detail

FudgeContext

public FudgeContext()

Constructs a new FudgeContext with a default type and object dictionary.

FudgeContext

public FudgeContext(FudgeContext other)

Constructs a new FudgeContext with copies of the supplied context's type and object dictionaries. It will share the taxonomy resolver with the supplied context.

Parameters:

other - the context to copy the type and object dictionaries from

Method Detail

getTaxonomyResolver

public TaxonomyResolver getTaxonomyResolver()

Returns the current TaxonomyResolver used by this context. A new FudgeContext starts with its own, default, taxonomy resolver. Any custom taxonomies must be registered with a resolver before they can be used.

Returns:

the taxonomy resolver

setTaxonomyResolver

public void setTaxonomyResolver(TaxonomyResolver taxonomyResolver)

Sets the TaxonomyResolver to be used by this context when expanding field names for incoming Fudge messages.

Parameters:

taxonomyResolver - the TaxonomyResolver to set

getTypeDictionary

public FudgeTypeDictionary getTypeDictionary()

Returns the current FudgeTypeDictionary used by this context and any messages created or decoded through it. A new FudgeContext starts with its own, default, type dictionary. Any custom types must be registered with the dictionary before they can be used.

Returns:

the current FudgeTypeDictionary

setTypeDictionary

public void setTypeDictionary(FudgeTypeDictionary typeDictionary)

Sets the current FudgeTypeDictionary to be used by the context and any messages created or decoded through it.

Parameters:

typeDictionary - the new FudgeTypeDictionary

getObjectDictionary

public FudgeObjectDictionary getObjectDictionary()

Returns the current FudgeObjectDictionary used by the context for object/Fudge message serialisation and deserialisation. A new FudgeContext starts with its own, default, object dictionary. Any custom object or message builders must be registered with the dictionary before they can be used.

Returns:

the current FudgeObjectDictionary

setObjectDictionary

public void setObjectDictionary(FudgeObjectDictionary objectDictionary)

Sets the current FudgeObjectDictionary to be used for object/Fudge message serialisation and deserialisation.

Parameters:

objectDictionary - the new FudgeObjectDictionary

newMessage

public MutableFudgeFieldContainer newMessage()

Creates an initially empty message.

Specified by:

newMessage in interface FudgeMessageFactory

Returns:

the empty message container, not null

newMessage

public MutableFudgeFieldContainer newMessage(FudgeFieldContainer fromMessage)

Creates a new message initially populated with the supplied message.

Specified by:

newMessage in interface FudgeMessageFactory

Parameters:

fromMessage - the source message to copy fields from, not null

Returns:

the new message container, not null

serialize

public void serialize(FudgeFieldContainer msg,
                      OutputStream os)

Encodes a Fudge message object to an OutputStream without any taxonomy reference.

Parameters:

msg - the FudgeFieldContainer to write

os - the OutputStream to write to

serialize

public void serialize(FudgeFieldContainer msg,
                      Short taxonomyId,
                      OutputStream os)

Encodes a Fudge message object to an OutputStream with an optional taxonomy reference. If a taxonomy is supplied it may be used to optimize the output by writing ordinals instead of field names.

Parameters:

msg - the FudgeMsg to write

taxonomyId - the identifier of the taxonomy to use. Specify null for no taxonomy.

os - the OutputStream to write to

toByteArray

public byte[] toByteArray(FudgeFieldContainer msg,
                          Short taxonomyId)

Returns the Fudge encoded form of a FudgeFieldContainer as a byte array with a taxonomy reference. The encoding includes an envelope header.

Parameters:

msg - the FudgeFieldContainer to encode

taxonomyId - the identifier of the taxonomy to use. Specify null or 0 for no taxonomy

Returns:

an array containing the encoded message

toByteArray

public byte[] toByteArray(FudgeFieldContainer msg)

Returns the Fudge encoded form of a FudgeFieldContainer as a byte array without a taxonomy reference. The encoding includes an envelope header.

Parameters:

msg - the FudgeFieldContainer to encode

Returns:

an array containing the encoded message

deserialize

public FudgeMsgEnvelope deserialize(InputStream is)

Decodes a Fudge message from an InputStream.

Parameters:

is - the InputStream to read encoded data from

Returns:

the next FudgeMsgEnvelope encoded on the stream

deserialize

public FudgeMsgEnvelope deserialize(byte[] bytes)

Decodes a Fudge message from a byte array. If the array is larger than the Fudge envelope, any additional data is ignored.

Parameters:

bytes - an array containing the encoded Fudge message including its envelope

Returns:

the decoded FudgeMsgEnvelope

createReader

public FudgeStreamReader createReader(InputStream is)

Creates a new reader for extracting Fudge stream elements from an InputStream.

Parameters:

is - the InputStream to read from

Returns:

the FudgeStreamReader

createReader

public FudgeStreamReader createReader(DataInput di)

Creates a new reader for extracting Fudge stream elements from a DataInput.

Parameters:

di - the DataInput to read from

Returns:

the FudgeStreamReader

createWriter

public FudgeStreamWriter createWriter(OutputStream outputStream)

Creates a new writer for encoding Fudge stream elements to a OutputStream.

Parameters:

outputStream - the OutputStream to write to

Returns:

the FudgeStreamWriter

createWriter

public FudgeStreamWriter createWriter(DataOutput dataOutput)

Creates a new writer for encoding Fudge stream elements to a DataOutput.

Parameters:

dataOutput - the DataOutput to write to

Returns:

the FudgeStreamWriter

createMessageReader

public FudgeMsgReader createMessageReader(DataInput dataInput)

Creates a new reader for extracting whole Fudge messages from a DataInput source.

Parameters:

dataInput - the source of data

Returns:

the FudgeMsgReader

createMessageReader

public FudgeMsgReader createMessageReader(InputStream inputStream)

Creates a new reader for extracting whole Fudge messages from a InputStream source.

Parameters:

inputStream - the source of data

Returns:

the FudgeMsgReader

createMessageWriter

public FudgeMsgWriter createMessageWriter(DataOutput dataOutput)

Creates a new writer for sending whole Fudge messages to a DataOutput target.

Parameters:

dataOutput - the target to write to

Returns:

the FudgeMsgWriter

createMessageWriter

public FudgeMsgWriter createMessageWriter(OutputStream outputStream)

Creates a new writer for sending whole Fudge messages to a OutputStream target.

Parameters:

outputStream - the target to write to

Returns:

the FudgeMsgWriter

createObjectReader

public FudgeObjectReader createObjectReader(DataInput dataInput)

Creates a new reader for deserialising Java objects from a Fudge data source.

Parameters:

dataInput - the DataInput to read from

Returns:

the FudgeObjectReader

createObjectReader

public FudgeObjectReader createObjectReader(InputStream inputStream)

Creates a new reader for deserialising Java objects from a Fudge data source.

Parameters:

inputStream - the InputStream to read from

Returns:

the FudgeObjectReader

createObjectWriter

public FudgeObjectWriter createObjectWriter(DataOutput dataOutput)

Creates a new writer for serialising Java objects to a Fudge stream.

Parameters:

dataOutput - the target to write to

Returns:

the FudgeObjectWriter

createObjectWriter

public FudgeObjectWriter createObjectWriter(OutputStream outputStream)

Creates a new writer for serialising Java objects to a Fudge stream.

Parameters:

outputStream - the target to write to

Returns:

the FudgeObjectWriter

writeObject

public void writeObject(Object object,
                        OutputStream outputStream)

Writes a Java object to an OutputStream using the Fudge serialization framework. The current FudgeObjectDictionary will be used to identify any custom message builders or apply default serialization behavior. Either a new serialization context will be used or an existing one reset for this operation.

Parameters:

object - the Object to write

outputStream - the OutputStream to write the Fudge encoded form of the object to

readObject

public <T> T readObject(Class<T> objectClass,
                        InputStream inputStream)

Reads a Java object from an InputStream using the Fudge serialization framework. The current FudgeObjectDictionary will be used to identify any custom object builders or apply default deserialization behavior. Always reads the next available Fudge message from the stream even if the message cannot be converted to the requested Object. Either a new deserialization context will be used or an existing one reset for this operation.

Type Parameters:

T - the target type to decode the message to

Parameters:

objectClass - the target Class to decode a message of. If an object of this or a sub-class is not available, an exception will be thrown.

inputStream - the InputStream to read the next Fudge message from

Returns:

the object read

toFudgeMsg

public <T> FudgeMsgEnvelope toFudgeMsg(T obj)

Converts a Java object to a FudgeMsgEnvelope using the Fudge serialization framework. Note that for repeated operations, it would be more efficient to maintain a FudgeSerializationContext instance and use that.

Type Parameters:

T - Java type

Parameters:

obj - object to serialize

Returns:

the serialized message

fromFudgeMsg

public Object fromFudgeMsg(FudgeFieldContainer message)

Deserializes a FudgeFieldContainer message to a Java object, trying to determine the type of the object automatically. Note that for repeated operations, it would be more efficient to maintain a FudgeDeserializationContext instance and use that.

Parameters:

message - the Fudge message to deserialize

Returns:

the deserialized object

fromFudgeMsg

public <T> T fromFudgeMsg(Class<T> clazz,
                          FudgeFieldContainer message)

Deserializes a FudgeFieldContainer message to a Java object of type clazz. Note that for repeated operations, it would be more efficient to maintain a FudgeDeserializationContext instance and use that.

Type Parameters:

T - Java type

Parameters:

clazz - the target type to deserialize

message - the message to process

Returns:

the deserialized object

getFieldValue

public <T> T getFieldValue(Class<T> clazz,
                           FudgeField field)

Type conversion for secondary types using information registered in the current type dictionary. See FudgeTypeDictionary.getFieldValue(java.lang.Class, org.fudgemsg.FudgeField) for more information.

Type Parameters:

T - type to convert to

Parameters:

clazz - target class for the converted value

field - field containing the value to convert

Returns:

the converted value

setConfiguration

public void setConfiguration(FudgeContextConfiguration... configurations)

Passes this context to the configuration objects supplied to update the type and object dictionaries. This can be used with Bean based frameworks to configure a context for custom types through injection.

Parameters:

configurations - the configuration objects to use