org.infinispan.marshall
Interface Externalizer<T>

All Known Implementing Classes:
AbstractExternalizer, AbstractWheelConsistentHash.Externalizer, ArrayListExternalizer, AtomicHashMap.Externalizer, AtomicHashMapDelta.Externalizer, Bucket.Externalizer, ByteArrayKey.Externalizer, ChunkCacheKey.Externalizer, ClearOperation.Externalizer, DefaultConsistentHash.Externalizer, DldGlobalTransaction.Externalizer, ExceptionResponse.Externalizer, ExperimentalDefaultConsistentHash.Externalizer, ExtendedResponse.Externalizer, FileCacheKey.Externalizer, FileListCacheKey.Externalizer, FileMetadata.Externalizer, FileReadLockKey.Externalizer, Fqn.Externalizer, GlobalTransaction.Externalizer, ImmortalCacheEntry.Externalizer, ImmortalCacheValue.Externalizer, Immutables.ImmutableMapWrapperExternalizer, JGroupsAddress.Externalizer, LinkedListExternalizer, MapExternalizer, MarshalledValue.Externalizer, MortalCacheEntry.Externalizer, MortalCacheValue.Externalizer, NodeKey.Externalizer, NodeTopologyInfo.Externalizer, PutOperation.Externalizer, RecoveryAwareDldGlobalTransaction.Externalizer, RecoveryAwareGlobalTransaction.Externalizer, RemoteTransactionLogDetails.Externalizer, RemoveOperation.Externalizer, ReplicableCommandExternalizer, RequestIgnoredResponse.Externalizer, SerializableXid.XidExternalizer, SetExternalizer, SingletonListExternalizer, SuccessfulResponse.Externalizer, TopologyAwareConsistentHash.Externalizer, TransactionLog.LogEntry.Externalizer, TransientCacheEntry.Externalizer, TransientCacheValue.Externalizer, TransientMortalCacheEntry.Externalizer, TransientMortalCacheValue.Externalizer, UnionConsistentHash.Externalizer, UnsuccessfulResponse.Externalizer, UnsureResponse.Externalizer

public interface Externalizer<T>

One of the key aspects of Infinispan is that it often needs to marshall/unmarshall objects in order to provide some of its functionality. For example, if it needs to store objects in a write-through or write-behind cache store, the objects stored need marshalling. If a cluster of Infinispan nodes is formed, objects shipped around need marshalling. Even if you enable lazy deserialization, objects need to marshalled so that they can be lazily unmarshalled with the correct classloader. Using standard JDK serialization is slow and produces payloads that are too big and can affect bandwidth usage. On top of that, JDK serialization does not work well with objects that are supposed to be immutable. In order to avoid these issues, Infinispan uses JBoss Marshalling for marshalling/unmarshalling objects. JBoss Marshalling is fast , provides very space efficient payloads, and on top of that, allows users to construct objects themselves during unmarshalling, hence allowing objects to carry on being immutable. Starting with 5.0, users of Infinispan can now benefit from this marshalling framework as well, and they can provide their own implementations of the Externalizer interface in order to define, how a particular object type needs to be marshalled or unmarshalled. It's common practice to include Externalizer implementations within the classes that they marshall/unmarshall as public static classes. To make Externalizer implementations easier to code and more typesafe, make sure you define type as the type of object that's being marshalled/unmarshalled. You can find plenty of examples of Externalizer implementations in the Infinispan code base, but to highlight one, check the Externalizer implementation for JGroupsAddress in JGroupsAddress.Externalizer AbstractExternalizer provides default implementations for some of the methods defined in this interface and so it's generally recommended that implementations extend that abstract class instead of implementing Externalizer directly.

Since:
4.0
Author:
Galder ZamarreƱo

Method Summary
 Integer getId()
          Returns an integer that identifies the externalizer type.
 Set<Class<? extends T>> getTypeClasses()
          Returns a collection of Class instances representing the types that this Externalizer can marshall.
 T readObject(ObjectInput input)
          Read an instance from the stream.
 void writeObject(ObjectOutput output, T object)
          Write the object reference to the stream.
 

Method Detail

writeObject

void writeObject(ObjectOutput output,
                 T object)
                 throws IOException
Write the object reference to the stream.

Parameters:
output - the object output to write to
object - the object reference to write
Throws:
IOException - if an I/O error occurs

readObject

T readObject(ObjectInput input)
             throws IOException,
                    ClassNotFoundException
Read an instance from the stream. The instance will have been written by the writeObject(ObjectOutput, Object) method. Implementations are free to create instances of the object read from the stream in any way that they feel like. This could be via constructor, factory or reflection.

Parameters:
input - the object input to read from
Returns:
the object instance
Throws:
IOException - if an I/O error occurs
ClassNotFoundException - if a class could not be found

getTypeClasses

Set<Class<? extends T>> getTypeClasses()
Returns a collection of Class instances representing the types that this Externalizer can marshall. Clearly, empty sets are not allowed.

Returns:
A set containing the Class instances that can be marshalled.

getId

Integer getId()
Returns an integer that identifies the externalizer type. This is used at read time to figure out which Externalizer should read the contents of the incoming buffer. Using a positive integer allows for very efficient variable length encoding of numbers, and it's much more efficient than shipping Externalizer implementation class information around. Negative values are not allowed. Implementers of this interface can use any positive integer as long as it does not clash with any other identifier in the system. You can find information on the pre-assigned identifier ranges in here. It's highly recommended that maintaining of these identifiers is done in a centralized way and you can do so by making annotations reference a set of statically defined identifiers in a separate class or interface. Such class/interface gives a global view of the identifiers in use and so can make it easier to assign new ids. Implementors can optionally avoid giving a meaningful implementation to this method (i.e. return null) and instead rely on XML or programmatic configuration to provide the Externalizer id. If no id can be determined via the implementation or XML/programmatic configuration, an error will be reported. If an id has been defined both via the implementation and XML/programmatic configuration, the value defined via XML/programmatic configuration will be used ignoring the other.

Returns:
A positive identifier for the Externalizer.

-->

Copyright © 2011 JBoss, a division of Red Hat. All Rights Reserved.