com.sleepycat.je.dbi

Class DbTree

java.lang.Object

com.sleepycat.je.dbi.DbTree

All Implemented Interfaces:

Loggable

public class DbTree
extends java.lang.Object
implements Loggable

DbTree represents the database directory for this environment. DbTree is itself implemented through two databases. The nameDatabase maps databaseName-> an internal databaseId. The idDatabase maps databaseId->DatabaseImpl. For example, suppose we have two databases, foo and bar. We have the following structure: nameDatabase idDatabase IN IN | | BIN BIN +-------------+--------+ +---------------+--------+ . | | . | | NameLNs NameLN NameLN MapLNs for MapLN MapLN for internal key=bar key=foo internal dbs key=53 key=79 dbs data= data= data= data= dbId79 dbId53 DatabaseImpl DatabaseImpl | | Tree for foo Tree for bar | | root IN root IN Databases, Cursors, the cleaner, compressor, and other entities have references to DatabaseImpls. It's important that object identity is properly maintained, and that all constituents reference the same DatabaseImpl for the same db, lest they develop disparate views of the in-memory database; corruption would ensue. To ensure that, all entities must obtain their DatabaseImpl by going through the idDatabase. DDL type operations such as create, rename, remove and truncate get their transactional semantics by transactionally locking the NameLN appropriately. A read-lock on the NameLN, called a handle lock, is maintained for all DBs opened via the public API (openDatabase). This prevents them from being renamed or removed while open. However, for internal database operations, no handle lock on the NameLN is acquired and MapLNs are locked with short-lived non-transactional Lockers. An entity that is trying to get a reference to the DatabaseImpl gets a short lived read lock just for the fetch of the MapLN. A write lock on the MapLN is taken when the database is created, deleted, or when the MapLN is evicted. (see DatabaseImpl.isInUse()) The nameDatabase operates pretty much as a regular application database in terms of eviction and recovery. The idDatabase requires special treatment for both eviction and recovery. The issues around eviction of the idDatabase center on the need to ensure that there are no other current references to the DatabaseImpl other than that held by the mapLN. The presence of a current reference would both make the DatabaseImpl not GC'able, and more importantly, would lead to object identify confusion later on. For example, if the MapLN is evicted while there is a current reference to its DatabaseImpl, and then refetched, there will be two in-memory versions of the DatabaseImpl. Since locks on the idDatabase are short lived, DatabaseImpl.useCount acts as a reference count of active current references. DatabaseImpl.useCount must be modified and read in conjunction with appropropriate locking on the MapLN. See DatabaseImpl.isInUse() for details. This reference count checking is only needed when the entire MapLN is evicted. It's possible to evict only the root IN of the database in question, since that doesn't interfere with the DatabaseImpl object identity.

Field Summary

Fields

Modifier and Type	Field and Description
static DatabaseId	ID_DB_ID
static DatabaseId	NAME_DB_ID
static int	NEG_DB_ID_START
static java.lang.String	REP_OPERATIONS_NAME
static java.lang.String	UTILIZATION_DB_NAME
static java.lang.String	VLSN_MAP_DB_NAME

Constructor Summary

Constructors

