Java Persistent Objects - JPOX SchemaTool

The meta-data files (JDO, ORM) that accompany persistable classes define how a class maps across to a persistent store (e.g database). The database schema can be

Already existing, and so the user maps their classes to their existing tables
Manually created by the user.
Automatically created at runtime by use of the org.jpox.autoCreateSchema property.
Created before running the application, using JPOX SchemaTool.

We will describe here the use of JPOX SchemaTool. It is included in the JPOX Core jar, and is very simple to operate.

JPOX SchemaTool has the following modes of operation :

create - all database tables required for a set of JDO MetaData files (and classes) will be created in the database schema. Alternatively this mode can be used to output the schema DDL necessary to create the schema.
delete - all database tables required for a set of JDO MetaData files (and classes) will be deleted from the database schema.
validate - all database tables required for a set of JDO MetaData files (and classes) will be validated for correct structure (just in case you have changed any of your class definitions, or MetaData files since last running JPOX).
dbinfo - provide detailed information about the database, it's limits and datatypes support.
schemainfo - provide detailed information about the database schema.

In addition, the create mode can be used by adding "-dumpDdl {filename}" and this will then not create the schema, but instead dump the DDL for the tables into the specified file.

Here we provide many different ways to invoke JPOX SchemaTool

Invoke it manually from the command line
Invoke it using Maven1, with the JPOX Maven1 plugin
Invoke it using Maven2, with the JPOX Maven2 plugin
Invoke it using Ant, using the provided JPOX SchemaTool ant task
Invoke it using Jython
Invoke it using the JPOX Eclipse plugin
Invoke it programmatically from within an application

Manual Usage

If you wish to call JPOX SchemaTool manually, it can be called as follows

java [-cp classpath] [system_props] org.jpox.SchemaTool [options] [props] [jdo-files] [class-files]
    where system_props should include
        -Djavax.jdo.option.ConnectionDriverName=db_driver_name
        -Djavax.jdo.option.ConnectionURL=db_url
        -Djavax.jdo.option.ConnectionUserName=db_username
        -Djavax.jdo.option.ConnectionPassword=db_password
        -Djavax.jdo.option.Mapping=orm_mapping_name (optional)
    where options can be
        -create : Create the tables specified by the jdo-files/class-files
        -delete : Delete the tables specified by the jdo-files/class-files
        -validate : Validate the tables specified by the jdo-files/class-files
        -dbinfo : Detailed information about the database
        -schemainfo : Detailed information about the database schema
        -dumpDdl {filename} : only for use with "create" mode to dump the DDL to the specified file
        -v : verbose output
    where props can be
        -props {propsfilename} : PMF properties to use in place of the "system_props" below
    and system_props could optionally include
        -Dlog4j.configuration=file:log4j_configuration_file.lcf

The user can specify "jdo-files" and/or "class-files", defining the classes to be used in the schema operations (the ability to specify class files is only applicable from version 1.1.2 of JPOX). The classes and JDO/ORM MetaData files must be present in the CLASSPATH. In terms of the schema to use, you either specify the "props" file (recommended), or you specify the System properties defining the database connection. You should only specify one of the [options] above. Let's make a specific example and see the output from SchemaTool. So we have the following files in our application

src/java/...   (source files and JDO MetaData files)
target/classes/...    (enhanced classes, and JDO MetaData files)
lib/log4j.jar
lib/jpox.jar
lib/jdo2-api.jar
lib/mysql-connector-java.jar    (JDBC driver for our database)
log4j.properties

So we want to create the schema for our persistent classes. So let's invoke JPOX SchemaTool to do this, from the top level of our project. In this example we're using Linux (change the CLASSPATH definition to suit for Windows)

jpox -cp target/classes:lib/log4j.jar:lib/jdo2-api.jar:lib/jpox.jar:lib/mysql-connector-java.jar
      -Djavax.jdo.option.ConnectionDriverName=com.mysql.jdbc.Driver
      -Djavax.jdo.option.ConnectionURL=jdbc:mysql://localhost/mydb
      -Djavax.jdo.option.ConnectionUserName=db_username
      -Djavax.jdo.option.ConnectionPassword=db_password
      -Dlog4j.configuration=file:log4j.properties
      org.jpox.SchemaTool -create  
      target/classes/org/jpox/examples/normal/package.jdo
      target/classes/org/jpox/examples/inverse/package.jdo


JPOX SchemaTool (version 1.1.0) : Creation of the schema

