org.infinispan.commons.marshall

Interface Externalizer<T>

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

AdvancedExternalizer<T>, LambdaExternalizer<T>

All Known Implementing Classes:

AbstractExternalizer, AdminFlagExternalizer, ByteBufferImpl.Externalizer, EquivalenceExternalizer, Immutables.ImmutableMapWrapperExternalizer, Immutables.ImmutableSetWrapperExternalizer, InstanceReusingAdvancedExternalizer, KeyValueWithPrevious.KeyValueWithPreviousExternalizer, MurmurHash3.Externalizer, NoStateExternalizer, SingletonExternalizer, SuppliedExternalizer, WrappedByteArray.Externalizer

public interface Externalizer<T>
extends java.io.Serializable

One of the key aspects of Infinispan is that it often needs to marshall or 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 storing as binary, 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. In the simplest possible form, users just need to provide an Externalizer implementation for the type that they want to marshall/unmarshall, and then annotate the marshalled type class with SerializeWith indicating the externalizer class to use and that's all about it. At runtime JBoss Marshaller will inspect the object and discover that's marshallable thanks to the annotation and so marshall it using the externalizer class passed. 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. Even though this way of defining externalizers is very user friendly, it has some disadvantages:

• Due to several constraints of the model, such as support different versions of the same class or the need to marshall the Externalizer class, the payload sizes generated via this method are not the most efficient.
• This model requires for the marshalled class to be annoated with SerializeWith but a user might need to provide an Externalizer for a class for which source code is not available, or for any other constraints, it cannot be modified.
• The use of annotations by this model might be limiting for framework developers or service providers that try to abstract lower level details, such as the marshalling layer, away from the user.

If you're affected by any of these disadvantages, an alternative mechanism to provide externalizers is available via AdvancedExternalizer. More details can be found in this interface's javadoc. Please note that even though Externalizer is marked as Serializable, the need to marshall the externalizer is only really needed when developing user friendly externalizers (using SerializeWith). AdvancedExternalizer instances do not require the externalizer to be serializable since the externalizer itself is not marshalled. Even though it's not strictly necessary, to avoid breaking compatibility with old clients, Externalizer implements Serializable but this requirement is only needed for those user friendly externalizers. There's a chance that in future major releases Externalizer won't extend Serializable any more, hence we strongly recommend that any user-friendly externalizer users mark their externalizer implementations as either Serializable or Externalizable.

Since:

5.0

Method Summary

Modifier and Type	Method and Description
T	readObject(java.io.ObjectInput input) Read an instance from the stream.
void	writeObject(java.io.ObjectOutput output, T object) Write the object reference to the stream.

Method Detail

writeObject

void writeObject(java.io.ObjectOutput output,
                 T object)
          throws java.io.IOException

Write the object reference to the stream.

Parameters:

output - the object output to write to

object - the object reference to write

Throws:

java.io.IOException - if an I/O error occurs

readObject

T readObject(java.io.ObjectInput input)
      throws java.io.IOException,
             java.lang.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:

java.io.IOException - if an I/O error occurs

java.lang.ClassNotFoundException - if a class could not be found