[hibernate-commits] Hibernate SVN: r19609 - core/trunk/documentation/manual/src/main/docbook/en-US/content.

[hibernate-commits at lists.jboss.org]

Author: steve.ebersole at 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.xml
Log:
HHH-5263 - Improve preface


Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.xml
===================================================================
--- 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 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.
+        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 a data representation from an object model
+        to a relational data model with a SQL-based schema;
+        see <ulink url="http://en.wikipedia.org/wiki/Object-relational_mapping"/> 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 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"/>
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        <ulink url="http://en.wikipedia.org/wiki/Data_modeling"/>
+                    </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 development 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 facilities. 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 common data persistence
-        related programming tasks. Hibernate may not be the best solution for data-centric
+        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