Hibernate SVN: r14428 - annotations/trunk/doc/reference/en/modules and 2 other directories.
by hibernate-commits＠lists.jboss.org
Author: epbernard
Date: 2008-03-14 13:30:00 -0400 (Fri, 14 Mar 2008)
New Revision: 14428
Modified:
annotations/trunk/doc/reference/en/master.xml
annotations/trunk/doc/reference/en/modules/additionalmodules.xml
annotations/trunk/doc/reference/en/modules/entity.xml
entitymanager/trunk/doc/reference/en/master.xml
entitymanager/trunk/doc/reference/en/modules/configuration.xml
entitymanager/trunk/doc/reference/en/modules/entitymanagerapi.xml
Log:
Add documentation before the release
Modified: annotations/trunk/doc/reference/en/master.xml
===================================================================
--- annotations/trunk/doc/reference/en/master.xml 2008-03-14 16:27:21 UTC (rev 14427)
+++ annotations/trunk/doc/reference/en/master.xml 2008-03-14 17:30:00 UTC (rev 14428)
@@ -12,7 +12,7 @@
<subtitle>Reference Guide</subtitle>
- <releaseinfo>3.3.0.GA</releaseinfo>
+ <releaseinfo>3.3.1.GA</releaseinfo>
<mediaobject>
<imageobject>
Modified: annotations/trunk/doc/reference/en/modules/additionalmodules.xml
===================================================================
--- annotations/trunk/doc/reference/en/modules/additionalmodules.xml 2008-03-14 16:27:21 UTC (rev 14427)
+++ annotations/trunk/doc/reference/en/modules/additionalmodules.xml 2008-03-14 17:30:00 UTC (rev 14428)
@@ -73,12 +73,12 @@
<para>To disable constraint propagation to DDL, set up
<literal>hibernate.validator.apply_to_ddl</literal> to false in the
configuration file. Such a need is very uncommon and not
- recommanded.</para>
+ recommended.</para>
<para>To disable pre-entity change validation, set up
<literal>hibernate.validator.autoregister_listeners</literal> to false
in the configuration file. Such a need is very uncommon and not
- recommanded.</para>
+ recommended.</para>
<para>Check the Hibernate Validator reference documentation for more
information.</para>
@@ -89,7 +89,7 @@
<title>Hibernate Search</title>
<section>
- <title>Decription</title>
+ <title>Description</title>
<para>Full text search engines like <productname>Apache
Lucene</productname> are a very powerful technology to bring free
@@ -108,10 +108,10 @@
<para>Hibernate Search integrates with Hibernate Annotations
transparently provided that hibernate-search.jar is present in the
- classpath. If you do not wish to autoregister Hibernate Search event
- listeners, you can set
+ classpath. If you do not wish to automatically register Hibernate Search
+ event listeners, you can set
<literal>hibernate.search.autoregister_listeners</literal> to false.
- Such a need is very uncommon and not recommanded.</para>
+ Such a need is very uncommon and not recommended.</para>
<para>Check the Hibernate Search reference documentation for more
information.</para>
Modified: annotations/trunk/doc/reference/en/modules/entity.xml
===================================================================
--- annotations/trunk/doc/reference/en/modules/entity.xml 2008-03-14 16:27:21 UTC (rev 14427)
+++ annotations/trunk/doc/reference/en/modules/entity.xml 2008-03-14 17:30:00 UTC (rev 14428)
@@ -2398,12 +2398,18 @@
<sect2 id="entity-hibspec-identifier" label="Identifier" revision="2">
<title>Identifier</title>
- <para><literal><literal>@org.hibernate.annotations.GenericGenerator</literal>
- and <literal>@org.hibernate.annotations.GenericGenerators</literal>
- allows you to define an Hibernate specific id
- generator.</literal></para>
+ <para>Hibernate Annotations goes beyond the Java Persistence
+ specification when defining identifiers.</para>
- <para><programlisting>@Id @GeneratedValue(generator="system-uuid")
+ <sect3>
+ <title>Generators</title>
+
+ <para><literal><literal>@org.hibernate.annotations.GenericGenerator</literal>
+ and <literal>@org.hibernate.annotations.GenericGenerators</literal>
+ allows you to define an Hibernate specific id
+ generator.</literal></para>
+
+ <para><programlisting>@Id @GeneratedValue(generator="system-uuid")
@GenericGenerator(name="system-uuid", strategy = "uuid")
public String getId() {
@@ -2416,19 +2422,19 @@
)
public Integer getId() {</programlisting></para>
- <para><literal>strategy</literal> is the short name of an Hibernate3
- generator strategy or the fully qualified class name of an
- <classname>IdentifierGenerator</classname> implementation. You can add
- some parameters through the <literal>parameters</literal>
- attribute.</para>
+ <para><literal>strategy</literal> is the short name of an Hibernate3
+ generator strategy or the fully qualified class name of an
+ <classname>IdentifierGenerator</classname> implementation. You can add
+ some parameters through the <literal>parameters</literal>
+ attribute.</para>
- <para>Contrary to their standard counterpart,
- <literal>@GenericGenerator</literal> and
- <literal>@GenericGenerators</literal> can be used in package level
- annotations, making them application level generators (just like if they
- were in a JPA XML file).</para>
+ <para>Contrary to their standard counterpart,
+ <literal>@GenericGenerator</literal> and
+ <literal>@GenericGenerators</literal> can be used in package level
+ annotations, making them application level generators (just like if
+ they were in a JPA XML file).</para>
- <programlisting>@GenericGenerators(
+ <programlisting>@GenericGenerators(
{
@GenericGenerator(
name="hibseq",
@@ -2442,6 +2448,48 @@
}
)
package org.hibernate.test.model</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>@NaturalId</title>
+
+ <para>While not used as identifier property, some (group of)
+ properties represent natural identifier of an entity. This is
+ especially true when the schema uses the recommended approach of using
+ surrogate primary key even if a natural business key exists. Hibernate
+ allows to map such natural properties and reuse them in a
+ <classname>Criteria</classname> query. The natural identifier is
+ composed of all the properties marked
+ <classname>@NaturalId</classname>.</para>
+
+ <programlisting>@Entity
+public class Citizen {
+ @Id
+ @GeneratedValue
+ private Integer id;
+ private String firstname;
+ private String lastname;
+
+ @NaturalId
+ @ManyToOne
+ private State state;
+
+ @NaturalId
+ private String ssn;
+ ...
+}
+
+
+
+//and later on query
+List results = s.createCriteria( Citizen.class )
+ .add( Restrictions.naturalId().set( "ssn", "1234" ).set( "state", ste ) )
+ .list();</programlisting>
+
+ <para>Note that the group of properties representing the natural
+ identifier have to be unique (Hibernate will generate a unique
+ constraint if the database schema is generated).</para>
+ </sect3>
</sect2>
<sect2 id="entity-hibspec-property" revision="2">
@@ -2913,6 +2961,63 @@
</tgroup>
</table>
</sect3>
+
+ <sect3 id="entity-hibspec-singleassoc-any">
+ <title>@Any</title>
+
+ <para>The <classname>@Any</classname> annotation defines a polymorphic
+ association to classes from multiple tables. This type of mapping
+ always requires more than one column. The first column holds the type
+ of the associated entity. The remaining columns hold the identifier.
+ It is impossible to specify a foreign key constraint for this kind of
+ association, so this is most certainly not meant as the usual way of
+ mapping (polymorphic) associations. You should use this only in very
+ special cases (eg. audit logs, user session data, etc).</para>
+
+ <para>The @Any 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.</para>
+
+ <programlisting> @Any( metaColumn = @Column( name = "property_type" ), fetch=FetchType.EAGER )
+ @AnyMetaDef(
+ idType = "integer",
+ metaType = "string",
+ metaValues = {
+ @MetaValue( value = "S", targetEntity = StringProperty.class ),
+ @MetaValue( value = "I", targetEntity = IntegerProperty.class )
+ } )
+ @JoinColumn( name = "property_id" )
+ public Property getMainProperty() {
+ return mainProperty;
+ }</programlisting>
+
+ <para><methodname>idType</methodname> represents the target entities
+ identifier property type and <methodname>metaType</methodname> the
+ metadata type (usually String).</para>
+
+ <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>//on a package
+@AnyMetaDef( name="property"
+ idType = "integer",
+ metaType = "string",
+ metaValues = {
+ @MetaValue( value = "S", targetEntity = StringProperty.class ),
+ @MetaValue( value = "I", targetEntity = IntegerProperty.class )
+ } )
+package org.hibernate.test.annotations.any;
+
+
+//in a class
+ @Any( metaDef="property", metaColumn = @Column( name = "property_type" ), fetch=FetchType.EAGER )
+ @JoinColumn( name = "property_id" )
+ public Property getMainProperty() {
+ return mainProperty;
+ }</programlisting>
+ </sect3>
</sect2>
<sect2 id="entity-hibspec-collection" revision="2">
@@ -3285,6 +3390,38 @@
is going to be unsupported in future releases</para>
</note>
</sect4>
+
+ <sect4>
+ <title>@ManyToAny</title>
+
+ <para><classname>@ManyToAny</classname> allows polymorphic
+ associations to classes from multiple tables. This type of mapping
+ always requires more than one column. The first column holds the
+ type of the associated entity. The remaining columns hold the
+ identifier. It is impossible to specify a foreign key constraint for
+ this kind of association, so this is most certainly not meant as the
+ usual way of mapping (polymorphic) associations. You should use this
+ only in very special cases (eg. audit logs, user session data,
+ etc).</para>
+
+ <programlisting> @ManyToAny(
+ metaColumn = @Column( name = "property_type" ) )
+ @AnyMetaDef(
+ idType = "integer",
+ metaType = "string",
+ metaValues = {
+ @MetaValue( value = "S", targetEntity = StringProperty.class ),
+ @MetaValue( value = "I", targetEntity = IntegerProperty.class ) } )
+ @Cascade( { org.hibernate.annotations.CascadeType.ALL } )
+ @JoinTable( name = "obj_properties", joinColumns = @JoinColumn( name = "obj_id" ),
+ inverseJoinColumns = @JoinColumn( name = "property_id" ) )
+ public List<Property> getGeneralProperties() {</programlisting>
+
+ <para>Like <classname>@Any</classname>,
+ <classname>@ManyToAny</classname> can use named
+ <classname>@AnyDef</classname>s, see <xref
+ linkend="entity-hibspec-singleassoc-any" /> for more info.</para>
+ </sect4>
</sect3>
</sect2>
Modified: entitymanager/trunk/doc/reference/en/master.xml
===================================================================
--- entitymanager/trunk/doc/reference/en/master.xml 2008-03-14 16:27:21 UTC (rev 14427)
+++ entitymanager/trunk/doc/reference/en/master.xml 2008-03-14 17:30:00 UTC (rev 14428)
@@ -16,7 +16,7 @@
<subtitle>User guide</subtitle>
- <releaseinfo>3.3.1.GA</releaseinfo>
+ <releaseinfo>3.3.2.GA</releaseinfo>
<mediaobject>
<imageobject>
Modified: entitymanager/trunk/doc/reference/en/modules/configuration.xml
===================================================================
--- entitymanager/trunk/doc/reference/en/modules/configuration.xml 2008-03-14 16:27:21 UTC (rev 14427)
+++ entitymanager/trunk/doc/reference/en/modules/configuration.xml 2008-03-14 17:30:00 UTC (rev 14428)
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
<chapter id="configuration">
<title id="setup">Setup and configuration</title>
@@ -7,11 +7,12 @@
<para>The EJB 3.0 / JPA compatible Hibernate EntityManager is built on top
of Hibernate core and Hibernate Annotations. You have to use compatible
- versions of each module. This version is known to work on Hibernate Core
- 3.2.0.GA uo to 3.2.2.GA and Hibernate Annotations 3.3.0.GA.
- The following libraries have to be in your classpath: hibernate3.jar,
- hibernate-annotations.jar, hibernate-commons-annotations.jar, hibernate-entitymanager.jar
- and all needed third party libraries for each package.(incl. ejb-persistence.jar).</para>
+ versions of each module. Please consult the compatibility matrix in the
+ hibernate.org download section. The following libraries have to be in your
+ classpath: hibernate3.jar, hibernate-annotations.jar,
+ hibernate-commons-annotations.jar, hibernate-entitymanager.jar and all
+ needed third party libraries for each package (incl.
+ ejb-persistence.jar).</para>
</section>
<section id="setup-configuration"
@@ -69,9 +70,7 @@
<variablelist spacing="compact">
<varlistentry>
- <term>
- <code>name</code>
- </term>
+ <term><code>name</code></term>
<listitem>
<para>(attribute) Every entity manager must have a name.</para>
@@ -79,9 +78,7 @@
</varlistentry>
<varlistentry>
- <term>
- <code>transaction-type</code>
- </term>
+ <term><code>transaction-type</code></term>
<listitem>
<para>(attribute) Transaction type used. Either JTA or
@@ -93,9 +90,7 @@
</varlistentry>
<varlistentry>
- <term>
- <code>provider</code>
- </term>
+ <term><code>provider</code></term>
<listitem>
<para>The provider is a fully-qualified class name of the EJB
@@ -119,9 +114,7 @@
</varlistentry>
<varlistentry>
- <term>
- <code>mapping-file</code>
- </term>
+ <term><code>mapping-file</code></term>
<listitem>
<para>The class element specifies a EJB3 compliant XML mapping
@@ -136,9 +129,7 @@
</varlistentry>
<varlistentry>
- <term>
- <code>jar-file</code>
- </term>
+ <term><code>jar-file</code></term>
<listitem>
<para>The jar-file elements specifies a jar to analyse. All
@@ -156,9 +147,7 @@
</varlistentry>
<varlistentry>
- <term>
- <code>exclude-unlisted-classes</code>
- </term>
+ <term><code>exclude-unlisted-classes</code></term>
<listitem>
<para>Do not check the main jar file for annotated classes. Only
@@ -167,9 +156,7 @@
</varlistentry>
<varlistentry>
- <term>
- <code>class</code>
- </term>
+ <term><code>class</code></term>
<listitem>
<para>The class element specifies a fully qualified class name
@@ -187,9 +174,7 @@
</varlistentry>
<varlistentry>
- <term>
- <code>properties</code>
- </term>
+ <term><code>properties</code></term>
<listitem>
<para>The properties element is used to specify vendor specific
@@ -337,12 +322,27 @@
<row>
<entry>hibernate.ejb.interceptor</entry>
- <entry>An optional Hibernate interceptor. This interceptor has
- to implement <classname>org.hibernate.Interceptor</classname>
- and have a no-arg constructor.</entry>
+ <entry>An optional Hibernate interceptor. The interceptor
+ instance is shared by all <classname>Session</classname>
+ instances. This interceptor has to implement
+ <classname>org.hibernate.Interceptor</classname> and have a
+ no-arg constructor. This property can not be combined with
+ <literal>hibernate.ejb.interceptor.session_scoped</literal>.</entry>
</row>
<row>
+ <entry>hibernate.ejb.interceptor.session_scoped</entry>
+
+ <entry>An optional Hibernate interceptor. The interceptor
+ instance is specific to a given <classname>Session</classname>
+ instance (and hence can be non thread-safe). This interceptor
+ has to implement
+ <classname>org.hibernate.Interceptor</classname> and have a
+ no-arg constructor. This property can not be combined with
+ <literal>hibernate.ejb.interceptor</literal>.</entry>
+ </row>
+
+ <row>
<entry>hibernate.ejb.naming_strategy</entry>
<entry>An optional naming strategy. The default naming strategy
Modified: entitymanager/trunk/doc/reference/en/modules/entitymanagerapi.xml
===================================================================
--- entitymanager/trunk/doc/reference/en/modules/entitymanagerapi.xml 2008-03-14 16:27:21 UTC (rev 14427)
+++ entitymanager/trunk/doc/reference/en/modules/entitymanagerapi.xml 2008-03-14 17:30:00 UTC (rev 14428)
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
<chapter id="objectstate">
<title>Working with objects</title>
@@ -382,8 +382,10 @@
</tgroup>
</table>
- <para>Please refer to the Hibernate reference documentation for more
- information.</para>
+ <para>The value object accept both the native type or its string
+ equivalent (eg. <literal>CaheMode.REFRESH</literal> or
+ <quote><literal>REFRESH</literal></quote>). Please refer to the
+ Hibernate reference documentation for more information.</para>
</section>
</section>
</section>
