JDO Metadata 

Definition

The JDO metadata is an XML file written in accordance with the document type definition (DTD) from the JDO specification. It describes persistence capable classes and their persistent fields.

Use

The JDO metadata is used both at enhancement time and at runtime. The JDO enhancer reads it to define which classes to enhance, and which fields to make persistent. Therefore, all persistence capable classes, as well as all persistent fields must be declared in the metadata. The non-declared fields are treated according to the defaults. For more information, see the JDO specification.

Structure

The name of the JDO metadata file is determined by the name of the class or the package it describes, and always has the extension .jdo. For example, the metadata for class Employee is Employee.jdo. It is recommended that you use a separate JDO metadata file for each JDO class and put the metadata file at the same location as the source of the JDO class.

The metadata includes the following elements:

·        jdo – the root element of the XML document, which is always required.

·        package – the required attribute for this element is the fully qualified package name.

<package name="com.sap.jdo.examples.empdep">…</package>

 

·        class – this is a child element of package. A required attribute is the fully qualified class name. In addition, you must specify the object ID class if the identity type is application. Note that if you do not specify the object ID class, the default identity type will be datastore.

If an extent should be managed for this class, you should include an attribute requires-extent = “true“. Its default value is “true” as well. Since relational databases implicitly and automatically manage the extent of persistent JDO classes, you can safely forget about this attribute.

For classes that have persistence capable superclasses, you must also add the persistence-capable-superclass attribute, which declares the fully qualified name of the persistence capable superclass.

<class name="Employee" identity-type="application" objectid-class="Employee$Id">...</class>

 

·        field – this is a child element of class, and it is optional. A valid field declaration requires the name of the field as defined in the persistence capable class.

You can specify the persistence modifier of the field – it can be either persistent, transactional, or none. For persistent fields the access is always mediated by the State Manager and their values are synchronized with the values in the data store. You can declare persistent fields of the primitive types, fields of the type java.lang.String ot java.lang.Number, and so on. For the transactional non-persistent fields only the write accesses are mediated by the StateManager, and their values are never written to the data store.

The fields that define the object identity in the case of application identity type are declared as primary-key. For these fields read access is always permitted, regardless of the instance’s state.

You can also use the default-fetch-group attribute for a non-key field to declare that the relevant field should be treated as a part of the default fetch group when it is retrieved. However, you cannot use this attribute for primary keys.

<field name="empId" persistence-modifier="persistent" primary-key="true"/>

 

·        collection – using this element, you can declare a collection of a specific element type.

<collection element-type="com.sap.jdo.examples.empdep.Employee"/>

 

·        map – with this element you can declare the types of the keys and values of a map typed field. In addition, you can choose to store them as a part of the instance if possible, or to store their instances in the data store.

·        array – using this element, you can specify the element type of an array typed field, as well as how the elements should be treated (similarly to the elements of the map typed fields).

For more information about the JDO metadata and its elements, see the Java™ Data Objects specification.