net.sf.farrago.fennel.tuple
Class FennelTupleAccessor

java.lang.Object
  net.sf.farrago.fennel.tuple.FennelTupleAccessor

public final class FennelTupleAccessor
extends Object

FennelTupleAccessor defines how to efficiently marshall and unmarshall values in a stored tuple. The same logical tuple definition can have multiple storage formats. See the design docs for more details. This class is JDK 1.4 compatible.

Field Summary

private List	attrAccessors Precomputed accessors for attributes, in logical tuple order.
private int	bitFieldOffset Precomputed byte offset for bit array.
private ByteBuffer	currTupleBuf current ByteBuffer used for unmarshalling; set by setCurrentTupleBuf().
private int	firstVarEndIndirectOffset Precomputed offset for indirect offset of end of first variable-width attribute, or Integer.MAX_VALUE if there are no variable-width attributes.
private int	firstVarOffset Precomputed offset for fixed start of first variable-width attribute, or Integer.MAX_VALUE if there are no variable-width attributes.
private int	format actual format of this accessor.
private boolean	hasAlignedVar Whether any variable-width attributes with alignment requirements (currently restricted to 2-byte alignment for UNICODE strings) are present.
private int	lastVarEndIndirectOffset Precomputed offset for indirect offset of end of last variable-width attribute, or Integer.MAX_VALUE if there are no variable-length attributes.
private List	marshalOrder Permutation in which attributes should be marshalled; null when !hasAlignedVar, in which case attributes should be marshalled in logical order.
private int	maxStorage maximum marshalled size of this tuple
private int	minStorage minimum marshalled size of this tuple
private int	nBitFields Precomputed size of bit field array (in bits).
private boolean	setNativeOrder if true, set the ByteBuffer to native order after slicing, when doing unmarshals
(package private) static int	STOREDVALUEOFFSETSIZE
static int	TUPLE_ALIGN_JVM Specifies alignment matching the data model of this JVM; fallback is to assume 4-byte if relevant system property is undefined.
static int	TUPLE_ALIGN4 Specifies 4-byte alignment.
static int	TUPLE_ALIGN8 Specifies 8-byte alignment.
static int	TUPLE_FORMAT_ALL_NOT_NULL_AND_FIXED
static int	TUPLE_FORMAT_NETWORK
static int	TUPLE_FORMAT_STANDARD format of the constructed buffer.
private int	tupleAlignment tuple byte alignment.
private int	tupleAlignmentMask mask derived from tupleAlignment
private List	varWidthAccessors Array of 0-based indices of variable-width attributes.

Constructor Summary

FennelTupleAccessor()
default construction.

FennelTupleAccessor(boolean setNativeOrder)
Creates tuple accessor with the default byte alignmnent and a flag indicating whether byte ordering should be set to native order after slicing.

FennelTupleAccessor(int alignment)
Creates tuple accessor with specified byte alignmnent.

FennelTupleAccessor(int alignment, boolean setNativeOrder)
Creates tuple accessor with specified byte alignmnent and a flag indicating whether byte ordering should be set to native order after slicing.

Method Summary

int	alignRoundUp(int val) rounds up a value to the next multiple of tupleAlignment.
private void	clear() reset this accessor.
void	compute(FennelTupleDescriptor tuple) Precomputes access for a particular tuple format.
void	compute(FennelTupleDescriptor tuple, int format) Precomputes access for a particular tuple format.
FennelAttributeAccessor	getAccessor(int i) gets an accessor by its numeric position.
FennelAttributeAccessor	getAttributeAccessor(int iAttribute) Gets an accessor for an individual attribute.
int	getBitFieldOffset() gets the offset of the first byte of bit fields, or Integer.MAX_VALUE if no bit fields are present.
int	getBufferByteCount(ByteBuffer pBuf) Determines the number of bytes stored in a tuple buffer without actually preparing to unmarshal it.
int	getByteCount(FennelTupleData tuple) Determines the number of bytes required to store a tuple without actually marshalling it.
int	getCurrentByteCount() Determines the number of bytes stored in the current tuple buffer.
ByteBuffer	getCurrentTupleBuf() Accesses the ByteBuffer storing the current tuple image.
int	getMaxByteCount() returns the maximum possible tuple storage size in bytes
int	getMinByteCount() returns the minimum possible tuple storage size in bytes
private void	initBitFieldAccessors(FennelTupleDescriptor tuple, List list) Initialize all the bit accessors in a tuple.
private void	initFixedAccessors(FennelTupleDescriptor tuple, List list) Initialize all the fixed width accessors in a tuple.
private void	initVarWidthAccessors(FennelTupleDescriptor tuple, List list) Initialize all the variable width accessors in a tuple.
boolean	isBufferSufficient(FennelTupleData tuple, int bufSize) Determines whether a buffer is big enough to fit marshalled tuple data.
boolean	isFixedWidth() Indicates whether all tuples will have the same fixed size.
void	marshal(FennelTupleData tuple, ByteBuffer tupleBuf) Marshalls a tuple's values into a buffer.
static int	readUnsignedShort(ByteBuffer buffer, int position) gets an unsigned short value.
void	resetCurrentTupleBuf() Forgets the current tuple buffer.
void	setCurrentTupleBuf(ByteBuffer currTupleBuf) Sets the buffer storing the current tuple image.
int	size() gets the number of attributes contained in this accessor.
void	unmarshal(FennelTupleData tuple) Unmarshals the current tuple buffer, setting a tuple's values to reference the contents.
void	unmarshal(FennelTupleData tuple, int iFirstDatum) Unmarshals the current tuple buffer, setting a tuple's values to reference the contents.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TUPLE_FORMAT_STANDARD

