com.sun.sgs.impl.service.data.store
Class DataStoreHeader

java.lang.Object
  com.sun.sgs.impl.service.data.store.DataStoreHeader

final class DataStoreHeader
extends Object

Encapsulates the layout of meta data stored at the start of the info database, and in the classes database. This class cannot be instantiated. In the info database, the value for key 0 stores a magic number common to all DataStoreImpl databases. Key 1 stores the major version number, which must match the value in the current version of the implementation. Key 2 stores the minor version number, which can vary between the database and the implementation. Key 3 stores the ID of the next free ID number to use for allocating new objects. Key 4 stores the ID of the next free transaction ID number for the network version to use in allocating transactions. Key 5 stores the ID of the lowest allocation block placeholder, or -1 if there are no placeholders. This field is used during initialization to remove any existing placeholders which were created for allocation blocks that are no longer in use. Placeholders always appear at the end of each allocation block, whose size is fixed (as of version 4.0) at 1024 bytes. Key 6 store the ID of the next free node ID to use for giving unique identifiers to nodes. In the classes database, keys whose initial byte is 1 map the SHA-1 hash of the serialized form of a class descriptor (a ObjectStreamClass) to the class ID, which is 4 byte integer. Keys whose initial byte is 2 map a class ID to the bytes making up the serialized form of the associated class descriptor. Since these entries come at the end, we can find the next class ID by using a cursor to find the last entry. In the names database, keys are the UTF8 encoding of binding names, and values are the object IDs of the associated objects. In the oids database, keys are object IDs, and values are the bytes representing the associated objects. The serialized forms used for the object values are compressed as follows: - If the first byte is 1, then the value was created by serialization protocol version 2, and the 4 bytes at the start of that format have been elided. - If the first byte is 2, then the subsequent bytes represent the uncompressed object data. - Class descriptors in the serialized form have been replaced by an integer which refers to a class ID stored in the classes database. The class IDs themselves have been compressed using the Int30 class Object values also have two additional, distinguished initial byte values to support placeholders: - If the first byte is 3, then the entry represents a placeholder, which means that the entry appears within the database but should not be considered to represent an object. Placeholders are used to create a barrier object in the database to improve concurrency for new object allocations when using BDB Java Edition. - If the first byte is 4, then the actual data value is represented by the remaining bytes. This "quoting" value can be used to represent data that starts with the 3 that marks placeholders, or the 4 used for quoting. Since serialized data will always start with 1 or 2, though, this value should not be used in practice. Version history: Version 1.0: Initial version, 11/3/2006 Version 2.0: Add NEXT_TXN_ID, 2/15/2007 Version 3.0: Add classes DB, compress object values, 5/18/2007 Version 4.0: Add placeholders, 7/8/2008 Version 5.0: Add node IDs, 7/21/2009

Field Summary

(package private) static int	ALLOCATION_BLOCK_SIZE The size of allocation blocks.
(package private) static byte	CLASS_HASH_PREFIX The first byte stored in keys for the classes database hash keys.
(package private) static byte	CLASS_ID_PREFIX The first byte value stored in class ID keys.
(package private) static long	FIRST_PLACEHOLDER_ID_KEY The key for the value of the first allocation block placeholder ID.
(package private) static long	INITIAL_NEXT_NODE_ID The first free node ID.
(package private) static long	INITIAL_NEXT_OBJ_ID The first free object ID.
(package private) static long	INITIAL_NEXT_TXN_ID The first free transaction ID.
(package private) static long	MAGIC The magic number: DaRkStAr.
(package private) static long	MAGIC_KEY The key for the magic number.
(package private) static long	MAJOR_KEY The key for the major version number.
(package private) static short	MAJOR_VERSION The major version number.
(package private) static long	MINOR_KEY The key for the minor version number.
(package private) static short	MINOR_VERSION The minor version number.
(package private) static long	NEXT_NODE_ID_KEY The key for the value of the next free node ID.
(package private) static long	NEXT_OBJ_ID_KEY The key for the value of the next free object ID.
(package private) static long	NEXT_TXN_ID_KEY The key for the value of the next free transaction ID, used in the network version.
(package private) static byte	PLACEHOLDER_OBJ_VALUE The first byte stored in the object value for a placeholder
(package private) static byte	QUOTE_OBJ_VALUE The first byte stored in an object value in order to ignore the meaning of the first byte, in particular if it is PLACEHOLDER_OBJ_VALUE or this value.

Method Summary

(package private) static void	create(DbDatabase db, DbTransaction dbTxn) Stores header information in the database.
(package private) static long	getNextId(long key, DbDatabase db, DbTransaction dbTxn, long increment) Returns the next available ID stored under the specified key, and increments the stored value by the specified amount, which must be greater than zero.
(package private) static String	headerString() Returns a string that describes the standard header.
(package private) static String	headerString(int minorVersion) Returns a string that describes the header with the specified minor version number.
(package private) static int	verify(DbDatabase db, DbTransaction dbTxn) Verifies the header information in the database, and returns its minor version number.

