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>
|
<book>
|
||||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml" />
|
<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/preface.xml" />
|
||||||
-->
|
|
||||||
|
|
||||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/database.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">
|
<section id="hibernate-dev-database-connect-pools-c3p0">
|
||||||
<title>Using c3p0 for connection pooling</title>
|
<title>Using c3p0 for connection pooling</title>
|
||||||
|
<para>
|
||||||
|
<!-- todo : what exactly needs discussed here? -->
|
||||||
|
To be continued...
|
||||||
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section id="hibernate-dev-database-connect-pools-proxool">
|
<section id="hibernate-dev-database-connect-pools-proxool">
|
||||||
<title>Using proxool for connection pooling</title>
|
<title>Using proxool for connection pooling</title>
|
||||||
|
<para>
|
||||||
|
<!-- todo : what exactly needs discussed here? -->
|
||||||
|
To be continued...
|
||||||
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
@ -110,10 +118,74 @@
|
||||||
|
|
||||||
<section id="hibernate-dev-database-dialect">
|
<section id="hibernate-dev-database-dialect">
|
||||||
<title>Database Dialects</title>
|
<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>
|
||||||
|
|
||||||
<section id="hiberate-dev-database-schema">
|
<section id="hiberate-dev-database-schema">
|
||||||
<title>Database Schema</title>
|
<title>Database Schema</title>
|
||||||
|
<para>
|
||||||
|
<!-- todo : what exactly needs discussed here? -->
|
||||||
|
To be continued...
|
||||||
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
</chapter>
|
</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