org.infinispan.commons.marshall

Interface Marshaller

All Known Subinterfaces:

StreamingMarshaller

All Known Implementing Classes:

AbstractDelegatingMarshaller, AbstractJBossMarshaller, AbstractMarshaller, BaseProtoStreamMarshaller, CompatibilityProtoStreamMarshaller, GenericJBossMarshaller, IdentityMarshaller, JavaSerializationMarshaller, StringMarshaller, UTF8StringMarshaller

@ThreadSafe
public interface Marshaller

A marshaller is a class that is able to marshall and unmarshall objects efficiently.

This interface is used to marshall ReplicableCommands, their parameters and their response values, as well as any other arbitraty Object <--> byte[] conversions, such as those used in client/server communications.

A single instance of any implementation is shared by multiple threads, so implementations need to be threadsafe, and preferably immutable.

Method Summary

Modifier and Type	Method and Description
BufferSizePredictor	getBufferSizePredictor(java.lang.Object o) Returns a marshalled payload size predictor for a particular type.
boolean	isMarshallable(java.lang.Object o) A method that checks whether the given object is marshallable as per the rules of this marshaller.
MediaType	mediaType()
java.lang.Object	objectFromByteBuffer(byte[] buf) Unmarshalls an object from a byte array.
java.lang.Object	objectFromByteBuffer(byte[] buf, int offset, int length) Unmarshalls an object from a specific portion of a byte array.
ByteBuffer	objectToBuffer(java.lang.Object o) A method that returns an instance of ByteBuffer, which allows direct access to the byte array with minimal array copying
byte[]	objectToByteBuffer(java.lang.Object obj) Marshalls an object to a byte array.
byte[]	objectToByteBuffer(java.lang.Object obj, int estimatedSize) Marshalls an object to a byte array.

Method Detail

objectToByteBuffer

byte[] objectToByteBuffer(java.lang.Object obj,
                          int estimatedSize)
                   throws java.io.IOException,
                          java.lang.InterruptedException

Marshalls an object to a byte array. The estimatedSize parameter is a hint that can be passed in to allow for efficient sizing of the byte array before attempting to marshall the object. The more accurate this estimate is, the less likely byte[]s will need to be resized to hold the byte stream generated by marshalling the object.

Parameters:

obj - object to convert to a byte array. Must not be null.

estimatedSize - an estimate of how large the resulting byte array may be

Returns:

a byte array with the marshalled form of the object

Throws:

java.io.IOException - if marshalling cannot complete due to some I/O error

java.lang.InterruptedException - if the marshalling was interrupted. Clients should take this as a sign that the marshaller is no longer available, maybe due to shutdown, and so no more unmarshalling should be attempted.

objectToByteBuffer

byte[] objectToByteBuffer(java.lang.Object obj)
                   throws java.io.IOException,
                          java.lang.InterruptedException

Marshalls an object to a byte array.

Parameters:

obj - object to convert to a byte array. Must not be null.

Returns:

a byte array

Throws:

java.io.IOException - if marshalling cannot complete due to some I/O error

java.lang.InterruptedException - if the marshalling process was interrupted. Clients should take this as a sign that the marshaller is no longer available, maybe due to shutdown, and so no more marshalling should be attempted.

objectFromByteBuffer

java.lang.Object objectFromByteBuffer(byte[] buf)
                               throws java.io.IOException,
                                      java.lang.ClassNotFoundException

Unmarshalls an object from a byte array.

Parameters:

buf - byte array containing the binary representation of an object. Must not be null.

Returns:

an object

Throws:

java.io.IOException - if unmarshalling cannot complete due to some I/O error

java.lang.ClassNotFoundException - if the class of the object trying to unmarshall is unknown

objectFromByteBuffer

java.lang.Object objectFromByteBuffer(byte[] buf,
                                      int offset,
                                      int length)
                               throws java.io.IOException,
                                      java.lang.ClassNotFoundException

Unmarshalls an object from a specific portion of a byte array.

Parameters:

buf - byte array containing the binary representation of an object. Must not be null.

offset - point in buffer to start reading

length - number of bytes to consider

Returns:

an object

Throws:

java.io.IOException - if unmarshalling cannot complete due to some I/O error

java.lang.ClassNotFoundException - if the class of the object trying to unmarshall is unknown

objectToBuffer

ByteBuffer objectToBuffer(java.lang.Object o)
                   throws java.io.IOException,
                          java.lang.InterruptedException

A method that returns an instance of ByteBuffer, which allows direct access to the byte array with minimal array copying

Parameters:

o - object to marshall

Throws:

java.io.IOException - if marshalling cannot complete due to some I/O error

java.lang.InterruptedException - if the marshalling process was interrupted. Clients should take this as a sign that the marshaller is no longer available, maybe due to shutdown, and so no more marshalling should be attempted.

isMarshallable

boolean isMarshallable(java.lang.Object o)
                throws java.lang.Exception

A method that checks whether the given object is marshallable as per the rules of this marshaller.

Parameters:

o - object to verify whether it's marshallable or not

Returns:

true if the object is marshallable, otherwise false

Throws:

java.lang.Exception - if while checking whether the object was serializable or not, an exception arose

getBufferSizePredictor

BufferSizePredictor getBufferSizePredictor(java.lang.Object o)

Returns a marshalled payload size predictor for a particular type. Accurate prediction of a type's serialized payload size helps avoid unnecessary copying and speeds up application performance.

Parameters:

o - Object for which serialized predictor will be returned

Returns:

an instance of BufferSizePredictor

Throws:

java.lang.NullPointerException - if o is null

mediaType

MediaType mediaType()

Returns:

the MediaType associated with the content produced by the marshaller