Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-4527 added some doc updates 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@18559 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Hardy Ferentschik 2010-01-14 21:32:33 +00:00
parent f45fceece0
commit d23a4a4fd3
1 changed files with 139 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
annotations/src/main/docbook/en/modules/entity.xml
View File

@ -1,4 +1,4 @@
<?xml version='1.0' encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ Hibernate, Relational Persistence for Idiomatic Java
~ ~
@ -22,8 +22,8 @@
~ 51 Franklin Street, Fifth Floor ~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA ~ Boston, MA 02110-1301 USA
--> -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="entity"> <chapter id="entity">
<title>Entity Beans</title> <title>Entity Beans</title>
@ -463,10 +463,10 @@ public class Country implements Serializable {
} }
</programlisting> </programlisting>
<para>A embeddable object inherit the access type of its owning entity <para>An embeddable object inherits the access type of its owning
(note that you can override that using the Hibernate specific entity (note that you can override that using
<literal>@AccessType</literal> annotations (see <xref <literal>@Access</literal> or the Hibernate specific
linkend="entity-hibspec" />).</para> <literal>@AccessType</literal> annotation.</para>
<para>The <literal>Person</literal> entity bean has two component <para>The <literal>Person</literal> entity bean has two component
properties, <literal>homeAddress</literal> and properties, <literal>homeAddress</literal> and
@ -939,8 +939,8 @@ public class BaseEntity {
</note> </note>
<note> <note>
<para>The access type (field or methods), is inherited from the root <para>The default access type (field or methods) is used, unless you
entity, unless you use the Hibernate annotation use the <literal>@Access</literal> or
<literal>@AccessType</literal></para> <literal>@AccessType</literal></para>
</note> </note>
@ -1799,14 +1799,14 @@ public class RegionalArticlePk implements Serializable { ... }
</programlisting> </programlisting>
<para><literal>@Embeddable</literal> inherit the access type of its <para><literal>@Embeddable</literal> inherit the access type of its
owning entity unless the Hibernate specific annotation owning entity unless <literal>@Access</literal> or the Hibernate
<literal>@AccessType</literal> is used. Composite foreign keys (if not specific annotation <literal>@AccessType</literal> is used. Composite
using the default sensitive values) are defined on associations using foreign keys (if not using the default sensitive values) are defined on
the <literal>@JoinColumns</literal> element, which is basically an array associations using the <literal>@JoinColumns</literal> element, which is
of <literal>@JoinColumn</literal>. It is considered a good practice to basically an array of <literal>@JoinColumn</literal>. It is considered a
express <literal>referencedColumnNames</literal> explicitly. Otherwise, good practice to express <literal>referencedColumnNames</literal>
Hibernate will suppose that you use the same order of columns as in the explicitly. Otherwise, Hibernate will suppose that you use the same
primary key declaration.</para> order of columns as in the primary key declaration.</para>
<programlisting> <programlisting>
@Entity @Entity
@ -2528,26 +2528,20 @@ List results = s.createCriteria( Citizen.class )
<sect3> <sect3>
<title>Access type</title> <title>Access type</title>
<para>The access type is guessed from the position of <para>The default access type is determined from the position of the
<literal>@Id</literal> or <literal>@EmbeddedId</literal> in the entity <literal>@Id</literal> or <literal>@EmbeddedId</literal> annotation in
hierarchy. Sub-entities, embedded objects and mapped superclass the entity hierarchy. </para>
inherit the access type from the root entity.</para>
<para>In Hibernate, you can override the access type to:</para> <note>
<para>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.</para>
</note>
<itemizedlist> <para>To finetune the access strategy JPA 2 introduces the @Access
<listitem> annotation. With its help you can define the access type on:</para>
<para>use a custom access type strategy</para>
</listitem>
<listitem>
<para>fine tune the access type at the class level or at the
property level</para>
</listitem>
</itemizedlist>
<para>An @AccessType annotation has been introduced to support this
behavior. You can define the access type on</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -2567,28 +2561,96 @@ List results = s.createCriteria( Citizen.class )
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>The access type is overriden for the annotated element, if <para>Prior to JPA 2 Hibernate used the Hibernate specific annotation
overriden on a class, all the properties of the given class inherit <literal>@org.hibernate.annotations.AccessType</literal> to change
the access type. For root entities, the access type is considered to specific access types. @AccessType still exists to support legacy
be the default one for the whole hierarchy (overridable at class or systems, but the usage of @Access is recommended for new applications.
property level).</para> The behaviour of @Access and @AccessType are similar, but there are
differences. For both annotations applies:</para>
<para>If the access type is marked as "property", the getters are <itemizedlist>
scanned for annotations, if the access type is marked as "field", the <listitem>
fields are scanned for annotations. Otherwise the elements marked with <para>The access type is overriden for the annotated element, if
@Id or @embeddedId are scanned.</para> overriden on a class, all the properties of the given class
inherit the access type. </para>
</listitem>
<para>You can override an access type for a property, but the element <listitem>
to annotate will not be influenced: for example an entity having <para>If an entity is marked as
access type <literal>field</literal>, can annotate a field with <literal>@Access(AccessType.PROPERTY)</literal> or
<literal>@AccessType("property")</literal>, the access type will then <literal>@AccessType("property")</literal> respectively, the
be property for this attribute, the the annotations still have to be getters are scanned for annotations, if the enitiy is marked as
carried on the field.</para> <literal>@Access(AccessType.FIELD)</literal> or
<literal>@AccessType("field")</literal> respectively, the fields
are scanned for annotations. </para>
</listitem>
</itemizedlist>
<para>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:</para>
<programlisting><emphasis role="bold">@AccessType("property")</emphasis> // 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")
<emphasis role="bold">@AccessType("field")</emphasis> // set the access type for name to field
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
</programlisting>
<programlisting><emphasis role="bold">@Access(AccessType.PROPERTY)</emphasis> // set access type for all properties in Country
public class Country implements Serializable {
private String iso2;
<emphasis role="bold">@Access(AccessType.FIELD)</emphasis> // 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;
}
}
</programlisting>
<note>
<para>Watch out for the different annotation placement strategy. In
the case of <literal>@Access</literal> the field has to be annotated
with the overriding access strategy whereas with
<literal>@AccessType</literal> the property gets annotated.</para>
</note>
<para>If a superclass or an embeddable object is not annotated, the <para>If a superclass or an embeddable object is not annotated, the
root entity access type is used (even if an access type has been default entity access type is used.</para>
define on an intermediate superclass or embeddable object). The
russian doll principle does not apply.</para>
<programlisting>@Entity <programlisting>@Entity
public class Person implements Serializable { public class Person implements Serializable {
@ -2655,14 +2717,28 @@ public long getObjectVolume()</programlisting>
<para><literal>@org.hibernate.annotations.TypeDef</literal> and <para><literal>@org.hibernate.annotations.TypeDef</literal> and
<literal>@org.hibernate.annotations.TypeDefs</literal> allows you to <literal>@org.hibernate.annotations.TypeDefs</literal> allows you to
declare type definitions. These annotations can be placed at the class or declare type definitions. These annotations can be placed at the class
package level. Note that these definitions are global for the 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 <literal>PhoneNumer</literal>, it delegates the persistence strategy to the custom mapping type <literal>PhoneNumberType</literal>. However, properties belonging to other classes, too, can delegate their persistence strategy to <literal>PhoneNumberType</literal>, by explicitly using the <literal>@Type</literal> annotation. </para> 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 <literal>PhoneNumer</literal>, it delegates the
persistence strategy to the custom mapping type
<literal>PhoneNumberType</literal>. However, properties belonging to
other classes, too, can delegate their persistence strategy to
<literal>PhoneNumberType</literal>, by explicitly using the
<literal>@Type</literal> annotation.</para>
<note>Package level annotations are placed in a file named <filename>package-info.java</filename> <note>
in the appropriate package. Place your annotations before the package declaration.</note> Package level annotations are placed in a file named
<programlisting> <filename>package-info.java</filename>
in the appropriate package. Place your annotations before the package declaration.
</note>
<programlisting>
@TypeDef( @TypeDef(
name = "phoneNumber", name = "phoneNumber",
defaultForType = PhoneNumber.class, defaultForType = PhoneNumber.class,
@ -2681,10 +2757,9 @@ public class ContactDetails {
</programlisting> </programlisting>
<para> <para>The following example shows the usage of the
The following example shows the usage of the <literal>parameters</literal> attribute to customize the TypeDef. <literal>parameters</literal> attribute to customize the
</para> TypeDef.</para>
<programlisting>//in org/hibernate/test/annotations/entity/package-info.java <programlisting>//in org/hibernate/test/annotations/entity/package-info.java
@TypeDefs( @TypeDefs(
@ -3863,4 +3938,4 @@ public interface Cuisine {
}</programlisting> }</programlisting>
</sect2> </sect2>
</sect1> </sect1>
</chapter> </chapter>