hibernate-orm/reference/en/master.xml

<?xml version='1.0' encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
                      "../support/docbook-dtd/docbookx.dtd"
[
<!ENTITY quickstart             SYSTEM "modules/quickstart.xml">
<!ENTITY architecture           SYSTEM "modules/architecture.xml">
<!ENTITY configuration          SYSTEM "modules/configuration.xml">
<!ENTITY persistent-classes     SYSTEM "modules/persistent_classes.xml">
<!ENTITY basic-mapping          SYSTEM "modules/basic_mapping.xml">
<!ENTITY collection-mapping     SYSTEM "modules/collection_mapping.xml">
<!ENTITY component-mapping      SYSTEM "modules/component_mapping.xml">
<!ENTITY inheritance-mapping    SYSTEM "modules/inheritance_mapping.xml">
<!ENTITY manipulating-data      SYSTEM "modules/manipulating_data.xml">
<!ENTITY transactions           SYSTEM "modules/transactions.xml">
<!ENTITY query-hql              SYSTEM "modules/query_hql.xml">
<!ENTITY query-criteria         SYSTEM "modules/query_criteria.xml">
<!ENTITY query-sql              SYSTEM "modules/query_sql.xml">
<!ENTITY performance            SYSTEM "modules/performance.xml">
<!ENTITY toolset-guide          SYSTEM "modules/toolset_guide.xml">
<!ENTITY example-parentchild    SYSTEM "modules/example_parentchild.xml">
<!ENTITY example-weblog         SYSTEM "modules/example_weblog.xml">
<!ENTITY example-mappings       SYSTEM "modules/example_mappings.xml">
<!ENTITY best-practices         SYSTEM "modules/best_practices.xml">
]>

<book lang="en">

    <bookinfo>
        <title>HIBERNATE - Relational Persistence for Idiomatic Java</title>
        <subtitle>Hibernate Reference Documentation</subtitle>
        <releaseinfo>3.0 beta2</releaseinfo>
    </bookinfo>

    <toc/>

    <preface id="preface" revision="1">
        <title>Preface</title>

        <para>
            Working with object-oriented software and a relational database can be cumbersome
            and time consuming in today's enterprise environments. Hibernate is an object/relational
            mapping tool for Java environments. The term object/relational mapping (ORM) refers to
            the technique of mapping a data representation from an object model to a relational
            data model with a SQL-based schema.
        </para>

        <para>
            Hibernate not only takes care of the mapping from Java classes to
            database tables (and from Java data types to SQL data types), but also provides data
            query and retrieval facilities and can significantly reduce development time otherwise
            spent with manual data handling in SQL and JDBC.
        </para>

        <para>
            Hibernates goal is to relieve the developer from 95 percent of common data persistence
            related programming tasks. Hibernate may not be the best solution for data-centric
            applications that only use stored-procedures to implement the business logic in the
            database, it is most useful with object-oriented domain models and business logic in
            the Java-based middle-tier. However, Hibernate can certainly help you to remove or
            encapsulate vendor-specific SQL code and will help with the common task of result set
            translation from a tabular representation to a graph of objects.
        </para>

        <para>
            If you are new to Hibernate and Object/Relational Mapping or even Java,
            please follow these steps:
        </para>

        <orderedlist>
            <listitem>
                <para>
                    Read <xref linkend="quickstart"/> for a 30 minute tutorial, using Tomcat.
                </para>
            </listitem>
            <listitem>
                <para>
                    Read <xref linkend="architecture"/> to understand the environments where
                    Hibernate can be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    Have a look at the <literal>eg/</literal> directory in the Hibernate
                    distribution, it contains a simple standalone application. Copy your
                    JDBC driver to the <literal>lib/</literal> directory and edit
                    <literal>etc/hibernate.properties</literal>, specifying correct values for
                    your database. From a command prompt in the distribution directory,
                    type <literal>ant eg</literal> (using Ant), or under Windows, type
                    <literal>build eg</literal>.
                </para>
            </listitem>
            <listitem>
                <para>
                    Use this reference documentation as your primary source of information.
                    Consider reading <emphasis>Hibernate in Action</emphasis>
                    (http://www.manning.com/bauer) if you need more help with application
                    design or if you prefer a step-by-step tutorial. Also visit
                    http://caveatemptor.hibernate.org and download the example application
                    for Hibernate in Action.
                </para>
            </listitem>
            <listitem>
				<para>
					FAQs are answered on the Hibernate website.
				</para>
            </listitem>
			<listitem>
				<para>
					Third party demos, examples and tutorials are linked on the Hibernate
					website.
				</para>
			</listitem>
            <listitem>
                <para>
                    The Community Area on the Hibernate website is a good source for
                    design patterns and various integration solutions (Tomcat, JBoss, Spring,
                    Struts, EJB, etc.).
                </para>
            </listitem>
         </orderedlist>

         <para>
             If you have questions, use the user forum linked on the Hibernate website. We also
             provide a JIRA issue trackings system for bug reports and feature requests. If you
             are interested in the development of Hibernate, join the developer mailing list. If
             you are interested in translating this documentation into your language, contact us
             on the developer mailing list.
         </para>

         <para>
             Commercial development support, production support and training for Hibernate is
             available through JBoss Inc. (see http://www.hibernate.org/SupportTraining/).
             Hibernate is a project of the JBoss Professional Open Source product suite.
         </para>

    </preface>

    &quickstart;

    &architecture;

    &configuration;

    &persistent-classes;

    &basic-mapping;
    &collection-mapping;
    &component-mapping;
    &inheritance-mapping;

    &manipulating-data;
    &transactions;

    &query-hql;
    &query-criteria;
    &query-sql;

    &performance;

    &toolset-guide;

    &example-parentchild;
    &example-weblog;
    &example-mappings;

    &best-practices;

</book>