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.
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]](img/note.gif) | Note |
|---|---|
Some databases are case-sensitive with respect to schema and table names. Oracle, for example, requires names in all upper case. |
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 thekodo.jdbc.schema.DynamicSchemaFactory. TheDynamicSchemaFactoryis 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 thekodo.jdbc.schema.LazySchemaFactory. As persistent classes are loaded by the application, Kodo reads their metadata and object-relational mapping information. This factory uses thejava.sql.DatabaseMetaDatainterface 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 totrueto automatically read foreign key information during schema validation.
table: This is an alias for thekodo.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 thejava.sql.DatabaseMetaDatastandard 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 toKODO_SCHEMA.PrimaryKeyColumn: The name of the table's numeric primary key column. Defaults toID.SchemaColumn: The name of the table's string column for holding the schema definition as an XML string. Defaults toSCHEMA_DEF.
file: This is an alias for thekodo.jdbc.schema.FileSchemaFactory. This factory is a lot like theTableSchemaFactory, 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 calledpackage.schema, located in any top-level directory of theCLASSPATHor in the top level of any jar in yourCLASSPATH.
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.
