org.jdesktop.dataset.util
Class DataSetUtility

java.lang.Object
  extended by org.jdesktop.dataset.util.DataSetUtility

public class DataSetUtility
extends java.lang.Object

DataSetUtility holds static methods for working with the org.jdesktop.dataset package. Currently there are methods for importing or exporting a DataSet schema.

Author:
Richard Bair, Adam Barclay, Patrick Wright

Constructor Summary
DataSetUtility()
           
 
Method Summary
static DataSet createDataSetSchema(JDBCDataConnection conn, java.lang.String... names)
          Creates a DataSet that contains a DataTable for each table that has been specified in the given names Set.
static void createDataTableSchema(JDBCDataConnection jdbcConn, DataSet ds, java.lang.String tableName, java.lang.String statement)
          Creates a new DataTable in the specified DataSet that maps directly to one returned from a custom SELECT query.
static void createRelations(JDBCDataConnection jdbcConn, DataSet ds)
          Creates any relations that exist between the tables in the given DataSet using the database metadata that can be retrieved using the given SQL Connection.
static void main(java.lang.String[] args)
           
static DataSet readDataSet(DataSetSchemaReader reader)
          Loads a DataSet schema using a schema reader, for all tables and relations declared in the schema.
static DataSet readDataSet(DataSetSchemaReader reader, java.lang.String... tableNames)
          Loads a DataSet schema using a schema reader, for the tables listed in the tableNames argument, and their relations.
static DataSet readDataSetFromJDBC(JDBCDataConnection jdbcConn)
          Loads a DataSet schema from a JDBC data connection, using JDBC metadata, for all tables and relations declared in the schema.
static DataSet readDataSetFromJDBC(JDBCDataConnection jdbcConn, java.lang.String... tableNames)
          Loads a DataSet schema from a JDBC data connection, using JDBC metadata, for the list of tables passed as an argument, and their relations.
static DataSet readDataSetFromXml(java.io.InputStream is, java.lang.String... tableNames)
          Loads a DataSet schema from a XML Schema, for all tables and relations declared in the schema.
static DataSet readDataSetFromXml(java.io.Reader reader, java.lang.String... tableNames)
          Loads a DataSet schema from a XML Schema, for all tables and relations declared in the schema.
static DataSet setProviderConnection(DataSet ds, JDBCDataConnection conn)
          Utility method that facilitates using a JDBCDataConnection to set the connection for each DataProvider in each DataTable contained in the DataSet.
static void writeDataSet(DataSetSchemaWriter writer, DataSet ds)
          Exports a DataSet's schema using a schema writer, for all tables in the DataSet, and their relations.
static void writeDataSet(DataSetSchemaWriter writer, DataSet ds, java.lang.String... tableNames)
          Exports a DataSet's schema using a schema writer, for the list of tables passed as an argument, and their relations.
static void writeDataSetAsXml(java.io.OutputStream out, DataSet ds)
          Exports a DataSet's schema as an XML Schema, for all tables in the DataSet, and their relations.
static void writeDataSetAsXml(java.io.Writer writer, DataSet ds)
          Exports a DataSet's schema as an XML Schema, for all tables in the DataSet, and their relations.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DataSetUtility

public DataSetUtility()
Method Detail

setProviderConnection

public static DataSet setProviderConnection(DataSet ds,
                                            JDBCDataConnection conn)
Utility method that facilitates using a JDBCDataConnection to set the connection for each DataProvider in each DataTable contained in the DataSet.

Parameters:
ds - The DataSet to add providers to.
conn - The JDBCDataConnection to set as a provider for the tables in the DataSet.
Returns:
The DataSet provided as a parameter.

readDataSet

public static DataSet readDataSet(DataSetSchemaReader reader)
                           throws SchemaReaderException
Loads a DataSet schema using a schema reader, for all tables and relations declared in the schema. It is recommended that the DataSet be empty before calling this method. TODO: document what happens if tables or relations already exist in the DataSet.

Parameters:
reader - The schema instance from which to read the schema.
Returns:
The DataSet, with the schema loaded from XML.
Throws:
SchemaReaderException - If an error occurs while reading the schema.

readDataSet

public static DataSet readDataSet(DataSetSchemaReader reader,
                                  java.lang.String... tableNames)
                           throws SchemaReaderException
Loads a DataSet schema using a schema reader, for the tables listed in the tableNames argument, and their relations. It is recommended that the DataSet be empty before calling this method. TODO: document what happens if tables or relations already exist in the DataSet.

