[hibernate-commits] Hibernate SVN: r11249 - in branches/Branch_3_2/HibernateExt: annotations/src/java/org/hibernate/annotations and 2 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Thu Mar 1 03:29:34 EST 2007
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>@org.hibernate.annotations.Table</literal>.</para>
</note>
+ <para><literal>@org.hibernate.annotations.Table</literal> 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
- at 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
+ at Inheritance(strategy = InheritanceType.JOINED)
+public abstract class File { ... }
+
+ at Entity
+ at 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>@org.hibernate.annotations.Table</literal> and either (or
+ all) attributes <literal>sqlInsert</literal>,
+ <literal>sqlUpdate</literal>, <literal>sqlDelete</literal>:</para>
+
+ <programlisting>@Entity
+ at SecondaryTables({
+ @SecondaryTable(name = "`Cat nbr1`"),
+ @SecondaryTable(name = "Cat2"})
+ at 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>@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)
+ at Retention(RUNTIME)
+ at Documented
+<emphasis role="bold">public @interface Patterns {</emphasis>
+ Pattern[] value();
+}
+
+ at Target(METHOD)
+ at Retention(RUNTIME)
+ at Documented
+ at 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>
More information about the hibernate-commits
mailing list