com.bigdata.btree
Interface ITupleSerializer<K,V>

All Superinterfaces:

IKeyBuilderFactory, Serializable

All Known Implementing Classes:

CommitRecordIndex.CommitRecordIndexTupleSerializer, CommitTimeIndex.TupleSerializer, CounterSetBTree.CounterSetBTreeTupleSerializer, DefaultTupleSerializer, EventReceiver.EventBTree.EventBTreeTupleSerializer, Id2TermTupleSerializer, JournalIndex.TupleSerializer, JustificationTupleSerializer, MagicTupleSerializer, MetadataIndex.PartitionLocatorTupleSerializer, Name2Addr.Name2AddrTupleSerializer, NOPTupleSerializer, SPOTupleSerializer, Term2IdTupleSerializer, TPSTupleSerializer

public interface ITupleSerializer<K,V>
extends IKeyBuilderFactory, Serializable

An interface that provides for the (de)-serialization of the value of a tuple stored in an index and, when possible, the key under which that value is stored.

The encoded key is always a variable length unsigned byte[]s. The purpose of the encoded key is to determine the total order over the tuple in the B+Tree. While some key encodings are reversible without less (e.g., int, long, float or double), many key encodings are simply not decodable (including Unicode keys). Applications that require the ability to decode complex keys may need to resort to storing the unencoded key state redundantly in the tuple value. FIXME extSer integration. There are two broad setups. (1) Local: when running without an IMetadataService and hence on a single AbstractJournal, the serializer state should be stored in a record whose address is available from the CommitRecordIndex of the Journal. (2) Distributed: when running a distributed federation the serializer state should be stored globally so that the serialized values can be consistently interpreted as they are moved from BTree to IndexSegment and from IndexSegment to IndexSegment.

I am inclined to store the serializer state for the distributed federation on a per-scale-out index basis. This means that you must de-serialize the keys and values in order to copy tuples from one scale-out index to another. However, when copying tuples from one federation to another de-serialization and re-serialization will be required regardless since the serializer state will not be shared and, in fact, could be different for the two indices (this is also true within a single federation or even within a scale-up instance). (There should probably be a utility class to do index copies that handles these various cases).

The critical point is being able to recover the reference to the (potentially remote) extSer object from within both the AbstractBTree and the various ITupleIterator implementations, including the AbstractChunkedTupleIterator. Further, the recovered object must cache the extSer state, must have a reasonable life cycle so that it is efficient, and must be linked into the commit protocol such that assigned class identifiers are always made persistent if a commit could have included data written using those class identifiers.

Version:

$Id: ITupleSerializer.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Method Summary

V	deserialize(ITuple tuple) De-serialize an object from an ITuple.
K	deserializeKey(ITuple tuple) De-serialize the application key from an ITuple (optional operation).
IKeyBuilder	getKeyBuilder() Factory for thread-safe IKeyBuilder objects for use by serializeKey(Object) and possibly others.
IRabaCoder	getLeafKeysCoder() The object used to code (compress) an ordered array of keys such as found in a B+Tree ILeafData record or in a ResultSet.
IRabaCoder	getLeafValuesCoder() The object used to code (compress) an unordered array of values ordered array of keys such as found in a B+Tree ILeafData record or in a ResultSet.
byte[]	serializeKey(Object obj) Serialize a facet of an object's state that places the object into the total sort order for the index.
byte[]	serializeVal(V obj) Serialize the persistent state of the object (the value stored in the index under the key for that object).

Method Detail

getKeyBuilder

IKeyBuilder getKeyBuilder()

Factory for thread-safe IKeyBuilder objects for use by serializeKey(Object) and possibly others.

Note: A mutable B+Tree is always single-threaded. However, read-only B+Trees allow concurrent readers. Therefore, thread-safety requirement is safe for either a single writers -or- for concurrent readers.

Note: If you change this value in a manner that is not backward compatible once entries have been written on the index then you may be unable to any read data already written.

Note: This IKeyBuilder SHOULD be used to form all keys for this index. This is critical for indices that have Unicode data in their application keys as the formation of Unicode sort keys from Unicode data depends on the IKeyBuilderFactory. If you use a locally configured IKeyBuilder then your Unicode keys will be encoded based on the Locale configured for the JVM NOT the factory specified for this index.

Specified by:

getKeyBuilder in interface IKeyBuilderFactory

serializeKey

byte[] serializeKey(Object obj)

Serialize a facet of an object's state that places the object into the total sort order for the index. This method is automatically applied by IAutoboxBTree.insert(Object, Object) and friends to convert the key object into an unsigned variable length byte[].

Note: This handles the conversion between an object and the unsigned variable length byte[] representation of that object which determines its place within the total index order. Since this transform imposes the total order of the index, different techniques are applied here than are applied to the serialization of the index values.

Parameters:

obj - A object (MAY NOT be null).

Returns:

An unsigned byte[] which places the object into the total sort order for the index and never null ( null keys are not allowed into an index).

Throws:

IllegalArgumentException - if obj is null.

serializeVal

byte[] serializeVal(V obj)

Serialize the persistent state of the object (the value stored in the index under the key for that object). This method is automatically applied by IAutoboxBTree.insert(Object, Object) and friends to convert the value object into an byte[].

Parameters:

obj - An object (MAY NOT be null).

Returns:

A byte[] containing the serialized state of the object -or- null if no value will be stored under the serialized key.

Throws:

IllegalArgumentException - if obj is null.

deserialize

V deserialize(ITuple tuple)

De-serialize an object from an ITuple. This method is automatically applied by methods on the IAutoboxBTree interface that return the object stored under a key and by ITuple.getObject().

Parameters:

tuple - The tuple.

Returns:

The de-serialized object.

Throws:

IllegalArgumentException - if tuple is null.

deserializeKey

K deserializeKey(ITuple tuple)

De-serialize the application key from an ITuple (optional operation).

Note: There is no general means to recover the application key from the B+Tree. However, there are two approaches, either of which may work for your data.

1. If the application key can be recovered from the application value then this method can delegate to deserialize(ITuple) and return the appropriate field or synthetic property value.
2. Some kinds of application keys can be directly de-serialized using KeyBuilder. For example, int, long, float, double, etc. However this is NOT possible for Unicode Strings.

Note: The B+Tree does NOT rely on this method. It is used to support the materialization of the key required to allow BigdataMap and BigdataSet to fulfill their respective APIs.

Throws:

UnsupportedOperationException - if this operation is not implemented.

getLeafKeysCoder

IRabaCoder getLeafKeysCoder()

The object used to code (compress) an ordered array of keys such as found in a B+Tree ILeafData record or in a ResultSet.

Note: If you change this value in a manner that is not backward compatible once entries have been written on the index then you may be unable to any read data already written.

getLeafValuesCoder

IRabaCoder getLeafValuesCoder()

The object used to code (compress) an unordered array of values ordered array of keys such as found in a B+Tree ILeafData record or in a ResultSet.

Note: If you change this value in a manner that is not backward compatible once entries have been written on the index then you may be unable to any read data already written.