[hibernate-commits] Hibernate SVN: r14428 - annotations/trunk/doc/reference/en/modules and 2 other directories.

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&gt;&lt;literal&gt;&lt;literal&gt;(a)org.hibernate.annotations.GenericGenerator&lt;/literal&gt; - and <literal&gt;(a)org.hibernate.annotations.GenericGenerators&lt;/literal&gt; - 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&gt;&lt;literal&gt;&lt;literal&gt;(a)org.hibernate.annotations.GenericGenerator&lt;/literal&gt; + and <literal&gt;(a)org.hibernate.annotations.GenericGenerators&lt;/literal&gt; + 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&gt;(a)NaturalId&lt;/classname&gt;.&lt;/para&gt; + + <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&lt;Property&gt; 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>