com.solarmetric.kodo.impl.jdbc.schema
Class SchemaTool

java.lang.Object
  |
  +--com.solarmetric.kodo.impl.jdbc.schema.SchemaTool

public class SchemaTool

extends Object

The SchemaTool is used to manage the database schema for JDO instances. The tool currently has the following limitations:

• Assumes single-table inheritance policy.
• Classes must still exist to drop their schema.
• Secondary tables that are no longer used are not detected.
• Dead columns of secondary tables are not detected.

Field Summary

static String	ADD
static String	DROP
static String	OUTPUT_STDOUT
static String	REFRESH
static String	RELOAD

Constructor Summary

SchemaTool(JDBCConfiguration conf, ClassResolver resolver, Connector connector)
Construct a SchemaTool that will use the given database.

SchemaTool(JDBCConfiguration conf, ClassResolver resolver, Connector connector, org.apache.commons.logging.Log sqllog, org.apache.commons.logging.Log schemalog)

SchemaTool(JDBCConfiguration conf, ClassResolver resolver, SQLExecutionManager manager)

SchemaTool(JDBCConfiguration conf, ClassResolver resolver, SQLExecutionManager manager, org.apache.commons.logging.Log sqllog, org.apache.commons.logging.Log schemalog)

Method Summary

void	add(Class type) Add the tables/columns used by the given class.
void	add(Class[] types) Add the tables/columns used by the given classes.
void	addColumn(Column column) Creates the given column in the DB, if it does not exist already.
void	addColumns(Column[] columns) Creates the given columns in the DB if they do not exist already.
void	addTable(Table table) Execute the SQL to create/refresh the given table in the DB.
void	addTables(Table[] tables) Execute the SQL to create/refresh the given tables in the DB.
void	close() Close the database connection used by the tool.
void	drop(Class type) Drop the tables and/or columns used by the given class from the DB.
void	drop(Class[] types) Drop the tables and/or columns used by the given classes from the DB.
void	dropColumn(Column column) Drop the given column from the DB.
void	dropColumns(Column[] columns) Drop the given columns from the DB.
void	dropTable(Table table) Drop the given table from the DB.
void	dropTables(Table[] tables) Drop the given tables from the DB.
(package private) void	executeSQL(SQLBuffer[] sql) Executes the given array of non-selecting SQL statements, correctly logging the SQL calls and optionally ignoring errors.
JDBCConfiguration	getConfiguration() Return the configuration in use by this tool.
Connection	getConnection() Return a connection to the database.
Connector	getConnector() Return a Connector for establishing connections.
DBDictionary	getDictionary()
boolean	getIgnoreErrors() If true, SQLExceptions thrown during schema manipulation will be printed but ignored.
SQLExecutionManager	getManager() Returns the SQLExecutionManager currently in use by this SchemaTool.
(package private) com.solarmetric.kodo.impl.jdbc.schema.SchemaTool.SchemaCache	getSchemaCache()
String[]	list()
(package private) void	log(Configuration conf, String msg)
(package private) void	log(String msg) Log a message to this tool's log writer.
static void	main(JDBCConfiguration conf, String action, boolean ignoreErrors, String outFile, String[] args, boolean dropCache, ClassResolver resolver) Utility method to run the schematool on all items in args.
static void	main(JDBCConfiguration conf, String action, boolean ignoreErrors, String outFile, String[] args, boolean dropCache, ClassResolver resolver, org.apache.commons.logging.Log sqllog, org.apache.commons.logging.Log schemalog)
static void	main(String[] args) Usage: java com.solarmetric.kodo.impl.schema.SchemaTool [option]* -action <add | refresh | drop> <class name | .class file | .jdo file<*
void	refresh(Class type) Refresh/create the tables/columns used by the given class.
void	refresh(Class[] types) Refresh/create the tables/columns used by the given classes.
void	refresh(Class[] types, boolean dropUnused) Refresh the schema for the given types, optionally dropping unused data.
void	refreshSequenceTables(Class[] types) Determines the SequenceFactory for each of the types and initializes their schema.
void	refreshTable(Table table) Similar to addTable, but drops unused columns as well.
void	refreshTables(Table[] tables) Similar to addTables, but drops unused columns as well.
void	setIgnoreErrors(boolean ignoreErrs) If true, SQLExceptions thrown during schema manipulation will be printed but ignored.
void	setOutputWriter(PrintWriter out) Specify a stream to log SQL commands to.
void	setSchemaLog(org.apache.commons.logging.Log log)
(package private) void	warn(String msg) Send a warning exception
(package private) void	warn(String msg, Throwable t)

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OUTPUT_STDOUT

