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. If you rely on the mapping tool to do all your mapping for you, you might want to keep mapping data out of the way in a database table. On the other hand, if you want easy access to your mapping information, or if you do not want to store any additional metadata in your database, you might want to store it as vendor extensions in your JDO metadata. Or perhaps JDO's metadata extension mechanism is too verbose for your tastes, and you'd like to use separate, more concise mapping files to express your mappings.
Kodo JDO uses the kodo.jdbc.meta.MappingFactory interface to abstract the storage and retrieval of mapping information. Kodo JDO includes built-in mapping factories for all of the options mentioned above, and you can create your own factory if you have custom needs. You control which mapping factory Kodo JDO uses with the kodo.jdbc.MappingFactory configuration property.
The bundled mapping factories are:
file: This is the default mapping factory. It is an alias for the kodo.jdbc.meta.FileMappingFactory . As its name implies, the FileMappingFactory stores mapping data in the file system. The data is stored in an XML format that closely resembles the JDO metadata format, and the placement of mapping files also follows the rules for the placement of JDO metadata files, the only difference being that mapping files use the .mapping extension rather than the .jdo extension.
The main advantages of this mapping factory are that it allows easy access to mapping data and that it doesn't create any special database tables. Additionally, its concise XML format is easier to manipulate than JDO metadata extensions, which are another option for mapping information storage (see below).
The file mapping factory accepts the following properties:
SingleFile: Set this property to true to have all mapping information stored in a single file. By default, the factory creates a mapping file for each JDO metadata file.
FileName: If you are using single file mode, then this property specifies the resource name of the XML mapping file. By default, the factory looks for a resource called package.mapping, located in any top-level directory of the CLASSPATH or in the top level of any jar.
metadata: This is an alias for the kodo.jdbc.meta.MetaDataMappingFactory : The MetaDataMappingFactory stores mapping data in your .jdo files using JDO metadata's built-in extension mechanism. This allows you easy access to the mapping information, and it consolidates all of your JDO metadata information in one place.
The only major disadvantage to using JDO metadata extensions is that they are rather verbose. For that reason some users may prefer the FileMappingFactory over this one.
db: This option is appropriate if you want Kodo JDO to do all the mapping work for you through the mapping tool (see Section 7.1, “Mapping Tool”). It is an alias for the kodo.jdbc.meta.DBMappingFactory. The DBMappingFactory stores its mapping data in a special database table it creates the first time the factory is used. Storing the mapping data in the database means you never need to see it or deal with it. It also means, however, that you can't access your mapping data easily if you want to manipulate it by hand. Recall that there are still metadata extensions you can use to control general mapping options like which columns are indexed or even what type of mapping to create on a given field. But if you plan on any detailed hand-mapping, you should use one of the other factories presented above. This factory accepts the following properties:
SingleRow: Set this property to true to have all mapping information stored in a single table row. By default, the factory creates a row for the mapping data of each class.
TableName: The name of the table to create to store mapping data. Defaults to JDO_MAPPING.
Note that using a mapping factory other than the MetaDataMappingFactory does not obviate the need for JDO metadata extensions. Extensions such as dependent, inverse-owner, and, if you use Kodo to create your schema, jdbc-size and jdbc-indexed still reside in your JDO metadata. While some of these extensions may affect object/relational mapping behavior, they do not contain object/relational mapping data per se. Mapping factories only hold information directly related to object/relational mapping: which columns a field occupies, and how those columns are linked to other schema components.
The mapping tool has the ability to import object-relational mapping data into the mapping factory, and to export mapping data from the mapping factory. We discuss the XML format used for imports and exports here.
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.12. 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.