12. Schema Reflection
Prev | Chapter 4. JDBC | Next

## 12. Schema Reflection

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.

### 12.1. Schemas List

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

### Note

Some databases are case-sensitive with respect to schema and table names. Oracle, for example, requires names in all upper case.

### 12.2. Schema Factory

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 also implement your own schema factory if you have needs not met by the existing options.

Prev | Up | Next
11. Default Schema | Home | 13. Schema Tool