Warehouse Common Java Components

Modified: $Date: 2006/07/06 20:17:13 $

Overview
How to Build the Components
How to Use the Components
Testing

JDBC Issues

Overview

Several of the Java-based loaders (GenBank, Uniprot, Enumerations) use a set of common reusable components located in the common/ directory of the Warehouse distribution..  These components consist of classes that can manage to the connection to the Warehouse database and classes that represent a Java binding of the database schema.  The Javadoc API documentation can be viewed here.

How to Build the Components

The common components are packaged into a single jar file (dist/warehouse-{version}.jar) that is included in the classpath by the client loaders.  Each client loader build file calls the build target of the common build file before compiling or executing the loader source code.

How to Use the Components

A simple example of how to use the common Java components to access the Warehouse is provided at com.sri.biospice.warehouse.database.WarehouseExample.  The Warehouse class is a Singleton and needs to be initialized just once via WarehouseManager.initWarehouse().  Thereafter, the Warehouse class may be accessed via the static factory method WarehouseManager.getWarehouse(). 

The WarehouseManager constructs either a MySQLWarehouse, OracleWarehouse, or NullWarehouse object, depending on the initialization parameters.  Although the NullWarehouse class is intended to be used as a mock object (a "null" database connection), many of the schema classes rely on being able to obtain real TableMetaData from a real database.  Hence the NullWarehouse cannot be used in a running application at this time.  (It is intended to be used for testing and running loaders without requiring a true database connection.  We intend to remove this restriction in the future, as time permits.)
Table classes
The classes in com.sri.biospice.warehouse.database.table represent single entries in a single column in a single table.  These classes know how to set their respective parameters in a PreparedStatement used to insert data into the schema tables.  In addition, these classes provide error checking.  For example, the StringColumn class can check that the value to be inserted into a column does not exceed the allowed column size.
Schema classes
The classes in com.sri.biospice.warehouse.database.schema and subpackages represent a Java binding of the Warehouse schema.  Each Warehouse table is represented by a single Java class, with accessor methods corresponding to the columns of the table.  For example, the Protein class has setName() and getName() methods.  All inserts into tables are performed via pre-compiled JDBC PreparedStatements.  The tables may represent new entries into a table or existing entries in the Warehouse.  Methods are provided to store, load, update, or delete an entry in a table.  Each instance of a schema class represents one row in one table.

The schema classes may be divided into three categories:  object tables, linking tables, and other tables.  The object table classes implement the ObjectTable interface and represent all tables that have a WID column (tables that represent real objects in the Warehouse schema).  Each linking table (a table that defines a linking relationship between two object tables) is defined by its own class, but clients may use the more convient LinkingTables class, which provides methods for each type of linking table.  The remaining tables do not have any other common defining features.

The schema classes are kept up-to-date with the Warehouse schema.  Any change to the schema definition (change in number or type of columns) requires a corresponding change to the Java class representing that table.  Any change to the listing of allowed enumerated values (values loaded into the Enumeration table by the Enumerations loader) require a corresponding change in the Java source code for that class.

Testing

The common java components are covered by a set of unit and functional tests located in the common/test/ directory.  Most of the unit tests require a live connection to an instance of the warehouse.  Many of the unit tests DO modify the data in the warehouse database, so be sure the testing parameters are set to connect to a database designated for testing.  The connection parameters for the unit tests must be defined in common/test/unittest.properties.  A template file is provided at common/test/unittest.properties.template.  In particular, the EnumeratedValues_Test checks to see that the number and type of enumerated values defined for each table (Java class) matches what is loaded in the Enumeration table of the database.

The tests are run by first editing the unittest.properties file and then invoking the test Ant target.


JDBC Issues

The Java Warehouse loaders all support both Oracle and MySQL Database Management Systems (DBMS).  In most cases, the warehouse source code uses DBMS-neutral (generic JDBC) code.  There are two areas where the two DBMSs must be handled differently: connection parameters and the selection of WIDs (Warehouse Identifiers). 

Developers using JDBC to connect to a number of different DBMSs should be aware of the limitations and known issues of each JDBC driver implementation.