/* Copyright (c) 2001-2004, The HSQL Development Group
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * Neither the name of the HSQL Development Group nor the names of its
 * contributors may be used to endorse or promote products derived from this
 * software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG, 
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */


package org.hsqldb.jdbc;

import java.sql.ResultSetMetaData;
import java.sql.SQLException;

import org.hsqldb.HsqlProperties;
import org.hsqldb.Result;
import org.hsqldb.ResultConstants;
import org.hsqldb.Trace;
import org.hsqldb.Types;

// fredt@users 20040412 - removed DITypeInfo dependencies
// boucherb@users - 200404xx - removed unused imports;refinement for better
//                             usability of getColumnDisplaySize;
//                             javadoc updates

/**
 * 
 * An object that can be used to get information about the types
 * and properties of the columns in a ResultSet object.
 * The following code fragment creates the ResultSet
 * object rs, creates the ResultSetMetaData object rsmd,
 * and uses rsmd to find out how many columns rs has and whether the
 * first column in rs can be used in a WHERE clause.
 * 
 *
 * ResultSet rs = stmt.executeQuery("SELECT a, b, c FROM TABLE2");
 * ResultSetMetaData rsmd = rs.getMetaData();
 * int numberOfColumns = rsmd.getColumnCount();
 * boolean b = rsmd.isSearchable(1);
 *
 * 
 * 
 *
 * 
 * 

 * 
HSQLDB-Specific Information:
 

 *
 * HSQLDB supports a subset of the ResultSetMetaData interface.

 *
 * The JDBC specification for ResultSetMetaData is in part very
 * vague. This causes potential incompatibility between interpretations of the
 * specification as realized in different JDBC driver implementations. As such,
 * deciding to what degree reporting ResultSetMetaData is accurate has been
 * considered very carefully. Hopefully, the design decisions made in light of
 * these considerations have yeilded precisely the subset of full
 * ResultSetMetaData support that is most commonly needed and that is most
 * important, while also providing, under the most common use-cases, the
 * fastest access with the least overhead and the best comprimise between
 * speed, accuracy, jar-foootprint and retention of JDBC resources. 

 *
 * (fredt@users) 

 * (boucherb@users)

 * 
 * 
 *
 * @author boucherb@users
 * @version 1.7.2
 * @see jdbcStatement#executeQuery
 * @see jdbcStatement#getResultSet
 * @see java.sql.ResultSetMetaData
 */
public class jdbcResultSetMetaData implements ResultSetMetaData {

    /**
     * An array of objects, each of which represents the reported attributes
     * for  a single column of this object's parent ResultSet.
     */
    private jdbcColumnMetaData[] columnMetaData;

    /** The number of columns in this object's parent ResultSet. */
    private int columnCount;

    /**
     * Whether to use the underlying column name or label when reporting
     * getColumnName().
     */
    private boolean useColumnName;

    /**
     * If true, then timings for init() are printed
     * to the console.
     */
    private static final boolean TRACE = false;

    /**
     * Constructs a new jdbcResultSetMetaData object from the specified
     * jdbcResultSet and HsqlProprties objects.
     *
     * @param rs the jdbcResultSet object from which to construct a new
     *        jdbcResultSetMetaData object
     * @param props the HsqlProperties object from which to construct a
     *        new jdbcResultSetMetaData object
     * @throws SQLException if a database access error occurs
     */
    jdbcResultSetMetaData(jdbcResultSet rs,
                          HsqlProperties props) throws SQLException {
        init(rs, props);
    }

    /**
     * Constructs a new jdbcResultSetMetaData object from the specified
     * Result and HsqlProprties objects.
     *
     * @param r the Result object from which to construct a new
     *        jdbcResultSetMetaData object
     * @param props the HsqlProperties object from which to construct a
     *        new jdbcResultSetMetaData object
     * @throws SQLException if a database access error occurs
     */
    jdbcResultSetMetaData(Result r,
                          HsqlProperties props) throws SQLException {
        init(r, props);
    }

