The Orindabuild reference manual
Topics
- Setting
your Classpath
- Importing Classes
- Implementing
com.orindasoft.pub.LogInterface
- Log into the
database and get a Connection object
- Creating a
Generated Class
- Calling
setParamXXXX Methods for Input Parameters
- Calling the
executeProc() Method
- Calling
getParamXXXX Methods for Output Parameters
- Retrieving
Sequence Values
- Retrieving
Cursors
- Generated
Procedure Call and SQL statement Methods
- Additional
generated SQL Class Methods
- Generated
Sequence Access Methods
- Generated Table
Classes
- Table Manager
Class Methods
- Generated SQL
Class Methods
Using Code Generated by OrindaBuild
This section explains how to use your generated Java code if you aren't
using a
DAO
Factory class or
Web
Services classes. Follow the steps
and examples. You can also refer to the
detailed
example for additional information.
Setting your Classpath
In order to use OrindaBuild generated code you need to make sure the
following files are in your Classpath:
- An Oracle JDBC Driver
- A copy of the com.orindasoft.pub library
Which files you use will depend on which version of Oracle you are
working with. See the
Library
manual section for more information.
Importing Classes
- Import the generated package to use its classes:
import com.yourcompany.yourproject.sql.*;
import com.yourcompany.yourproject.plsql.*;
import com.yourcompany.yourproject.sequence.*;
import com.yourcompany.yourproject.table.manager.*;
import com.yourcompany.yourproject.table.instance.*;
|
- Import the OrindaSoft Public package containing the that
implement StatsInterface and LogInterface classes:
import
com.orindasoft.pub.*;
|
- Import Java's SQL package:
- Import the Oracle JDBC driver. If you are accessing an Oracle
JDBC driver prior to version 9.0.1 you need to import
"oracle.jdbc.driver.*". From 9.0.1 onwards you import "oracle.jdbc.*":
Implementing com.orindasoft.pub.LogInterface
All generated classes use an instance of
com.orindasoft.pub.LogInterface to log messages and errors.
You can implement the LogInterface Interface in your own logging
mechanism.
com.orindasoft.pub.LogInterface theLog;
theLog = new TextLog("C:\\Log");
|
Creating a Connection Object
Log in to your database and create a connection object.
In the following example, generated SQLExceptions pass into the error
method of theLogInterface class.
//First register the driver
try
{
Class.forName("oracle.jdbc.driver.OracleDriver");
}
catch (ClassNotFoundException e)
{
theLog.syserror("Oracle Driver not found " + e);
System.exit(1);
}
// Then try and create a connection object
try
{
theConnection =
(OracleConnection)DriverManager.getConnection (
"jdbc:oracle:thin:@" + "192.168.0.18"
+ ":" + "1521"
+ ":" + "DB920",
"ORINDADEMO", "ORINDADEMO");
// By default JDBC drivers commit automatically. Turn this off...
theConnection.setAutoCommit(false);
}
catch (java.sql.SQLException e)
{
theLog.error(e);
}
|
Creating instance of a Generated Class
Generated classes use a Connection and a LogInterface constructor.
example1 = new
OrindaBuild Example1(theConnection, theLog);
|
Calling setParamXXXX Methods for Input Parameters
Each input parameter has one or more set methods, depending on the
underlying data type. Number parameters have one method for every
numeric Java data type.
example1.setParamAParam(42);
example1.setParamDateA(new java.util.Date(2001,11,2));
example1.setParamDateB(System.currentTimeMillis());
|
Calling the executeProc(), executeCall() or executeQuery() Method
For Procedures and SQL Statements
The method that calls your statement differs depending on the statement
type.
Statement
Type
|
Method
Name
|
Returns
|
SQL Query
|
executeQuery()
|
ReadOnlyRowSet
|
Sequence Access
|
getNext()
|
long
|
PL/SQL Procedure or Function
|
executeProc()
|
|
Other SQL Statement
|
executeCall()
|
|
In the example below the executeProc() method of your generated class
executes the procedure and unloads any output parameters. The method
generates errors as instances of the com.orindasoft.pub.CSException
class:
try
{
example1.executeProc();
}
catch (CSException e)
{
theLog.error(e);
}
|
In this example below the executeQuery() method of your generated class
returns the result of a query as a ReadOnlyRowSet. The method generates
errors as instances of the com.orindasoft.pub.CSException class:
try
{
normalQuery sqlFile = new normalQuery(theConnection,theLog);
}
catch (CSException e)
{
theLog.error(e);
}
ReadOnlyRowSet theRowSet = sqlFile.executeQuery();
|
Calling getParamXXXX Methods for Output Parameters
All output parameters have one or more getParamXXXX methods. Most
specify the data type in the method name:
long outputNumber = example1.getParamBParamLong();
java.util.Date outputDate = example1.getParamDateBDate();
String outputString = example1.getParamCParam();
|
|
Retrieving Sequence Values
Sequence generation shares the same constructor as other generated
classes. Access the next value of the sequence using the getNext()
method:
TestSeq exampleSequence;
long seqVal = exampleSequence.getNext();
|
Retrieving Cursors
Cursors are unloaded into com.orindasoft.pub.ReadOnlyRowSet
objects. You can regard cursors as two-dimensional arrays (rows and
columns). If you call a PL/SQL procedure you can get any cursors that
are returned by calling the appopriate 'get' method. If you have
executed a SELECT statement then its ReadOnlyRowSet is returned by the
executeQuery() call.
Use the first(), last(), nextRow(), previousRow and setRowNumber()
methods to navigate rows.
Row numbering starts at zero. You retrieve column values by position or
name.
try
{
// Any errors that occur are re-cast to 'CSException'.
example2Cur1.executeProc();
}
catch (CSException e)
{
theLog.error(e);
}
// Retrieve the cursor into a ReadOnlyRowSet
com.orindasoft.pub.ReadOnlyRowSet rowSet = example2Cur1.getParamOutParam();
// Retrieve list of column headings
String[] colHeadings = rowSet.getColumnNamesAsStringArray();
// Print a message saying how many rows we retrieved.
theLog.info(rowSet.size() + " rows retrieved");
// iterate through rowset and print out the first 10 rows...
for (int i=0; i < rowSet.size() && i < 10; i++)
{
// rowSet row numbering starts at 0.
rowSet.setCurrentRowNumber(i);
// iterate through each column
for (int j=0; j < colHeadings.length; j++)
{
try
{
theLog.info(colHeadings[j] + "=" + rowSet.getString(j));
}
catch (CSException e)
{
theLog.error(e);
}
}
}
}
|
Generated Procedure Call and SQL statement Methods
Generated code contains protected and private methods. The table
below lists the public methods commonly used for working with PL/SQL
procedures and SQL statements..
Method Name
|
Purpose
|
Comment
|
Common Methods
|
setParam[Name]
|
Sets
a Parameter Value
|
|
executeProc(),
executeCall(), executeQuery()
|
Executes
procedure, SQL statement or SQL query.
|
getParam[Name][Type]
|
Gets
a Parameter Value.
|
setMaxRows()
|
Set
maximum number of rows that will be retrieved from a cursor.
|
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
|
Methods used for working with LONG data
|
setBufferSize()
|
Sets
file IO buffer size for LONG object retrieval.
|
Only
present if LONG data types are being retrieved
|
setKeepFiles()
|
Defines
whether temporary files are deleted automatically when the JVM
exits. Default value is 'false'.
|
setTempDir()
|
Set
directory for downloaded LONG objects.
|
setTempFilePrefix()
|
Set
file prefix for downloaded LONG objects
|
setTempFilePrefix()
|
Set
file suffix for downloaded LONG objects
|
Additional generated SQL Class Methods
When creating Java classes to run SQL statements OrindaBuild acts
differently depending on whether the file contains a query or not. For
SQL queries OrindaBuild creates an abstract class called
'abstractQueryStatement.java' and then
a matching Java class for each query. Once you have created an instance
of the class and provided values for its parameters you can get the
result of the query in a ReadOnlyRowSet by calling the executeQuery()
method. If the statement is a query then OrindaBuild will also try and
determine
what columns are returned by it. If succesful it will add a static
method called 'getArrayFromReadOnlyRowSet' that converts the
ReadOnlyRowSet returned by the query into either of these Java record
classes:
- filenameCursorAttrs,
which is a method-less Java class that contains variables that
correspond to the values returned by the query.
- filenameCursor, which
extends filenameCursorAttrs
by adding 'get' and 'set' methods.
Note that you can get the class to cache query results by using
the method setCacheSeconds() to specify how long the result of a query
remains valid for.
For all other SQL statements OrindaBuild creates an abstract
class called 'abstractSqlStatement.java' and then a matching Java class
for each statement. After creating an instance of the class you call
the appropriate set methods and then the executeCall() method to issue
the statement. In
all cases the generated class with have set methods for the statement's
parameters.
The
table
above lists the other methods that
are created in generated code.
Generated Sequence Access Methods
Generated code contains many protected and private methods. The
table below lists the public methods that are relevant to normal use.
Method Name
|
Purpose
|
Comment
|
Common Methods
|
getNext()
|
Get
next number from a sequence
|
|
getLast()
|
Get
most recent value for getNext()
|
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
|
Generated Table Classes
OrindaBuild generates multiple classes for each table. The two most
important classes are
tablenameMgr
and
tablenameRow. The table
below shows how the classes are named and what they are for.
Class
Name
|
Purpose
|
Comment
|
| Core Classes |
tablenameMgr
|
Manager
class that has database connection, LogInterface Object and can
retrieve or update row classes.
|
These are the only two classes
you need to use directly. tablenameMgr
instantiates and uses
instances of the other classes as it needs them. |
tablenameRowAttr
|
Serializable Instance
class that represents one row in tablename.
|
tablenameRow
|
Extension of tablenameRowAttr that
adds extra 'set' and 'get' methods, conversion methods and LOB fields where needed.tablename.
|
Abstract And Utility
Classes
|
abstractTableMgr
|
Abstract
base class for tablenameMgr.
|
These are extended by tablenameMgr
to provide functionality common to all Mgr classes. |
abstractTableBfileCreator
|
Utility
class to turn directory and file name into a BFILE pointer
|
DML Classes
|
| tablenameIns
|
Insert
a Row
|
These classes are used by tablenameMgr
for insert, update and delete. If the table has a LOB columns tablenameUpd will call tablenameLckprimaryKeyConstraint to obtain a
row level lock. |
| tablenameUpd
|
Update
a Row
|
| tablenameDel
|
Deletes
a Row
|
tablenameLckprimaryKeyConstraint
|
Locks row for update.
|
Query Classes
|
tablenameConprimaryKeyConstraint
|
Return
a tablenameRow using the
Primary key of tablename.
|
These
classes retrieve rows from tablename
using Primary Keys, Unique Keys and Indices.
They alse retrieve rows from child tables of tablename using Foreign Keys. |
| tablenameConUniqueKeyConstraint |
Return
a tablenameRow using a Unique
key of tablename. |
| tablenameConForeignKeyConstraint |
Return
an array of tablenameRow[]
using the foreign key foreignKeyConstraint
|
| tablenameConIndexName |
Return
one or more tablenameRow
using the index foreignKeyConstraint.
- Index Classes are only created if there is no matching
foreign, unique or primary key.
- Unique indexes will only return one tablenameRow
|
|
|
Table Manager Class Methods
The table
below lists the methods you can expect to find in a Table Manager class
and explains what they are for..
Class Name
|
Purpose
|
Comment
|
Core Methods
|
getByPk
|
Retrieves
a row using the Primary Key Columns
|
These
methods each use a generated class to retrieve one or more rows.
The class is instantiated the first time the method is called.
|
getByUkconstraint_name
|
Retrieves
a row using the Columns in Unique Key constraint_name
|
| getChildByFkconstraint_name
|
Retrieves
1 or more rows using the Columns in Foreign Key constraint_name. |
| getChildByIxindex_name
|
Retrieves
1 or more rows using the Columns in index_name. Unique indexes will
only return 1 row. |
| 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
|
| Data
Management Methods |
processOnetableNameRow
|
These
methods take a ReadOnlyRowSet containing a cursor of tableName rows and turn it
into tablenameRow objects. |
There is
no reason why you can't use these methods to process the result of any
query that returns a cursor with the same columns as tablename. You could also use
OrindaBuild to write access code for such a query.
|
| processManytableNameRows |
| DML and Validation
Methods |
rowValidate
|
This method makes sure that a
row Object has values for any fields which are NOT NULL columns in the
database. It also checks for the existance of decimal places for number
fields that map to a database column that does not allow decimals.
|
|
| rowInsert |
Attempts to insert a row into
the database. If the row has one or more LOB columns it will also call
rowLock and rowUpdate so that the LOB Insert/Lock/Update cycle is
transparent from the calling program's perspective.
|
Note
that none of these methods attempt to keep track of whether this record
is already in the database.
|
| rowLock |
Attempts to obtain a row level
lock on an existing row in the database. Used when inserting LOBS.
|
| rowUpdate |
Attempts to update a row in the
database
|
| rowDelete |
Attempts to delete a row in the
database
|
Methods used for working
with LONG data
|
setBufferSize()
|
Sets
file IO buffer size for LONG object retrieval.
|
Inherited
from abstractTableMgr.
|
setKeepFiles()
|
Defines
whether temporary files are deleted automatically when the JVM
exits. Default value is 'false'.
|
setTempDir()
|
Set
directory for downloaded LONG objects.
|
setTempFilePrefix()
|
Set
file prefix for downloaded LONG objects
|
setTempFilePrefix()
|
Set
file suffix for downloaded LONG objects
|