JDBCWizard Web Service Generator Reference Manual

Public Library

Topics

Using the com.orindasoft.pub Java Class Libraries
Accessing Data from Cursors
Using the QueryStatement class
Using the StatsInterface Performance Metrics Interface
Using the LogInterface Logging Interface
Using the OracleResourceUser Interface

Using the com.orindasoft.pub Java Class Libraries

Generated code uses the com.orindasoft.pub class libraries for logging and managing retrieved data. There is a class library version for each Oracle release supported by JDBCWizard and two additional libraries used for logging. The libraries are located in the following directories:

*Location...*	*Library...*	*Description...*
InstallDir/lib/815	OrindaBuildpub815.jar	Compiled Java Class Library for use with Oracle 8.1.5
InstallDir/lib/816	OrindaBuildpub816.jar	Compiled Java Class Library for use with Oracle 8.1.6
InstallDir/lib/817	OrindaBuildpub817.jar	Compiled Java Class Library for use with Oracle 8.1.7
InstallDir/lib/901	OrindaBuildpub901.jar	Compiled Java Class Library for use with Oracle 9.0.1
InstallDir/lib/920	OrindaBuildpub920.jar	Compiled Java Class Library for use with Oracle 9.2.0
InstallDir/lib/1010	OrindaBuildpub1010.jar	Compiled Java Class Library for use with Oracle 10.1.0
InstallDir/lib/1020	OrindaBuildpub1020.jar	Compiled Java Class Library for use with Oracle 10.2.0
InstallDir/lib/1110	OrindaBuildpub1110.jar	Compiled Java Class Library for use with Oracle 11.1.0
InstallDir/lib/1120	OrindaBuildpub1120.jar	Compiled Java Class Library for use with Oracle 11.2.0
InstallDir/lib	OBJavaLog.jar	Compiled Java Class Library that contains a version of com.orindasoft.pub.LogInterface that works with Java 1.4's java.util.logging package.
InstallDir/lib	OBLog4JLog.jar	Compiled Java Class Library that contains a version of com.orindasoft.pub.LogInterface that works with Log4J.

If you license a full version of JDBCWizard the library source code is located in the following directories:

*Location...*	*Zip File...*	*Description...*
InstallDir/src	OrindaBuildpubApi815.zip	Java Source Library for use with Oracle 8.1.5
InstallDir/src	OrindaBuildpubApi816.zip	Java Source Library for use with Oracle 8.1.6
InstallDir/src	OrindaBuildpubApi817.zip	Java Source Library for use with Oracle 8.1.7
InstallDir/src	OrindaBuildpubApi901.zip	Java Source Library for use with Oracle 9.0.1
InstallDir/src	OrindaBuildpubApi920.zip	Java Source Library for use with Oracle 9.2.0
InstallDir/src	OrindaBuildpubApi1010.zip	Java Source Library for use with Oracle 10.1.0
InstallDir/src	OrindaBuildpubApi1020.zip	Java Source Library for use with Oracle 10.2.0
InstallDir/src	OrindaBuildpubApi1110.zip	Java Source Library for use with Oracle 11.1.0
InstallDir/src	OrindaBuildpubApi1120.zip	Java Source Library for use with Oracle 11.2.0
InstallDir/lib	OBLog4JLog.jar	Compiled Java Class Library that contains a version of com.orindasoft.pub.LogInterface that works with Log4J.
InstallDir/src	OBJavaLogSrc.zip	Java Source for com.orindasoft.pub.JavaLog (Java 1.4 logging)

JavaDoc Documentation for com.orindasoft.pub

Click here for a full and detailed Application Programming Interface

Note: Orinda Software can not guarantee that future releases and builds of JDBCWizard will not make changes to the com.orindasoft.pub java class libraries. We will attempt to avoid changes which would break existing applications.

Accessing Data from Cursors

Use com.orindasoft.pub.ReadOnlyRowSet to access data from cursors.

Usage

Regard cursors as two-dimensional arrays with rows and columns. ReadOnlyRowSet uses a concept of a current row.
Use the first(),last(),next() and setRowNumber() methods to change the current row. The current row always starts at zero, consistent the handling of arrays.
When you select a row, you retrieve the contents of columns by position or name. Use a get method to perform data type conversions.

