com.sleepycat.je.dbi
Class DbTree

java.lang.Object
  extended by com.sleepycat.je.dbi.DbTree
All Implemented Interfaces:
Loggable

public class DbTree
extends 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 acacuiqred 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
static DatabaseId ID_DB_ID
           
static DatabaseId NAME_DB_ID
           
static String REP_OPERATIONS_NAME
           
static String UTILIZATION_DB_NAME
           
 
Constructor Summary
DbTree()
          Create a dbTree from the log.
DbTree(EnvironmentImpl env)
          Create a new dbTree for a new environment.
 
Method Summary
 DatabaseImpl createDb(Locker locker, String databaseName, DatabaseConfig dbConfig, Database databaseHandle)
          Create a database.
(package private)  void dbRemove(Locker locker, String databaseName)
          Remove the database by deleting the nameLN.
(package private)  boolean dbRename(Locker locker, String databaseName, String newName)
          Return true if the operation succeeded, false otherwise.
(package private)  void deleteMapLN(DatabaseId id)
           
 void dump()
          For debugging.
 void dumpLog(StringBuffer sb, boolean verbose)
          Write the object into the string buffer for log dumping.
(package private)  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, Map 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, String dbNameIfAvailable)
          Get a database object based on an id only.
 DatabaseImpl getDb(Locker nameLocker, String databaseName, Database databaseHandle)
          Get a database object given a database name.
 String getDbName(DatabaseId id)
          Return the database name for a given db.
 List getDbNames()
           
 Map getDbNamesAndIds()
           
 int getHighestLevel()
           
 int getHighestLevel(DatabaseImpl dbImpl)
           
 List getInternalDbNames()
          Return a list of the names of internally used databases.
 List getInternalNoLookupDbNames()
          Return a list of the names of internally used databases that don't get looked up through the naming tree.
 int getLastDbId()
          Get the latest allocated id, for checkpoint info.
 int getLogSize()
           
 long getTransactionId()
           
 boolean isReservedDbName(String name)
          Returns true if the name is a reserved JE database name.
 void modifyDbRoot(DatabaseImpl db)
          Called by the Tree to propagate a root change.
 void optionalModifyDbRoot(DatabaseImpl db)
          Called by the Tree to propagate a root change.
 void readFromLog(ByteBuffer itemBuffer, byte entryTypeVersion)
          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(Map dbCache)
          Calls releaseDb for all DBs in the given map of DatabaseId to DatabaseImpl.
(package private)  void setEnvironmentImpl(EnvironmentImpl envImpl)
          Set the db environment during recovery, after instantiating the tree from the log.
 void setLastDbId(int maxDbId)
          Initialize the db id, from recovery.
 String toString()
           
(package private)  TruncateResult truncate(Locker locker, DatabaseImpl oldDatabase, boolean returnCount)
          Deprecated. This method used by Database.truncate()
(package private)  long truncate(Locker locker, String databaseName, boolean returnCount)
          To truncate, remove the database named by databaseName and create a new database in its place.
 boolean verify(VerifyConfig config, PrintStream out)
           
 void writeToLog(ByteBuffer logBuffer)
          Serialize this object into the buffer.
 
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 String UTILIZATION_DB_NAME
See Also:
Constant Field Values

REP_OPERATIONS_NAME

public static final String REP_OPERATIONS_NAME
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)
       throws DatabaseException
Create a new dbTree for a new environment.

Throws:
DatabaseException
Method Detail

getLastDbId

public int getLastDbId()
Get the latest allocated id, for checkpoint info.


setLastDbId

public void setLastDbId(int maxDbId)
Initialize the db id, from recovery.


setEnvironmentImpl

void setEnvironmentImpl(EnvironmentImpl envImpl)
                  throws DatabaseException
Set the db environment during recovery, after instantiating the tree from the log.

Throws:
DatabaseException

createDb

public DatabaseImpl createDb(Locker locker,
                             String databaseName,
                             DatabaseConfig dbConfig,
                             Database databaseHandle)
                      throws DatabaseException
Create a database. 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] Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Parameters:
locker - owning locker
databaseName - identifier for database
dbConfig -
Throws:
DatabaseException

optionalModifyDbRoot

public void optionalModifyDbRoot(DatabaseImpl db)
                          throws DatabaseException
Called by the Tree to propagate a root change. If the tree is a data database, we will write the MapLn that represents this db to the log. If the tree is one of the mapping dbs, we'll write the dbtree to the log.

Parameters:
db - the target db
Throws:
DatabaseException

modifyDbRoot

public void modifyDbRoot(DatabaseImpl db)
                  throws DatabaseException
Called by the Tree to propagate a root change. If the tree is a data database and it's not a deferred write db, we will write the MapLN that represents this db to the log. If the tree is one of the mapping dbs, we'll write the dbtree to the log. Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Parameters:
db - the target db
Throws:
DatabaseException

dbRename

boolean dbRename(Locker locker,
                 String databaseName,
                 String newName)
           throws DatabaseException
Return true if the operation succeeded, false otherwise.

Throws:
DatabaseException

dbRemove

void dbRemove(Locker locker,
              String databaseName)
        throws DatabaseException
Remove the database by deleting the nameLN.

Throws:
DatabaseException

truncate

long truncate(Locker locker,
              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

truncate

TruncateResult truncate(Locker locker,
                        DatabaseImpl oldDatabase,
                        boolean returnCount)
                  throws DatabaseException
Deprecated. This method used by Database.truncate()

Truncate a database named by databaseName. Return the new DatabaseImpl object that represents the truncated database. The old one is marked as deleted. Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Throws:
DatabaseException

getDb

public DatabaseImpl getDb(Locker nameLocker,
                          String databaseName,
                          Database databaseHandle)
                   throws DatabaseException
Get a database object given a database name. 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,
                          Map 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,
                          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(Map 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,
                      PrintStream out)
               throws DatabaseException
Throws:
DatabaseException

getDbName

public String getDbName(DatabaseId id)
                 throws DatabaseException
Return the database name for a given db. Slow, must traverse. Used by truncate and for debugging. Do not evict (do not call CursorImpl.setAllowEviction(true)) during low level DbTree operation. [#15176]

Throws:
DatabaseException

getDbNamesAndIds

public Map getDbNamesAndIds()
                     throws DatabaseException
Returns:
a map of database ids to database names (Strings).
Throws:
DatabaseException

getDbNames

public List getDbNames()
                throws DatabaseException
Returns:
a list of database names held in the environment, as strings.
Throws:
DatabaseException

getInternalNoLookupDbNames

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


getInternalDbNames

public List getInternalDbNames()
Return a list of the names of internally used databases.


isReservedDbName

public boolean isReservedDbName(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

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(ByteBuffer logBuffer)
Description copied from interface: Loggable
Serialize this object into the buffer.

Specified by:
writeToLog in interface Loggable
Parameters:
logBuffer - is the destination buffer
See Also:
Loggable.writeToLog(java.nio.ByteBuffer)

readFromLog

public void readFromLog(ByteBuffer itemBuffer,
                        byte entryTypeVersion)
                 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(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()

dumpString

String dumpString(int nSpaces)

toString

public String toString()
Overrides:
toString in class Object

dump

public void dump()
          throws DatabaseException
For debugging.

Throws:
DatabaseException


Copyright 2004,2008 Oracle. All rights reserved.