JPOX SchemaTool : Classpath
>>  /home/andy/work/JPOX/samples/packofcards/target/classes
>>  /home/andy/work/JPOX/samples/packofcards/lib/log4j.jar
>>  /home/andy/work/JPOX/samples/packofcards/lib/jpox.jar
>>  /home/andy/work/JPOX/samples/packofcards/lib/jdo2-api.jar
>>  /home/andy/work/JPOX/samples/packofcards/lib/mysql-connector-java.jar

JPOX SchemaTool : Input Files
>> /home/andy/work/JPOX/samples/packofcards/target/classes/org/jpox/examples/inverse/package.jdo
>> /home/andy/work/JPOX/samples/packofcards/target/classes/org/jpox/examples/normal/package.jdo

JPOX SchemaTool : System Properties
>>  log4j.configuration=file:/home/andy/work/JPOX/samples/packofcards/log4j.properties
>>  javax.jdo.option.ConnectionDriverName=com.mysql.jdbc.Driver
>>  javax.jdo.option.ConnectionURL=jdbc:mysql://localhost/mydb
>>  javax.jdo.option.ConnectionUserName=db_username
>>  javax.jdo.option.Mapping=jpox
>>  org.jpox.autoCreateTables=true
>>  org.jpox.autoCreateConstraints=true
>>  org.jpox.autoCreateColumns=false
>>  org.jpox.validateTables=false
>>  org.jpox.validateConstraints=false

SchemaTool completed successfully

So as you see, JPOX SchemaTool prints out our input, the properties used, and finally a success message. If an error occurs, then something will be printed to the screen, and more information will be written to the log.

Maven

If you are using Maven to build your system, you will need the JPOX Maven plugin. This provides 3 goals representing the different modes of JPOX SchemaTool. You can use the goals jpox:schema-create, jpox:schema-delete, jpox:schema-validate depending on whether you want to create, delete or validate the database tables. To use the JPOX Maven plugin you will need to set properties for the plugin (in your project.properties). For example

maven.jpox.verbose=true
maven.jpox.schematool.ddlfile=
maven.jpox.orm.mapping=mysql
maven.jpox.log4j.configuration=file:log4j.properties
maven.jpox.properties=${basedir}/jpox.properties

So with these example properties I am setting the Maven plugin to use PMF properties from the file "jpox.properties" at the root of the Maven project. I am also specifying a log4j configuration file defining the logging for the SchemaTool process. In addition, I am specifying my object-relational mapping (O/R mapping) in files with names like package-mysql.orm. This last part is optional, and you can specify the mapping information in the JDO MetaData files. The other property we have defined is to receive verbose output from SchemaTool. The output obtained from Maven like this is identical to that obtained when invoking the SchemaTool manually.

Maven2

If you are using Maven2 to build your system, you will need the JPOX Maven2 plugin. This provides 5 goals representing the different modes of JPOX SchemaTool. You can use the goals jpox:schema-create, jpox:schema-delete, jpox:schema-validate depending on whether you want to create, delete or validate the database tables. To use the JPOX Maven2 plugin you will may need to set properties for the plugin (in your pom.xml). For example

