[hibernate-commits] Hibernate SVN: r20623 - in core/trunk/documentation/devguide/src/main/docbook/en-US: content and 1 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Sat Sep 11 15:18:01 EDT 2010
Author: steve.ebersole at 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
More information about the hibernate-commits
mailing list