Author: epbernard Date: 2006-12-07 16:36:31 -0500 (Thu, 07 Dec 2006) New Revision: 10947 Modified: branches/Branch_3_2/HibernateExt/ejb/build.xml branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/master.xml branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/modules/configuration.xml branches/Branch_3_2/HibernateExt/ejb/src/java/org/hibernate/ejb/Version.java branches/Branch_3_2/HibernateExt/metadata/build.xml branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/master.xml branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/entity.xml branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/setup.xml branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/validator.xml branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/annotations/ResultCheckStyle.java branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/cfg/annotations/Version.java branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/validator/NotEmptyValidator.java Log: Various docs adds-on and fixes Version change Modified: branches/Branch_3_2/HibernateExt/ejb/build.xml =================================================================== --- branches/Branch_3_2/HibernateExt/ejb/build.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/ejb/build.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -16,7 +16,7 @@ <!-- Name of project and version, used to create filenames --> <property name="Name" value="Hibernate EntityManager"/> <property name="name" value="hibernate-entitymanager"/> - <property name="version" value="3.2.0.GA"/> + <property name="version" value="3.2.1.GA"/> <property name="javadoc.packagenames" value="org.hibernate.ejb.*"/> <property name="jdbc.dir" value="jdbc"/> <property name="copy.test" value="true"/> Modified: branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/master.xml =================================================================== --- branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/master.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/master.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -16,7 +16,7 @@ <subtitle>User guide</subtitle> - <releaseinfo>3.2.0.GA</releaseinfo> + <releaseinfo>3.2.1.GA</releaseinfo> <mediaobject> <imageobject> Modified: branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/modules/configuration.xml =================================================================== --- branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/modules/configuration.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/ejb/doc/reference/en/modules/configuration.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -8,18 +8,17 @@ <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.CR5 and 3.2.0.GA and Hibernate Annotations - 3.2.0.CR3 and 3.2.0.GA. 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> + 3.2.0.CR5, 3.2.0.GA, 3.2.1.GA and Hibernate Annotations 3.2.0.CR3, 3.2.0.GA, 3.2.1.GA. + 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" xreflabel="Configuration and bootstrapping"> <title>Configuration and bootstrapping</title> - <section id="setup-configuration-packaging"> + <section id="setup-configuration-packaging" revision="1"> <title>Packaging</title> <para>The configuration for entity managers both inside an application @@ -87,7 +86,9 @@ <listitem> <para>(attribute) Transaction type used. Either JTA or RESOURCE_LOCAL (default to JTA in a JavaEE environment and to - RESOURCE_LOCAL in a JavaSE environment).</para> + RESOURCE_LOCAL in a JavaSE environment). When a jta-datasource is + used, the default is JTA, if non-jta-datasource is used, + RESOURCE_LOCAL is used.</para> </listitem> </varlistentry> @@ -145,7 +146,12 @@ files part of this jar file will be added to the persistence unit configuration. This element is mainly used in Java EE environment. Use of this one in Java SE should be considered as non portable, - in this case a absolute url is needed.</para> + in this case a absolute url is needed. You can alternatively point + to a directory (This is especially useful when in your test + environment, the persistence.xml file is not under the same root + directory or jar than your domain model).</para> + + <programlisting> &lt;jar-file&gt;file:/home/turin/work/local/lab8/build/classes&lt;/jar-file&gt;</programlisting> </listitem> </varlistentry> @@ -173,7 +179,10 @@ through the class element though. As an extension to the specification, you can add a package name in the <literal>&lt;class&gt;</literal> element (eg - <code>&lt;class&gt;org.hibernate.eg&lt;/class&gt;</code>).</para> + <code>&lt;class&gt;org.hibernate.eg&lt;/class&gt;</code>). + Caution, the package will include the metadata defined at the + package level (ie in <filename>package-info.java</filename>), it + will not include all the classes of a given package.</para> </listitem> </varlistentry> @@ -204,7 +213,7 @@ version="1.0"&gt;</programlisting> </section> - <section id="setup-configuration-bootstrapping"> + <section id="setup-configuration-bootstrapping" revision="1"> <title>Bootstrapping</title> <para>The EJB3 specification defines a bootstrap procedure to access the @@ -411,7 +420,7 @@ &lt;!-- alternatively to &lt;class&gt; and &lt;property&gt; declarations, you can use a regular hibernate.cfg.xml file --&gt; &lt;!-- property name="hibernate.ejb.cfgfile" value="/org/hibernate/ejb/test/hibernate.cfg.xml"/ --&gt; &lt;/properties&gt; - &lt;persistence-unit&gt; + &lt;/persistence-unit&gt; &lt;/persistence&gt;</programlisting> <para>To ease the programmatic configuration, Hibernate Entity Manager Modified: branches/Branch_3_2/HibernateExt/ejb/src/java/org/hibernate/ejb/Version.java =================================================================== --- branches/Branch_3_2/HibernateExt/ejb/src/java/org/hibernate/ejb/Version.java 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/ejb/src/java/org/hibernate/ejb/Version.java 2006-12-07 21:36:31 UTC (rev 10947) @@ -8,7 +8,7 @@ * @author Emmanuel Bernard */ public class Version { - public static final String VERSION = "3.2.0.GA"; + public static final String VERSION = "3.2.1.GA"; private static Log log = LogFactory.getLog( Version.class ); static { Modified: branches/Branch_3_2/HibernateExt/metadata/build.xml =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/build.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/build.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -16,7 +16,7 @@ <!-- Name of project and version, used to create filenames --> <property name="Name" value="Hibernate Annotations"/> <property name="name" value="hibernate-annotations"/> - <property name="version" value="3.2.0.GA"/> + <property name="version" value="3.2.1.GA"/> <property name="javadoc.packagenames" value="org.hibernate.*"/> <property name="jdbc.dir" value="jdbc"/> <property name="copy.test" value="true"/> Modified: branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/master.xml =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/master.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/master.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -13,7 +13,7 @@ <subtitle>Reference Guide</subtitle> - <releaseinfo>3.2.0.GA</releaseinfo> + <releaseinfo>3.2.1.GA</releaseinfo> <mediaobject> <imageobject> Modified: branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/entity.xml =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/entity.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/entity.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -1714,7 +1714,7 @@ <literal>LAZY</literal> and <literal>@OneToOne</literal> and <literal>@ManyToOne</literal> are defaulted to <literal>EAGER</literal>. For more information about static fetching, - check <xref linkend="entity-hibspec-singleassoc-fetching" />. </para> + check <xref linkend="entity-hibspec-singleassoc-fetching" />.</para> <para>The recommanded approach is to use <literal>LAZY</literal> onn all static fetching definitions and override this choice dynamically @@ -2623,6 +2623,25 @@ <literal>@Generated(INSERT)</literal> by design, it has to be either <literal>NEVER</literal> or <literal>ALWAYS</literal>.</para> </sect3> + + <sect3> + <title>@Target</title> + + <para>Sometimes, the type guessed by reflection is not the one you + want Hibernate to use. This is especially true on components when an + interface is used. You can use <literal>@Target</literal> to by pass + the reflection guessing mechanism (very much like the + <literal>targetEntity</literal> attribute available on + associations.</para> + + <programlisting> @Embedded + <emphasis role=&quot;bold&quot;&gt;(a)Target(OwnerImpl.class)&lt;/emphasis&gt; + public Owner getOwner() { + return owner; + }</programlisting> + + <para></para> + </sect3> </sect2> <sect2 id="entity-hibspec-inheritance" revision="1"> @@ -2903,7 +2922,7 @@ </note> </sect4> - <sect4> + <sect4 id="entity-hibspec-collection-extratype-map" revision="1"> <title>Map</title> <para>Hibernate Annotations also supports true Map mappings, if @@ -2915,6 +2934,18 @@ embeddable object, or you can use <literal&gt;(a)org.hibernate.annotations.MapKeyManyToMany&lt;/literal&gt; if your key is an entity.</para> + + <para>Both <literal&gt;(a)org.hibernate.annotations.MapKey&lt;/literal&gt; and + <literal&gt;(a)org.hibernate.annotations.MapKeyManyToMany&lt;/literal&gt; + allows you to override the target element to be used. This is + especially useful if your collection does not use generics (or if + you use interfaces).</para> + + <programlisting> @CollectionOfElements(targetElement = SizeImpl.class) + @MapKeyManyToMany(<emphasis role="bold">targetEntity = LuggageImpl.class</emphasis>) + private Map&lt;Luggage, Size&gt; sizePerLuggage = new HashMap&lt;Luggage, Size&gt;();</programlisting> + + <para></para> </sect4> <sect4 id="entity-hibspec-collection-extratype-indexbidir"> @@ -3319,5 +3350,84 @@ detyped <literal>@QueryHint</literal>. Another key advantage is the ability to set those annotations at a package level.</para> </sect2> + + <sect2 id="entity-hibspec-customsql"> + <title>Custom SQL for CRUD operations</title> + + <para>Hibernate gives you the avility to override every single SQL + statement generated. We have seen native SQL query usage already, but + you can also override the SQL statement used to load or change the state + of entities.</para> + + <programlisting>@Entity +@Table(name="CHAOS") +<emphasis role="bold">@SQLInsert( sql="INSERT INTO CHAOS(size, name, nickname, id) VALUES(?,upper(?),?,?)") +@SQLUpdate( sql="UPDATE CHAOS SET size = ?, name = upper(?), nickname = ? WHERE id = ?") +@SQLDelete( sql="DELETE CHAOS WHERE id = ?") +@SQLDeleteAll( sql="DELETE CHAOS") +</emphasis><emphasis role="bold">@Loader(namedQuery = "chaos")</emphasis> +@NamedNativeQuery(name="chaos", query="select id, size, name, lower( nickname ) as nickname from CHAOS where id= ?", resultClass = Chaos.class) +public class Chaos { + @Id + private Long id; + private Long size; + private String name; + private String nickname;</programlisting> + + <para><literal>@SQLInsert</literal>, <literal>@SQLUpdate</literal>, + <literal>@SQLDelete</literal>, <literal>@SQLDeleteAll</literal> + respectively override the INSERT statement, UPDATE statement, DELETE + statement, DELETE statement to remove all entities.</para> + + <para>If you expect to call a store procedure, be sure to set the + <literal>callable</literal> attribute to true + (<literal>@SQLInsert(callable=true, ...)</literal>).</para> + + <para>To check that the execution happens correctly, Hibernate allows + you to define one of those three strategies:</para> + + <itemizedlist> + <listitem> + <para>NONE: no check is performed: the store procedure is expected + to fail upon issues</para> + </listitem> + + <listitem> + <para>COUNT: use of rowcount to check that the update is + successful</para> + </listitem> + + <listitem> + <para>PARAM: like COUNT but using an output parameter rather that + the standard mechanism</para> + </listitem> + </itemizedlist> + + <para>To define the result check style, use the <literal>check</literal> + parameter (<literal&gt;(a)SQLUpdate(check=ResultCheckStyle.COUNT, + ...)</literal>).</para> + + <para>You can also override the SQL load statement by a native SQL query + or a HQL query. You just have to refer to a named query with the + <literal><literal>@Loader</literal></literal> annotation.</para> + + <para>You can use the exact same set of annotations to override the + collection related statements.</para> + + <programlisting>@OneToMany +@JoinColumn(name="chaos_fk") +<emphasis role="bold">@SQLInsert( sql="UPDATE CASIMIR_PARTICULE SET chaos_fk = ? where id = ?") +@SQLDelete( sql="UPDATE CASIMIR_PARTICULE SET chaos_fk = null where id = ?")</emphasis> +private Set&lt;CasimirParticle&gt; particles = new HashSet&lt;CasimirParticle&gt;();</programlisting> + + <para>The parameters order is important and is defined by the order + Hibernate handle properties. You can see the expected order by enabling + debug logging for the <literal>org.hibernate.persister.entity</literal> + level. With this level enabled Hibernate will print out the static SQL + that is used to create, update, delete etc. entities. (To see the + expected sequence, remember to not include your custom SQL through + annotations as that will override the Hibernate generated static + sql.)</para> + </sect2> </sect1> </chapter> \ No newline at end of file Modified: branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/setup.xml =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/setup.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/setup.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -18,8 +18,8 @@ </listitem> <listitem> - <para>This release is known to work on Hibernate core 3.2.0.CR5 - and 3.2.0.GA</para> + <para>This release is known to work on Hibernate core 3.2.0.CR5, 3.2.0.GA + and 3.2.1.GA</para> </listitem> <listitem> Modified: branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/validator.xml =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/validator.xml 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/doc/reference/en/modules/validator.xml 2006-12-07 21:36:31 UTC (rev 10947) @@ -45,7 +45,7 @@ constraint apply to the annotated element.</para> </sect2> - <sect2> + <sect2 id="validator-constraints-built-in" revision="1"> <title>Built in constraints</title> <para>Hibernate Validator comes with some built-in constraints, which @@ -114,6 +114,17 @@ </row> <row> + <entry>@NotEmpty</entry> + + <entry>property</entry> + + <entry>check if the string is not null nor empty. Check if the + connection is not null nor empty</entry> + + <entry>Column(s) are not null (for String)</entry> + </row> + + <row> <entry>@Past</entry> <entry>property (date or calendar)</entry> Modified: branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/annotations/ResultCheckStyle.java =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/annotations/ResultCheckStyle.java 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/annotations/ResultCheckStyle.java 2006-12-07 21:36:31 UTC (rev 10947) @@ -7,7 +7,25 @@ * @author L�szl� Benke */ public enum ResultCheckStyle { + /** + * Do not perform checking. Either user simply does not want checking, or is + * indicating a {@link java.sql.CallableStatement} execution in which the + * checks are being performed explicitly and failures are handled through + * propogation of {@link java.sql.SQLException}s. + */ NONE, + /** + * Perform row-count checking. Row counts are the int values returned by both + * {@link java.sql.PreparedStatement#executeUpdate()} and + * {@link java.sql.Statement#executeBatch()}. These values are checked + * against some expected count. + */ COUNT, + /** + * Essentially the same as {@link #COUNT} except that the row count actually + * comes from an output parameter registered as part of a + * {@link java.sql.CallableStatement}. This style explicitly prohibits + * statement batching from being used... + */ PARAM } Modified: branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/cfg/annotations/Version.java =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/cfg/annotations/Version.java 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/cfg/annotations/Version.java 2006-12-07 21:36:31 UTC (rev 10947) @@ -8,7 +8,7 @@ * @author Emmanuel Bernard */ public class Version { - public static final String VERSION = "3.2.1-dev"; + public static final String VERSION = "3.2.1.GA"; private static Log log = LogFactory.getLog( Version.class ); static { Modified: branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/validator/NotEmptyValidator.java =================================================================== --- branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/validator/NotEmptyValidator.java 2006-12-07 14:50:59 UTC (rev 10946) +++ branches/Branch_3_2/HibernateExt/metadata/src/java/org/hibernate/validator/NotEmptyValidator.java 2006-12-07 21:36:31 UTC (rev 10947) @@ -5,13 +5,18 @@ import java.lang.reflect.Array; import java.util.Collection; import java.util.Map; +import java.util.Iterator; +import org.hibernate.mapping.Property; +import org.hibernate.mapping.SingleTableSubclass; +import org.hibernate.mapping.Column; + /** * Check the non emptyness of the element * * @author Gavin King */ -public class NotEmptyValidator implements Validator<NotEmpty>, Serializable { +public class NotEmptyValidator implements Validator<NotEmpty>, PropertyConstraint, Serializable { public void initialize(NotEmpty parameters) { } @@ -32,4 +37,18 @@ } } + @SuppressWarnings("unchecked") + public void apply(Property property) { + if ( ! ( property.getPersistentClass() instanceof SingleTableSubclass ) + && ! ( property.getValue() instanceof Collection ) ) { + //single table should not be forced to null + if ( !property.isComposite() ) { //composite should not add not-null on all columns + Iterator<Column> iter = (Iterator<Column>) property.getColumnIterator(); + while ( iter.hasNext() ) { + iter.next().setNullable( false ); + } + } + } + } + }