Author: steve.ebersole(a)jboss.com Date: 2010-09-11 15:18:00 -0400 (Sat, 11 Sep 2010) New Revision: 20623 Added: core/trunk/documentation/devguide/src/main/docbook/en-US/content/preface.xml core/trunk/documentation/devguide/src/main/docbook/en-US/images/ core/trunk/documentation/devguide/src/main/docbook/en-US/images/hibernate_logo_a.png Modified: core/trunk/documentation/devguide/src/main/docbook/en-US/Hibernate_Developer_Guide.xml core/trunk/documentation/devguide/src/main/docbook/en-US/content/database.xml Log: HHH-5468 - Write a chapter about setting up database access Modified: core/trunk/documentation/devguide/src/main/docbook/en-US/Hibernate_Developer_Guide.xml =================================================================== --- core/trunk/documentation/devguide/src/main/docbook/en-US/Hibernate_Developer_Guide.xml 2010-09-11 15:38:28 UTC (rev 20622) +++ core/trunk/documentation/devguide/src/main/docbook/en-US/Hibernate_Developer_Guide.xml 2010-09-11 19:18:00 UTC (rev 20623) @@ -6,9 +6,8 @@ <book> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml" /> - <!-- todo : preface once solidified in getting started guide... + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/preface.xml" /> - --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/database.xml" /> Modified: core/trunk/documentation/devguide/src/main/docbook/en-US/content/database.xml =================================================================== --- core/trunk/documentation/devguide/src/main/docbook/en-US/content/database.xml 2010-09-11 15:38:28 UTC (rev 20622) +++ core/trunk/documentation/devguide/src/main/docbook/en-US/content/database.xml 2010-09-11 19:18:00 UTC (rev 20623) @@ -75,10 +75,18 @@ <section id="hibernate-dev-database-connect-pools-c3p0"> <title>Using c3p0 for connection pooling</title> + <para> + <!-- todo : what exactly needs discussed here? --> + To be continued... + </para> </section> <section id="hibernate-dev-database-connect-pools-proxool"> <title>Using proxool for connection pooling</title> + <para> + <!-- todo : what exactly needs discussed here? --> + To be continued... + </para> </section> </section> @@ -110,10 +118,74 @@ <section id="hibernate-dev-database-dialect"> <title>Database Dialects</title> + <para> + A <firstterm><phrase>Dialect</phrase></firstterm> informs Hibernate of the capabilities of the + underlying database. This role is fulfilled by an instance of a + <classname>org.hibernate.dialect.Dialect</classname> subclass. The Dialect is one of the most important + pieces of information given to the Hibernate <interfacename>org.hibernate.Sessionfactory</interfacename> + during startup as it allows Hibernate to properly plan how it needs to communicate with the database. + </para> + + <section id="hibernate-dev-database-dialect-config"> + <title>Specifying the Dialect to use</title> + <para> + The developer may manually specify the Dialect to use by setting the + <property>hibernate.dialect</property> configuration property to the name of the specific + <classname>org.hibernate.dialect.Dialect</classname> class to use. + </para> + </section> + + <section id="hibernate-dev-database-dialect-resolution"> + <title>Dialect resolution</title> + <para> + Assuming a <interfacename>org.hibernate.connection.ConnectionProvider</interfacename> has been + set up according to <xref linkend="hibernate-dev-database-connect"/> then Hibernate will attempt + to automatically determine the Dialect to use based on the + <interfacename>java.sql.DatabaseMetaData</interfacename> reported by a + <interfacename>java.sql.Connection</interfacename> obtained from that + <interfacename>org.hibernate.connection.ConnectionProvider</interfacename>. + </para> + <para> + This functionality is provided by a series of + <interfacename>org.hibernate.dialect.resolver.DialectResolver</interfacename> instances registered + with Hibernate internally. Hibernate comes with a standard set of recognitions. If your application + requires extra Dialect resolution capabilities, it would simply register a custom implementation + of <interfacename>org.hibernate.dialect.resolver.DialectResolver</interfacename> as follows + </para> + <example id="hibernate-dev-database-dialect-resolution-registration"> + <title>Registering a custom <interfacename>org.hibernate.dialect.resolver.DialectResolver</interfacename></title> + <programlisting role="JAVA"><![CDATA[ + org.hibernate.dialect.resolver.DialectFactory.registerDialectResolver( "org.hibernate.example.CustomDialectResolver" ); +]]></programlisting> + </example> + <para> + Registered <interfacename>org.hibernate.dialect.resolver.DialectResolver</interfacename> are + <emphasis>prepended</emphasis> to an internal list of resolvers, so they take precedence + before any already registered resolvers including the standard one. + </para> + </section> + + <section id="hibernate-dev-database-dialect-custom"> + <title>Custom Dialects</title> + <para> + It is sometimes necessary for developers to write a custom Dialect for Hibernate to use. Generally + this is as simple as selecting a particular <classname>org.hibernate.dialect.Dialect</classname> + implementation that is closest to your needs and subclassing it and overriding where necessary. + </para> + <para> + Custom dialects may be manually specified as outlined in + <xref linkend="hibernate-dev-database-dialect-config"/> as well as registered through a resolver as + outlined in <xref linkend="hibernate-dev-database-dialect-resolution-registration"/>. + </para> + </section> </section> <section id="hiberate-dev-database-schema"> <title>Database Schema</title> + <para> + <!-- todo : what exactly needs discussed here? --> + To be continued... + </para> </section> </chapter> \ No newline at end of file Added: core/trunk/documentation/devguide/src/main/docbook/en-US/content/preface.xml =================================================================== --- core/trunk/documentation/devguide/src/main/docbook/en-US/content/preface.xml (rev 0) +++ core/trunk/documentation/devguide/src/main/docbook/en-US/content/preface.xml 2010-09-11 19:18:00 UTC (rev 20623) @@ -0,0 +1,133 @@ +<?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_Getting_Started_Guide.ent"> +%BOOK_ENTITIES; + +]> + +<preface id="hibernate-gsg-preface"> + <title>Preface</title> + + <!-- + NOTE : This duplicates a lot of the information in the manual preface. This is a great example of where the + "content reuse" capabilities of DITA could be leveraged. + --> + + <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"/> + </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 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> + + <section> + <title>Get Involved</title> + <itemizedlist> + <listitem> + <para> + Use Hibernate and report any bugs or issues you find. See + <ulink url="http://hibernate.org/issuetracker.html"/> for details. + </para> + </listitem> + <listitem> + <para> + Try your hand at fixing some bugs or implementing enhancements. Again, see + <ulink url="http://hibernate.org/issuetracker.html"/>;. + </para> + </listitem> + <listitem> + <para> + Engage with the community using mailing lists, forums, IRC, or other ways listed at + <ulink url="http://hibernate.org/community.html"/>;. + </para> + </listitem> + <listitem> + <para> + Help improve or translate this documentation. Contact us on + the developer mailing list if you have interest. + </para> + </listitem> + <listitem> + <para> + Spread the word. Let the rest of your organization know about the benefits of + Hibernate.<!-- I didn't like 'evangelize'. Too many religious overtones. I'd like something stronger than this though. I'll have a think. --> + </para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Getting Started Guide</title> + <para> + New users may want to first look through the + <citetitle pubwork="book">Hibernate Getting Started Guide</citetitle> for basic information as well as + tutorials. Even seasoned veterans may want to considering perusing the sections pertaining to + build artifacts for any changes. + </para> + </section> +</preface> Added: core/trunk/documentation/devguide/src/main/docbook/en-US/images/hibernate_logo_a.png =================================================================== (Binary files differ) Property changes on: core/trunk/documentation/devguide/src/main/docbook/en-US/images/hibernate_logo_a.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream