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.

Author:

Abe White, Patrick Linskey

Field Summary

static String	ADD
static String	DROP
static String	LIST
static String	OUTPUT_STDOUT
static String	REFRESH
static String	REGISTER
static String	UNREGISTER

Constructor Summary

SchemaTool(JDBCConfiguration conf)
Construct a SchemaTool that will use the given database.

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.
boolean	getCacheTables() If true, only one call will be made to getTables() in the DatabaseMetaData.
JDBCConfiguration	getConfiguration() Return the configuration in use by this tool.
Connection	getConnection() Return a connection to the database.
boolean	getIgnoreErrors() If true, SQLExceptions thrown during schema manipulation will be printed but ignored.
String[]	list() Return a list of persistent types registered with the schema tool.
static void	main(JDBCConfiguration conf, String action, boolean ignoreErrors, String outFile, String[] args, ClassLoader loader, boolean dropCache) Utility method to run the schematool on all items in args.
static void	main(String[] args) Usage: java com.solarmetric.kodo.impl.schema.SchemaTool [option]* -action <add | refresh | drop | list | register | unregister> <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	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	register(String className) Add the given class name to the list of registered classes.
void	register(String[] classNames) Add the given class names to the list of registered classes.
void	setCacheTables(boolean cacheTables) If true, only one call will be made to getTables() in the DatabaseMetaData.
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	unregister(String className) Remove the given class name from the list of registered classes.
void	unregister(String[] classNames) Remove the given class names from the list of registered classes.

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

REFRESH

public static String REFRESH

DROP

public static String DROP

UNREGISTER

public static String UNREGISTER

REGISTER

public static String REGISTER

LIST

public static String LIST

Constructor Detail

SchemaTool

public SchemaTool(JDBCConfiguration conf)

Construct a SchemaTool that will use the given database.

Method Detail

getConfiguration

public JDBCConfiguration getConfiguration()

Return the configuration in use by this tool.

getConnection

public Connection getConnection()

Return a connection to the database.

close

public void close()
           throws SQLException

Close the database connection used by the tool.

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.

getCacheTables

public boolean getCacheTables()

If true, only one call will be made to getTables() in the DatabaseMetaData. Otherwise, the table information will always be retrieved.

setCacheTables

public void setCacheTables(boolean cacheTables)

If true, only one call will be made to getTables() in the DatabaseMetaData. Otherwise, the table information will always be retrieved.

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.

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.

list

public String[] list()
              throws SQLException

Return a list of persistent types registered with the schema tool.

unregister

public void unregister(String className)
                throws SQLException

Remove the given class name from the list of registered classes.

unregister

public void unregister(String[] classNames)
                throws SQLException

Remove the given class names from the list of registered classes.

register

public void register(String className)
              throws SQLException

Add the given class name to the list of registered classes.

register

public void register(String[] classNames)
              throws SQLException

Add the given class names to the list of registered classes.

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.

main

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

Usage: java com.solarmetric.kodo.impl.schema.SchemaTool [option]* -action <add | refresh | drop | list | register | unregister> <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
• -db <db name>: if using the deprecated system.prefs, the name of the database to access; 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
• list
: list classes currently registered with this database
• register: register a new persistent type with this database
• unregister: remove a type from those registered with the database

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,
                        ClassLoader loader,
                        boolean dropCache)
                 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, UNREGISTER, REGISTER, or LIST.

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.