Chapter 15. Mapping Metadata
Prev | Part 3. Java Data Objects | Next

## Chapter 15. Mapping Metadata

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.

| Note
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.

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

Prev | Up | Next
Chapter 14. JDOR | Home | 15.2. Mapping Metadata DTD