com.jcorporate.expresso.core.dataobjects.jdbc
Class JDBCDataObject

java.lang.Object
  com.jcorporate.expresso.core.dataobjects.BaseDataObject
      com.jcorporate.expresso.core.dataobjects.jdbc.JDBCDataObject

All Implemented Interfaces:

Cacheable, ContextNested, DataObject, Serializable

Direct Known Subclasses:

DBObject

public abstract class JDBCDataObject

extends BaseDataObject

Base class for JDBC-based data objects.

Since:

Expresso 5.1

Modify by Yves Henri AMAIZO

Author:

Michael Rimov

See Also:

Serialized Form

Field Summary

boolean	anyFieldsDistinct If setFieldDistinct has been used to specify distinct/unique fields for the next query.
protected boolean	anyFieldsToRetrieve If setFieldsToRetrieve has been used to specify fields which will be retrieve by the next query.
protected boolean	appendCustomWhere Flag to indicate whether we append any custom WHERE clause to the one generated, or just use the supplied custom WHERE clause
protected boolean	caseSensitiveQuery This flag tells the buildWhereClause method(s) to either be case sensitive (normal queries) or to be case insensitive.
protected String	customWhereClause If we are using a custom where clause for this query, it's stored here.
protected String	dbKey dbKey is used to indicate that this object is actually stored in other than the default database.
protected HashMap	distinctFields Map of any distinct fields for retrieval.
protected DBConnection	localConnection Local connection that we use if it's initialized, but if it's null we generate our own connection
static int	LONGBINARY_READ_DEFAULT_SIZE
protected int	maxRecords
protected String	myClassName We use getClass().getName() a lot in this class, however, it takes actually significant time to use this over the time it takes to do, say, a concurrentReaderHashMap lookup.
protected ArrayList	myUpdates Holds the FieldUpdate objects representing any changes made to this object since it was retrieved
protected int	offsetRecord The number of records we must skip over before we start reading the ResultSet proper in a searchAndRetrieve. 0 means no limit author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
protected ArrayList	recordSet The ArrayList of DB objects retrieved by the last searchAndRetrieve method
HashMap	retrieveFields The actual fields retrieved
protected static EDU.oswego.cs.dl.util.concurrent.ConcurrentReaderHashMap	sMetadataMap DBObjects themselves do not contain the "meta data" or the definition of what fields they contain and other information.
protected ArrayList	sortKeys The list of fields by which this object should be sorted when records are retrieved

Fields inherited from class com.jcorporate.expresso.core.dataobjects.BaseDataObject

currentStatus, globalMask

Fields inherited from interface com.jcorporate.expresso.core.dataobjects.DataObject

STATUS_CURRENT, STATUS_DELETED, STATUS_NEW, STATUS_UPDATED

Constructor Summary

JDBCDataObject()
Default constructor

Method Summary

