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

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.jcorporate.expresso.kernel.exception.ChainedException
              com.jcorporate.expresso.core.db.DBException
                  com.jcorporate.expresso.core.dataobjects.DataException
                      com.jcorporate.expresso.core.dataobjects.jdbc.JDBCUtil

All Implemented Interfaces:

Serializable

public class JDBCUtil

extends DataException

This class provides utility functions that are common across the jdbc.* package classes. This class is normally not accessed except through other classes in the jdbc package.

Since:

Expresso 5.0

Author:

Michael Rimov

See Also:

Serialized Form

Field Summary

static String	DATE_FORMAT
static String	DATETIME_FORMAT
static String	TIME_FORMAT

Constructor Summary

protected

JDBCUtil()

Method Summary

String	buildWhereClause(JDBCDataObject criteria, boolean useAllFields) Build and return a string consisting of an SQL 'where' clause using the current field values as criteria for the search.
FastStringBuffer	buildWhereClauseBuffer(JDBCDataObject criteria, 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	containsWildCards(JDBCDataObject ownerObject, String fieldValue) See if this field value contains wild cards (e.g. pattern matching criteria for the database).
String	formatDateTime(DataObject theObject, String fieldName) Given the value of a date/time or date/time field, return the value formatted as appropriate for the current DBMS.
String	formatDateTime(DataObject theObject, String fieldName, boolean surroundWithQuotes) Given the value of a date/time or datetime field, return the value formatted as appropriate for the current DBMS.
protected com.jcorporate.expresso.core.dataobjects.jdbc.JDBCUtil.DateReturnFormat	formatDateTimeInternal(DataObject theObject, String fieldName) This class combines the old getFieldDate() with quoteIfNeeded() to format the Date-Time fields appropriately for storage.
Date	getDateField(DataObject theObject, String fieldName) Helper function that helps convert any string values from the database's format
static JDBCUtil	getInstance()
protected SimpleDateFormat	getSimpleDateFormat(String pattern) Get a SimpleDateFormat object that is cached.
String	makeLimitationStub(DBConnection theConnection, DataObject theObj) Creates the limitation syntax optimisation stub to embed inside the SQL command that performs search and retrieve.
String	quoteIfNeeded(JDBCDataObject targetObject, String fieldName, String rangeString) Return the value of this field, placing double quotes around it if the field's datatype requires it.

Methods inherited from class com.jcorporate.expresso.core.db.DBException

getDBMessage, getMessage

Methods inherited from class com.jcorporate.expresso.kernel.exception.ChainedException

getErrorNumber, getNested, omitPackages, printStackTrace, printStackTrace, printStackTrace

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Field Detail

DATETIME_FORMAT

public static final String DATETIME_FORMAT

See Also:

Constant Field Values

DATE_FORMAT

public static final String DATE_FORMAT

See Also:

Constant Field Values

TIME_FORMAT

public static final String TIME_FORMAT

See Also:

Constant Field Values

Constructor Detail

JDBCUtil

protected JDBCUtil()

Method Detail

getInstance

public static JDBCUtil getInstance()

formatDateTime

public String formatDateTime(DataObject theObject,
                             String fieldName)
                      throws DataException

Given the value of a date/time or date/time field, return the value formatted as appropriate for the current DBMS. Can be configured using property file values.

Parameters:

fieldName - java.lang.String The value for the date/time field.

theObject - the DataObject that the date field is coming from.

Returns:

java.lang.String The formatted date time, ready for use in the DBMS

Throws:

DataException

formatDateTime

public String formatDateTime(DataObject theObject,
                             String fieldName,
                             boolean surroundWithQuotes)
                      throws DataException

Given the value of a date/time or datetime field, return the value formatted as appropriate for the current DBMS. Can be configured using expresso-config file values.

Parameters:

fieldName - java.lang.String The value for the date/time field.

theObject - the DataObject that the date field is coming from.

surroundWithQuotes - set to true if you want the returned value to be surrounded with single quotes, such as for a standard JDBC SELECT statement. Use false if you want to use it, for example, in a PreparedStatement

Returns:

java.lang.String The formatted date time, ready for use in the DBMS

Throws:

DataException

getSimpleDateFormat

protected SimpleDateFormat getSimpleDateFormat(String pattern)

Get a SimpleDateFormat object that is cached. Make sure you have dateConvertFormatMap already locked before calling this function or you'll have a race condition.

Parameters:

pattern - the format pattern to look up

Returns:

an instantiated SimpleDateFormat object. SimpleDateFormat is NOT threadsafe, so make sure you do your parsing while still in the synchronized block. Perhaps in the future a keyed Object pool will be better.

getDateField

public Date getDateField(DataObject theObject,
                         String fieldName)
                  throws DataException

Helper function that helps convert any string values from the database's format

Parameters:

theObject - the source data object

fieldName - the name of the field

Returns:

java.util.Date

Throws:

DataException - upon error (possibly conversion error)

formatDateTimeInternal

protected com.jcorporate.expresso.core.dataobjects.jdbc.JDBCUtil.DateReturnFormat formatDateTimeInternal(DataObject theObject,
                                                                                                         String fieldName)
                                                                                                  throws DataException

This class combines the old getFieldDate() with quoteIfNeeded() to format the Date-Time fields appropriately for storage. This probably could use some serious optimization since it looks like at first glance it does the same operation twice. Any volunteers? :)

Parameters:

theObject - The object that contains the data to froatm

fieldName - the name of the field to format

Returns:

a DateReturnFormat object.

Throws:

DataException - upon error

buildWhereClause

public String buildWhereClause(JDBCDataObject criteria,
                               boolean useAllFields)
                        throws DataException

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:

criteria - the JDBCDataObject to build from

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

Returns:

The where clause to use in a query.

Throws:

DataException

buildWhereClauseBuffer

public FastStringBuffer buildWhereClauseBuffer(JDBCDataObject criteria,
                                               boolean useAllFields,
                                               FastStringBuffer allocatedBuffer)
                                        throws DataException

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:

criteria - the JDBCDataObject to build from

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:

DataException - upon error

makeLimitationStub

public String makeLimitationStub(DBConnection theConnection,
                                 DataObject theObj)

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

theObj - the DataObject to query for the limitation stub

Returns:

the limitation syntax stub string

quoteIfNeeded

public String quoteIfNeeded(JDBCDataObject targetObject,
                            String fieldName,
                            String rangeString)
                     throws DataException

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

targetObject - the JDBCDataObject to query for metadata

Returns:

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

Throws:

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

containsWildCards

public boolean containsWildCards(JDBCDataObject ownerObject,
                                 String fieldValue)
                          throws DataException

See if this field value contains wild cards (e.g. pattern matching criteria for the database). The wild cards can be configured via the properties file.

Parameters:

fieldValue - The field value to check for wild cards

ownerObject - the obejct to query for metadata

Returns:

True if the string does contain wild cards, False if it does not

Throws:

DataException