4.13. Schema Reflection

4.13.1. Schemas List
4.13.2. Schema Factory

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.13.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:


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

4.13.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.15, “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.


Skip navigation bar   Back to Top