|
|
|
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.
|
| Overview |
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:
- Configure the database properties in the dataaccess.properties file.
- Get a reference to a DatabaseManager using the DataAccessProvider class.
- Create a ResultSetVisitor instance to process the results of the sql.
- 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.
Examples
Here is a sample property file for an Oracle connection:
defaultConnection=myMainDatabase
myMainDatabase.driver=oracle.jdbc.driver.OracleDriver
myMainDatabase.url=jdbc:oracle:thin:@localhost:1521:myOracleDB
myMainDatabase.username=user
myMainDatabase.password=secret
|
|
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).
Examples
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.
Examples
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.
Examples
Query with parameters:
String selectSQL = "select TST_DATE, TST_TEXT, TST_INTEGER, TST_FLOAT" +
" from TST_FOO where TST_INTEGER = ?";
Vector parameters = new Vector();
parameters.add(testInteger);
manager.select(selectSQL, parameters, visitor);
|
|
|
