From hibernate-commits at lists.jboss.org Tue May 25 16:45:27 2010
Content-Type: multipart/mixed; boundary="===============4869821361728441610=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r19609 -
 core/trunk/documentation/manual/src/main/docbook/en-US/content.
Date: Tue, 25 May 2010 16:45:27 -0400
Message-ID: <201005252045.o4PKjRTF022317@svn01.web.mwc.hst.phx2.redhat.com>

--===============4869821361728441610==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: steve.ebersole(a)jboss.com
Date: 2010-05-25 16:45:26 -0400 (Tue, 25 May 2010)
New Revision: 19609

Modified:
   core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.x=
ml
Log:
HHH-5263 - Improve preface


Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/pr=
eface.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.=
xml	2010-05-25 20:30:50 UTC (rev 19608)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.=
xml	2010-05-25 20:45:26 UTC (rev 19609)
@@ -2,10 +2,10 @@
 <!--
   ~ Hibernate, Relational Persistence for Idiomatic Java
   ~
-  ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors=
 as
+  ~ 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 Middleware LLC.
+  ~ 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
@@ -33,23 +33,50 @@
     <title>Preface</title>
 =

     <para>
-        Working with object-oriented software and a relational database ca=
n be cumbersome
-        and time consuming in today's enterprise environments. Hibernate i=
s an Object/Relational
-        Mapping tool for Java environments. The term Object/Relational Map=
ping (ORM) refers to
-        the technique of mapping a data representation from an object mode=
l to a relational
-        data model with a SQL-based schema.
+        Working with both Object-Oriented software and Relational Database=
s can be cumbersome and time consuming.
+        Development costs are significantly higher due to a paradigm misma=
tch between how data is represented in
+        objects versus relational databases.  Hibernate is an Object/Relat=
ional Mapping solution for Java environments.
+        The term Object/Relational Mapping refers to the technique of mapp=
ing a data representation from an object model
+        to a relational data model with a SQL-based schema;
+        see <ulink url=3D"http://en.wikipedia.org/wiki/Object-relational_m=
apping"/> for a 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 fu=
lly and quickly.  Probably the single
+            best background is an understanding of data modeling principle=
s.  You might want to consider these resources
+            as a good starting point:
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        <ulink url=3D"http://www.agiledata.org/essays/data=
Modeling101.html"/>
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <ulink url=3D"http://en.wikipedia.org/wiki/Data_mo=
deling"/>
+                    </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 also significantly reduce d=
evelopment time otherwise
-        spent with manual data handling in SQL and JDBC.
+        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 facili=
ties. It can also significantly reduce
+        development time otherwise spent with manual data handling in SQL =
and JDBC.
     </para>
 =

     <para>
-        Hibernate's goal is to relieve the developer from 95 percent of co=
mmon data persistence
-        related programming tasks. Hibernate may not be the best solution =
for data-centric
+        Hibernate=E2=80=99s design goal is to relieve the developer from 9=
5% of common data persistence-related programming
+        tasks by eliminating the need for manual, hand-crafted data proces=
sing using SQL and JDBC.  However, unlike
+        many other persistence solutions, Hibernate does not hide the powe=
r of SQL from you and guarantees that your
+        investment in relational technology and knowledge is as valid as a=
lways.
+    </para>
+
+    <para>
+        Hibernate may not be the best solution for data-centric
         applications that only use stored-procedures to implement the busi=
ness 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


--===============4869821361728441610==--