[hibernate-commits] Hibernate SVN: r10485 - in trunk/HibernateExt: ejb ejb/doc/reference/en ejb/doc/reference/en/modules ejb/lib metadata metadata/doc/reference/en metadata/doc/reference/en/modules metadata/lib

Author: epbernard Date: 2006-09-16 16:50:39 -0400 (Sat, 16 Sep 2006) New Revision: 10485 Modified: trunk/HibernateExt/ejb/changelog.txt trunk/HibernateExt/ejb/doc/reference/en/master.xml trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml trunk/HibernateExt/ejb/doc/reference/en/modules/listeners.xml trunk/HibernateExt/ejb/lib/hibernate-annotations.jar trunk/HibernateExt/ejb/readme.txt trunk/HibernateExt/metadata/changelog.txt trunk/HibernateExt/metadata/doc/reference/en/master.xml trunk/HibernateExt/metadata/doc/reference/en/modules/entity.xml trunk/HibernateExt/metadata/doc/reference/en/modules/lucene.xml trunk/HibernateExt/metadata/doc/reference/en/modules/setup.xml trunk/HibernateExt/metadata/doc/reference/en/modules/validator.xml trunk/HibernateExt/metadata/doc/reference/en/modules/xml-overriding.xml trunk/HibernateExt/metadata/lib/README.txt trunk/HibernateExt/metadata/readme.txt Log: Documentation and release preparation Modified: trunk/HibernateExt/ejb/changelog.txt =================================================================== --- trunk/HibernateExt/ejb/changelog.txt 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/ejb/changelog.txt 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,6 +1,51 @@ Hibernate EntityManager Changelog ================================== +3.2.0.CR2 (16-09-2006) +---------------------- +** Bug + * [EJB-98] - EntityManager.find() throws an org.hibernate.ObjectDeletedException if you find something deleted in the same TXA + * [EJB-148] - Incorrect exception when @CollectionOfElement is used with @Where and FetchType is EAGER + * [EJB-174] - Ejb3Configuration can't open EJB Jar file with persistence.xml in Oracle OC4J server (Jifeng Liu) + * [EJB-181] - ExplodedJarVisitor and paths with white spaces + * [EJB-185] - Some EJB3 exceptions does not support nested exceptions + * [EJB-187] - RuntimeException raised in CallBack methods should be left as is + * [EJB-188] - @PostUpdate can be called even if @PreUpdate is not when object is in DELETED state + * [EJB-189] - em.getReference() should raise IllegalArgumentException if the id is of the wrong type + * [EJB-190] - Query.setParameter() should raise an IllegalArgumentException if the parameter does not exist + * [EJB-191] - Incoherent usage of getResultList(), executeUpdate() or getSingleResult() regarding the DML/Select style should raise an IllegalStateException + * [EJB-194] - Removing a detached instance is not allowed + * [EJB-195] - Wrong query should raise an IllegalArgumentException + * [EJB-196] - referencing a transient instance while flushing an association non cascaded should raise IllegalStateException + * [EJB-198] - On em.close(), tries to register the transaction even if the transaction is marked for rollback + * [EJB-202] - Inaccurate exception message for setFirstResult in QueryImpl + * [EJB-203] - exception when using top-level <access>PROPERTY</access> in orm.xml + * [EJB-204] - ClassCastException when using <mapped-superclass> in orm.xml + * [EJB-205] - refresh() should raise IllegalArgumentException if the entity is not managed + * [EJB-207] - em.lock(..., WRITE) raise NPE on some DBs + * [EJB-212] - excludeUnlistedClasses ignored in SE case + * [EJB-214] - Native Query can not be used with parameter + * [EJB-215] - EntityManager fails during transaction commit after it has been closed + * [EJB-216] - Query.getSingleResult() whose state-field is null raise an EntityNotFoundException rather than returning null + * [EJB-218] - markForRollback() should not swallow the original exception + * [EJB-220] - Entity listener documentation contradicts EJB3 specification + * [EJB-223] - EntityNotFoundDelegate not Serializable + + +** Improvement + * [EJB-82] - Query interface should support parameter lists for positions + * [EJB-182] - Add Websphere proprietary jar protocol + * [EJB-186] - Set the default cache provider to NoCache to prevent PU misuse to raise exceptions + * [EJB-201] - Ejb3Configuration should output a warning if no persistence.xml is found + * [EJB-210] - OptimisticLockStrategy should expose the underlying stale entity + * [EJB-211] - JavaDoc the EJB 3 API + +** New Feature + * [EJB-154] - Allow to create/configure an EJB3Configuration without building a sessionfactory + * [EJB-160] - Push EJB3Configuration and SessionFactory into JNDI + * [EJB-184] - Add EM property for FlushMode + + 3.2.0.CR1 (13-05-2006) ---------------------- ** Bug Modified: trunk/HibernateExt/ejb/doc/reference/en/master.xml =================================================================== --- trunk/HibernateExt/ejb/doc/reference/en/master.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/ejb/doc/reference/en/master.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -16,7 +16,7 @@ <subtitle>User guide</subtitle> - <releaseinfo>3.2.0 CR1</releaseinfo> + <releaseinfo>3.2.0 CR2</releaseinfo> <mediaobject> <imageobject> Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml =================================================================== --- trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -194,8 +194,8 @@ entity managers.</para> <para>In a transaction-scoped container managed entity manager (common - case in a J2EE environment), the JTA transaction propagation is the same - as the persistence context resource propagation. In other words, + case in a Java EE environment), the JTA transaction propagation is the + same as the persistence context resource propagation. In other words, container-managed transaction-scoped entity managers retrieved within a given JTA transaction all share the same persistence context. In Hibernate terms, this means all managers share the same session.</para> @@ -246,21 +246,21 @@ </section> </section> - <section> - <title>J2SE environments</title> + <section id="architecture-javase" revision="1"> + <title>Java SE environments</title> - <para>In a J2SE environment only extented context application-managed + <para>In a Java SE environment only extented context application-managed entity managers are available. You can retrieve an entity manger using the <literal>EntityManagerFactory</literal> API. Only resource-local entity managers are available. In other words, JTA transactions and persistence - context propagation are not supported in J2SE (you will have to propagate - the persistence context yourself, e.g. using the thread local session - pattern popular in the Hibernate community).</para> + context propagation are not supported in Java SE (you will have to + propagate the persistence context yourself, e.g. using the thread local + session pattern popular in the Hibernate community).</para> <para>Extended context means that a persistence context is created when the entity manager is retrieved (using - <literal>EntityManagerFactory.createEntityManager(EXTENDED)</literal> ) - and closed when the entity manager is closed. Many resource-local - transaction share the same persistence context, in this case.</para> + <literal>EntityManagerFactory.createEntityManager(...)</literal> ) and + closed when the entity manager is closed. Many resource-local transaction + share the same persistence context, in this case.</para> </section> </chapter> \ No newline at end of file Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml =================================================================== --- trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -5,13 +5,14 @@ <section> <title>Setup</title> - <para>The EJB3 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 - 3.2.0.CR2 and Hibernate Annotations 3.2.0.CR1. The following libraries - have to be in your classpath: hibernate3.jar, hibernate-annotations.jar, - hibernate-entity-manager.jar and all needed third party libraries for each - package.(incl. ejb-persistence.jar).</para> + <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.CR4 (and 3.2.0.GA at the time of writing) and Hibernate Annotations + 3.2.0.CR2. The following libraries have to be in your classpath: + hibernate3.jar, hibernate-annotations.jar, hibernate-entitymanager.jar and + all needed third party libraries for each package.(incl. + ejb-persistence.jar).</para> </section> <section id="setup-configuration" @@ -431,7 +432,7 @@ .addClass( NonAnnotatedClass.class ) //add an hbm.xml file using the Hibernate convention .addRerousce( "mypath/MyOtherCLass.hbm.xml ) //add an hbm.xml file .addRerousce( "mypath/orm.xml ) //add an EJB3 deployment descriptor - .createEntityManagerFactory(); //Create the entity manager factory</programlisting> + .buildEntityManagerFactory(); //Create the entity manager factory</programlisting> </section> </section> @@ -577,7 +578,7 @@ </section> <section> - <title>Obtaining an EntityManager in a J2SE environment</title> + <title>Obtaining an EntityManager in a Java SE environment</title> <para>An entity manager factory should be considered as an immutable configuration holder, it is defined to point to a single datasource and to Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/listeners.xml =================================================================== --- trunk/HibernateExt/ejb/doc/reference/en/modules/listeners.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/ejb/doc/reference/en/modules/listeners.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1"?> -<chapter id="lsiteners"> +<chapter id="listeners"> <title>Entity listeners and Callback methods</title> <section> @@ -64,7 +64,7 @@ have two methods being annotated by the same callback annotation whether it is a callback method or an entity listener method. A callback method is a no-arg method with no return type and any arbitrary name. An entity - listener has the signature public <code>void &lt;METHOD&gt;(Object)</code> + listener has the signature <code>void &lt;METHOD&gt;(Object)</code> where Object is of the actual entity type (note that Hibernate Entity Manager relaxed this constraint and allows <literal>Object</literal> of <literal>java.lang.Object</literal> type (allowing sharing of listeners Modified: trunk/HibernateExt/ejb/lib/hibernate-annotations.jar =================================================================== (Binary files differ) Modified: trunk/HibernateExt/ejb/readme.txt =================================================================== --- trunk/HibernateExt/ejb/readme.txt 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/ejb/readme.txt 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,6 +1,6 @@ Hibernate EntityManager ================================================== -Version: 3.2.0.CR2, xx.09.2006 +Version: 3.2.0.CR2, 16.09.2006 THIS RELEASE OF HIBERNATE ENTITYMANAGER REQUIRES HIBERNATE CORE 3.2.0.CR4 AND DOES NOT WORK WITH HIBERNATE 3.1.x OR ANY OLDER VERSION OF HIBERNATE. Modified: trunk/HibernateExt/metadata/changelog.txt =================================================================== --- trunk/HibernateExt/metadata/changelog.txt 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/changelog.txt 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,6 +1,70 @@ Hibernate Annotations Changelog =============================== +3.2.0.CR2 (16-09-2006) +---------------------- +** Bug + * [ANN-181] - Do not fail on unbound attributes marked as @Type + * [ANN-243] - @MapKey doesn't properly refer to column name mapped to property (quoted column) + * [ANN-345] - EJB3NamingStrategy should be Serializable + * [ANN-359] - @MappedSuperclass overriding fails on EJB3 DD + * [ANN-362] - Specification of table @Table name with quotes using backticks fails with @OneToMany mapping + * [ANN-368] - Keywords first letter is not decapilalized + * [ANN-369] - @CollectionOfElements on a Map uses reserved word "key" as column name + * [ANN-370] - Lucene updates are not thread safe + * [ANN-375] - @Email validator failed a valid email address + * [ANN-379] - Map<Entity, Entity> fails due to unique constraint on map-key column + * [ANN-382] - Id involving many to one may fail depending on the entity process ordering + * [ANN-393] - Documentation errors in Many-toMany Annotation explanation + * [ANN-405] - JPA XML overriding wrong when default schema and *-to-one association + * [ANN-409] - Enum constants in HQL leads to ClassCastException + * [ANN-411] - @Generated(INSERT) properties does not update columns + * [ANN-412] - Generator definition (@Table, @Generic, @Sequence) no longer taken into account at field level + * [ANN-414] - Map, OneToMany, join table or @ManyToMany does not work on MySQL and on composite keys + * [ANN-415] - <named-native-query result-class leads to CCE + * [ANN-416] - Mapping of inheritance with several generic superclasses fails + * [ANN-421] - Unable to map no packaged classes when JPA XML is used + * [ANN-423] - @Min/@Max broken with BigInteger/BigDecimal + * [ANN-424] - column overriding fails on composite elements when defined at the entity level + * [ANN-426] - Validator keep a JavaXFactory in a static variable creating memleaks on redeployement + * [ANN-427] - throw "java.lang.IllegalStateException: Property parent has an unbound type and no explicit target entity." on generic type + + +** Improvement + * [ANN-7] - Document usage of @IndexColumn in one-to-many with indexed collection + * [ANN-36] - @ForceDiscriminator (Serg Prasolov) + * [ANN-39] - @CollectionId for idbags + * [ANN-47] - Allow to set an enum parameter on a query + * [ANN-261] - Allow specifying foreign key constraint name using annotations (inspired by David Hay) + * [ANN-265] - Fall back to default validator message if the key is not found + * [ANN-343] - validator messages in brazilian portuguese + * [ANN-350] - Support ejb3 dd when no schema locator is defined + * [ANN-351] - Validator Brazilian translation + * [ANN-355] - Make XML overriding rules for access type smoother + * [ANN-356] - Clear the PC on Rollback on RESOURCE_LOCAL Transactions + * [ANN-371] - Abstract DocumentBuilder from the underlying Directory implementation + * [ANN-373] - imports are not done for the full entityname + * [ANN-374] - Map - OneToMany w or w/o join table creates bad sql + * [ANN-381] - Make possible to specify an @EmbeddedId's field in a @OneToMany's mappedBy property + * [ANN-397] - Incomplete AnnotationException at org.hibernate.cfg.annotations.TableBinder + * [ANN-399] - Class validator should not WARN on unbound properties not involved in validation + +** New Feature + * [ANN-284] - @OrderBy clash with @Formula Properties + * [ANN-349] - Add @FlushModeType.MANUAL + * [ANN-367] - Upgrade to Lucene 2.0.0 (Sylvain Vieujot) + * [ANN-372] - @Boost factor on document and fields + * [ANN-378] - Chinese translation (Xiaogang Cao) + * [ANN-385] - Abstract the Lucene directory implementation and allow configuration based definition + * [ANN-386] - Add support for RAMDirectory + * [ANN-419] - Support SortedMap + * [ANN-440] - MessageIntrospector hook introduced in HibernateValidator + + +** Task + * [ANN-410] - Depreciate EJB 3 Package annotations + + 3.2.0.CR1 (13-05-2006) ---------------------- ** Bug Modified: trunk/HibernateExt/metadata/doc/reference/en/master.xml =================================================================== --- trunk/HibernateExt/metadata/doc/reference/en/master.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/doc/reference/en/master.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -13,7 +13,7 @@ <subtitle>Reference Guide</subtitle> - <releaseinfo>3.2.0 CR1</releaseinfo> + <releaseinfo>3.2.0 CR2</releaseinfo> <mediaobject> <imageobject> @@ -24,7 +24,7 @@ <toc></toc> - <preface> + <preface id="preface" revision="1"> <title>Preface</title> <para>Hibernate, like all other object/relational mapping tools, requires @@ -53,24 +53,24 @@ your project. You can at all times fall back to Hibernate native APIs, or if required, even to native JDBC and SQL.</para> - <para>Please note that this documentation is based on a preview release of - the Hibernate Annotations that follows the public final draft of EJB - 3.0/JSR-220 persistence annotations. This work is already very close to - the final concepts in the new specification. Our goal is to provide a - complete set of ORM annotations, including EJB3 standard annotations as - well as Hibernate3 extensions for cases not covered by the specification. - Eventually you will be able to create all possible mappings with - annotations. See the JIRA road mapsection for more information.</para> + <para>This release is based on the final release of the EJB 3.0 / JPA + specification (aka JSP-220) and support all the specification features + (including the optional ones). Most of the Hibernate features and + extensions are also available through Hibernate specific annotations + compared to the specification are also available. While the Hibernate + feature coverage is now very high, some are still missing. The eventual + goal is to cover all of them. See the JIRA road map section for more + informations.</para> - <para>The EJB3 Public final draft has change some annotations, please - refer to http://www.hibernate.org/371.html as a migration guide from - previous versions of Hibernate Annotations.</para> + <para>If you are moving from previous Hibernate Annotations versions, + please have a look at <uri>http://www.hibernate.org/371.html</uri> for a + migration guide.</para> </preface> &setup; &entity; - + &xml-overriding; &validator; Modified: trunk/HibernateExt/metadata/doc/reference/en/modules/entity.xml =================================================================== --- trunk/HibernateExt/metadata/doc/reference/en/modules/entity.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/doc/reference/en/modules/entity.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -9,18 +9,18 @@ Hibernate-specific extensions.</para> </sect1> - <sect1 id="mapping" revision="1"> + <sect1 id="entity-mapping" revision="2"> <title>Mapping with EJB3 Annotations</title> <para>EJB3 entity beans are plain POJOs. Actually they represent the exact same concept as the Hibernate persistent entities. Their mappings are defined through JDK 5.0 annotations (an XML descriptor syntax for - overriding will be defined in the EJB3 specification, but it's not - finalized so far). Annotations can be split in two categories, the logical - mapping annotations (allowing you to describe the object model, the class - associations, etc.) and the physical mapping annotations (describing the - physical schema, tables, columns, indexes, etc). We will mix annotations - from both categories in the following code examples.</para> + overriding is defined in the EJB3 specification). Annotations can be split + in two categories, the logical mapping annotations (allowing you to + describe the object model, the class associations, etc.) and the physical + mapping annotations (describing the physical schema, tables, columns, + indexes, etc). We will mix annotations from both categories in the + following code examples.</para> <para>EJB3 annotations are in the <literal>javax.persistence.*</literal> package. Most JDK 5 compliant IDE (like Eclipse, IntelliJ IDEA and @@ -510,7 +510,7 @@ </sect3> </sect2> - <sect2 id="mapping-identifier" label="" + <sect2 id="entity-mapping-identifier" label="" xreflabel="Mapping identifier properties"> <title>Mapping identifier properties</title> @@ -565,10 +565,18 @@ <literal>@TableGenerator</literal>. The scope of a generator can be the application or the class. Class-defined generators are not visible outside the class and can override application level generators. - Application level generators are defined at package level (see - <classname>package-info.java</classname>):</para> + Application level generators are defined at XML level (see <xref + linkend="xml-overriding" />):</para> - <programlisting> + <programlisting>&lt;table-generator name="EMP_GEN" + table="GENERATOR_TABLE" + pk-column-name="key" + value-column-name="hi" + pk-column-value="EMP" + allocation-size="20"/&gt; + +//and the annotation equivalent + @javax.persistence.TableGenerator( name="EMP_GEN", table="GENERATOR_TABLE", @@ -577,16 +585,22 @@ pkColumnValue="EMP", allocationSize=20 ) + +&lt;sequence-generator name="SEQ_GEN" + sequence-name="my_sequence" + allocation-size="20"/&gt; + +//and the annotation equivalent + @javax.persistence.SequenceGenerator( name="SEQ_GEN", - sequenceName="my_sequence" + sequenceName="my_sequence", + allocationSize=20 ) -package org.hibernate.test.metadata; </programlisting> - <para>If <classname>package-info.java</classname> in the - <classname>org.hibernate.test.metadata</classname> package is used to - initialize the EJB configuration, <literal>EMP_GEN</literal> and + <para>If JPA XML (like <filename>META-INF/orm.xml</filename>) is used to + define thegenerators, <literal>EMP_GEN</literal> and <literal>SEQ_GEN</literal> are application level generators. <literal>EMP_GEN</literal> defines a table based id generator using the hilo algorithm with a <literal>max_lo</literal> of 20. The hi value is @@ -597,11 +611,20 @@ "<literal>hi</literal>" contains the the next high value used.</para> <para><literal>SEQ_GEN</literal> defines a sequence generator using a - sequence named <literal>my_sequence</literal>. Note that this version of - Hibernate Annotations does not handle <literal>initialValue</literal> - and <literal>allocationSize</literal> parameters in the sequence - generator.</para> + sequence named <literal>my_sequence</literal>. The allocation size used + for this sequence based hilo algorithm is 20. Note that this version of + Hibernate Annotations does not handle <literal>initialValue</literal> in + the sequence generator. The default allocation size is 50, so if you + want to use a sequence and pickup the value each time, you must set the + allocation size to 1.</para> + <note> + <para>Package level definition is no longer supported by the EJB 3.0 + specification. However, you can use the + <literal>@GenericGenerator</literal> at the package level (see <xref + linkend="entity-hibspec-identifier" />).</para> + </note> + <para>The next example shows the definition of a sequence generator in a class scope:</para> @@ -1178,7 +1201,8 @@ <sect3 id="entity-mapping-association-collections"> <title>Collections</title> - <sect4> + <sect4 id="entity-mapping-association-collections-overview" + revision="1"> <title>Overview</title> <para>You can map <classname>Collection</classname>, @@ -1245,6 +1269,16 @@ </row> <row> + <entry>Bag semantic with primary key (withtout the + limitations of Bag semantic)</entry> + + <entry>java.util.List, java.util.Collection</entry> + + <entry&gt;((a)org.hibernate.annotations.CollectionOfElements or + @OneToMany or @ManyToMany) and @CollectionId</entry> + </row> + + <row> <entry>List semantic</entry> <entry>java.util.List</entry> @@ -1270,8 +1304,8 @@ <entry&gt;((a)org.hibernate.annotations.CollectionOfElements or @OneToMany or @ManyToMany) and (nothing or - @org.hibernate.annotations.MapKey/MapKeyManyToMany for true map support, OR - @javax.persistence.MapKey</entry> + @org.hibernate.annotations.MapKey/MapKeyManyToMany for true + map support, OR @javax.persistence.MapKey</entry> </row> </tbody> </tgroup> @@ -1465,7 +1499,8 @@ (<literal>inversejoinColumns</literal>).</para> </sect5> - <sect5> + <sect5 id="entity-mapping-association-collection-manytomany-default" + revision="1"> <title>Defaults</title> <para>Without describing any physical mapping, a unidirectional @@ -1504,7 +1539,8 @@ </sect5> </sect4> - <sect4> + <sect4 id="eentity-mapping-association-collection-manytomany" + revision=""> <title>Many-to-many</title> <sect5> @@ -1596,7 +1632,7 @@ } </programlisting> - <para>A <literal>Store_Table</literal> is used as the join table. + <para>A <literal>Store_City</literal> is used as the join table. The <literal>Store_id</literal> column is a foreign key to the <literal>Store</literal> table. The <literal>implantedIn_id</literal> column is a foreign key to the @@ -1635,7 +1671,7 @@ table. The <literal>stores_id</literal> column is a foreign key to the <literal>Store</literal> table. The <literal>customers_id</literal> column is a foreign key to the - <literal>City</literal> table.</para> + <literal>Customer</literal> table.</para> </sect5> </sect4> </sect3> @@ -1701,7 +1737,7 @@ class has to be serializable and implements <methodname>equals()</methodname>/<methodname>hashCode()</methodname>. You can also use <literal>@IdClass</literal> as described in <xref - linkend="mapping-identifier" />.</para> + linkend="entity-mapping-identifier" />.</para> <programlisting> @Entity @@ -1849,22 +1885,23 @@ <sect1 id="entity-mapping-query"> <title>Mapping Queries</title> - <sect2> - <title>Mapping EJBQL/HQL queries</title> + <sect2 id="entity-mapping-query-hql" label="Mapping JPAQL/HQL queries" + revision="1"> + <title>Mapping JPAQL/HQL queries</title> <para>You can map EJBQL/HQL queries using annotations. <literal>@NamedQuery</literal> and <literal>@NamedQueries</literal> can - be defined at the class or at the package level. However their + be defined at the class level or in a JPA XML file. However their definitions are global to the session factory/entity manager factory scope. A named query is defined by its name and the actual query string.</para> - <programlisting> -javax.persistence.NamedQueries( - @javax.persistence.NamedQuery(name="plane.getAll", query="select p from Plane p") -) -package org.hibernate.test.annotations.query; - + <programlisting>&lt;entity-mappings&gt; + &lt;named-query name="plane.getAll"&gt; + &lt;query&gt;select p from Plane p&lt;/query&gt; + &lt;/named-query&gt; + ... +&lt;/entity-mappings&gt; ... @Entity @@ -1971,18 +2008,20 @@ <literal>@SqlResultSetMapping</literal> (or <literal>@SqlResultSetMappings</literal> if you plan to define several resulset mappings). Like <literal>@NamedQuery</literal>, a - <literal>@SqlResultSetMapping</literal> can be defined at both package - level or class level. However its scope is global to the application. As - we will see, a <literal>resultSetMapping</literal> parameter is defined - the <literal>@NamedNativeQuery</literal>, it represents the name of a - defined <literal>@SqlResultSetMapping</literal>. The resultset mapping - declares the entities retrieved by this native query. Each field of the - entity is bound to an SQL alias (or column name). All fields of the - entity including the ones of subclasses and the foreign key columns of - related entities have to be present in the SQL query. Field definitions - are optional provided that they map to the same column name as the one - declared on the class property.</para> + <literal>@SqlResultSetMapping</literal> can be defined at class level or + in a JPA XML file. However its scope is global to the + application.</para> + <para>As we will see, a <literal>resultSetMapping</literal> parameter is + defined in <literal>@NamedNativeQuery</literal>, it represents the name + of a defined <literal>@SqlResultSetMapping</literal>. The resultset + mapping declares the entities retrieved by this native query. Each field + of the entity is bound to an SQL alias (or column name). All fields of + the entity including the ones of subclasses and the foreign key columns + of related entities have to be present in the SQL query. Field + definitions are optional provided that they map to the same column name + as the one declared on the class property.</para> + <para><programlisting>@NamedNativeQuery(name="night&amp;area", query="select night.id nid, night.night_duration, " + " night.night_date, area.id aid, night.area_id, area.name " + "from Night night, Area area where night.area_id = area.id", <emphasis @@ -2302,7 +2341,7 @@ public class Carrot extends Vegetable { ... }</programlisting></para> </sect2> - <sect2> + <sect2 id="entity-hibspec-identifier" label="Identifier" revision="1"> <title>Identifier</title> <para&gt;&lt;literal&gt;&lt;literal&gt;(a)org.hibernate.annotations.GenericGenerator&lt;/literal&gt; @@ -2326,7 +2365,20 @@ 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> + attribute.</para> + + <para>Contrary to its standard counterpart, + <literal>@GenericGenerator</literal> can be used in package level + annotations, making it an application level generator (just like if it + were in a JPA XML file).</para> + + <programlisting>@GenericGenerator(name="hibseq", strategy = "seqhilo", + parameters = { + @Parameter(name="max_lo", value = "5"), + @Parameter(name="sequence", value="heybabyhey") + } +) +package org.hibernate.test.model</programlisting> </sect2> <sect2 id="entity-hibspec-property" revision="2"> @@ -2575,7 +2627,7 @@ </sect3> </sect2> - <sect2> + <sect2 id="entity-hibspec-inheritance" revision="1"> <title>Inheritance</title> <para>SINGLE_TABLE is a very powerful strategy but sometimes, and @@ -2590,9 +2642,17 @@ <programlisting>@Entity @DiscriminatorForumla("case when forest_type is null then 0 else forest_type end") public class Forest { ... }</programlisting> + + <para>By default, when querying the top entities, Hibernate does not put + a restriction clause on the discriminator column. This can be + inconvenient if this column contains values not mapped in your hierarchy + (through <literal>@DiscriminatorValue</literal>). To work around that + you can use <literal>@ForceDiscriminator</literal> (at the class level, + next to <literal>@DiscriminatorColumn</literal>). Hibernate will then + list the available values when loading the entities.</para> </sect2> - <sect2> + <sect2 id="entity-hibspec-singleassoc"> <title>Single Association related annotations</title> <para>By default, when Hibernate cannot resolve the association because @@ -2629,6 +2689,21 @@ <para>In this case Hibernate generates a cascade delete constraint at the database level.</para> + <para>Foreign key constraints, while generated by Hibernate, have a + fairly unreadable name. You can override the constraint name by use + <literal&gt;(a)ForeignKey&lt;/literal&gt;.&lt;/para&gt; + + <programlisting>@Entity +public class Child { + ... + @ManyToOne + <emphasis role="bold">@ForeignKey(name="FK_PARENT")</emphasis> + public Parent getParent() { ... } + ... +} + +alter table Child add constraint FK_PARENT foreign key (parent_id) references Parent</programlisting> + <sect3> <title>Lazy options and fetching modes</title> @@ -2733,8 +2808,8 @@ <sect2 id="entity-hibspec-collection" revision="2"> <title>Collection related annotations</title> - <sect3> - <title>Parameter annotations</title> + <sect3 id="entity-hibspec-collection-enhance" revision="1"> + <title>Enhance collection settings</title> <para>It is possible to set <itemizedlist> <listitem> @@ -2763,7 +2838,9 @@ you want between unsorted, natural or custom comparator. If you want to use your own comparator implementation, you'll also have to express the implementation class using the <literal>comparator</literal> - attribute.</para> + attribute. Note that you need to use either a + <classname>SortedSet</classname> or a <classname>SortedMap</classname> + interface.</para> <programlisting> @OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER) @JoinColumn(name="CUST_ID") @@ -2776,63 +2853,187 @@ <para>Please refer to the previous descriptions of these annotations for more informations.</para> + + <para>Foreign key constraints, while generated by Hibernate, have a + fairly unreadable name. You can override the constraint name by use + <literal>@ForeignKey</literal>. Note that this annotation has to be + placed on the owning side of the relationship, + <literal>inverseName</literal> referencing to the other side + constraint.</para> + + <programlisting>@Entity +public class Woman { + ... + @ManyToMany(cascade = {CascadeType.ALL}) + <emphasis role="bold">@ForeignKey(name = "TO_WOMAN_FK", inverseName = "TO_MAN_FK")</emphasis> + public Set&lt;Man&gt; getMens() { + return mens; + } +} + +alter table Man_Woman add constraint TO_WOMAN_FK foreign key (woman_id) references Woman +alter table Man_Woman add constraint TO_MAN_FK foreign key (man_id) references Man</programlisting> </sect3> - <sect3> + <sect3 id="entity-hibspec-collection-extratype" revision="1"> <title>Extra collection types</title> - <para>Beyond EJB3, Hibernate Annotations supports true - <classname>List</classname> and <classname>Array</classname>. Map your - collection the same way as usual and add the - @<literal>IndexColumn</literal>. This annotation allows you to - describe the column that will hold the index. You can also declare the - index value in DB that represent the first element (aka as base - index). The usual value is <literal>0</literal> or - <literal>1</literal>.</para> + <sect4> + <title>List</title> - <programlisting>@OneToMany(cascade = CascadeType.ALL) + <para>Beyond EJB3, Hibernate Annotations supports true + <classname>List</classname> and <classname>Array</classname>. Map + your collection the same way as usual and add the + @<literal>IndexColumn</literal>. This annotation allows you to + describe the column that will hold the index. You can also declare + the index value in DB that represent the first element (aka as base + index). The usual value is <literal>0</literal> or + <literal>1</literal>.</para> + + <programlisting>@OneToMany(cascade = CascadeType.ALL) @IndexColumn(name = "drawer_position", base=1) public List&lt;Drawer&gt; getDrawers() { return drawers; }</programlisting> - <note> - <para>If you forgot to set <literal>@IndexColumn</literal>, the bag - semantic is applied</para> - </note> + <note> + <para>If you forgot to set <literal>@IndexColumn</literal>, the + bag semantic is applied. If you want the bag semantic without the + limitations of it, consider using + <literal&gt;(a)CollectionId&lt;/literal&gt;.&lt;/para&gt; + </note> + </sect4> - <para>Hibernate Annotations also supports true Map mappings, if - <literal&gt;(a)javax.persistence.MapKey&lt;/literal&gt; is not set, hibernate - will map the key element or embeddable object in its/their own - columns. To overrides the default columns, you can use - <literal&gt;(a)org.hibernate.annotations.MapKey&lt;/literal&gt; if your key is a basic type - or an embeddable object, or you canh use - <literal&gt;(a)org.hibernate.annotations.MapKey&lt;/literal&gt; if your key is an entity. - </para> + <sect4> + <title>Map</title> - <para>Hibernate Annotations also supports collections of core types - (Integer, String, Enums, ...), collections of embeddable objects and - even arrays of primitive types. This is known as collection of - elements.</para> + <para>Hibernate Annotations also supports true Map mappings, if + <literal&gt;(a)javax.persistence.MapKey&lt;/literal&gt; is not set, hibernate + will map the key element or embeddable object in its/their own + columns. To overrides the default columns, you can use + <literal&gt;(a)org.hibernate.annotations.MapKey&lt;/literal&gt; if your key is + a basic type (defaulted to <literal>mapkey</literal>) or an + embeddable object, or you can use + <literal&gt;(a)org.hibernate.annotations.MapKeyManyToMany&lt;/literal&gt; if + your key is an entity.</para> + </sect4> - <para>A collection of elements has to be annotated as - <literal>@CollectionOfElements</literal> (as a replacement of - <literal>@OneToMany</literal>) To define the collection table, the - <literal>@JoinTable</literal> annotation is used on the association - property, <literal>joinColumns</literal> defines the join columns - between the entity primary table and the collection table - (inverseJoincolumn is useless and should be left empty). For - collection of core types or array of primitive types, you can override - the element column definition using a <literal>@Column</literal> on - the association property. You can also override the columns of a - collection of embeddable object using - <literal>@AttributeOverride</literal>. To reach the collection - element, you need to append "element" to the attribute override name - (eg "element" for core types, or "element.serial" for the serial - property of an embeddable element). To reach the index/key of a - collection, append "key" instead.</para> + <sect4 id="entity-hibspec-collection-extratype-indexbidir"> + <title>Bidirectional association with indexed collections</title> - <programlisting>@Entity + <para>A bidirectional association where one end is represented as a + <literal>@IndexColumn</literal> or + <literal&gt;(a)org.hibernate.annotations.MapKey[ManyToMany]&lt;/literal&gt; + requires special consideration. If there is a property of the child + class which maps to the index column, no problem, we can continue + using <literal>mappedBy</literal> on the collection mapping:</para> + + <programlisting>@Entity +public class Parent { + @OneToMany(mappedBy="parent") + @org.hibernate.annotations.MapKey(columns=@Column(name="name")) + private Map&lt;String, Child&gt; children; + ... +} + +@Entity +public class Parent { + ... + @Basic + private String name; + + @ManyToOne + @JoinColumn(name="parent_id", nullable=false) + private Parent parent; + ... +}</programlisting> + + <para>But, if there is no such property on the child class, we can't + think of the association as truly bidirectional (there is + information available at one end of the association that is not + available at the other end). In this case, we can't map the + collection <literal>mappedBy</literal>. Instead, we could use the + following mapping:</para> + + <programlisting>@Entity +public class Parent { + @OneToMany + @org.hibernate.annotations.MapKey(columns=@Column(name="name")) + @JoinColumn(name="parent_id", nullable=false) + private Map&lt;String, Child&gt; children; + ... +} + +@Entity +public class Parent { + ... + @ManyToOne + @JoinColumn(name="parent_id", insertable=false, updatable=false, nullable=false) + private Parent parent; + ... +}</programlisting> + + <para>Note that in this mapping, the collection-valued end of the + association is responsible for updates to the foreign key.</para> + </sect4> + + <sect4> + <title>Bag with primary key</title> + + <para>Another interesting feature is the ability to define a + surrogate primary key to a bag collection. This remove pretty much + all of the drawbacks of bags: update and removal are efficient, more + than one <literal>EAGER</literal> bag per query or per entity. This + primary key will be contained in a additional column of your + collection table but will not be visible to the Java application. + @CollectionId is used to mark a collection as id bag, it also allow + to override the primary key column(s), the primary key type and the + generator strategy. The strategy can be <literal>identity</literal>, + or any defined generator name of your application.</para> + + <programlisting>@Entity +@TableGenerator(name="ids_generator", table="IDS") +public class Passport { + ... + + @ManyToMany(cascade = CascadeType.ALL) + @JoinTable(name="PASSPORT_VISASTAMP") + <emphasis role="bold">@CollectionId( + columns = @Column(name="COLLECTION_ID"), + type=@Type(type="long"), + generator = "ids_generator" + )</emphasis> + private Collection&lt;Stamp&gt; visaStamp = new ArrayList(); + ... +}</programlisting> + </sect4> + + <sect4> + <title>Collection of element or composite elements</title> + + <para>Hibernate Annotations also supports collections of core types + (Integer, String, Enums, ...), collections of embeddable objects and + even arrays of primitive types. This is known as collection of + elements.</para> + + <para>A collection of elements has to be annotated as + <literal>@CollectionOfElements</literal> (as a replacement of + <literal>@OneToMany</literal>) To define the collection table, the + <literal>@JoinTable</literal> annotation is used on the association + property, <literal>joinColumns</literal> defines the join columns + between the entity primary table and the collection table + (inverseJoincolumn is useless and should be left empty). For + collection of core types or array of primitive types, you can + override the element column definition using a + <literal>@Column</literal> on the association property. You can also + override the columns of a collection of embeddable object using + <literal>@AttributeOverride</literal>. To reach the collection + element, you need to append "element" to the attribute override name + (eg "element" for core types, or "element.serial" for the serial + property of an embeddable element). To reach the index/key of a + collection, append "key" instead.</para> + + <programlisting>@Entity public class Boy { private Integer id; private Set&lt;String&gt; nickNames = new HashSet&lt;String&gt;(); @@ -2934,19 +3135,20 @@ } }</programlisting> - <para>On a collection of embeddable objects, the embeddable object can - have a proeprty annotated with <literal>@Parent</literal>. This - property will then point back to the entity containing the - collection.</para> + <para>On a collection of embeddable objects, the embeddable object + can have a property annotated with <literal>@Parent</literal>. This + property will then point back to the entity containing the + collection.</para> - <note> - <para>Previous versions of Hibernate Annotations used the - <literal>@OneToMany</literal> to mark a collection of elements. Due - to semantic inconsistencies, we've introduced the annotation - <literal>@CollectionOfElements</literal>. Marking collections of - elements the old way still work but is considered deprecated and is - going to be unsupported in future releases</para> - </note> + <note> + <para>Previous versions of Hibernate Annotations used the + <literal>@OneToMany</literal> to mark a collection of elements. + Due to semantic inconsistencies, we've introduced the annotation + <literal>@CollectionOfElements</literal>. Marking collections of + elements the old way still work but is considered deprecated and + is going to be unsupported in future releases</para> + </note> + </sect4> </sect3> </sect2> @@ -3040,7 +3242,7 @@ public class Forest { ... }</programlisting></para> </sect2> - <sect2> + <sect2 id="entity-hibspec-query"> <title>Queries</title> <para>Since Hibernate has more features on named queries than the one @@ -3095,9 +3297,10 @@ </listitem> </itemizedlist> - <para>Note, that the EJB3 public final draft has introduced the notion - of <literal>@QueryHint</literal>, which is probably a better way to - define those hints.</para> + <para>Those hints can be set in a standard + <literal&gt;(a)javax.persistence.NamedQuery&lt;/literal&gt; annotations through the + detyped <literal>@QueryHint</literal>. Another key advantage is the + ability to set those annotations at a package level.</para> </sect2> </sect1> </chapter> \ No newline at end of file Modified: trunk/HibernateExt/metadata/doc/reference/en/modules/lucene.xml =================================================================== --- trunk/HibernateExt/metadata/doc/reference/en/modules/lucene.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/doc/reference/en/modules/lucene.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="ISO-8859-1"?> -<chapter id="lucene"> - <title id="lucene">Hibernate Lucene Integration</title> +<chapter id="lucene" revision="1"> + <title>Hibernate Lucene Integration</title> <para>Lucene is a high-performance Java search engine library available from the Apache Software Foundation. Hibernate Annotations includes a package of @@ -8,34 +8,35 @@ have Hibernate maintain a Lucene index of any instances persisted via Hibernate.</para> - <sect1 id="lucene-intro"> - <title>Using Lucene to index your entities</title> + <para>Hibernate Lucene is a work in progress and new features are cooking in + this area. So expect some compatibility changes in subsequent + versions.</para> - <sect2> - <title>Annotating your domain model</title> + <section id="lucene-mapping"> + <title>Mapping the entities to the index</title> - <para>First, we must declare a persistent class as - <literal>@Indexed</literal>:</para> + <para>First, we must declare a persistent class as indexable. This is done + by annotating the class with <literal>@Indexed</literal>:</para> - <programlisting>@Entity + <programlisting>@Entity @Indexed(index="indexes/essays") public class Essay { ... }</programlisting> - <para>The <literal>index</literal> attribute tells Hibernate where the - Lucene index is located (a directory on your file system). If you wish - to define a base directory for all lucene indexes, you can use the - <literal>hibernate.lucene.index_dir</literal> property in your - configuration file.</para> + <para>The <literal>index</literal> attribute tells Hibernate what the + lucene directory name is (usually a directory on your file system). If you + wish to define a base directory for all lucene indexes, you can use the + <literal>hibernate.lucene.default.indexDir</literal> property in your + configuration file.</para> - <para>Lucene indexes contain four kinds of fields: - <emphasis>keyword</emphasis> fields, <emphasis>text</emphasis> fields, - <emphasis>unstored</emphasis> fields and <emphasis>unindexed</emphasis> - fields. Hibernate Annotations provides annotations to mark a property of - an entity as one of the first three kinds of indexed fields.</para> + <para>Lucene indexes contain four kinds of fields: + <emphasis>keyword</emphasis> fields, <emphasis>text</emphasis> fields, + <emphasis>unstored</emphasis> fields and <emphasis>unindexed</emphasis> + fields. Hibernate Annotations provides annotations to mark a property of + an entity as one of the first three kinds of indexed fields.</para> - <programlisting>@Entity + <programlisting>@Entity @Indexed(index="indexes/essays") public class Essay { ... @@ -53,22 +54,119 @@ }</programlisting> - <para>These annotations define an index with three fields: - <literal>Id</literal>, <literal>Abstract</literal> and - <literal>Text</literal>.</para> + <para>These annotations define an index with three fields: + <literal>id</literal>, <literal>Abstract</literal> and + <literal>text</literal>. Note that by default the field name is + decapitalized, following the JavaBean specification.</para> - <para>Note: you <emphasis>must</emphasis> specify - <literal>@Keyword(id=true)</literal> on the identifier property of your - entity class.</para> + <para>Note: you <emphasis>must</emphasis> specify + <literal>@Keyword(id=true)</literal> on the identifier property of your + entity class.</para> - <para>The analyzer class used to index the elements is configurable - through the <literal>hibernate.lucene.analyzer</literal> property. If - none defined, - <classname>org.apache.lucene.analysis.standard.StandardAnalyzer</classname> - is used as the default.</para> - </sect2> + <para>Lucene has the notion of <emphasis>boost factor</emphasis>. It's a + way to give more weigth to a field or to an indexed element over an other + during the indexation process. You can use <literal>@Boost</literal> at + the field or the class level.</para> - <sect2> + <para>The analyzer class used to index the elements is configurable + through the <literal>hibernate.lucene.analyzer</literal> property. If none + defined, + <classname>org.apache.lucene.analysis.standard.StandardAnalyzer</classname> + is used as the default.</para> + </section> + + <section id="lucene-configuration"> + <title>Configuration</title> + + <section id="lucene-configuration-directory"> + <title>directory configuration</title> + + <para>Lucene has a notion of Directory where the index is stored. The + Directory implementation can be customized but Lucene comes bundled with + a file system and a full memory implementation. Hibernate Lucene has the + notion of <literal>DirectoryProvider</literal> that handle the + configuration and the initialization of the Lucene Directory.</para> + + <table> + <title>List of built-in Directory Providers</title> + + <tgroup cols="3"> + <thead> + <row> + <entry align="center">Class</entry> + + <entry align="center">description</entry> + + <entry align="center">Properties</entry> + </row> + </thead> + + <tbody> + <row> + <entry>org.hibernate.lucene.store.FSDirectoryProvider</entry> + + <entry>File system based directory. The directory used will be + &amp;lt;indexBase&amp;gt;/&amp;lt;&lt;literal&gt;(a)Index.name&lt;/literal&gt;&amp;gt;&lt;/entry&gt; + + <entry><literal>indexBase</literal>: Base directory</entry> + </row> + + <row> + <entry>org.hibernate.lucene.store.RAMDirectoryProvider</entry> + + <entry>Memory based directory, the directory will be uniquely + indentified by the <literal&gt;(a)Index.name&lt;/literal&gt; + element</entry> + + <entry>none</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>If the built-in directory providers does not fit your needs, you + can write your own directory provider by implementing the + <classname>org.hibernate.store.DirectoryProvider</classname> + interface</para> + + <para>Each indexed entity is associated to a Lucene index (an index can + be shared by several entities but this is not usually the case). You can + configure the index through properties prefixed by + <literal><literal>hibernate.lucene.&lt;indexname&gt;</literal></literal>. + Default properties inherited to all indexes can be defined using the + prefix hibernate.lucene.default.</para> + + <para>To define the directory provider of a given index, you use the + <literal>hibernate.lucene.&lt;indexname&gt;.directory_provider</literal></para> + + <programlisting>hibernate.lucene.default.directory_provider org.hibernate.lucene.store.FSDirectoryProvider +hibernate.lucene.default.indexDir=/usr/lucene/indexes + +hibernate.lucene.Rules.directory_provider org.hibernate.lucene.store.RAMDirectoryProvider +</programlisting> + + <para>applied on</para> + + <programlisting>@Indexed(name="Status") +public class Status { ... } + +@Indexed(name="Rules") +public class Rule { ... }</programlisting> + + <para>will create a file system directory in + <filename>/usr/lucene/indexes/Status</filename> where the Status + entities will be indexed, and use an in memory directory named + <literal>Rules</literal> where Rule entities will be indexed.</para> + + <para>So you can easily defined common rules like the directory provider + and base directory, and overide those default later on on a per index + basis.</para> + + <para>Writing your own DirectoryProvider, you can benefit this + configuration mechanism too.</para> + </section> + + <section id="lucene-configuration-event"> <title>Enabling automatic indexing</title> <para>Finally, we enable the <literal>LuceneEventListener</literal> for @@ -90,6 +188,6 @@ class="org.hibernate.lucene.event.LuceneEventListener"/&gt; &lt;/event&gt; &lt;/hibernate-configuration&gt;</programlisting> - </sect2> - </sect1> + </section> + </section> </chapter> \ No newline at end of file Modified: trunk/HibernateExt/metadata/doc/reference/en/modules/setup.xml =================================================================== --- trunk/HibernateExt/metadata/doc/reference/en/modules/setup.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/doc/reference/en/modules/setup.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -12,13 +12,15 @@ </listitem> <listitem> - <para><emphasis>This preview release requires Hibernate 3.2.0.CR2 and - above. Do not use this release of Hibernate Annotations with an older - version of Hibernate 3.x!</emphasis></para> + <para><emphasis>This release requires Hibernate 3.2.0.CR4 and above. + Do not use this release of Hibernate Annotations with an older version + of Hibernate 3.x!</emphasis></para> </listitem> <listitem> - <para>This release is known to work on Hibernate core 3.2.0.CR2</para> + <para>This release is known to work on Hibernate core 3.2.0.CR4 and is + expected (at the time of writing) to work on Hibernate Core + 3.2.0.GA</para> </listitem> <listitem> @@ -124,7 +126,7 @@ <emphasis role="bold"> .addResource("test/animals/orm.xml")</emphasis> .buildSessionFactory();</programlisting> - <para>You can also use the Hibernate Entity Manager which has it's own + <para>You can also use the Hibernate EntityManager which has its own configuration mechanism. Please refer to this project documentation for more details.</para> Modified: trunk/HibernateExt/metadata/doc/reference/en/modules/validator.xml =================================================================== --- trunk/HibernateExt/metadata/doc/reference/en/modules/validator.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/doc/reference/en/modules/validator.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -219,20 +219,24 @@ </sect2> <sect2 id="validator-constraints-error" xreflabel="Error messages"> - <title id="validator-constraints-error">Error messages</title> + <title>Error messages</title> <para>Hibernate Validator comes with a default set of error messages - translated in a few languages (if yours is not part of it, please sent - us a patch). You can override those messages by creating a + translated in about ten languages (if yours is not part of it, please + sent us a patch). You can override those messages by creating a <filename>ValidatorMessages.properties</filename> or - (<filename>ValidatorMessages_loc.properties</filename>) out of - <filename>org.hibernate.validator.resources.DefaultValidatorMessages.properties</filename> - and change the appropriate keys. You can even add your own additional - set of messages while writing your validator annotations.</para> + (<filename>ValidatorMessages_loc.properties</filename>) and override the + needed keys. You can even add your own additional set of messages while + writing your validator annotations. If Hibernate Validator cannot + resolve a key from your resourceBundle nor from ValidatorMessage, it + falls back to the default built-in values.</para> <para>Alternatively you can provide a <classname>ResourceBundle</classname> while checking programmatically - the validation rules on a bean.</para> + the validation rules on a bean or if you want a completly different + interpolation mechanism, you can provide an implementation of + <literal>org.hibernate.validator.MessageInterpolator</literal> (check + the JavaDoc for more informations).</para> </sect2> <sect2> Modified: trunk/HibernateExt/metadata/doc/reference/en/modules/xml-overriding.xml =================================================================== --- trunk/HibernateExt/metadata/doc/reference/en/modules/xml-overriding.xml 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/doc/reference/en/modules/xml-overriding.xml 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1"?> -<chapter id="xml-overriding"> +<chapter id="xml-overriding" label="Overriding metadata through XML"> <title>Overriding metadata through XML</title> <para>The primary target for metadata in EJB3 is annotations, but the EJB3 @@ -12,7 +12,7 @@ <para>The unit test suite shows some additional XML file samples.</para> - <section> + <section id="xml-overriding-principles"> <title>Principles</title> <para>The XML deployment descriptor structure has been designed to reflect @@ -58,7 +58,7 @@ feature.</para> </section> - <section> + <section id="xml-overriding-principles-entity" revision="1"> <title>Entity level metadata</title> <para>You can either define or override metadata informations on a given @@ -138,7 +138,7 @@ </callout> <callout arearefs="aa3"> - <para><literal>entity</literal>: desribes an entity. </para> + <para><literal>entity</literal>: desribes an entity.</para> <para><literal>metadata-complete</literal> defines whether the metadata description for this element is complete or not (in other @@ -146,7 +146,7 @@ considered or not).</para> <para>An entity has to have a <literal>class</literal> attribute - refering the java class the metadata applies on. </para> + refering the java class the metadata applies on.</para> <para>You can overrides entity name through the <literal>name</literal> attribute, if none is defined and if an @@ -156,7 +156,9 @@ <para>For netadata complete (see below) element, you can define an <literal>access</literal> (either <literal>FIELD</literal> or <literal>PROPERTY</literal> (default)). For non medatada complete - element, the annotations driven access type is used.</para> + element, if <literal>access</literal> is not defined, the @Id + position will lead position, if <literal>access</literal> is + defined, the value is used.</para> </callout> <callout arearefs="aa4"> Modified: trunk/HibernateExt/metadata/lib/README.txt =================================================================== --- trunk/HibernateExt/metadata/lib/README.txt 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/lib/README.txt 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,5 +1,5 @@ Hibernate Metadata dependencies =============================== -ejb3-persistence.jar (public final draft version): required -lucene-1.4.3.jar (1.4.3): optional, useful when lucene integration is used \ No newline at end of file +ejb3-persistence.jar (final release version): required +lucene-2.0.0.jar (2.0.0): optional, useful when lucene integration is used \ No newline at end of file Modified: trunk/HibernateExt/metadata/readme.txt =================================================================== --- trunk/HibernateExt/metadata/readme.txt 2006-09-14 16:03:06 UTC (rev 10484) +++ trunk/HibernateExt/metadata/readme.txt 2006-09-16 20:50:39 UTC (rev 10485) @@ -1,6 +1,6 @@ Hibernate Annotations ================================================== -Version: 3.2.0 CR2, xx.09.2006 +Version: 3.2.0 CR2, 16.09.2006 THIS RELEASE OF HIBERNATE ANNOTATIONS REQUIRES HIBERNATE CORE 3.2.0.CR4 AND DOES NOT WORK WITH HIBERNATE 3.1.x OR ANY OLDER VERSION OF HIBERNATE.