5.4. Field Element
Prev | Chapter 5. Metadata | Next

## 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`.

  - Fields of types `java.lang.String, java.lang.Number, java.math.BigDecimal, java.math.BigInteger, java.util.Locale`, and `java.util.Date` default to `persistent`.

  - Fields of any user-defined persistence-capable type default to `persistent`.

  - Arrays of any of the types above default to `persistent`.

  - Fields of the following container types in the `java.util` package default to `persistent`: `Collection, Set, List, Map, ArrayList, HashMap, HashSet, Hashtable, LinkedList, TreeMap, TreeSet, Vector`.

  - All other fields default to `none`.

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

Prev | Up | Next
5.3. Class Element | Home | 5.5. Fetch Group Element