Logo Search packages:      
Sourcecode: db4.2 version File versions  Download package

void com::sleepycat::db::Db::open ( DbTxn  txnid,
String  file,
String  database,
int  type,
int  flags,
int  mode 
) throws DbException, java.io.FileNotFoundException, DbDeadlockException, DbLockNotGrantedException [inline]

The Db.open method opens the database represented by the file and database parameters for both reading and writing.

The currently supported Berkeley DB file formats (or access methods ) are Btree, Hash, Queue, and Recno. The Btree format is a representation of a sorted, balanced tree structure. The Hash format is an extensible, dynamic hashing scheme. The Queue format supports fast access to fixed-length records accessed sequentially or by logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally backed by a flat text file.

Storage and retrieval for the Berkeley DB access methods are based on key/data pairs; see Dbt for more information.

Calling Db.open is a relatively expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly opening and closing the database for each new query.

Environment Variables

If the database was opened within a database environment, the environment variable DB_HOME may be used as the path of the database environment home.

Db.open is affected by any database directory specified using the DbEnv.setDataDir method, or by setting the "set_data_dir" string in the environment's DB_CONFIG file.

If the file and dbenv parameters to Db.open are null, the environment variable TMPDIR may be used as a directory in which to create temporary backing files

Parameters:
database optional, and allows applications to have multiple databases in a single file. Although no database parameter needs to be specified, it is an error to attempt to open a second database in a file that was not initially created using a database name. Further, the database parameter is not supported by the Queue format. Finally, when opening multiple databases in the same physical file, it is important to consider locking and memory cache issues; see Opening multiple databases in a single file for more information.

In-memory databases never intended to be preserved on disk may be created by setting both the file and database parameters to null. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe.

Parameters:
file used as the name of an underlying file that will be used to back the database.

In-memory databases never intended to be preserved on disk may be created by setting both the file and database parameters to null. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe.

Parameters:
flags must be set to 0 or by bitwise inclusively OR 'ing together one or more of the following values:
  • Db.DB_AUTO_COMMIT

    Enclose the Db.open call within a transaction. If the call succeeds, the open operation will be recoverable. If the call fails, no database will have been created.

  • Db.DB_DIRTY_READ

    Support dirty reads; that is, read operations on the database may request the return of modified but not yet committed data. This flag must be specified on all Db handles used to perform dirty reads or database updates, otherwise requests for dirty reads may not be honored and the read may block.

  • Db.DB_RDONLY

    Open the database for reading only. Any attempt to modify items in the database will fail, regardless of the actual permissions of any underlying files.

  • Db.DB_THREAD

    Cause the Db handle returned by Db.open to be free-threaded ; that is, usable by multiple threads within a single address space.

    Threading is always assumed in the Java API, so no special flags are required, and Berkeley DB functions will always behave as if the Db.DB_THREAD flag was specified.

  • Db.DB_TRUNCATE

    Physically truncate the underlying file, discarding all previous databases it might have held. Underlying filesystem primitives are used to implement this flag. For this reason, it is applicable only to the file and cannot be used to discard databases within a file.

    The Db.DB_TRUNCATE flag cannot be lock or transaction-protected, and it is an error to specify it in a locking or transaction-protected environment.

Parameters:
mode On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the database open are created with mode mode (as described in chmod (2)) and modified by the process' umask value at the time of creation (see umask (2)). If mode is 0, the database open will use a default mode of readable and writable by both owner and group. On Windows systems, the mode parameter is ignored. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.
txnid If the operation is to be transaction-protected, (other than by specifying the Db.DB_AUTO_COMMIT flag), the txnid parameter is a transaction handle returned from DbEnv.txnBegin; otherwise, null. Note that transactionally protected operations on a Db handle requires the Db handle itself be transactionally protected during its open.
type must be set to one of Db.DB_BTREE, Db.DB_HASH, Db.DB_QUEUE, Db.DB_RECNO, or Db.DB_UNKNOWN. If type is Db.DB_UNKNOWN, the database must already exist and Db.open will automatically determine its type. The Db.getDbType method may be used to determine the underlying type of databases opened using Db.DB_UNKNOWN.
Exceptions:
DbException The Db.open method may fail and throw DbException, encapsulating one of the following non-zero errors: The database cannot be opened without being first upgraded. Db.DB_CREATE and Db.DB_EXCL were specified and the database exists. A nonexistent re_source file was specified.
DbDeadlockException If a transactional database environment operation was selected to resolve a deadlock, the Db.open method will fail and throw a DbDeadlockException exception.
DbLockNotGrantedException If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time, the Db.open method will fail and throw a DbLockNotGrantedException exception.
FileNotFoundException If the file or directory does not exist, the Db.open method will fail and throw a FileNotFoundException exception.
IllegalArgumentException The Db.open method will fail and throw a IllegalArgumentException exception if an unknown database type, page size, hash function, pad byte, byte order, or a flag value or parameter that is incompatible with the specified database was specified; the Db.DB_THREAD flag was specified and fast mutexes are not available for this architecture; the Db.DB_THREAD flag was specified to Db.open, but was not specified to the DbEnv.open call for the environment in which the Db handle was created; a backing flat text file was specified with either the Db.DB_THREAD flag or the provided database environment supports transaction processing; or if an invalid flag value or parameter was specified.

Definition at line 484 of file Db.java.

Referenced by com::sleepycat::examples::bdb::access::AccessExample::AccessExample(), com::sleepycat::examples::bdb::helloworld::HelloDatabaseWorld::open(), com::sleepycat::examples::bdb::shipment::tuple::SampleDatabase::SampleDatabase(), com::sleepycat::examples::bdb::shipment::sentity::SampleDatabase::SampleDatabase(), com::sleepycat::examples::bdb::shipment::marshal::SampleDatabase::SampleDatabase(), com::sleepycat::examples::bdb::shipment::index::SampleDatabase::SampleDatabase(), com::sleepycat::examples::bdb::shipment::factory::SampleDatabase::SampleDatabase(), com::sleepycat::examples::bdb::shipment::entity::SampleDatabase::SampleDatabase(), com::sleepycat::examples::bdb::shipment::basic::SampleDatabase::SampleDatabase(), and com::sleepycat::bdb::StoredClassCatalog::StoredClassCatalog().

                                                           {
        /*
         *  Java is always threaded
         */
        flags |= Db.DB_THREAD;
        open0(txnid, file, database, type, flags, mode);
    }


Generated by  Doxygen 1.6.0   Back to index