From hibernate-commits at lists.jboss.org Wed May 26 12:18:28 2010
Content-Type: multipart/mixed; boundary="===============4165705447726162003=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r19615 -
 core/trunk/documentation/manual/src/main/docbook/en-US/content.
Date: Wed, 26 May 2010 12:18:28 -0400
Message-ID: <201005261618.o4QGISwj022430@svn01.web.mwc.hst.phx2.redhat.com>

--===============4165705447726162003==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: epbernard
Date: 2010-05-26 12:18:28 -0400 (Wed, 26 May 2010)
New Revision: 19615

Modified:
   core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_map=
ping.xml
Log:
HHH-5149 Merge @Any documentation

Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/ba=
sic_mapping.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma=
pping.xml	2010-05-26 16:17:33 UTC (rev 19614)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma=
pping.xml	2010-05-26 16:18:28 UTC (rev 19615)
@@ -4747,21 +4747,62 @@
       <title>Any</title>
 =

       <para>There is one more type of property mapping. The
-      <literal>&lt;any&gt;</literal> mapping element defines a polymorphic
-      association to classes from multiple tables. This type of mapping
-      requires more than one column. The first column contains the type of=
 the
-      associated entity. The remaining columns contain the identifier. It =
is
-      impossible to specify a foreign key constraint for this kind of
-      association. This is not the usual way of mapping polymorphic
-      associations and you should use this only in special cases. For exam=
ple,
-      for audit logs, user session data, etc.</para>
+      <classname>@Any</classname> mapping defines a polymorphic associatio=
n to
+      classes from multiple tables. This type of mapping requires more than
+      one column. The first column contains the type of the associated ent=
ity.
+      The remaining columns contain the identifier. It is impossible to
+      specify a foreign key constraint for this kind of association. This =
is
+      not the usual way of mapping polymorphic associations and you should=
 use
+      this only in special cases. For example, for audit logs, user session
+      data, etc.</para>
 =

-      <para>The <literal>meta-type</literal> attribute allows the applicat=
ion
-      to specify a custom type that maps database column values to persist=
ent
-      classes that have identifier properties of the type specified by
-      <literal>id-type</literal>. You must specify the mapping from values=
 of
-      the meta-type to class names.</para>
+      <para>The <classname>@Any</classname> annotation describes the column
+      holding the metadata information. To link the value of the metadata
+      information and an actual entity type, The
+      <classname>@AnyDef</classname> and <classname>@AnyDefs</classname>
+      annotations are used. The <literal>metaType</literal> attribute allo=
ws
+      the application to specify a custom type that maps database column
+      values to persistent classes that have identifier properties of the =
type
+      specified by <literal>idType</literal>. You must specify the mapping
+      from values of the <literal>metaType</literal> to class names.</para>
 =

+      <programlisting language=3D"JAVA" role=3D"JAVA">@Any( metaColumn =3D=
 @Column( name =3D "property_type" ), fetch=3DFetchType.EAGER )
+(a)AnyMetaDef( =

+    idType =3D "integer", =

+    metaType =3D "string", =

+    metaValues =3D {
+        @MetaValue( value =3D "S", targetEntity =3D StringProperty.class ),
+        @MetaValue( value =3D "I", targetEntity =3D IntegerProperty.class )
+    } )
+(a)JoinColumn( name =3D "property_id" )
+public Property getMainProperty() {
+    return mainProperty;
+}</programlisting>
+
+      <para>Note that <classname>@AnyDef</classname> can be mutualized and
+      reused. It is recommended to place it as a package metadata in this
+      case.</para>
+
+      <programlisting language=3D"JAVA" role=3D"JAVA">//on a package
+(a)AnyMetaDef( name=3D"property" =

+    idType =3D "integer", =

+    metaType =3D "string", =

+    metaValues =3D {
+        @MetaValue( value =3D "S", targetEntity =3D StringProperty.class ),
+        @MetaValue( value =3D "I", targetEntity =3D IntegerProperty.class )
+    } )
+package org.hibernate.test.annotations.any;
+
+
+//in a class
+    @Any( metaDef=3D"property", metaColumn =3D @Column( name =3D "property=
_type" ), fetch=3DFetchType.EAGER )
+    @JoinColumn( name =3D "property_id" )
+    public Property getMainProperty() {
+        return mainProperty;
+    }</programlisting>
+
+      <para>The hbm.xml equivalent is:</para>
+
       <programlisting role=3D"XML">&lt;any name=3D"being" id-type=3D"long"=
 meta-type=3D"string"&gt;
     &lt;meta-value value=3D"TBL_ANIMAL" class=3D"Animal"/&gt;
     &lt;meta-value value=3D"TBL_HUMAN" class=3D"Human"/&gt;
@@ -4770,6 +4811,11 @@
     &lt;column name=3D"id"/&gt;
 &lt;/any&gt;</programlisting>
 =

+      <note>
+        <para>You cannot mutualize the metadata in hbm.xml as you can in
+        annotations.</para>
+      </note>
+
       <programlistingco role=3D"XML">
         <areaspec>
           <area coords=3D"2" id=3D"any1" />


--===============4165705447726162003==--