protected void	addInParam(String inFieldName) Add a new field to the list of fields that are part of this object's list of input parameters.
protected void	addOutParam(String outFieldName) Add a new field to the list of fields that are part of this object's list of output parameter.
String	buildWhereClause(boolean useAllFields) Build and return a string consisting of an SQL 'where' clause using the current field values as criteria for the search.
protected FastStringBuffer	buildWhereClauseBuffer(boolean useAllFields, FastStringBuffer allocatedBuffer) Build and return a FastStringBuffer ring consisting of an SQL 'where' clause using the current field values as criteria for the search.
boolean	checkZeroUpdate() Returns the checkzero update as defined by the object's metadata.
protected DBObjectDef	constructNewMetaData() Construction method to allow for specialized metadata with specialized fields other than DBObjectDef.
DBConnection	createAndExecuteSearch(ArrayList retrievedFieldList) Refactoring to split the execution of a query statement into the query part and the load part.
DBConnection	createAndRunStoreProcedure(ArrayList retrievedFieldList) Refactoring to split the execution of a query statement into the query part and the load part.
DBConnectionPool	getConnectionPool() Retrieve the connection pool associated with this DBObject.
String	getCustomStringFieldValue(DBConnection connection, String oneFieldName) This convenience method retrieve through the resultSet.MetaData the date value of field define as date or time DBObject
protected DBObjectDef	getDef() Return the DBObjectRef object that contains the definition of the current DBObject.
ArrayList	getDistinctFieldArrayList() Get a special ArrayList object list of all of the fields in this object that are set to distinct
DataExecutorInterface	getExecutor() Use this function to acquire the Executor interface that is associated with this data object
Iterator	getFieldsToRetrieveIterator() Get a special Iterator object list of all of the fields in this object that are set to retrieve Author Yves henri Amaizo
JDBCObjectMetaData	getJDBCMetaData() Retrieve the JDBCObjectMetaData
protected JDBCUtil	getJDBCUtil() Get the JDBC Util functions
DBConnection	getLocalConnection() Return local DBConnection value author Yves Henri AMAIZO <amy_amaizo@compuserve.com>
String	getMappedDataContext() Returns the name of the physical database that we're talking with.
DataObjectMetaData	getMetaData() Retrieve the database object's metadata
DataQueryInterface	getQueryInterface() Use this function to acquire the DataQueryInterface that is associated with this data object
String	getSerialForm(DataFieldMetaData theField) This function is called whenever the DBField is about to be written to the database.
void	loadFromConnection(JDBCDataObject myObj, DBConnection myConnection, ArrayList retrievedFieldList) Fills the given constructed data object with data from the connection given the field order specified in retrievedFieldList.
protected String	makeLimitationStub(DBConnection theConnection) Creates the limitation syntax optimisation stub to embed inside the SQL command that performs search and retrieve.
String	quoteIfNeeded(String fieldName, String rangeString) Return the value of this field, placing double quotes around it if the field's datatype requires it.
void	runStoredProcedure() Run a particular store procedure in the database into this object's fields
protected ArrayList	runStoredProcedureAndRetrieveList() Run a particular store procedure in the database into this object's fields
String	selectFieldString(String fieldName) Build an appropriate String for use in the select part of an SQL statement by doing the
void	setCaseSensitiveQuery(boolean caseSensitiveQuery) This tells the buildWhereClause to either respect case (true) or ignore case (false).
void	setConnection(DBConnection newConnection) Set a specific DB connection for use with this db object.
void	setConnection(DBConnection newConnection, String setupTablesContext) Set a specific DB connection for use with this db object.
protected void	setDBConnectionPool(DBConnectionPool newPool) Sets the connection pool associated with this dbobject.
void	setDBName(String newOther) Set the database name/context for this db object.
protected void	setMappedDataContext(String newMappedName)
protected void	setOriginalDBName(String newOriginalName) Set the name of the db context that was the "original" context for this object - e.g. before any database mapping took place.
void	setTargetStoreProcedure(String theStoreProcedure) Set the target store procedure for this DBObject.

Methods inherited from class com.jcorporate.expresso.core.dataobjects.BaseDataObject

getGlobalMask, getStatus, isGlobalMasked, setFieldsWithDefaults, setGlobalMask, setStatus

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.jcorporate.expresso.core.dataobjects.DataObject

add, checkField, clear, count, delete, equals, find, get, getAllAttributes, getAttribute, getDataField, getField, getFieldMetaData, getLocale, getMaxRecords, getOffsetRecord, getValidValuesList, searchAndRetrieveList, searchAndRetrieveList, set, setAttribute, setLocale, setMaxRecords, setOffsetRecord, update

Methods inherited from interface com.jcorporate.expresso.core.cache.Cacheable

getKey

Methods inherited from interface com.jcorporate.expresso.core.dataobjects.ContextNested

getDataContext, setDataContext

Field Detail

LONGBINARY_READ_DEFAULT_SIZE

public static int LONGBINARY_READ_DEFAULT_SIZE

customWhereClause

protected String customWhereClause

If we are using a custom where clause for this query, it's stored here. If null, then build the where clause

appendCustomWhere

protected boolean appendCustomWhere

Flag to indicate whether we append any custom WHERE clause to the one generated, or just use the supplied custom WHERE clause

dbKey

protected String dbKey

dbKey is used to indicate that this object is actually stored in other than the default database. Null indicates it's in the default database

recordSet

protected ArrayList recordSet

The ArrayList of DB objects retrieved by the last searchAndRetrieve method

myClassName

protected transient String myClassName

We use getClass().getName() a lot in this class, however, it takes actually significant time to use this over the time it takes to do, say, a concurrentReaderHashMap lookup. So we precalculate this value at instantiation and go from there.

distinctFields

protected HashMap distinctFields

Map of any distinct fields for retrieval.

retrieveFields

public HashMap retrieveFields

The actual fields retrieved

sMetadataMap

protected static transient volatile EDU.oswego.cs.dl.util.concurrent.ConcurrentReaderHashMap sMetadataMap

DBObjects themselves do not contain the "meta data" or the definition of what fields they contain and other information. Instead, a DBObjectRef object (one per TYPE of DBObject) contains this info and is looked up as needed. This HashMap contains the DBObjectRef objects for all initialized DBObjects

