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

## 4.12. Schema Reflection

Kodo 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, Kodo requires schema information during development so that it can manipulate the schema to match your object model. Kodo uses the `SchemaFactory` interface to provide runtime mapping information, and the `SchemaTool` for development-time data. Each is presented below.

### 4.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 Kodo acts on with the `kodo.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.

### 4.12.2. Schema Factory

Kodo relies on the `kodo.jdbc.SchemaFactory` interface for runtime schema information. You can control the schema factory Kodo uses through the `kodo.jdbc.SchemaFactory` property. There are several built-in options to choose from:

- `dynamic`: This is the default setting. It is an alias for the `kodo.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 Kodo can order its SQL statements to meet them.

- `native`: This is an alias for the `kodo.jdbc.schema.LazySchemaFactory` . As persistent classes are loaded by the application, Kodo 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. Because the factory doesn't reflect on a table definition until that table is mentioned by the mapping information, we call it "lazy". 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 `kodo.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 `KODO_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 `kodo.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 4.14, “XML Schema Format”. As with any Kodo plugin, you can can also implement your own schema factory if you have needs not met by the existing options.

Prev | Up | Next
4.11. Default Schema | Home | 4.13. Schema Tool