Parameters:
reader - The schema reader to use.
tableNames - Array of table names to read from the schema. Each element can be an unqualified table name, or a table.columnname entry, where only the columns listed for the table are read from the schema. Only tables listed in this argument are read from the schema, along with their relations.
Returns:
The DataSet with its schema configured.
Throws:
SchemaReaderException - If an error occurs while reading the schema.

readDataSetFromJDBC

public static DataSet readDataSetFromJDBC(JDBCDataConnection jdbcConn)
                                   throws SchemaReaderException
Loads a DataSet schema from a JDBC data connection, using JDBC metadata, for all tables and relations declared in the schema. The accuracy of the schema loading depends on the quality of the metadata returned by the JDBC driver; test carefully to make sure you get the results you want. It is recommended that the DataSet be empty before calling this method. TODO: document what happens if tables or relations already exist in the DataSet.

Parameters:
jdbcConn - The connection from which to read the JDBC metadata.
Returns:
The DataSet, with its schema configured.
Throws:
SchemaReaderException - If an error occurs while reading the schema.

readDataSetFromJDBC

public static DataSet readDataSetFromJDBC(JDBCDataConnection jdbcConn,
                                          java.lang.String... tableNames)
                                   throws SchemaReaderException
Loads a DataSet schema from a JDBC data connection, using JDBC metadata, for the list of tables passed as an argument, and their relations. The accuracy of the schema loading depends on the quality of the metadata returned by the JDBC driver; test carefully to make sure you get the results you want. It is recommended that the DataSet be empty before calling this method. TODO: document what happens if tables or relations already exist in the DataSet.

Parameters:
jdbcConn - The connection from which to read the schema.
tableNames - Array of table names to read from the schema. Each element can be an unqualified table name, or a table.columnname entry, where only the columns listed for the table are read from the schema. Only tables listed in this argument are read from the schema, along with their relations.
Returns:
The DataSet with its schema configured.
Throws:
SchemaReaderException - If an error occurs while reading the schema.

readDataSetFromXml

public static DataSet readDataSetFromXml(java.io.InputStream is,
                                         java.lang.String... tableNames)
                                  throws SchemaReaderException
Loads a DataSet schema from a XML Schema, for all tables and relations declared in the schema. It is recommended that the DataSet be empty before calling this method. TODO: document what happens if tables or relations already exist in the DataSet.

Parameters:
is - An InputStream from which to read the schema; this should be open before calling this method, and closed by the caller.
tableNames - Array of table names to read from the schema. Each element can be an unqualified table name, or a table.columnname entry, where only the columns listed for the table are read from the schema. Only tables listed in this argument are read from the schema, along with their relations.
Returns:
The DataSet with its schema configured.
Throws:
SchemaReaderException - If an error occurs while reading the schema.

readDataSetFromXml

public static DataSet readDataSetFromXml(java.io.Reader reader,
                                         java.lang.String... tableNames)
                                  throws SchemaReaderException
Loads a DataSet schema from a XML Schema, for all tables and relations declared in the schema. It is recommended that the DataSet be empty before calling this method. TODO: document what happens if tables or relations already exist in the DataSet.

Parameters:
reader - A Reader from which to read the schema; this should be open before calling this method, and closed by the caller.
tableNames - Array of table names to read from the schema. Each element can be an unqualified table name, or a table.columnname entry, where only the columns listed for the table are read from the schema. Only tables listed in this argument are read from the schema, along with their relations.
Returns:
The DataSet with its schema configured.
Throws:
SchemaReaderException - If an error occurs while reading the schema.

writeDataSet

public static void writeDataSet(DataSetSchemaWriter writer,
                                DataSet ds)
                         throws SchemaWriterException
Exports a DataSet's schema using a schema writer, for all tables in the DataSet, and their relations.

Parameters:
writer - The schema writer to use.
ds - The DataSet to export a schema for.
Throws:
SchemaWriterException - If an error occurs while writing the schema.

writeDataSet

public static void writeDataSet(DataSetSchemaWriter writer,
                                DataSet ds,
                                java.lang.String... tableNames)
                         throws SchemaWriterException
Exports a DataSet's schema using a schema writer, for the list of tables passed as an argument, and their relations.

Parameters:
writer - The schema writer to use.
ds - The DataSet to export a schema for.
tableNames - Array of table names to export the schema for. Each element can be an unqualified table name, or a table.columnname entry, where only the columns listed for the table are written out. Only tables listed in this argument are exported, along with their relations.
Throws:
SchemaWriterException - If an error occurs while writing the schema.

