JPA MetaData has the following format. Please refer to the
JPA ORM XSD for precise
details. What follows provides a reference guide to MetaData elements.
The <description> element (<entity-mappings>) contains the text describing all
classes (and hence entities) defined in this file. It serves no useful purpose other than descriptive.
The <xml-mapping-metadata-complete> element (under <persistence-unit-metadata>)
when specified defines that the classes in this file are fully specified with just their metadata and
that any annotations should be ignored.
The <package> element (under <entity-mappings>) contains the text defining the
package into which all classes in this file belong.
The <schema> element (under <entity-mappings>) contains the default schema for all
classes in this file.
The <catalog> element (under <entity-mappings>) contains the default catalog for all
classes in this file.
The <access> element (under <entity-mappings>) contains the setting for how to access
the persistent fields/properties. This can be set to either "FIELD" or "PROPERTY".
The <sequence-generator> element (under <entity-mappings>, or <entity> or
<id>) defines a generator of sequence values, for use elsewhere in this persistence-unit.
| Attribute | Description | Values |
|---|
| name | Name of the generator (required) | |
| sequence-name | Name of the sequence | |
| initial-value | Initial value for the sequence | 1 |
| allocation-size | Number of values that the sequence allocates when needed | 50 |
The <table-generator> element (under <entity-mappings>, or <entity> or
<id>) defines a generator of sequence values using a datastore table, for use elsewhere in
this persistence-unit.
| Attribute | Description | Values |
|---|
| name | Name of the generator (required) | |
| table | name of the table to use for sequences | SEQUENCE_TABLE |
| catalog | Catalog to store the sequence table | |
| schema | Schema to store the sequence table | |
| pk-column-name | Name of the primary-key column in the table | SEQUENCE_NAME |
| value-column-name | Name of the value column in the table | NEXT_VAL |
| pk-column-value | Name of the value to use in the primary key column (for this row) | {name of the class} |
| initial-value | Initial value to use in the table | 0 |
| allocation-size | Number of values to allocate when needed | 50 |
The <named-query> element (under <entity-mappings> or under <entity>) defines
a JPQL query that will be accessible at runtime via the name. The element itself will contain the text
of the query. It has the following attributes
| Attribute | Description | Values |
|---|
| name | Name of the query | |
The <named-native-query> element (under <entity-mappings> or under <entity>)
defines an SQL query that will be accessible at runtime via the name. The element itself will contain
the text of the query. It has the following attributes
| Attribute | Description | Values |
|---|
| name | Name of the query | |
The <sql-result-set-mapping> element (under <entity-mappings> or under <entity>)
defines how the results of the SQL query are output to the user per row of the result set.
It will contain sub-elements. It has the following attributes
| Attribute | Description | Values |
|---|
| name | Name of the SQL result-set mapping (referenced by native queries) | |
The <entity-result> element (under <sql-result-set-mapping>)
defines an entity that is output from an SQL query per row of the result set.
It can contain sub-elements of type <field-result>. It has the following attributes
| Attribute | Description | Values |
|---|
| entity-class | Class of the entity | |
| discriminator-column | Column containing any discriminator (so subclasses of the entity type can be distinguished) | |
The <field-result> element (under <entity-result>)
defines a field of an entity and the column representing it in an SQL query.
It has the following attributes
| Attribute | Description | Values |
|---|
| name | Name of the entity field | |
| column | Name of the SQL column | |
The <column-result> element (under <sql-result-set-mapping>)
defines a column that is output directly from an SQL query per row of the result set.
It has the following attributes
| Attribute | Description | Values |
|---|
| name | Name of the SQL column | |
These are attributes within the <mapped-superclass> tag (under <entity-mappings>).
This is used to define the persistence definition for a class that has no table but is mapped.
| Attribute | Description | Values |
|---|
| class | Name of the class (required) | |
| metadata-complete | Whether the definition of persistence of this class is complete with this MetaData definition.
That is, should any annotations be ignored. | true | false |
These are attributes within the <entity> tag (under <entity-mappings>).
This is used to define the persistence definition for this class.
| Attribute | Description | Values |
|---|
| class | Name of the class (required) | |
| name | Name of the entity. Used by JPQL queries | |
| metadata-complete | Whether the definition of persistence of this class is complete with this MetaData definition.
That is, should any annotations be ignored. | true | false |
The <description> element (under <entity>) contains the text describing
the class being persisted. It serves no useful purpose other than descriptive.
These are attributes within the <table> tag (under <entity>).
This is used to define the table where this class will be persisted.
| Attribute | Description | Values |
|---|
| name | Name of the table | |
| catalog | Catalog where the table is stored | |
| schema | Schema where the table is stored | |
These are attributes within the <secondary-table> tag (under <entity>).
This is used to define the join of a secondary table back to the primary table where this class will be
persisted.
| Attribute | Description | Values |
|---|
| name | Name of the table | |
| catalog | Catalog where the table is stored | |
| schema | Schema where the table is stored | |
These are attributes within the <join-table> tag
(under <one-to-one>, <one-to-many>, <many-to-many>).
This is used to define the join table where a collection/maps relationship will be persisted.
| Attribute | Description | Values |
|---|
| name | Name of the join table | |
| catalog | Catalog where the join table is stored | |
| schema | Schema where the join table is stored | |
This element is specified under the <table>, <secondary-table> or
<join-table> tags. This is used to define a unique constraint on the table.
No attributes are provided, just sub-element(s) "column-name"
These are attributes within the <column> tag (under <basic>).
This is used to define the column where the data will be stored.
| Attribute | Description | Values |
|---|
| name | Name of the column | |
| unique | Whether the column is unique | true | false |
| nullable | Whether the column is nullable | true | false |
| insertable | Whether the column is insertable | true | false |
| updatable | Whether the column is updatable | true | false |
| column-definition | Some vague JPA term that you put anything in and get any unexpected results from | |
| table | Table for the column ? | |
| length | Length for the column (when string type) | 255 |
| precision | Precision for the column (when numeric type) | 0 |
| scale | Scale for the column (when numeric type) | 0 |
These are attributes within the <primary-join-key-column> tag
(under <secondary-table> or <entity>).
This is used to define the join of PK columns between secondary and primary tables, or
between table of subclass and table of base class.
| Attribute | Description | Values |
|---|
| name | Name of the column | |
| referenced-column-name | Name of column in primary table | |
These are attributes within the <join-column> tag (under <join-table>).
This is used to define the join column.
| Attribute | Description | Values |
|---|
| name | Name of the column | |
| referenced-column-name | Name of the column at the other side of the relation that this is a FK to | |
| unique | Whether the column is unique | true | false |
| nullable | Whether the column is nullable | true | false |
| insertable | Whether the column is insertable | true | false |
| updatable | Whether the column is updatable | true | false |
| column-definition | Some vague JPA term that you put anything in and get any unexpected results from.
Not supported by JPOX. | |
| table | Table for the column ? | |
These are attributes within the <inverse-join-column> tag (under <join-table>).
This is used to define the join column to the element.
| Attribute | Description | Values |
|---|
| name | Name of the column | |
| referenced-column-name | Name of the column at the other side of the relation that this is a FK to | |
| unique | Whether the column is unique | true | false |
| nullable | Whether the column is nullable | true | false |
| insertable | Whether the column is insertable | true | false |
| updatable | Whether the column is updatable | true | false |
| column-definition | Some vague JPA term that you put anything in and get any unexpected results from.
Not supported by JPOX. | |
| table | Table for the column ? | |
These are attributes within the <id-class> tag (under <entity>).
This defines a identity class to be used for this entity.
| Attribute | Description | Values |
|---|
| class | Name of the identity class (required) | |
These are attributes within the <inheritance> tag (under <entity>).
This defines the inheritance of the class.
| Attribute | Description | Values |
|---|
| strategy | Strategy for inheritance in terms of storing this class | SINGLE_TABLE | JOINED | TABLE_PER_CLASS |
These are attributes within the <discriminator-value> tag (under <entity>).
This defines the value used in a discriminator. The value is contained in the element.
Specification of the value will result in a "value-map" discriminator strategy being adopted.
If no discriminator-value is present, but discriminator-column is then "class-name" discriminator
strategy is used.
These are attributes within the <discriminator-column> tag (under <entity>).
This defines the column used for a discriminator.
| Attribute | Description | Values |
|---|
| name | Name of the discriminator column | DTYPE |
| discriminator-type | Type of data stored in the discriminator column | STRING | CHAR | INTEGER |
| length | Length of the discriminator column | |
These are attributes within the <id> tag (under <attributes>).
This is used to define the field used to be the identity of the class.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
These are attributes within the <generated-value> tag (under <id>).
This is used to define how to generate the value for the identity field.
| Attribute | Description | Values |
|---|
| strategy | Generation strategy.
Please refer to the Identity Generation Guide | auto | identity | sequence | table |
| generator | Name of the generator to use if wanting to override the default JPOX generator for the specified
strategy.
Please refer to the <sequence-generator> and
<table-generator> | |
These are attributes within the <embedded-id> tag (under <attributes>).
This is used to define the field used to be the (embedded) identity of the class.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
These are attributes within the <version> tag (under <attributes>).
This is used to define the field used to be hold the version of the class.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
These are attributes within the <basic> tag (under <attributes>).
This is used to define the persistence information for the field.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
| fetch | Fetch type for this field | LAZY | EAGER |
| optional | Whether this field may be null and may be used in schema generation | true | false |
These are attributes within the <temporal> tag (under <basic>).
This is used to define the details of persistence as a temporal type. The contents of the element
can be one of DATE, TIME, TIMESTAMP.
These are attributes within the <enumerated> tag (under <basic>).
This is used to define the details of persistence as an enum type. The contents of the element
can be one of ORDINAL or STRING to represent whether the enum is persisted as an integer-based or
the actual string.
These are attributes within the <one-to-one> tag (under <attributes>).
This is used to define that the field is part of a 1-1 relation.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
| target-entity | Class name of the related entity | |
| fetch | Whether the field should be fetched immediately | EAGER | LAZY |
| optional | Whether the field can store nulls. | true | false |
| mapped-by | Name of the field that owns the relation (specified on the inverse side) | |
These are attributes within the <many-to-one> tag (under <attributes>).
This is used to define that the field is part of a N-1 relation.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
| target-entity | Class name of the related entity | |
| fetch | Whether the field should be fetched immediately | EAGER | LAZY |
| optional | Whether the field can store nulls. | true | false |
These are attributes within the <one-to-many> tag (under <attributes>).
This is used to define that the field is part of a 1-N relation.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
| target-entity | Class name of the related entity | |
| fetch | Whether the field should be fetched immediately | EAGER | LAZY |
| mapped-by | Name of the field that owns the relation (specified on the inverse side) | |
These are attributes within the <many-to-many> tag (under <attributes>).
This is used to define that the field is part of a M-N relation.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
| target-entity | Class name of the related entity | |
| fetch | Whether the field should be fetched immediately | EAGER | LAZY |
| mapped-by | Name of the field on the non-owning side that completes the relation.
Specified on the owner side | |
This element is specified under <one-to-many> or <many-to-many>.
It is used to define the field(s) of the element class that is used for ordering the elements when
they are retrieved from the datastore. It has no attributes and the ordering is specified within
the element itself. It should be a comma-separated list of field names (of the element) with
optional "ASC" or "DESC" to signify ascending or descending
These are attributes within the <map-key> tag (under <one-to-many> or
<many-to-many>). This is used to define the field of the value class that is the key of a Map.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
These are attributes within the <transient> tag (under <attributes>).
This is used to define that the field is not to be persisted.
| Attribute | Description | Values |
|---|
| name | Name of the field (required) | |
This element is specified under <mapped-superclass> or <entity> and is used to denote
that any default listeners defined in this file will be ignored.
This element is specified under <mapped-superclass> or <entity> and is used to denote
that any listeners of superclasses will be ignored.
These are attributes within the <entity-listener> tag (under <entity-listeners>).
This is used to an EntityListener class and the methods it uses
| Attribute | Description | Values |
|---|
| class | Name of the EntityListener class that receives the callbacks for this Entity | |
These are attributes within the <pre-persist> tag (under <entity>).
This is used to define any "PrePersist" method callback.
| Attribute | Description | Values |
|---|
| method-name | Name of the method (required) | |
These are attributes within the <post-persist> tag (under <entity>).
This is used to define any "PostPersist" method callback.
| Attribute | Description | Values |
|---|
| method-name | Name of the method (required) | |
These are attributes within the <pre-remove> tag (under <entity>).
This is used to define any "PreRemove" method callback.
| Attribute | Description | Values |
|---|
| method-name | Name of the method (required) | |
These are attributes within the <post-remove> tag (under <entity>).
This is used to define any "PostRemove" method callback.
| Attribute | Description | Values |
|---|
| method-name | Name of the method (required) | |
These are attributes within the <pre-remove> tag (under <entity>).
This is used to define any "PreUpdate" method callback.
| Attribute | Description | Values |
|---|
| method-name | Name of the method (required) | |
These are attributes within the <post-update> tag (under <entity>).
This is used to define any "PostUpdate" method callback.
| Attribute | Description | Values |
|---|
| method-name | Name of the method (required) | |
These are attributes within the <post-load> tag (under <entity>).
This is used to define any "PostLoad" method callback.
| Attribute | Description | Values |
|---|
| method-name | Name of the method (required) | |
These are attributes within the <attribute-override> tag (under <entity>).
This is used to override the columns for any fields in superclasses
| Attribute | Description | Values |
|---|
| name | Name of the field/property (required) | |
These are attributes within the <association-override> tag (under <entity>).
This is used to override the columns for any N-1/1-1 fields in superclasses
| Attribute | Description | Values |
|---|
| name | Name of the field/property (required) | |
