Who We Are
User Guides
Release Notes
Project on SourceForge
To Do List
Mailing Lists
Component Guides
Base Services
Business Data
Client Controller
Data Access
Data Domain
Java Class Generator
Data Parser
Property Tree
XML Wrapper
UI Framework
Data Access Component

The data access component, of Arch4J, is a abstraction layer above JDBC so that the more mundane JDBC code is all located in one place. The developer no longer needs to get the connection, execute the sql, handle the result set, and close the objects. All that the developer needs to do is create the sql to be executed and build a Listener to parse the result set.

This layer can be used to support a sophisticated persistence layer of your own making, or provide the makings of a simple persistence model for more straightforward applications. Or, if you are buying a persistence capability, you can use this to create fast read-only capabilities, or ditch it altogether.

Get Started

If you are installing as part of the full Arch4J distribution, you need to put the arch4j.jar file into your classpath.
If you are only interested in the data access component, you need the base.jar and arch4j_dataaccess.jar in your classpath.
You will also need any third party JDBC driver in your classpath.


The data access model is designed around having a method invoked for each row in the result set from a database query. You will need to create a ResultSetVisitor instance that contains the code required to process each row.

The reason for doing things this way is to move all of the JDBC code into a single class that can manage all of the low level JDBC Java code for you

How To

In order to use the Database Manager, you will need to do four things:

  1. Configure the database properties in the dataaccess.properties file.

  2. Get a reference to a DatabaseManager using the DataAccessProvider class.

  3. Create a ResultSetVisitor instance to process the results of the sql.

  4. Use the DatabaseManager from step 2 to execute the sql and the ResultSetListener
    from step 3 to process the results.

Property File Configuration

The property file name is dataaccess.properties. This is where you define logical names for your database connections and set up the physical connection information to get to the data.

Property Name Property Value Required
defaultConnection <logical_database_name> Yes, if requesting default connections.
<logical_database_name>.driver <JDBC_driver_class_name> Yes
<logical_database_name>.url <JDBC_connection_url> Yes
<logical_database_name>.username <database_user_name> No
<logical_database_name>.password <database_user_password> No

The driver, url, username, and password pattern may be duplicated as many times as you want to set up as many separate logical database names as you want. You pick the logical name and then use it to define the physical characteristics of the connection. One of the logical names can be set as the default connection to use.


Here is a sample property file for an Oracle connection:

Acessing the DatabaseManager

To get a reference to the DatabaseManager, you need to use the DataAccessProvider class. This class uses the singleton pattern. To get the instance of the provider, use the getProvider() method.

You can then get get an instance of the DatabaseManager using either the getDefaultManager() or one of the getManagerFor methods (see JavaDoc).


Getting instance by name:
DatabaseManager manager = DataAccessProvider.getProvider().getManagerFor("myMainDatabase");

Getting instance by name and using our own userid, and password:
DatabaseManager manager = DataAccessProvider.getProvider().getManagerFor("myMainDatabase", "sa", "");
Creating a ResultSetVisitor

A ResultSetVisitor is used to process each row of a result set. There are several visitors out of the box as well as the ResultSetAdapter class that provides default implementation of the ResultSetVisitor interface. The adapter class may be sub-classed and then you only have to implement the method(s) you are interested in. These classes are in the listeners sub-package.


Create new listener as anonymous inner class. This inner-class will inherit from the ResultSetAdapter class
ResultSetCounter visitor = new ResultSetAdapter() {
  public boolean processNextRow( ResultSet aResultSet ) {

   Code to process a single row...


Other visitors that have been created for your convienience include:
ResultSetCache:   May be used to store data from the result set without holding the connection open or to pass database results around.
ResultSetCounter: Used to obtain the number of items returned without having the overhead of parsing all of the data.
ResultSetPrinter:   Used to display the results out to the System.out stream.
Execute the query and process the results

Once you have a reference to the DatabaseManager and a Visitor to process the results, you can execute the SQL and process any results.


Query with parameters:
String selectSQL = "select TST_DATE, TST_TEXT, TST_INTEGER, TST_FLOAT" +
                    " from TST_FOO where TST_INTEGER = ?";
Vector parameters = new Vector();
manager.select(selectSQL, parameters, visitor);

Arch4J is hosted by

SourceForge Logo

Copyright © 2001-2004 SpiderLogic, a service of Wipfli Ullrich Bertelson LLP.