anyFieldsToRetrieve

protected boolean anyFieldsToRetrieve

If setFieldsToRetrieve has been used to specify fields which will be retrieve by the next query.

localConnection

protected transient DBConnection localConnection

Local connection that we use if it's initialized, but if it's null we generate our own connection

offsetRecord

protected transient int offsetRecord

The number of records we must skip over before we start reading the ResultSet proper in a searchAndRetrieve. 0 means no limit author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

maxRecords

protected transient int maxRecords

sortKeys

protected transient ArrayList sortKeys

The list of fields by which this object should be sorted when records are retrieved

myUpdates

protected transient ArrayList myUpdates

Holds the FieldUpdate objects representing any changes made to this object since it was retrieved

anyFieldsDistinct

public boolean anyFieldsDistinct

If setFieldDistinct has been used to specify distinct/unique fields for the next query.

caseSensitiveQuery

protected boolean caseSensitiveQuery

This flag tells the buildWhereClause method(s) to either be case sensitive (normal queries) or to be case insensitive. The case insensitive query is useful when you want to do a search and retreive and want case insensitive matching.

Constructor Detail

JDBCDataObject

public JDBCDataObject()

Default constructor

Method Detail

getMappedDataContext

public String getMappedDataContext()

Returns the name of the physical database that we're talking with. This is opposed to getDataContext() which returns the security context as well. getMappedDataContext() is strictly used to get at the low level database connection.

Returns:

java.lang.String... the underlying data context that is mapped to the physical database

getConnectionPool

public DBConnectionPool getConnectionPool()
                                   throws DataException

Retrieve the connection pool associated with this DBObject.

Returns:

DBConnectionPool instance for the current mapped context.

Throws:

DataException - upon error getting the connection pool instance

setDBConnectionPool

protected void setDBConnectionPool(DBConnectionPool newPool)

Sets the connection pool associated with this dbobject. Is only settable from derived classes as we normally create our own as needed.

Parameters:

newPool - the new DBConnectionPool to set

getSerialForm

public String getSerialForm(DataFieldMetaData theField)
                     throws DataException

This function is called whenever the DBField is about to be written to the database. It may do additional processing such as encryption depending on the field attributes.

Parameters:

theField - A DBField object

Returns:

the value to write to the data source.

Throws:

DataException - upon error

setDBName

public void setDBName(String newOther)
               throws DBException

Set the database name/context for this db object. If setDBName is not called, the "default" db name and context is used. See com.jcorporate.expresso.core.misc.ConfigManager for information about multiple contexts. Note that setting a db/context name only affects the object when it allocates it's own db connections - if a specific connection is used (via the setConnection(DBConnection) method) then that connection must be already associated with the correct db/context. If there is an entry in the DBOtherMap table for this object, it is forced to that database, and a warning is logged if any other database is specified.

Parameters:

newOther - The name of the context or database to use

Throws:

DBException

getMetaData

public final DataObjectMetaData getMetaData()

Retrieve the database object's metadata

Returns:

a built DataObjectMetaData

getJDBCMetaData

public final JDBCObjectMetaData getJDBCMetaData()

Retrieve the JDBCObjectMetaData

Returns:

