SEnvironment (Oracle - Berkeley DB Client-Server API)
Date: 2018-05-29

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

    All Methods Instance Methods Concrete Methods Default Methods
    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`

Copyright (c) 2016, 2018 Oracle and/or its affiliates. All rights reserved.