org.afcs.warts.handlers
Class DataHandlerSupport

java.lang.Object
  org.afcs.warts.handlers.DataHandlerSupport

Direct Known Subclasses:

BinaryDataHandler, CharacterHandler, DecimalHandler, IntegerHandler, LobDataHandlerSupport, NullHandler, TimestampHandler

public class DataHandlerSupport

extends java.lang.Object

The DataHandlerSupport class is the base class for all data handling classes, providing several useful utility methods for subclasses.

LICENSE: This code is released to the public domain and may be used for any purpose whatsoever without permission or acknowledgment.

Version:

Last Modified 2 September 2003

Author:

Warren Hedley ( whedley at sdsc dot edu )

Constructor Summary

protected

DataHandlerSupport(TableDescription tableDescription, ColumnDescription columnDescription) Constructs a new instance on behalf of subclasses that will handle data values for the specified column.

Method Summary

protected ColumnDescription	getColumnDescription() Returns the column description for this instance, which was set at initialisation.
int	getNullType() The default type to use when binding null values in prepared statements is the type defined in the column metadata, and this implementation always returns that.
protected TableDescription	getTableDescription() Returns the table description for this instance, which was set at initialisation.
boolean	isCharacterData() Always returns false.
boolean	isNullHandler() All handlers other than the NullHandler will return false, so we return false here so other subclasses don't have to worry about it.
protected static byte[]	loadBytesFromStream(java.io.InputStream stream, int length) This utility method can be used by subclasses to allocate a byte array of the specified length and read that number of bytes into the array from the specified stream, converting any IO errors that occur into SQL errors.
protected void	logWrongValueTypeWarning(java.lang.String methodName, java.lang.String actualValueType, java.lang.String expectedValueType) This method should be called by subclasses that wish to log a warning about receiving the wrong class of value in some method (presumably bindNonNullValue() or printNonNullValue()).
void	postProcessBind(java.sql.Connection connection, java.util.List primaryKeyValues, java.lang.Object value) This method does absolutely nothing, and needs to be overridden by subclasses that actually do require bind post-processing when writing data to the database.
boolean	requiresBindPostProcessing() This method always returns false, and needs to be overridden by subclasses that actually do require bind post-processing when writing data to the database.
boolean	requiresStreamedLoading() This method always returns true, and needs to be overridden by subclasses that represent data types that actually do require streamed loading.
java.lang.String	toString() Returns a text description of the current instance that can be used for debugging purposes.
protected java.lang.String	verifyObjectIsString(java.lang.Object value) This utility can be used by subclasses that deal with character data (such as CharacterHandler and OracleClobHandler to verify that anobject is a potential character data class and to truncate its string valueto the column's size before attempting to print or bind its value.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataHandlerSupport

protected DataHandlerSupport(TableDescription tableDescription,
                             ColumnDescription columnDescription)

Constructs a new instance on behalf of subclasses that will handle data values for the specified column.

Parameters:

tableDescription - The table that the handler will be handling data for.

columnDescription - The column that this class will be processing data for.

Method Detail

getNullType

public int getNullType()

The default type to use when binding null values in prepared statements is the type defined in the column metadata, and this implementation always returns that.

Returns:

The constant from java.sql.Types that should be used to bind null values in prepared-statements.

isCharacterData

public boolean isCharacterData()

Always returns false. This should be overridden by data handlers that actually do deal with character data.

Returns:

Always false.

isNullHandler

public boolean isNullHandler()

All handlers other than the NullHandler will return false, so we return false here so other subclasses don't have to worry about it.

Returns:

Always false.

postProcessBind

public void postProcessBind(java.sql.Connection connection,
                            java.util.List primaryKeyValues,
                            java.lang.Object value)
                     throws java.sql.SQLException

This method does absolutely nothing, and needs to be overridden by subclasses that actually do require bind post-processing when writing data to the database.

Parameters:

connection - The database connection to use.

primaryKeyValues - The primary key values identifying the row that the specified value has to be written to.

value - The value to write to the database (always ignored).

Throws:

java.sql.SQLException - If a SQL error occurs during binding (never).

requiresBindPostProcessing

public boolean requiresBindPostProcessing()

This method always returns false, and needs to be overridden by subclasses that actually do require bind post-processing when writing data to the database.

Returns:

Always false.

requiresStreamedLoading

public boolean requiresStreamedLoading()

This method always returns true, and needs to be overridden by subclasses that represent data types that actually do require streamed loading.

Returns:

Always true.

toString

public java.lang.String toString()

Returns a text description of the current instance that can be used for debugging purposes. This uses the class name of this instance, so it doesn't need to be overridden by subclasses.

Returns:

A text description of the current instance that can be used for debugging purposes.

getTableDescription

protected TableDescription getTableDescription()

Returns the table description for this instance, which was set at initialisation.

Returns:

The table description for this instance.

getColumnDescription

protected ColumnDescription getColumnDescription()

Returns the column description for this instance, which was set at initialisation.

Returns:

The column description for this instance.

loadBytesFromStream

protected static byte[] loadBytesFromStream(java.io.InputStream stream,
                                            int length)
                                     throws java.sql.SQLException

This utility method can be used by subclasses to allocate a byte array of the specified length and read that number of bytes into the array from the specified stream, converting any IO errors that occur into SQL errors.

Parameters:

stream - The stream to read from.

length - The number of bytes to read.

Returns:

An array containing the specifed number of bytes read from the specified stream.

Throws:

java.sql.SQLException - If an IO error occurs.

logWrongValueTypeWarning

protected void logWrongValueTypeWarning(java.lang.String methodName,
                                        java.lang.String actualValueType,
                                        java.lang.String expectedValueType)

This method should be called by subclasses that wish to log a warning about receiving the wrong class of value in some method (presumably bindNonNullValue() or printNonNullValue()).

Parameters:

methodName - The name of the method that saw the wrong type.

actualValueType - The actual type of object received.

expectedValueType - The expected type.

verifyObjectIsString

protected java.lang.String verifyObjectIsString(java.lang.Object value)

This utility can be used by subclasses that deal with character data (such as CharacterHandler and OracleClobHandler to verify that anobject is a potential character data class and to truncate its string valueto the column's size before attempting to print or bind its value.

Valid character data values are a DataHighBitAnalysis instance, a String instance, or null. Any other value will cause a warning message to be logged and null to be reutrned. If a DataHighBitAnalysis instance is specified, the string contained in it will be verified.

A warning message is logged whenever an oversize string value is recevied.

Parameters:

value - The object to verify.

Returns:

The truncated string value of the object.

Throws:

java.lang.IllegalArgumentException - If the specified value is not a character data class.