JPA XML Meta-Data Reference

JPA XML MetaData has the following format. Please refer to the JPA ORM XSD for precise details. What follows provides a reference guide to MetaData elements.



Metadata for description tag

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.





Metadata for xml-mapping-metadata-complete tag

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.





Metadata for package tag

The <package> element (under <entity-mappings>) contains the text defining the package into which all classes in this file belong.





Metadata for schema tag

The <schema> element (under <entity-mappings>) contains the default schema for all classes in this file.





Metadata for catalog tag

The <catalog> element (under <entity-mappings>) contains the default catalog for all classes in this file.





Metadata for access tag

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





Metadata for sequence-generator tag

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




Metadata for table-generator tag

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




Metadata for named-query tag

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




Metadata for named-native-query tag

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




Metadata for sql-result-set-mapping tag

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)




Metadata for entity-result tag

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)




Metadata for field-result tag

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




Metadata for column-result tag

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




Metadata for mapped-superclass tag

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




Metadata for entity tag

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
cacheable Whether instances of this class should be cached in the L2 cache. New in JPA2 true | false




Metadata for description tag

The <description> element (under <entity>) contains the text describing the class being persisted. It serves no useful purpose other than descriptive.





Metadata for table tag

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




Metadata for secondary-table tag

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




Metadata for join-table tag

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
orphan-removal Whether to remove orphans when either removng the owner or nulling the relation false




Metadata for unique-constraint tag

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"





Metadata for column tag

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




Metadata for primary-key-join-column tag

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




Metadata for join-column tag

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 DataNucleus.
table Table for the column ?




Metadata for inverse-join-column tag

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 DataNucleus.
table Table for the column ?




Metadata for id-class tag

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)




Metadata for inheritance tag

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




Metadata for discriminator-value tag

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.





Metadata for discriminator-column tag

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




Metadata for id tag

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)




Metadata for generated-value tag

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 DataNucleus generator for the specified strategy. Please refer to the <sequence-generator> and <table-generator>




Metadata for embedded-id tag

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)




Metadata for version tag

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)




Metadata for basic tag

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




Metadata for temporal tag

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.





Metadata for enumerated tag

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.





Metadata for one-to-one tag

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)




Metadata for many-to-one tag

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




Metadata for one-to-many tag

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)
orphan-removal Whether to remove orphans when either removng the owner or removing the element false




Metadata for many-to-many tag

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




Metadata for order-by tag

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





Metadata for order-column tag

This element is specified under <one-to-many> or <many-to-many>. It is used to define that the List will be ordered with the ordering stored in a surrogate column in the other table.

Attribute Description Values
name Name of the column {fieldName}_ORDER
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
base Origin of the ordering (value for the first element) 0




Metadata for map-key tag

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)




Metadata for transient tag

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)




Metadata for exclude-default-listeners tag

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.





Metadata for exclude-superclass-listeners tag

This element is specified under <mapped-superclass> or <entity> and is used to denote that any listeners of superclasses will be ignored.





Metadata for entity-listener tag

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




Metadata for pre-persist tag

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)




Metadata for post-persist tag

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)




Metadata for pre-remove tag

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)




Metadata for post-remove tag

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)




Metadata for pre-update tag

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)




Metadata for post-update tag

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)




Metadata for post-load tag

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)




Metadata for attribute-override tag

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)




Metadata for association-override tag

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)