com.ibm.db.beans
Class DBSelectMetaData

java.lang.Object
  |
  +--com.ibm.db.beans.DBSelectMetaData
All Implemented Interfaces:
java.io.Serializable

public class DBSelectMetaData
extends java.lang.Object
implements java.io.Serializable

This class allows you to get and set meta-data about a result set produced by a DBSelect or DBProcedureCall bean. The meta-data exposes JDBC 2.0 RowSetMetaData functionality and adds its own useful functions.

The java.sql.ResultSetMetaData object allows you to get meta data about a result set after it has been prepared (and possibly executed). The javax.sql.RowSetMetaData object extends that interface by allowing you to set meta data about a result set. The DBSelectMetaData object adds additional function to allow you to specify what java class should be used to store values of a column, to specify the table you plan to update using the result set, to specify which columns should be updatable, and to identify "key" columns in the result set that can be used to uniquely identify a row.

There is no public constructor for DBSelectMetaData. A DBSelect is created with a DBSelectMetaData, which you can get with getMetaData(). A DBProcedureCall is not created with a DBSelectMetaData, since the stored procedure may not return a result set. Use DBProcedureCall.createMetaData() to create one.

You can set meta data before actually executing a statement to change the way your result data will be stored. Or you can simply allow the meta data to be filled in for you after you execute a statement. You can also provide meta data "sparsely", specifing information only for those columns and characteristics which you want to override.

Convenience methods are provided that allow you specify multiple characteristics at once for a column not previously described. (setColumn) Or, if you want to provide information more sparsely, you can just call individual methods to set one characteristic of one column at a time. You can use these same more granular methods to change a description you have previously provided. You can describe columns in any order. The position of the column in the result set is determined by the index used to call the methods that describe it.

You can also get a reference to the java.sql.ResultSetMetaData which this bean contains and use it to access the full set of methods available on that object.

See Also:
Serialized Form

Method Summary
 void clear()
          Clears the descriptions of all columns in this result set.
 java.lang.String getCatalogName(int column)
          Gets the catalog name of the table of the specified column.
 java.lang.Class getColumnClass(int column)
          Gets the Java class to be used when getting or setting values for this column.
 int getColumnCount()
          Gets the number of columns in this RowSet.
 java.lang.String getColumnLabel(int column)
          Gets the label for this column, which may be different from its name.
 java.lang.String getColumnName(int column)
          Gets a column's name.
 int getColumnNumber(java.lang.String name)
          Gets the number of a column based on its label.
 int getColumnType(int column)
          Gets a column's SQL type.
 java.sql.ResultSetMetaData getResultSetMetaData()
          Gets a reference to the java.sql.ResultSetMetaData object obtained when the associated statement was executed.
 int getScale(int column)
          Gets the number of digits to the right of the decimal point.
 java.lang.String getSchemaName(int column)
          Gets the table schema of this column.
 java.lang.String getTableForUpdate()
          Gets the name of the table to be the target for Update, Insert, and Delete statements generated by the DBSelect bean.
 java.lang.String getTableName(int column)
          Gets the table name of this column.
 boolean isKey(int column)
          Indicates whether this column belongs to a set of columns that can uniquely identify a row in the result set.
 boolean isUpdateEnabled(int column)
          Indicates whether to allow values in this column to be set and then updated in the database using an associated DBSelect or DBProcedureCall.
 boolean isWritable(int column)
          Indicates whether it is possible to use the associated DBSelect or DBProcedureCall to change database values in this column.
 void setCatalogName(int column, java.lang.String name)
          Sets the catalog name of the table of the specified column.
 void setColumn(int column, java.lang.String name, java.lang.String label, java.lang.Class aClass, boolean updateEnabled)
          Adds the definition of a new column to this bean.
 void setColumnClass(int column, java.lang.Class aClass)
          Sets the Java class to be used when getting or setting values for this column.
 void setColumnLabel(int column, java.lang.String label)
          Sets the label for this column, which may be different from its name.
 void setColumnName(int column, java.lang.String aName)
          Sets the name for this column.
 void setKey(int column, boolean isKey)
          Sets specification of whether this column belongs to a set of columns that can uniquely identify a row in the result set.
 void setScale(int column, int scale)
          Sets the number of digits to the right of the decimal point for this column.
 void setSchemaName(int column, java.lang.String name)
          Sets the schema name of the table of this column The index of the first column is 1.
 void setTableForUpdate(java.lang.String name)
          Specifies the name of the table to be the target for Update, Insert, and Delete statements generated by the DBSelect bean.
 void setTableName(int column, java.lang.String name)
          Sets the name of the table of this column.
 void setUpdateEnabled(int column, boolean updateEnabled)
          Sets specification of whether to allow values in this column to be set and then updated in the database using an associated DBSelect or DBProcedureCall.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