public static String OUTPUT_STDOUT

ADD

public static String ADD

RELOAD

public static String RELOAD

REFRESH

public static String REFRESH

DROP

public static String DROP

Constructor Detail

SchemaTool

public SchemaTool(JDBCConfiguration conf,
                  ClassResolver resolver,
                  Connector connector)
           throws SQLException

Construct a SchemaTool that will use the given database.

SchemaTool

public SchemaTool(JDBCConfiguration conf,
                  ClassResolver resolver,
                  Connector connector,
                  org.apache.commons.logging.Log sqllog,
                  org.apache.commons.logging.Log schemalog)
           throws SQLException

SchemaTool

public SchemaTool(JDBCConfiguration conf,
                  ClassResolver resolver,
                  SQLExecutionManager manager)

SchemaTool

public SchemaTool(JDBCConfiguration conf,
                  ClassResolver resolver,
                  SQLExecutionManager manager,
                  org.apache.commons.logging.Log sqllog,
                  org.apache.commons.logging.Log schemalog)

Method Detail

getConfiguration

public JDBCConfiguration getConfiguration()

Return the configuration in use by this tool.

getConnection

public Connection getConnection()
                         throws SQLException

Return a connection to the database.

getConnector

public Connector getConnector()
                       throws SQLException

Return a Connector for establishing connections.

getDictionary

public DBDictionary getDictionary()
                           throws SQLException

getSchemaCache

com.solarmetric.kodo.impl.jdbc.schema.SchemaTool.SchemaCache getSchemaCache()
                                                                      throws SQLException

Returns:

the SchemaCache implementation to remember information about the database schema.

getManager

public SQLExecutionManager getManager()
                               throws SQLException

Returns the SQLExecutionManager currently in use by this SchemaTool.

close

public void close()
           throws SQLException

Close the database connection used by the tool. A SchemaTool that has been closed can be re-used: when needed, a new SQLExecutionManager will be created and used.

getIgnoreErrors

public boolean getIgnoreErrors()

If true, SQLExceptions thrown during schema manipulation will be printed but ignored.

setIgnoreErrors

public void setIgnoreErrors(boolean ignoreErrs)

If true, SQLExceptions thrown during schema manipulation will be printed but ignored.

setOutputWriter

public void setOutputWriter(PrintWriter out)
                     throws IOException

Specify a stream to log SQL commands to. If this stream is specified, then the SchemaTool will not modify the datastore.

setSchemaLog

public void setSchemaLog(org.apache.commons.logging.Log log)

drop

public void drop(Class type)
          throws SQLException

Drop the tables and/or columns used by the given class from the DB.

drop

public void drop(Class[] types)
          throws SQLException

Drop the tables and/or columns used by the given classes from the DB.

add

public void add(Class type)
         throws SQLException

Add the tables/columns used by the given class.

add

public void add(Class[] types)
         throws SQLException

Add the tables/columns used by the given classes.

refresh

public void refresh(Class type)
             throws SQLException

Refresh/create the tables/columns used by the given class.

refresh

public void refresh(Class[] types)
             throws SQLException

Refresh/create the tables/columns used by the given classes.

refresh

public void refresh(Class[] types,
                    boolean dropUnused)
             throws SQLException

Refresh the schema for the given types, optionally dropping unused data.

refreshSequenceTables

public void refreshSequenceTables(Class[] types)
                           throws SQLException

Determines the SequenceFactory for each of the types and initializes their schema.

dropTable

public void dropTable(Table table)
               throws SQLException

Drop the given table from the DB.

dropTables

