org.jdesktop.dataset.io.schema
Class JDBCDataSetSchemaReader

java.lang.Object
  extended by org.jdesktop.dataset.io.schema.JDBCDataSetSchemaReader
All Implemented Interfaces:
DataSetSchemaReader

public class JDBCDataSetSchemaReader
extends java.lang.Object
implements DataSetSchemaReader

An JDBCDataSetSchemaReader instantiates a DataSet from a schema stored in an XML file; the schema is read from the JDBC metadata classes (see DatabaseMetaData and ResultSetMetaData), and the accuracy of the schema depends on the quality of the JDBC driver used.

Each instance of JDBCDataSetSchemaReader works against a single JDBCDataConnection connected to through a JDBC driver to a JDBC datasource (presumably a relational database). Once instantiated against that JDBCConnection, the reader methods (e.g. readDataSet()) may be used to load the DataSet. DataSetSchemaReader classes do not load data, only the DataSet schema. Typical usage: JDBCDataConnection jdbcConn = new JDBCDataConnection("org.apache.derby.jdbc.EmbeddedDriver", "jdbc:derby:testDB", "sa", ""); JDBCDataSetSchemaReader reader = new JDBCDataSetSchemaReader(jdbcConn); DataSet dataSet = reader.readDataSet();

You can also use the one-line methods in DataSetUtility, such as DataSetUtility.readDataSetFromJDBC(JDBCDataConnection).

Author:
Adam Barclay, Patrick Wright

