Chapter 2. Enabling Transactions

Table of Contents

File Naming
Error Support
Shared Memory Regions
Security Considerations
Opening a Transactional Environment and Container
Opening Berkeley DB Databases

In order to use transactions with your application, you must turn them on. To do this you must:


All BDB XML applications use environments. However, simple BDB XML applications can use a default environment that only provide a small subset of features — most notably, multi-threaded access (but not multi-process) is enabled, as is the in-memory cache. For more advanced features, such as transactional protection, you must use an externally-managed environment.

An environment, represents an encapsulation of one or more containers and any associated log and region files. They are used to support multi-threaded and multi-process applications by allowing different threads of control to share the in-memory cache, the locking tables, the logging subsystem, and the file namespace. By sharing these things, your concurrent application is more efficient than if each thread of control had to manage these resources on its own.

By default all BDB XML containers are backed by files on disk. In addition to these files, transactional BDB XML applications create logs that are also by default stored on disk (they can optionally be backed using shared memory). Finally, transactional BDB XML applications also create and use shared-memory regions that are also typically backed by the filesystem. But like containers and logs, the regions can be maintained strictly in-memory if your application requires it. For an example of an application that manages all environment files in-memory, see In-Memory Transaction Example.

File Naming

In order to operate, your BDB XML application must be able to locate its container files, log files, and region files. If these are stored in the filesystem, then you must tell BDB XML where they are located (a number of mechanisms exist that allow you to identify the location of these files – see below). Otherwise, by default they are located in the current working directory.

Specifying the Environment Home Directory

The environment home directory is used to determine where BDB XML files are located. Its location is identified using one of the following mechanisms, in the following order of priority:

  • If no information is given as to where to put the environment home, then the current working directory is used.

  • If a home directory is specified on the Environment() constructor, then that location is always used for the environment home.

  • If a home directory is not supplied to Environment(), then the directory identified by the DB_HOME environment variable is used if you specify true to either the EnvironmentConfig.setUseEnvironment() or EnvironmentConfig.setUseEnvironmentRoot() method. Both methods allow you to identify the path to the environment's home directory using DB_HOME. However, EnvironmentConfig.setUseEnvironmentRoot() is honored only if the process is run with root or administrative privileges.

Specifying File Locations

By default, all BDB XML files are created relative to the environment home directory. For example, suppose your environment home is in /export/myAppHome. Also suppose you name your container data/myContainer.dbxml. Then in this case, the container is placed in: /export/myAppHome/data/myContainer.dbxml.

That said, BDB XML always defers to absolute pathnames. This means that if you provide an absolute filename when you name your container, then that file is not placed relative to the environment home directory. Instead, it is placed in the exact location that you specified for the filename.