    /**
     * Initializes this jdbcResultSetMetaData object from the specified
     * jdbcResultSet and HsqlProperties objects.
     *
     * @param rs the jdbcResultSet object from which to initialize this
     *        jdbcResultSetMetaData object
     * @param props the HsqlProperties object from which to initialize this
     *        jdbcResultSetMetaData object
     * @throws SQLException if a database access error occurs
     */
    void init(jdbcResultSet rs, HsqlProperties props) throws SQLException {

        if (rs == null) {
            throw jdbcUtil.sqlException(Trace.GENERAL_ERROR,
                                        Trace.JDBC_NO_RESULT_SET_METADATA,
                                        null);
        }

        init(rs.rResult, props);
    }

    /**
     * Initializes this jdbcResultSetMetaData object from the specified
     * Result and HsqlProperties objects.
     *
     * @param r the Result object from which to initialize this
     *        jdbcResultSetMetaData object
     * @param props the HsqlProperties object from which to initialize this
     *        jdbcResultSetMetaData object
     * @throws SQLException if a database access error occurs
     */
    void init(Result r, HsqlProperties props) throws SQLException {

        jdbcColumnMetaData    cmd;
        int                   type;
        Result.ResultMetaData rmd;

        if (r == null) {
            throw jdbcUtil.sqlException(Trace.GENERAL_ERROR,
                                        Trace.JDBC_NO_RESULT_SET, null);
        }

        if (r.iMode != ResultConstants.DATA) {

            // implied: columnCount = 0;
            return;
        }

        columnCount    = r.getColumnCount();
        useColumnName  = props.isPropertyTrue("get_column_name");
        columnMetaData = new jdbcColumnMetaData[columnCount];
        rmd            = r.metaData;

        for (int i = 0; i < columnCount; i++) {
            cmd               = new jdbcColumnMetaData();
            columnMetaData[i] = cmd;

            // Typically, these null checks are not needed, but as
            // above, it is not _guaranteed_ that these values
            // will be non-null.   So, it is better to do the work
            // here than have to perform checks and conversions later.
            cmd.catalogName    = rmd.sCatalog[i] == null ? ""
                                                         : rmd.sCatalog[i];
            cmd.schemaName     = rmd.sSchema[i] == null ? ""
                                                        : rmd.sSchema[i];
            cmd.tableName      = rmd.sTable[i] == null ? ""
                                                       : rmd.sTable[i];
            cmd.columnName     = rmd.sName[i] == null ? ""
                                                      : rmd.sName[i];
            cmd.columnLabel    = rmd.sLabel[i] == null ? ""
                                                       : rmd.sLabel[i];
            cmd.columnType     = rmd.colType[i];
            cmd.columnTypeName = Types.getTypeString(cmd.columnType);
            cmd.isWritable     = rmd.isWritable[i];
            cmd.isReadOnly     = !cmd.isWritable;

            // default: cmd.isDefinitelyWritable = false;
            cmd.isAutoIncrement = rmd.isIdentity[i];
            cmd.isNullable      = rmd.nullability[i];
            type                = cmd.columnType;
            cmd.columnClassName = rmd.sClassName[i];

            if (cmd.columnClassName == null
                    || cmd.columnClassName.length() == 0) {
                cmd.columnClassName = Types.getColStClsName(type);
            }

            // Some tools, such as PowerBuilder, require that (for char and
            // varchar types, at any rate) getMaxDisplaySize returns a value
            // _at least_ as large as the length of the longest value in this
            // column of the result set, or else an internal error will occur
            // at retrieve time the instant a longer value is fetched.
            //
            // org.hsqldb.Types has been patched to retrieve, by default, either
            // a large-but-reasonable value or a value defined through system
            // properties that is expected to be unlikely to cause problems in
            // the majority of cases.
            if (Types.acceptsPrecisionCreateParam(type)) {
                if (rmd.colSize[i] == 0) {
                    cmd.columnDisplaySize = Types.getMaxDisplaySize(type);
                } else {
                    cmd.columnDisplaySize = rmd.colSize[i];
                }
            } else {
                cmd.columnDisplaySize = Types.getMaxDisplaySize(type);
            }

            // todo: declared scale (and precision?) across the network
            // for types that accept (precision, scale) declarations
            // We do not yet (will we ever?) enforce/consider
            // NUMERIC/DECIMAL precision
//            if (Types.isNumberType(type)
//                    &&Types.acceptsPrecisionCreateParam(type)
//             ) {
//                cmd.precision = rmd.colSize[i];
//                if (cmd.precision == 0) {
//                    cmd.precision = Types.getPrecision(type);
//                }
//            } else {
            cmd.precision = Types.getPrecision(type);

//            }
            // Without a non-zero scale value, some (legacy only?) tools will
            // simply truncate digits to the right of the decimal point when
            // retrieving values from the result set. The measure below can
            // help, but currently only as long as one is connected to an
            // embedded instance at design time, not via a network connection.
            if (Types.acceptsScaleCreateParam(type)) {
                cmd.scale = rmd.colScale[i];
            }

            Boolean iua = Types.isUnsignedAttribute(type);

            cmd.isSigned = iua != null &&!iua.booleanValue();

            Boolean ics = Types.isCaseSensitive(type);

            cmd.isCaseSensitive = ics != null && ics.booleanValue();
            cmd.isSearchable    = Types.isSearchable(type);
        }
    }

