com.sleepycat.client

Class SEnvironment

java.lang.Object

com.sleepycat.client.SEnvironment

All Implemented Interfaces:

TxnHelper, java.lang.AutoCloseable

public class SEnvironment
extends java.lang.Object
implements TxnHelper, java.lang.AutoCloseable

A database environment. Environments include support for all of caching, locking, logging and transactions.

To open an existing environment with default attributes the application may use a default environment configuration object or null:

  // Open an environment handle with default attributes.
  BdbServerConnection conn = BdbServerConnection.connect(host, port);
  SEnvironment env = conn.openEnvironment(home, new SEnvironmentConfig());
 

or

  SEnvironment env = conn.openEnvironment(home, null);
 

Note that many SEnvironment objects may access a single environment.

To create an environment or customize attributes, the application should customize the configuration class. For example:

  SEnvironmentConfig envConfig = new SEnvironmentConfig();
  envConfig.setAllowCreate(true).setCacheSize(1000000);
  ...
  SEnvironment env = conn.openEnvironment(home, envConfig);
 

An environment handle is an SEnvironment instance. More than one SEnvironment instance may be created for the same physical directory, which is the same as saying that more than one SEnvironment handle may be open at one time for a given environment.

The SEnvironment handle should not be closed while any other handle remains open that is using it as a reference (for example, SDatabase or STransaction). Once SEnvironment.close is called, this object may not be accessed again, regardless of whether or not it throws an exception.

Nested Class Summary

Nested classes/interfaces inherited from interface com.sleepycat.client.TxnHelper

TxnHelper.TransactionOperations<V>

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SEnvironment(SEnvironment env) Create a shallow copy of the given environment.

Method Summary

Modifier and Type	Method and Description
STransaction	beginTransaction(STransaction parent, STransactionConfig config) Create a new transaction in the database environment.
void	checkpoint(SCheckpointConfig config) Synchronously checkpoint the database environment.
void	close() Close the database environment, freeing any allocated resources and closing any underlying subsystems.
SCacheFileStats[]	getCacheFileStats(SStatsConfig config) Return statistics for individual files in the cache.
SCacheStats	getCacheStats(SStatsConfig config) Returns the memory pool (that is, the buffer cache) subsystem statistics.
SEnvironmentConfig	getConfig() Return this object's configuration.
SEnvironment	getEnvironment() Return this environment.
java.lang.String	getHome() Return the database environment home directory.
SLockStats	getLockStats(SStatsConfig config) Return the database environment's locking statistics.
SLogStats	getLogStats(SStatsConfig config) Return the database environment's logging statistics.
SMultiStats	getMultipleStats(SMultiStatsConfig config) Return multiple database environment's statistics.
SMutexStats	getMutexStats(SStatsConfig config) Return the database environment's mutex statistics.
java.nio.ByteOrder	getServerByteOrder() Return the native byte order of the connected server.
STransactionStats	getTransactionStats(SStatsConfig config) Return the database environment's transactional statistics.
default <V> V	handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
SDatabase	openDatabase(STransaction txn, java.lang.String fileName, java.lang.String databaseName, SDatabaseConfig config) Open a database.
SSecondaryDatabase	openSecondaryDatabase(STransaction txn, java.lang.String fileName, java.lang.String databaseName, SDatabase primaryDatabase, SSecondaryConfig config) Open a secondary database.
default <V> V	remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)
default <V> V	remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)
void	removeDatabase(STransaction txn, java.lang.String fileName, java.lang.String databaseName, boolean force) Remove the database specified by the fileName and databaseName parameters.
void	renameDatabase(STransaction txn, java.lang.String fileName, java.lang.String databaseName, java.lang.String newName, boolean force) Rename a database.
void	setConfig(SEnvironmentConfig config) Change the settings in an existing environment handle.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.sleepycat.client.TxnHelper

runInSingleTxn, runInSingleTxnWithIOException

Constructor Detail

SEnvironment

protected SEnvironment(SEnvironment env)

Create a shallow copy of the given environment. The original environment handle must not be used anymore after this method returns. This constructor is reserved for tests.

Parameters:

env - the environment

Method Detail

close

public void close()
           throws SDatabaseException

Close the database environment, freeing any allocated resources and closing any underlying subsystems.

When you call this method, all open database and cursor handles that depend on this are closed automatically, and should not be reused.

The SEnvironment handle should not be closed while any other handle that refers to it is not yet closed.

Closing the environment aborts any unresolved transactions. Applications should not depend on this behavior for transactions involving databases; all such transactions should be explicitly resolved. The problem with depending on this semantic is that aborting an unresolved transaction involving database operations requires a database handle. Because the database handles should have been closed before closing the environment, it will not be possible to abort the transaction, and recovery will have to be run on the database environment before further operations are done.