Configuration name   Default Value     Description
mappingIncludes      **/*.jdo          Fileset to include
mappingExcludes                        Fileset to exclude, if any
props                                  Name of a properties file defining the datastore
outputFile                             name of a file to dump DDL to (when using schema-create)
log4jConfiguration   {internal props}  Log definition to use
verbose              false             Turn on more output ?

So to give an example, I add the following to my pom.xml

    <build>
        ...
        <plugins>
            <plugin>
                <groupId>jpox</groupId>
                <artifactId>jpox-maven-plugin</artifactId>
                <version>1.1.7</version>
                <configuration>
                    <props>${basedir}/jpox.properties</props>
                    <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
                    <verbose>true</verbose>
                </configuration>
            </plugin>
        </plugins>
        ...
    </build>

So with these properties when I run SchemaTool it uses properties from the file "jpox.properties" at the root of the Maven project. I am also specifying a log4j configuration file defining the logging for the SchemaTool process. I then can invoke any of the Maven2 goals

mvn jpox:schema-create              Create the Schema
mvn jpox:schema-delete              Delete the schema
mvn jpox:schema-validate            Validate the Schema
mvn jpox:schema-info                Output info for the Schema
mvn jpox:schema-dbinfo              Output info for the datastore

Ant

An Ant task is provided for using JPOX SchemaTool. It has classname org.jpox.SchemaToolTask, and accepts the following parameters

Parameter	Description	values
mode	Mode of operation.	create, delete, validate, dbinfo, schemainfo
verbose	Whether to give verbose output.	true, false
props	The filename to use for PMF properties
dumpDdl	The filename where a dump of the DDL scripts will we output.

In addition to the parameters that the Ant task accepts, you will need to set up your CLASSPATH to include the classes and JDO MetaData files, and to define the following system properties via the sysproperty parameter (not required when specifying the PMF props via the properties file)

Parameter	Description	Optional
javax.jdo.option.ConnectionDriverName	Name of JDBC driver class	Mandatory
javax.jdo.option.ConnectionURL	URL for the database	Mandatory
javax.jdo.option.ConnectionUserName	User name for the database	Mandatory
javax.jdo.option.ConnectionPassword	Password for the database	Mandatory
javax.jdo.option.Mapping	ORM Mapping name	Optional
log4j.configuration	Log4J configuration file, for SchemaTool's Log	Optional

So you could define something like the following, setting up the parameters schematool.classpath, javax.jdo.option.ConnectionDriverName, javax.jdo.option.ConnectionURL, javax.jdo.option.ConnectionUserName, and javax.jdo.option.ConnectionPassword to suit your situation.

You define the jdo files to create the tables using fileset.

<taskdef name="schematool" classname="org.jpox.SchemaToolTask" />

<schematool failonerror="true" verbose="true" mode="create">
    <classpath>
        <path refid="schematool.classpath"/>
    </classpath>
    <fileset dir="${classes.dir}">
        <include name="**/*.jdo"/>
    </fileset>
    <sysproperty key="javax.jdo.option.ConnectionDriverName" value="${javax.jdo.option.ConnectionDriverName}"/>
    <sysproperty key="javax.jdo.option.ConnectionURL" value="${javax.jdo.option.ConnectionURL}"/>
    <sysproperty key="javax.jdo.option.ConnectionUserName" value="${javax.jdo.option.ConnectionUserName}"/>
    <sysproperty key="javax.jdo.option.ConnectionPassword" value="${javax.jdo.option.ConnectionPassword}"/>
    <sysproperty key="javax.jdo.option.Mapping" value="${javax.jdo.option.Mapping}"/>
</schematool>

Jython

Jython is a powerful scripting language that allows you to automate tasks and easy the development. If you are using Jython, and wants to use JPOX tools, all you need is to the place the JPOX jars, the persistent classes, metadata files, jdbc driver jars and dependencies into the classpath.

The Jython script may be written in several forms but achieving the same goals.

Here we have a template for invoking the main method of the Schema Tool. The main method acts like the command line, by parsing arguments and invoking the appropriate methods.

from org.jpox import SchemaTool
tool = SchemaTool()
tool.main(<<<[options] [jdo-files]>>>)

The below is a concrete example.

from org.jpox import SchemaTool
tool = SchemaTool()
tool.main(["-create",
           "-props=/home/JDOproperties.properties",
           "target/classes/org/jpox/examples/normal/package.jdo",
           "target/classes/org/jpox/examples/inverse/package.jdo"])

Another form for invoking the same operation is:

from org.jpox import SchemaTool
from java.io import File
tool = SchemaTool()
props = File("/home/JDOproperties.properties")
metadata1 = File("target/classes/org/jpox/examples/normal/package.jdo")
metadata2 = File("target/classes/org/jpox/examples/normal/package.jdo")
tool.createSchemaTables([metadata1.toURL(),metadata2.toURL()],props,1)

For other operations of the SchemaTool consult the JPOX javadocs. For questions about Jython, please refer to Jython WebSite.

programmatic

JPOX SchemaTool can also be called programmatically from the application. There are two versions of the SchemaTool create-/delete-/validate- functions, one taking absolute filenames and the other taking URL parameters.

Create the Schema with the absolute filenames of the jdo Metadata and class files.

String[] jdoFiles = new String[]
    {
        "/home/andy/MyApp/target/classes/mydomain/MyApp/dataaccess/package.jdo"
    };
String[] classFiles = ...
File propsFile = ...
try
{
    SchemaTool.createSchemaTables(jdoFiles, classFiles, propsFile, false, null);
}
catch(Exception e)
{
    ...
}

Create the Schema with the URLs of the JDO Metadata and class files.

URL[] jdoFiles = new URL[]
    {
        this.getClass().getClassLoader().getResource("com/myCompany/myJPOXApp/dataObjects/package.jdo")
    };
URL[] classFiles = ...
File propsFile = ...
try
{
    SchemaTool.createSchemaTables(jdoFiles, classFiles, propsFile, false, null);
}
catch(Exception e)
{
    ...
}