Kodo JDO stores persistent objects in relational database tables. As you add, remove, or modify your persistent classes, these tables must be updated to reflect the current object model.
To facilitate this process, Kodo JDO provides the schematool. This command-line tool can create, refresh, or drop the relational schema for any persistent types, relieving you from database administration tasks. You can invoke the tool through the included schematool script or via its java class, com.solarmetric.kodo.impl.jdbc.schema.SchemaTool . It accepts the standard set of command-line arguments defined by the configuration framework. It also accepts the following flags:
-ignoreErrors <true|false>: Whether the tool should ignore SQL errors that are thrown while it is manipulating the schema. This optional argument defaults to false.
-outfile <filename>: If this optional argument is set, then the schematool will write SQL statements to the specified file rather than perform any modifications to the data store. Use the keyword stdout to print the SQL to standard output.
-action <add|refresh|drop|register|unregister|list>: This flag is required. It tells the tool what action to perform, where the available actions are:
add: Creates the schema for the given persistent types, if it does not already exist. This action will add tables for new classes, secondary tables for new collection, array, and map fields, or add new columns to existing tables for new simple fields. If the schema is already up-to-date, the tool will detect this and will not perform any additional work. This action will never drop data.
refresh: Similar to add, but also detects columns that are no longer used and drops them from the schema (some databases do not support dropping columns).
drop: Drops all schema components used by the given persistent types. If a subclass is mapped to the same table as its parent class, and only the subclass is included in the list of types to drop, the parent class' table will not be destroyed. If possible, the tool will remove the subclass' columns from the table. Be careful when using this action!
register: Adds the given persistent types to the list of known JDO classes. This list is required by the JDO runtime. Normally, registration is performed automatically when the add or refresh actions are used to create the schema for a type; however, if the schema was created without the schematool, this action can be used to register types after the fact. Strategies for maintaining the list of known JDO types are discussed in the next section.
unregister: Removes the given persistent types from the list of known JDO classes. Normally, types are unregistered automatically when the drop action is used to drop the corresponding schema elements. However, if you drop the schema without the schematool or if the Java classes are deleted (in which case the drop action cannot be used), types can be manually unregistered with this action.
list: This action prints a list of the known persistent types for the database.
-db <db name>: This option is for users of the deprecated system.prefs configuration mechanism. Use it to specify the symbolic name of the database to connect to.
 |
Important |
|---|---|
When acting on a persistent type, the schematool automatically extends the action to all known subclasses of the type. | |
Example 15.4. Using the Kodo JDO Schematool
Refresh the schema for all known persistent classes:
schematool -action refresh
Drop the schema for the Company and any types listed in the package.jdo file.
schematool -properties hsql.properties -action drop com.solarmetric.examples.Company ../package.jdo