After this method has been called, regardless of its return, the SEnvironment handle may not be accessed again.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

SDatabaseException - if any error occurs

getEnvironment

public SEnvironment getEnvironment()

Return this environment.

Specified by:

getEnvironment in interface TxnHelper

Returns:

this environment

getServerByteOrder

public java.nio.ByteOrder getServerByteOrder()

Return the native byte order of the connected server.

Returns:

the native byte order of the connected server

getConfig

public SEnvironmentConfig getConfig()
                             throws SDatabaseException

Return this object's configuration.

Returns:

this object's configuration

Throws:

SDatabaseException - if any error occurs

setConfig

public void setConfig(SEnvironmentConfig config)
               throws SDatabaseException

Change the settings in an existing environment handle. Only set attributes are changed. Therefore, there is no need to call getConfig() to get the current setting because unset attributes are not changed.

Parameters:

config - the database environment attributes; if null, no attribute is changed

Throws:

SDatabaseException - if any error occurs

getHome

public java.lang.String getHome()

Return the database environment home directory. This directory is normally identified in BdbServerConnection.openEnvironment(String, SEnvironmentConfig).

Returns:

the database environment home directory

openDatabase

public SDatabase openDatabase(STransaction txn,
                              java.lang.String fileName,
                              java.lang.String databaseName,
                              SDatabaseConfig config)
                       throws java.io.IOException,
                              SDatabaseException

Open a database.

The database is represented by the file and database parameters.

The currently supported database 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.

Storage and retrieval are based on key/data pairs; see SDatabaseEntry for more information.

Opening a database 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.

Parameters:

txn - for a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit

fileName - the name of an underlying file that will be used to back the database

databaseName - an optional parameter that allows applications to have multiple databases in a single file. Although no databaseName parameter needs to be specified, it is an error to attempt to open a second database in a physical file that was not initially created using a databaseName parameter; further, the databaseName parameter is not supported by the Queue format

config - the database open attributes; if null, default attributes are used.

Returns:

a new database handle

Throws:

java.io.IOException - if the database file cannot be accessed

SResourceInUseException - if the database is being renamed or removed

SDatabaseException - if any error occurs

openSecondaryDatabase

public SSecondaryDatabase openSecondaryDatabase(STransaction txn,
                                                java.lang.String fileName,
                                                java.lang.String databaseName,
                                                SDatabase primaryDatabase,
                                                SSecondaryConfig config)
                                         throws java.io.IOException,
                                                SDatabaseException

Open a secondary database.

The database is represented by the file and database parameters.

The currently supported database 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.

Storage and retrieval are based on key/data pairs; see SDatabaseEntry for more information.

Opening a database 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.

Parameters:

txn - for a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit

fileName - the name of an underlying file that will be used to back the database

databaseName - an optional parameter that allows applications to have multiple databases in a single file. Although no databaseName parameter needs to be specified, it is an error to attempt to open a second database in a physical file that was not initially created using a databaseName parameter; further, the databaseName parameter is not supported by the Queue format

primaryDatabase - a database handle for the primary database that is to be indexed

config - the secondary database open attributes; if null, default attributes are used

Returns:

a new secondary database handle

Throws:

java.io.IOException - if the database file cannot be accessed

SResourceInUseException - if the database is being renamed or removed

SDatabaseException - if any error occurs

removeDatabase

public void removeDatabase(STransaction txn,
                           java.lang.String fileName,
                           java.lang.String databaseName,
                           boolean force)
                    throws java.io.IOException,
                           SDatabaseException

Remove the database specified by the fileName and databaseName parameters.

If no database is specified, the underlying file specified is removed, incidentally removing all of the databases it contained.

Applications should never remove databases with open SDatabase handles, or in the case of removing a file, when any database in the file has an open handle.

If force is set to true, all open handles for the database, or in the case of removing a file, all open handles for any database in the file are closed so that the remove can proceed. If force is false, and there is at least one open handle for the database, SResourceInUseException is thrown.

Parameters:

txn - if the operation is part of an application-specified transaction, the txn parameter is a STransaction object returned from the beginTransaction(com.sleepycat.client.STransaction, com.sleepycat.client.STransactionConfig) method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit.

fileName - the physical file which contains the database to be removed

databaseName - the database to be removed

force - if true, open handles are closed as necessary to allow the remove operation to proceed; otherwise, throw SResourceInUseException if the database has at least one open handle

Throws:

java.io.IOException - the database file cannot be accessed

SResourceInUseException - if force is false and there is at least one open handle for the database

SDatabaseException - if any error occurs

renameDatabase

