[hibernate-commits] Hibernate SVN: r11165 - branches/HAN_SPLIT/HibernateExt/metadata/doc/reference/en/modules.

[hibernate-commits at lists.jboss.org]

Author: epbernard
Date: 2007-02-07 18:01:44 -0500 (Wed, 07 Feb 2007)
New Revision: 11165

Added:
   branches/HAN_SPLIT/HibernateExt/metadata/doc/reference/en/modules/additionalmodules.xml
Log:
oups missing module doc

Added: branches/HAN_SPLIT/HibernateExt/metadata/doc/reference/en/modules/additionalmodules.xml
===================================================================
--- branches/HAN_SPLIT/HibernateExt/metadata/doc/reference/en/modules/additionalmodules.xml	                        (rev 0)
+++ branches/HAN_SPLIT/HibernateExt/metadata/doc/reference/en/modules/additionalmodules.xml	2007-02-07 23:01:44 UTC (rev 11165)
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="additionalmodules">
+  <title>Additional modules</title>
+
+  <para>Hibernate Annotations mainly focus on persistence metadata. The
+  project also have a nice integration with two Hibernate modules.</para>
+
+  <section>
+    <title>Hibernate Validator</title>
+
+    <section>
+      <title>Description</title>
+
+      <para>Annotations are a very convenient and elegant way to specify
+      invariant constraints for a domain model. You can, for example, express
+      that a property should never be null, that the account balance should be
+      strictly positive, etc. These domain model constraints are declared in
+      the bean itself by annotating its properties. A validator can then read
+      them and check for constraint violations. The validation mechanism can
+      be executed in different layers in your application without having to
+      duplicate any of these rules (presentation layer, data access layer).
+      Following the DRY principle, Hibernate Validator has been designed for
+      that purpose.</para>
+
+      <para>Hibernate Validator works at two levels. First, it is able to
+      check in-memory instances of a class for constraint violations. Second,
+      it can apply the constraints to the Hibernate metamodel and incorporate
+      them into the generated database schema.</para>
+
+      <para>Each constraint annotation is associated to a validator
+      implementation responsible for checking the constraint on the entity
+      instance. A validator can also (optionally) apply the constraint to the
+      Hibernate metamodel, allowing Hibernate to generate DDL that expresses
+      the constraint. With the appropriate event listener, you can execute the
+      checking operation on inserts and updates done by Hibernate. Hibernate
+      Validator is not limited to use with Hibernate. You can easily use it
+      anywhere in your application.</para>
+
+      <para>When checking instances at runtime, Hibernate Validator returns
+      information about constraint violations in an array of
+      <classname>InvalidValue</classname> s. Among other information, the
+      <classname>InvalidValue</classname> contains an error description
+      message that can embed the parameter values bundle with the annotation
+      (eg. length limit), and message strings that may be externalized to a
+      <classname>ResourceBundle</classname> .</para>
+    </section>
+
+    <section>
+      <title>Integration with Hibernate Annotations</title>
+
+      <para>If Hibernate Validator
+      (<filename>hibernate-validator.jar</filename>) is available in the
+      classpath, Hibernate Annotations will integrates in two ways: </para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Constraints will be applied to the Data Definition Language.
+          In other words, the database schema will reflect the constraints
+          (provided that you use the hbm2ddl tool).</para>
+        </listitem>
+
+        <listitem>
+          <para>Before an entity change is applied to the database (insert or
+          update), the entity is validated. Validation errors, if any, will be
+          carried over through an
+          <classname>InvalidStateException</classname>.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>For entities free of validation rules, the runtime performance
+      cost is null.</para>
+
+      <para>To disable constraint propagation to DDL, set up
+      <literal>hibernate.validator.apply_to_ddl</literal> to false in the
+      configuration file. Such a need is very uncommon and not
+      recommanded.</para>
+    </section>
+  </section>
+
+  <section>
+    <title>Hibernate Search</title>
+
+    <section>
+      <title>Decription</title>
+
+      <para>Full text search engines like <productname>Apache
+      Lucene</productname> are a very powerful technology to bring free
+      text/efficient queries to applications. If suffers several mismatches
+      when dealing with a object domain model (keeping the index up to date,
+      mismatch between the index structure and the domain model, querying
+      mismatch...) Hibernate Search indexes your domain model thanks to a few
+      annotations, takes care of the database / index synchronization and
+      brings you back regular managed objects from free text queries.
+      Hibernate Search is using <ulink url="http://lucene.apache.org">Apache
+      Lucene</ulink> under the cover.</para>
+    </section>
+
+    <section>
+      <title>Integration with Hibernate Annotations</title>
+
+      <para>Hibernate Search integrates with Hibernate Annotations through
+      Hibernate event listeners definitions, please check the Hibernate Search
+      reference documentation for more information.</para>
+    </section>
+  </section>
+</chapter>
\ No newline at end of file