[hibernate-commits] Hibernate SVN: r11155 - in
branches/HAN_SPLIT/HibernateExt/validator/doc/reference: en
and 1 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Feb 6 00:51:21 EST 2007
Author: epbernard
Date: 2007-02-06 00:51:21 -0500 (Tue, 06 Feb 2007)
New Revision: 11155
Added:
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/build.xml
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml
Removed:
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/entity.xml
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/lucene.xml
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/setup.xml
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/validator.xml
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/xml-overriding.xml
Modified:
branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/master.xml
Log:
Standalone validator documentation
Added: branches/HAN_SPLIT/HibernateExt/validator/doc/reference/build.xml
===================================================================
--- branches/HAN_SPLIT/HibernateExt/validator/doc/reference/build.xml (rev 0)
+++ branches/HAN_SPLIT/HibernateExt/validator/doc/reference/build.xml 2007-02-06 05:51:21 UTC (rev 11155)
@@ -0,0 +1,17 @@
+<project name="Documentation" default="all.doc" basedir=".">
+
+ <!-- Use the core Hibernate3 doc build system -->
+ <import file="../../../common/common-build.xml"/>
+ <import file="${hibernate-cvs.doc.reference}/build.xml"/>
+
+
+ <target name="all.doc" depends="clean">
+
+ <!-- TRANSLATOR: Duplicate this call for your language -->
+ <antcall target="lang.all">
+ <param name="docname" value="hibernate_validator"/>
+ <param name="lang" value="en"/>
+ </antcall>
+ </target>
+
+</project>
Modified: branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/master.xml
===================================================================
--- branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/master.xml 2007-02-05 23:37:37 UTC (rev 11154)
+++ branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/master.xml 2007-02-06 05:51:21 UTC (rev 11155)
@@ -1,79 +1,69 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
-"../../../../../Hibernate3/doc/reference/support/docbook-dtd/docbookx.dtd" [
-<!ENTITY setup SYSTEM "modules/setup.xml">
-<!ENTITY entity SYSTEM "modules/entity.xml">
-<!ENTITY xml-overriding SYSTEM "modules/xml-overriding.xml">
-<!ENTITY validator SYSTEM "modules/validator.xml">
-<!ENTITY lucene SYSTEM "modules/lucene.xml">
-]>
+ "../../../../../Hibernate3/doc/reference/support/docbook-dtd/docbookx.dtd" [
+ <!ENTITY defineconstraints SYSTEM "modules/defineconstraints.xml">
+ <!ENTITY checkconstraints SYSTEM "modules/checkconstraints.xml">
+ ]>
<book lang="en">
- <bookinfo>
- <title>Hibernate Annotations</title>
+ <bookinfo>
+ <title>Hibernate Validator</title>
- <subtitle>Reference Guide</subtitle>
+ <subtitle>Reference Guide</subtitle>
- <releaseinfo>3.2.1.GA</releaseinfo>
+ <releaseinfo>3.2.2.GA</releaseinfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/hibernate_logo_a.png" format="png" />
- </imageobject>
- </mediaobject>
- </bookinfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/hibernate_logo_a.png" format="png"/>
+ </imageobject>
+ </mediaobject>
+ </bookinfo>
- <toc></toc>
+ <toc></toc>
- <preface id="preface" revision="1">
- <title>Preface</title>
+ <preface id="preface" revision="1">
+ <title>Preface</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, like all other object/relational mapping tools, requires
- metadata that governs the transformation of data from one representation
- to the other (and vice versa). In Hibernate 2.x, mapping metadata is most
- of the time declared in XML text files. Another option is XDoclet,
- utilizing Javadoc source code annotations and a preprocessor at compile
- time. The same kind of annotation support is now available in the standard
- JDK, although more powerful and better supported by tools. IntelliJ IDEA,
- and Eclipse for example, support auto-completion and syntax highlighting
- of JDK 5.0 annotations. Annotations are compiled into the bytecode and
- read at runtime (in Hibernate's case on startup) using reflection, so no
- external XML files are needed.</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>The EJB3 specification recognizes the interest and the success of
- the transparent object/relational mapping paradigm. The EJB3 specification
- standardizes the basic APIs and the metadata needed for any
- object/relational persistence mechanism. <emphasis>Hibernate
- EntityManager</emphasis> implements the programming interfaces and
- lifecycle rules as defined by the EJB3 persistence specification. Together
- with <emphasis>Hibernate Annotations</emphasis>, this wrapper implements a
- complete (and standalone) EJB3 persistence solution on top of the mature
- Hibernate core. You may use a combination of all three together,
- annotations without EJB3 programming interfaces and lifecycle, or even
- pure native Hibernate, depending on the business and technical needs of
- your project. You can at all times fall back to Hibernate native APIs, or
- if required, even to native JDBC and SQL.</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>This release is based on the final release of the EJB 3.0 / JPA
- specification (aka JSP-220) and support all the specification features
- (including the optional ones). Most of the Hibernate features and
- extensions are also available through Hibernate specific annotations
- compared to the specification are also available. While the Hibernate
- feature coverage is now very high, some are still missing. The eventual
- goal is to cover all of them. See the JIRA road map section for more
- informations.</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>
+ </preface>
- <para>If you are moving from previous Hibernate Annotations versions,
- please have a look at <uri>http://www.hibernate.org/371.html</uri> for a
- migration guide.</para>
- </preface>
+ &defineconstraints;
+ &checkconstraints;
- &setup;
-
- &entity;
-
- &xml-overriding;
-
- &validator;
-
- &lucene;
</book>
\ No newline at end of file
Copied: branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml (from rev 11154, branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/validator.xml)
===================================================================
--- branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml (rev 0)
+++ branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/checkconstraints.xml 2007-02-06 05:51:21 UTC (rev 11155)
@@ -0,0 +1,197 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="validator-checkconstraints">
+ <title>Using the Validator framework</title>
+
+ <para>Hibernate Validator is intended to be used to implement multi-layered
+ data validation, where constraints are expressed in a single place (the
+ annotated domain model) and checked in various different layers of the
+ application.</para>
+
+ <para>This chapter will cover Hibernate Validator usage for different
+ layers</para>
+
+ <section id="validator-checkconstraints-db" revision="1">
+ <title>Database schema-level validation</title>
+
+ <para>Out of the box, Hibernate Annotations will translate the constraints
+ you have defined for your entities into mapping metadata. For example, if
+ a property of your entity is annotated <literal>@NotNull</literal>, its
+ columns will be declared as <literal>not null</literal> in the DDL schema
+ generated by Hibernate.</para>
+
+ <para>Using hbm2ddl, domain model constraints will be expressed into the
+ database schema.</para>
+ </section>
+
+ <section id="validator-checkconstraints-orm">
+ <title>ORM integration</title>
+
+ <para>Hibernate Validator integrates with both Hibernate and all pure Java
+ Persistence providers</para>
+
+ <section id="validator-checkconstraints-orm-hibernateevent" revision="1">
+ <title>Hibernate event-based validation</title>
+
+ <para>Hibernate Validator has two built-in Hibernate event listeners.
+ Whenever a <literal>PreInsertEvent</literal> or
+ <literal>PreUpdateEvent</literal> occurs, the listeners will verify all
+ constraints of the entity instance and throw an exception if any
+ constraint is violated. Basically, objects will be checked before any
+ inserts and before any updates made by Hibernate. This includes changes
+ applied by cascade! This is the most convenient and the easiest way to
+ activate the validation process. On constraint violation, the event will
+ raise a runtime <classname>InvalidStateException</classname> which
+ contains an array of <literal>InvalidValue</literal>s describing each
+ failure.</para>
+
+ <programlisting><hibernate-configuration>
+ ...
+ <event type="pre-update">
+ <listener
+ class="org.hibernate.validator.event.ValidateEventListener"/>
+ </event>
+ <event type="pre-insert">
+ <listener
+ class="org.hibernate.validator.event.ValidateEventListener"/>
+ </event>
+</hibernate-configuration></programlisting>
+
+ <para><note>
+ <para>When using Hibernate Entity Manager, the Validation framework
+ is activated out of the box. If the beans are not annotated with
+ validation annotations, there is no performance cost.</para>
+ </note></para>
+ </section>
+
+ <section id="validator-checkconstraints-orm-jpaevent">
+ <title>Java Persistence event-based validation</title>
+
+ <para>Hibernate Validator is not tied to Hibernate for event based
+ validation: a Java Persistence entity listener is available. Whenever an
+ listened entity is persisted or updated, Hibernate Validator will verify
+ all constraints of the entity instance and throw an exception if any
+ constraint is violated. Basically, objects will be checked before any
+ inserts and before any updates made by the Java Persistence provider.
+ This includes changes applied by cascade! On constraint violation, the
+ event will raise a runtime <classname>InvalidStateException</classname>
+ which contains an array of <literal>InvalidValue</literal>s describing
+ each failure.</para>
+
+ <para>Here is how to make a class validatable:</para>
+
+ <programlisting>@Entity
+ at EntityListeners( JPAValidateListener.class )
+public class Submarine {
+ ...
+}
+}</programlisting>
+
+ <para><note>
+ <para>Compared to the Hibernate event, the Java Persistence listener
+ has two drawbacks. You need to define the entity listener on every
+ validatable entity. The DDL generated by your provider will not
+ reflect the constraints.</para>
+ </note></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Application-level validation</title>
+
+ <para>Hibernate Validator can be applied anywhere in your application
+ code.</para>
+
+ <programlisting>ClassValidator personValidator = new ClassValidator( Person.class );
+ClassValidator addressValidator = new ClassValidator( Address.class, ResourceBundle.getBundle("messages", Locale.ENGLISH) );
+
+InvalidValue[] validationMessages = addressValidator.getInvalidValues(address);</programlisting>
+
+ <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>
+
+ <para>The third line actually validates the <literal>Address</literal>
+ instance and returns an array of <literal>InvalidValue</literal>s. Your
+ application logic will then be able to react to the failure.</para>
+
+ <para>You can also check a particular property instead of the whole bean.
+ This might be useful for property per property user interaction</para>
+
+ <programlisting>ClassValidator addressValidator = new ClassValidator( Address.class, ResourceBundle.getBundle("messages", Locale.ENGLISH) );
+
+//only get city property invalid values
+InvalidValue[] validationMessages = addressValidator.getInvalidValues(address, "city");
+
+//only get potential city property invalid values
+InvalidValue[] validationMessages = addressValidator.getPotentialInvalidValues("city", "Paris")</programlisting>
+ </section>
+
+ <section>
+ <title>Presentation layer validation</title>
+
+ <para>When working with JSF and <productname>JBoss Seam</productname>, one
+ can triggers the validation process at the presentation layer using Seam's
+ JSF tags <literal><s:validate></literal> and
+ <literal><s:validateAll/></literal>, letting the constraints be
+ expressed on the model, and the violations presented in the view</para>
+
+ <programlisting><h:form>
+ <div>
+ <h:messages/>
+ </div>
+ <emphasis role="bold"><s:validateAll></emphasis>
+ <div>
+ Country:
+ <h:inputText value="#{location.country}" required="true"/>
+ </div>
+ <div>
+ Zip code:
+ <h:inputText value="#{location.zip}" required="true"/>
+ </div>
+ <div>
+ <h:commandButton/>
+ </div>
+ <emphasis role="bold"></s:validateAll></emphasis>
+</h:form></programlisting>
+
+ <para>Going even further, and adding <productname>Ajax4JSF</productname>
+ to the loop will bring client side validation with just a couple of
+ 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>
+ </section>
+
+ <section>
+ <title>Validation informations</title>
+
+ <para>As a validation information carrier, hibernate provide an array of
+ <classname>InvalidValue</classname>. Each <literal>InvalidValue</literal>
+ has a buch of methods describing the individual issues.</para>
+
+ <para><methodname>getBeanClass()</methodname> retrieves the failing bean
+ type</para>
+
+ <para><methodname>getBean()</methodname>retrieves the failing instance (if
+ any ie not when using
+ <methodname>getPotentianInvalidValues()</methodname>)</para>
+
+ <para><methodname>getValue()</methodname> retrieves the failing
+ value</para>
+
+ <para><methodname>getMessage()</methodname> retrieves the proper
+ internationalized error message</para>
+
+ <para><methodname>getRootBean()</methodname> retrieves the root bean
+ instance generating the issue (useful in conjunction with
+ <literal>@Valid</literal>), is null if getPotentianInvalidValues() is
+ used.</para>
+
+ <para><literal>getPropertyPath()</literal> retrieves the dotted path of
+ the failing property starting from the root bean</para>
+ </section>
+</chapter>
\ No newline at end of file
Copied: branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml (from rev 11154, branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/validator.xml)
===================================================================
--- branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml (rev 0)
+++ branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml 2007-02-06 05:51:21 UTC (rev 11155)
@@ -0,0 +1,409 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="validator-defineconstraints">
+ <title>Defining constraints</title>
+
+ <section id="validator-defineconstraints-definition" revision="1">
+ <title>What is a constraint?</title>
+
+ <para>A constraint is a rule that a given element (field, property or
+ bean) has to comply to. The rule semantic is expressed by an annotation. A
+ constraint usually has some attributes used to parameterize the
+ constraints limits. The constraint applies to the annotated
+ element.</para>
+ </section>
+
+ <section id="validator-defineconstraints-builtin" revision="1">
+ <title>Built in constraints</title>
+
+ <para>Hibernate Validator comes with some built-in constraints, which
+ covers most basic data checks. As we'll see later, you're not limited to
+ them, you can literally in a minute write your own constraints.</para>
+
+ <table>
+ <title>Built-in constraints</title>
+
+ <tgroup cols="4">
+ <colspec align="center" />
+
+ <thead>
+ <row>
+ <entry>Annotation</entry>
+
+ <entry>Apply on</entry>
+
+ <entry>Runtime checking</entry>
+
+ <entry>Hibernate Metadata impact</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>@Length(min=, max=)</entry>
+
+ <entry>property (String)</entry>
+
+ <entry>check if the string length match the range</entry>
+
+ <entry>Column length will be set to max</entry>
+ </row>
+
+ <row>
+ <entry>@Max(value=)</entry>
+
+ <entry>property (numeric or string representation of a
+ numeric)</entry>
+
+ <entry>check if the value is less than or equals to max</entry>
+
+ <entry>Add a check constraint on the column</entry>
+ </row>
+
+ <row>
+ <entry>@Min(value=)</entry>
+
+ <entry>property (numeric or string representation of a
+ numeric)</entry>
+
+ <entry>check if the value is more than or equals to min</entry>
+
+ <entry>Add a check constraint on the column</entry>
+ </row>
+
+ <row>
+ <entry>@NotNull</entry>
+
+ <entry>property</entry>
+
+ <entry>check if the value is not null</entry>
+
+ <entry>Column(s) are not null</entry>
+ </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>
+
+ <entry>check if the date is in the past</entry>
+
+ <entry>Add a check constraint on the column</entry>
+ </row>
+
+ <row>
+ <entry>@Future</entry>
+
+ <entry>property (date or calendar)</entry>
+
+ <entry>check if the date is in the future</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry>@Pattern(regex="regexp", flag=)</entry>
+
+ <entry>property (string)</entry>
+
+ <entry>check if the property match the regular expression given a
+ match flag (see <classname>java.util.regex.Pattern </classname>
+ )</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry>@Range(min=, max=)</entry>
+
+ <entry>property (numeric or string representation of a
+ numeric)</entry>
+
+ <entry>check if the value is between min and max
+ (included)</entry>
+
+ <entry>Add a check constraint on the column</entry>
+ </row>
+
+ <row>
+ <entry>@Size(min=, max=)</entry>
+
+ <entry>property (array, collection, map)</entry>
+
+ <entry>check if the element size is between min and max
+ (included)</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry>@AssertFalse</entry>
+
+ <entry>property</entry>
+
+ <entry>check that the method evaluates to false (useful for
+ constraints expressed in code rather than annotations)</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry>@AssertTrue</entry>
+
+ <entry>property</entry>
+
+ <entry>check that the method evaluates to true (useful for
+ constraints expressed in code rather than annotations)</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry>@Valid</entry>
+
+ <entry>property (object)</entry>
+
+ <entry>perform validation recursively on the associated object. If
+ the object is a Collection or an array, the elements are validated
+ recursively. If the object is a Map, the value elements are
+ validated recursively.</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry>@Email</entry>
+
+ <entry>property (String)</entry>
+
+ <entry>check whether the string is conform to the email address
+ specification</entry>
+
+ <entry>none</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="validator-defineconstraints-error" xreflabel="Error messages">
+ <title>Error messages</title>
+
+ <para>Hibernate Validator comes with a default set of error messages
+ translated in about ten languages (if yours is not part of it, please sent
+ us a patch). You can override those messages by creating a
+ <filename>ValidatorMessages.properties</filename> or (
+ <filename>ValidatorMessages_loc.properties</filename> ) and override the
+ needed keys. You can even add your own additional set of messages while
+ writing your validator annotations. If Hibernate Validator cannot resolve
+ a key from your resourceBundle nor from ValidatorMessage, it falls back to
+ the default built-in values.</para>
+
+ <para>Alternatively you can provide a
+ <classname>ResourceBundle</classname> while checking programmatically the
+ validation rules on a bean or if you want a completly different
+ interpolation mechanism, you can provide an implementation of
+ <literal>org.hibernate.validator.MessageInterpolator</literal> (check the
+ JavaDoc for more informations).</para>
+ </section>
+
+ <section>
+ <title>Writing your own constraints</title>
+
+ <para>Extending the set of built-in constraints is extremely easy. Any
+ constraint consists of two pieces: the constraint
+ <emphasis>descriptor</emphasis> (the annotation) and the constraint
+ <emphasis>validator</emphasis> (the implementation class). Here is a
+ simple user-defined descriptor:</para>
+
+ <programlisting>@ValidatorClass(CapitalizedValidator.class)
+ at Target(METHOD)
+ at Retention(RUNTIME)
+ at Documented
+public @interface Capitalized {
+ CapitalizeType type() default Capitalize.FIRST;
+ String message() default "has incorrect capitalization"
+} </programlisting>
+
+ <para><literal>type</literal> is a parameter describing how the property
+ should to be capitalized. This is a user parameter fully dependant on the
+ annotation business.</para>
+
+ <para><literal>message</literal> is the default string used to describe
+ the constraint violation and is mandatory. You can hard code the string or
+ you can externalize part/all of it through the Java ResourceBundle
+ mechanism. Parameters values are going to be injected inside the message
+ when the <literal>{parameter}</literal> string is found (in our example
+ <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>
+
+ <programlisting>@ValidatorClass(CapitalizedValidator.class)
+ at Target(METHOD)
+ at Retention(RUNTIME)
+ at Documented
+public @interface Capitalized {
+ CapitalizeType type() default Capitalize.FIRST;
+ String message() default "{validator.capitalized}";
+}
+
+
+#in ValidatorMessages.properties
+validator.capitalized = <literal>Capitalization is not {type}</literal>
+ </programlisting>
+
+ <para>As you can see the {} notation is recursive.</para>
+
+ <para>To link a descriptor to its validator implementation, we use the
+ <literal>@ValidatorClass</literal> meta-annotation. The validator class
+ parameter must name a class which implements
+ <literal>Validator<ConstraintAnnotation></literal> .</para>
+
+ <para>We now have to implement the validator (ie. the rule checking
+ implementation). A validation implementation can check the value of the a
+ property (by implementing <literal>PropertyConstraint</literal> ) and/or
+ can modify the hibernate mapping metadata to express the constraint at the
+ database level (by implementing
+ <literal>PersistentClassConstraint</literal> )</para>
+
+ <programlisting>public class CapitalizedValidator
+ implements Validator<Capitalized>, PropertyConstraint {
+ private CapitalizeType type;
+
+ //part of the Validator<Annotation> contract,
+ //allows to get and use the annotation values
+ public void initialize(Capitalized parameters) {
+ type = parameters.type();
+ }
+
+ //part of the property constraint contract
+ public boolean isValid(Object value) {
+ if (value==null) return true;
+ if ( !(value instanceof String) ) return false;
+ String string = (String) value;
+ if (type == CapitalizeType.ALL) {
+ return string.equals( string.toUpperCase() );
+ }
+ else {
+ String first = string.substring(0,1);
+ return first.equals( first.toUpperCase();
+ }
+ }
+} </programlisting>
+
+ <para>The <literal>isValid()</literal> method should return false if the
+ constraint has been violated. For more examples, refer to the built-in
+ validator implementations.</para>
+
+ <para>We only have seen property level validation, but you can write a
+ Bean level validation annotation. Instead of receiving the return instance
+ 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>
+ </section>
+
+ <section>
+ <title>Annotating your domain model</title>
+
+ <para>Since you are already familiar with annotations now, the syntax
+ should be very familiar</para>
+
+ <programlisting>public class Address {
+ private String line1;
+ private String line2;
+ private String zip;
+ private String state;
+ private String country;
+ private long id;
+
+ // a not null string of 20 characters maximum
+ @Length(max=20)
+ @NotNull
+ public String getCountry() {
+ return country;
+ }
+
+ // a non null string
+ @NotNull
+ public String getLine1() {
+ return line1;
+ }
+
+ //no constraint
+ public String getLine2() {
+ return line2;
+ }
+
+ // a not null string of 3 characters maximum
+ @Length(max=3) @NotNull
+ public String getState() {
+ return state;
+ }
+
+ // a not null numeric string of 5 characters maximum
+ // if the string is longer, the message will
+ //be searched in the resource bundle at key 'long'
+ @Length(max=5, message="{long}")
+ @Pattern(regex="[0-9]+")
+ @NotNull
+ public String getZip() {
+ return zip;
+ }
+
+ // should always be true
+ @AssertTrue
+ public boolean isValid() {
+ return true;
+ }
+
+ // a numeric between 1 and 2000
+ @Id @Min(1)
+ @Range(max=2000)
+ public long getId() {
+ return id;
+ }
+} </programlisting>
+
+ <para>While the example only shows public property validation, you can
+ also annotate fields of any kind of visibility</para>
+
+ <programlisting>@MyBeanConstraint(max=45
+public class Dog {
+ @AssertTrue private boolean isMale;
+ @NotNull protected String getName() { ... };
+ ...
+} </programlisting>
+
+ <para>You can also annotate interfaces. Hibernate Validator will check all
+ superclasses and interfaces extended or implemented by a given bean to
+ read the appropriate validator annotations.</para>
+
+ <programlisting>public interface Named {
+ @NotNull String getName();
+ ...
+}
+
+public class Dog implements Named {
+
+ @AssertTrue private boolean isMale;
+
+ public String getName() { ... };
+
+}
+ </programlisting>
+
+ <para>The name property will be checked for nullity when the Dog bean is
+ validated.</para>
+ </section>
+</chapter>
\ No newline at end of file
Property changes on: branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/defineconstraints.xml
___________________________________________________________________
Name: svn:keywords
+ Author Date Id Revision
Name: svn:eol-style
+ native
Deleted: branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/entity.xml
===================================================================
--- branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/entity.xml 2007-02-05 23:37:37 UTC (rev 11154)
+++ branches/HAN_SPLIT/HibernateExt/validator/doc/reference/en/modules/entity.xml 2007-02-06 05:51:21 UTC (rev 11155)
@@ -1,3432 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<chapter id="entity">
- <title>Entity Beans</title>
-
- <sect1 id="entity-overview" revision="1">
- <title>Intro</title>
-
- <para>This section covers EJB 3.0 (aka JPA) entity annotations and
- Hibernate-specific extensions.</para>
- </sect1>
-
- <sect1 id="entity-mapping" revision="2">
- <title>Mapping with EJB3/JPA Annotations</title>
-
- <para>EJB3 entities are plain POJOs. Actually they represent the exact
- same concept as the Hibernate persistent entities. Their mappings are
- defined through JDK 5.0 annotations (an XML descriptor syntax for
- overriding is defined in the EJB3 specification). Annotations can be split
- in two categories, the logical mapping annotations (allowing you to
- describe the object model, the class associations, etc.) and the physical
- mapping annotations (describing the physical schema, tables, columns,
- indexes, etc). We will mix annotations from both categories in the
- following code examples.</para>
-
- <para>EJB3 annotations are in the <literal>javax.persistence.*</literal>
- package. Most JDK 5 compliant IDE (like Eclipse, IntelliJ IDEA and
- Netbeans) can autocomplete annotation interfaces and attributes for you
- (even without a specific "EJB3" module, since EJB3 annotations are plain
- JDK 5 annotations).</para>
-
- <para>For more and runnable concrete examples read the JBoss EJB 3.0
- tutorial or review the Hibernate Annotations test suite. Most of the unit
- tests have been designed to represent a concrete example and be a
- inspiration source.</para>
-
- <sect2>
- <title>Declaring an entity bean</title>
-
- <para>Every bound persistent POJO class is an entity bean and is
- declared using the <literal>@Entity</literal> annotation (at the class
- level):</para>
-
- <programlisting>
- at Entity
-public class Flight implements Serializable {
- Long id;
-
- @Id
- public Long getId() { return id; }
-
- public void setId(Long id) { this.id = id; }
-}
- </programlisting>
-
- <para><literal>@Entity</literal> declares the class as an entity bean
- (i.e. a persistent POJO class), <literal>@Id</literal> declares the
- identifier property of this entity bean. The other mapping declarations
- are implicit. This configuration by exception concept is central to the
- new EJB3 specification and a major improvement. The class Flight is
- mapped to the Flight table, using the column id as its primary key
- column.</para>
-
- <para>Depending on whether you annotate fields or methods, the access
- type used by Hibernate will be <literal>field</literal> or
- <literal>property</literal>. The EJB3 spec requires that you declare
- annotations on the element type that will be accessed, i.e. the getter
- method if you use <literal>property</literal> access, the field if you
- use <literal>field</literal> access. Mixing EJB3 annotations in both
- fields and methods should be avoided. Hibernate will guess the access
- type from the position of <literal>@Id</literal> or
- <literal>@EmbeddedId</literal>.</para>
-
- <sect3>
- <title>Defining the table</title>
-
- <para><literal>@Table</literal> is set at the class level; it allows
- you to define the table, catalog, and schema names for your entity
- bean mapping. If no <literal>@Table</literal> is defined the default
- values are used: the unqualified class name of the entity.</para>
-
- <programlisting>
- at Entity
- at Table(name="tbl_sky")
-public class Sky implements Serializable {
-...
- </programlisting>
-
- <para>The <literal>@Table</literal> element also contains a
- <literal>schema</literal> and a <literal>catalog</literal> attributes,
- if they need to be defined. You can also define unique constraints to
- the table using the <literal>@UniqueConstraint</literal> annotation in
- conjunction with <literal>@Table</literal> (for a unique constraint
- bound to a single column, refer to <literal>@Column</literal>).</para>
-
- <programlisting>@Table(name="tbl_sky",
- <emphasis role="bold">uniqueConstraints = {@UniqueConstraint(columnNames={"month", "day"})}</emphasis>
-)</programlisting>
-
- <para>A unique constraint is applied to the tuple month, day. Note
- that the <literal>columnNames</literal> array refers to the logical
- column names.</para>
-
- <remark>The logical column name is defined by the Hibernate
- NamingStrategy implementation. The default EJB3 naming strategy use
- the physical column name as the logical column name. Note that this
- may be different than the property name (if the column name is
- explicit). Unless you override the NamingStrategy, you shouldn't worry
- about that.</remark>
- </sect3>
-
- <sect3>
- <title>Versioning for optimistic locking</title>
-
- <para>You can add optimistic locking capability to an entity bean
- using the <literal>@Version</literal> annotation:</para>
-
- <programlisting>
- at Entity
-public class Flight implements Serializable {
-...
- @Version
- @Column(name="OPTLOCK")
- public Integer getVersion() { ... }
-} </programlisting>
-
- <para>The version property will be mapped to the
- <literal>OPTLOCK</literal> column, and the entity manager will use it
- to detect conflicting updates (preventing lost updates you might
- otherwise see with the last-commit-wins strategy).</para>
-
- <para>The version column may be a numeric (the recommended solution)
- or a timestamp as per the EJB3 spec. Hibernate support any kind of
- type provided that you define and implement the appropriate
- <classname>UserVersionType</classname>.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Mapping simple properties</title>
-
- <sect3>
- <title>Declaring basic property mappings</title>
-
- <para>Every non static non transient property (field or method) of an
- entity bean is considered persistent, unless you annotate it as
- <literal>@Transient</literal>. Not having an annotation for your
- property is equivalent to the appropriate <literal>@Basic</literal>
- annotation. The <literal>@Basic</literal> annotation allows you to
- declare the fetching strategy for a property:</para>
-
- <programlisting>public transient int counter; //transient property
-
-private String firstname; //persistent property
-
- at Transient
-String getLengthInMeter() { ... } //transient property
-
-String getName() {... } // persistent property
-
- at Basic
-int getLength() { ... } // persistent property
-
- at Basic(fetch = FetchType.LAZY)
-String getDetailedComment() { ... } // persistent property
-
- at Temporal(TemporalType.TIME)
-java.util.Date getDepartureTime() { ... } // persistent property
-
- at Enumerated(STRING)
-Starred getNote() { ... } //enum persisted as String in database</programlisting>
-
- <para><literal>counter</literal>, a transient field, and
- <literal>lengthInMeter</literal>, a method annotated as
- <literal>@Transient</literal>, and will be ignored by the entity
- manager. <literal>name</literal>, <literal>length</literal>, and
- <literal>firstname</literal> properties are mapped persistent and
- eagerly fetched (the default for simple properties). The
- <literal>detailedComment</literal> property value will be lazily
- fetched from the database once a lazy property of the entity is
- accessed for the first time. Usually you don't need to lazy simple
- properties (not to be confused with lazy association fetching).</para>
-
- <note>
- <para>To enable property level lazy fetching, your classes have to
- be instrumented: bytecode is added to the original one to enable
- such feature, please refer to the Hibernate reference documentation.
- If your classes are not instrumented, property level lazy loading is
- silently ignored.</para>
- </note>
-
- <para>The recommended alternative is to use the projection capability
- of EJB-QL or Criteria queries.</para>
-
- <para>EJB3 support property mapping of all basic types supported by
- Hibernate (all basic Java types , their respective wrappers and
- serializable classes). Hibernate Annotations support out of the box
- Enum type mapping either into a ordinal column (saving the enum
- ordinal) or a string based column (saving the enum string
- representation): the persistence representation, defaulted to ordinal,
- can be overriden through the <literal>@Enumerated</literal> annotation
- as shown in the <literal>note</literal> property example.</para>
-
- <para>In core Java APIs, the temporal precision is not defined. When
- dealing with temporal data you might want to describe the expected
- precision in database. Temporal data can have <literal>DATE</literal>,
- <literal>TIME</literal>, or <literal>TIMESTAMP</literal> precision (ie
- the actual date, only the time, or both). Use the
- <literal>@Temporal</literal> annotation to fine tune that.</para>
-
- <para><literal>@Lob</literal> indicates that the property should be
- persisted in a Blob or a Clob depending on the property type:
- <classname>java.sql.Clob</classname>,
- <classname>Character[]</classname>, <classname>char[]</classname> and
- java.lang.<classname>String</classname> will be persisted in a Clob.
- <classname>java.sql.Blob</classname>, <classname>Byte[]</classname>,
- <classname>byte[] </classname>and serializable type will be persisted
- in a Blob.</para>
-
- <programlisting>
- at Lob
-public String getFullText() {
- return fullText;
-}
-
- at Lob
-public byte[] getFullCode() {
- return fullCode;
-}
- </programlisting>
-
- <para>If the property type implements
- <classname>java.io.Serializable</classname> and is not a basic type,
- and if the property is not annotated with <literal>@Lob</literal>,
- then the Hibernate <literal>serializable</literal> type is
- used.</para>
- </sect3>
-
- <sect3>
- <title>Declaring column attributes</title>
-
- <para>The column(s) used for a property mapping can be defined using
- the <literal>@Column</literal> annotation. Use it to override default
- values (see the EJB3 specification for more information on the
- defaults). You can use this annotation at the property level for
- properties that are:</para>
-
- <itemizedlist>
- <listitem>
- <para>not annotated at all</para>
- </listitem>
-
- <listitem>
- <para>annotated with <literal>@Basic</literal></para>
- </listitem>
-
- <listitem>
- <para>annotated with <literal>@Version</literal></para>
- </listitem>
-
- <listitem>
- <para>annotated with <literal>@Lob</literal></para>
- </listitem>
-
- <listitem>
- <para>annotated with <literal>@Temporal</literal></para>
- </listitem>
-
- <listitem>
- <para>annotated with
- <literal>@org.hibernate.annotations.CollectionOfElements</literal>
- (for Hibernate only)</para>
- </listitem>
- </itemizedlist>
-
- <programlisting>
- at Entity
-public class Flight implements Serializable {
-...
- at Column(updatable = false, name = "flight_name", nullable = false, length=50)
-public String getName() { ... }
- </programlisting>
-
- <para>The <literal>name</literal> property is mapped to the
- <literal>flight_name</literal> column, which is not nullable, has a
- length of 50 and is not updatable (making the property
- immutable).</para>
-
- <para>This annotation can be applied to regular properties as well as
- <literal>@Id</literal> or <literal>@Version</literal>
- properties.</para>
-
- <programlistingco>
- <areaspec>
- <area coords="2 55" id="hm1" />
-
- <area coords="3 55" id="hm2" />
-
- <area coords="4 55" id="hm3" />
-
- <area coords="5 55" id="hm4" />
-
- <area coords="6 55" id="hm5" />
-
- <area coords="7 55" id="hm6" />
-
- <area coords="8 55" id="hm7" />
-
- <area coords="9 55" id="hm8" />
-
- <area coords="10 55" id="hm9" />
-
- <area coords="11 55" id="hm10" />
- </areaspec>
-
- <programlisting>@Column(
- name="columnName";
- boolean unique() default false;
- boolean nullable() default true;
- boolean insertable() default true;
- boolean updatable() default true;
- String columnDefinition() default "";
- String table() default "";
- int length() default 255;
- int precision() default 0; // decimal precision
- int scale() default 0; // decimal scale</programlisting>
-
- <calloutlist>
- <callout arearefs="hm1">
- <para><literal>name</literal> (optional): the column name
- (default to the property name)</para>
- </callout>
-
- <callout arearefs="hm2">
- <para><literal>unique</literal> (optional): set a unique
- constraint on this column or not (default false)</para>
- </callout>
-
- <callout arearefs="hm3">
- <para><literal>nullable</literal> (optional): set the column as
- nullable (default false).</para>
- </callout>
-
- <callout arearefs="hm4">
- <para><literal>insertable</literal> (optional): whether or not
- the column will be part of the insert statement (default
- true)</para>
- </callout>
-
- <callout arearefs="hm5">
- <para><literal>updatable</literal> (optional): whether or not
- the column will be part of the update statement (default
- true)</para>
- </callout>
-
- <callout arearefs="hm6">
- <para><literal>columnDefinition</literal> (optional): override
- the sql DDL fragment for this particular column (non
- portable)</para>
- </callout>
-
- <callout arearefs="hm7">
- <para><literal>table</literal> (optional): define the targeted
- table (default primary table)</para>
- </callout>
-
- <callout arearefs="hm8">
- <para><literal><literal>length</literal></literal> (optional):
- column length (default 255)</para>
- </callout>
-
- <callout arearefs="hm8">
- <para><literal><literal>precision</literal></literal>
- (optional): column decimal precision (default 0)</para>
- </callout>
-
- <callout arearefs="hm10">
- <para><literal><literal>scale</literal></literal> (optional):
- column decimal scale if useful (default 0)</para>
- </callout>
- </calloutlist>
- </programlistingco>
- </sect3>
-
- <sect3>
- <title>Embedded objects (aka components)</title>
-
- <para>It is possible to declare an embedded component inside an entity
- and even override its column mapping. Component classes have to be
- annotated at the class level with the <literal>@Embeddable</literal>
- annotation. It is possible to override the column mapping of an
- embedded object for a particular entity using the
- <literal>@Embedded</literal> and <literal>@AttributeOverride</literal>
- annotation in the associated property:</para>
-
- <programlisting>
- at Entity
-public class Person implements Serializable {
-
- // Persistent component using defaults
- Address homeAddress;
-
- @Embedded
- @AttributeOverrides( {
- @AttributeOverride(name="iso2", column = @Column(name="bornIso2") ),
- @AttributeOverride(name="name", column = @Column(name="bornCountryName") )
- } )
- Country bornIn;
- ...
-}
- </programlisting>
-
- <programlisting>
- at Embeddable
-public class Address implements Serializable {
- String city;
- Country nationality; //no overriding here
-}
- </programlisting>
-
- <programlisting>
- at Embeddable
-public class Country implements Serializable {
- private String iso2;
- @Column(name="countryName") private String name;
-
- public String getIso2() { return iso2; }
- public void setIso2(String iso2) { this.iso2 = iso2; }
-
-
- public String getName() { return name; }
- public void setName(String name) { this.name = name; }
- ...
-}
- </programlisting>
-
- <para>A embeddable object inherit the access type of its owning entity
- (note that you can override that using the Hibernate specific
- <literal>@AccessType</literal> annotations (see <xref
- linkend="entity-hibspec" />).</para>
-
- <para>The <literal>Person</literal> entity bean has two component
- properties, <literal>homeAddress</literal> and
- <literal>bornIn</literal>. <literal>homeAddress</literal> property has
- not been annotated, but Hibernate will guess that it is a persistent
- component by looking for the <literal>@Embeddable</literal> annotation
- in the Address class. We also override the mapping of a column name
- (to <literal>bornCountryName</literal>) with the
- <literal>@Embedded</literal> and <literal>@AttributeOverride
- </literal>annotations for each mapped attribute of
- <literal>Country</literal>. As you can see, <literal>Country
- </literal>is also a nested component of <literal>Address</literal>,
- again using auto-detection by Hibernate and EJB3 defaults. Overriding
- columns of embedded objects of embedded objects is currently not
- supported in the EJB3 spec, however, Hibernate Annotations supports it
- through dotted expressions.</para>
-
- <para><programlisting> @Embedded
- @AttributeOverrides( {
- @AttributeOverride(name="city", column = @Column(name="fld_city") )
- @AttributeOverride(name="<emphasis role="bold">nationality.iso2</emphasis>", column = @Column(name="nat_Iso2") ),
- @AttributeOverride(name="<emphasis role="bold">nationality.name</emphasis>", column = @Column(name="nat_CountryName") )
- //nationality columns in homeAddress are overridden
- } )
- Address homeAddress;</programlisting>Hibernate Annotations supports one
- more feature that is not explicitly supported by the EJB3
- specification. You can annotate a embedded object with the
- <literal>@MappedSuperclass</literal> annotation to make the superclass
- properties persistent (see <literal>@MappedSuperclass</literal> for
- more informations).</para>
-
- <para>While not supported by the EJB3 specification, Hibernate
- Annotations allows you to use association annotations in an embeddable
- object (ie <literal>@*ToOne</literal> nor
- <literal>@*ToMany</literal>). To override the association columns you
- can use <literal>@AssociationOverride</literal>.</para>
-
- <para>If you want to have the same embeddable object type twice in the
- same entity, the column name defaulting will not work: at least one of
- the columns will have to be explicit. Hibernate goes beyond the EJB3
- spec and allows you to enhance the defaulting mechanism through the
- <classname>NamingStrategy</classname>.
- <classname>DefaultComponentSafeNamingStrategy</classname> is a small
- improvement over the default EJB3NamingStrategy that allows embedded
- objects to be defaulted even if used twice in the same entity.</para>
- </sect3>
-
- <sect3>
- <title>Non-annotated property defaults</title>
-
- <para>If a property is not annotated, the following rules
- apply:</para>
-
- <itemizedlist>
- <listitem>
- If the property is of a single type, it is mapped as @Basic
- </listitem>
-
- <listitem>
- Otherwise, if the type of the property is annotated as @Embeddable, it is mapped as @Embedded
- </listitem>
-
- <listitem>
- Otherwise, if the type of the property is Serializable, it is mapped as @Basic in a column holding the object in its serialized version
- </listitem>
-
- <listitem>
- Otherwise, if the type of the property is java.sql.Clob or java.sql.Blob, it is mapped as @Lob with the appropriate LobType
- </listitem>
- </itemizedlist>
- </sect3>
- </sect2>
-
- <sect2 id="entity-mapping-identifier" label=""
- xreflabel="Mapping identifier properties">
- <title>Mapping identifier properties</title>
-
- <para>The <literal>@Id</literal> annotation lets you define which
- property is the identifier of your entity bean. This property can be set
- by the application itself or be generated by Hibernate (preferred). You
- can define the identifier generation strategy thanks to the
- <literal>@GeneratedValue</literal> annotation:</para>
-
- <itemizedlist>
- <listitem>
- AUTO - either identity column, sequence or table depending on the underlying DB
- </listitem>
-
- <listitem>
- TABLE - table holding the id
- </listitem>
-
- <listitem>
- IDENTITY - identity column
- </listitem>
-
- <listitem>
- SEQUENCE - sequence
- </listitem>
- </itemizedlist>
-
- <para>Hibernate provides more id generators than the basic EJB3 ones.
- Check <xref linkend="entity-hibspec" /> for more informations.</para>
-
- <para>The following example shows a sequence generator using the
- SEQ_STORE configuration (see below)</para>
-
- <programlisting>
- at Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="SEQ_STORE")
-public Integer getId() { ... }
- </programlisting>
-
- <para>The next example uses the identity generator:</para>
-
- <programlisting>
- at Id @GeneratedValue(strategy=GenerationType.IDENTITY)
-public Long getId() { ... }
- </programlisting>
-
- <para>The <literal>AUTO</literal> generator is the preferred type for
- portable applications (across several DB vendors). The identifier
- generation configuration can be shared for several
- <literal>@Id</literal> mappings with the generator attribute. There are
- several configurations available through
- <literal>@SequenceGenerator</literal> and
- <literal>@TableGenerator</literal>. The scope of a generator can be the
- application or the class. Class-defined generators are not visible
- outside the class and can override application level generators.
- Application level generators are defined at XML level (see <xref
- linkend="xml-overriding" />):</para>
-
- <programlisting><table-generator name="EMP_GEN"
- table="GENERATOR_TABLE"
- pk-column-name="key"
- value-column-name="hi"
- pk-column-value="EMP"
- allocation-size="20"/>
-
-//and the annotation equivalent
-
- at javax.persistence.TableGenerator(
- name="EMP_GEN",
- table="GENERATOR_TABLE",
- pkColumnName = "key",
- valueColumnName = "hi"
- pkColumnValue="EMP",
- allocationSize=20
-)
-
-<sequence-generator name="SEQ_GEN"
- sequence-name="my_sequence"
- allocation-size="20"/>
-
-//and the annotation equivalent
-
- at javax.persistence.SequenceGenerator(
- name="SEQ_GEN",
- sequenceName="my_sequence",
- allocationSize=20
-)
- </programlisting>
-
- <para>If JPA XML (like <filename>META-INF/orm.xml</filename>) is used to
- define thegenerators, <literal>EMP_GEN</literal> and
- <literal>SEQ_GEN</literal> are application level generators.
- <literal>EMP_GEN</literal> defines a table based id generator using the
- hilo algorithm with a <literal>max_lo</literal> of 20. The hi value is
- kept in a <literal>table</literal> "<literal>GENERATOR_TABLE</literal>".
- The information is kept in a row where <literal>pkColumnName</literal>
- "key" is equals to <literal>pkColumnValue</literal>
- "<literal>EMP</literal>" and column <literal>valueColumnName</literal>
- "<literal>hi</literal>" contains the the next high value used.</para>
-
- <para><literal>SEQ_GEN</literal> defines a sequence generator using a
- sequence named <literal>my_sequence</literal>. The allocation size used
- for this sequence based hilo algorithm is 20. Note that this version of
- Hibernate Annotations does not handle <literal>initialValue</literal> in
- the sequence generator. The default allocation size is 50, so if you
- want to use a sequence and pickup the value each time, you must set the
- allocation size to 1.</para>
-
- <note>
- <para>Package level definition is no longer supported by the EJB 3.0
- specification. However, you can use the
- <literal>@GenericGenerator</literal> at the package level (see <xref
- linkend="entity-hibspec-identifier" />).</para>
- </note>
-
- <para>The next example shows the definition of a sequence generator in a
- class scope:</para>
-
- <programlisting>
- at Entity
- at javax.persistence.SequenceGenerator(
- name="SEQ_STORE",
- sequenceName="my_sequence"
-)
-public class Store implements Serializable {
- private Long id;
-
- @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="SEQ_STORE")
- public Long getId() { return id; }
-}
- </programlisting>
-
- <para>This class will use a sequence named my_sequence and the SEQ_STORE
- generator is not visible in other classes. Note that you can check the
- Hibernate Annotations tests in the org.hibernate.test.metadata.id
- package for more examples.</para>
-
- <para>You can define a composite primary key through several
- syntaxes:</para>
-
- <itemizedlist>
- <listitem>
- annotate the component property as @Id and make the component class @Embeddable
- </listitem>
-
- <listitem>
- annotate the component property as @EmbeddedId
- </listitem>
-
- <listitem>
- annotate the class as @IdClass and annotate each property of the entity involved in the primary key with @Id
- </listitem>
- </itemizedlist>
-
- <para>While quite common to the EJB2 developer,
- <literal>@IdClass</literal> is likely new for Hibernate users. The
- composite primary key class corresponds to multiple fields or properties
- of the entity class, and the names of primary key fields or properties
- in the primary key class and those of the entity class must match and
- their types must be the same. Let's look at an example:</para>
-
- <programlisting>@Entity
-<emphasis role="bold">@IdClass(FootballerPk.class)</emphasis>
-public class Footballer {
- //part of the id key
- <emphasis role="bold">@Id</emphasis> public String getFirstname() {
- return firstname;
- }
-
- public void setFirstname(String firstname) {
- this.firstname = firstname;
- }
-
- //part of the id key
- <emphasis role="bold">@Id</emphasis> public String getLastname() {
- return lastname;
- }
-
- public void setLastname(String lastname) {
- this.lastname = lastname;
- }
-
- public String getClub() {
- return club;
- }
-
- public void setClub(String club) {
- this.club = club;
- }
-
- //appropriate equals() and hashCode() implementation
-}
-
- at Embeddable
-public class FootballerPk implements Serializable {
- //same name and type as in Footballer
- public String getFirstname() {
- return firstname;
- }
-
- public void setFirstname(String firstname) {
- this.firstname = firstname;
- }
-
- //same name and type as in Footballer
- public String getLastname() {
- return lastname;
- }
-
- public void setLastname(String lastname) {
- this.lastname = lastname;
- }
-
- //appropriate equals() and hashCode() implementation
-}
-</programlisting>
-
- <para>As you may have seen, <literal>@IdClass</literal> points to the
- corresponding primary key class.</para>
-
- <para>While not supported by the EJB3 specification, Hibernate allows
- you to define associations inside a composite identifier. Simply use the
- regular annotations for that</para>
-
- <programlisting>@Entity
- at AssociationOverride( name="id.channel", joinColumns = @JoinColumn(name="chan_id") )
-public class TvMagazin {
- @EmbeddedId public TvMagazinPk id;
- @Temporal(TemporalType.TIME) Date time;
-}
-
- at Embeddable
-public class TvMagazinPk implements Serializable {
- @ManyToOne
- public Channel channel;
- public String name;
- @ManyToOne
- public Presenter presenter;
-}
-</programlisting>
- </sect2>
-
- <sect2>
- <title>Mapping inheritance</title>
-
- <para>EJB3 supports the three types of inheritance:</para>
-
- <itemizedlist>
- <listitem>
- Table per Class Strategy: the <union-class> element in Hibernate
- </listitem>
-
- <listitem>
- Single Table per Class Hierarchy Strategy: the <subclass> element in Hibernate
- </listitem>
-
- <listitem>
- Joined Subclass Strategy: the <joined-subclass> element in Hibernate
- </listitem>
- </itemizedlist>
-
- <para>The chosen strategy is declared at the class level of the top
- level entity in the hierarchy using the <literal>@Inheritance</literal>
- annotation.</para>
-
- <note>
- <para>Annotating interfaces is currently not supported.</para>
- </note>
-
- <sect3>
- <title>Table per class</title>
-
- <para>This strategy has many drawbacks (esp. with polymorphic queries
- and associations) explained in the EJB3 spec, the Hibernate reference
- documentation, Hibernate in Action, and many other places. Hibernate
- work around most of them implementing this strategy using <literal>SQL
- UNION</literal> queries. It is commonly used for the top level of an
- inheritance hierarchy:</para>
-
- <programlisting>
- at Entity
- at Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
-public class Flight implements Serializable {
- </programlisting>
-
- <para>This strategy support one to many associations provided that
- they are bidirectional. This strategy does not support the
- <literal>IDENTITY</literal> generator strategy: the id has to be
- shared across several tables. Consequently, when using this strategy,
- you should not use <literal>AUTO </literal>nor
- <literal>IDENTITY</literal>.</para>
- </sect3>
-
- <sect3>
- <title>Single table per class hierarchy</title>
-
- <para>All properties of all super- and subclasses are mapped into the
- same table, instances are distinguished by a special discriminator
- column:</para>
-
- <programlisting>
- at Entity
- at Inheritance(strategy=InheritanceType.SINGLE_TABLE)
- at DiscriminatorColumn(
- name="planetype",
- discriminatorType=DiscriminatorType.STRING
-)
- at DiscriminatorValue("Plane")
-public class Plane { ... }
-
- at Entity
- at DiscriminatorValue("A320")
-public class A320 extends Plane { ... }
- </programlisting>
-
- <para><classname>Plane</classname> is the superclass, it defines the
- inheritance strategy <literal>InheritanceType.SINGLE_TABLE</literal>.
- It also defines the discriminator column through the
- <literal>@DiscriminatorColumn</literal> annotation, a discriminator
- column can also define the discriminator type. Finally, the
- <literal>@DiscriminatorValue</literal> annotation defines the value
- used to differentiate a class in the hierarchy. All of these
- attributes have sensible default values. The default name of the
- discriminator column is <literal>DTYPE</literal>. The default
- discriminator value is the entity name (as defined in
- <literal>@Entity.name</literal>) for DiscriminatorType.STRING.
- <classname>A320</classname> is a subclass; you only have to define
- discriminator value if you don't want to use the default value. The
- strategy and the discriminator type are implicit.</para>
-
- <para><literal>@Inheritance</literal> and
- <literal>@DiscriminatorColumn</literal> should only be defined at the
- top of the entity hierarchy.</para>
- </sect3>
-
- <sect3>
- <title>Joined subclasses</title>
-
- <para>The<literal> @PrimaryKeyJoinColumn</literal> and
- <literal>@PrimaryKeyJoinColumns</literal> annotations define the
- primary key(s) of the joined subclass table:</para>
-
- <programlisting>
- at Entity
- at Inheritance(strategy=InheritanceType.JOINED)
-public class Boat implements Serializable { ... }
-
- at Entity
-public class Ferry extends Boat { ... }
-
- at Entity
- at PrimaryKeyJoinColumn(name="BOAT_ID")
-public class AmericaCupClass extends Boat { ... }
- </programlisting>
-
- <para>All of the above entities use the <literal>JOINED</literal>
- strategy, the <literal>Ferry</literal> table is joined with the
- <literal>Boat</literal> table using the same primary key names. The
- <literal>AmericaCupClass</literal> table is joined with
- <literal>Boat</literal> using the join condition <code>Boat.id =
- AmericaCupClass.BOAT_ID</code>.</para>
- </sect3>
-
- <sect3>
- <title>Inherit properties from superclasses</title>
-
- <para>This is sometimes useful to share common properties through a
- technical or a business superclass without including it as a regular
- mapped entity (ie no specific table for this entity). For that purpose
- you can map them as <literal>@MappedSuperclass</literal>.</para>
-
- <programlisting>@MappedSuperclass
-public class BaseEntity {
- @Basic
- @Temporal(TemporalType.TIMESTAMP)
- public Date getLastUpdate() { ... }
- public String getLastUpdater() { ... }
- ...
-}
-
- at Entity class Order extends BaseEntity {
- @Id public Integer getId() { ... }
- ...
-}</programlisting>
-
- <para>In database, this hierarchy will be represented as an
- <literal>Order</literal> table having the <literal>id</literal>,
- <literal>lastUpdate</literal> and <literal>lastUpdater</literal>
- columns. The embedded superclass property mappings are copied into
- their entity subclasses. Remember that the embeddable superclass is
- not the root of the hierarchy though.</para>
-
- <note>
- <para>Properties from superclasses not mapped as
- <literal>@MappedSuperclass</literal> are ignored.</para>
- </note>
-
- <note>
- <para>The access type (field or methods), is inherited from the root
- entity, unless you use the Hibernate annotation
- <literal>@AccessType</literal></para>
- </note>
-
- <note>
- <para>The same notion can be applied to
- <literal>@Embeddable</literal> objects to persist properties from
- their superclasses. You also need to use
- <literal>@MappedSuperclass</literal> to do that (this should not be
- considered as a standard EJB3 feature though)</para>
- </note>
-
- <note>
- <para>It is allowed to mark a class as
- <literal>@MappedSuperclass</literal> in the middle of the mapped
- inheritance hierarchy.</para>
- </note>
-
- <note>
- <para>Any class in the hierarchy non annotated with
- <literal>@MappedSuperclass</literal> nor <literal>@Entity</literal>
- will be ignored.</para>
- </note>
-
- <para>You can override columns defined in entity superclasses at the
- root entity level using the <literal>@AttributeOverride</literal>
- annotation.</para>
-
- <programlisting>@MappedSuperclass
-public class FlyingObject implements Serializable {
-
- public int getAltitude() {
- return altitude;
- }
-
- @Transient
- public int getMetricAltitude() {
- return metricAltitude;
- }
-
- @ManyToOne
- public PropulsionType getPropulsion() {
- return metricAltitude;
- }
- ...
-}
-
- at Entity
- at AttributeOverride( name="altitude", column = @Column(name="fld_altitude") )
- at AssociationOverride( name="propulsion", joinColumns = @JoinColumn(name="fld_propulsion_fk") )
-public class Plane extends FlyingObject {
- ...
-}</programlisting>
-
- <para>The <literal>altitude</literal> property will be persisted in an
- <literal>fld_altitude</literal> column of table
- <literal>Plane</literal> and the propulsion association will be
- materialized in a <literal>fld_propulsion_fk</literal> foreign key
- column.</para>
-
- <para>You can define <literal>@AttributeOverride</literal>(s) and
- <literal>@AssociationOverride</literal>(s) on
- <literal>@Entity</literal> classes,
- <literal>@MappedSuperclass</literal> classes and properties pointing
- to an <literal>@Embeddable</literal> object.</para>
- </sect3>
- </sect2>
-
- <sect2 id="entity-mapping-association">
- <title>Mapping entity bean associations/relationships</title>
-
- <sect3>
- <title>One-to-one</title>
-
- <para>You can associate entity beans through a one-to-one relationship
- using <literal>@OneToOne</literal>. There are three cases for
- one-to-one associations: either the associated entities share the same
- primary keys values, a foreign key is held by one of the entities
- (note that this FK column in the database should be constrained unique
- to simulate one-to-one multiplicity), or a association table is used
- to store the link between the 2 entities (a unique constraint has to
- be defined on each fk to ensure the one to one multiplicity)</para>
-
- <para>First, we map a real one-to-one association using shared primary
- keys:</para>
-
- <programlisting>
- at Entity
-public class Body {
- @Id
- public Long getId() { return id; }
-
- @OneToOne(cascade = CascadeType.ALL)
- @PrimaryKeyJoinColumn
- public Heart getHeart() {
- return heart;
- }
- ...
-}
- </programlisting>
-
- <programlisting>
- at Entity
-public class Heart {
- @Id
- public Long getId() { ...}
-}
- </programlisting>
-
- <para>The one to one is marked as true by using the
- <literal>@PrimaryKeyJoinColumn</literal> annotation.</para>
-
- <para>In the following example, the associated entities are linked
- through a foreign key column:</para>
-
- <programlisting>
- at Entity
-public class Customer implements Serializable {
- @OneToOne(cascade = CascadeType.ALL)
- <emphasis role="bold">@JoinColumn(name="passport_fk")</emphasis>
- public Passport getPassport() {
- ...
- }
-
- at Entity
-public class Passport implements Serializable {
- @OneToOne(<emphasis role="bold">mappedBy = "passport"</emphasis>)
- public Customer getOwner() {
- ...
-}
- </programlisting>
-
- <para>A <classname>Customer</classname> is linked to a
- <classname>Passport</classname>, with a foreign key column named
- <literal>passport_fk</literal> in the <literal>Customer</literal>
- table. The join column is declared with the
- <literal>@JoinColumn</literal> annotation which looks like the
- <literal>@Column</literal> annotation. It has one more parameters
- named <literal>referencedColumnName</literal>. This parameter declares
- the column in the targeted entity that will be used to the join. Note
- that when using
- <literal><literal>referencedColumnName</literal></literal> to a non
- primary key column, the associated class has to be
- <classname>Serializable</classname>. Also note that the
- <literal><literal>referencedColumnName</literal></literal> to a non
- primary key column has to be mapped to a property having a single
- column (other cases might not work).</para>
-
- <para>The association may be bidirectional. In a bidirectional
- relationship, one of the sides (and only one) has to be the owner: the
- owner is responsible for the association column(s) update. To declare
- a side as <emphasis>not</emphasis> responsible for the relationship,
- the attribute <literal>mappedBy</literal> is used.
- <literal>mappedBy</literal> refers to the property name of the
- association on the owner side. In our case, this is
- <literal>passport</literal>. As you can see, you don't have to (must
- not) declare the join column since it has already been declared on the
- owners side.</para>
-
- <para>If no <literal>@JoinColumn</literal> is declared on the owner
- side, the defaults apply. A join column(s) will be created in the
- owner table and its name will be the concatenation of the name of the
- relationship in the owner side, <keycap>_</keycap> (underscore), and
- the name of the primary key column(s) in the owned side. In this
- example <literal>passport_id</literal> because the property name is
- <literal>passport</literal> and the column id of <literal>Passport
- </literal>is <literal>id</literal>.</para>
-
- <para>The third possibility (using an association table) is very
- exotic.</para>
-
- <programlisting>
- at Entity
-public class Customer implements Serializable {
- @OneToOne(cascade = CascadeType.ALL)
- <emphasis role="bold">@JoinTable(name = "CustomerPassports"
- joinColumns = @JoinColumn(name="customer_fk"),
- inverseJoinColumns = @JoinColumns(name="passport_fk")</emphasis>
- )
- public Passport getPassport() {
- ...
- }
-
- at Entity
-public class Passport implements Serializable {
- @OneToOne(<emphasis role="bold">mappedBy = "passport"</emphasis>)
- public Customer getOwner() {
- ...
-}
- </programlisting>
-
- <para>A <classname>Customer</classname> is linked to a
- <classname>Passport</classname> through a association table named
- <literal>CustomerPassports</literal> ; this association table has a
- foreign key column named <literal>passport_fk</literal> pointing to
- the <literal>Passport</literal> table (materialized by the
- <literal>inverseJoinColumn</literal>, and a foreign key column named
- <literal>customer_fk</literal> pointing to the
- <literal>Customer</literal> table materialized by the
- <literal>joinColumns</literal> attribute.</para>
-
- <para>You must declare the join table name and the join columns
- explicitly in such a mapping.</para>
- </sect3>
-
- <sect3>
- <title>Many-to-one</title>
-
- <para>Many-to-one associations are declared at the property level with
- the annotation <literal>@ManyToOne</literal>:</para>
-
- <programlisting>
- at Entity()
-public class Flight implements Serializable {
- <emphasis role="bold">@ManyToOne</emphasis>( cascade = {CascadeType.PERSIST, CascadeType.MERGE} )
- @JoinColumn(name="COMP_ID")
- public Company getCompany() {
- return company;
- }
- ...
-}
- </programlisting>
-
- <para>The <literal>@JoinColumn</literal> attribute is optional, the
- default value(s) is like in one to one, the concatenation of the name
- of the relationship in the owner side, <keycap>_</keycap>
- (underscore), and the name of the primary key column in the owned
- side. In this example <literal>company_id</literal> because the
- property name is <literal>company</literal> and the column id of
- Company is <literal>id</literal>.</para>
-
- <para><literal>@ManyToOne</literal> has a parameter named
- <literal>targetEntity</literal> which describes the target entity
- name. You usually don't need this parameter since the default value
- (the type of the property that stores the association) is good in
- almost all cases. However this is useful when you want to use
- interfaces as the return type instead of the regular entity.</para>
-
- <programlisting>
- at Entity()
-public class Flight implements Serializable {
- @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE}, <emphasis
- role="bold">targetEntity=CompanyImpl.class</emphasis> )
- @JoinColumn(name="COMP_ID")
- public Company getCompany() {
- return company;
- }
- ...
-}
-
-public interface Company {
- ...
- </programlisting>
-
- <para>You can alse map a many to one association through an
- association table. This association table described by the
- <literal>@JoinTable</literal> annotation will contains a foreign key
- referencing back the entity table (through
- <literal>@JoinTable.joinColumns</literal>) and a a foreign key
- referencing the target entity table (through
- <literal>@JoinTable.inverseJoinColumns</literal>).</para>
-
- <programlisting>
- at Entity()
-public class Flight implements Serializable {
- @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE} )
- <emphasis role="bold">@JoinTable(name="Flight_Company",
- joinColumns = @JoinColumn(name="FLIGHT_ID"),
- inverseJoinColumns = @JoinColumns(name="COMP_ID")
- )</emphasis>
- public Company getCompany() {
- return company;
- }
- ...
-}
- </programlisting>
- </sect3>
-
- <sect3 id="entity-mapping-association-collections" revision="1">
- <title>Collections</title>
-
- <sect4 id="entity-mapping-association-collections-overview"
- revision="1">
- <title>Overview</title>
-
- <para>You can map <classname>Collection</classname>,
- <literal>List</literal> (ie ordered lists, not indexed lists),
- <literal>Map</literal> and <classname>Set</classname>. The EJB3
- specification describes how to map an ordered list (ie a list
- ordered at load time) using
- <literal>@javax.persistence.OrderBy</literal> annotation: this
- annotation takes into parameter a list of comma separated (target
- entity) properties to order the collection by (eg <code>firstname
- asc, age desc</code>), if the string is empty, the collection will
- be ordered by id. For true indexed
- collections, please refer to the <xref linkend="entity-hibspec" />.
- EJB3 allows you to map Maps using as a key one of the target entity
- property using <literal>@MapKey(name="myProperty")</literal>
- (myProperty is a property name in the target entity). When using
- <literal>@MapKey</literal> (without property name), the target
- entity primary key is used. The map key uses the same column as the
- property pointed out: there is no additional column defined to hold
- the map key, and it does make sense since the map key actually
- represent a target property. Be aware that once loaded, the key is
- no longer kept in sync with the property, in other words, if you
- change the property value, the key will not change automatically in
- your Java model (for true map support please refers to <xref
- linkend="entity-hibspec" />). Many people confuse
- <literal><map></literal> capabilities and
- <literal>@MapKey</literal> ones. These are two different features.
- <literal>@MapKey</literal> still has some limitations, please check
- the forum or the JIRA tracking system for more informations.</para>
-
- <para>Hibernate has several notions of collections.</para>
-
- <para></para>
-
- <table>
- <title>Collections semantics</title>
-
- <tgroup cols="3">
- <colspec colname="c1" />
-
- <colspec colname="c2" />
-
- <colspec colname="c3" colnum="2" />
-
- <thead>
- <row>
- <entry>Semantic</entry>
-
- <entry>java representation</entry>
-
- <entry>annotations</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Bag semantic</entry>
-
- <entry>java.util.List, java.util.Collection</entry>
-
- <entry>@org.hibernate.annotations.CollectionOfElements or
- @OneToMany or @ManyToMany</entry>
- </row>
-
- <row>
- <entry>Bag semantic with primary key (withtout the
- limitations of Bag semantic)</entry>
-
- <entry>java.util.List, java.util.Collection</entry>
-
- <entry>(@org.hibernate.annotations.CollectionOfElements or
- @OneToMany or @ManyToMany) and @CollectionId</entry>
- </row>
-
- <row>
- <entry>List semantic</entry>
-
- <entry>java.util.List</entry>
-
- <entry>(@org.hibernate.annotations.CollectionOfElements or
- @OneToMany or @ManyToMany) and
- @org.hibernate.annotations.IndexColumn</entry>
- </row>
-
- <row>
- <entry>Set semantic</entry>
-
- <entry>java.util.Set</entry>
-
- <entry>@org.hibernate.annotations.CollectionOfElements or
- @OneToMany or @ManyToMany</entry>
- </row>
-
- <row>
- <entry>Map semantic</entry>
-
- <entry>java.util.Map</entry>
-
- <entry>(@org.hibernate.annotations.CollectionOfElements or
- @OneToMany or @ManyToMany) and (nothing or
- @org.hibernate.annotations.MapKey/MapKeyManyToMany for true
- map support, OR @javax.persistence.MapKey</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <remark>So specifically, java.util.List collections without
- @org.hibernate.annotations.IndexColumn are going to be considered as
- bags.</remark>
-
- <para>Collection of primitive, core type or embedded objects is not
- supported by the EJB3 specification. Hibernate Annotations allows
- them however (see <xref linkend="entity-hibspec" />).</para>
-
- <programlisting>@Entity public class City {
- @OneToMany(mappedBy="city")
- <emphasis role="bold">@OrderBy("streetName")</emphasis>
- public List<Street> getStreets() {
- return streets;
- }
-...
-}
-
- at Entity public class Street {
- <emphasis role="bold">public String getStreetName()</emphasis> {
- return streetName;
- }
-
- @ManyToOne
- public City getCity() {
- return city;
- }
- ...
-}
-
-
- at Entity
-public class Software {
- @OneToMany(mappedBy="software")
- <emphasis role="bold">@MapKey(name="codeName")</emphasis>
- public Map<String, Version> getVersions() {
- return versions;
- }
-...
-}
-
- at Entity
- at Table(name="tbl_version")
-public class Version {
- <emphasis role="bold">public String getCodeName()</emphasis> {...}
-
- @ManyToOne
- public Software getSoftware() { ... }
-...
-}</programlisting>
-
- <para>So <literal>City</literal> has a collection of
- <literal>Street</literal>s that are ordered by
- <literal>streetName</literal> (of <literal>Street</literal>) when
- the collection is loaded. <literal>Software</literal> has a map of
- <literal>Version</literal>s which key is the
- <literal>Version</literal> <literal>codeName</literal>.</para>
-
- <para>Unless the collection is a generic, you will have to define
- <literal>targetEntity</literal>. This is a annotation attribute that
- take the target entity class as a value.</para>
- </sect4>
-
- <sect4 id="entity-mapping-association-collection-onetomany"
- revision="2">
- <title>One-to-many</title>
-
- <para>One-to-many associations are declared at the property level
- with the annotation <literal>@OneToMany</literal>. One to many
- associations may be bidirectional.</para>
-
- <sect5>
- <title>Bidirectional</title>
-
- <para>Since many to one are (almost) always the owner side of a
- bidirectional relationship in the EJB3 spec, the one to many
- association is annotated by <literal>@OneToMany( mappedBy=...
- )</literal></para>
-
- <programlisting>@Entity
-public class Troop {
- @OneToMany(mappedBy="troop")
- public Set<Soldier> getSoldiers() {
- ...
-}
-
- at Entity
-public class Soldier {
- @ManyToOne
- @JoinColumn(name="troop_fk")
- public Troop getTroop() {
- ...
-} </programlisting>
-
- <para><classname>Troop</classname> has a bidirectional one to many
- relationship with <literal>Soldier</literal> through the
- <literal>troop</literal> property. You don't have to (must not)
- define any physical mapping in the <literal>mappedBy</literal>
- side.</para>
-
- <para>To map a bidirectional one to many, with the one-to-many
- side as the owning side, you have to remove the
- <literal>mappedBy</literal> element and set the many to one
- <literal>@JoinColumn</literal> as insertable and updatable to
- false. This solution is obviously not optimized and will produce
- some additional UPDATE statements.</para>
-
- <programlisting>@Entity
-public class Troop {
- @OneToMany
- @JoinColumn(name="troop_fk") //we need to duplicate the physical information
- public Set<Soldier> getSoldiers() {
- ...
-}
-
- at Entity
-public class Soldier {
- @ManyToOne
- @JoinColumn(name="troop_fk", insertable=false, updatable=false)
- public Troop getTroop() {
- ...
-}</programlisting>
- </sect5>
-
- <sect5>
- <title>Unidirectional</title>
-
- <para>A unidirectional one to many using a foreign key column in
- the owned entity is not that common and not really recommended. We
- strongly advise you to use a join table for this kind of
- association (as explained in the next section). This kind of
- association is described through a
- <literal>@JoinColumn</literal></para>
-
- <programlisting>
- at Entity
-public class Customer implements Serializable {
- @OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER)
- @JoinColumn(name="CUST_ID")
- public Set<Ticket> getTickets() {
- ...
-}
-
- at Entity
-public class Ticket implements Serializable {
- ... //no bidir
-}
- </programlisting>
-
- <para><literal>Customer</literal> describes a unidirectional
- relationship with <literal>Ticket</literal> using the join column
- <literal>CUST_ID</literal>.</para>
- </sect5>
-
- <sect5>
- <title>Unidirectional with join table</title>
-
- <para>A unidirectional one to many with join table is much
- preferred. This association is described through an
- <literal>@JoinTable</literal>.</para>
-
- <programlisting>
- at Entity
-public class Trainer {
- @OneToMany
- @JoinTable(
- name="TrainedMonkeys",
- joinColumns = { @JoinColumn( name="trainer_id") },
- inverseJoinColumns = @JoinColumn( name="monkey_id")
- )
- public Set<Monkey> getTrainedMonkeys() {
- ...
-}
-
- at Entity
-public class Monkey {
- ... //no bidir
-}
- </programlisting>
-
- <para><literal>Trainer</literal> describes a unidirectional
- relationship with <classname>Monkey</classname> using the join
- table <classname>TrainedMonkeys</classname>, with a foreign key
- <literal>trainer_id</literal> to <literal>Trainer</literal>
- (<literal>joinColumns</literal>) and a foreign key
- <literal>monkey_id</literal> to <literal>Monkey</literal>
- (<literal>inversejoinColumns</literal>).</para>
- </sect5>
-
- <sect5 id="entity-mapping-association-collection-manytomany-default"
- revision="1">
- <title>Defaults</title>
-
- <para>Without describing any physical mapping, a unidirectional
- one to many with join table is used. The table name is the
- concatenation of the owner table name, <keycap>_</keycap>, and the
- other side table name. The foreign key name(s) referencing the
- owner table is the concatenation of the owner table,
- <keycap>_</keycap>, and the owner primary key column(s) name. The
- foreign key name(s) referencing the other side is the
- concatenation of the owner property name, <keycap>_</keycap>, and
- the other side primary key column(s) name. A unique constraint is
- added to the foreign key referencing the other side table to
- reflect the one to many.</para>
-
- <programlisting>
- at Entity
-public class Trainer {
- @OneToMany
- public Set<Tiger> getTrainedTigers() {
- ...
-}
-
- at Entity
-public class Tiger {
- ... //no bidir
-}
- </programlisting>
-
- <para><classname>Trainer</classname> describes a unidirectional
- relationship with <classname>Tiger</classname> using the join
- table <literal>Trainer_Tiger</literal>, with a foreign key
- <literal>trainer_id</literal> to <literal>Trainer</literal> (table
- name, <keycap>_</keycap>, trainer id) and a foreign key
- <literal>trainedTigers_id</literal> to <literal>Monkey</literal>
- (property name, <keycap>_</keycap>, Tiger primary column).</para>
- </sect5>
- </sect4>
-
- <sect4 id="eentity-mapping-association-collection-manytomany"
- revision="">
- <title>Many-to-many</title>
-
- <sect5>
- <title>Definition</title>
-
- <para>A many-to-many association is defined logically using the
- <literal>@ManyToMany</literal> annotation. You also have to
- describe the association table and the join conditions using the
- <literal>@JoinTable</literal> annotation. If the association is
- bidirectional, one side has to be the owner and one side has to be
- the inverse end (ie. it will be ignored when updating the
- relationship values in the association table):</para>
-
- <programlisting>
- at Entity
-public class Employer implements Serializable {
- @ManyToMany(
- targetEntity=org.hibernate.test.metadata.manytomany.Employee.class,
- cascade={CascadeType.PERSIST, CascadeType.MERGE}
- )
- @JoinTable(
- name="EMPLOYER_EMPLOYEE",
- joinColumns={@JoinColumn(name="EMPER_ID")},
- inverseJoinColumns={@JoinColumn(name="EMPEE_ID")}
- )
- public Collection getEmployees() {
- return employees;
- }
- ...
-}
- </programlisting>
-
- <programlisting>
- at Entity
-public class Employee implements Serializable {
- @ManyToMany(
- cascade={CascadeType.PERSIST, CascadeType.MERGE},
- mappedBy="employees"
- targetEntity=Employer.class
- )
- public Collection getEmployers() {
- return employers;
- }
-}
- </programlisting>
-
- <para>We've already shown the many declarations and the detailed
- attributes for associations. We'll go deeper in the
- <literal>@JoinTable</literal> description, it defines a
- <literal>name</literal>, an array of join columns (an array in
- annotation is defined using { A, B, C }), and an array of inverse
- join columns. The latter ones are the columns of the association
- table which refer to the <classname>Employee</classname> primary
- key (the "other side").</para>
-
- <para>As seen previously, the other side don't have to (must not)
- describe the physical mapping: a simple
- <literal>mappedBy</literal> argument containing the owner side
- property name bind the two.</para>
- </sect5>
-
- <sect5>
- <title>Default values</title>
-
- <para>As any other annotations, most values are guessed in a many
- to many relationship. Without describing any physical mapping in a
- unidirectional many to many the following rules applied. The table
- name is the concatenation of the owner table name,
- <keycap>_</keycap> and the other side table name. The foreign key
- name(s) referencing the owner table is the concatenation of the
- owner table name, <keycap>_</keycap> and the owner primary key
- column(s). The foreign key name(s) referencing the other side is
- the concatenation of the owner property name, <keycap>_</keycap>,
- and the other side primary key column(s). These are the same rules
- used for a unidirectional one to many relationship.</para>
-
- <programlisting>
- at Entity
-public class Store {
- @ManyToMany(cascade = CascadeType.PERSIST)
- public Set<City> getImplantedIn() {
- ...
- }
-}
-
- at Entity
-public class City {
- ... //no bidirectional relationship
-}
- </programlisting>
-
- <para>A <literal>Store_City</literal> is used as the join table.
- The <literal>Store_id</literal> column is a foreign key to the
- <literal>Store</literal> table. The
- <literal>implantedIn_id</literal> column is a foreign key to the
- <literal>City</literal> table.</para>
-
- <para>Without describing any physical mapping in a bidirectional
- many to many the following rules applied. The table name is the
- concatenation of the owner table name, <keycap>_</keycap> and the
- other side table name. The foreign key name(s) referencing the
- owner table is the concatenation of the other side property name,
- <keycap>_</keycap>, and the owner primary key column(s). The
- foreign key name(s) referencing the other side is the
- concatenation of the owner property name, <keycap>_</keycap>, and
- the other side primary key column(s). These are the same rules
- used for a unidirectional one to many relationship.</para>
-
- <programlisting>
- at Entity
-public class Store {
- @ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
- public Set<Customer> getCustomers() {
- ...
- }
-}
-
- at Entity
-public class Customer {
- @ManyToMany(mappedBy="customers")
- public Set<Store> getStores() {
- ...
- }
-}
- </programlisting>
-
- <para>A <literal>Store_Customer</literal> is used as the join
- table. The <literal>stores_id</literal> column is a foreign key to
- the <literal>Store</literal> table. The
- <literal>customers_id</literal> column is a foreign key to the
- <literal>Customer</literal> table.</para>
- </sect5>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Transitive persistence with cascading</title>
-
- <para>You probably have noticed the <literal>cascade</literal>
- attribute taking an array of <classname>CascadeType</classname> as a
- value. The cascade concept in EJB3 is very is similar to the
- transitive persistence and cascading of operations in Hibernate, but
- with slightly different semantics and cascading types:</para>
-
- <itemizedlist>
- <listitem>
- CascadeType.PERSIST: cascades the persist (create) operation to associated entities persist() is called or if the entity is managed
- </listitem>
-
- <listitem>
- CascadeType.MERGE: cascades the merge operation to associated entities if merge() is called or if the entity is managed
- </listitem>
-
- <listitem>
- CascadeType.REMOVE: cascades the remove operation to associated entities if delete() is called
- </listitem>
-
- <listitem>
- CascadeType.REFRESH: cascades the refresh operation to associated entities if refresh() is called
- </listitem>
-
- <listitem>
- CascadeType.ALL: all of the above
- </listitem>
- </itemizedlist>
-
- <para>Please refer to the chapter 6.3 of the EJB3 specification for
- more information on cascading and create/merge semantics.</para>
- </sect3>
-
- <sect3 id="entity-mapping-association-fetching" revision="1">
- <title>Association fetching</title>
-
- <para>You have the ability to either eagerly or lazily fetch
- associated entities. The <literal>fetch</literal> parameter can be set
- to <literal>FetchType.LAZY</literal> or
- <literal>FetchType.EAGER</literal>. <literal>EAGER</literal> will try
- to use an outer join select to retrieve the associated object, while
- <literal>LAZY</literal> will only trigger a select when the associated
- object is accessed for the first time. <literal>@OneToMany</literal>
- and <literal>@ManyToMany</literal> associations are defaulted to
- <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>
-
- <para>The recommanded approach is to use <literal>LAZY</literal> onn
- all static fetching definitions and override this choice dynamically
- through JPA-QL. JPA-QL has a <literal>fetch</literal> keyword that
- allows you to override laziness when doing a particular query. This is
- very useful to improve performance and is decided on a use case to use
- case basis.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Mapping composite primary and foreign keys</title>
-
- <para>Composite primary keys use a embedded class as the primary key
- representation, so you'd use the <literal>@Id</literal> and
- <literal>@Embeddable</literal> annotations. Alternatively, you can use
- the <literal>@EmbeddedId</literal> annotation. Note that the dependent
- class has to be serializable and implements
- <methodname>equals()</methodname>/<methodname>hashCode()</methodname>.
- You can also use <literal>@IdClass</literal> as described in <xref
- linkend="entity-mapping-identifier" />.</para>
-
- <programlisting>
- at Entity
-public class RegionalArticle implements Serializable {
-
- @Id
- public RegionalArticlePk getPk() { ... }
-}
-
- at Embeddable
-public class RegionalArticlePk implements Serializable { ... }
- </programlisting>
-
- <para>or alternatively</para>
-
- <programlisting>
- at Entity
-public class RegionalArticle implements Serializable {
-
- @EmbeddedId
- public RegionalArticlePk getPk() { ... }
-}
-
-public class RegionalArticlePk implements Serializable { ... }
- </programlisting>
-
- <para><literal>@Embeddable</literal> inherit the access type of its
- owning entity unless the Hibernate specific annotation
- <literal>@AccessType</literal> is used. Composite foreign keys (if not
- using the default sensitive values) are defined on associations using
- the <literal>@JoinColumns</literal> element, which is basically an array
- of <literal>@JoinColumn</literal>. It is considered a good practice to
- express <literal>referencedColumnNames</literal> explicitly. Otherwise,
- Hibernate will suppose that you use the same order of columns as in the
- primary key declaration.</para>
-
- <programlisting>
- at Entity
-public class Parent implements Serializable {
- @Id
- public ParentPk id;
- public int age;
-
- @OneToMany(cascade=CascadeType.ALL)
- @JoinColumns ({
- @JoinColumn(name="parentCivility", referencedColumnName = "isMale"),
- @JoinColumn(name="parentLastName", referencedColumnName = "lastName"),
- @JoinColumn(name="parentFirstName", referencedColumnName = "firstName")
- })
- public Set<Child> children; //unidirectional
- ...
-}
- </programlisting>
-
- <programlisting>
- at Entity
-public class Child implements Serializable {
- @Id @GeneratedValue
- public Integer id;
-
- @ManyToOne
- @JoinColumns ({
- @JoinColumn(name="parentCivility", referencedColumnName = "isMale"),
- @JoinColumn(name="parentLastName", referencedColumnName = "lastName"),
- @JoinColumn(name="parentFirstName", referencedColumnName = "firstName")
- })
- public Parent parent; //unidirectional
-}
- </programlisting>
-
- <programlisting>
- at Embeddable
-public class ParentPk implements Serializable {
- String firstName;
- String lastName;
- ...
-}
- </programlisting>
-
- <para>Note the explicit usage of the
- <literal>referencedColumnName</literal>.</para>
- </sect2>
-
- <sect2>
- <title>Mapping secondary tables</title>
-
- <para>You can map a single entity bean to several tables using the
- <literal>@SecondaryTable</literal> or
- <literal>@SecondaryTables</literal> class level annotations. To express
- that a column is in a particular table, use the <literal>table</literal>
- parameter of <literal>@Column</literal> or
- <literal>@JoinColumn</literal>.</para>
-
- <programlisting>
- at Entity
- at Table(name="MainCat")
-<emphasis role="bold">@SecondaryTables({
- @SecondaryTable(name="Cat1", pkJoinColumns={
- @PrimaryKeyJoinColumn(name="cat_id", referencedColumnName="id")
- ),
- @SecondaryTable(name="Cat2", uniqueConstraints={@UniqueConstraint(columnNames={"storyPart2"})})
-})</emphasis>
-public class Cat implements Serializable {
-
- private Integer id;
- private String name;
- private String storyPart1;
- private String storyPart2;
-
- @Id @GeneratedValue
- public Integer getId() {
- return id;
- }
-
- public String getName() {
- return name;
- }
-
- <emphasis role="bold">@Column(table="Cat1")</emphasis>
- public String getStoryPart1() {
- return storyPart1;
- }
-
- <emphasis role="bold">@Column(table="Cat2")</emphasis>
- public String getStoryPart2() {
- return storyPart2;
- }
-</programlisting>
-
- <para>In this example, <literal>name</literal> will be in
- <literal>MainCat</literal>. <literal>storyPart1</literal> will be in
- <literal>Cat1</literal> and <literal>storyPart2</literal> will be in
- <literal>Cat2</literal>. <literal>Cat1</literal> will be joined to
- <literal>MainCat</literal> using the <literal>cat_id</literal> as a
- foreign key, and <literal>Cat2</literal> using <literal>id</literal> (ie
- the same column name, the <literal>MainCat</literal> id column has).
- Plus a unique constraint on <literal>storyPart2</literal> has been
- set.</para>
-
- <para>Check out the JBoss EJB 3 tutorial or the Hibernate Annotations
- unit test suite for more examples.</para>
- </sect2>
- </sect1>
-
- <sect1 id="entity-mapping-query">
- <title>Mapping Queries</title>
-
- <sect2 id="entity-mapping-query-hql" label="Mapping JPAQL/HQL queries"
- revision="1">
- <title>Mapping JPAQL/HQL queries</title>
-
- <para>You can map EJBQL/HQL queries using annotations.
- <literal>@NamedQuery</literal> and <literal>@NamedQueries</literal> can
- be defined at the class level or in a JPA XML file. However their
- definitions are global to the session factory/entity manager factory
- scope. A named query is defined by its name and the actual query
- string.</para>
-
- <programlisting><entity-mappings>
- <named-query name="plane.getAll">
- <query>select p from Plane p</query>
- </named-query>
- ...
-</entity-mappings>
-...
-
- at Entity
- at NamedQuery(name="night.moreRecentThan", query="select n from Night n where n.date >= :date")
-public class Night {
- ...
-}
-
-public class MyDao {
- doStuff() {
- Query q = s.getNamedQuery("night.moreRecentThan");
- q.setDate( "date", aMonthAgo );
- List results = q.list();
- ...
- }
- ...
-}
- </programlisting>
-
- <para>You can also provide some hints to a query through an array of
- <literal>QueryHint</literal> through a <literal>hints</literal>
- attribute.</para>
-
- <para>The availabe Hibernate hints are</para>
-
- <para></para>
-
- <table>
- <title>Query hints</title>
-
- <tgroup cols="2">
- <thead>
- <colspec colname="c1" />
-
- <colspec colname="c2" colnum="2" />
-
- <row>
- <entry>hint</entry>
-
- <entry colname="c2">descriptio