clear

public void clear()
Clears the descriptions of all columns in this result set.

See Also:
setColumn(int, java.lang.String, java.lang.String, java.lang.Class, boolean)

getCatalogName

public java.lang.String getCatalogName(int column)
                                throws DBException,
                                       java.sql.SQLException
Gets the catalog name of the table of the specified column. The index of the first column is 1.

Parameters:
column - the index of the column
Returns:
catalog name or "" if not applicable.
Throws:
DBException - columnNotDefined - if no column has been defined in this position
java.sql.SQLException - if a database access error occurs
See Also:
setCatalogName(int, java.lang.String)

getColumnClass

public java.lang.Class getColumnClass(int column)
                               throws DBException,
                                      java.sql.SQLException
Gets the Java class to be used when getting or setting values for this column. The index of the first column is 1.

Parameters:
column - the column number
Returns:
the Java class
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setColumnClass(int, java.lang.Class)

getColumnCount

public int getColumnCount()
                   throws java.sql.SQLException
Gets the number of columns in this RowSet. If information has been specified sparsely (for only some columns) in this bean, the value returned is the number of the last column for which information has been specified.

Returns:
the number of columns
Throws:
java.sql.SQLException - if a database access error occurs

getColumnLabel

public java.lang.String getColumnLabel(int column)
                                throws DBException,
                                       java.sql.SQLException
Gets the label for this column, which may be different from its name. The index of the first column is 1. The label is guaranteed to be unique (without qualification by the table name, etc.) within the columns defined in this bean. If you do not specify a label, it defaults to the column name.

If you allow the name and label to be filled in when the statement executes, and the unqualified column name is not unique, the label will be suffixed with a number to make it unique.

In methods of DBSelect and DBProcedureCall that access columns by "name", it is actually the column label that is being matched.

Parameters:
column - the column number
Returns:
the column label
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setColumnLabel(int, java.lang.String), getColumnName(int)

getColumnName

public java.lang.String getColumnName(int column)
                               throws DBException,
                                      java.sql.SQLException
Gets a column's name. The index of the first column is 1. The name returned is the unqualified name. The name of its table, schema, and catalog (if known) are returned in getTableName, getSchemaName, and getCatalogName.

In methods of DBSelect and DBProcedureCall that access columns by "name", it is actually the column label that is being matched. (Uniqueness of the label without qualification by table name, etc. is enforced.)

Parameters:
column - the column number
Returns:
the column name
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setColumnName(int, java.lang.String), getTableName(int), getSchemaName(int), getCatalogName(int), getColumnLabel(int)

getColumnNumber

public int getColumnNumber(java.lang.String name)
                    throws DBException
Gets the number of a column based on its label. The number of the first column is 1.

Parameters:
name - the label of the column
Returns:
the column number
Throws:
DBException - columnNotDefined - if no column has been defined with this label
See Also:
getColumnLabel(int), getColumnName(int)

getColumnType

public int getColumnType(int column)
                  throws DBException,
                         java.sql.SQLException
Gets a column's SQL type. The number of the first column is 1.

Parameters:
column - the column number
Returns:
SQL type from java.sql.Types
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
Types

getResultSetMetaData

public java.sql.ResultSetMetaData getResultSetMetaData()
Gets a reference to the java.sql.ResultSetMetaData object obtained when the associated statement was executed. Until the statement has been executed, this returns a null value.

Returns:
a java.sql.ResultSetMetaData object

getScale

public int getScale(int column)
             throws DBException,
                    java.sql.SQLException
Gets the number of digits to the right of the decimal point. The index of the first column is 1. This value is only used for columns whose SQL type is decimal.

Parameters:
column - the column number
Returns:
the column scale
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setScale(int, int)

getSchemaName

public java.lang.String getSchemaName(int column)
                               throws DBException,
                                      java.sql.SQLException
Gets the table schema of this column. The index of the first column is 1.

Parameters:
column - the column number
Returns:
schema name or "" if not applicable
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setSchemaName(int, java.lang.String)

getTableForUpdate

public java.lang.String getTableForUpdate()
Gets the name of the table to be the target for Update, Insert, and Delete statements generated by the DBSelect bean.

The name may be the unqualified table name, or may be qualified. It will be substituted exactly as specified into Update, Insert, or Delete statements.

Returns:
name of the table to update
See Also:
setTableForUpdate(java.lang.String)

