Hibernate example source code file (metamodel.xml)

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

Java - Hibernate tags/keywords

a, cdata, cdata, for, jpa2, jpa2, metamodel, metamodel, public, singularattribute, the, the, this, util, z

The Hibernate metamodel.xml source code

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

<chapter id="metamodel">
    <title>Metamodel

    <note>
        <para>
            The Metamodel itself is described in <citetitle pubwork="chapter">Chapter 5 Metamodel API
            of the <citation>.  Chapter 6 Criteria API
            of the <citation> describes and shows uses of the metamodel in criteria
            queries, as does <xref linkend="querycriteria"/>.
        </para>
    </note>

    <para>
        The metamodel is a set of objects that describe your domain model.
        <interfacename>javax.persistence.metamodel.Metamodel acts as a repository of these metamodel
        objects and provides access to them, and can be obtained from either the
        <interfacename>javax.persistence.EntityManagerFactory or the
        <interfacename>javax.persistence.EntityManager via their
        <methodname>getMetamodel method.
    </para>

    <para>
        This metamodel is important in 2 ways.  First, it allows providers and frameworks a generic way to
        deal with an application's domain model.  Persistence providers will already have some form of
        metamodel that they use to describe the domain model being mapped.  This API however defines a single,
        independent access to that existing information.  A validation framework, for example, could use this
        information to understand associations; a marshaling framework might use this information to decide how
        much of an entity graph to marshal.  This usage is beyond the scope of this documentation.
    </para>

    <important>
        <para>
            As of today the JPA 2 metamodel does not provide any facility for accessing relational information
            pertaining to the physical model.  It is expected this will be addressed in a future release of the
            specification.
        </para>
    </important>

    <para>
        Second, from an application writer's perspective, it allows very fluent expression of completely type-safe
        criteria queries, especially the <emphasis>Static Metamodel approach.  The
        <citation> defines a number of ways the metamodel can be accessed and used,
        including the <emphasis>Static Metamodel approach, which we will look at later.
        The <emphasis>Static Metamodel approach is wonderful when the code has
        <ulink url="http://en.wikipedia.org/wiki/A_priori_and_a_posteriori">a priori knowledge of the domain
        model.  <xref linkend="querycriteria"/> uses this approach exclusively in its examples.
    </para>

    <section id="metamodel-static">
        <title>Static metamodel
        <para>
            A <emphasis>static metamodel is a series of classes that "mirror" the entities and embeddables
            in the domain model and provide static access to the metadata about the mirrored class's attributes.  We
            will exclusively discuss what the <citation> terms a
            <emphasis>Canonical Metamodel:
        </para>

        <blockquote>
            <attribution>
                <citation>, section 6.2.1.1, pp 198-199
            </attribution>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            For each managed class <classname>X in package p,
                            a metamodel class <classname>X_ in package p is created.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            The name of the metamodel class is derived from the name of the managed class by appending
                           "_" to the name of the managed class.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            The metamodel class <classname>X_ must be annotated with the
                            <interfacename>javax.persistence.StaticMetamodelannotation
                            <footnote>
                                <para>
                                    <emphasis>(from the original) If the class was generated, the
                                    <interfacename>javax.annotation.Generated annotation should be
                                    used to annotate the class. The use of any other annotations on static metamodel
                                    classes is undefined.
                                </para>
                            </footnote>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            If class <classname>X extends another class S, where
                            <classname>S is the most derived managed class (i.e., entity or mapped
                            superclass) extended by <classname>X, then class X_ must
                            extend class <classname>S_, where S_ is the metamodel
                            class created for <classname>S.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            For every persistent non-collection-valued attribute <emphasis>y declared by
                            class <classname>X, where the type of y is
                            <classname>Y, the metamodel class must contain a declaration as follows:
                            <programlisting> y;]]>
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            For every persistent collection-valued attribute <emphasis>z declared by class
                            <classname>X, where the element type of z is
                            <classname>Z, the metamodel class must contain a declaration as follows:
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        if the collection type of <emphasis>z is
                                        <interfacename>java.util.Collection, then
                                        <programlisting> z;]]>
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        if the collection type of <emphasis>z is
                                        <interfacename>java.util.Set, then
                                        <programlisting> z;]]>
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        if the collection type of <emphasis>z is
                                        <interfacename>java.util.List, then
                                        <programlisting> z;]]>
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>
                                        if the collection type of <emphasis>z is
                                        <interfacename>java.util.Map, then
                                        <programlisting> z;]]>
                                        where <classname>K is the type of the key of the map in class
                                        <classname>X
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
            <para>
                Import statements must be included for the needed <package>javax.persistence.metamodel types
                as appropriate (e.g., <interfacename>javax.persistence.metamodel.SingularAttribute,
                <interfacename>javax.persistence.metamodel.CollectionAttribute,
                <interfacename>javax.persistence.metamodel.SetAttribute,
                <interfacename>javax.persistence.metamodel.ListAttribute,
                <interfacename>javax.persistence.metamodel.MapAttribute) and all classes
                <classname>X, Y, Z, and K.
            </para>
        </blockquote>

        <example id="metamodel-static-ex">
            <title>Static metamodel example
            <para>
                For the <classname>Person entity
                <programlisting>
                The corresponding canonical metamodel class, <classname>Person_ would look like
                <programlisting>
            </para>
        </example>

        <note>
            <para>
                These canonical metamodel classes can be generated manually if you wish though it is expected
                that most developers will prefer use of an <ulink url="&aptUrl;">annotation processor.
                Annotation processors themselves are beyond the scope of this document.  However, the Hibernate team
                does develop an annotation processor tool for generating a canonical metamodel.
                See <citetitle>Hibernate Metamodel Generator.
            </para>
        </note>

        <para>
            When the Hibernate <interfacename>EntityManagerFactory is being built, it will
            look for a canonical metamodel class for each of the managed typed is knows about and if it finds
            any it will inject the appropriate metamodel information into them, as outlined in
            <citation>, section 6.2.2, pg 200
        </para>
    </section>

</chapter>