Methods

Method Name	Purpose
Navigation Methods
first()	Move to row #0
last()	Move to last row
setCurrentRowNumber()	Move to a given row
size()	How many rows are in this rowset
width()	How many columns there are in this rowset
*Access Methods*
get[type]()	Get column as data type [type] - e.g., getFloat() returns a float variable.
get[type]Obj()	Get column as data type [type] where [type] is an object - e.g., getFloatObj returns a Float object.
isNull()	Returns 'true' if a column is null.
*Miscellaneous Methods*
checkColumnName()	Checks that a column name is present in the rowSet
getColumnId()	Gets ID of a named column
getColumnName()	Gets name of a column using ID
getColumnNamesAsString()	Returns a String containing the column names
getColumnNamesAsStringArray()	Returns a String Array containing the column names
getRowAsString()	Gets current row as a String
hitMemLimit()	Returns 'true' if retrieving data stops because the JVM runs out of memoryy
hitRowLimit()	Returns 'true' if retrieving data stops because the row limit specified in the constructor is exceeded.
setExpireDate()	Used by QueryStatement's caching mechanism
getExpireDate()	Used by QueryStatement's caching mechanism

JavaDoc Documentation for ReadOnlyRowSet

Click here for a full and detailed Application Programming Interface

Using the QueryStatement class

The com.orindasoft.pub.QueryStatement is a reusable query object that caches the results of queries and continues to function without a JDBC Connection object.

To create a QueryStatement:

Use an SQL Query, a Connection and a LogInterface object.

QueryStatement cachedQuery

= new QueryStatement("SELECT f.airline_name, count(*) howmany "

                     + "FROM flights f "

                     + "WHERE f.aircraft_type = ?"

                     + " GROUP BY f.airline_name"

                     + " ORDER BY count(*) DESC "

                   , theLog, theConnection);

Pass the QueryStatement any required parameters.

Execute the class. The results is a ReadOnlyRowSet:

cachedQuery.setParam(1,"Boeing 747");

com.orindasoft.pub.ReadOnlyRowSet cachedList = cachedQuery.execute();

To execute the same query with a different value for the parameter re-use the QueryStatement Object:

   


cachedQuery.setParam(1,"Boeing 727")

com.orindasoft.pub.ReadOnlyRowSet cachedList2= cachedQuery.execute();


cachedQuery.setParam(1,"DC-10");

com.orindasoft.pub.ReadOnlyRowSet cachedList3= cachedQuery.execute();


cachedQuery.setParam(1,"Concorde");

com.orindasoft.pub.ReadOnlyRowSet cachedList4= cachedQuery.execute();

Caching QueryStatement results

The QueryStatement class uses a built-in cache. The number of stored query results or the required duration for storing the results determines the cache size.

To turn on caching:

Call the setCacheSeconds method with a non-zero value.

To control the size of the cache:

Call the setCacheRows method with a non-zero value.

The execute method checks the cache for a ReadOnlyRowSet with the same set of parameters before executing the database query.

cachedQuery.setCacheSeconds(600);

cachedQuery.setCacheRows(100);

// Issue query with new parameter - Database is accesed and results

// cached.

cachedQuery.setParam(1,"Lockheed Tristar");

com.orindasoft.pub.ReadOnlyRowSet cachedList5 = cachedQuery.execute();

// Issue same query again - same ReadOnlyRowSet is returned without the

// database being accessed.

cachedQuery.setParam(1,"Lockheed Tristar");

com.orindasoft.pub.ReadOnlyRowSet cachedList6 = cachedQuery.execute();

Purging the cache

The cache will replace expired ReadOnlyRowSet queries. The QueryStatement replaces it with a fresh query result from the database.

To periodically purge the cache of expired elements:

Call the purgeExpiredCacheEntries(int howManyMilliseconds) method. Specify the length of the purge operation using the howManyMilliseconds parameter.

-Or-

Call the purgeUnderusedCacheEntries(int minAcceptableReuses) method. Specify the used query using the using the minAcceptableReuses parameter.

// Spend 1.5 seconds looking for and deleting expired

