4.3. Field-level Object-Relational Mapping Extensions
Prev | Chapter 4. Metadata | Next

## 4.3. Field-level Object-Relational Mapping Extensions

The following keys are recognized for `extension` elements that are direct children of `field` elements in the metadata document:

- `dependent`: Setting a value of `true` for this extension indicates that the persistent object stored in this field should be deleted when the parent object is deleted. The deletion of dependent field values occurs during the commit process.

- `element-dependent`: This extension is equivalent to the `dependent` extension above, but applies to the element values of collection fields. Use this extension for one-to-many or many-to-many relations where the related objects should be deleted along with the owning object.

- `value-dependent`: This extension is equivalent to the `dependent` extension above, but applies to first class map values.

- `key-dependent`: This extension is equivalent to the `dependent` extension above, but applies to first class map keys (note: first class map keys are not yet supported.

- `inverse`: Specifies the field name of the other side of a two-sided relationship between objects. It is safe to leave out this extension, but the relational schema can be more efficient when the inverse is known. In object-relational mapping terms, inverses are used to detect 2-sided one-to-ones, one-to-many and 2-sided many-to-many mappings.

- `blob`: Takes a value of `true` or `false`. This extension can be used to explicitly mark fields that should be stored as serialized BLOB values. For example, Kodo JDO would normally store a field of type `byte[]` using a secondary table with a row for each byte value in the array; this type of storage allows for queries on the array. If the `byte[]` is large or contains information that should not be query-able, it may be more efficient to store it as a BLOB column of the main table. Fields that Kodo JDO cannot normally persist, such as user-defined interface fields or fields of type `java.lang.Object` are defaulted to use BLOB mappings. In these cases this extension is not necessary, though it is still allowed.

- `column-length`: String fields can specify the maximum length of the String that will be stored in the database column. The default maximum is 255 characters. Use a value of -1 to indicate that there should be no length limit on the String. In this case, the column will be created as a CLOB, or the correct database equivalent. Currently, this extension is used only when creating a schema using the `schematool`. In the future, this extension may be also used for performing runtime data validations.

- `column-index`: This extension takes a value of `true` or `false` to specify whether the column holding the data for the field should be indexed.

- `ordered`: This extension accepts a value of `true` or `false`. By default, databases do not guarantee the order in which results are read. Thus, collection and array field elements may be retrieved from the database in a different order from the one in which they were stored. A value of `true` for this key, however, will ensure that the order of the elements in this field is retained during database reads. This flag is useful only for collection and array fields that represent a one-sided relationship, such as a collection of simple values or a 1-sided many-to-many relation. It cannot be used for one-to-many relations or shared many-to-many relations. See the order-column extension for more information.

- `table`: Some mappings do not store their data in the class' primary table. This extension specifies the table where the data for this field is stored. This attribute is also used in multi-table inheritance mappings.

  For collection, array, and map fields, this is the secondary or cross-reference table used to hold the field value. Normally, Kodo JDO auto-generates secondary tables based on the class and field name. Note that this extension should not be used for one-to-many collections, since there is no secondary table for such collections.

- `data-column`: This extension specifies the column in which the data for this field is stored. For simple fields, this column must belong to the primary table of the class (i.e., the table in which the primary key value is stored). For collection and map fields, this column can belong to a secondary table, as long as an additional `ref` column is provided to link the secondary table to the primary (see below). If this field represents a relation to another persistent object, the named column should hold the primary key value of the related instance. Note that this extension is ignored if the class to which this field refers uses application identity. The next section covers application identity extensions.

- `key-column`: This extension is applicable only to map fields. It specifies the column of the secondary table that holds the key values.

- `ref-column`: This extension is only for a collection or map field whose data column exists in a secondary table. The `ref-column` must be in the same table as the data column, and must contain the primary key value of the owning instance. This allows a SQL join to be performed linking this ref column with the primary key column of the primary table. Note that this extension is ignored if the class to which this field refers uses application identity. The next section covers application identity extensions.

- `order-column`: This extension is applicable only to collection fields that also have the `ordered` extension. It specifies the column of the secondary table used to hold ordering information. This column must be of a numeric type. If the `ordered` extension is given but this extension is omitted, Kodo JDO will create its own order column, usually named `JDOORDERX`.

- `read-only`: This extension is used for inverse one-to-one relations and collection fields that represent a shared many-to-many mapping.

  In inverse one-to-one relations, this meta data flag marks which class does not own the field in its table, and thus has a read-only view of the relational data. If neither side of such a relation is marked read-only, Kodo will automatically choose one side as such.

  In many-to-many collection field mappings, one class can declare its field to be read-only in order to avoid duplicate inserts into the shared table. The value of this extension should be either `true` or `false`. Note that Kodo JDO typically makes one side of the relation read-only automatically; this extension is never strictly needed.

- `custom-mapping`: This optional extension stores the name of the `FieldMapping` subclass to use for this field.

Prev | Up | Next
4.2. Class-level Object-Relational Mapping Extensions | Home | 4.4. Extensions Under Application Identity