Hibernate example source code file (additionalmodules.xml)

This example Hibernate source code file (additionalmodules.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Hibernate tags/keywords

bean, bean, hibernate, hibernate, lesser, license, public, search, search, this, validation, validation, validator, xml

The Hibernate additionalmodules.xml source code

<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ Hibernate, Relational Persistence for Idiomatic Java
  ~
  ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
  ~ indicated by the @author tags or express copyright attribution
  ~ statements applied by the authors.  All third-party contributions are
  ~ distributed under license by Red Hat Middleware LLC.
  ~
  ~ This copyrighted material is made available to anyone wishing to use, modify,
  ~ copy, or redistribute it subject to the terms and conditions of the GNU
  ~ Lesser General Public License, as published by the Free Software Foundation.
  ~
  ~ This program is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="additionalmodules">
  <title>Additional modules

  <para>Hibernate Core also offers integration with some external
  modules/projects. This includes Hibernate Validator the reference
  implementation of Bean Validation (JSR 303) and Hibernate Search. </para>

  <section>
    <title>Bean Validation

    <para>Bean Validation standardizes how to define and declare domain model
    level constraints. 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. Bean Validation 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, Bean Validation and its reference implementation Hibernate
    Validator has been designed for that purpose.</para>

    <para>The integration between Hibernate and Bean Validation 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, updates and deletes done by
    Hibernate.</para>

    <para>When checking instances at runtime, Hibernate Validator returns
    information about constraint violations in a set of
    <classname>ConstraintViolations. Among other information, the
    <classname>ConstraintViolation contains an error description
    message that can embed the parameter values bundle with the annotation
    (eg. size limit), and message strings that may be externalized to a
    <classname>ResourceBundle.

    <section>
      <title>Adding Bean Validation

      <para>To enable Hibernate's Bean Validation integration, simply add a
      Bean Validation provider (preferably Hibernate Validation 4) on your
      classpath.</para>
    </section>

    <section>
      <title>Configuration

      <para>By default, no configuration is necessary.

      <para>The Default group is validated on entity
      insert and update and the database model is updated accordingly based on
      the <classname>Default group as well.

      <para>You can customize the Bean Validation integration by setting the
      validation mode. Use the
      <literal>javax.persistence.validation.mode property and set it
      up for example in your <filename>persistence.xml file or your
      <filename>hibernate.cfg.xml file. Several options are
      possible:</para>

      <itemizedlist>
        <listitem>
          <para>auto (default): enable integration between
          Bean Validation and Hibernate (callback and ddl generation) only if
          Bean Validation is present in the classpath.</para>
        </listitem>

        <listitem>
          <para>none: disable all integration between Bean
          Validation and Hibernate</para>
        </listitem>

        <listitem>
          <para>callback: only validate entities when they
          are either inserted, updated or deleted. An exception is raised if
          no Bean Validation provider is present in the classpath.</para>
        </listitem>

        <listitem>
          <para>ddl: only apply constraints to the database
          schema when generated by Hibernate. An exception is raised if no
          Bean Validation provider is present in the classpath. This value is
          not defined by the Java Persistence spec and is specific to
          Hibernate.</para>
        </listitem>
      </itemizedlist>

      <note>
        <para>You can use both callback and
        <literal>ddl together by setting the property to
        <literal>callback, dll

        <programlisting language="XML" role="XML"><persistence ...>
  <persistence-unit ...>
    ...
    <properties>
      <property name="javax.persistence.validation.mode"
                value="callback, ddl"/>
    </properties>
  </persistence-unit>
</persistence></programlisting>

        <para>This is equivalent to auto except that if no
        Bean Validation provider is present, an exception is raised.</para>
      </note>

      <para>If you want to validate different groups during insertion, update
      and deletion, use:</para>

      <itemizedlist>
        <listitem>
          <para>javax.persistence.validation.group.pre-persist:
          groups validated when an entity is about to be persisted (default to
          <classname>Default)
        </listitem>

        <listitem>
          <para>javax.persistence.validation.group.pre-update:
          groups validated when an entity is about to be updated (default to
          <classname>Default)
        </listitem>

        <listitem>
          <para>javax.persistence.validation.group.pre-remove:
          groups validated when an entity is about to be deleted (default to
          no group)</para>
        </listitem>

        <listitem>
          <para>org.hibernate.validator.group.ddl: groups
          considered when applying constraints on the database schema (default
          to <classname>Default)
        </listitem>
      </itemizedlist>

      <para>Each property accepts the fully qualified class names of the
      groups validated separated by a comma (,)</para>

      <example>
        <title>Using custom groups for validation

        <programlisting language="XML" role="XML"><persistence ...>
  <persistence-unit ...>
    ...
    <properties>
      <property name="javax.persistence.validation.group.pre-update"
                value="javax.validation.group.Default, com.acme.group.Strict"/>
      <property name="javax.persistence.validation.group.pre-remove"
                value="com.acme.group.OnDelete"/>
      <property name="org.hibernate.validator.group.ddl"
                value="com.acme.group.DDL"/>
    </properties>
  </persistence-unit>
</persistence></programlisting>
      </example>

      <note>
        <para>You can set these properties in
        <filename>hibernate.cfg.xml,
        <filename>hibernate.properties or programmatically.
      </note>
    </section>

    <section>
      <title>Catching violations

      <para>If an entity is found to be invalid, the list of constraint
      violations is propagated by the
      <classname>ConstraintViolationException which exposes the
      set of <classname>ConstraintViolations.

      <para>This exception is wrapped in a
      <classname>RollbackException when the violation happens at
      commit time. Otherwise the
      <classname>ConstraintViolationException is returned (for
      example when calling <methodname>flush(). Note that
      generally, catchable violations are validated at a higher level (for
      example in Seam / JSF 2 via the JSF - Bean Validation integration or in
      your business layer by explicitly calling Bean Validation).</para>

      <para>An application code will rarely be looking for a
      <classname>ConstraintViolationException raised by Hibernate.
      This exception should be treated as fatal and the persistence context
      should be discarded (<classname>EntityManager or
      <classname>Session).
    </section>

    <section>
      <title>Database schema

      <para>Hibernate uses Bean Validation constraints to generate an accurate
      database schema:</para>

      <itemizedlist>
        <listitem>
          <para>@NotNull leads to a not null column
          (unless it conflicts with components or table inheritance)</para>
        </listitem>

        <listitem>
          <para>@Size.max leads to a
          <literal>varchar(max) definition for Strings
        </listitem>

        <listitem>
          <para>@Min, @Max lead
          to column checks (like <code>value <= max)
        </listitem>

        <listitem>
          <para>@Digits leads to the definition of
          precision and scale (ever wondered which is which? It's easy now
          with <classname>@Digits :) )
        </listitem>
      </itemizedlist>

      <para>These constraints can be declared directly on the entity
      properties or indirectly by using constraint composition.</para>

      <para>For more information check the Hibernate Validator 
    </section>
  </section>

  <section>
    <title>Hibernate Search

    <section>
      <title>Description

      <para>Full text search engines like 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.
    </section>

    <section>
      <title>Integration with Hibernate Annotations

      <para>Hibernate Search integrates with Hibernate Core transparently
      provided that the Hibernate Search jar is present on the classpath. If
      you do not wish to automatically register Hibernate Search event
      listeners, you can set
      <literal>hibernate.search.autoregister_listeners to false.
      Such a need is very uncommon and not recommended.</para>

      <para>Check the Hibernate Search 
    </section>
  </section>
</chapter>