getTableName

public java.lang.String getTableName(int column)
                              throws DBException,
                                     java.sql.SQLException
Gets the table name of this column. The index of the first column is 1.

Parameters:
column - the column number
Returns:
table name or "" if not applicable
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setTableName(int, java.lang.String)

isKey

public boolean isKey(int column)
              throws DBException
Indicates whether this column belongs to a set of columns that can uniquely identify a row in the result set. The index of the first column is 1.

If you identify one or more columns as belonging to a "key", when the associated DBSelect or DBProcedureCall bean attempts to locate a row in order to lock it, update it, delete it, etc., it will use the key columns to do so. Otherwise, it will use all of the columns to locate the row, which is a less efficient process.

You may identify one or more columns as the "key" even if no key is actually declared in the database. You should do so only if you are certain that these columns can uniquely identify a row.

Parameters:
column - the column number
Returns:
true if the column belongs to a "key"; false otherwise
Throws:
DBException - columnNotDefined - if no column has been defined at this position
See Also:
setKey(int, boolean)

isUpdateEnabled

public boolean isUpdateEnabled(int column)
                        throws DBException,
                               java.sql.SQLException
Indicates whether to allow values in this column to be set and then updated in the database using an associated DBSelect or DBProcedureCall. The index of the first column is 1.

If this value is false, you will not be allowed to set a value in this column via the associated DBSelect or DBProcedureCall bean even if the associated bean itself is not readOnly.

If this value is true, you will be allowed to set a value in this column via the associated DBSelect or DBProcedureCall as long as the associated bean is not readOnly.

Parameters:
column - the column number
Returns:
true if values are allowed to be set; false if values are not allowed to be set By default, updateEnabled is true.
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setUpdateEnabled(int, boolean), isWritable(int), DBSelect.isReadOnly()

isWritable

public boolean isWritable(int column)
                   throws DBException,
                          java.sql.SQLException
Indicates whether it is possible to use the associated DBSelect or DBProcedureCall to change database values in this column. The index of the first column is 1.

This value is true if you have not disabled the setting of values via the setUpdateEnabled method and the associated DBSelect or DBProcedureCall bean is not readOnly, and the database allows writes to this column.

Parameters:
column - the column number
Returns:
true if column values can be changed in the database; false otherwise
Throws:
DBException - columnNotDefined - if no column has been defined at this position
java.sql.SQLException - if a database access error occurs
See Also:
setUpdateEnabled(int, boolean), DBSelect.isReadOnly()

setCatalogName

public void setCatalogName(int column,
                           java.lang.String name)
                    throws DBException,
                           java.sql.SQLException
Sets the catalog name of the table of the specified column. The index of the first column is 1.

Parameters:
column - the column number
name - the catalog name
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
java.sql.SQLException - if a database access error occurs
See Also:
getCatalogName(int)

setColumn

public void setColumn(int column,
                      java.lang.String name,
                      java.lang.String label,
                      java.lang.Class aClass,
                      boolean updateEnabled)
               throws DBException,
                      java.sql.SQLException
Adds the definition of a new column to this bean. This is a convenience method that allows you specify multiple characteristics of the column at once rather than separately calling several other methods to set them.

When you call this method, there must be no column currently defined in the position you specify. The index of the first column is 1.

The characteristics you can specify are those you would specify via the methods setColumnName, setColumnLabel, setColumnClass, and setUpdateEnabled.

Parameters:
column - the column number
name - the column name String, may be null
label - the column label String, may be null
aClass - the java class to be used for column values
updateEnabled - whether to allow column values to be set
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
DBException - columnAlreadyDefined - if a column is already defined at the specified position
DBException - duplicateColumn - if a column with this label has already been defined
java.sql.SQLException
See Also:
setColumnName(int, java.lang.String), setColumnLabel(int, java.lang.String), setColumnClass(int, java.lang.Class), setUpdateEnabled(int, boolean)

setColumnClass

public void setColumnClass(int column,
                           java.lang.Class aClass)
                    throws DBException,
                           java.sql.SQLException
Sets the Java class to be used when getting or setting values for this column. The index of the first column is 1.

Parameters:
column - the column number
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
java.sql.SQLException - if a database access error occurs
See Also:
getColumnClass(int)

setColumnLabel

public void setColumnLabel(int column,
                           java.lang.String label)
                    throws DBException,
                           java.sql.SQLException
Sets the label for this column, which may be different from its name. The index of the first column is 1. Uniqueness of the label (without qualification by the table name, etc.) is enforced within the columns defined in this bean. If you do not specify a label, it defaults to the column name.

