Author: epbernard Date: 2007-03-01 03:29:34 -0500 (Thu, 01 Mar 2007) New Revision: 11249 Modified: branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/entity.xml branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/setup.xml branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Table.java branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Tuplizer.java branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/architecture.xml branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml Log: Documentation Modified: branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/entity.xml =================================================================== --- branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/entity.xml 2007-02-28 02:06:13 UTC (rev 11248) +++ branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/entity.xml 2007-03-01 08:29:34 UTC (rev 11249) @@ -133,8 +133,8 @@ type provided that you define and implement the appropriate <classname>UserVersionType</classname>.</para> - <para>The application must not alter the version number set up - by Hibernate in any way. To artificially increase the version number, + <para>The application must not alter the version number set up by + Hibernate in any way. To artificially increase the version number, check in Hibernate Entity Manager's reference documentation <literal>LockMode.WRITE</literal></para> </sect3> @@ -2238,7 +2238,7 @@ <classname>org.hibernate.annotations</classname> package contains all these annotations extensions.</para> - <sect2 id="entity-hibspec-entity" revision="2"> + <sect2 id="entity-hibspec-entity" revision="3"> <title>Entity</title> <para>You can fine tune some of the actions done by Hibernate on @@ -2323,6 +2323,45 @@ <literal&gt;(a)org.hibernate.annotations.Table&lt;/literal&gt;.&lt;/para&gt; </note> + <para&gt;&lt;literal&gt;(a)org.hibernate.annotations.Table&lt;/literal&gt; can also be + used to define the following elements of secondary tables: </para> + + <itemizedlist> + <listitem> + <para><literal>fetch</literal>: If set to JOIN, the default, + Hibernate will use an inner join to retrieve a secondary table + defined by a class or its superclasses and an outer join for a + secondary table defined by a subclass. If set to select then + Hibernate will use a sequential select for a secondary table defined + on a subclass, which will be issued only if a row turns out to + represent an instance of the subclass. Inner joins will still be + used to retrieve a secondary defined by the class and its + superclasses.</para> + </listitem> + + <listitem> + <para><literal>inverse</literal>: If true, Hibernate will not try to + insert or update the properties defined by this join. Default to + false.</para> + </listitem> + + <listitem> + <para><literal>optional</literal>: If enabled (the default), + Hibernate will insert a row only if the properties defined by this + join are non-null and will always use an outer join to retrieve the + properties. </para> + </listitem> + + <listitem> + <para><literal>foreignKey</literal>: defines the Foreign Key name of + a secondary table pointing back to the primary table.</para> + </listitem> + </itemizedlist> + + <para><literal>@Immutable</literal> marks an entity as immutable. The + entity may not be updated or deleted by the application. This allows + Hibernate to make some minor performance optimizations.</para> + <para><programlisting>@Entity @BatchSize(size=5) @org.hibernate.annotations.Entity( @@ -2648,7 +2687,7 @@ </sect3> </sect2> - <sect2 id="entity-hibspec-inheritance" revision="1"> + <sect2 id="entity-hibspec-inheritance" revision="2"> <title>Inheritance</title> <para>SINGLE_TABLE is a very powerful strategy but sometimes, and @@ -2661,7 +2700,7 @@ column).</para> <programlisting>@Entity -@DiscriminatorForumla("case when forest_type is null then 0 else forest_type end") +<emphasis role="bold">@DiscriminatorForumla("case when forest_type is null then 0 else forest_type end")</emphasis> public class Forest { ... }</programlisting> <para>By default, when querying the top entities, Hibernate does not put @@ -2671,6 +2710,21 @@ 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> + + <para>You can define the foreign key name generated by Hibernate for + subclass tables in the JOINED inheritance strategy.</para> + + <programlisting>@Entity +@Inheritance(strategy = InheritanceType.JOINED) +public abstract class File { ... } + +@Entity +@ForeignKey(name = "FK_DOCU_FILE") +public class Document extends File {</programlisting> + + <para>The foreign key from the <literal>Document</literal> table to the + <literal>File</literal> table will be named + <literal>FK_DOCU_FILE</literal>.</para> </sect2> <sect2 id="entity-hibspec-singleassoc"> @@ -2830,7 +2884,7 @@ <sect2 id="entity-hibspec-collection" revision="2"> <title>Collection related annotations</title> - <sect3 id="entity-hibspec-collection-enhance" revision="2"> + <sect3 id="entity-hibspec-collection-enhance" revision="3"> <title>Enhance collection settings</title> <para>It is possible to set <itemizedlist> @@ -2853,6 +2907,10 @@ <listitem> the delete cascade strategy through @OnDelete(action=OnDeleteAction.CASCADE) </listitem> + + <listitem> + the collection immutability using @Immutable: if set specifies that the elements of the collection never change (a minor performance optimization in some cases) + </listitem> </itemizedlist></para> <para>You can also declare a sort comparator. Use the @@ -3355,8 +3413,8 @@ ability to set those annotations at a package level.</para> </sect2> - <sect2 id="entity-hibspec-customsql"> - <title>Custom SQL for CRUD operations</title> + <sect2 id="entity-hibspec-customsql" revision="1"> + <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 @@ -3432,6 +3490,69 @@ expected sequence, remember to not include your custom SQL through annotations as that will override the Hibernate generated static sql.)</para> + + <para>Overriding SQL statements for secondary tables is also possible + using <literal&gt;(a)org.hibernate.annotations.Table&lt;/literal&gt; and either (or + all) attributes <literal>sqlInsert</literal>, + <literal>sqlUpdate</literal>, <literal>sqlDelete</literal>:</para> + + <programlisting>@Entity +@SecondaryTables({ + @SecondaryTable(name = "`Cat nbr1`"), + @SecondaryTable(name = "Cat2"}) +(a)org.hibernate.annotations.Tables( { + @Table(appliesTo = "Cat", comment = "My cat table" ), + @Table(appliesTo = "Cat2", foreignKey = @ForeignKey(name="FK_CAT2_CAT"), fetch = FetchMode.SELECT, + <emphasis role="bold">sqlInsert=@SQLInsert(sql="insert into Cat2(storyPart2, id) values(upper(?), ?)") )</emphasis> +} ) +public class Cat implements Serializable {</programlisting> + + <para>The previous example also show that you can give a comment to a + given table (promary or secondary): This comment will be used for DDL + generation.</para> </sect2> + + <sect2> + <title>Tuplizer</title> + + <para><classname>org.hibernate.tuple.Tuplizer</classname>, and its + sub-interfaces, are responsible for managing a particular representation + of a piece of data, given that representation's + <literal>org.hibernate.EntityMode</literal>. If a given piece of data is + thought of as a data structure, then a tuplizer is the thing which knows + how to create such a data structure and how to extract values from and + inject values into such a data structure. For example, for the POJO + entity mode, the correpsonding tuplizer knows how create the POJO + through its constructor and how to access the POJO properties using the + defined property accessors. There are two high-level types of Tuplizers, + represented by the + <classname>org.hibernate.tuple.EntityTuplizer</classname> and + <classname>org.hibernate.tuple.ComponentTuplizer</classname> interfaces. + EntityTuplizers are responsible for managing the above mentioned + contracts in regards to entities, while + <classname>ComponentTuplizers</classname> do the same for components. + Check the Hibernate reference documentation for more information.</para> + + <para>To define tuplixer in annotations, simply use the + <literal>@Tuplizer</literal> annotation on the according element</para> + + <programlisting>@Entity +<emphasis role="bold">@Tuplizer(impl = DynamicEntityTuplizer.class)</emphasis> +public interface Cuisine { + @Id + @GeneratedValue + public Long getId(); + public void setId(Long id); + + public String getName(); + public void setName(String name); + + <emphasis role="bold">@Tuplizer(impl = DynamicComponentTuplizer.class)</emphasis> + public Country getCountry(); + public void setCountry(Country country); + + +}</programlisting> + </sect2> </sect1> </chapter> \ No newline at end of file Modified: branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/setup.xml =================================================================== --- branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/setup.xml 2007-02-28 02:06:13 UTC (rev 11248) +++ branches/Branch_3_2/HibernateExt/annotations/doc/reference/en/modules/setup.xml 2007-03-01 08:29:34 UTC (rev 11249) @@ -48,7 +48,6 @@ <filename>lib/ejb3-persistence.jar</filename> from the Hibernate Annotations distribution to your classpath as well.</para> </listitem> - </itemizedlist></para> <para>If you wish to use Hibernate Validator (TODO make a link to HV doc), @@ -156,4 +155,40 @@ hbm</literal> will prioritize the annotated classes over hbm files when a conflict occurs.</para> </section> + + <section> + <title id="setup-properties">Properties</title> + + <para>Asides from the Hibernate core properties, Hibernate Annotations + reacts to the following one</para> + + <table> + <title>List of properties</title> + + <tgroup cols="2"> + <thead> + <row> + <entry align="center">Property</entry> + + <entry align="center">Definition</entry> + </row> + </thead> + + <tbody> + <row> + <entry>hibernate.validator.apply_to_ddl</entry> + + <entry>Use Hibernate Validator annotations to refine the database + schema generation. Default to true.</entry> + </row> + + <row> + <entry></entry> + + <entry></entry> + </row> + </tbody> + </tgroup> + </table> + </section> </chapter> \ No newline at end of file Modified: branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Table.java =================================================================== --- branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Table.java 2007-02-28 02:06:13 UTC (rev 11248) +++ branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Table.java 2007-03-01 08:29:34 UTC (rev 11249) @@ -31,7 +31,7 @@ /** * Defines the Foreign Key name of a secondary table - * back to the primary table + * pointing back to the primary table */ ForeignKey foreignKey() default @ForeignKey( name="" ); @@ -49,7 +49,7 @@ FetchMode fetch() default FetchMode.JOIN; /** - * If enabled, Hibernate will not try to insert or update the properties defined by this join. + * If true, Hibernate will not try to insert or update the properties defined by this join. * * <b>Only applies to secondary tables</b> */ Modified: branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Tuplizer.java =================================================================== --- branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Tuplizer.java 2007-02-28 02:06:13 UTC (rev 11248) +++ branches/Branch_3_2/HibernateExt/annotations/src/java/org/hibernate/annotations/Tuplizer.java 2007-03-01 08:29:34 UTC (rev 11249) @@ -16,6 +16,6 @@ public @interface Tuplizer { /** tuplizer implementation */ Class impl(); - /** either pojo, dynamic-map or domj4 */ + /** either pojo, dynamic-map or dom4j� */ String entityMode() default "pojo"; } Modified: branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/architecture.xml =================================================================== --- branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/architecture.xml 2007-02-28 02:06:13 UTC (rev 11248) +++ branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/architecture.xml 2007-03-01 08:29:34 UTC (rev 11249) @@ -1,46 +1,80 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> +<?xml version="1.0" encoding="UTF-8"?> <chapter id="search-architecture"> - <title>Architecture</title> + <title>Architecture</title> - <para>Hibernate Search is made of an indexing engine and an index search - engine. Both are backed by Apache Lucene. - </para> + <para>Hibernate Search is made of an indexing engine and an index search + engine. Both are backed by Apache Lucene.</para> - <para>When an entity is inserted, updated or removed to/from the database, - <productname>Hibernate Search</productname> - will keep track of this event - (through the Hibernate event system) and schedule an index update. When - out of transaction, the update is executed right after the actual database - operation. It is however recommended, for both your database and Hibernate - Search, to execute your operation in a transaction (whether JDBC or JTA). - When in a transaction, the index update is schedule for the transaction - commit (and discarded in case of transaction rollback). You can think of - this as the regular (infamous) autocommit vs transactional behavior. From - a performance perspective, the - <emphasis>in transaction</emphasis> - mode is - recommended. All the index updates are handled for you without you having - to use the Apache Lucene APIs. - </para> + <para>When an entity is inserted, updated or removed to/from the database, + <productname>Hibernate Search</productname> will keep track of this event + (through the Hibernate event system) and schedule an index update. When out + of transaction, the update is executed right after the actual database + operation. It is however recommended, for both your database and Hibernate + Search, to execute your operation in a transaction (whether JDBC or JTA). + When in a transaction, the index update is schedule for the transaction + commit (and discarded in case of transaction rollback). You can think of + this as the regular (infamous) autocommit vs transactional behavior. From a + performance perspective, the <emphasis>in transaction</emphasis> mode is + recommended. All the index updates are handled for you without you having to + use the Apache Lucene APIs.</para> - <para>To interact with Apache Lucene indexes, Hibernate Search has the - notion of - <classname>DirectoryProvider</classname> - . A directory provider - will manage a given Lucene - <classname>Directory</classname> - type. You can - configure directory providers to adjust the directory target. - </para> + <para>To interact with Apache Lucene indexes, Hibernate Search has the + notion of <classname>DirectoryProvider</classname> . A directory provider + will manage a given Lucene <classname>Directory</classname> type. You can + configure directory providers to adjust the directory target.</para> - <para> - <productname>Hibernate Search</productname> - can also use a Lucene - index to search an entity and return a (list of) managed entity saving you - from the tedious Object / Lucene Document mapping and low level Lucene - APIs. The application code use the unified - <classname>org.hibernate.Query</classname> - API exactly the way a HQL or - native query would be done. - </para> + <para><productname>Hibernate Search</productname> can also use a Lucene + index to search an entity and return a (list of) managed entity saving you + from the tedious Object / Lucene Document mapping and low level Lucene APIs. + The application code use the unified + <classname>org.hibernate.Query</classname> API exactly the way a HQL or + native query would be done.</para> + + <section> + <title>Backend</title> + + <para>Hibernate Search offers the ability to process the</para> + + <section> + <title>Lucene</title> + + <para>In this mode, all index update operations applied on a given node + (JVM) will be executed to the Lucene directories (through the directory + providers) by the same node. This mode is typically used in non + clustered mode or in clustered mode where the directory store is shared. + </para> + </section> + + <section> + <title>JMS</title> + + <para></para> + </section> + + <section> + <title>Custom</title> + + <para></para> + </section> + </section> + + <section> + <title>Work execution</title> + + <para>The indexing work can be executed synchronously with the transaction + commit (or update operation if out of transaction), or + asynchronously.</para> + + <section> + <title>Synchronous</title> + + <para></para> + </section> + + <section> + <title>Asynchronous</title> + + <para></para> + </section> + </section> </chapter> \ No newline at end of file Modified: branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml =================================================================== --- branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml 2007-02-28 02:06:13 UTC (rev 11248) +++ branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml 2007-03-01 08:29:34 UTC (rev 11249) @@ -10,7 +10,7 @@ <para>This chapter will cover Hibernate Validator usage for different layers</para> - <section id="validator-checkconstraints-db" revision="1"> + <section id="validator-checkconstraints-db" revision="2"> <title>Database schema-level validation</title> <para>Out of the box, Hibernate Annotations will translate the constraints @@ -21,6 +21,10 @@ <para>Using hbm2ddl, domain model constraints will be expressed into the database schema.</para> + + <para>If, for some reason, the feature needs to be disabled, set + <literal>hibernate.validator.apply_to_ddl</literal> to + <literal>false</literal>.</para> </section> <section id="validator-checkconstraints-orm"> @@ -83,7 +87,6 @@ @EntityListeners( JPAValidateListener.class ) public class Submarine { ... -} }</programlisting> <para><note> @@ -108,10 +111,10 @@ <para>The first two lines prepare the Hibernate Validator for class checking. The first one relies upon the error messages embedded in - Hibernate Validator (see <xref linkend="validator-defineconstraints-error" />), - the second one uses a resource bundle for these messages. It is considered - a good practice to execute these lines once and cache the validator - instances.</para> + Hibernate Validator (see <xref + linkend="validator-defineconstraints-error" />), the second one uses a + resource bundle for these messages. It is considered a good practice to + execute these lines once and cache the validator instances.</para> <para>The third line actually validates the <literal>Address</literal> instance and returns an array of <literal>InvalidValue</literal>s. Your @@ -162,8 +165,8 @@ additional JSF tags, again without validation definition duplication.</para> - <para>Check the <ulink url="http://www.jboss.com/products/seam">JBoss Seam</ulink> - documentation for more information.</para> + <para>Check the <ulink url="http://www.jboss.com/products/seam">JBoss + Seam</ulink> documentation for more information.</para> </section> <section> Modified: branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml =================================================================== --- branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml 2007-02-28 02:06:13 UTC (rev 11248) +++ branches/Branch_3_2/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml 2007-03-01 08:29:34 UTC (rev 11249) @@ -12,7 +12,7 @@ element.</para> </section> - <section id="validator-defineconstraints-builtin" revision="1"> + <section id="validator-defineconstraints-builtin" revision="2"> <title>Built in constraints</title> <para>Hibernate Validator comes with some built-in constraints, which @@ -112,7 +112,8 @@ </row> <row> - <entry>@Pattern(regex="regexp", flag=)</entry> + <entry>@Pattern(regex="regexp", flag=) or @Patterns( + {@Pattern(...)} )</entry> <entry>property (string)</entry> @@ -191,6 +192,54 @@ <entry>none</entry> </row> + + <row> + <entry>@CreditCardNumber</entry> + + <entry>property (String)</entry> + + <entry>check whether the string is a well formated credit card + number (derivative of the Luhn algorithm)</entry> + + <entry>none</entry> + </row> + + <row> + <entry>@Digits</entry> + + <entry>property (numeric or string representation of a + numeric)</entry> + + <entry>check whether the property is a number having up to + <literal>integerDigits</literal> integer digits and + <literal>fractionalDigits</literal> fractonal digits</entry> + + <entry>define column precision and scale</entry> + </row> + + <row> + <entry>@EAN</entry> + + <entry>property (string)</entry> + + <entry>check whether the string is a properly formated EAN or + UPC-A code</entry> + + <entry>none</entry> + </row> + + <row> + <entry>@Digits</entry> + + <entry>property (numeric or string representation of a + numeric)</entry> + + <entry>check whether the property is a number having up to + <literal>integerDigits</literal> integer digits and + <literal>fractionalDigits</literal> fractonal digits</entry> + + <entry>define column precision and scale</entry> + </row> </tbody> </tgroup> </table> @@ -217,7 +266,7 @@ JavaDoc for more informations).</para> </section> - <section> + <section id="validator-defineconstraints-own" revision="1"> <title>Writing your own constraints</title> <para>Extending the set of built-in constraints is extremely easy. Any @@ -247,7 +296,8 @@ <literal>Capitalization is not {type}</literal> would generate <literal>Capitalization is not FIRST</literal> ), externalizing the whole string in <filename>ValidatorMessages.properties</filename> is considered - good practice. See <xref linkend="validator-defineconstraints-error" /> .</para> + good practice. See <xref linkend="validator-defineconstraints-error" /> + .</para> <programlisting&gt;(a)ValidatorClass(CapitalizedValidator.class) @Target(METHOD) @@ -311,6 +361,28 @@ of a property, the bean itself will be passed to the validator. To activate the validation checking, just annotated the bean itself instead. A small sample can be found in the unit test suite.</para> + + <para>If your constraint can be applied multiple times (with different + parameters) on the same property or type, you can use the following + annotation form:</para> + + <programlisting>@Target(METHOD) +@Retention(RUNTIME) +@Documented +<emphasis role="bold">public @interface Patterns {</emphasis> + Pattern[] value(); +} + +@Target(METHOD) +@Retention(RUNTIME) +@Documented +(a)ValidatorClass(PatternValidator.class) +public @interface Pattern { + String regexp(); +}</programlisting> + + <para>Basically an annotation containing the value attribute as an array + of validator annotations.</para> </section> <section>