Orindasoft

JDBCWizard Web Service Generator Reference Manual

Using the DAO Factory Class

Topics

1. Using the DAO Factory Class
   
2. Advantages of the DAO Factory Class
   
3. Log File Management
   
4. Database Connection Management
   
5. Manual Connection Management
   
6. Java Session Bean Support
   
7. Working with the DAO Factory class
   
8. Creating an instance of the class
   
9. Obtaining and using a database access class
   
10. Releasing and reaquiring resouces
    
11. Extending the DAO Factory class
    
12. DAO Factory class methods
    

Using the DAO Factory Class

Advantages of the DAO Factory Class

 In step 4.3 of the JDBCWizard user interface you can create a single class called a "DAO Factory Class" that allows you to create instances of all your other generated classes and makes it easy to manage database connections and logging. The benefits of this class are explained below.

Log File Management

The DAO Factory class can be generated with any of the following logging mechanisms ready for use:

Logging Mechanism	Description	Prerequisites
JDBCWizard.s Text Log	Text log files are generated in  a specified directory. This mechanism  is useful if the DAO Factory class is being used in an environment without it's own logging mechanism.	com.orindasoft.pub classes or library in CLASSPATH "Log Name" is a valid directory
JDBCWizard.s Console Log	Messages are written to System.out and System.err. This is useful for prototypes and early stage development.	com.orindasoft.pub classes or library in CLASSPATH
Java 1.4 Logging	Messages are logged using java.util.logging	com.orindasoft.pub classes or library in CLASSPATH Java 1.4 or higher in use OBJavaLog.jar in CLASSPATH java.util.logging has been configured. "Log Name" is a dot seperated value that represents the DAO Factory class such as it's Java package name
Apache's Log4J	Messages are logged using Apache's Log4J	com.orindasoft.pub classes or library in CLASSPATH OBLog4JLog.jar in CLASSPATH Log4J JAR file in CLASSPATH. Log4J has been configured "Log Name" is a dot seperated value that represents the DAO Factory class such as it's Java package name

When the class is called with a default constructor an appropriate log object will be created.

Database Connection Management

The DAO Factory class postpones the creation of a Database Connection until it receives a request for a DAO object or the ejbActivate() method is called. There are four different ways to provide the DAOFactory class with a Connection:

Connection Mechanism	Description	Prerequisites
Hard Coded Connect String	JDBCWizard assumes that the value in the 'Connection Name' field is a valid connect string for Oracle's thin JDBC driver.	com.orindasoft.pub classes or library in CLASSPATH "Connection Name" is a valid thin driver connect string such as: jdbc:oracle:thin:ORINDADEMO/ORINDADEMO@localhost:1521:ORCL
JNDI used to get DataSource	JDBCWizard queries JNDI with the value in the 'Connection Name' field and expects to retrieve a DataSource object.	com.orindasoft.pub classes or library in CLASSPATH JNDI installed and configured
DataSource passed in at runtime	The generated class has a 'setDataSource' method that is used to give the class a Data Source.	com.orindasoft.pub classes or library in CLASSPATH A DataSource object.
oracle.jbo.server.DBTransaction	The generated class has a 'setDBTransaction' method that is used to give the class a.oracle.jbo.server.DBTransaction	com.orindasoft.pub classes or library in CLASSPATH An oracle.jbo.server.DBTransaction object Oracle's BC4J classes in the CLASSPATH Sun's collections.jar in the CLASSPATH (needed by BC4J).

In addition to providing a mechanism for initially creating connections the generated class provides methods that allow you to withdraw and assign connections to all the objects under the control of the DAOFactory class.

Manual Connection Management

JDBCWizard also allows you to manually pass in and withdraw Connection objects at runtime. This can be done either when you create the DAOFactory object by passing a Connection to the constructor or by calling the setConnection method before you access any of the classes controlled by the DAO. The method confirmConnection does not attempt to create a Connection if one has been provided already.
If no connection has been set before you attempt to use the DAOFactory class confirmConnection will be called and will attempt to create a Connection. It is therefore important that you do not provide a valid connect string or DataSource name when using the GUI if you will be handling Connection management yourself - you could end up connecting to the wrong database.

Java Session Bean Support

The DAOFactory class can optionally implement javax.ejb.SessionBean. Selecting this option results in the following methods being added to the class:

