com.opencloud.rhino.util

Class EncodableMap<K,V>

java.lang.Object

com.opencloud.rhino.util.EncodableMap<K,V>

Type Parameters:

K - map key type.

V - map value type.

All Implemented Interfaces:

Encodable, Map<K,V>

public abstract class EncodableMap<K,V>
extends Object
implements Map<K,V>, Encodable

Generic implementation of a map structure that can be stored in SLEE CMP fields with sensible serialisation semantics. This class essentially provides a layer on top of some other map implementation, delegating method calls on the Map interface through to the underlying map implementation, while handling the serialisation and deserialisation of the map's state via the contract provided by the Encodable interface.

In order to use this map, a subclass must be implemented that:

• Provides at least a public constructor satisfying the contract of the Encodable interface.
• Implements the abstract write* and read* methods defined in this class to serialise and deserialise individual map keys and values.

This implementation provides the ability to specify what type of map structure to use as a backing store from a set of predefined types. A subclass may use an alternative map implementation by:

• Invoking the one-arg class constructor passing null as the backingStore parameter; and
• Overriding the newMapInstance(BackingStore) method to create the required map structure, disregarding the method argument.

Since:

Rhino 2.4.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EncodableMap.BackingStore Pre-defined backing stores for the EncodableMap.

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

Constructors

Modifier	Constructor and Description
	EncodableMap() Create an EncodableMap using EncodableMap.BackingStore.HASH as the default backing store.
protected	EncodableMap(DataInput in, ClassLoader cl, DecoderUtils utils) Creates an EncodableMap with state restored from the specified input stream.
	EncodableMap(EncodableMap.BackingStore backingStore) Create an EncodableMap using the specified backing store.
protected	EncodableMap(EncodableMap.BackingStore backingStore, Map<K,V> map) Create an EncodableSet using the specified backing store and map.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
void	encode(DataOutput out, EncoderUtils utils) Encode the state of this object to the given data output stream.
Set<Map.Entry<K,V>>	entrySet()
boolean	equals(Object o)
protected void	fromStream(DataInput in, ClassLoader cl, DecoderUtils utils) Populate map entries with state restored from the specified input stream.
V	get(Object key)
int	hashCode()
boolean	isEmpty()
Set<K>	keySet()
protected boolean	manageNullKeys() Determine if this EncodableMap type should manage null keys within the serialisation logic.
protected boolean	manageNullValues() Determine if this EncodableMap type should manage null values within the serialisation logic.
protected Map<K,V>	newMapInstance(EncodableMap.BackingStore backingStore) Create a new map instance for the backing store.
V	put(K key, V value)
void	putAll(Map<? extends K,? extends V> m)
protected abstract K	readKey(DataInput in, ClassLoader cl, DecoderUtils utils) Deserialise a map key from the input stream.
protected abstract V	readValue(DataInput in, ClassLoader cl, DecoderUtils utils) Deserialise a map value from the input stream.
V	remove(Object key)
int	size()
protected void	toStream(DataOutput out, EncoderUtils utils) Serialise the state of the map to the given output stream.
String	toString()
Collection<V>	values()
protected abstract void	writeKey(K key, DataOutput out, EncoderUtils utils) Serialise the specified map key to the output stream.
protected abstract void	writeValue(V value, DataOutput out, EncoderUtils utils) Serialise the specified map value to the output stream.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EncodableMap

public EncodableMap()

Create an EncodableMap using EncodableMap.BackingStore.HASH as the default backing store.

EncodableMap

public EncodableMap(EncodableMap.BackingStore backingStore)

Create an EncodableMap using the specified backing store.

Parameters:

backingStore - the backing store to use.

EncodableMap

protected EncodableMap(EncodableMap.BackingStore backingStore,
            Map<K,V> map)

Create an EncodableSet using the specified backing store and map. This constructor may be used to create an EncodableMap that wraps a pre-existing map.

Parameters:

backingStore - the backing store to use.

map - the initial map state.

EncodableMap

protected EncodableMap(DataInput in,
            ClassLoader cl,
            DecoderUtils utils)
                throws IOException

Creates an EncodableMap with state restored from the specified input stream.

Parameters:

in - the input stream to read map state from.

cl - classloader that can be used to resolve class dependencies.

utils - additional utility decoding functions.

Throws:

IOException - if an I/O error occurs.

Method Detail

fromStream

protected void fromStream(DataInput in,
              ClassLoader cl,
              DecoderUtils utils)
                   throws IOException

Populate map entries with state restored from the specified input stream. This method typically would only be used after the map has been cleared, and can be used to recycle the underlying map object.

Warning: This method can only be used to deserialise a map serialised using the toStream(DataOutput, EncoderUtils) method. It will not work with a map serialised using the encode(DataOutput, EncoderUtils) method.

Parameters:

