HHH-5468 - Write a chapter about setting up database access
git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20623 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole
parent
0ac3d23979
commit
7803cb5b81
|
|
@ -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" />
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Loading…
Reference in New Issue