Constructor and Description
DbTree() Create a dbTree from the log.
DbTree(EnvironmentImpl env, boolean replicationIntended) Create a new dbTree for a new environment.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Release resources and update memory budget.
DatabaseImpl	createClientDb(Locker locker, java.lang.String databaseName, DatabaseConfig dbConfig, NameLN replicatedLN, ReplicationContext repContext) Create a replicated database on this client node.
DatabaseImpl	createDb(Locker locker, java.lang.String databaseName, DatabaseConfig dbConfig, Database databaseHandle) Creates a new database object given a database name.
DatabaseImpl	createInternalDb(Locker locker, java.lang.String databaseName, DatabaseConfig dbConfig) Create a database for internal use that will never be replicated.
void	dbRemove(Locker locker, java.lang.String databaseName, DatabaseId checkId) Remove the database by deleting the nameLN.
boolean	dbRename(Locker locker, java.lang.String databaseName, java.lang.String newName) Return true if the operation succeeded, false otherwise.
(package private) void	deleteMapLN(DatabaseId id)
void	dump() For debugging.
void	dumpLog(java.lang.StringBuffer sb, boolean verbose) Write the object into the string buffer for log dumping.
(package private) java.lang.String	dumpString(int nSpaces)
DatabaseImpl	getDb(DatabaseId dbId) Get a database object based on an id only.
DatabaseImpl	getDb(DatabaseId dbId, long lockTimeout) Get a database object based on an id only.
DatabaseImpl	getDb(DatabaseId dbId, long lockTimeout, java.util.Map<DatabaseId,DatabaseImpl> dbCache) Get a database object based on an id only, caching the id-db mapping in the given map.
DatabaseImpl	getDb(DatabaseId dbId, long lockTimeout, java.lang.String dbNameIfAvailable) Get a database object based on an id only.
DatabaseImpl	getDb(Locker nameLocker, java.lang.String databaseName, Database databaseHandle) Get a database object given a database name.
java.lang.String	getDbName(DatabaseId id) Return the database name for a given db.
java.util.List<java.lang.String>	getDbNames()
java.util.Map<DatabaseId,java.lang.String>	getDbNamesAndIds()
int	getHighestLevel()
int	getHighestLevel(DatabaseImpl dbImpl)
java.util.List<java.lang.String>	getInternalDbNames() Return a list of the names of internally used databases.
java.util.List<java.lang.String>	getInternalNoLookupDbNames() Return a list of the names of internally used databases that don't get looked up through the naming tree.
int	getLastLocalDbId() The last allocated local and replicated db ids are used for ckpts.
int	getLastReplicatedDbId()
int	getLogSize()
long	getTransactionId()
(package private) long	getTreeAdminMemory()
(package private) void	initExistingEnvironment(EnvironmentImpl envImpl, boolean replicationIntended) Initialize the db tree during recovery, after instantiating the tree from the log.
static boolean	isReservedDbName(java.lang.String name) Returns true if the name is a reserved JE database name.
boolean	logicalEquals(Loggable other)
void	modifyDbRoot(DatabaseImpl db) Write the MapLN to disk.
void	modifyDbRoot(DatabaseImpl db, long ifBeforeLsn, boolean mustExist) Write a MapLN to the log in order to: - propagate a root change - save per-db utilization information - save database config information.
void	optionalModifyDbRoot(DatabaseImpl db) Check deferred write settings before writing the MapLN.
void	readFromLog(java.nio.ByteBuffer itemBuffer, byte entryVersion) Initialize this object from the data in itemBuf.
void	rebuildINListMapDb() Rebuild the IN list after recovery.
void	releaseDb(DatabaseImpl db) Decrements the use count of the given DB, allowing it to be evicted if the use count reaches zero.
void	releaseDbs(java.util.Map<DatabaseId,DatabaseImpl> dbCache) Calls releaseDb for all DBs in the given map of DatabaseId to DatabaseImpl.
void	setLastDbId(int lastReplicatedDbId, int lastLocalDbId) Initialize the db ids, from recovery.
java.lang.String	toString()
long	truncate(Locker locker, java.lang.String databaseName, boolean returnCount) To truncate, remove the database named by databaseName and create a new database in its place.
void	updateFromReplay(DatabaseId replayDbId)
boolean	verify(VerifyConfig config, java.io.PrintStream out)
void	writeToLog(java.nio.ByteBuffer logBuffer) This log entry type is configured to perform marshaling (getLogSize and writeToLog) under the write log mutex.

Methods inherited from class java.lang.Object

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

Field Detail

ID_DB_ID

public static final DatabaseId ID_DB_ID

NAME_DB_ID

public static final DatabaseId NAME_DB_ID

UTILIZATION_DB_NAME

public static final java.lang.String UTILIZATION_DB_NAME

See Also:

Constant Field Values

REP_OPERATIONS_NAME

public static final java.lang.String REP_OPERATIONS_NAME

See Also:

Constant Field Values

VLSN_MAP_DB_NAME

public static final java.lang.String VLSN_MAP_DB_NAME

See Also:

Constant Field Values

NEG_DB_ID_START

public static final int NEG_DB_ID_START

See Also:

Constant Field Values

Constructor Detail

DbTree

public DbTree()
       throws DatabaseException

Create a dbTree from the log.

Throws:

DatabaseException

DbTree

public DbTree(EnvironmentImpl env,
      boolean replicationIntended)
       throws DatabaseException

Create a new dbTree for a new environment.

Throws:

DatabaseException

Method Detail

getLastLocalDbId

public int getLastLocalDbId()

The last allocated local and replicated db ids are used for ckpts.

getLastReplicatedDbId

public int getLastReplicatedDbId()

setLastDbId

public void setLastDbId(int lastReplicatedDbId,
               int lastLocalDbId)

Initialize the db ids, from recovery.

updateFromReplay

public void updateFromReplay(DatabaseId replayDbId)

initExistingEnvironment

void initExistingEnvironment(EnvironmentImpl envImpl,
                           boolean replicationIntended)
                       throws DatabaseException

Initialize the db tree during recovery, after instantiating the tree from the log. a. set up references to the environment impl b. check for replication rules.

Throws:

DatabaseException

createDb

public DatabaseImpl createDb(Locker locker,
                    java.lang.String databaseName,
                    DatabaseConfig dbConfig,
                    Database databaseHandle)
                      throws DatabaseException

