Easy DB setup with Apache Derby - RIFE

Apache Derby is probably your best choice for getting a database up and running ASAP, in order to get the Friends tutorial working, and otherwise try out Rife.

Here are some notes to get you going. These were arrived at using Derby 10.1.2.1-bin with Rife 1.3 and JDK 5 and Apache Jakarta Tomcat 5.5.12 on Debian testing, and with the help of the Rife users' mailing list.

These instructions describe using Derby in embedded mode. What you lose in multi-application access you gain in utter simplicity. For example, when Derby is used this way, you do not need to configure Derby as a resource in Tomcat's configuration file conf/server.xml .

The jarfiles you need are derby.jar and derbytools.jar . Due to classloader peculiarities, don't copy them to your application's web/WEB-INF/lib/ subdirectory, or to Tomcat's shared/lib/ directory. Tomcat's common/lib/ directory works, and probably common/endorsed/ does too.
Rife's QueryManagers automatically store fields in the database that have matching getters and setters. With Derby, the names of such variables may not begin with an underscore "_"

Finally, there is the matter of JDBC URL's and your app's configuration file WEB-INF/classes/rep/datasources.xml . The <user> and <password> tags can cause problems, so the following is a fully functional datasources.xml :

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE datasources SYSTEM "/dtd/datasources.dtd">
<datasources>
    <datasource name="derby">
        <driver>org.apache.derby.jdbc.EmbeddedDriver</driver>
        <url>jdbc:derby:rife</url>
        <poolsize>5</poolsize>
    </datasource>
</datasources>

Comment(Odo): I have to provide empty <username> and <password> tags to get things working and with Jetty and Eclipse the Jars should be in jetty/lib and in the classpath.
Naturally then, the name of the datasource, "derby", must be specified in your file WEB-INF/classes/rep/config.xml :

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE config SYSTEM "/dtd/config.dtd">
<config>
    <param name="DATASOURCE">derby</param>
    [..]

Next, you may wish to create your new database outside of the servlet container. Do this by going to a directory which will be your "Derby system home". In these examples, it is /opt/derbyhome . With the two Derby jarfiles on your CLASSPATH, and the Derby ij command on your PATH, enter the ij command, get its prompt, and create the database (in this case, named "rife") like so:

/opt/derbyhome >> ij.ksh
ij version 10.1
ij> connect 'jdbc:derby:rife;create=true';
ij> exit;
/opt/derbyhome >> ls rife/
log/  seg0/  service.properties

You now have a Derby database! Now you must make its location known to Rife, and you do this by using one of two basic forms of JDBC URL; your choice depends upon how much deployment flexibility you need. As previously stated, the directory where you ran ij is your Derby system home. If your database will always be in this location, no matter what machine your app is running on, then you can hardcode its location in the JDBC URL, like so:

[in file datasources.xml]
<url>jdbc:derby:/opt/derbyhome/rife</url>

If instead you need to define the location of the database to your application at startup time, you can do it like so:

1. In the JDBC URL, specify the database by name only:

<url>jdbc:derby:/opt/derbyhome/rife</url>

2. Define the environment variable derby.system.home to Tomcat by modifying JAVA_OPTS before you start Tomcat (again assuming that the directory in question is /opt/derbydb):

>> JAVA_OPTS="-Dderby.system.home=/opt/derbydb $JAVA_OPTS"

3. You can verify that the variable is properly defined to Rife by using the following code, which can (for instance) be placed in your Rep Participant which does startup:

import com.uwyn.rife.rep.Rep;
import com.uwyn.rife.rep.BlockingParticipant;
import com.uwyn.rife.ioc.HierarchicalProperties;

public class MyParticipant extends BlockingParticipant {
     protected void initialize() {
        [..]
        HierarchicalProperties PP = Rep.getProperties();
        System.out.println("derby.system.home: " +
             PP.getValueString("derby.system.home"));
        [..]

Enjoy!

F.Baube
fbaube ,at, saunalahti.fi