Methods inherited from class java.lang.Object

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

Field Detail

MAGIC_KEY

static final long MAGIC_KEY

The key for the magic number.

See Also:

Constant Field Values

MAJOR_KEY

static final long MAJOR_KEY

The key for the major version number.

See Also:

Constant Field Values

MINOR_KEY

static final long MINOR_KEY

The key for the minor version number.

See Also:

Constant Field Values

NEXT_OBJ_ID_KEY

static final long NEXT_OBJ_ID_KEY

The key for the value of the next free object ID.

See Also:

Constant Field Values

NEXT_TXN_ID_KEY

static final long NEXT_TXN_ID_KEY

The key for the value of the next free transaction ID, used in the network version.

See Also:

Constant Field Values

FIRST_PLACEHOLDER_ID_KEY

static final long FIRST_PLACEHOLDER_ID_KEY

The key for the value of the first allocation block placeholder ID.

See Also:

Constant Field Values

NEXT_NODE_ID_KEY

static final long NEXT_NODE_ID_KEY

The key for the value of the next free node ID.

See Also:

Constant Field Values

MAGIC

static final long MAGIC

The magic number: DaRkStAr.

See Also:

Constant Field Values

MAJOR_VERSION

static final short MAJOR_VERSION

The major version number.

See Also:

Constant Field Values

MINOR_VERSION

static final short MINOR_VERSION

The minor version number.

See Also:

Constant Field Values

INITIAL_NEXT_OBJ_ID

static final long INITIAL_NEXT_OBJ_ID

The first free object ID.

See Also:

Constant Field Values

INITIAL_NEXT_TXN_ID

static final long INITIAL_NEXT_TXN_ID

The first free transaction ID.

See Also:

Constant Field Values

INITIAL_NEXT_NODE_ID

static final long INITIAL_NEXT_NODE_ID

The first free node ID.

See Also:

Constant Field Values

CLASS_HASH_PREFIX

static final byte CLASS_HASH_PREFIX

The first byte stored in keys for the classes database hash keys.

See Also:

Constant Field Values

CLASS_ID_PREFIX

static final byte CLASS_ID_PREFIX

The first byte value stored in class ID keys. This value should be greater than CLASS_HASH, to insure that class ID keys come after class hash ones.

See Also:

Constant Field Values

PLACEHOLDER_OBJ_VALUE

static final byte PLACEHOLDER_OBJ_VALUE

The first byte stored in the object value for a placeholder

See Also:

Constant Field Values

QUOTE_OBJ_VALUE

static final byte QUOTE_OBJ_VALUE

The first byte stored in an object value in order to ignore the meaning of the first byte, in particular if it is PLACEHOLDER_OBJ_VALUE or this value. When this is the first byte of object data, the actual data consists of the second and following bytes. Because object data is always serialized data, which uses a specialized encoding that starts with either 1 or 2, this value should not be used in practice.

See Also:

Constant Field Values

ALLOCATION_BLOCK_SIZE

static final int ALLOCATION_BLOCK_SIZE

The size of allocation blocks. The size is fixed so that it can be used at initialization time to find allocation block placeholders that appear at multiples of this size after the offset is stored under the FIRST_PLACEHOLDER_ID_KEY key.

See Also:

Constant Field Values

Method Detail

verify

static int verify(DbDatabase db,
                  DbTransaction dbTxn)

Verifies the header information in the database, and returns its minor version number.

Parameters:

db - the database

dbTxn - the database transaction

Returns:

the minor version number

Throws:

DbDatabaseException - if a problem occurs accessing the database

DataStoreException - if the format of the header information is incorrect

create

static void create(DbDatabase db,
                   DbTransaction dbTxn)

Stores header information in the database.

Parameters:

db - the database

dbTxn - the database transaction

Throws:

DbDatabaseException - if a problem occurs accessing the database

getNextId

static long getNextId(long key,
                      DbDatabase db,
                      DbTransaction dbTxn,
                      long increment)

Returns the next available ID stored under the specified key, and increments the stored value by the specified amount, which must be greater than zero. The return value will be a positive number.

Parameters:

key - the key under which the ID is stored

db - the database

dbTxn - the database transaction

increment - the amount to increment the stored amount

Returns:

the next available ID

Throws:

DbDatabaseException - if a problem occurs accessing the database

IllegalArgumentException - if increment is not greater than zero

headerString

static String headerString()

Returns a string that describes the standard header.

headerString

static String headerString(int minorVersion)

Returns a string that describes the header with the specified minor version number.