diff --git a/annotations/src/main/docbook/en/modules/entity.xml b/annotations/src/main/docbook/en/modules/entity.xml index 9a152919ab..3bbbd4e944 100644 --- a/annotations/src/main/docbook/en/modules/entity.xml +++ b/annotations/src/main/docbook/en/modules/entity.xml @@ -1,4 +1,4 @@ - + - - + Entity Beans @@ -463,10 +463,10 @@ public class Country implements Serializable { } - A embeddable object inherit the access type of its owning entity - (note that you can override that using the Hibernate specific - @AccessType annotations (see ). + An embeddable object inherits the access type of its owning + entity (note that you can override that using + @Access or the Hibernate specific + @AccessType annotation. The Person entity bean has two component properties, homeAddress and @@ -939,8 +939,8 @@ public class BaseEntity { - The access type (field or methods), is inherited from the root - entity, unless you use the Hibernate annotation + The default access type (field or methods) is used, unless you + use the @Access or @AccessType @@ -1799,14 +1799,14 @@ public class RegionalArticlePk implements Serializable { ... } @Embeddable inherit the access type of its - owning entity unless the Hibernate specific annotation - @AccessType is used. Composite foreign keys (if not - using the default sensitive values) are defined on associations using - the @JoinColumns element, which is basically an array - of @JoinColumn. It is considered a good practice to - express referencedColumnNames explicitly. Otherwise, - Hibernate will suppose that you use the same order of columns as in the - primary key declaration. + owning entity unless @Access or the Hibernate + specific annotation @AccessType is used. Composite + foreign keys (if not using the default sensitive values) are defined on + associations using the @JoinColumns element, which is + basically an array of @JoinColumn. It is considered a + good practice to express referencedColumnNames + explicitly. Otherwise, Hibernate will suppose that you use the same + order of columns as in the primary key declaration. @Entity @@ -2528,26 +2528,20 @@ List results = s.createCriteria( Citizen.class ) Access type - The access type is guessed from the position of - @Id or @EmbeddedId in the entity - hierarchy. Sub-entities, embedded objects and mapped superclass - inherit the access type from the root entity. + The default access type is determined from the position of the + @Id or @EmbeddedId annotation in + the entity hierarchy. - In Hibernate, you can override the access type to: + + The placement of annotations within a class hierarchy has to + be consistent (either field or on property) to be able to determine + the default access type. It is recommended to stick to one single + annotation placement strategy throughout your whole + application. + - - - use a custom access type strategy - - - - fine tune the access type at the class level or at the - property level - - - - An @AccessType annotation has been introduced to support this - behavior. You can define the access type on + To finetune the access strategy JPA 2 introduces the @Access + annotation. With its help you can define the access type on: @@ -2567,28 +2561,96 @@ List results = s.createCriteria( Citizen.class ) - The access type is overriden for the annotated element, if - overriden on a class, all the properties of the given class inherit - the access type. For root entities, the access type is considered to - be the default one for the whole hierarchy (overridable at class or - property level). + Prior to JPA 2 Hibernate used the Hibernate specific annotation + @org.hibernate.annotations.AccessType to change + specific access types. @AccessType still exists to support legacy + systems, but the usage of @Access is recommended for new applications. + The behaviour of @Access and @AccessType are similar, but there are + differences. For both annotations applies: - If the access type is marked as "property", the getters are - scanned for annotations, if the access type is marked as "field", the - fields are scanned for annotations. Otherwise the elements marked with - @Id or @embeddedId are scanned. + + + The access type is overriden for the annotated element, if + overriden on a class, all the properties of the given class + inherit the access type. + - You can override an access type for a property, but the element - to annotate will not be influenced: for example an entity having - access type field, can annotate a field with - @AccessType("property"), the access type will then - be property for this attribute, the the annotations still have to be - carried on the field. + + If an entity is marked as + @Access(AccessType.PROPERTY) or + @AccessType("property") respectively, the + getters are scanned for annotations, if the enitiy is marked as + @Access(AccessType.FIELD) or + @AccessType("field") respectively, the fields + are scanned for annotations. + + + + In the case where you want to override the access type for a + property of an entity which already defines an explicit access type + the annotation placement between @Access and @AccessType + differs: + + @AccessType("property") // set access type for all properties in Country +public class Country implements Serializable { + private String iso2; + private String name; + + public String getIso2() { + return iso2; + } + + public void setIso2(String iso2) { + this.iso2 = iso2; + } + + @Column(name = "countryName") + @AccessType("field") // set the access type for name to field + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } +} + + + @Access(AccessType.PROPERTY) // set access type for all properties in Country +public class Country implements Serializable { + private String iso2; + + @Access(AccessType.FIELD) // set the access type for name to field + private String name; + + public String getIso2() { + return iso2; + } + + public void setIso2(String iso2) { + this.iso2 = iso2; + } + + @Column(name = "countryName") + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } +} + + + + Watch out for the different annotation placement strategy. In + the case of @Access the field has to be annotated + with the overriding access strategy whereas with + @AccessType the property gets annotated. + If a superclass or an embeddable object is not annotated, the - root entity access type is used (even if an access type has been - define on an intermediate superclass or embeddable object). The - russian doll principle does not apply. + default entity access type is used. @Entity public class Person implements Serializable { @@ -2655,14 +2717,28 @@ public long getObjectVolume() @org.hibernate.annotations.TypeDef and @org.hibernate.annotations.TypeDefs allows you to - declare type definitions. These annotations can be placed at the class or - package level. Note that these definitions are global for the - session factory (even when defined at the class level). If the type is used on a single entity, you can place the definition on the entity itself. Otherwise, it is recommended to place the definition at the package level. In the example below, when Hibernate encounters a property of class PhoneNumer, it delegates the persistence strategy to the custom mapping type PhoneNumberType. However, properties belonging to other classes, too, can delegate their persistence strategy to PhoneNumberType, by explicitly using the @Type annotation. + declare type definitions. These annotations can be placed at the class + or package level. Note that these definitions are global for the + session factory (even when defined at the class level). If the type is + used on a single entity, you can place the definition on the entity + itself. Otherwise, it is recommended to place the definition at the + package level. In the example below, when Hibernate encounters a + property of class PhoneNumer, it delegates the + persistence strategy to the custom mapping type + PhoneNumberType. However, properties belonging to + other classes, too, can delegate their persistence strategy to + PhoneNumberType, by explicitly using the + @Type annotation. - Package level annotations are placed in a file named package-info.java - in the appropriate package. Place your annotations before the package declaration. + + Package level annotations are placed in a file named - + package-info.java + + in the appropriate package. Place your annotations before the package declaration. + + + @TypeDef( name = "phoneNumber", defaultForType = PhoneNumber.class, @@ -2681,10 +2757,9 @@ public class ContactDetails { - -The following example shows the usage of the parameters attribute to customize the TypeDef. - - + The following example shows the usage of the + parameters attribute to customize the + TypeDef. //in org/hibernate/test/annotations/entity/package-info.java @TypeDefs( @@ -3863,4 +3938,4 @@ public interface Cuisine { } - \ No newline at end of file +