writeDataSetAsXml

public static void writeDataSetAsXml(java.io.OutputStream out,
                                     DataSet ds)
                              throws SchemaWriterException
Exports a DataSet's schema as an XML Schema, for all tables in the DataSet, and their relations.

Parameters:
out - The OutputStream to write the XML to.
ds - The DataSet to export.
Throws:
SchemaWriterException - If an error occurs while writing the schema.

writeDataSetAsXml

public static void writeDataSetAsXml(java.io.Writer writer,
                                     DataSet ds)
                              throws SchemaWriterException
Exports a DataSet's schema as an XML Schema, for all tables in the DataSet, and their relations.

Parameters:
writer - The Writer to write the XML to.
ds - The DataSet to export.
Throws:
SchemaWriterException - If an error occurs while writing the schema.

createDataTableSchema

public static void createDataTableSchema(JDBCDataConnection jdbcConn,
                                         DataSet ds,
                                         java.lang.String tableName,
                                         java.lang.String statement)
                                  throws SchemaCreationException
Creates a new DataTable in the specified DataSet that maps directly to one returned from a custom SELECT query.

Unlike the readDataSetFromJDBC(JDBCDataConnection, String[]) method the data relations are not set up, as typically the links would be within the table itself (i.e. due to a JOIN statement on a foreign key)

To avoid expensive queries that will have to be executed twice (to create and then load the table) the statement passed in here should use a LIMIT 0 statement to avoid returning any real data, as only the metadata is required for analysis.

It should be noted that only one catalog is currently supported and therefore the query should only select tables from one catalog. A SchemaCreationException will be thrown if more than one catalog is used.

If at any point during the creation of the new table a problem occurs an exception will be thrown to indicate this problem, and no new table will be added to the DataSet.

Parameters:
ds - The DataSet to import schema information into.
jdbcConn - a valid connection to a database that is used to generate the queries and metadata, that must be opened prior to calling this method
tableName - The new table's name that is to be created
statement - The custom query that is to be used to generate the table
Throws:
SchemaCreationException - if a problem occurs at any time during the creation of the schema
See Also:
readDataSetFromJDBC(JDBCDataConnection, String[])

createDataSetSchema

public static DataSet createDataSetSchema(JDBCDataConnection conn,
                                          java.lang.String... names)
                                   throws SchemaCreationException
Creates a DataSet that contains a DataTable for each table that has been specified in the given names Set. Each DataTable will be created in turn and then any relations between the created tables will be established. This method takes an array of database entity "names" which are of the form: table or table.column

As the definition of each DataTable created refers only to a physical table and is therefore backed up by a physical representation in the database an SQLDataProvider implementation is created for each table that will create the required statements for updating the table. The DataConnection will be set to the given jdbcConn parameter.

This method delegates the work of actualy creating the schema to the createDataTableSchema(JDBCDataConnection, DataSet, String, String) method, which should be referred to for details of the work actually performed.

NB: The catalog used to retrieve the information is the 'current' one as set by the database system, one that is automatically used when a query is sent to the database without explicity stating a catalog.

Parameters:
conn - a valid connection to a database that is used to generate the queries and metadata, that must be opened prior to calling this method
names - A list of all tables to be included (plus optional explicit column names for each table)
Returns:
a new DataSet containing newly created DataTable definitions
Throws:
SchemaCreationException - if a problem occurs at any time during the creation of the schema
See Also:
createDataTableSchema(JDBCDataConnection, DataSet, String, String), createRelations(JDBCDataConnection, DataSet)

createRelations

public static void createRelations(JDBCDataConnection jdbcConn,
                                   DataSet ds)
                            throws SchemaCreationException
Creates any relations that exist between the tables in the given DataSet using the database metadata that can be retrieved using the given SQL Connection.

NB: The catalog used to retrieve the information is the 'current' one as set by the database system, one that is automatically used when a query is sent to the database without explicity stating a catalog.

Parameters:
jdbcConn - a valid connection to a database that is used to generate the queries and metadata, that must be opened prior to calling this method
ds - the DataSet that contains the DataTables which are to be analysed for relations
Throws:
SchemaCreationException - if a problem occurs at any time during the creation of the schema

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception
Throws:
java.lang.Exception


Copyright © 2005 Sun Microsystems All Rights Reserved.