public static final int TUPLE_FORMAT_STANDARD

format of the constructed buffer. FIXME: not supported; is this necessary?

See Also:

Constant Field Values

TUPLE_FORMAT_ALL_NOT_NULL_AND_FIXED

public static final int TUPLE_FORMAT_ALL_NOT_NULL_AND_FIXED

See Also:

Constant Field Values

TUPLE_FORMAT_NETWORK

public static final int TUPLE_FORMAT_NETWORK

See Also:

Constant Field Values

STOREDVALUEOFFSETSIZE

static final int STOREDVALUEOFFSETSIZE

See Also:

Constant Field Values

TUPLE_ALIGN4

public static final int TUPLE_ALIGN4

Specifies 4-byte alignment.

See Also:

Constant Field Values

TUPLE_ALIGN8

public static final int TUPLE_ALIGN8

Specifies 8-byte alignment.

See Also:

Constant Field Values

TUPLE_ALIGN_JVM

public static final int TUPLE_ALIGN_JVM

Specifies alignment matching the data model of this JVM; fallback is to assume 4-byte if relevant system property is undefined. TODO jvs 26-May-2007: we really ought to be calling Fennel to get this instead, since e.g. on Sun CPU architectures, 64-bit alignment is required even for a 32-bit JVM. Plus this System property is undocumented, although it's also available on JRockit.

attrAccessors

private final List attrAccessors

Precomputed accessors for attributes, in logical tuple order.

varWidthAccessors

private final List varWidthAccessors

Array of 0-based indices of variable-width attributes.

maxStorage

private int maxStorage

maximum marshalled size of this tuple

minStorage

private int minStorage

minimum marshalled size of this tuple

nBitFields

private int nBitFields

Precomputed size of bit field array (in bits).

bitFieldOffset

private int bitFieldOffset

Precomputed byte offset for bit array.

firstVarEndIndirectOffset

private int firstVarEndIndirectOffset

Precomputed offset for indirect offset of end of first variable-width attribute, or Integer.MAX_VALUE if there are no variable-width attributes.

lastVarEndIndirectOffset

private int lastVarEndIndirectOffset

Precomputed offset for indirect offset of end of last variable-width attribute, or Integer.MAX_VALUE if there are no variable-length attributes.

firstVarOffset

private int firstVarOffset

Precomputed offset for fixed start of first variable-width attribute, or Integer.MAX_VALUE if there are no variable-width attributes.

currTupleBuf

private ByteBuffer currTupleBuf

current ByteBuffer used for unmarshalling; set by setCurrentTupleBuf().

format

private int format

actual format of this accessor.

tupleAlignment

private int tupleAlignment

tuple byte alignment.

tupleAlignmentMask

private int tupleAlignmentMask

mask derived from tupleAlignment

setNativeOrder

private final boolean setNativeOrder

if true, set the ByteBuffer to native order after slicing, when doing unmarshals

marshalOrder

private List marshalOrder

Permutation in which attributes should be marshalled; null when !hasAlignedVar, in which case attributes should be marshalled in logical order.

hasAlignedVar

private boolean hasAlignedVar

Whether any variable-width attributes with alignment requirements (currently restricted to 2-byte alignment for UNICODE strings) are present.

Constructor Detail

FennelTupleAccessor

public FennelTupleAccessor()

default construction.

FennelTupleAccessor

public FennelTupleAccessor(int alignment)

Creates tuple accessor with specified byte alignmnent.

Parameters:

alignment - must be multiple of 4

FennelTupleAccessor

public FennelTupleAccessor(boolean setNativeOrder)

Creates tuple accessor with the default byte alignmnent and a flag indicating whether byte ordering should be set to native order after slicing.

Parameters:

setNativeOrder - if true, set byte ordering to native order after slicing

FennelTupleAccessor

public FennelTupleAccessor(int alignment,
                           boolean setNativeOrder)

Creates tuple accessor with specified byte alignmnent and a flag indicating whether byte ordering should be set to native order after slicing.

