com.ibm.websphere.objectgrid.plugins.io
Interface ValueDataSerializer.Versionable

All Superinterfaces:

DataSerializer, DataSerializer.DataAttributeInflatable, ValueDataSerializer

Enclosing interface:

ValueDataSerializer

public static interface ValueDataSerializer.Versionable
extends ValueDataSerializer

ValueDataSerializers can implement the optional Versionable interface to allow high performance versioning when using in conjunction with the optimistic locking strategy.

Optimistic versioning is used to identify the version of a data object when using the LockStrategy.OPTIMISTIC locking strategy. The Versioning interface allows the eXtreme Scale runtime to update the version in the data object and read and compare the version whenever updates occur in one of the cache tiers: the transactional, client or server cache tiers.

The Versionable interface can also allow the customer to enable optimistic locking without versioning by returning the ValueDataSerializer.Versionable.VersionType.NO_VERSION value from the getVersion(DataObjectContext, XsDataInputStream, XsDataOutputStream) method.

Since:

7.1.1

Nested Class Summary

static class

ValueDataSerializer.Versionable.VersionType The VersionType enumeration indicates the type of version information that the Versionable data serializer exports from the getVersion(DataObjectContext, XsDataInputStream, XsDataOutputStream) method.

Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.plugins.io.ValueDataSerializer

ValueDataSerializer.Mergeable, ValueDataSerializer.Versionable

Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.plugins.io.DataSerializer

DataSerializer.DataAttributeInflatable, DataSerializer.Identifiable, DataSerializer.SpecialValue, DataSerializer.UserReadable

Method Summary

ValueDataSerializer.Versionable.VersionType	getVersion(DataObjectContext ctx, XsDataInputStream existingDataObjectInput, XsDataOutputStream versionDataOutput) Retrieve the serialized form of the attribute that identifies the version.
Object	inflateDataObjectVersion(DataObjectContext ctx, XsDataInputStream versionDataInput) From the specified Version object, inflate the version attribute
ValueDataSerializer.Versionable.VersionType	updateVersion(DataObjectContext ctx, XsDataInputStream existingDataObjectInput, XsDataOutputStream updatedDataObjectOutput) Invoked when the version of the cache entry needs to be updated to the next version.
boolean	versionEquals(DataObjectContext ctx, XsDataInputStream versionDataInput1, XsDataInputStream versionDataInput2) Answers true if the two serialized data objects equate to the same version.

Methods inherited from interface com.ibm.websphere.objectgrid.plugins.io.ValueDataSerializer

getValueDataDescriptor

Methods inherited from interface com.ibm.websphere.objectgrid.plugins.io.DataSerializer.DataAttributeInflatable

getAttributeContexts, inflateDataObjectAttributes

Methods inherited from interface com.ibm.websphere.objectgrid.plugins.io.DataSerializer

inflateDataObject, serializeDataObject

Method Detail

getVersion

ValueDataSerializer.Versionable.VersionType getVersion(DataObjectContext ctx,
                                                       XsDataInputStream existingDataObjectInput,
                                                       XsDataOutputStream versionDataOutput)
                                                       throws IOException

Retrieve the serialized form of the attribute that identifies the version.

This method is called whenever a data object is associated with a transaction so that at commit time, the ObjectGrid runtime can do qualified updates using this value to detect if the value changed during the optimistic transaction. The Loader also gets this value from the LogElement.

This method is called prior to the other ValueDataSerializer.Versionable methods. If this method returns null or ValueDataSerializer.Versionable.VersionType.NO_VERSION, then the cache entry will abstain from versioning.

Do not store or use the data streams beyond the confines of this method call. The data streams are owned by the WebSphere eXtreme Scale framework and my be closed, pooled or reused as required.

Parameters:

ctx - the context of the method call.

existingDataObjectInput - the data input stream to read the object, produced from DataSerializer.serializeDataObject(DataObjectContext, Object, XsDataOutputStream). Must not be null.

versionDataOutput - the data output stream to receive the serialized form of the attributes that represent the version. Ignored if the return value is not ValueDataSerializer.Versionable.VersionType.USER_VERSION Must not be null.

Returns:

One of the VersionType attributes representing the form of the object version. Data in the versionOutput stream is ignored if the value is other than ValueDataSerializer.Versionable.VersionType.USER_VERSION

Throws:

IOException - thrown if there is a problem reading or writing the data.

See Also:

Loader, LogElement.getVersionedValue()

updateVersion

ValueDataSerializer.Versionable.VersionType updateVersion(DataObjectContext ctx,
                                                          XsDataInputStream existingDataObjectInput,
                                                          XsDataOutputStream updatedDataObjectOutput)
                                                          throws IOException

Invoked when the version of the cache entry needs to be updated to the next version. If the default version is being used (the entire object), the updateVersion() method should return ValueDataSerializer.Versionable.VersionType.DEFAULT_VERSION or ValueDataSerializer.Versionable.VersionType.NO_VERSION. If the updateVersion() method writes the new object data (with the updated version attribute) to the output stream, the method should return ValueDataSerializer.Versionable.VersionType.USER_VERSION;

Do not store or use the data streams beyond the confines of this method call. The data streams are owned by the WebSphere eXtreme Scale framework and my be closed, pooled or reused as required.

Parameters:

ctx - the context of the method call.

existingDataObjectInput - the data input stream to read the existing object, produced from DataSerializer.serializeDataObject(DataObjectContext, Object, XsDataOutputStream). Must not be null.

updatedDataObjectOutput - the data output stream to store the updated object, compatible with that produced from DataSerializer.serializeDataObject(DataObjectContext, Object, XsDataOutputStream) for an object of the subsequent version from the input object. Ignored if the return value is other than ValueDataSerializer.Versionable.VersionType.USER_VERSION. Must not be null.

Returns:

type - ValueDataSerializer.Versionable.VersionType.USER_VERSION if the object data was updated

Throws:

IOException - thrown if there is a problem reading or writing the data.

versionEquals

boolean versionEquals(DataObjectContext ctx,
                      XsDataInputStream versionDataInput1,
                      XsDataInputStream versionDataInput2)
                      throws IOException

Answers true if the two serialized data objects equate to the same version.

Do not store or use the data streams beyond the confines of this method call. The data streams are owned by the WebSphere eXtreme Scale framework and my be closed, pooled or reused as required.

Parameters:

ctx - the context of the method call.

versionDataInput1 - the data input stream to read the serialized form of a data object produced from getVersion(DataObjectContext, XsDataInputStream, XsDataOutputStream) Must not be null.

versionDataInput2 - the data input stream to read the serialized form of a data object produced from getVersion(DataObjectContext, XsDataInputStream, XsDataOutputStream). May be the serialized form of the entire object if ValueDataSerializer.Versionable.VersionType.USER_VERSION was not used. Must not be null.

Returns:

true if the version is equivalent.

Throws:

IOException - thrown if there is a problem reading the data.

inflateDataObjectVersion

Object inflateDataObjectVersion(DataObjectContext ctx,
                                XsDataInputStream versionDataInput)
                                throws IOException

From the specified Version object, inflate the version attribute

Do not store or use the data stream beyond the confines of this method call. The data stream is owned by the WebSphere eXtreme Scale framework and my be closed, pooled or reused as required.

Parameters:

ctx - - the context of the method call

versionDataInput - the data input stream to read the serialized form of a data object produced from getVersion(DataObjectContext, XsDataInputStream, XsDataOutputStream) Must not be null.

Returns:

The POJO version object, suitable for use with qualified updates by the Loader or ObjectGrid framework.

Throws:

IOException - thrown if there is a problem reading the data.