B.2 Metadata Elements


The XML DTD for the JDO metadata defines the various elements that can be specified in the metadata file. In most cases, default values are defined that avoid having to specify values explicitly, except where the default is not appropriate. This keeps the average metadata file short and simple.

B.2.1 File header

A metadata file requires a header that specifies the XML version and encoding along with the location of the metadata XML DTD:

 
 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jdo SYSTEM "jdo.dtd"> 

The DTD location can be the public URL as published by Sun Microsystems, or it can be a DTD file stored elsewhere. The JDO 1.0.1 maintenance release defines two standard locations for the DTD. The public location is as follows :

 
[View full width]
 
[View full width]
<!DOCTYPE jdo PUBLIC "-//Sun Microsystems, Inc.//DTD Java Data Objects Metadata 1.0//EN" "http://java.sun.com graphics/ccc.gif /dtd/jdo_1_0.dtd">

A system location could be as follows:

 
 <!DOCTYPE jdo SYSTEM "file:/javax/jdo/jdo.dtd" 

If either of these two locations is used, then the JDO implementation may optimize access to the DTD by using its own local copy.

B.2.2 ELEMENT jdo

All other metadata elements are contained within the jdo element:

 
 <jdo> </jdo> 

The jdo element should contain one or more package elements and can contain zero or more extension elements.

B.2.3 ELEMENT package

A package element specifies the name of a package and contains the metadata for the persistence-capable classes within that package. The name attribute is used to specify the package name:

 
 <package name="com.corejdo.examples.model"> <\package> 

The package element should contain one or more class elements and can contain zero or more extension elements.

B.2.4 ELEMENT class

A class element specifies the name of a persistence-capable Java class and contains the metadata for specific fields within the class. The name attribute is used to specify the class name:

 
 <class name="Author"> </class> 

In addition to the name attribute, the class element has a number of optional attributes that can be specified:

identity-type: Can be application , datastore , or nondurable . Specifies the object identity type for the class. Defaults to the identity type of the persistence-capable-superclass class, if one is specified. Otherwise , if objectid-class is specified, this defaults to application ; otherwise, it defaults to datastore .

objectid-class: The name of the class that implements the application identity for the persistence-capable class. This attribute is applicable only when identity-type is specified as application . Defaults to the class specified by the persistence-capable-superclass class, if identity-type is application .

The class name follows Java rules for naming: If no package is included in the name, the package name is assumed to be the same package as the persistence-capable class. Inner classes are identified by the $ marker.

requires-extent: Can be true or false . Specifies whether an Extent is required for the class. Defaults to true .

persistence-capable-superclass: The name of the persistence-capable superclass of the class. If omitted, it is assumed that there is no superclass in the inheritance hierarchy that is persistence capable.

The class name uses Java rules for naming: If no package is included in the name, the package name is assumed to be the same package as the persistence-capable class.

The class element may contain zero or more field or extension elements.

B.2.5 ELEMENT field

A field element specifies the name of a field of the persistence-capable class and contains metadata about that field. The name attribute is used to specify the field name:

 
 <field name="books"> </field> 

The following optional attributes can also be specified:

persistence-modifier: Can be persistent , transactional , or none . Specifies whether the field should be stored in the datastore, not stored in the datastore but managed transactionally , or simply not managed at all. A transactional field's value is subject to rollback, and a field whose persistence-modifier is none is effectively ignored by the JDO implementation.

Fields declared as being static, transient, or final default to none . Fields of primitive types, wrapper types, and supported system interfaces or classes (see Chapter 3 for more details) default to persistent . The same is true for fields that reference persistence-capable classes. All other fields default to none .

primary-key: Can be true or false . Identifies the field as being part of the application identity for the class. Can be specified only for fields whose persistence-modifier is persistent . Defaults to false .

default-fetch- group : Can be true or false . Specifies whether the field should be part of the default fetch group for the class. Can be specified only for fields whose persistence-modifier is persistent . Defaults to true for fields of primitive types, wrapper types, supported types in the java.lang and java.math packages and java.util.Date . All other fields default to false .

