org.hsqldb.jdbc.jdbcResultSetMetaData
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object
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:
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)
jdbcStatement.executeQuery(java.lang.String),
jdbcStatement.getResultSet(),
ResultSetMetaData| Field Summary | |
static int |
MAX_DISPLAY_SIZE
The maximum value that this object returns in response to calling getColumnDisplaySize(). |
static int |
MAX_SCAN
The maximum number of rows in this object's parent ResultSet that will be scanned to calculate an approximation of getColumnDisplaySize(), when the
value is not to be determined statically from the known maximum
length or precision of the column's data type. |
static int |
MIN_DISPLAY_SIZE
The minimum value that this object returns in response to calling getColumnDisplaySize(). |
| Fields inherited from interface java.sql.ResultSetMetaData |
columnNoNulls, columnNullable, columnNullableUnknown |
| Method Summary | |
String |
getCatalogName(int column)
Gets the designated column's table's catalog name. |
String |
getColumnClassName(int column)
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.
|
int |
getColumnCount()
Returns the number of columns in this ResultSet
object. |
int |
getColumnDisplaySize(int column)
Indicates the designated column's normal maximum width in characters. |
String |
getColumnLabel(int column)
Gets the designated column's suggested title for use in printouts and displays. |
String |
getColumnName(int column)
Get the designated column's name. |
int |
getColumnType(int column)
Retrieves the designated column's SQL type. |
String |
getColumnTypeName(int column)
Retrieves the designated column's database-specific type name. |
int |
getPrecision(int column)
Get the designated column's number of decimal digits. |
int |
getScale(int column)
Gets the designated column's number of digits to right of the decimal point. |
String |
getSchemaName(int column)
Get the designated column's table's schema. |
String |
getTableName(int column)
Gets the designated column's table name. |
boolean |
isAutoIncrement(int column)
Indicates whether the designated column is automatically numbered, thus read-only. |
boolean |
isCaseSensitive(int column)
Indicates whether a column's case matters. |
boolean |
isCurrency(int column)
Indicates whether the designated column is a cash value. |
boolean |
isDefinitelyWritable(int column)
Indicates whether a write on the designated column will definitely succeed. |
int |
isNullable(int column)
Indicates the nullability of values in the designated column. |
boolean |
isReadOnly(int column)
Indicates whether the designated column is definitely not writable. |
boolean |
isSearchable(int column)
Indicates whether the designated column can be used in a where clause. |
boolean |
isSigned(int column)
Indicates whether values in the designated column are signed numbers. |
boolean |
isWritable(int column)
Indicates whether it is possible for a write on the designated column to succeed. |
String |
toString()
|
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
public static final int MIN_DISPLAY_SIZE
getColumnDisplaySize().
public static final int MAX_DISPLAY_SIZE
getColumnDisplaySize().
public static final int MAX_SCAN
getColumnDisplaySize(), when the
value is not to be determined statically from the known maximum
length or precision of the column's data type.
| Method Detail |
public int getColumnCount()
throws SQLException
ResultSet
object.
getColumnCount in interface ResultSetMetaDataSQLException - if a database access error occurs
public boolean isAutoIncrement(int column)
throws SQLException
HSQLDB-Specific Information:
HSQLDB 1.7.1 did not support accurately reporting this value,
either always throwing or always returning false, depending
upon client property values.
Starting with HSQLDB 1.7.2, this feature is better supported.
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.
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.
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.
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.
isAutoIncrement in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public boolean isCaseSensitive(int column)
throws SQLException
HSQLDB-Specific Information:
HSQLDB 1.7.1 did not support accurately reporting this value.
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.
isCaseSensitive in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public boolean isSearchable(int column)
throws SQLException
HSQLDB-Specific Information:
HSQLDB 1.7.1 did not support accurately reporting this value.
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.
isSearchable in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public boolean isCurrency(int column)
throws SQLException
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.
isCurrency in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public int isNullable(int column)
throws SQLException
HSQLDB-Specific Information:
Up to 1.7.1, HSQLDB did not support accurately reporting this
value.
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.
isNullable in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
columnNoNulls,
columnNullable or columnNullableUnknown
SQLException - if a database access error occurs
public boolean isSigned(int column)
throws SQLException
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).
isSigned in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public int getColumnDisplaySize(int column)
throws SQLException
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.
For colums whose data type has a known maximum display size (not zero),
the following rules apply:
In the standard distribution, MIN_DISPLAY_SIZE is 6, the minimum number
of characters required to display a character sequence representing the
Java String representation of null, bracketed with two additional
characters (e.g. "(null)"), while MAX_DISPLAY_SIZE is 255, the typical
maximum size for character display in graphical presentation
manangers.
In all other cases, up to the first MAX_SCAN (512 in the standard
distribution) rows of the result set are scanned to calculate an
approximation of the maximum width, in characters, that would be
required to display the column's data if each value were retrieved
as a Java String using ResultSet.getString(). If the scan at any time
determines that the approximation will result in a value greater than
or equal to MAX_DISPLAY_SIZE, then the scan is terminated and
MAX_DISPLAY_SIZE is reported. Othersize, the fully approximated
display size is reported. MIN_DISPLAY_SIZE is reported if the scan
encounters that the parent result set has no rows, while the minimum
value calculated by the approximation is also MIN_DISPLAY_SIZE, in the
case where the first MAX_SCAN (or fewer) values of the column are all
null, zero-length or less than MIN_DISPLAY_SIZE characters when
retreived using ResultSet.getString().
getColumnDisplaySize in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public String getColumnLabel(int column)
throws SQLException
HSQLDB-Specific Information:
In HSQLDB a
ResultSet column label is determined in the
following order of precedence:
This also applies to aggregate functions.String.
getColumnLabel in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public String getColumnName(int column)
throws SQLException
HSQLDB-Specific Information:
In HSQLDB a ResultSet column name is determined in the following
order of prcedence:
If the
String.jdbc.get_column_name property of the database
has been set to false, this method returns the same value as
getColumnLabel(int).
getColumnName in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public String getSchemaName(int column)
throws SQLException
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:
jdbcDatabaseMetaData.
getSchemaName in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public int getPrecision(int column)
throws SQLException
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.
getPrecision in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public int getScale(int column)
throws SQLException
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.
getScale in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public String getTableName(int column)
throws SQLException
getTableName in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public String getCatalogName(int column)
throws SQLException
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:
jdbcDatabaseMetaData.
getCatalogName in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public int getColumnType(int column)
throws SQLException
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.
getColumnType in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occursTypes
public String getColumnTypeName(int column)
throws SQLException
getColumnTypeName in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
SQLException - if a database access error occurs
public boolean isReadOnly(int column)
throws SQLException
HSQLDB-Specific Information:
Up to and including 1.7.1, HSQLDB did not support accurately reporting
this value.
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.
isReadOnly in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public boolean isWritable(int column)
throws SQLException
HSQLDB-Specific Information:
Up to and including 1.7.1, HSQLDB did not support accurately reporting
this value.
Starting with HSQLDB 1.7.2, this feature is better supported.
In essense, the negation of isReadOnly() is reported.
isWritable in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public boolean isDefinitelyWritable(int column)
throws SQLException
HSQLDB-Specific Information:
HSQLDB 1.7.1 did not support reporting 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.
isDefinitelyWritable in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
true if so; false otherwise
SQLException - if a database access error occurs
public String getColumnClassName(int column)
throws SQLException
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.
getColumnClassName in interface ResultSetMetaDatacolumn - the first column is 1, the second is 2, ...
ResultSet.getObject to retrieve the value in the
specified column. This is the class name used for custom mapping.
SQLException - if a database access error occurspublic String toString()
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||