org.afcs.warts.handlers
Interface DataHandler

All Known Implementing Classes:

BinaryDataHandler, CharacterHandler, DecimalHandler, IntegerHandler, NullHandler, OracleBlobHandler, OracleClobHandler, TimestampHandler

public interface DataHandler

The DataHandler interface defines a set of methods that must be implemented by a class that is to be responsible for reading and writing a specific type of data from the database.

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

Version:

Last Modified 26 August 2003

Author:

Warren Hedley ( whedley at sdsc dot edu )

Method Summary

void	bindNonNullValue(java.sql.PreparedStatement statement, int variableIndex, java.lang.Object value) The implementation of this method in concrete subclasses should bind the specified non-null value to the specified index in the specified statement.
int	getNullType() Returns the constant from java.sql.Types that should be used to bind null values in prepared-statements.
boolean	isCharacterData() Returns true if the current column contains character data, and should therefore be loaded when performing non-ascii character scanning on a table.
boolean	isNullHandler() Returns true if the implementation is the "Null handler", which is used when the DataHandlerFactory cannot construct an appropriate handler for a specific column type.
java.lang.Object	loadValue(java.sql.ResultSet resultSet, int columnIndex) This method is responsible for constructing and returning an object from the specified column of the specified result set.
void	postProcessBind(java.sql.Connection connection, java.util.List primaryKeyValues, java.lang.Object value) This method is called when requiresBindPostProcessing() returns true to finish writing data to the database for which simple binding isn't sufficient.
java.lang.String	printNonNullValue(java.lang.Object value) This method should return a representation of the specified value that is appropriate for inclusion in a SQL script.
boolean	requiresBindPostProcessing() Returns true if writing of the data handled by this handler requires additional post-processing of the bind step.
boolean	requiresStreamedLoading() Returns true if the loading of this data requires streaming outside the standard result set, which is true for LOB data.

Method Detail

bindNonNullValue

public void bindNonNullValue(java.sql.PreparedStatement statement,
                             int variableIndex,
                             java.lang.Object value)
                      throws java.sql.SQLException

The implementation of this method in concrete subclasses should bind the specified non-null value to the specified index in the specified statement.

Parameters:

statement - The statement to bind the value in.

variableIndex - The index of the variable to bind.

value - The value to bind to the statement. This value should be of the appropriate type for the data handler subclass.

Throws:

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

getNullType

public int getNullType()

Returns the constant from java.sql.Types that should be used to bind null values in prepared-statements. Normally, one would hope that you could just use the type returned by analysis of column metadata, but in some cases, like Oracle LOBs, this isn't the case, and the data-handler must override that value.

Returns:

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

isCharacterData

public boolean isCharacterData()

Returns true if the current column contains character data, and should therefore be loaded when performing non-ascii character scanning on a table. The objects returned by loadValue(java.sql.ResultSet, int) for character data columns will always be of type DataHighBitAnalysis.

Returns:

True if the current column contains character data.

isNullHandler

public boolean isNullHandler()

Returns true if the implementation is the "Null handler", which is used when the DataHandlerFactory cannot construct an appropriate handler for a specific column type. Null handlers are not allowed in primary key columns, because this will make rows indistinguishable.

Returns:

True if the implementation is the "Null handler".

loadValue

public java.lang.Object loadValue(java.sql.ResultSet resultSet,
                                  int columnIndex)
                           throws java.sql.SQLException

This method is responsible for constructing and returning an object from the specified column of the specified result set. The object returned may be used in maps and sortable tables, so should implement java.lang.Comparable and provide reasonable equals(), hashCode() and toString() implementations.

Parameters:

resultSet - The result set to load data from.

columnIndex - The index of the column to load data from.

Returns:

An object appropriate to the type of data being handled that is obtained by loading data from the specified column of the specified result set. This may be null if the data is null.

Throws:

java.sql.SQLException - If a SQL exception occurs while loading data.

postProcessBind

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

This method is called when requiresBindPostProcessing() returns true to finish writing data to the database for which simple binding isn't sufficient. This is the case with LOB data, for example.

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.

Throws:

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

printNonNullValue

public java.lang.String printNonNullValue(java.lang.Object value)

This method should return a representation of the specified value that is appropriate for inclusion in a SQL script. The representation does not necessarily have to work reliably, particularly for large binary or character data values, because the scripts generated are a preview of the SQL that will be executed.

Parameters:

value - The object value to print, which is guaranteed to be non-null.

Returns:

A string containing a representation of the specified value appropriate for use in a SQL script.

requiresBindPostProcessing

public boolean requiresBindPostProcessing()

Returns true if writing of the data handled by this handler requires additional post-processing of the bind step. This is the case, for example, with LOB data, which can not be simply bound. If this returns true, then postProcessBind(java.sql.Connection, java.util.List, java.lang.Object) will be called after the initial INSERT or UDPATE statement that handled the bind step is executed.

Returns:

True if writing of the data handled by this handler require additional post-processing of the bind step.

requiresStreamedLoading

public boolean requiresStreamedLoading()

Returns true if the loading of this data requires streaming outside the standard result set, which is true for LOB data. The loading of streamed data can be sped up by loading it using parallel worker threads outside the main load query.

Returns:

True if the loading of this data requires streaming outside the standard result set.