org.afcs.warts.db
Class ColumnDescription

java.lang.Object
  org.afcs.warts.db.ColumnDescription

public final class ColumnDescription

extends java.lang.Object

The ColumnDescription class stores information about a specific column in a database table. A TableDescription contains an list of ColumnDescription instances, one for each column.

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

Version:

Last Modified 28 August 2003

Author:

Warren Hedley ( whedley at sdsc dot edu )

Constructor Summary

ColumnDescription(java.lang.String name, int sqlType, java.lang.String sqlTypeName, int size, int decimalDigits, boolean isNullable, java.lang.String defaultValue)
Initialises a new instance with the specified information.

Method Summary

void	bindValue(java.sql.PreparedStatement statement, int variableIndex, java.lang.Object value) This method is responsible for binding the specified value to the specified index in the specified statement.
java.lang.String	describeFirstEquivalenceIssue(ColumnDescription anotherColumnDescription) Returns a text description of the first reason that can be found for this column not being equivalent to the specified column.
boolean	equals(java.lang.Object otherObj) Returns true if the specified object is a ColumnDescription instance that has an identical configuration to this one, where all fields other than column size are considered.
int	getDecimalDigits() Returns the number of digits allowed on the right of the decimal point in a numeric column.
java.lang.String	getDefaultValue() Returns the default value for the column, if one exists.
java.lang.String	getName() Returns the name of the column.
int	getSize() Returns the total width of the data that can be stored in this column for numeric and character data types (excluding CLOBs).
int	getSqlType() Returns the constant from java.sql.Types that was specified as the column type at initialisation.
java.lang.String	getSqlTypeName() Returns the data type name specified at initialisation, which is obtained from the column metadata.
int	hashCode() Returns a hashcode based on the configuration of this instance.
protected boolean	initializeDataHandler(TableDescription tableDescription) This is used during the initialization phase of an TableDescription instance to initialize a data handler for each column.
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	isNullable() Returns true if the column allows nulls.
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, delegating the operation to a datatype specific handler.
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	printValue(java.lang.Object value) This method returns a string containing a representation of the specified value appropriate for use in a SQL script.
boolean	requiresBindPostProcessing() Returns true if writing of the data contained in this column 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.
java.lang.String	toString() Returns a text description of the current instance that can be used for debugging purposes.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ColumnDescription

public ColumnDescription(java.lang.String name,
                         int sqlType,
                         java.lang.String sqlTypeName,
                         int size,
                         int decimalDigits,
                         boolean isNullable,
                         java.lang.String defaultValue)

Initialises a new instance with the specified information.

Parameters:

name - The name of the column.

sqlType - The type of data stored in the column, which will be one of the constants from java.sql.Types, and is obtained by querying the table metadata.

sqlTypeName - The name of the datatype stored in the column. This is database-specific, and is obtained by querying the table metadata.

size - The size of the column.

decimalDigits - The number of decimal digits (precision) of the column.

isNullable - Whether the column takes null values.

defaultValue - The default value of the column, if specified.

Throws:

java.lang.NullPointerException - If name or sqlTypeName is null.

Method Detail

getName

public java.lang.String getName()

Returns the name of the column.

Returns:

The name of the column.

getSqlType

public int getSqlType()

Returns the constant from java.sql.Types that was specified as the column type at initialisation. This type is always obtained from the column metadata.

Returns:

The column type as obtained from the column metadata.

getSqlTypeName

public java.lang.String getSqlTypeName()

Returns the data type name specified at initialisation, which is obtained from the column metadata.

Returns:

The column data type name as obtained from the column metadata.

getSize

public int getSize()

Returns the total width of the data that can be stored in this column for numeric and character data types (excluding CLOBs).

Returns:

The total width of the data that can be stored in this column.

getDecimalDigits

public int getDecimalDigits()

Returns the number of digits allowed on the right of the decimal point in a numeric column.

Returns:

The number of digits allowed on the right of the decimal point in a numeric column.

equals

public boolean equals(java.lang.Object otherObj)

Returns true if the specified object is a ColumnDescription instance that has an identical configuration to this one, where all fields other than column size are considered.

Column size is not considered because of a bug in the Oracle JDBC drivers that prevents the correct column size from being returned for character columns with character length semantics.

Parameters:

otherObj - The object to compare this instance to.

Returns:

True if the specified object is identical to this one.

describeFirstEquivalenceIssue

public java.lang.String describeFirstEquivalenceIssue(ColumnDescription anotherColumnDescription)

Returns a text description of the first reason that can be found for this column not being equivalent to the specified column. If equals(java.lang.Object) returns false for the same column, this is useful for finding out why. It will return null if the columns are equal.

Parameters:

anotherColumnDescription - The other column to compare the current instance to.

Returns:

A text description of the first reason that can be found for this column not being equivalent to the specified column, or null if they are equivalent.

Throws:

java.lang.NullPointerException - If anotherColumnDescription is null.

hashCode

public int hashCode()

Returns a hashcode based on the configuration of this instance. All configuration fields are included.

Column size is not considered because of a bug in the Oracle JDBC drivers that prevents the correct column size from being returned for character columns with character length semantics.

Returns:

A hashcode based on the configuration of this instance.

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.

isNullable

public boolean isNullable()

Returns true if the column allows nulls.

Returns:

True if the column allows nulls.

getDefaultValue

public java.lang.String getDefaultValue()

Returns the default value for the column, if one exists.

Returns:

The default value for the column.

bindValue

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

This method is responsible for binding the specified 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, or null.

Throws:

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

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, delegating the operation to a datatype specific handler.

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.

printValue

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

This method returns a string containing a representation of the specified value appropriate for use in a SQL script. In the case of a null value, the string 'NULL' will be returned. A warning will be logged if a null is passed to a non-nullable column.

Parameters:

value - The object value to print.

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 contained in this column 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 contained in this column 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.

toString

public java.lang.String toString()

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

Returns:

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

initializeDataHandler

protected boolean initializeDataHandler(TableDescription tableDescription)

This is used during the initialization phase of an TableDescription instance to initialize a data handler for each column. If no suitable data handler can be found for this column by DataHandlerFactory, then true is returned to indicate that the "null" handler is being used. The null handler is, of course, not much use for primary key columns.

Parameters:

tableDescription - The table containing the column.

Returns:

True if the data handler initialized is the "null" handler.

Throws:

java.lang.NullPointerException - If tableDescription is null.

java.lang.IllegalArgumentException - If tableDescription does not contain this column.