If you allow the name and label to be filled in when the statement executes, and the unqualified column name is not unique, the label will be suffixed with a number to make it unique.

In methods of DBSelect and DBProcedureCall that access columns by "name", it is actually the column label that is being matched.

Parameters:
column - the column number
label - the column label String
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
DBException - duplicateColumn - if a column with the specified label has already been defined
java.sql.SQLException - if a database access error occurs
See Also:
getColumnLabel(int), setColumnName(int, java.lang.String)

setColumnName

public void setColumnName(int column,
                          java.lang.String aName)
                   throws DBException,
                          java.sql.SQLException
Sets the name for this column. The index of the first column is 1. The name specified is the unqualified name. The name of its table, schema, and catalog (if known) are set via setTableName, setSchemaName, and setCatalogName. If you do not specify a name, it will be filled in when the statement executes.

In methods of DBSelect and DBProcedureCall that access columns by "name", it is actually the column label that is being matched.

If you set the column name, and its label is null, the label will automatically be set to the name value. Note that the label must be unique without qualification by the table name, schema name, etc.

Parameters:
column - the column number
aName - the column name String
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
DBException - duplicateColumn - if a column with the specified label has already been defined
java.sql.SQLException - if a database access error occurs
See Also:
getColumnName(int), setColumnLabel(int, java.lang.String)

setKey

public void setKey(int column,
                   boolean isKey)
            throws DBException,
                   java.sql.SQLException
Sets specification of whether this column belongs to a set of columns that can uniquely identify a row in the result set. The index of the first column is 1.

If you identify one or more columns as belonging to a "key", when the associated DBSelect or DBProcedureCall bean attempts to locate a row in order to lock it, update it, delete it, etc., it will use the key columns to do so. Otherwise, it will use all of the columns to locate the row, which is a less efficient process.

You may identify one or more columns as the "key" even if no key is actually declared in the database. You should do so only if you are certain that these columns can uniquely identify a row.

Parameters:
column - the column number
isKey - true if the column belongs to a "key"; false otherwise
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
java.sql.SQLException - if a database access error occurs
See Also:
isKey(int)

setScale

public void setScale(int column,
                     int scale)
              throws DBException,
                     java.sql.SQLException
Sets the number of digits to the right of the decimal point for this column. The index of the first column is 1. This value is only used for columns whose SQL type is decimal.

Parameters:
column - the column number
scale - the number of digits to the right of the decimal point
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
java.sql.SQLException - if a database access error occurs
See Also:
getScale(int)

setSchemaName

public void setSchemaName(int column,
                          java.lang.String name)
                   throws DBException,
                          java.sql.SQLException
Sets the schema name of the table of this column The index of the first column is 1.

Parameters:
column - the column number
name - the schema name.
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
java.sql.SQLException - if a database access error occurs
See Also:
getSchemaName(int)

setTableForUpdate

public void setTableForUpdate(java.lang.String name)
                       throws DBException
Specifies the name of the table to be the target for Update, Insert, and Delete statements generated by the DBSelect bean. If you do not provide a table name, the query will be parsed to determine what name to use.

The name may be the unqualified table name, or may be qualified. It will be substituted exactly as specified into Update, Insert, or Delete statements.

Parameters:
name - name of the table to update
DBException
See Also:
getTableForUpdate()

setTableName

public void setTableName(int column,
                         java.lang.String name)
                  throws DBException,
                         java.sql.SQLException
Sets the name of the table of this column. The index of the first column is 1.

Parameters:
column - the column number
name - the table name.
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
java.sql.SQLException - if a database access error occurs
See Also:
getTableName(int)

setUpdateEnabled

public void setUpdateEnabled(int column,
                             boolean updateEnabled)
                      throws DBException,
                             java.sql.SQLException
Sets specification of whether to allow values in this column to be set and then updated in the database using an associated DBSelect or DBProcedureCall. The index of the first column is 1.

If you set this value to false, you will not be allowed to set a value in this column via the associated DBSelect or DBProcedureCall bean even if the associated bean itself is not readOnly.

If you set this value to true, you will be allowed to set a value in this column via the associated DBSelect or DBProcedureCall as long as the associated bean is not readOnly.

By default, updateEnabled is true.

Parameters:
column - the column number
updateEnabled - true to allow values to be set; false to prevent values from being set
Throws:
DBException - invalidColumnNumber - if column number is invalid (less than 1)
java.sql.SQLException - if a database access error occurs
See Also:
isUpdateEnabled(int), isWritable(int), DBSelect.isReadOnly()