Geronimo's Embedded Derby System

Note that this documentation is based upon changes that were made after the M3 build.

Geronimo's org/apache/geronimo/!SystemDatabase configuraton starts the DerbySystem GBean, DerbyNetwork GBean, JDBCTransactionalThreadPooledTimer GBean, JDBCNonTransactionalThreadPooledTimer GBean, and defines the SystemDatasource that is intended for use by Geronimo and associated components (e.g. ActiveMQ). The SystemDatasource is not intended for direct use by J2EE applications.

Refer to the DerbySystem GBean and DerbyNetwork GBean topics for further information on configuring the embedded Derby system.

Configuring a Server-Wide Datasource under the Embedded Derby System

The following command deploys the database plan file shown below using the Derby connector.

java -jar bin/deployer.jar deploy mydatabase-plan.xml \
               repository/geronimo/rars/geronimo-derby-connector-1.0-SNAPSHOT.rar

Note: The repository/geronimo/rars/geronimo-derby-connector-1.0-SNAPSHOT.rar file did not exist in the M3 build.

Sample database plan file:

<?xml version="1.0" encoding="UTF-8"?>

<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector"
    version="1.5"
    configId="com/mycompany/MyDatabase"
    parentId="org/apache/geronimo/SystemDatabase"
>

    <resourceadapter>
        <outbound-resourceadapter>
            <connection-definition>
                <connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface>
                <connectiondefinition-instance>
                    <name>jdbc/MYDB</name>
                    <config-property-setting name="UserName">MYAPP</config-property-setting>
                    <config-property-setting name="Password">myappPassword</config-property-setting>
                    <config-property-setting name="DatabaseName">MYDB</config-property-setting>
                    <config-property-setting name="CreateDatabase">create</config-property-setting>
                    <connectionmanager>
                        <xa-transaction>
                            <transaction-caching/>
                        </xa-transaction>
                        <single-pool>
                            <max-size>10</max-size>
                            <blocking-timeout-milliseconds>5000</blocking-timeout-milliseconds>
                            <match-one/>
                        </single-pool>
                    </connectionmanager>
                    <global-jndi-name>MYDB</global-jndi-name>
                </connectiondefinition-instance>
             </connection-definition>
        </outbound-resourceadapter>
        
    </resourceadapter>

</connector>

FIXME - need to confirm whether the current database schema for the above embedded connection will be MYAPP. See http://incubator.apache.org/derby/faq.html#schema_exist

Creating tables in an Embedded Derby Database via Derby's ij tool (whilst Geronimo is running)

Derby does not currently provide a network JDBC driver (although this will change soon), therefore you must download the IBM DB2 JDBC Universal Driver, for Cloudscape/Derby (db2jcc_for_derby.zip - 1.03MB) from http://www-106.ibm.com/developerworks/db2/downloads/jcc/

The following jars need to be on the classpath:

db2jcc.jar
db2jcc_license_c.jar

Currently Geronimo doesn't include the derbytools JAR file that contains the ij utility http://issues.apache.org/jira/browse/GERONIMO-631. So download the file http://cvs.apache.org/repository/incubator-derby/jars/derbytools-10.0.2.1.jar into the geronimo/repository/incubator-derby/jars directory.

Assuming you are in the geronimo root directory, create a database using Derby's ij tool (UNIX example):

java -cp db2jcc.jar:db2jcc_license_c.jar:\
         repository/incubator-derby/jars/derbytools-10.0.2.1.jar \
     -Dij.driver=com.ibm.db2.jcc.DB2Driver -Dij.user=MYAPP \ 
     -Dij.password=myappPassword -Dij.protocol=jdbc:derby:net://localhost:1527/ org.apache.derby.tools.ij
ij version 10.0
ij> connect 'MYDB;create=true';
ij> CREATE TABLE products(name CHAR(30), price INTEGER);
0 rows inserted/updated/deleted
ij> disconnect;
ij> exit;

The above commands will result in:

the MYDB database being created (if it hasn't already). If the database wasn't already created, the directory "MYDB" is created for the database under the geronimo\var\derby (Derby system) directory.
the products table is created in the MYDB database.

Note that the above ij command will only work on the localhost with the standard DerbyNetwork GBean configuration. FIXME - add more information about this (preferably under the DerbyNetwork GBean topic.