5.4. Field Element

The class element may contain
extension elements, field
elements, and fetch-group elements.
field elements represent fields declared
by the persistent class. These elements are optional; if a field
declared in the class is not named by some field
element, then its properties are defaulted as explained in the
attribute listings below. Thanks to JDO's comprehensive set of
defaults, most fields do not need to be listed explicitly.
field elements accept the following attributes:

name: The name of the field, as it is
declared in the persistent class. This attribute is required.

persistence-modifier: Specifies how JDO
should manage the field. Legal values are
persistent for persistent fields,
transactional for fields that are
non-persistent but can be rolled back along with the current
transaction, and
none. The default value of
this attribute is based on the type of the field:

Fields declared static, transient,
or final default to
none.

Fields of any primitive or primitive wrapper type
default to persistent.

primary-key: Set this attribute to
true if the class uses application identity
and this field is a primary key field. Defaults to
false.

null-value: Specifies the treatment of
null values when the field is written to the
datastore. Use a value of none if the data
store should hold a null value for the
field. Use default to write a datastore
default value instead. Finally, use
exception if you want the JDO implementation
to throw an exception if the field is null
at flush time. Defaults to none.

default-fetch-group: Default fetch group
fields are managed as a single unit for efficiency. They are
typically loaded as a block from the datastore, and are
often written as a block as well. This attribute defaults to
true for primitive, primitive wrapper,
String, Date, BigDecimal, and
BigInteger types. All other types default
to false.

dependent: Set this attribute to
true to create a dependent
relation. In a dependent relation, the referenced object is
deleted whenever the owning object is deleted, or whenever the
relation is severed by nulling or resetting the owning field.
For example, if the Magazine.coverArticle
field is marked dependent, then setting
Magazine.coverArticle
to a new Article instance will
automatically delete the old Article
stored in the field. Similarly, deleting a Magazine
object will automatically delete its current cover
Article.

The dependent attribute is only meaningful
if the field holds a reference to another persistence-capable
object.

Note

Kodo allows you to assign a dependent object that has been
severed from its owning field or whose owner has been
deleted to another relation within the same transaction.
This will prevent the dependent object from being deleted.

embedded: This is a hint to the JDO
implementation to store the field as part of the class
instance in the datastore, rather than as a separate entity.
For example, a relational implementation might store a
Company's Address
properties in the same database row as the
Company record.
Embedded defaults to true for primitive,
primitive wrapper, Date, BigDecimal,
BigInteger, array, collection, and map
types. All other types default
to false. Embedded objects do not
appear in the Extent for their
class, and cannot be retrieved directly by query.

Any embedded relation to another persistence-capable object is
automatically dependent as well.

All field elements may contain
extension child elements. field
elements that represent array, collection, or map fields may also
contain a single array,
collection, or map child element,
respectively. Each of these elements may contain additional
extension elements in turn.

The array element has two attributes:

dependent-element: Equivalent to the
field element's
dependent attribute, but applies to the
values stored in each array index. In addition to the owning
field being reset or nulled, dependent elements can be
severed from their owner by removing the element from the
array. This will cause the element value to be deleted.

embedded-element: This attribute mirrors the
embedded attribute of the field
element, but applies to the values stored in each
array index.

The collection element also has the
dependent-element and embedded-element
attributes. Additionally, it declares the
element-type attribute. Use this
attribute to tell the JDO implementation what class of objects the
collection contains. This is important for efficient storage of the
collection contents. The element-type defaults to
java.lang.Object unless you are using Java 5
parameterized types, in which case it defaults to the type parameter
in your field declaration.

The map element define six attributes. They are:

key-type: The class of objects used for
map keys. Similar to element-type as
described above. The key-type defaults to
java.lang.Object unless you are using
Java 5 parameterized types, in which case it defaults to
the key type parameter in your field declaration.

dependent-key: Same as the
dependent-element attribute of arrays and
collections, but applies to map keys.

embedded-key: Same as the
embedded-element attribute of arrays and
collections, but applies to map keys.

value-type: The class of objects used for
map values. The value-type defaults to
java.lang.Object unless you are using Java 5
parameterized types, in which case it defaults to the value
type parameter in your field declaration.

dependent-value: Same as the
dependent-element element of arrays and
collections, but applies to map values.

embedded-value: Same as the
embedded-element element of arrays and
collections, but applies to map values.