com.neeve.sto
Class StoField

java.lang.Object
  com.neeve.util.UtlListElement
      com.neeve.sto.StoField

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

StoBooleanField, StoBufferField, StoByteField, StoDateField, StoDoubleField, StoFixedLengthStringField, StoFloatField, StoIntField, StoLongField, StoShortField, StoVariableLengthField

public abstract class StoField
extends com.neeve.util.UtlListElement
implements Cloneable

Base class implementation of an STO field.

Threading:

STO fields are not safe for concurrent access by multiple threads.

Nested Class Summary

static class

StoField.Type Enumerates the supported STO field types.

Field Summary

Fields inherited from class com.neeve.util.UtlListElement

count, head, next, prev

Method Summary

StoField	changeBackingBuffer(ByteBuffer buffer, int bufferOffset) Change an STO field's backing buffer.
StoField	clearBackingBuffer() Clear an STO field's backing buffer.
Object	clone() Clone an STO field.
boolean	contentsEquals(StoField other) Compare a field contents against another field contents.
static StoField	create(ByteBuffer buffer, int bufferOffset) Create an STO field from its serialized form.
ByteBuffer	getBackingBuffer() Get an STO field's backing buffer.
com.neeve.sto.StoFieldHeader	getHeader() Get an STO field's header
int	getLength() Get an STO field's length in serialized form.
String	getName() Get an STO field's name.
static int	getSerializedLength(ByteBuffer buffer, int bufferOffset) Get the length of a serialized STO field.
static int	getSerializedLength(StoField.Type type, ByteBuffer buffer, int bufferOffset) Get the length of a serialized STO field.
StoField.Type	getType() Get an STO field's type.
short	getVersion() Get an STO field's version.
boolean	isNamed() Check if a field is named
abstract boolean	isVariableLength() Invoked to determine whether a field is fixed or variable length.
abstract void	reset() Reset the contents of a field.
StoField	setBackingBuffer(ByteBuffer buffer, int bufferOffset) Set an STO field's backing buffer.
int	shiftForHeader(int offset) Shift an offset adjusting for the STO field header.
StoField	sync(ByteBuffer buffer, int bufferOffset) Sync (serialize) an STO field to a buffer.
String	toString() Get an STO field's string representation.

Methods inherited from class com.neeve.util.UtlListElement

count, insertAfter, insertBefore, isLinked, next, previous, unlink, wipe

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

isVariableLength

public abstract boolean isVariableLength()

Invoked to determine whether a field is fixed or variable length.

This method, implemented by the concrete field implementation, should return whether the field is a fixed or variable length field.

getSerializedLength

public static int getSerializedLength(StoField.Type type,
                                      ByteBuffer buffer,
                                      int bufferOffset)

Get the length of a serialized STO field.

Parameters:

type - The field type.

buffer - The buffer in which the field is serialized.

bufferOffset - The offset into the buffer where the field is serialized.

This method returns the length of the serialized form of a field. It accepts a buffer and the offset into the buffer where the field is serialized. The method parses the serialized form of the field in the buffer and returns the number of bytes occupied by the serialized field in the buffer.

getSerializedLength

public static int getSerializedLength(ByteBuffer buffer,
                                      int bufferOffset)

Get the length of a serialized STO field.

Parameters:

buffer - The buffer in which the field is serialized.

bufferOffset - The offset into the buffer where the field is serialized.

This method gets the field type from the supplied serialized buffer and then invokes getSerializedLength(StoField.Type, ByteBuffer, int)

create

public static StoField create(ByteBuffer buffer,
                              int bufferOffset)

Create an STO field from its serialized form.

Parameters:

buffer - The buffer in which the field is serialized.

bufferOffset - The offset into the buffer where the field is serialized.

This method accepts a buffer that contains a serialized STO field. The method instantiates and initializes a field object from its serialized form.

setBackingBuffer

public final StoField setBackingBuffer(ByteBuffer buffer,
                                       int bufferOffset)

Set an STO field's backing buffer.

Parameters:

buffer - The buffer to use as backing storage.

bufferOffset - The offset into the buffer to store the field's contents.

Returns:

Returns this object for invocation chaining.

This method sets the buffer to use as backing storage for an STO field. The method syncs the contents of the field to the buffer starting at the specified offset and holds onto the buffer as the backing storage for the field i.e. all subsequent changes to the field contents are directly updated in the backing buffer.

This method leaves the buffer markers unchanged.

clearBackingBuffer

public final StoField clearBackingBuffer()

Clear an STO field's backing buffer.

This method leaves the buffer markers unchanged.

changeBackingBuffer

public final StoField changeBackingBuffer(ByteBuffer buffer,
                                          int bufferOffset)
                                   throws EStoFieldCorruptException

Change an STO field's backing buffer.

Parameters:

buffer - The buffer to set as the backing buffer.

bufferOffset - The offset into the buffer at which to start the buffer's backing storage.

Returns:

Returns this object for invocation chaining.

This method replaces a field's backing buffer. This method is the converse of setBackingBuffer(ByteBuffer, int) in that it treats the contents of the buffer as primary (i.e. overwriting the in-memory field values) as opposed to the other method that treats the in-memory field values as primary i.e. overrwriting the the buffer contents.

This method leaves the buffer markers unchanged.

Throws:

EStoFieldCorruptException

shiftForHeader

public final int shiftForHeader(int offset)

Shift an offset adjusting for the STO field header.

Parameters:

offset - The offset to shift

sync

public final StoField sync(ByteBuffer buffer,
                           int bufferOffset)

Sync (serialize) an STO field to a buffer.

Parameters:

buffer - The buffer to serialize the field to.

bufferOffset - The offset into the buffer to serialize the field to.

This method leaves the buffer markers unchanged.

getHeader

public final com.neeve.sto.StoFieldHeader getHeader()

Get an STO field's header

isNamed

public final boolean isNamed()

Check if a field is named

getName

public final String getName()

Get an STO field's name.

getVersion

public final short getVersion()

Get an STO field's version.

getType

public final StoField.Type getType()

Get an STO field's type.

getLength

public final int getLength()

Get an STO field's length in serialized form.

getBackingBuffer

public final ByteBuffer getBackingBuffer()

Get an STO field's backing buffer.

contentsEquals

public final boolean contentsEquals(StoField other)

Compare a field contents against another field contents.

Parameters:

other - The field to compare against

This method returns true if and only if a field has contents that are identical to the field being compared against.

clone

public final Object clone()

Clone an STO field.

This method clones the contents of a STO field. The cloned object has the same type and value as the original field. However, the cloned field is not backed by a buffer.

Overrides:

clone in class com.neeve.util.UtlListElement

reset

public abstract void reset()

Reset the contents of a field.

This method resets the contents of a field. Upon return from this method, the field contents are the same as a freshly created field of the same type. If a buffer is backing a field, this method also resets the field contents in the buffer.

This method is intended for use with object pools through which field objects can be recycled rather than created fresh every time.

toString

public final String toString()

Get an STO field's string representation.

Overrides:

toString in class Object