Creates a new database object given a database name. Increments the use count of the new DB to prevent it from being evicted. releaseDb should be called when the returned object is no longer used, to allow it to be evicted. See DatabaseImpl.isInUse. [#13415]

Throws:

DatabaseException

createInternalDb

public DatabaseImpl createInternalDb(Locker locker,
                            java.lang.String databaseName,
                            DatabaseConfig dbConfig)
                              throws DatabaseException

Create a database for internal use that will never be replicated.

Throws:

DatabaseException

createClientDb

public DatabaseImpl createClientDb(Locker locker,
                          java.lang.String databaseName,
                          DatabaseConfig dbConfig,
                          NameLN replicatedLN,
                          ReplicationContext repContext)
                            throws DatabaseException

Create a replicated database on this client node.

Throws:

DatabaseException

optionalModifyDbRoot

public void optionalModifyDbRoot(DatabaseImpl db)
                          throws DatabaseException

Check deferred write settings before writing the MapLN.

Parameters:

db - the database represented by this MapLN

Throws:

DatabaseException

modifyDbRoot

public void modifyDbRoot(DatabaseImpl db)
                  throws DatabaseException

Write the MapLN to disk.

Parameters:

db - the database represented by this MapLN

Throws:

DatabaseException

modifyDbRoot

public void modifyDbRoot(DatabaseImpl db,
                long ifBeforeLsn,
                boolean mustExist)
                  throws DatabaseException

Write a MapLN to the log in order to: - propagate a root change - save per-db utilization information - save database config information. Any MapLN writes must be done through this method, in order to ensure that the root latch is taken, and updates to the rootIN are properly safeguarded. See MapN.java for more detail.

Parameters:

db - the database whose root is held by this MapLN

ifBeforeLsn - if argument is not NULL_LSN, only do the write if this MapLN's current LSN is before isBeforeLSN.

if - true, throw DatabaseException if the DB does not exist; if false, silently do nothing.

Throws:

DatabaseException

dbRename

public boolean dbRename(Locker locker,
               java.lang.String databaseName,
               java.lang.String newName)
                 throws DatabaseException

Return true if the operation succeeded, false otherwise.

Throws:

DatabaseException

dbRemove

public void dbRemove(Locker locker,
            java.lang.String databaseName,
            DatabaseId checkId)
              throws DatabaseException

Remove the database by deleting the nameLN. Does nothing if the non-null checkId argument does not match the database identified by databaseName. Does nothing if the database name does not exist.

Throws:

DatabaseException

truncate

public long truncate(Locker locker,
            java.lang.String databaseName,
            boolean returnCount)
              throws DatabaseException

To truncate, remove the database named by databaseName and create a new database in its place. Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Parameters:

returnCount - if true, must return the count of records in the database, which can be an expensive option.

Throws:

DatabaseException

deleteMapLN

void deleteMapLN(DatabaseId id)
           throws DatabaseException

Throws:

DatabaseException

getDb

public DatabaseImpl getDb(Locker nameLocker,
                 java.lang.String databaseName,
                 Database databaseHandle)
                   throws DatabaseException

Get a database object given a database name. Increments the use count of the given DB to prevent it from being evicted. releaseDb should be called when the returned object is no longer used, to allow it to be evicted. See DatabaseImpl.isInUse. [#13415] Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Parameters:

nameLocker - is used to access the NameLN. As always, a NullTxn is used to access the MapLN.

databaseName - target database

Returns:

null if database doesn't exist

Throws:

DatabaseException

getDb

public DatabaseImpl getDb(DatabaseId dbId)
                   throws DatabaseException

Get a database object based on an id only. Used by recovery, cleaning and other clients who have an id in hand, and don't have a resident node, to find the matching database for a given log entry.

Throws:

DatabaseException

getDb

public DatabaseImpl getDb(DatabaseId dbId,
                 long lockTimeout)
                   throws DatabaseException

Get a database object based on an id only. Specify the lock timeout to use, or -1 to use the default timeout. A timeout should normally only be specified by daemons with their own timeout configuration. public for unit tests.

Throws:

DatabaseException

getDb

public DatabaseImpl getDb(DatabaseId dbId,
                 long lockTimeout,
                 java.util.Map<DatabaseId,DatabaseImpl> dbCache)
                   throws DatabaseException

Get a database object based on an id only, caching the id-db mapping in the given map.

Throws:

DatabaseException

getDb

public DatabaseImpl getDb(DatabaseId dbId,
                 long lockTimeout,
                 java.lang.String dbNameIfAvailable)
                   throws DatabaseException

Get a database object based on an id only. Specify the lock timeout to use, or -1 to use the default timeout. A timeout should normally only be specified by daemons with their own timeout configuration. public for unit tests. Increments the use count of the given DB to prevent it from being evicted. releaseDb should be called when the returned object is no longer used, to allow it to be evicted. See DatabaseImpl.isInUse. [#13415] Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Throws:

DatabaseException

releaseDb

public void releaseDb(DatabaseImpl db)

Decrements the use count of the given DB, allowing it to be evicted if the use count reaches zero. Must be called to release a DatabaseImpl that was returned by a method in this class. See DatabaseImpl.isInUse. [#13415]

releaseDbs

public void releaseDbs(java.util.Map<DatabaseId,DatabaseImpl> dbCache)

Calls releaseDb for all DBs in the given map of DatabaseId to DatabaseImpl. See getDb(DatabaseId, long, Map). [#13415]

rebuildINListMapDb

public void rebuildINListMapDb()
                        throws DatabaseException

Rebuild the IN list after recovery.

Throws:

DatabaseException

verify

public boolean verify(VerifyConfig config,
             java.io.PrintStream out)
               throws DatabaseException

Throws:

DatabaseException

getDbName

public java.lang.String getDbName(DatabaseId id)
                           throws DatabaseException

Return the database name for a given db. Slow, must traverse. Called by Database.getName. Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Throws:

DatabaseException

getDbNamesAndIds

public java.util.Map<DatabaseId,java.lang.String> getDbNamesAndIds()
                                                            throws DatabaseException

Returns:

a map of database ids to database names (Strings).

Throws:

DatabaseException

getDbNames

public java.util.List<java.lang.String> getDbNames()
                                            throws DatabaseException

Returns:

a list of database names held in the environment, as strings.

Throws:

DatabaseException

getInternalNoLookupDbNames

public java.util.List<java.lang.String> getInternalNoLookupDbNames()

Return a list of the names of internally used databases that don't get looked up through the naming tree.

getInternalDbNames

public java.util.List<java.lang.String> getInternalDbNames()

Return a list of the names of internally used databases. TODO: The internal replication DBs are not added here and therefore not verified by DbVerify. Reassess for HA release.

isReservedDbName

public static boolean isReservedDbName(java.lang.String name)

Returns true if the name is a reserved JE database name.

getHighestLevel

public int getHighestLevel()
                    throws DatabaseException

Returns:

the higest level node in the environment.

Throws:

DatabaseException

getHighestLevel

public int getHighestLevel(DatabaseImpl dbImpl)
                    throws DatabaseException

Returns:

the higest level node for this database.

Throws:

DatabaseException

close

public void close()

Release resources and update memory budget. Should only be called when this dbtree is closed and will never be accessed again.

getTreeAdminMemory

long getTreeAdminMemory()

getLogSize

public int getLogSize()

Specified by:

getLogSize in interface Loggable

Returns:

number of bytes used to store this object.

See Also:

Loggable.getLogSize()

writeToLog

public void writeToLog(java.nio.ByteBuffer logBuffer)

This log entry type is configured to perform marshaling (getLogSize and writeToLog) under the write log mutex. Otherwise, the size could change in between calls to these two methods as the result of utilizaton tracking.

Specified by:

writeToLog in interface Loggable

Parameters:

logBuffer - is the destination buffer

See Also:

Loggable.writeToLog(java.nio.ByteBuffer)

readFromLog

public void readFromLog(java.nio.ByteBuffer itemBuffer,
               byte entryVersion)
                 throws LogException

Description copied from interface: Loggable

Initialize this object from the data in itemBuf.

Specified by:

readFromLog in interface Loggable

Throws:

LogException

See Also:

Loggable.readFromLog(java.nio.ByteBuffer, byte)

dumpLog

public void dumpLog(java.lang.StringBuffer sb,
           boolean verbose)

Description copied from interface: Loggable

Write the object into the string buffer for log dumping. Each object should be dumped without indentation or new lines and should be valid XML.

Specified by:

dumpLog in interface Loggable

Parameters:

sb - destination string buffer

verbose - if true, dump the full, verbose version

See Also:

Loggable.dumpLog(java.lang.StringBuffer, boolean)

getTransactionId

public long getTransactionId()

Specified by:

getTransactionId in interface Loggable

Returns:

the transaction id embedded within this loggable object. Objects that have no transaction id should return 0.

See Also:

Loggable.getTransactionId()

logicalEquals

public boolean logicalEquals(Loggable other)

Specified by:

logicalEquals in interface Loggable

Returns:

true if these two loggable items are logically the same. Used for replication testing.

See Also:

Always return false, this item should never be compared.

dumpString

java.lang.String dumpString(int nSpaces)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

dump

public void dump()
          throws DatabaseException

For debugging.

Throws:

DatabaseException