// cache entries

CachedQuery.PurgeExpiredCacheEntries(1500);

// spend 2.3 seconds looking for and deleting cache entries that

// have never been used after their first retrieval

CachedQuery.purgeUnderusedCacheEntries (2,2300);

Using the StatsInterface Performance Metrics Interface

JDBCWizard tracks the time used for parsing, executing and retrieving data operations.

To obtain JDBCWizard performance metrics:

Select the Maintain Usage Statistics check box in the 3. Code Options screen.

The performance metrics methods and variables are standardized by the StatsInterface interface. The available methods are:

Method Name...	Purpose...
getParses()	Returns number of times statement has been parsed.
getParseTime()	Returns total elapsed time in milliseconds spent parsing.
GetExecutions()	Returns number of times the statement has been executed
GetExecutionTime()	Returns total elapsed time in milliseconds spent executing statement on server.
GetRetrievalTime()	Returns total elapsed time in milliseconds spent retrieving records.
GetReleases()	Returns number of times the Connection has been released
GetErrors()	Returns number of times the Connection has been re-established
resetStatsCounters	Reset all counters to zero.

Generate statistics during the development of an application. When application development is complete, regenerate the code without statistics.

To compare statistics between different classes use StatsInterface and pass the results to a logging routine:

myLog.info("Exec Time = " + ((StatsInterface)myClass).getExecutionTime());

myLog.info("Exec Time = " + ((StatsInterface)myOtherClass).getExecutionTime());

Using the LogInterface Logging Interface

LogInterface provides a logging interface to integrate JDBCWizard with other development environments. The interface supports five types of messages:

Message Type...	Description...
Debug	A message normally used for testing of programs under development. Turn the message on and off using debugOn and debugOff methods.
Info	Screen information seen by the user while the program is working.
Warning	Indicate that the program is not performing as expected or is about to lead to a further error.
Error	An error that leads some loss of functionality, but the program functions after user intervention
systemError	A very serious program error that leads to a complete loss of functionality. The user cannot continue and the program eventually crashes.

Each message has two methods:

A simple method that uses the message text as the sole parameter.
A detailed method that allows the developer to specify the following:
- isModal: To display a modal window.
- isLogged : To log of a message to a file or another persistent storage mechanism.

Use the following methods to manage log files on your computer:

flush(): To flush any written log files.
getCurrentLogFile(): To return the name of the current log file.

The com.codespooks.pub package comes with the following full and partial implementations of LogInterface:

Java Class...	Description...
GenericLog	Partial implementation of LogInterface that composes error messages but leaves the actual logging to other classes.
TextLog	A full implementation of LogInterface. Use TextLog as a logging mechanism for large volumes of data over a protracted period. Log files are stored in their own dedicated directory structure.
UiLog	This extends TextLog and uses a javax.swing.JLabel field to display messages. It also extends and logs modal messages if requested.
ConsoleLog	This is a lightweight implementation of LogInterface. It uses standard output for information messages and errors and not do modal messages or log messages.
JavaLog	This implementation integrates LogInterface with Java 1.4's java.util.logging package. It is supplied as a separate JAR file - OBJavaLog.jar
Log4JLog	This implementation integrates LogInterface with Apache's Log4J. It assumes you have log4j-1.2.8.jar or a compatible JAR file in your classpath. It is supplied in a seperate JAR file - OBLog4JLog.jar

Using the OracleResourceUser Interface

The OracleResourceUser interface provides a mechanism for keeping track of objects that are using Oracle Resources such as Connection objects. All the objects in a your application that implement this interface can be added to a vector or a similer data structure. When the time comes to free Oracle resources the class can then iterate through the vector of OracleResourceUser and get them to free their resources. OracleResourceUser consists of the following two methods

Method Name	Description
hasResources()	Used to tell if the object is using Oracle resources. Returns `true` if the objects holds an open PreparedStatement, ResultSet or similer resource.
releaseResources()	Used to tell an object to release its Oracle resources. This method never throws an exception. If releasing the resource will create problems they should be dealt with by the implementing class, not escalated to the calling class. Returns `true` if the objects held an open PreparedStatement, ResultSet or similer resource.