JPA : XML Metadata Reference

JPA XML MetaData allows you to define mapping information but in a separate file (orm.xml) separating persistence mapping from your model. What follows provides a reference guide to MetaData elements. Here is an example header for orm.xml files with XSD specification

<?xml version="1.0" encoding="UTF-8" ?>
<entity-mappings xmlns="http://xmlns.jcp.org/xml/ns/persistence/orm"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence/orm
        http://xmlns.jcp.org/xml/ns/persistence/orm_2_1.xsd" version="2.1">
    ...
</entity-mappings>

If using any of the DataNucleus extensions, then the XSD is defined here, in which case you would define your header as :-

<?xml version="1.0" encoding="UTF-8" ?>
<entity-mappings xmlns="http://www.datanucleus.org/xsd/jpa/orm"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.datanucleus.org/xsd/jpa/orm
        http://www.datanucleus.org/xsd/jpa/orm_2_1.xsd" version="2.1">
    ...
</entity-mappings>

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 named-entity-graph tag

The <named-entity-graph> element (under <entity>) defines an entity graph with root as that entity, accessible at runtime via the name. It has the following attributes

Attribute Description Values
name Name of the entity graph


Metadata for named-attribute-node tag

The <named-attribute-node> element (under <named-entity-graph>) defines a node in the entity graph. It has the following attributes

Attribute Description Values
name Name of the node (field/property)
subgraph Name of a subgraph that maps this attribute fully (optional)


Metadata for subgraph/subclass-subgraph tag

The <subgraph>/subclass-subgraph element (under <named-entity-graph>) defines a subgraph in the entity graph. It has the following attributes

Attribute Description Values
name Name of the subgraph (referenced in the named-attribute-node)
class Type of the subgraph attribute


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 collection-table tag

These are attributes within the <collection-table> tag (under <element-collection>). This is used to define the join table where a collections 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


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
jdbc-type The JDBC Type to use for this column (DataNucleus extension)
position The position to use for this column (first=0) (DataNucleus extension)


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 datastore-id tag

These are attributes within the <datastore-id> tag (under <entity>). This is used to define the entity is using datastore identity (DataNucleus extension).

Attribute Description Values
column Name of the surrogate column to add for the datastore identity.
generated-value Details of the generated value strategy and generator. Please refer to the <generated-value>


Metadata for surrogate-version tag

These are attributes within the <surrogate-version> tag (under <entity>). This is used to define the entity has a surrogate version column (DataNucleus extension).

Attribute Description Values
column Name of the surrogate column to add for the version.
indexed Whether the surrogate version column should be indexed. true | false


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. Note that this is not yet fully supported - specify the fields in 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 element-collection tag

These are attributes within the <element-collection> tag (under <attributes>). This is used to define that the field is part of a 1-N non-PC relation.

Attribute Description Values
name Name of the field (required)
target-class Class name of the related object
fetch Whether the field should be fetched immediately EAGER | LAZY


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 embedded tag

These are attributes within the <embedded> tag (under <attributes>). This is used to define that the field is part of an embedded relation.

Attribute Description Values
name Name of the field (required)


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 map-key-temporal tag

Within the <map-key-temporal> tag (under <element-collection>, <one-to-many> or <many-to-many>) you put the TemporalType value.



Metadata for map-key-enumerated tag

Within the <map-key-enumerated> tag (under <element-collection>, <one-to-many> or <many-to-many>) you put the EnumType value.



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 index tag

These are attributes within the <index> element. This is used to define the details of an index when overriding the provider default.

Attribute Description Values
name Name of the index
unique Whether the index is unique
column-list List of columns (including any ASC, DESC specifications for each column)


Metadata for foreign-key tag

These are attributes within the <foreign-key> element. This is used to define the details of a foreign-key when overriding the provider default.

Attribute Description Values
name Name of the foreign-key
value Constraint mode
foreignKeyDefinition The DDL for the foreign key


Metadata for convert tag

These are attributes within the <convert> element, under <basic>. This is used to define the use of type conversion on this field.

Attribute Description Values
converter Class name of the converter
attribute-name Name of the embedded field to convert (optional). Not yet supported
disable-conversion Whether to disable any auto-apply converters for this field true | false


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)