Constructor Summary
JDBCDataSetSchemaReader(JDBCDataConnection jdbcConn)
          Instantiates a new JDBCDataSetSchemaReader for a JDBCDataConnection to a JDBC data source, presumably a relational database, using the default catalog and schema as understood by the JDBC driver (e.g.
JDBCDataSetSchemaReader(JDBCDataConnection jdbcConn, java.lang.String catalog, java.lang.String schema)
          Instantiates a new JDBCDataSetSchemaReader, for a JDBCDataConnection to a JDBC data source, presumably a relational database, for a given catalog and schema in that database.
 
Method Summary
 java.util.List<java.lang.String> addRelations(DataSet dataSet, java.lang.String... tableNames)
          Adds all DataRelation for the named DataTable to the specified DataSet, as read from the schema which this reader is reading from.
 java.util.List<java.lang.String> addTables(DataSet dataSet, java.lang.String... tableNames)
          Appends one or more DataTable to a DataSet from the schema represented by this reader.
protected  java.lang.String getTableSelectNoRowsCommand(java.lang.String tableName, java.util.List<java.lang.String> columnNames)
          Returns the SELECT statement used to query the given table, without rows being returned; this may vary between databases.
 DataSet readDataSet()
          Instantiates a new DataSet from the JDBCDataConnection specified in the constructor.
 DataSet readDataSet(java.lang.String... tableNames)
          Instantiates a new DataSet from the JDBCDataConnection specified in the constructor, for the tables and columns given in the tableNames parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JDBCDataSetSchemaReader

public JDBCDataSetSchemaReader(JDBCDataConnection jdbcConn)
Instantiates a new JDBCDataSetSchemaReader for a JDBCDataConnection to a JDBC data source, presumably a relational database, using the default catalog and schema as understood by the JDBC driver (e.g. null). The data connection cannot be changed once the reader is instantiated. The connection will be opened as necessary to read the metadata, and returned to its orignal connection state after reading. As the JDBC connections are not necessarily thread-safe, calling classes should synchronize around the schema loading process. See class documentation for more details.

Parameters:
jdbcConn - A JDBCDataConnection.

JDBCDataSetSchemaReader

public JDBCDataSetSchemaReader(JDBCDataConnection jdbcConn,
                               java.lang.String catalog,
                               java.lang.String schema)
Instantiates a new JDBCDataSetSchemaReader, for a JDBCDataConnection to a JDBC data source, presumably a relational database, for a given catalog and schema in that database. The data connection cannot be changed once the reader is instantiated. The connection will be opened as necessary to read the metadata, and returned to its orignal connection state after reading. As the JDBC connections are not necessarily thread-safe, calling classes should synchronize around the schema loading process. See class documentation for more details.

Parameters:
catalog - Name of the catalog to read the schema from. The meaning of "catalog" is RDBMS-dependent; consult the documentation for your data source and JDBC driver.
schema - Name of the schema to read the DataSet schema from. The meaning of "schema" is RDBMS-dependent; consult the documentation for your data source and JDBC driver.
jdbcConn - A JDBCDataConnection.
Method Detail

readDataSet

public DataSet readDataSet()
                    throws SchemaReaderException
Instantiates a new DataSet from the JDBCDataConnection specified in the constructor. If the schema contains multiple DataTables or DataRelations, all of them are loaded from the schema into the new DataSet. Relations are read for a table using the DatabaseMetaData.getImportedKeys(String catalog, String schema, String tableName). For a relational database, this would mean a foreign key constraint on the table. If such metadata does not exist for table relations, you will need to create them yourself after instantiating the DataSet. This method is probably not thread-safe for multiple threads accessing the same JDBCDataConnection and underlying java.sql.Connection.

Specified by:
readDataSet in interface DataSetSchemaReader
Returns:
A new DataSet instantiated from the JDBCDataConnection specified for the implementing class, including all tables and relations in the schema.
Throws:
SchemaReaderException - If an error occurred while loading the schema.

readDataSet

public DataSet readDataSet(java.lang.String... tableNames)
                    throws SchemaReaderException
Instantiates a new DataSet from the JDBCDataConnection specified in the constructor, for the tables and columns given in the tableNames parameter. from the schema into the new DataSet. Relations are read for a table using the DatabaseMetaData.getImportedKeys(String catalog, String schema, String tableName). For a relational database, this would mean a foreign key constraint on the table. If such metadata does not exist for table relations, you will need to create them yourself after instantiating the DataSet. This method is probably not thread-safe for multiple threads accessing the same JDBCDataConnection and underlying java.sql.Connection.

Specified by:
readDataSet in interface DataSetSchemaReader
Parameters:
tableNames - One or more table names to load from the schema. Each name can be either a table, or a table and column, dot-separated. If no columns are specified, all columns in the table are read from the schema; if columns are listed, only those columns are loaded. DataRelations for those tables and columns loaded from the schema are also instantiated automatically through addRelations(org.jdesktop.dataset.DataSet, String...).
Returns:
A new DataSet instantiated from the JDBCDataConnection specified for the implementing class, including only the tables and columns listed in the tableNames parameter.
Throws:
SchemaReaderException - If an error occurred while loading the schema.

addTables

public java.util.List<java.lang.String> addTables(DataSet dataSet,
                                                  java.lang.String... tableNames)
                                           throws SchemaReaderException
Appends one or more DataTable to a DataSet from the schema represented by this reader. If the table, by name, is found in the DataSet, the table is skipped; if you want to re-add a table (for example, to pick up changes in table structure), drop the table from the DataSet before calling this method.

Specified by:
addTables in interface DataSetSchemaReader
Parameters:
dataSet - The DataSet to which to add the tables.
tableNames - One or more table names to load from the schema and add to the DataSet. Each name can be either a table, or a table and column, dot-separated. If no columns are specified, all columns in the table are read from the schema; if columns are listed, only those columns are loaded. DataRelations for those tables and columns are not loaded from the schema; to that end, use addRelations(DataSet, String...).
Returns:
A List of the table names that were actually found. You can check this to verify that all tables requested were loaded.
Throws:
SchemaReaderException - If an error occurred while loading the schema.

addRelations

public java.util.List<java.lang.String> addRelations(DataSet dataSet,
                                                     java.lang.String... tableNames)
                                              throws SchemaReaderException
Adds all DataRelation for the named DataTable to the specified DataSet, as read from the schema which this reader is reading from. All DataRelations for each table are dropped from the DataSet and re-added.

Specified by:
addRelations in interface DataSetSchemaReader
Parameters:
dataSet - The DataSet to which to add the relations.
tableNames - One or more table names for which to read relations from the schema. Only those relations for columns in the DataTable (as currently loaded) are added.
Returns:
A List of the DataRelation names loaded from the schema.
Throws:
SchemaReaderException - If an error occurred while loading the schema.

getTableSelectNoRowsCommand

protected java.lang.String getTableSelectNoRowsCommand(java.lang.String tableName,
                                                       java.util.List<java.lang.String> columnNames)
Returns the SELECT statement used to query the given table, without rows being returned; this may vary between databases. The default is to select "where 1 = 0". You may override this in a subclass to provide a database-specific SELECT command, e.g. "SELECT * FROM LIMIT 0".

Parameters:
tableName - The table from which to select.
columnNames - The columns to select for that table, null means all columns.
Returns:
A SELECT statement with no parameters, selecting from the table for the columns specified, and returning no rows.


Copyright © 2005 Sun Microsystems All Rights Reserved.