diff --git a/spec/src/main/asciidoc/ch02-entities.adoc b/spec/src/main/asciidoc/ch02-entities.adoc index d6f4520e..1a334cdd 100644 --- a/spec/src/main/asciidoc/ch02-entities.adoc +++ b/spec/src/main/asciidoc/ch02-entities.adoc @@ -174,7 +174,7 @@ _byte[]_, _Byte[]_, _char[]_, _Character[]_, _java.time.LocalDate_, _java.time.LocalTime_, _java.time.LocalDateTime_, _java.time.OffsetTime_, _java.time.OffsetDateTime_, _java.time.Instant_, _java.time.Year_, -and user-defined types that implement the _Serializable_ interface _)_; +and user-defined types that implement the _Serializable_ interface); enums; entity types; collections of entity types; embeddable classes (see <>); collections of basic and embeddable types (see <>). @@ -379,45 +379,62 @@ contexts of differing access types within the same persistence unit. === Primary Keys and Entity Identity [[a132]] -Every entity must have a primary key. - -The primary key must be defined on the entity -class that is the root of the entity hierarchy or on a mapped superclass -that is a (direct or indirect) superclass of all entity classes in the -entity hierarchy. The primary key must be defined exactly once in an -entity hierarchy. - -* A primary key corresponds to one or more -fields or properties (“attributes”) of the entity class. -* A simple (i.e., non-composite) primary key -must correspond to a single persistent field or property of the entity -class. The _Id_ annotation or _id_ XML element must be used to denote a -simple primary key. See <>. -* A composite primary key must correspond to -either a single persistent field or property or to a set of such fields -or properties as described below. A primary key class must be defined to -represent a composite primary key. Composite primary keys typically -arise when mapping from legacy databases when the database key is -comprised of several columns. The _EmbeddedId_ or _IdClass_ annotation -is used to denote a composite primary key. See <> and <>. +Every entity must have a primary key. The primary key must be declared by: + +- the entity class that is the root of the entity hierarchy, or +- a mapped superclass that is a (direct or indirect) superclass of all + entity classes in the entity hierarchy. + +A primary key must be defined exactly once in each entity hierarchy. + +- A primary key comprises one or more fields or properties (“attributes”) + of the entity class. +- A _simple primary key_ is a single persistent field or property of the + entity class which type is one of the legal simple primary key types + listed below. The _Id_ annotation or _id_ XML element must be used to + identify the simple primary key. See <>. +- A _composite primary key_ must correspond to either a single persistent + field or property or to a set of such fields or properties, as described + below.footnote:[Composite primary keys often arise when mapping a legacy + database with primary keys comprising multiple columns.] + A _primary key class_ must be defined to represent the composite primary + key. + * When the composite primary key corresponds to a single field or + property of the entity, the _EmbeddedId_ annotation identifies the + primary key, and the type of the annotated field or property is the + primary key class. + * Otherwise, when the composite primary key corresponds to multiple + fields or properties, the _Id_ annotation identifies the fields and + properties which comprise the composite key, and the _IdClass_ + annotation is used to specify the primary key class. See <> + and <>. A simple primary key or a field or property of a composite primary key -should be one of the following types: any Java primitive type; -any primitive wrapper type; _java.lang.String_; _java.util.UUID_; -_java.util.Date_; _java.sql.Date_; _java.math.BigDecimal_; -_java.math.BigInteger_.footnote:[In general, however, -approximate numeric types (e.g., floating point types) should never be -used in primary keys.] If the primary key is a -composite primary key derived from the primary key of another entity, -the primary key may contain an attribute whose type is that of the -primary key of the referenced entity as described in <>. -Entities whose primary keys use types other than these will -not be portable. If generated primary keys are used, only integral types -will be portable. If _java.util.Date_ is used as a primary key field or -property, the temporal type should be specified as _DATE_. - -The following rules apply for composite -primary keys: +should have one of the following types: + +- any Java primitive type, or _java.lang_ wrapper for a primitive type, + footnote:[In general, however, approximate numeric types (e.g., + floating point types) should never be used in primary keys.] +- _java.lang.String_, +- _java.util.UUID_, +- _java.time.LocalDate_, +- _java.util.Date_ or _java.sql.Date_, +- _java.math.BigDecimal_ or _java.math.BigInteger_. + +If a primary key field or property has type _java.util.Date_, the temporal +type should be specified as _DATE_. See <>. + +If the primary key is a composite primary key derived from the primary +key of another entity, the primary key may contain an attribute whose +type is that of the primary key of the referenced entity. See <>. + +An entity with a primary key involving any type other than the types +listed above is not portable. If the primary key is generated, and its +type is not _java.util.UUID_, _java.lang.String_, _java.lang.Long_, +_java.lang.Integer_, _long_, or _int_, the entity is not portable. +See <>. + +The following rules apply to composite primary keys: - The primary key class may be a non-abstract regular Java class with a no-arg constructor. The no-arg constructor must be public or protected. @@ -1116,12 +1133,20 @@ public class MedicalHistory { === Basic Type [[a486]] -A basic type is any Java primitive type, wrapper of the primitive types, java.lang.String, -java.math.BigInteger, java.math.BigDecimal, java.util.Date, java.util.Calendar, -java.sql.Date, java.sql.Time, java.sql.Timestamp, java.time.LocalDate, java.time.LocalTime, -java.time.LocalDateTime, java.time.OffsetTime, java.time.OffsetDateTime, -java.time.Instant, java.time.Year, byte[], Byte[], char[], Character[], any enum type, -any other type that implements Serializable. +The following Java types are considered _basic types_: + +- any Java primitive type, or _java.lang_ wrapper class for a primitive type, +- _java.lang.String_, +- _java.util.UUID_, +- _java.math.BigInteger_, _java.math.BigDecimal_, +- _java.time.LocalDate_, _java.time.LocalTime_, _java.time.LocalDateTime_, + _java.time.OffsetTime_, _java.time.OffsetDateTime_, + _java.time.Instant_, _java.time.Year_, +- _java.util.Date_, _java.util.Calendar_, + _java.sql.Date_, _java.sql.Time_, _java.sql.Timestamp_, +- _byte[]_, _Byte[]_, _char[]_, _Character[]_, +- any Java `enum` type, +- any other type which implements `java.io.Serializable`. Persistence for basic types is defined in <> and <>. @@ -1269,31 +1294,21 @@ specify the value type for the map. Default mappings are described in === Mapping Defaults for Non-Relationship Fields or Properties [[a511]] -If a persistent field or property other than -a relationship property is _not_ annotated with one of the mapping -annotations defined in <> (or equivalent mapping information is not -specified in the XML descriptor), the following default mapping rules -are applied in order: - -* If the type is a class that is annotated with -the _Embeddable_ annotation, it is mapped in the same way as if the -field or property were annotated with the _Embedded_ annotation. See -<> and <>. -* If the type of the field or property is one of the following, it is -mapped in the same way as it would if it were annotated as _Basic_: -Java primitive types, wrappers of the primitive types, -_java.lang.String_, _java.math.BigInteger_, _java.math.BigDecimal_, -_java.util.UUID_, _java.util.Date_, _java.util.Calendar_, -_java.sql.Date_, _java.sql.Time_, _java.sql.Timestamp_, -_java.time.LocalDate_, _java.time.LocalTime_, -_java.time.LocalDateTime_, _java.time.OffsetTime_, -_java.time.OffsetDateTime_, _java.time.Instant_, _java.time.Year_ -_byte[]_, _Byte[]_, _char[]_, _Character[]_, enums, -any other type that implements _Serializable_. -See <>, <>, <>, and <>. - -It is an error if no annotation is present -and none of the above rules apply. +If a persistent field or property other than a relationship property is +_not_ annotated with one of the mapping annotations defined in <> +(and no equivalent mapping information is specified in any XML descriptor), +the following default mapping rules are applied in order: + +- If the type of the field or property is a class annotated with the + _Embeddable_ annotation, the field or property is mapped as if it were + annotated with the _Embedded_ annotation. See <> and <>. +- Otherwise, if the type of the field or property is one of the one of + the basic types listed in <>, it is mapped in the same way as if + it were annotated as _Basic_. See <>, <>, <>, + and <>. + +It is an error if no annotation is present and neither of the above rules +applies. === Entity Relationships [[a516]] diff --git a/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc b/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc index a7e4a38b..4480248e 100644 --- a/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc +++ b/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc @@ -529,18 +529,9 @@ public EmploymentPeriod getEmploymentPeriod() { ... } ==== Basic Annotation [[a14205]] -The _Basic_ annotation is the simplest type -of mapping to a database column. The _Basic_ annotation can be applied -to a persistent property or instance variable of any of the following -types: Java primitive types, wrappers of the primitive types, -_java.lang.String_, _java.math.BigInteger_, _java.math.BigDecimal_, -_java.util.UUID_, _java.util.Date_, _java.util.Calendar_, -_java.sql.Date_, _java.sql.Time_, _java.sql.Timestamp_, -_java.time.LocalDate_, _java.time.LocalTime_, _java.time.LocalDateTime_, -_java.time.OffsetTime_, _java.time.OffsetDateTime_, -_java.time.Instant_ and _java.time.Year_, -_byte[]_, _Byte[]_, _char[]_, _Character[]_, enums, and any other type -that implements _Serializable_. +The _Basic_ annotation is the simplest type of mapping to a database column. +The _Basic_ annotation may be applied to any persistent property or instance +variable whose type is one of the basic types listed in <>. For the types listed above, the persistence provider must support mappings to the column types listed in tables B-2 and B-4 of Appendix B of the @@ -2055,21 +2046,22 @@ Long id; ==== Id Annotation [[a14827]] -The _Id_ annotation specifies the primary key -property or field of an entity. The _Id_ annotation may be applied in an -entity or mapped superclass. +The _Id_ annotation declares a primary key property or field of an entity. +The _Id_ annotation may be applied to a property or field of: -The field or property to which the _Id_ annotation is applied should be -one of the following types: any Java primitive type; any primitive wrapper -type; _java.lang.String_; _java.util.UUID_; _java.util.Date_; _java.sql.Date_; -_java.math.BigDecimal_; _java.math.BigInteger_footnote:[Primary keys using -types other than these will not be portable. In general, floating point -types should never be used in primary keys.]. See <>. +- an entity class that is the root of an entity hierarchy, or +- a mapped superclass that is a superclass of all entity classes in an + entity hierarchy. -The mapped column for the primary key of the -entity is assumed to be the primary key of the primary table. If no -_Column_ annotation is specified, the primary key column name is assumed -to be the name of the primary key property or field. +The field or property to which the _Id_ annotation is applied should have +one of the legal simple primary key types listed in <>.footnote:[A +primary key with a type not listed is not portable.]footnote:[In general, +floating point types should never be used in primary keys.] + +The mapped column for the primary key of the entity is assumed to be the +primary key of the primary table. If no _Column_ annotation is specified, +the primary key column name is assumed to be the name of the primary key +property or field. [source,java] ---- @@ -5797,7 +5789,7 @@ See <>. The _GeneratedValue_ annotation indicates a primary key whose value is to be generated by the provider. If a strategy is indicated, the provider must use it if it is supported by -the target database. Note that specification of the AUTO strategy may +the target database. Note that specification of the _AUTO_ strategy may result in the provider creating a database object for Id generation (e.g., a database sequence). Rules for the _GeneratedValue_ annotation are described in <>. The _GeneratedValue_ annotation may only be portably used