    /**
     * 
     * Returns the number of columns in this ResultSet
     * object. 

     * 
     * @return the number of columns
     * @exception SQLException if a database access error occurs
     */
    public int getColumnCount() throws SQLException {
        return columnCount;
    }

    /**
     * 
     * Indicates whether the designated column is automatically numbered,
     * thus read-only. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * HSQLDB 1.7.1 did not report this value accurately,
     * either always throwing or always returning false, depending
     * upon client property values.

     *
     * Starting with HSQLDB 1.7.2, this feature is better supported. 

     *
     * 

     *
     * However, it must be stated here that, contrary to the generic
     * documentation above, HSQLDB automatically numbered columns
     * (IDENTITY columns, in HSQLDB parlance) are not read-only. 

     *
     * In fact, the generic documentation above seems to contradict the general
     * definition of what, at minimum, an auto-increment column is: 

     *
     * Simply, an auto-increment column is one that guarantees it has a
     * unique value after a successful insert or update operation, even if
     * no value is supplied or NULL is explicitly specified by the application
     * or a default value expression. 

     *
     * Further, without SQL Feature T176, Sequence generator support, the
     * attributes of the internal source consulted for unique values are not
     * defined. That is, unlike for a standard SQL SEQUENCE object or a system
     * with full SQL 9x or 200n support for SQL Feature T174, Identity columns,
     * an application must not assume and cannot determine in a standard way
     * that auto-increment values start at any particular point, increment by
     * any particular value or have any of the other attributes generally
     * associated with SQL SEQUENCE generators. Further still, without full
     * support for both feature T174 and T176, if a unique value is supplied
     * by an application or provided by a declared or implicit default value
     * expression, then whether that value is used or substituted with one
     * from the automatic unique value  source is implementation-defined
     * and cannot be known in a standard way. Finally, without full support
     * for features T174 and T176, it is also implementation-defined and
     * cannot be know in a standard way whether an exception is thrown or
     * a unique value is automatically substituted when an application or
     * default value expression supplies a non-NULL,
     * non-unique value. 

     *
     * Up to and including HSQLDB 1.7.2, values supplied by an application or
     * default value expression are used if they are indeed non-NULL unique
     * values, while an exception is thrown if either possible value source
     * for the site attempts to supply a non-NULL, non-unique value.  This is
     * very likely to remain the behaviour of HSQLDB for its foreseable
     * lifetime and at the very least for the duration of the 1.7.x release
     * series.

     *
     * 

     *
     * Regardless of the new and better support for reporting
     * isAutoIncrement(), it is still possible under certain conditions that
     * accurate reporting may be impossible. For example, if this object's
     * parent Connection is closed before the first call to this method or to
     * any other method of this class that initializes the connection-dependent
     * ResultSetMetaData values, then it is impossible to report accurately for
     * result set columns that directly represent table column values.

     *
     * Under such special circumstances, the driver rethrows the exception that
     * occured during the initialization, or a SQLException wrapping it. 

     *
     * Those wishing to determine the auto-increment status of a table column
     * in isolation from ResultSetMetaData can do so by inspecting the
     * corresponding value of the SYSTEM_COLUMNS.IS_IDENTITY BOOLEAN column which
     * is also currently included (in a fashion proprietary to HSQLDB) as the
     * last column of the jdbcDatabaseMetaData.getColumns() result.
     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isAutoIncrement(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isAutoIncrement;
    }

    /**
     * 
     * Indicates whether a column's case matters. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * HSQLDB 1.7.1 did not report this value accurately.  

     *
     * Starting with 1.7.2, this feature is better supported.  

     *
     * This method returns true for any column whose data type is a character
     * type, with the exception of VARCHAR_IGNORECASE for which it returns
     * false. It also returns false for any column whose data type is a
     * not a character data type. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isCaseSensitive(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isCaseSensitive;
    }

    /**
     * 
     * Indicates whether the designated column can be used in a where
     * clause. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * HSQLDB 1.7.1 did not report this value accurately.  

     *
     * Starting with 1.7.2, this feature is better supported.  

     *
     * If the data type of the column is definitely known to be searchable
     * in any way under HSQLDB, then true is returned, else false.  That is,
     * if the type is reported in DatabaseMetaData.getTypeInfo() as having
     * DatabaseMetaData.typePredNone or is not reported, then false is
     * returned, else true.
     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isSearchable(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isSearchable;
    }

    /**
     * 
     * Indicates whether the designated column is a cash value. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to and including HSQLDB 1.7.2, this method always returns
     * false. 

     *
     * This is because true fixed (precision,scale) data types are not yet
     * supported.  That is, DECIMAL and NUMERIC types are implemented
     * as a thin wrap of java.math.BigDecimal, which cannot, without
     * additional, as yet unimplemented constraint enforcement code, be
     * said to be a fixed (precision,scale) types. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isCurrency(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isCurrency;
    }

    /**
     * 
     * Indicates the nullability of values in the designated column. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to 1.7.1, HSQLDB did not report this value accurately. 

     *
     * Starting with 1.7.2, this feature is better supported.  

     *
     * columnNullableUnknown is always returned for result set columns that
     * do not directly represent table column values (i.e. are calculated),
     * while the corresponding value in SYSTEM_COLUMNS.NULLABLE is returned
     * for result set columns that do directly represent table column values. 

     *
     * Those wishing to determine the nullable status of a table column in
     * isolation from ResultSetMetaData and in a DBMS-independent fashion
     * can do so by calling DatabaseMetaData.getColumns() with the appropriate
     * filter values and inspecting the result at the position described in
     * the API documentation. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return the nullability status of the given column; one of
     *      columnNoNulls,
     *      columnNullable or columnNullableUnknown
     * @exception SQLException if a database access error occurs
     */
    public int isNullable(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isNullable;
    }

