Contents

Overview

The DerbySystem GBean instantiates a single instance of the Derby database engine and the environment in which it runs. In Derby terminology this is known as a "Derby System". Refer to the Derby Developer's Guide for detailed information on a Derby System.

Refer to Database Configuration for further information on Geronimo's database usage.

Lifecycle

The DerbySystem GBean is started by the org/apache/geronimo/SystemDatabase configuration, that is a child of the org/apache/geronimo/Server configuration.

Note for developers: The plan for the org/apache/geronimo/SystemDatabase configuration is located at geronimo/modules/assembly/src/plan/system-database-plan.xml

GBean Attributes

derbySystemHome

The derbySystemHome attribute of the DerbySystem GBean sets the derby.system.home environment variable that specifies Derby's system directory.

In the default configuration, the derbySystemHome attribute of the DerbySystem GBean is set to var/derby that is relative to the geronimo directory.

When Derby is initialised, it looks in its system directory for an optional derby.properties configuration file, and also attempts to find existing databases (each in a subdirectory of the system directory) that are in its system. Derby also creates new databases as subdirectories of the system directory. If you specify a directory in the derbySystemHome attribute at startup that does not exist, Derby will create the directory.

Note that if you change the value of the DerbySystem GBean's derbySystemHome attribute whilst Derby is running, the change does not take effect until the DerbySystem GBean is restarted.

Derby log files

A derby.log file will be created in the Derby system directory. The amount of information logged to this file can be controlled via the derby.properties file (read below).

Further configuration of Derby

A derby.properties file can optionally be placed in the Derby system directory to further control the operation of the Derby System. Refer to the Tuning Derby manual for further information on the Derby properties.

The following is a sample derby.properties file:

#
#Security settings (read Derby documentation before playing with this)
#
#derby.connection.requireAuthentication=true
#derby.authentication.provider=BUILTIN

# User and pswd list for BUILTIN authentication provider 
#
#derby.user.john=johnspassword
#derby.user.system=manager

###############################
# Derby Logging Properties
###############################

# append to derby.log when server is booted
derby.infolog.append=false

# log connections and disconnections
derby.drda.logConnections=true

###############################
# Problem Diagnosis Properties
###############################

# write a detailed list of locks when a transaction times out
derby.locks.deadlockTrace=true

# Report all errors to the derby.log file.
derby.stream.error.logSeverityLevel=0

# Log SQL statements to aid problem diagnosis
derby.language.logStatementText=true

# Network Server Tracing
#derby.drda.traceAll=true