Parameters:

alignment - must be multiple of 4

setNativeOrder - if true, set byte ordering to native order after slicing

Method Detail

alignRoundUp

public int alignRoundUp(int val)

rounds up a value to the next multiple of tupleAlignment.

size

public int size()

gets the number of attributes contained in this accessor.

readUnsignedShort

public static int readUnsignedShort(ByteBuffer buffer,
                                    int position)

gets an unsigned short value.

initFixedAccessors

private void initFixedAccessors(FennelTupleDescriptor tuple,
                                List list)

Initialize all the fixed width accessors in a tuple.

initVarWidthAccessors

private void initVarWidthAccessors(FennelTupleDescriptor tuple,
                                   List list)

Initialize all the variable width accessors in a tuple.

initBitFieldAccessors

private void initBitFieldAccessors(FennelTupleDescriptor tuple,
                                   List list)

Initialize all the bit accessors in a tuple.

clear

private void clear()

reset this accessor.

getAccessor

public FennelAttributeAccessor getAccessor(int i)

gets an accessor by its numeric position.

compute

public void compute(FennelTupleDescriptor tuple,
                    int format)

Precomputes access for a particular tuple format. Must be called before any other method.

Parameters:

tuple - the tuple to be accessed

format - how to store tuple

compute

public void compute(FennelTupleDescriptor tuple)

Precomputes access for a particular tuple format. Must be called before any other method. Assumes the default format parameter.

Parameters:

tuple - the tuple to be accessed

getMaxByteCount

public int getMaxByteCount()

returns the maximum possible tuple storage size in bytes

getMinByteCount

public int getMinByteCount()

returns the minimum possible tuple storage size in bytes

isFixedWidth

public boolean isFixedWidth()

Indicates whether all tuples will have the same fixed size.

NOTE: this is copied from fennel, but what about isNullable fields?

getBitFieldOffset

public int getBitFieldOffset()

gets the offset of the first byte of bit fields, or Integer.MAX_VALUE if no bit fields are present.

getCurrentTupleBuf

public ByteBuffer getCurrentTupleBuf()

Accesses the ByteBuffer storing the current tuple image.

Returns:

address of tuple image, or NULL if no current tuple

setCurrentTupleBuf

public void setCurrentTupleBuf(ByteBuffer currTupleBuf)

Sets the buffer storing the current tuple image. Must be called before getCurrentByteCount and unmarshal.

Parameters:

currTupleBuf - address of tuple image

resetCurrentTupleBuf

public void resetCurrentTupleBuf()

Forgets the current tuple buffer.

getCurrentByteCount

public int getCurrentByteCount()

Determines the number of bytes stored in the current tuple buffer. This will always be greater than or equal to getMinByteCount() and less than getMaxByteCount().

Returns:

byte count

getBufferByteCount

public int getBufferByteCount(ByteBuffer pBuf)

Determines the number of bytes stored in a tuple buffer without actually preparing to unmarshal it.

Parameters:

pBuf - tuple buffer

Returns:

byte count

getByteCount

public int getByteCount(FennelTupleData tuple)

Determines the number of bytes required to store a tuple without actually marshalling it.

Parameters:

tuple - the tuple data

Returns:

byte count

isBufferSufficient

public boolean isBufferSufficient(FennelTupleData tuple,
                                  int bufSize)

Determines whether a buffer is big enough to fit marshalled tuple data.

Parameters:

tuple - the tuple to be marshalled

bufSize - the size of the candidate buffer

Returns:

true if bufSize is big enough

unmarshal

public void unmarshal(FennelTupleData tuple,
                      int iFirstDatum)

Unmarshals the current tuple buffer, setting a tuple's values to reference the contents.

Parameters:

tuple - the tuple which will be modified to reference the unmarshalled values

iFirstDatum - 0-based index of FennelTupleDatum at which to start writing to tuple (defaults to first FennelTupleDatum); note that unmarshalling always starts with the first attribute

unmarshal

public void unmarshal(FennelTupleData tuple)

Unmarshals the current tuple buffer, setting a tuple's values to reference the contents. Assumes starting at the first FennelTupleDatum (index zero).

Parameters:

tuple - the tuple which will be modified to reference the unmarshalled values, starting with the first datum

getAttributeAccessor

public FennelAttributeAccessor getAttributeAccessor(int iAttribute)

Gets an accessor for an individual attribute. This can be used to unmarshall values individually.

Parameters:

iAttribute - 0-based index of the attribute within the tuple

marshal

public void marshal(FennelTupleData tuple,
                    ByteBuffer tupleBuf)

Marshalls a tuple's values into a buffer.

Parameters:

tuple - the tuple to be marshalled

tupleBuf - the buffer into which to marshal (note that this accessor's own current tuple buffer remains unchanged)