embedded: Can be true or false . Provides a hint to the JDO implementation as to whether the field should be stored as part of the containing instance. Can be specified only for fields whose persistence-modifier is persistent . Fields of primitive types, wrapper types, and supported system interfaces or classes (see Chapter 3 for more details) default to true . The same is true for fields that are arrays of these types. All other fields default to false .

Specifying true for a field that is a reference to a persistence-capable class implies containment ”that the embedded instance has no independent existence in the datastore and is not part of its class's Extent . But this behavior is not further specified by JDO and is not portable.

null-value: Can be none , exception , or default . Specifies how null values should be handled in the datastore. If none , then null values are stored in the datastore as null; if the datastore does not support null, then a JDOUserException is thrown. If exception , then a JDOUserException is thrown if the field has a null value when stored. If default , then a null value is converted to the datastore's default representation when stored ”therefore, a null value may not be distinguishable from a default value. Defaults to none .

The field element may contain a collection , map , or array element and zero or more extension elements.

B.2.6 ELEMENT collection

A collection element can be used for java.util.Collection fields to specify additional metadata about the elements within the collection. It can specify the class name of the instances contained within the collection, as well as whether those instances should be stored as part of the containing instance:

 
 <collection> </collection> 

The following optional attributes can also be specified:

element-type: The class name of the instances contained within the collection. Defaults to Object if not specified.

The class name follows Java rules for naming: If no package is included in the name, the package name is assumed to be the same package as the persistence-capable class. Inner classes are identified by the $ marker.

embedded-element: Can be true or false . Specifies whether the instances contained within the collection should be stored as part of the containing instance. Defaults to false for collections of references to persistence-capable classes and interfaces; otherwise, defaults to true .

Specifying true for a collection of references to a persistence-capable class implies containment ”that the embedded instances have no independent existence in the data store and are not part of their class's Extent . But this behavior is not further specified by JDO and is not portable.

The collection element may contain zero or more extension elements.

B.2.7 ELEMENT map

A map element can optionally be used for fields of type java.util.Map to specify additional metadata about the elements within the map. It can specify the class name of the instances contained within the map (both keys and values), as well as whether those instances should be stored as part of the containing instance:

 
 <map> </map> 

The following optional attributes can also be specified:

key-type & element-type: The name of the class of the key or value instances contained within the map. Defaults to Object if not specified.

The class name follows Java rules for naming: If no package is included in the name, the package name is assumed to be the same package as the persistence-capable class. Inner classes are identified by the $ marker.

embedded-key & embedded-value: Can be true or false . Specifies whether the key or value instances contained within the map should be stored as part of the containing instance. Defaults to false for maps of references to persistence-capable classes and interfaces; otherwise, it defaults to true .

Specifying true for a map of references to a persistence-capable class implies containment ”that is the embedded instances have no independent existence in the datastore and are not part of their class's Extent . But this behavior is not further specified by JDO and is not portable.

The map element may contain zero or more extension elements.

B.2.8 ELEMENT array

An array element can optionally be used for array fields to specify additional metadata about the elements within the array. It can specify whether those instances should be stored as part of the containing instance:

 
 <array> </array> 

The following optional attributes can also be specified:

embedded-element: Can be true or false . Specifies whether the instances contained within the array should be stored as part of the containing instance. Defaults to false for arrays of references to persistence-capable classes and interfaces; otherwise, it defaults to true .

Specifying true for an array of references to a persistence-capable class implies containment ”that the embedded instances have no independent existence in the datastore and are not part of their class's Extent . But this behavior is not further specified by JDO and is not portable.

The collection element may contain zero or more extension elements.

B.2.9 ELEMENT extension

Each of the elements already outlined can contain zero or more extension elements. This element allows additional metadata to be specified that is specific to a particular JDO implementation. The vendor-name attribute is used to identify a vendor:

 
 <extension vendor-name="JDORI"> </extension> 

The vendor name JDORI is reserved for use by the JDO reference implementation. The following optional attributes can also be specified:

key: A string that is specific to the given JDO implementation.

value: A string that is specific to the given JDO implementation.

An extension element may be ignored by any JDO implementation.



Core Java Data Objects
Core Java Data Objects
ISBN: 0131407317
EAN: 2147483647
Year: 2003
Pages: 146

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net