<?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 preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent">
%BOOK_ENTITIES;

]>

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

    <para>
        Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming.
        Development costs are significantly higher due to a paradigm mismatch between how data is represented in
        objects versus relational databases.  Hibernate is an Object/Relational Mapping solution for Java environments.
        The term Object/Relational Mapping refers to the technique of mapping data from an object model representation
        to a relational data model representation (and visa versa).  See <ulink url="http://en.wikipedia.org/wiki/Object-relational_mapping"/>
        for a good high-level discussion.
    </para>

    <note>
        <para>
            While having a strong background in SQL is not required to use Hibernate, having a basic understanding of
            the concepts can greatly help you understand Hibernate more fully and quickly.  Probably the single
            best background is an understanding of data modeling principles.  You might want to consider these resources
            as a good starting point:
            <itemizedlist>
                <listitem>
                    <para>
                        <ulink url="http://www.agiledata.org/essays/dataModeling101.html">http://www.agiledata.org/essays/dataModeling101.html</ulink>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <ulink url="http://en.wikipedia.org/wiki/Data_modeling">http://en.wikipedia.org/wiki/Data_modeling</ulink>
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </note>

    <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. It can significantly reduce
        development time otherwise spent with manual data handling in SQL and JDBC.  Hibernate’s design goal is to
        relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for
        manual, hand-crafted data processing using SQL and JDBC.  However, unlike many other persistence solutions,
        Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology
        and knowledge is as valid as always.
    </para>

    <para>
        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="tutorial"/> for a tutorial with step-by-step
                instructions. The source code for the tutorial is included in the
                distribution in the <literal>doc/reference/tutorial/</literal>
                directory.
            </para>
        </listitem>
        <listitem>
            <para>
                Read <xref linkend="architecture"/> to understand the environments where
                Hibernate can be used.
            </para>
        </listitem>
        <listitem>
            <para>
                View 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 <biblioref linkend="biblio-JPwH"/>
                if you need more help with application design, or if you prefer
                a step-by-step tutorial. Also visit
                <ulink url="http://caveatemptor.hibernate.org"/> and download
                the example application from <biblioref linkend="biblio-JPwH"/>.
            </para>
        </listitem>
        <listitem>
            <para>
                FAQs are answered on the Hibernate website.
            </para>
        </listitem>
        <listitem>
            <para>
                Links to third party demos, examples, and tutorials are maintained
                on the Hibernate website.
            </para>
        </listitem>
        <listitem>
            <para>
                The Community Area on the Hibernate website is a good resource for
                design patterns and various integration solutions (Tomcat, JBoss AS,
                Struts, EJB, etc.).
            </para>
        </listitem>
     </orderedlist>

    <para>
        There are a number of ways to become involved in the Hibernate community, including
        <itemizedlist>
            <listitem>
                <para>
                    Trying stuff out and reporting bugs.  See
                    <ulink url="http://hibernate.org/issuetracker.html">http://hibernate.org/issuetracker.html</ulink>
                    details.
                </para>
            </listitem>
            <listitem>
                <para>
                    Trying your hand at fixing some bugs or implementing enhancements.  Again, see
                    <ulink url="http://hibernate.org/issuetracker.html">http://hibernate.org/issuetracker.html</ulink>
                    details.
                </para>
            </listitem>
            <listitem>
                <para>
                    <ulink url="http://hibernate.org/community.html">http://hibernate.org/community.html</ulink> list
                    a few ways to engage in the community.
                    <itemizedlist>
                        <listitem>
                            <para>
                                There are forums for users to ask questions and receive help from the community.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                There are also <ulink url="http://en.wikipedia.org/wiki/Internet_Relay_Chat">IRC</ulink>
                                channels for both user and developer discussions.
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </listitem>
            <listitem>
                <para>
                    Helping improve or translate this documentation.  Contact us on the developer mailing list
                    if you have interest.
                </para>
            </listitem>
            <listitem>
                <para>
                    Evangelizing Hibernate within your organization.
                </para>
            </listitem>
        </itemizedlist>
    </para>

</preface>
