13.3 O/R mapping files

The following table describes the configuration of the O/R mapping files:

Tag name							Occurrence pattern	Description
`<entity-mappings>`							Once	Indicates the root tag.
	`<description>`						0 or once	Adds the description.
	`<persistence-unit-metadata>`						0 or once	Specifies the definition related to the entire `PersistenceUnit`.
		`<xml-mapping-metadata-complete>`					0 or once	Specifies whether to control the mapping metadata of the persistence unit.
		`<persistence-unit-defaults>`					0 or once	Specifies the default value of the persistence unit.
			`<schema>`				0 or once	Defines the schema.
			`<catalog>`				0 or once	Defines the catalog.
			`<access>`				0 or once	Specifies the access type.
			`<cascade-persist>`				0 or once	Adds the cascade persistence option.
			`<entity-listeners>`				0 or once	Defines the default entity listener of the persistence unit.
				`<entity-listener>`			0 or more times	Specifies the entity listener.
					`<pre-persist>`		0 or once	Specifies the lifecycle callback method.
					`<post-persist>`		0 or once	Specifies the lifecycle callback method.
					`<pre-remove>`		0 or once	Specifies the lifecycle callback method.
					`<post-remove>`		0 or once	Specifies the lifecycle callback method.
					`<pre-update>`		0 or once	Specifies the lifecycle callback method.
					`<post-update>`		0 or once	Specifies the lifecycle callback method.
					`<post-load>`		0 or once	Specifies the lifecycle callback method.
	`<package>`						0 or once	Specifies the class package described in the elements and attributes within the same mapping file.
	`<schema>`						0 or once	Defines the schema.
	`<catalog>`						0 or once	Defines the catalog.
	`<access>`						0 or once	Defines the access method.
	`<sequence-generator>`						0 or more times	Adds the sequence generator.
	`<table-generator>`						0 or more times	Defines the table generator.
		`<unique-constraint>`					0 or more times	Adds a unique constraint to DDL.
			`<column-name>`				One or more times	Specifies the name of the column in which the unique constraint will be added.
	`<named-query>`						0 or more times	Defines a named query.
		`<query>`					Once	Specifies the query string.
		`<hint>`					0 or more times	Adds a hint to the query.
	`<named-native-query>`						0 or more times	Defines the named native query.
		`<query>`					Once	Specifies the query string.
		`<hint>`					0 or more times	Adds a hint to the query.
	`<sql-result-set-mapping>`						0 or more times	Defines the SQL result set mapping.
		`<entity-result>`					0 or more times	Specifies the `entity` class used for mapping the native SQL query result.
			`<field-result>`				0 or more times	Specifies the field used for mapping the native SQL query result.
		`<column-result>`					0 or more times	Specifies the column used for mapping the native SQL query result.
	`<mapped-superclass>`						0 or more times	Defines the mapped superclass of the persistence unit.
		`<description>`					0 or once	Adds the description for the mapped superclass of the persistence unit.
		`<id-class>`					0 or once	Overwrites `@IdClass` specified in the mapped superclass.
		`<exclude-default-listeners>`					0 or once	Defines whether to control the default entity listener of the mapped superclass and the sub class.
		`<exclude-superclass-listeners>`					0 or once	Defines whether to control the superclass listener of the mapped superclass and the sub class.
		`<entity-listeners>`					0 or once	Specifies the callback listener class.
			`<entity-listener>`				0 or more times	Specifies the entity listener.
				`<pre-persist>`			0 or once	Specifies the lifecycle callback method.
				`<post-persist>`			0 or once
				`<pre-remove>`			0 or once
				`<post-remove>`			0 or once
				`<pre-update>`			0 or once
				`<post-update>`			0 or once
				`<post-load>`			0 or once
		`<pre-persist>`					0 or once	Defines the lifecycle callback method using the corresponding annotations in the mapped superclass.
		`<post-persist>`					0 or once
		`<pre-remove>`					0 or once
		`<post-remove>`					0 or once
		`<pre-update>`					0 or once
		`<post-update>`					0 or once
		`<post-load>`					0 or once
		`<attributes>`					0 or once	The element is not defined.
			`<id>`				0 or more times^#1	Overwrites the mapping specified in fields and properties.
				`<column>`			0 or once	Specifies the column mapping for the properties of the Persistent field.
				`<generated-value>`			0 or once	Specifies the strategy for generating the primary key value.
				`<temporal>`			0 or once	Specified when mapping to the DATE, TIME, and TIMESTAMP type.
				`<table-generator>`			0 or once	Adds the table generator.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<sequence-generator>`			0 or once	Adds the sequence generator.
			`<embedded-id>`				0 or once^#1	Overwrites the mapping specified in fields and properties.
				`<attribute-override>`			0 or more times	Overwrites the mapping of properties and fields.
					`<column>`		Once	Specifies the column mapping for the properties of the Persistent field.
			`<basic>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<column>`			0 or once	Specifies the column mapping for the properties of the Persistent field.
				`<lob>`			0 or once^#2	Specified when mapping to the Lob type.
				`<temporal>`			0 or once^#2	Specified when mapping to the DATE, TIME, and TIMESTAMP type.
				`<enumerated>`			0 or once^#2	Specified when mapping to the enumeration type.
			`<version>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<column>`			0 or once	Specifies the column mapping for the properties of the Persistent field.
				`<temporal>`			0 or once	Specified when mapping to the DATE, TIME, and TIMESTAMP type.
			`<many-to-one>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<join-column>`			0 or more times^#3	Specifies the external key column of the join table corresponding to the owner-side entity.
				`<join-table>`			0 or once^#3	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<one-to-many>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<order-by>`			0 or once	Specifies the order to be applied when maintaining a relation in the collection.
				`<map-key>`			0 or once	Specifies the map key as the Map type relation.
				`<join-table>`			0 or once^#4	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<join-column>`			0 or more times^#4	Specifies the external key column of the join table corresponding to the owner-side entity.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<one-to-one>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<primary-key-join-column>`			0 or more times^#5	Specifies the primary key column used as external key to JOIN with other tables.
				`<join-column>`			0 or more times^#5	Specifies the external key column of the join table corresponding to the owner-side entity.
				`<join-table>`			0 or once^#5	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<many-to-many>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<order-by>`			0 or once	Specifies the order to be applied when maintaining a relation in the collection.
				`<map-key>`			0 or once	Specifies the map key as the Map type relation.
				`<join-table>`			0 or once	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<embedded>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<attribute-override>`			0 or more times	Overwrites the mapping of properties and fields.
					`<column>`		Once	Specifies the column mapping for the properties of the Persistent field.
			`<transient>`				0 or more times	Overwrites the mapping specified in fields and properties.
	`<entity>`						0 or more times	Defines the entities of the persistence unit.
		`<description>`					0 or once	Adds the description for the entities of the persistence unit.
		`<table>`					0 or once	Overwrites `@Table` (including default values) of the `entity` class.
			`<unique-constraint>`				0 or more times	Adds a unique constraint to DDL.
				`<column-name>`			One or more times	Specifies the name of the column in which the unique constraint will be added.
		`<secondary-table>`					0 or more times	Overwrites all `@SecondaryTable` and `@SecondaryTables` (including default values) of the `entity` class.
			`<primary-key-join-column>`				0 or more times	Overwrites all `@PrimaryKeyJoinColumn` and `@PrimaryKeyJoinColumns` (including default values) of the `entity` class.
			`<unique-constraint>`				0 or more times	Adds a unique constraint to DDL.
				`<column-name>`			One or more times	Specifies the name of the column in which the unique constraint will be added.
		`<primary-key-join-column>`					0 or more times	Overwrites all `@PrimaryKeyJoinColumn` and `@PrimaryKeyJoinColumns` (including default values) of the `entity` class.
		`<id-class>`					0 or once	Overwrites `@IdClass` specified in the `entity` class.
		`<inheritance>`					0 or once	Overwrites `@Inheritance` (including default values) of the `entity` class.
		`<discriminator-value>`					0 or once	Overwrites `@Discriminator`Value (including default values) of the `entity` class.
		`<discriminator-column>`					0 or once	Overwrites `@DiscriminatorColumn` (including default values) of the `entity` class.
		`<sequence-generator>`					0 or once	Specifies the settings for the sequence generator that creates the primary key.
		`<table-generator>`					0 or once	Specifies the settings for the generator that creates the primary key.
			`<unique-constraint>`				0 or more times	Adds a unique constraint to DDL.
				`<column-name>`			One or more times	Specifies the name of the column in which the unique constraint will be added.
		`<named-query>`					0 or more times	Defines a named query.
			`<query>`				Once	Specifies the query string.
			`<hint>`				0 or more times	Adds a hint to the query.
		`<named-native-query>`					0 or more times	Defines the named native query.
			`<query>`				Once	Specifies the query string.
			`<hint>`				0 or more times	Adds a hint to the query.
		`<sql-result-set-mapping>`					0 or more times	Defines the mapping of the SQL results.
			`<entity-result>`				0 or more times	Specifies the `entity` class used for mapping the native SQL query result.
				`<field-result>`			0 or more times	Specifies the field used for mapping the native SQL query result.
			`<column-result>`				0 or more times	Specifies the column used for mapping the native SQL query result.
		`<exclude-default-listeners>`					0 or once	Controls the default entity listeners of the `entity` class and the sub class.
		`<exclude-superclass-listeners>`					0 or once	Controls the superclass listeners of the `entity` class and the sub class.
		`<entity-listeners>`					0 or once	Overwrites `@EntityListeners` of the `entity` class.
			`<entity-listener>`				0 or more times	Specifies the entity listener.
				`<pre-persist>`			0 or once	Overwrites the definition of the lifecycle callback method according to the corresponding annotations, in the mapped superclass.
				`<post-persist>`			0 or once
				`<pre-remove>`			0 or once
				`<post-remove>`			0 or once
				`<pre-update>`			0 or once
				`<post-update>`			0 or once
				`<post-load>`			0 or once
		`<pre-persist>`					0 or once	Overwrites the definition of the lifecycle callback method according to the corresponding annotations, in the `entity` class.
		`<post-persist>`					0 or once
		`<pre-remove>`					0 or once
		`<post-remove>`					0 or once
		`<pre-update>`					0 or once
		`<post-update>`					0 or once
		`<post-load>`					0 or once
		`<attribute-override>`					0 or more times	Added to the value defined in `@AttributeOverride` or `@AttributeOverrides` of the `entity` class.
			`<column>`				Once	Specifies the column mapping for the properties of the Persistent field.
		`<association-override>`					0 or more times	Added to the value defined in `@AssociationOverride` or `@AssociationOverride`s of the `entity` class.
			`<join-column>`				One or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
		`<attributes>`					0 or once	The element is not defined.
			`<id>`				0 or more times^#1	Overwrites the mapping specified in fields and properties.
				`<column>`			0 or once	Specifies the column mapping for the properties of the Persistent field.
				`<generated-value>`			0 or once	Specifies the strategy for generating the primary key value.
				`<temporal>`			0 or once	Specified when mapping to the DATE, TIME, and TIMESTAMP type.
				`<table-generator>`			0 or once	Adds the table generator.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<sequence-generator>`			0 or once	Specifies the settings for the sequence generator that creates the primary key.
			`<embedded-id>`				0 or once^#1	Overwrites the mapping specified in fields and properties.
				`<attribute-override>`			0 or more times	Added to the value defined in `@AttributeOverride` or `@AttributeOverrides` of the `entity` class.
					`<column>`		Once	Specifies the column mapping for the properties of the Persistent field.
			`<basic>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<column>`			0 or once	Specifies the column mapping for the properties of the Persistent field.
				`<lob>`			0 or once^#2	Specified when mapping to the Lob type.
				`<temporal>`			0 or once	Specified when mapping to the DATE, TIME, and TIMESTAMP type.
				`<enumerated>`			0 or once^#2	Specified when mapping to the enumeration type.
			`<version>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<column>`			0 or once	Specifies the column mapping for the properties of the Persistent field.
				`<temporal>`			0 or once	Specified when mapping to the DATE, TIME, and TIMESTAMP type.
			`<many-to-one>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<join-column>`			0 or more times^#4	Specifies the external key column of the join table corresponding to the owner-side entity.
				`<join-table>`			0 or once^#4	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<one-to-many>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<order-by>`			0 or once	Specifies the order to be applied when maintaining a relation in the collection.
				`<map-key>`			0 or once	Specifies the map key as the Map type relation.
				`<join-table>`			0 or once^#3	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<join-column>`			0 or more times^#3	Specifies the external key column of the join table corresponding to the owner-side entity.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<one-to-one>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<primary-key-join-column>`			0 or more times^#5	Overwrites all `@PrimaryKeyJoinColumn` and `@PrimaryKeyJoinColumns` (including default values) of the `entity` class.
				`<join-column>`			0 or more times^#5	Specifies the external key column of the join table corresponding to the owner-side entity.
				`<join-table>`			0 or once^#5	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<many-to-many>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<order-by>`			0 or once	Specifies the order to be applied when maintaining a relation in the collection.
				`<map-key>`			0 or once	Specifies the map key as the Map type relation.
				`<join-table>`			0 or once	Specifies the join table to be used in many-to-many and the unilateral one-to-many relationships.
					`<join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owner-side entity.
					`<inverse-join-column>`		0 or more times	Specifies the external key column of the join table corresponding to the owned-side entity.
					`<unique-constraint>`		0 or more times	Adds a unique constraint to DDL.
						`<column-name>`	One or more times	Specifies the name of the column in which the unique constraint will be added.
				`<cascade>`			0 or once	Specifies the operations that you can cascade.
					`<cascade-all>`		0 or once	Cascades all the operations.
					`<cascade-persist>`		0 or once	Cascades the persist operation.
					`<cascade-merge>`		0 or once	Cascades the merge operation.
					`<cascade-remove>`		0 or once	Cascades the remove operation.
					`<cascade-refresh>`		0 or once	Cascades the refresh operation.
			`<embedded>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<attribute-override>`			0 or more times	Added to the value defined in `@AttributeOverride` or `@AttributeOverrides` of the `entity` class.
					`<column>`		Once	Specifies the column mapping for the properties of the Persistent field.
			`<transient>`				0 or more times	Overwrites the mapping specified in fields and properties.
	`<embeddable>`						0 or more times	Defines the `embeddable` class of the persistence unit.
		`<description>`					0 or once	Adds the description for the `embeddable` class of the persistence unit.
		`<attributes>`					0 or once	The element is not defined.
			`<basic>`				0 or more times	Overwrites the mapping specified in fields and properties.
				`<column>`			0 or once	Specifies the column mapping for the properties of the Persistent field.
				`<lob>`			0 or once^#2	Specified when mapping to the Lob type.
				`<temporal>`			0 or once^#2	Specified when mapping to the DATE, TIME, and TIMESTAMP type.
				`<enumerated>`			0 or once^#2	Specified when mapping to the enumeration type.
			`<transient>`				0 or more times	Overwrites the mapping specified in fields and properties.

#1: Specify any one among the <id> tag and the <embedded-id> tag.
#2: Specify any one among the <lob> tag, the <temporal> tag, and the <enumerated> tag.
#3: Specify any one among the <join-column> tag and the <join-table> tag.
#4: Specify any one among the <join-table> tag and the <join-column> tag.
#5: Specify any one among the <primary-key-join-column> tag, the <join-column> tag, and the <join-table> tag.

Organization of this section

To Page Top