the JDBCObjectMetadata. [Actually an instance of DataObjectMetaData, but this way it's type correct]

getDef

protected final DBObjectDef getDef()

Return the DBObjectRef object that contains the definition of the current DBObject. If there isn't one in the dbobjMetadata hashmap, initialize a new one as required

Returns:

static the DBObject Definition

constructNewMetaData

protected DBObjectDef constructNewMetaData()
                                    throws DBException

Construction method to allow for specialized metadata with specialized fields other than DBObjectDef. Override in classes that need custom derived from DBObjectDef classes.

Returns:

DBOBjectDef derived instance

Throws:

DBException - upon construction error

checkZeroUpdate

public boolean checkZeroUpdate()

Returns the checkzero update as defined by the object's metadata.

Returns:

true if checkZeroUpdate is unabled

setOriginalDBName

protected void setOriginalDBName(String newOriginalName)

Set the name of the db context that was the "original" context for this object - e.g. before any database mapping took place.

Parameters:

newOriginalName - new value to set

setMappedDataContext

protected void setMappedDataContext(String newMappedName)

setCaseSensitiveQuery

public void setCaseSensitiveQuery(boolean caseSensitiveQuery)

This tells the buildWhereClause to either respect case (true) or ignore case (false). You can call this method before doing a search and retrieve if you want to match without worrying about case. For example if you were to call this method with isCaseSensitiveQuery = FALSE then this comparison would match in the search:

vendor_name actual value = "My Name"

query value = "my name"

This would match in a search and retrieve.

author Adam Rossi, PlatinumSolutions

Parameters:

caseSensitiveQuery - boolean

selectFieldString

public String selectFieldString(String fieldName)
                         throws DBException

Build an appropriate String for use in the select part of an SQL statement by doing the

Parameters:

fieldName - The name of the field to be handled

Returns:

The portion of the select clause with the appropriate function wrapped around it

Throws:

DBException

quoteIfNeeded

public String quoteIfNeeded(String fieldName,
                            String rangeString)
                     throws DBException

Return the value of this field, placing double quotes around it if the field's datatype requires it.

Parameters:

fieldName - The name of the field to be used

rangeString - the appropriately formatted string

Returns:

A string, quoted if necessary, to be used in building an SQL statement

Throws:

DBException - If there is no such field or it's value cannot be determined

setConnection

public void setConnection(DBConnection newConnection)
                   throws DBException

Set a specific DB connection for use with this db object. If you do not set a connection, the db object will request it's own connection from the appropriate connection pool & release it again after every operation (e.g. add, update, etc). It is important to use your own explicit connection when dealing with a database transactional environment (e.g. commit(), rollback()).

Parameters:

newConnection - The new DBConnection object to be used by this DB Object

Throws:

DBException

setConnection

public void setConnection(DBConnection newConnection,
                          String setupTablesContext)
                   throws DBException

Set a specific DB connection for use with this db object. If you do not set a connection, the db object will request it's own connection from the appropriate connection pool & release it again after every operation (e.g. add, update, etc). It is important to use your own explicit connection when dealing with a database transactional environment (e.g. commit(), rollback()).

The difference between this and setConnection(DBConnection) is that this is used for using otherDB capabilities within a transaction. So you use a dbconnection from your other pool, but the setup tables are in a different context

Parameters:

newConnection - The new DBConnection object to be used by this DB Object

setupTablesContext - the data context that is used for the expresso setup tables.

Throws:

DBException

See Also:

setConnection(DBConnection)

createAndExecuteSearch

public DBConnection createAndExecuteSearch(ArrayList retrievedFieldList)
                                    throws DBException

Refactoring to split the execution of a query statement into the query part and the load part. The DBConnection returned will have the query already executed.

SIDE-EFFECT: custom 'where' clause is set to null.

Parameters:

retrievedFieldList - instantiate an ArrayList and the function will fill out the field order that the SQL statement will have it's fields in.

Returns:

connection that has already executed the search statement.

Modify by Yves Henri AMAIZO

Throws:

DBException - upon database communication error

Since:

$DatabaseSchema $Date: 2004/11/18 02:03:27 $

loadFromConnection

public void loadFromConnection(JDBCDataObject myObj,
                               DBConnection myConnection,
                               ArrayList retrievedFieldList)
                        throws DBException

Fills the given constructed data object with data from the connection given the field order specified in retrievedFieldList. Similar to loadFromConnection but much faster because the connection fields are retrieved via number instead of name.

Parameters:

myObj - the Object to have the values filled out. [in/out parameter]

myConnection - [in] the connection to retrieve the fields from

retrievedFieldList - [in] An array of Strings representing the field names to retrieve in the order they exist in the connection.

Throws:

DBException - upon error

makeLimitationStub

protected String makeLimitationStub(DBConnection theConnection)

Creates the limitation syntax optimisation stub to embed inside the SQL command that performs search and retrieve.

This method takes the limitation syntax string and performs a string replacement on the following tokens

• %offset%
• 
  the number of rows in the ResultSet to skip before reading the data.

• %maxrecord%
• 
  the maximum number of rows to read from the ResultSet. Also known as the rowlength.

• %endrecord%
• 
  the last record of in the ResultSet that the search and retrieved should retrieve. The end record number is equal to ( %offset% + %maxrecord% - 1 )

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Parameters:

theConnection - the db connection to make this stub from

Returns:

the limitation syntax stub string

See Also:

DataObject.searchAndRetrieveList(), DataObject.setOffsetRecord( int ), DataObject.setMaxRecords( int )

getDistinctFieldArrayList

public ArrayList getDistinctFieldArrayList()
                                    throws DBException

Get a special ArrayList object list of all of the fields in this object that are set to distinct

Returns:

An Iterator of all the distinct fieldNames in this object

Throws:

DBException - If the list cannot be retrieved

author Peter Pilgrim

getFieldsToRetrieveIterator

public Iterator getFieldsToRetrieveIterator()
                                     throws DBException

Get a special Iterator object list of all of the fields in this object that are set to retrieve

Author Yves henri Amaizo

Returns:

An Iterator of all the retrieve fieldNames in this object

Throws:

DBException - If the list cannot be retrieved

buildWhereClause

public String buildWhereClause(boolean useAllFields)
                        throws DBException

Build and return a string consisting of an SQL 'where' clause using the current field values as criteria for the search. See setCustomWhereClause for information on specifying a more complex where clause.

Parameters:

useAllFields - True if all fields are to be used, false for only key fields

Returns:

The where clause to use in a query.

Throws:

DBException

buildWhereClauseBuffer

protected FastStringBuffer buildWhereClauseBuffer(boolean useAllFields,
                                                  FastStringBuffer allocatedBuffer)
                                           throws DBException

Build and return a FastStringBuffer ring consisting of an SQL 'where' clause using the current field values as criteria for the search. See setCustomWhereClause for information on specifying a more complex where clause.

Parameters:

useAllFields - True if all fields are to be used, false for only key fields

allocatedBuffer - - An already allocated FastStringBuffer to fill out. This allows for compatability with, for example, object pools.

Returns:

A FastStringBuffer containing the "where" clause for the SQL statement

Throws:

DBException

getJDBCUtil

protected JDBCUtil getJDBCUtil()

Get the JDBC Util functions

Returns:

JDBCUtil class.

getExecutor

public DataExecutorInterface getExecutor()

Use this function to acquire the Executor interface that is associated with this data object

Returns:

DataExecutorInterface or null if no Executor has been associated with this object

getQueryInterface

public DataQueryInterface getQueryInterface()

Use this function to acquire the DataQueryInterface that is associated with this data object

Returns:

DataQueryInterface or null if no QueryInterface has been associated with this object

getCustomStringFieldValue

public String getCustomStringFieldValue(DBConnection connection,
                                        String oneFieldName)
                                 throws DBException

This convenience method retrieve through the resultSet.MetaData the date value of field define as date or time DBObject

Parameters:

connection - The DBConnection

oneFieldName - the field name to get the custom field value from

Returns:

Custom String value retrieve from resultSet according to metaData.

Throws:

DBException - author Yves Henri AMAIZO

getLocalConnection

public DBConnection getLocalConnection()

Return local DBConnection value

author Yves Henri AMAIZO <amy_amaizo@compuserve.com>

Returns:

DBConnection

createAndRunStoreProcedure

public DBConnection createAndRunStoreProcedure(ArrayList retrievedFieldList)
                                        throws DBException

Refactoring to split the execution of a query statement into the query part and the load part. The DBConnection returned will have the query already executed, it is ready to

Parameters:

retrievedFieldList - instantiate an ArrayList and the function will fill out the field order that the SQL statement will have it's fields in.

Returns:

connection that has already executed the search statement.

Throws:

DBException - upon database communication error

addInParam

protected void addInParam(String inFieldName)
                   throws DBException

Add a new field to the list of fields that are part of this object's list of input parameters. Called after all of the "addField" calls in the setupFields() method to specify which fields make up the primary key of this object.

Parameters:

inFieldName - The name of the field to add as part of the key

Throws:

DBException - if the field name is not valid or the field allows nulls

addOutParam

protected void addOutParam(String outFieldName)
                    throws DBException

Add a new field to the list of fields that are part of this object's list of output parameter. Called after all of the "addField" calls in the setupFields() method to specify which fields make up the primary key of this object.

Parameters:

outFieldName - The name of the field to add as part of the key

Throws:

DBException - if the field name is not valid or the field allows nulls

setTargetStoreProcedure

public void setTargetStoreProcedure(String theStoreProcedure)
                             throws DBException

Set the target store procedure for this DBObject.

Parameters:

theStoreProcedure - Table for this object

Throws:

DBException - upon execution error.

runStoredProcedure

public void runStoredProcedure()
                        throws DBException

Run a particular store procedure in the database into this object's fields

Throws:

DBException - If the record could not be retrieved.

runStoredProcedureAndRetrieveList

protected ArrayList runStoredProcedureAndRetrieveList()
                                               throws DBException

Run a particular store procedure in the database into this object's fields

Returns:

Vector A vector of new database objects containing the results of the search

Throws:

DBException - If the record could not be retrieved.