Method	Description
ejbCreate()	Required by classes that implement Session Bean. Does nothing in the case of DAOFactory.
setSessionContext()	Required by classes that implement Session Bean. Does nothing in the case of DAOFactory. Value passed in is stored in case DAOFactory class is extended by a class which needs Session Context information.
ejbActivate()	Calls confirmConnection() to obtain a database Connection
ejbPassivate()	Calls releaseResources() to dispose of any database Connections
ejbRemove()	Calls releaseResources() to dispose of any database Connections

Working with the DAO Factory class

Creating an instance of the class

Your DAO Factory class always has a null contructor so you can create an instance using code like this:

// Create DAO Factory com.mycompany.myprod.generated.DaoFactory theFactory = new com.mycompany.myprod.generated.DaoFactory.DaoFactory();

The generated class will open a log when started but will not attempt to get a database connection until it receives a request for a database access class.

Obtaining and using a database access class

Each database access class will have a matching method named get{ClassName}{ClassType}DAO(). The DAOFactory class does not create a new instance each time this method is called. The first call will create an instance which is then recyled when further requests for the DAO are received. The example below shows how to get an instance of a DAO class.




// Get list DAO com.mycompany.myprod.generated.plsql.simpleExamplesGetlists getLists = theFactory.getsimpleExamplesGetlistsPlSqlDAO();      // Call DAO's execute method getLists.executeProc(); // get data com.orindasoft.pub.ReadOnlyRowSet theRowSet = getLists.getParamPAircraftListing();

Releasing and reaquiring resouces

Because the DAOFactory class keeps a copy of each DAO instance it hands out it can withdraw and re-assign database connections as needed. When theDAOFactory class's 'releaseResources()' method is called it works its way through all the DAO classes it is responsible for and if they are active it tells them to release their database connections. This means that a single call to releaseResources() will affect all the objects originally created by that DAOFactory class. To reaquire database resources  you can call the method confirmConnection() will create a new connection and assign it to all instantiated DAO classes.

Extending the DAO Factory class

The generated DAOFactory class can be extended to provide additional functionality.

DAO Factory class methods

The table below lists the methods you can expect to find in a DAO Factory class and explains what they are for

Method Name	Purpose	Comment
Constructors
DaoFactory()	Default Constructor	The default constructor creates its own logging mechanism and will obtain a Connection when asked to return a DAO object.
DaoFactory(Connection, LogInterface)	Constructor that takes a Connection and LogInterface. Intended for development.
DaoFactory(LogInterface)	Constructor that takes a LogInterface
Database Resource Methods
releaseResources()	Releases database connection	Part of OracleResourceUser Interface
setConnection()	Re-establishes database connection
HasResources()	Returns 'true' if database connection is being used
confirmConnection()	Creates a database Connection if needed	Will inform all existing DAO classes of new DB connection. Also called whenever a DAO class is requested.
setCommitOnRelease	Flag that says whether this class should commit connections when releaseResources() is called	Defaults to 'true'
setCloseOnRelease	Flag that says whether this class should close connections when releaseResources() is called	Defaults to 'true'
DAO Methods
getTableNameTableDAO()	These methods either return the existing instance of the DAO class or create a new instance and return it.	The DAO Factory class will never create two instances of the same DAO class. Calling one of these methods will also make the DAO Factory class call confirmConnection() to make sure it has a DB connection
getProcedureNamePlSqlDAO()
getSqlFileNameSqlDAO()
getSequenceNameSequenceDAO()
Option Specfic Methods
setDBTransaction()	Allows DAOFactory class to use an Oracle JBO DBTransaction object for Connection management	Only present when you specifiy "oracle.jbo.server.DBTransaction" in step 4.3. If this method is created it must be called before calling confirmConnection() or a getDAO() method.
setDataSource()	Sets the DataSource to be used by the DAOFactory class.	Present when you specifiy either "JNDI Used to get Datasource" or "Datasource provided at runtime" in step 4.3. If JNDI is not in use then this method must be called before calling confirmConnection() or a getDAO() method.
setOracleTimeZoneName()	Sets the Oracle time zone.	Used when working with TIMESTAMP WITH LOCAL TIMEZONE and its  Java representation oracle.sql.TIMESTAMPLTZ