in - the input stream to read map state from.

cl - classloader that can be used to resolve class dependencies.

utils - additional utility decoding functions.

Throws:

IOException - if an I/O error occurs.

encode

public void encode(DataOutput out,
          EncoderUtils utils)
            throws IOException

Description copied from interface: Encodable

Encode the state of this object to the given data output stream.

Specified by:

encode in interface Encodable

Parameters:

out - the data output stream to encode the value to.

utils - additional utility encoding functions that may be useful to the encoder.

Throws:

IOException - if an I/O error occurs.

toStream

protected void toStream(DataOutput out,
            EncoderUtils utils)
                 throws IOException

Serialise the state of the map to the given output stream.

Warning: the serialisation data created by this method can only be restored using the fromStream(DataInput, ClassLoader, DecoderUtils) method. For a more general result that follows the Encodable contract, use the encode(DataOutput, EncoderUtils) method.

Parameters:

out - the output stream to write map state to.

utils - additional utility encoding functions.

Throws:

IOException - if an I/O error occurs.

size

public int size()

Specified by:

size in interface Map<K,V>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

put

public V put(K key,
    V value)

Specified by:

put in interface Map<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

putAll

public void putAll(Map<? extends K,? extends V> m)

Specified by:

putAll in interface Map<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

entrySet

public Set<Map.Entry<K,V>> entrySet()

Specified by:

entrySet in interface Map<K,V>

equals

public boolean equals(Object o)

Specified by:

equals in interface Map<K,V>

Overrides:

equals in class Object

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<K,V>

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

manageNullKeys

protected boolean manageNullKeys()

Determine if this EncodableMap type should manage null keys within the serialisation logic.

The result of this method determines whether or not null checks are included for keys in the output stream when the map is serialised. If null keys are never expected, not supported by the underlying backing store, or the implementation of writeKey(K, java.io.DataOutput, com.opencloud.rhino.cmp.codecs.EncoderUtils) and readKey(java.io.DataInput, java.lang.ClassLoader, com.opencloud.rhino.cmp.codecs.DecoderUtils) will handle null keys, then this method may safely return false.

The default implementation of this method always returns false.

Returns:

true if null keys should be managed, false otherwise.

manageNullValues

protected boolean manageNullValues()

Determine if this EncodableMap type should manage null values within the serialisation logic.

The result of this method determines whether or not null checks are included for values in the output stream when the map is serialised. If null values are never expected, not supported by the underlying backing store, or the implementation of writeValue(V, java.io.DataOutput, com.opencloud.rhino.cmp.codecs.EncoderUtils) and readValue(java.io.DataInput, java.lang.ClassLoader, com.opencloud.rhino.cmp.codecs.DecoderUtils) will handle null values, then this method may safely return false.

The default implementation of this method always returns true.

Returns:

true if null values should be managed, false otherwise.

newMapInstance

protected Map<K,V> newMapInstance(EncodableMap.BackingStore backingStore)

Create a new map instance for the backing store. The default behaviour of this method simply returns the value of backingStore.createMap().

Parameters:

backingStore - the backing store originally passed in to the class constructor when the EncodableMap was first created.

Returns:

a map.

writeKey

protected abstract void writeKey(K key,
            DataOutput out,
            EncoderUtils utils)
                          throws IOException

Serialise the specified map key to the output stream.

Parameters:

key - the map key, may be null if the underlying map supports null keys and manageNullKeys() return false.

out - the output stream to write the key state to.

utils - additional utility encoding functions that may be useful when serialising the key.

Throws:

IOException - if an I/O error occurs.

writeValue

protected abstract void writeValue(V value,
              DataOutput out,
              EncoderUtils utils)
                            throws IOException

Serialise the specified map value to the output stream.

Parameters:

value - the map value, may be null if the underlying map supports null values and manageNullValues() return false.

out - the output stream to write the value state to.

utils - additional utility encoding functions that may be useful when serialising the value.

Throws:

IOException - if an I/O error occurs.

readKey

protected abstract K readKey(DataInput in,
        ClassLoader cl,
        DecoderUtils utils)
                      throws IOException

Deserialise a map key from the input stream.

Parameters:

in - the input stream to read the key state from.

cl - classloader that can be used to resolve class dependencies.

utils - additional utility decoding functions that may be useful when deserialising the key.

Returns:

a map key.

Throws:

IOException - if an I/O error occurs.

readValue

protected abstract V readValue(DataInput in,
          ClassLoader cl,
          DecoderUtils utils)
                        throws IOException

Deserialise a map value from the input stream.

Parameters:

in - the input stream to read the value state from.

cl - classloader that can be used to resolve class dependencies.

utils - additional utility decoding functions that may be useful when deserialising the value.

Returns:

a map value.

Throws:

IOException - if an I/O error occurs.