public void dropTables(Table[] tables)
                throws SQLException

Drop the given tables from the DB.

addTable

public void addTable(Table table)
              throws SQLException

Execute the SQL to create/refresh the given table in the DB. The table will be created if they do not already exist; otherwise, any new columns on the table will be added.

addTables

public void addTables(Table[] tables)
               throws SQLException

Execute the SQL to create/refresh the given tables in the DB.

refreshTable

public void refreshTable(Table table)
                  throws SQLException

Similar to addTable, but drops unused columns as well.

refreshTables

public void refreshTables(Table[] tables)
                   throws SQLException

Similar to addTables, but drops unused columns as well.

dropColumn

public void dropColumn(Column column)
                throws SQLException

Drop the given column from the DB.

dropColumns

public void dropColumns(Column[] columns)
                 throws SQLException

Drop the given columns from the DB.

addColumn

public void addColumn(Column column)
               throws SQLException

Creates the given column in the DB, if it does not exist already.

addColumns

public void addColumns(Column[] columns)
                throws SQLException

Creates the given columns in the DB if they do not exist already.

list

public String[] list()

executeSQL

void executeSQL(SQLBuffer[] sql)
          throws SQLException

Executes the given array of non-selecting SQL statements, correctly logging the SQL calls and optionally ignoring errors.

log

void log(String msg)

Log a message to this tool's log writer.

warn

void warn(String msg)

Send a warning exception

warn

void warn(String msg,
          Throwable t)

log

void log(Configuration conf,
         String msg)

main

public static void main(String[] args)
                 throws SQLException,
                        ClassNotFoundException,
                        IOException

Usage: java com.solarmetric.kodo.impl.schema.SchemaTool [option]* -action <add | refresh | drop> <class name | .class file | .jdo file<*

Where the following options are recognized.

• -properties <properties file>: the path to a Kodo properties file containing information such as the license key and connection data as outlined in Configuration; optional
• -<bean property> <value>: all bean properties of the Kodo JDBCConfiguration can be set by using their names and supplying a value; for example: -licenseKey adslfja83r3lkadf
• -ignoreErrors <true|false>: if false, an exception will will be thrown if the tool encounters any database exceptions; defaults to false
• -outfile <stdout|file>: specify that SQL should not be executed against the data store, but should be appended to the given file, or to stdout (in which case other log msgs will go to stderr); optional

If the license key is not specified otherwise, Kodo will check for default preference files with license keys as outlined in DefaultConfiguration.

The various actions are as follows.

• add: bring the schema up-to-date with the latest changes to the object model by adding new columns and tables as necessary (note: to prevent accidental data loss, adding never drops columns or tables)
• refresh: behaves in the same manner as add, but will drop unused columns and tables as applicable
• drop: drop the tables used by the object model

Each additional argument can be either the full class name of a type to act on, the path to the .class file for the type, or the path to a .jdo file listing one or more types. If no arguments are provided, the action will be peformed on all classes listed in the database in use.

main

public static void main(JDBCConfiguration conf,
                        String action,
                        boolean ignoreErrors,
                        String outFile,
                        String[] args,
                        boolean dropCache,
                        ClassResolver resolver)
                 throws SQLException,
                        ClassNotFoundException,
                        IOException

Utility method to run the schematool on all items in args.

Parameters:

conf - The configuration to use for this schema tool

action - The action to perform. One of the string constants ADD, REFRESH, DROP, or RELOAD.

ignoreErrors - Whether or not errors should cause the schema tool to abort.

outFile - The file name to which SQL should be written, or "stdout" write just SQL to standard output.

args - The class names, class files, or .jdo files to operate on.

loader - The class loader to use for loading the persistent types

dropCache - Whether or not the db cache should be dropped.

main

public static void main(JDBCConfiguration conf,
                        String action,
                        boolean ignoreErrors,
                        String outFile,
                        String[] args,
                        boolean dropCache,
                        ClassResolver resolver,
                        org.apache.commons.logging.Log sqllog,
                        org.apache.commons.logging.Log schemalog)
                 throws SQLException,
                        ClassNotFoundException,
                        IOException