public void renameDatabase(STransaction txn,
                           java.lang.String fileName,
                           java.lang.String databaseName,
                           java.lang.String newName,
                           boolean force)
                    throws java.io.IOException,
                           SDatabaseException

Rename a database.

If no database name is specified, the underlying file specified is renamed, incidentally renaming all of the databases it contains.

Applications should never rename databases that are currently in use. If an underlying file is being renamed and logging is currently enabled in the database environment, no database in the file may be open when this method is called.

If force is set to true, all open handles for the database, or in the case of removing a file, all open handles for any database in the file are closed so that the rename can proceed. If force is false, and there is at least one open handle for the database, SResourceInUseException is thrown.

Parameters:

txn - if the operation is part of an application-specified transaction, the txn parameter is a STransaction object returned from the beginTransaction(com.sleepycat.client.STransaction, com.sleepycat.client.STransactionConfig) method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit.

fileName - the physical file which contains the database to be renamed

databaseName - the database to be renamed

newName - the new name of the database or file

force - if true, open handles are closed as necessary to allow the remove operation to proceed; otherwise, throw SResourceInUseException if the database has at least one open handle

Throws:

java.io.IOException - the database file cannot be accessed

SResourceInUseException - if force is false and there is at least one open handle for the database

SDatabaseException - if any error occurs

beginTransaction

public STransaction beginTransaction(STransaction parent,
                                     STransactionConfig config)
                              throws SDatabaseException

Create a new transaction in the database environment.

A parent transaction may not issue any Berkeley DB driver operations -- except for beginTransaction(com.sleepycat.client.STransaction, com.sleepycat.client.STransactionConfig), STransaction.abort() and STransaction.commit() -- while it has active child transactions (child transactions that have not yet been committed or aborted).

Parameters:

parent - if the parent parameter is non-null, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent; transactions may be nested to any level

config - the transaction attributes; if null, default attributes are used.

Returns:

the newly created transaction's handle

Throws:

SDatabaseException - if any error occurs

checkpoint

public void checkpoint(SCheckpointConfig config)
                throws SDatabaseException

Synchronously checkpoint the database environment.

Parameters:

config - the checkpoint attributes; if null, default attributes are used.

Throws:

SDatabaseException - if any error occurs

getCacheFileStats

public SCacheFileStats[] getCacheFileStats(SStatsConfig config)
                                    throws SDatabaseException

Return statistics for individual files in the cache.

Parameters:

config - the statistics attributes; if null, default attributes are used.

Returns:

statistics for individual files in the cache

Throws:

SDatabaseException - if any error occurs

getCacheStats

public SCacheStats getCacheStats(SStatsConfig config)
                          throws SDatabaseException

Returns the memory pool (that is, the buffer cache) subsystem statistics.

Parameters:

config - the statistics attributes

Returns:

the memory pool (that is, the buffer cache) subsystem statistics

Throws:

SDatabaseException - if any error occurs

getLockStats

public SLockStats getLockStats(SStatsConfig config)
                        throws SDatabaseException

Return the database environment's locking statistics.

Parameters:

config - the statistics attributes

Returns:

the database environment's locking statistics

Throws:

SDatabaseException - if any error occurs

getLogStats

public SLogStats getLogStats(SStatsConfig config)
                      throws SDatabaseException

Return the database environment's logging statistics.

Parameters:

config - the statistics attributes

Returns:

the database environment's logging statistics

Throws:

SDatabaseException - if any error occurs

getMutexStats

public SMutexStats getMutexStats(SStatsConfig config)
                          throws SDatabaseException

Return the database environment's mutex statistics.

Parameters:

config - the statistics attributes

Returns:

the database environment's mutex statistics

Throws:

SDatabaseException - if any error occurs

getTransactionStats

public STransactionStats getTransactionStats(SStatsConfig config)
                                      throws SDatabaseException

Return the database environment's transactional statistics.

Parameters:

config - the statistics attributes

Returns:

the database environment's transactional statistics

Throws:

SDatabaseException - if any error occurs

getMultipleStats

public SMultiStats getMultipleStats(SMultiStatsConfig config)
                             throws SDatabaseException

Return multiple database environment's statistics.

The config parameter specifies which statistics are retrieved and what attributes apply for each statistics retrieval operation.

Compared to other statistics retrieval operations that retrieve only a single statistics, this method can save a few network round trips when multiple statistics are retrieved.

Parameters:

config - the multiple statistics attributes

Returns:

the selected database environment's statistics

Throws:

SDatabaseException - if any error occurs

remoteCallWithIOException

public <V> V remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)
                                throws java.io.IOException

Throws:

java.io.IOException

remoteCall

public <V> V remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)

handleRuntimeExceptions

public <V> V handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
                              throws org.apache.thrift.TException

Throws:

org.apache.thrift.TException