    /**
     * 
     * Indicates whether values in the designated column are signed
     * numbers. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * HSQLDB 1.7.1 introduced support for this feature and 1.7.2
     * reports identical values (although using a slightly different
     * implementation).

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isSigned(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isSigned;
    }

    /**
     * 
     * Indicates the designated column's normal maximum width in
     * characters. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to and including HSQLDB 1.7.1, this method always returned
     * 0, which was intended to convey unknown display size.
     * Unfortunately, this value is not universally handled by all
     * clients and in the worst case can cause some applications to
     * crash. 

     *
     * Starting with 1.7.2, this feature is better supported.  

     *
     * The current calculation follows these rules: 

     *
     * 

     * 
Long character types and datetime types:

     *
     *     The maximum length/precision, repectively.

     *
     * 
CHAR and VARCHAR types: 

     *
     *      

     *      
 If the result set column is a direct pass through of a table
     *           column value, column size was declared and the connection is
     *           to an embedded database instance, then the declared value is
     *           returned.

     *
     *      
 Otherwise, the value of the system property
     *           hsqldb.max_xxxchar_display_size or the magic value
     *           32766 (0x7FFE) (tested usable/accepted by most tools and
     *           compatible with assumptions made by java.io read/write
     *           UTF) when the system property is not defined or is not
     *           accessible, due to security constraints. 

     *
     *      
     *
     *      It must be noted that the latter value in no way affects the
     *      ability of the HSQLDB JDBC driver to retrieve longer values
     *      and serves only as the current best effort at providing a
     *      value that maximizes usability across a wide range of tools,
     *      given that the HSQLDB database engine does not require the
     *      length to be declared and does not necessarily enforce it,
     *      even if declared. 

     *
     * 
Number types: 

     *
     *     The max precision, plus the length of the negation character (1),
     *     plus (if applicable) the maximum number of characters that may
     *     occupy the exponent character sequence.  Note that some legacy tools
     *     do not correctly handle BIGINT values of greater than 18 digits. 

     *
     * 
BOOLEAN (BIT) type: 

     *
     *     The length of the character sequence "false" (5), the longer of the
     *     two boolean value String representations. 

     *
     * 
Remaining types: 

     *
     *     The maximum length/precision, respectively, as reported by
     *     DatabaseMetaData.getTypeInfo(), when applicable.  If the maximum
     *     display size is unknown, unknowable or inapplicable, then zero is
     *     returned. 

     *
     * 
     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return the normal maximum number of characters allowed as the width
     *      of the designated column
     * @exception SQLException if a database access error occurs
     */
    public int getColumnDisplaySize(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].columnDisplaySize;
    }

    /**
     * 
     * Gets the designated column's suggested title for use in printouts and
     * displays. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * In HSQLDB a ResultSet column label is determined in the
     * following order of precedence:

     *
     * 

     * 
The label (alias) specified in the generating query.
     * 
The name of the underlying column, if no label is specified.

     *    This also applies to aggregate functions.
     * 
An empty String.
     * 
 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return the suggested column title
     * @exception SQLException if a database access error occurs
     */
    public String getColumnLabel(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].columnLabel;
    }

    /**
     * 
     * Get the designated column's name. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * In HSQLDB a ResultSet column name is determined in the following
     * order of prcedence:

     *
     * 

     * 
The name of the underlying columnm, if the ResultSet column
     *   represents a column in a table.
     * 
The label or alias specified in the generating query.
     * 
An empty String.
     * 
 

     *
     * If the jdbc.get_column_name property of the database
     * has been set to false, this method returns the same value as
     * {@link #getColumnLabel(int)}.

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return column name
     * @exception SQLException if a database access error occurs
     */
    public String getColumnName(int column) throws SQLException {

        checkColumn(column);

        column--;

        return useColumnName ? columnMetaData[column].columnName
                             : columnMetaData[column].columnLabel;
    }

    /**
     * 
     * Get the designated column's table's schema. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to 1.7.1, HSQLDB did not support the notion of schemas at all,
     * including schema names in result set metadata; this method always
     * returned "". 

     *
     * Staring with 1.7.2, schema name reporting is supported only as an
     * optional, experimental feature that is disabled by default.
     * Enabling this feature requires setting the database property
     * "hsqldb.schemas=true". 

     *
     * Specifically, when this feature is enabled under 1.7.2, only very
     * limited support is provided by the engine for executing SQL containing
     * schema-qualified database object identifiers.  That is, when this
     * feature is enabled under 1.7.2, it is not yet possible in most cases
     * to use what would otherwise be the correct, canonical SQL calculated
     * from ResultSetMetaData. 

     *
     * Regardless, reporting is done only in system table content and is
     * not yet carried over to ResultSetMetaData. 

     *
     * For greater detail, see discussion at:
     * {@link jdbcDatabaseMetaData}. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return schema name or "" if not applicable
     * @exception SQLException if a database access error occurs
     */
    public String getSchemaName(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].schemaName;
    }

    /**
     * 
     * Get the designated column's number of decimal digits. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to and including HSQLDB 1.7.1, this method always returned 0,
     * which was intended to convey that the precision was unknown,
     * undefined or that no applicable limit was
     * imposed. 

     *
     * Starting with 1.7.2, HSQLDB reports the maximum length or
     * precision intrinsic to the data type of each result set column. 

     *
     * This method does not yet make any attempt to report the declared
     * length or precision specifiers for table columns (if they are defined,
     * which up to 1.7.2 is not a requirement in DDL), as these values may or
     * may not be enforced, depending on the value of the database
     * property: 

     *
     * 
     * sql.enforce_size
     * 
     *
     * Because the property may change from one instantiation of a Database
     * to the next and because, when set true, is not applied to existing
     * values in table columns (only to new values introduced by following
     * inserts and updates), the length and/or precision specifiers for table
     * columns still do not neccessarily accurately reflect true constraints
     * upon the contents of the columns. This situation may or may not change
     * in a future release. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return precision
     * @exception SQLException if a database access error occurs
     */
    public int getPrecision(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].precision;
    }

    /**
     * 
     * Gets the designated column's number of digits to right of the
     * decimal point. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to and including HSQLDB 1.7.2, this method always returns 0
     * (which is the actual scale for integral types and is to be interpreted
     * as unknown or not applicable for all other
     * types). 

     *
     * HSQLDB currently implements DECIMAL and NUMERIC--the only HSQLDB
     * types to which this value would apply, if supported--as a thin wrap
     * of BigDecimal and thus does not presently ever enforce scale
     * declarations.  Those wishing to determine the declared--intended, but
     * not enforced--scale of a DECIMAL and NUMERIC table column should
     * instead consult the DatabaseMetaData.getColumns() result using the
     * required filter parameters. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return scale
     * @exception SQLException if a database access error occurs
     */
    public int getScale(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].scale;
    }

    /**
     * 
     * Gets the designated column's table name. 

     * 
     * @param column the first column is 1, the second is 2, ...
     * @return table name or "" if not applicable
     * @exception SQLException if a database access error occurs
     */
    public String getTableName(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].tableName;
    }

    /**
     * 
     * Gets the designated column's table's catalog name. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to and including 1.7.1, HSQLDB did not support the notion of
     * catalog and this method always returned "". 

     *
     * Starting with 1.7.2, HSQLDB supports catalog reporting only as an
     * optional, experimental feature that is disabled by default. Enabling
     * this feature requires setting the database property
     * "hsqldb.catalogs=true". When enabled, the catalog name for table columns
     * is reported as the name by which the hosting Database knows itself. 

     *
     * HSQLDB does not yet support any use of catalog qualification in
     * DLL or DML. This fact is accurately indicated in the corresponding
     * DatabaseMetaData.supportsXXX() method return values. 

     *
     * Regardless, reporting is done only in system table content and is
     * not yet carried over to ResultSetMetaData. 

     *
     * For greater detail, see discussion at:
     * {@link jdbcDatabaseMetaData}. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return the name of the catalog for the table in which the given column
     *      appears or "" if not applicable
     * @exception SQLException if a database access error occurs
     */
    public String getCatalogName(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].catalogName;
    }

    /**
     * 
     * Retrieves the designated column's SQL type. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * This reports the SQL type of the column. HSQLDB can return Objects in
     * any Java integral type wider than Integer for an SQL
     * integral type.

     *
     * 
     * 
     *
     *
     * @param column the first column is 1, the second is 2, ...
     * @return SQL type from java.sql.Types
     * @exception SQLException if a database access error occurs
     * @see java.sql.Types
     */
    public int getColumnType(int column) throws SQLException {

        checkColumn(column);

        int type = columnMetaData[--column].columnType;

        return type == Types.VARCHAR_IGNORECASE ? Types.VARCHAR
                                                : type;
    }

    /**
     * 
     * Retrieves the designated column's database-specific type name. 

     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return type name used by the database. If the column type is
     * a user-defined type, then a fully-qualified type name is returned.
     * @exception SQLException if a database access error occurs
     */
    public String getColumnTypeName(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].columnTypeName;
    }

    /**
     * 
     * Indicates whether the designated column is definitely not writable.

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to and including 1.7.1, HSQLDB did not report this value accurately.
     * 

     *
     * Starting with HSQLDB 1.7.2, this feature is better supported. 

     *
     * For result set columns that do not directly
     * represent table column values (i.e. are calculated), true is reported.
     * Otherwise, the read only status of the table and the database are used
     * in the calculation, but not the read-only status of the session. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isReadOnly(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isReadOnly;
    }

    /**
     * 
     * Indicates whether it is possible for a write on the designated
     * column to succeed. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * Up to and including 1.7.1, HSQLDB did not report this value accurately.
     * 

     *
     * Starting with HSQLDB 1.7.2, this feature is better supported. 

     *
     * In essense, the negation of isReadOnly() is reported. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isWritable(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].isWritable;
    }

    /**
     * 
     * Indicates whether a write on the designated column will definitely
     * succeed. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * HSQLDB 1.7.1 did not report this value accurately. 

     *
     * Starting with HSQLDB 1.7.2, this method always returns false. The
     * reason for this is that it is generally either very complex or
     * simply impossible to calculate deterministically true for table columns
     * under all concievable conditions. The value is of dubious usefulness, except
     * perhaps if there were support for updateable result sets using
     * "SELECT ... FOR UPDATE" style locking.  However, this is not anticipated to
     * occur any time in the 1.7.x release series. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return true if so; false otherwise
     * @exception SQLException if a database access error occurs
     */
    public boolean isDefinitelyWritable(int column) throws SQLException {

        checkColumn(column);

// NOTE:
// boucherb@users - 20020329
// currently, we can't tell _for sure_ that this is true without a
// great deal more work (and even then, not necessarily deterministically),
// plus it is of dubious usefulness to know this is true _for sure_ anyway.
// It's not like one can do an insert or update without a try-catch block
// using JDBC, even if one knows that a column is definitely writable.  And
// the catch will always let us know if there is a failure and why.  Also,
// it is typically completely useless to know that, although it is  _possible_
// that a write may succeed (as indicated by a true value of isWritable()),
// it also might fail (as indicated by a false returned here).
        // as of 1.7.2, always false
        return columnMetaData[--column].isDefinitelyWritable;
    }

    //--------------------------JDBC 2.0-----------------------------------

    /**
     * 
     * Returns the fully-qualified name of the Java class whose instances
     * are manufactured if the method ResultSet.getObject
     * is called to retrieve a value from the column.
     * ResultSet.getObject may return a subclass of the class
     * returned by this method. 

     * 
     *
     * 
     * 

     * 
HSQLDB-Specific Information:
 

     *
     * HSQLDB 1.7.1 did not support this feature; calling this method
     * always caused an SQLException to be thrown,
     * stating that the function was not supported. 

     *
     * 
     * 
     *
     * @param column the first column is 1, the second is 2, ...
     * @return the fully-qualified name of the class in the Java programming
     *      language that would be used by the method
     *      ResultSet.getObject to retrieve the value in the
     *      specified column. This is the class name used for custom mapping.
     * @exception SQLException if a database access error occurs
     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview for
     *      jdbcResultSet)
     */
    public String getColumnClassName(int column) throws SQLException {

        checkColumn(column);

        return columnMetaData[--column].columnClassName;
    }

    public String toString() {

        StringBuffer sb = new StringBuffer();

        sb.append(super.toString());

        if (columnCount == 0) {
            sb.append("[columnCount=0]");

            return sb.toString();
        }

        sb.append('[');

        for (int i = 0; i < columnCount; i++) {
            sb.append('\n');
            sb.append("   column_");
            sb.append(i + 1);
            sb.append('=');
            sb.append(columnMetaData[i]);

            if (i + 1 < columnCount) {
                sb.append(',');
                sb.append(' ');
            }
        }

        sb.append('\n');
        sb.append(']');

        return sb.toString();
    }

// ------------------------- Internal Implementation ---------------------------

    /**
     * Performs an internal check for column index validity. 

     *
     * @param column index of column to check
     * @throws SQLException when this object's parent ResultSet has
     *      no such column
     */
    private void checkColumn(int column) throws SQLException {

        if (column < 1 || column > columnCount) {
            throw jdbcUtil.sqlException(Trace.COLUMN_NOT_FOUND,
                                        String.valueOf(column));
        }
    }
}