An important decision in the object-relational mapping process is how and where to store the data necessary to map your persistent classes to the database schema.
In JPA, mapping metadata is defined in annotations. Future versions of the JPA drafts will also define a mapping XML format. Chapter 12, Mapping Metadata in the JPA Overview describes JPA mapping options.
In JDO, mapping metadata is integrated with persistence metadata in
your .jdo files by default.
Section 15.1, “Mapping Metadata Placement” in the
JDO Overview explains how to use separate .orm
files for mapping metadata instead. Using separate files separates
concerns and allows you to define multiple mappings for the same object
model, but it is slightly less convenient to work with.
Section 6.2, “Metadata Factory” introduced Kodo's
MetaDataFactory interface. Kodo uses this same interface
to abstract the storage and retrieval of mapping information. Kodo
includes the built-in mapping factories below, and you can create
your own factory if you have custom needs. You control which mapping
factory Kodo uses with the
kodo.jdbc.MappingFactory configuration
property.
Kodo allows you to mix metadata and mapping factories from both the
JPA and JDO specifications. For example, you can configure Kodo to use
JPA annotations for metadata but JDO .orm files
for mapping information. We present an example of this configuration
below.
The bundled mapping factories are:
-: Leaving the
kodo.jdbc.MappingFactory property unset allows your
metadata factory to take over mappings as well.
If you are using the jpa metadata factory,
Kodo will read mapping information from your annotations when
you leave the mapping factory unspecified.
If you are using the jdo metadata factory,
this gives the standard behavior defined in
Section 15.1, “Mapping Metadata Placement”. Even without
setting an explicit mapping factory name, however, you can
still use the kodo.jdbc.MappingFactory
property to specify mapping options, including:
ConstraintNames: Set this option
to true to include the names of
foreign key and unique constraints in all generated
mappings. By default, Kodo does not record constraint
names.
jdo-orm: This is an alias for the
kodo.jdo.jdbc.ORMFileJDORMappingFactory
. This factory stores mapping metadata in
.orm files. It accepts the following properties:
ConstraintNames: Set this option
to true to include the names of
foreign key and unique constraints in all generated
mappings. By default, Kodo does not record constraint
names.
Mapping: The logical name of these
mappings. Mapping files are suffixed with
"-<logical name>.orm". If not
specified, this value is taken from the
kodo.Mapping configuration property.
jdo-table: This is an alias for the
kodo.jdo.jdbc.TableJDORMappingFactory
. This factory stores mapping metadata as XML strings
in a database table it creates for this purpose. It accepts
the following options:
ConstraintNames: Set this option
to true to include the names of
foreign key and unique constraints in all generated
mappings. By default, Kodo does not record constraint
names.
Table: The name of the table.
Defaults to KODO_JDO_MAPPINGS.
NameColumn: The name of the column
that holds the mapping name. For class mappings, the
mapping name is the class name. For named queries and
sequences, it is the sequence or query name.
Defaults to NAME.
TypeColumn: The name of the column
that holds the mapping type. Defaults to
MAPPING_TYPE. Type constants are:
0: A class mapping.
1: A named sequence.
2: A system-level named
query.
3: A class-level named
query.
MappingColumn: The name of the
column that holds the XML mapping. Defaults to
MAPPING_DEF.
The mapping table is automatically created as needed, but you
can also manipulate it through the
TableORMMappingFactory's main
method, or the corresponding
mappingtable shell/bat script. See the
factory's
Javadoc for usage instructions.
file: Backwards-compatibility setting for
Kodo 3.x mapping files.
You can only use this factory with the kodo3
metadata factory.
metadata: Backwards-compatibility setting for
Kodo 3.x mapping metadata extensions.
You can only use this factory with the kodo3
metadata factory.
db: Backwards-compatibility setting for
the Kodo 3.x mapping table. You can only use this
factory with the kodo3 metadata factory.
Example 7.19. Standard JPA Configuration
In the standard JPA configuration, the mapping factory is left unset.
<property name="kodo.MetaDataFactory" value="jpa"/>
Example 7.20. Standard JDO Configuration
In the standard JDO configuration, the mapping factory is left unset.
kodo.MetaDataFactory: jdo
Example 7.21. Recording Constraint Names
This example uses standard JDO mapping, but uses the
MappingFactory property to tell Kodo to record
the names of all generated constraints in the mappings.
kodo.jdbc.MappingFactory: ConstraintNames=true
Example 7.22. JDO ORM File Configuration
You can configure Kodo to separate JDO mapping data into
.orm files either by setting the
kodo.Mapping property to the logical mapping
name, or by explicitly setting your
kodo.jdbc.MappingFactory property.
unset.
kodo.MetaDataFactory: jdo kodo.Mapping: oracle
kodo.MetaDataFactory: jdo kodo.jdbc.MappingFactory: jdo-orm(Mapping=oracle)
Example 7.23. Storing JDO Mappings in a Table
This example stores JDO mapping metadata in the
MAPPING database table.
kodo.jdbc.MappingFactory: jdo-table(Table=MAPPING)
Example 7.24. JPA Metadata, JDO Mapping Files
This example configures Kodo to use JPA annotations for metadata,
but JDO .orm files for mappings.
<property name="kodo.MetaDataFactory" value="jpa"/> <property name="kodo.jdbc.MappingFactory" value="jdo-orm"/>
The mapping tool has the ability to import mapping data into the mapping factory, and to export mapping data from the mapping factory. Importing and exporting mapping data is useful for a couple of reasons. First, you may want to use a mapping factory that stores mapping data in an out-of-the-way location like the database, but you still want the ability to manipulate this information occasionally by hand. You can do so by exporting the data to XML, modifying it, and then re-importing it.
Example 7.25. Modifying Difficult-to-Access Mapping Data
mappingtool -a export -f mappings.xml package.jdo ... modify mappings.xml file as necessary ... mappingtool -a import mappings.xml
Second, you can use the export/import facilities to switch mapping factories at any time.
Example 7.26. Switching Mapping Factories
mappingtool -a export -f mappings.xml *.jdo ... switch the kodo.jdbc.MappingFactory configuration ... ... property to list your new mapping factory choice ... mappingtool -a import mappings.xml
Kodo uses JDO's orm mapping format for imports
and exports. See Chapter 15, Mapping Metadata for details
on the orm mapping format.
|
|