On UNIX systems, an absolute pathname is a name that begins with a forward slash ('/'). On Windows systems, an absolute pathname is a name that begins with one of the following:

  • A backslash ('\').

  • Any alphabetic letter, followed by a colon (':'), followed by a backslash ('\').


Try not to use absolute path names for your environment's files. Under certain recovery scenarios, absolute path names can render your environment unrecoverable. This occurs if you are attempting to recover your environment on a system that does not support the absolute path name that you used.

Identifying Specific File Locations

As described in the previous sections, BDB XML will place all its files in or relative to the environment home directory. You can also cause a specific container file to be placed in a particular location by using an absolute path name for its name. In this situation, the environment's home directory is not considered when naming the file.

It is frequently desirable to place container, log, and region files on separate disk drives. By spreading I/O across multiple drives, you can increase parallelism and improve throughput. Additionally, by placing log files and container files on separate drives, you improve your application's reliability by providing your application with a greater chance of surviving a disk failure.

You can cause BDB XML's files to be placed in specific locations using the following mechanisms:

File Type To Override
container files

You can cause container files to be created in a directory other than the environment home by using the EnvironmentConfig.addDataDir() method. The directory identified here must exist. If a relative path is provided, then the directory location is resolved relative to the environment's home directory.

This method modifies the directory used for container files created and managed by a single environment handle; it does not configure the entire environment.

You can also set a default data location that is used by the entire environment by using the set_data_dir parameter in the environment's DB_CONFIG file. Note that the set_data_dir parameter overrides any value set by the EnvironmentConfig.addDataDir() method.

Log files

You can cause log files to be created in a directory other than the environment home directory by using the EnvironmentConfig.LogDirectory() method. The directory identified here must exist. If a relative path is provided, then the directory location is resolved relative to the environment's home directory.

This method modifies the directory used for container files created and managed by a single environment handle; it does not configure the entire environment.

You can also set a default log file location that is used by the entire environment by using the set_lg_dir parameter in the environment's DB_CONFIG file. Note that the set_lg_dir parameter overrides any value set by the EnvironmentConfig.LogDirectory() method.

Region files If backed by the filesystem, region files are always placed in the environment home directory.

Note that the DB_CONFIG must reside in the environment home directory. Parameters are specified in it one parameter to a line. Each parameter is followed by a space, which is followed by the parameter value. For example:

    set_data_dir /export1/db/env_data_files 

Error Support

To simplify error handling and to aid in application debugging, environments offer several useful methods. They are:

  • Sets the to be used for displaying error messages issued by the BDB XML library.

  • EnvironmentConfig.setErrorHandler()

    Defines the message handler that is called when an error message is issued by BDB XML. The error prefix and message are passed to this callback. It is up to the application to display this information correctly.

    Note that the message handler must be an implementation of the com.sleepycat.db.ErrorHandler interface.

    This is the recommended way to get error messages from BDB XML.

  • EnvironmentConfig.setErrorPrefix()

    Sets the prefix used to for any error messages issued by the BDB XML library.

Shared Memory Regions

The subsystems that you enable for an environment (in our case, transaction, logging, locking, and the memory pool) are described by one or more regions. The regions contain all of the state information that needs to be shared among threads and/or processes using the environment.

Regions may be backed by the file system, by heap memory, or by system shared memory.


When BDB XML dynamically obtains memory, it uses memory outside of the JVM. Normally the amount of memory that BDB XML obtains is trivial, a few bytes here and there, so you might not notice it. However, if heap or system memory is used to back your region files, then this can represent a significant amount of memory being used by BDB XML above and beyond the memory required by the JVM process. As a result, the JVM process may appear to be using more memory than you told the process it could use.

Regions Backed by Files

By default, shared memory regions are created as files in the environment's home directory (not the environment's data directory). If it is available, the POSIX mmap interface is used to map these files into your application's address space. If mmap is not available, then the UNIX shmget interfaces are used instead (again, if they are available).

In this default case, the region files are named __db.### (for example, __db.001, __db.002, and so on).

Regions Backed by Heap Memory

If heap memory is used to back your shared memory regions, the environment may only be accessed by a single process, although that process may be multi-threaded. In this case, the regions are managed only in memory, and they are not written to the filesystem. You indicate that heap memory is to be used for the region files by specifying true to the EnvironmentConfig.setPrivate() method.

(For an example of an entirely in-memory transactional application, see In-Memory Transaction Example.)

Regions Backed by System Memory

Finally, you can cause system memory to be used for your regions instead of memory-mapped files. You do this by providing true to the EnvironmentConfig.setSystemMemory() method.

When region files are backed by system memory, BDB XML creates a single file in the environment's home directory. This file contains information necessary to identify the system shared memory in use by the environment. By creating this file, BDB XML enables multiple processes to share the environment.

The system memory that is used is architecture-dependent. For example, on systems supporting X/Open-style shared memory interfaces, such as UNIX systems, the shmget(2) and related System V IPC interfaces are used.

On Windows platforms, the use of system memory for the region files is problematic because the operating system uses reference counting to clean up shared objects in the paging file automatically. In addition, the default access permissions for shared objects are different from files, which may cause problems when an environment is accessed by multiple processes running as different users. See Windows notes or more information.

Security Considerations

When using environments, there are some security considerations to keep in mind:

  • Database environment permissions

    The directory used for the environment should have its permissions set to ensure that files in the environment are not accessible to users without appropriate permissions. Applications that add to the user's permissions (for example, UNIX setuid or setgid applications), must be carefully checked to not permit illegal use of those permissions such as general file access in the environment directory.

  • Environment variables

    Setting so that environment variables can be used during file naming can be dangerous. Setting those flags in BDB XML applications with additional permissions (for example, UNIX setuid or setgid applications) could potentially allow users to read and write containers to which they would not normally have access.

    For example, suppose you write a BDB XML application that runs setuid. This means that when the application runs, it does so under a userid different than that of the application's caller. This is especially problematic if the application is granting stronger privileges to a user than the user might ordinarily have.

    Now, if then the environment that the application is using is modifiable using the DB_HOME environment variable. In this scenario, if the uid used by the application has sufficiently broad privileges, then the application's caller can read and/or write containers owned by another user simply by setting his DB_HOME environment variable to the environment used by that other user.

    Note that this scenario need not be malicious; the wrong environment could be used by the application simply by inadvertently specifying the wrong path to DB_HOME.

    As always, you should use setuid sparingly, if at all. But if you do use setuid, then you should refrain from specifying for the environment open. And, of course, if you must use setuid, then make sure you use the weakest uid possible – preferably one that is used only by the application itself.

  • File permissions

    By default, BDB XML always creates container and log files readable and writable by the owner and the group (that is, S_IRUSR, S_IWUSR, S_IRGRP and S_IWGRP; or octal mode 0660 on historic UNIX systems). The group ownership of created files is based on the system and directory defaults, and is not further specified by BDB XML.

  • Temporary backing files

    If your BDB XML application is also using Berkeley DB databases, then you should pay attention to temporary backing files.

    If an unnamed database is created and the cache is too small to hold the database in memory, Berkeley DB will create a temporary physical file to enable it to page the database to disk as needed. In this case, environment variables such as TMPDIR may be used to specify the location of that temporary file. Although temporary backing files are created readable and writable by the owner only (S_IRUSR and S_IWUSR, or octal mode 0600 on historic UNIX systems), some filesystems may not sufficiently protect temporary files created in random directories from improper access. To be absolutely safe, applications storing sensitive data in unnamed databases should use the EnvironmentConfig.setTemporaryDirectory() method to specify a temporary directory with known permissions.