Chapter 15. Mapping Metadata

15.1. Mapping Metadata Placement
15.2. Mapping Metadata DTD
15.3. Sequences
15.4. Class Table
15.5. Datastore Identity
15.6. Column
15.7. Joins
15.7.1. Shortcuts
15.7.2. Self Joins
15.7.3. Target Fields
15.8. Inheritance
15.8.1. subclass-table Advantages Disadvantages Additional Considerations
15.8.2. new-table Joined Advantages Disadvantages Table Per Class Advantages Disadvantages
15.8.3. superclass-table Advantages Disadvantages
15.8.4. Putting it All Together
15.9. Discriminator
15.9.1. class-name
15.9.2. value-map
15.9.3. none
15.9.4. Putting it All Together
15.10. Version
15.10.1. none
15.10.2. version-number
15.10.3. date-time
15.10.4. state-comparison
15.10.5. Putting it All Together
15.11. Field Mapping
15.11.1. Superclass Fields
15.11.2. Basic Mapping CLOB BLOB
15.11.3. Automatic Values
15.11.4. Secondary Tables
15.11.5. Direct Relations Inverse Keys Bidirectional Relations
15.11.6. Basic Collections
15.11.7. Association Table Collections Bidirectional Relations
15.11.8. Inverse Key Collections Bidirectional Relations
15.11.9. Maps
15.11.10. Embedded Objects
15.12. Foreign Keys
15.13. Indexes
15.14. Unique Constraints
15.15. The Complete Document

Object-relational mapping is the process of mapping persistent classes to relational database tables. In JDOR, you perform object/relational mapping through mapping metadata. Mapping metadata uses XML to describe how to link your object model to your relational model. With a few notable exceptions, every persistent class and every persistent field must have mapping metadata.


Kodo offers tools to automate mapping. See Chapter 7, Mapping in the Reference Guide.

15.1. Mapping Metadata Placement

By default, JDOR implementations expect to find mapping metadata integrated into the persistence metadata defined in your .jdo files. You can, however, instruct the implementation to look for separate mapping files by supplying a value for the javax.jdo.option.Mapping key in the Properties used to construct your PersistenceManagerFactory (see Section 6.3, “PersistenceManagerFactory Construction”). When this key is set, JDOR completely ignores any mapping metadata in your .jdo files. Instead, the implementation looks for mapping metadata in separate .orm files. The placement rules for these .orm files are very similar to the rules for .jdo files: the mapping document for a persistent class must be available as a resource from the class' class loader, and must exist in one of two standard locations:

  1. In a resource called <class-name>-<mapping>.orm, where <class-name> is the unqualified name of the class the document applies to, and <mapping> is the value of the javax.jdo.option.Mapping property. The resource must be located in the same package as the class.

  2. In a resource called package-<mapping>.orm, where <mapping> is the value of the javax.jdo.option.Mapping property. The resource should be placed in the corresponding package, or in any ancestor package. Package-level documents should contain the mappings for all the persistence-capable classes in the package, except those classes that have individual <class-name>-<mapping>.orm resources associated with them. They may also contain the mappings for classes in any sub-packages.

Assuming you are using a standard Java class loader, these rules imply that for a javax.jdo.option.Mapping setting of hsql and a class Magazine defined by the file org/mag/Magazine.class, the corresponding mapping document could be defined in any of the following files:

  • org/mag/Magazine-hsql.orm

  • org/mag/package-hsql.orm

  • org/package-hsql.orm

  • package-hsql.orm

Because mapping documents are loaded as resources, JDOR implementations can also read them from jar files.


Kodo offers additional options for mapping metadata placement, including the ability to define mappings yourself at runtime. See Section 7.5, “Mapping Factory”.