OpenJPA needs information about your database schema for two reasons. First, it
can use schema information at runtime to validate that your schema is compatible
with your persistent class definitions. Second, OpenJPA requires schema
information during development so that it can manipulate the schema to match
your object model. OpenJPA uses the SchemaFactory interface
to provide runtime mapping information, and the SchemaTool
for development-time data. Each is presented below.
By default, schema reflection acts on all the schemas your JDBC driver can
"see". You can limit the schemas and tables OpenJPA acts on with the
openjpa.jdbc.Schemas configuration property. This property accepts a
comma-separated list of schemas and tables. To list a schema, list its name. To
list a table, list its full name in the form
<schema-name>.<table-name>. If a table does not have a
schema or you do not know its schema, list its name as
.<table-name> (notice the preceding '.'). For example, to list
the BUSOBJS schema, the ADDRESS table in
the GENERAL schema, and the SYSTEM_INFO
table, regardless of what schema it is in, use the string:
BUSOBJS,GENERAL.ADDRESS,.SYSTEM_INFO
Some databases are case-sensitive with respect to schema and table names. Oracle, for example, requires names in all upper case.
OpenJPA relies on the
openjpa.jdbc.SchemaFactory interface for runtime
schema information. You can control the schema factory OpenJPA uses through the
openjpa.jdbc.SchemaFactory property. There are several
built-in options to choose from:
dynamic: This is the default setting. It is an alias for the
org.apache.openjpa.jdbc.schema.DynamicSchemaFactory. The
DynamicSchemaFactory is the most performant
schema factory, because it does not validate mapping information against the
database. Instead, it assumes all object-relational mapping information is
correct, and dynamically builds an in-memory representation of the schema from
your mapping metadata. When using this factory, it is important that your
mapping metadata correctly represent your database's foreign key constraints so
that OpenJPA can order its SQL statements to meet them.
native: This is an alias for the
org.apache.openjpa.jdbc.schema.LazySchemaFactory
. As persistent classes are loaded by the application, OpenJPA reads their
metadata and object-relational mapping information. This factory uses the
java.sql.DatabaseMetaData interface to reflect on the
schema and ensure that it is consistent with the mapping data being read.
Use this factory if you want up-front validation that your mapping metadata is
consistent with the database during development. This factory accepts the
following important properties:
ForeignKeys: Set to true to automatically
read foreign key information during schema validation.
table: This is an alias for the
org.apache.openjpa.jdbc.schema.TableSchemaFactory
. This schema factory stores schema information as an XML document in a database
table it creates for this purpose. If your JDBC driver doesn't support the
java.sql.DatabaseMetaData standard interface, but you
still want some schema validation to occur at runtime, you might use this
factory. It is not recommended for most users, though, because it is easy for
the stored XML schema definition to get out-of-synch with the actual database.
This factory accepts the following properties:
Table: The name of the table to create to store schema
information. Defaults to OPENJPA_SCHEMA.
PrimaryKeyColumn: The name of the table's numeric primary
key column. Defaults to ID.
SchemaColumn: The name of the table's string column for
holding the schema definition as an XML string. Defaults to SCHEMA_DEF
.
file: This is an alias for the
org.apache.openjpa.jdbc.schema.FileSchemaFactory
. This factory is a lot like the TableSchemaFactory, and
has the same advantages and disadvantages. Instead of storing its XML schema
definition in a database table, though, it stores it in a file. This factory
accepts the following properties:
File: The resource name of the XML schema file. By default,
the factory looks for a resource called package.schema,
located in any top-level directory of the CLASSPATH or in the
top level of any jar in your CLASSPATH.
You can switch freely between schema factories at any time. The XML file format used by some factories is detailed in Section 14, “ XML Schema Format ” . As with any OpenJPA plugin, you can can also implement your own schema factory if you have needs not met by the existing options.