db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rsf...@apache.org
Subject cvs commit: db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/howtos howto-use-ojb-with-springframework.xml
Date Sun, 21 Nov 2004 17:29:30 GMT
rsfeir      2004/11/21 09:29:30

  Added:       src/doc/forrest/src/documentation/content/xdocs/docu/howtos
                        howto-use-ojb-with-springframework.xml
  Log:
  added new tutorial on how to use the SpringFramework with OJB
  
  Revision  Changes    Path
  1.1                  db-ojb/src/doc/forrest/src/documentation/content/xdocs/docu/howtos/howto-use-ojb-with-springframework.xml
  
  Index: howto-use-ojb-with-springframework.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Copyright 2002-2004 The Apache Software Foundation
  
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
  
        http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!-- @version $Id: howto-use-ojb-with-springframework.xml,v 1.1 2004/11/21 17:29:30 rsfeir
Exp $ -->
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
  
  <document>
      <header>
          <title>Using OJB with the Springframework - Getting Started</title>
          <authors>
              <person name="Robert S. Sfeir" email="rsfeir@apache.org"/>
          </authors>
      </header>
  
      <body>
          <section>
              <title>Using OJB with the Spring Framework - Getting Started</title>
              <section>
                  <title>Introduction</title>
                  <p>
                  You can spent the good part of a day working out the ins and outs of the
                      <a href="http://springframework.org/">Springframework</a>
and
                      <a href="http://db.apache.org/ojb/">OJB</a>.  There is a
fail level of handicap involved
                      while you up to speed with the Springframework, but once it's done and
working,
                      you will realize how simple it really is.
                  </p>
                  <p>
                  Here are some thoughts on how to setup the initial hooks between OJB and
Spring,
                  and how to make it work for your needs.</p>
                  <p>
                    This tutorial will:
                  </p>
  
                  <ol>
                      <li>Describe all the files involved in the process</li>
                      <li>Describe the OJB specific files you need</li>
                      <li>Show you where to put these files</li>
                      <li>Show how to edit the Springframework's applicationContext.xml</li>
                      <li>Show how to change the OJB.properties file for specific Springframework
needs.</li>
                  </ol>
                  <p>
                      This tutorial presumes you are comfortable configuring your relational
                      database of choice, including adding databases and users, and
                      configuring access controls at the database level (ie, you can create
a
                      database and user and give the user permission to access and change
the
                      database over a JDBC connection).  It assumes a fair level of comfort
with OJB, it won't
                      spell everything out for you.  It also assumes that you have Springframework
files downloaded
                      and setup.
                  </p>
                  <p>
                      For some help, setting up and running OJB in the traditional way
                      <a href="http://db.apache.org/ojb/docu/index.html">can be found
here</a>.
                      I highly recommend for anyone to take a look
                      <a href="http://db.apache.org/ojb/docu/guides/xdoclet-module.html">at
the xdoclet tutorial</a>
                      it will make your life much much easier in the long run in understanding
OJB.  I wish the xdoclet support existed when I started using OJB.
                  </p>
              </section>
  
              <section>
                  <title>Some Basics</title>
                  <p>
                      The Springframework approach essentially removes the complexities of
setting up transactions
                      and dealing with them properly.  There are a lot of instances where
you think you did the right
                      thing, only to find out that you didn't close a broker, or simply did
not setup a rollback point
                      if you encountered an exception.  In a way, Springframework has also
managed to simplify the
                      OJB configuration pieces also and integrated them really well with the
whole Framework.
                  </p>
                  <p>
                  Traditionally with OJB you'd have 2 main files to deal with:
                      <ul>
                          <li>1- repository.xml - contains ojb's internal schema, your
schema, and jdbc connection details.</li>
                          <li>2- OJB.properties - contains various settings to allow
ojb to find repository.xml, Collection, Pooling, and other settings to specify OJB's behavior.</li>
                      </ul>
                  With the Springframework approach this list grows a little.
                  </p>
                  <title>First Things First - Setup OJB</title>
                  <p>
                      Setup the OJB files where they need to go.  There is a specific set
of files OJB and Springframework need
                      to have to operate properly together.
                      <i>Note: This information can also be pulled together from looking
at the PetClinic Sample project in the
                      Springframework distribution.</i>
                  </p>
                  <p>
                      In your OJB distribution generate, or find the existing set of the following
files,
                      and place them in your &lt;web-root&gt;/WEB-INF directory:
                      <ul>
                          <li>repository.xml</li>
                          <li>OJB.properties</li>
                          <li>OJB-logging.properties</li>
                          <li>repository_internal.xml</li>
                      </ul>
                      Fetch the following libraries, you can find them in the &lt;ojb-root&gt;/lib
directory, and
                      place them in your &lt;web-root&gt;/WEB-INF/lib directory.
                      <ul>
                          <li>db-ojb-1.0.1.jar</li>
                          <li>commons-dbcp-1.1.jar</li>
                          <li>commons-lang-2.0.jar</li>
                          <li>commons-pool-1.1.jar</li>
                      </ul>
                      This concludes the piece of setting up the OJB part of the files in
the right locations.
                      You'll still need to edit the OJB.properties and respository.xml later.
                  </p>
                  <title>Setup The Spring Framework's applicationContext.xml</title>
                  <p>
                      The Springframework piece which sets things up to communicate with OJB
is fairly simple.
                      Springframework's setup file file is called applicationContext.xml,
at least it is by default and
                      will be for this example.
                  </p>
                  <p>
                      Find your applicationContext.xml file, and add the following lines to
the file, if you don't already
                      have them.  This information was copied from the sample apps the framework
comes with.  I added them
                      at the beginning of my applicationContext.xml file.
                  </p>
                  <p>
                      The first entry will serve to resolve property value pairs in a file
called jdbc.init,
                      as specified in the first block of XML.  We'll create the property file
shortly.
                      <br></br>
                      <code>
                          &lt;!-- Configurer that replaces ${...} placeholders with values
from a properties file --&gt;
                          &lt;!-- (in this case, OJB-related settings for the dataSource
definition below) --&gt;
                          &lt;bean id="propertyConfigurer" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"&gt;
                          &lt;property name="location">&lt;value>/WEB-INF/jdbc.properties&lt;/value&gt;&lt;/property&gt;
                          &lt;/bean&gt;
                          &lt;!-- Local DataSource that works in any environment --&gt;
                          &lt;bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource"&gt;
                          &lt;property name="driverClassName">&lt;value>${jdbc.driverClassName}&lt;/value&gt;&lt;/property&gt;
                          &lt;property name="url"&gt;&lt;value>${jdbc.url}&lt;/value&gt;&lt;/property&gt;
                          &lt;property name="username"&gt;&lt;value>${jdbc.username}&lt;/value&gt;&lt;/property&gt;
                          &lt;property name="password"&gt;&lt;value&gt;${jdbc.password}&lt;/value&gt;&lt;/property&gt;
                          &lt;/bean&gt;
                      </code>
                  </p>
                  <p>
                      The next block informs the Springframework which beans you intent to
use when you're instantiating
                      OJB and its transactions.
                      <br></br>
                      <code>
                          &lt;!-- Transaction manager --&gt;
                          &lt;!-- OJB configurer that allows to use LocalDataSourceConnectionFactory
in OJB.properties --&gt;
                          &lt;bean id="ojbConfigurer" class="org.springframework.orm.ojb.support.LocalOjbConfigurer"/&gt;
                          <br></br>
                          &lt;!-- Transaction manager for a single OJB PersistenceBroker
(alternative to JTA) --&gt;
                          &lt;bean id="transactionManager" class="org.springframework.orm.ojb.PersistenceBrokerTransactionManager"/&gt;
                      </code>
                      <br></br>
                      That's all you need to change in the applicationContext.xml in order
to get things hooked into your
                      bean, and getting your beans to make the proper calls.  An example of
what this would look like
                      in your code is:
                      <br></br>
                      <code>
                          &lt;bean id="userManager" class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean"&gt;
                          <b>&lt;property name="transactionManager"&gt;
                              &lt;ref local="transactionManager"/&gt;
                              &lt;/property&gt;</b>
                          &lt;property name="target"&gt;
                          &lt;ref local="userManagerTarget"/&gt;
                          &lt;/property&gt;
                          &lt;property name="transactionAttributes"&gt;
                          &lt;props&gt;
                          &lt;prop key="save*"&gt;PROPAGATION_REQUIRED&lt;/prop&gt;
                          &lt;prop key="remove*"&gt;PROPAGATION_REQUIRED&lt;/prop&gt;
                          &lt;prop key="*"&gt;PROPAGATION_REQUIRED,readOnly&lt;/prop&gt;
                          &lt;/props&gt;
                          &lt;/property&gt;
                          &lt;/bean&gt;
                      </code>
                  </p>
                  <p>
                      Now onto the jdbc.properties file.  This file will allow you to simply
setup the database
                      information in one location and share it across implementations.  This
case is particularly usefule
                      if you have an application which needs to support 2 different ORMs,
and having a file like
                      this helps a lot because you only need to set things up once and based
on the ORM impl you use once.
                  </p>
                  <p>
                      Create a jdbc.properties file and put the following in it, remembering
to replace the right values
                      for your username, password and database:
                      <br></br>
                      <code>
                      jdbc.driverClassName=org.postgresql.Driver
                      jdbc.url=jdbc:postgresql:myDB
                      jdbc.username=myUser
                      jdbc.password=myPassword
                      </code>
                      <br></br>
                      That's it, there is no OJB specific information which needs to go in
here.  If you were using
                      Hibernate you'd add a hibernate.dialect=... entry for your own DB in
the file and you'd be done.
                  </p>
                  <p>
                      Now place applicationContext.xml and jdbc.properties in your &lt;web
-root&gt;/WEB-INF directory.
                  </p>
              </section>
              <section>
                  <title>Configuring OJB repository.xml and OJB.properties</title>
                  <p>
                      Now, let's edit the OJB repository.xml and OJB.properties file to be
specific to the Springframework.
                      We first start with the repository.xml.
                  </p>
                  <p>
                      In Respository.xml add the following block of xml for your jdbc-connection-descritor
entry,
                      notice how the jcd-alias is called dataSource to match the applicationContext.xml
entry:
                      <br></br>
                      <code>
                          &lt;jdbc-connection-descriptor jcd-alias="dataSource" default-connection="true"
platform="PostgreSQL" jdbc-level="3.0" useAutoCommit="1"&gt;
                          &lt;connection-pool maxActive="10" maxIdle="2" maxWait="3" validationQuery=""
logAbandoned="true" removeAbandoned="true" removeAbandonedTimeout="8"/&gt;
                          &lt;sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerHighLowImpl"&gt;
                          &lt;attribute attribute-name="grabSize" attribute-value="5"/&gt;
                          &lt;attribute attribute-name="autoNaming" attribute-value="true"/&gt;
                          &lt;attribute attribute-name="globalSequenceId" attribute-value="false"/&gt;
                          &lt;attribute attribute-name="globalSequenceStart" attribute-value="1"/&gt;
                          &lt;/sequence-manager&gt;
                          &lt;/jdbc-connection-descriptor&gt;
                      </code>
                  </p>
                  <p>
                      <b>Now a word of caution:</b>
                      <i> I'm using the SequenceManagerHighLowImpl, but the PetClinic
is
                      using SequenceManagerNativeImpl.  The IDs generated by that implementation
was returning negative
                      numbers before a record was inserted, according to OJB documentation
this is because there needs
                      to be some kind of ID generated before the insert because we don't know
what the ID is going to be
                      in the DB, especially since not all DBs have a Sequence like Oracle
and Postgresql.  If you use
                      something like
                          <a href="http://dbunit.sourceforge.net/">db-unit</a>
to do your tests, the
                      SequenceManagerNativeImpl will make it more difficult for you, since
it will pose a bit of a
                      challenge to figure out which ID to select against in the DB once an
object is added, for example.
                      I found that in general the SequenceManagerHighLowImpl to work best
for all DBs, since OJB takes
                      care of maintaining and divvying out the IDs, and is what I've always
used when using OJB, though
                      if you use Oracle and Postgres for example you can use the SequenceManagerNextValImpl,
which relies
                      on the Sequences of those databases.  I didn't see anything in PetClinic
which indicated a reason
                      why they chose to use SequenceManagerNativeImpl, it is perhaps because
that implementation doesn't
                      require adding the extra OJB table required for the SequenceManagerHighLowImpl,
and it works for
                      their purpose.
                      </i>
                  </p>
                  <p>
                      On to editing the OJB.properties file.  There are 2 entries which need
to be looked at in here:
                      <ul>
                          <li>ConnectionFactoryClass value</li>
                          <li>ObjectCacheClass value</li>
                      </ul>
                      The ConnectionFactoryClass entry.
                      <br></br>
                      Find the line in your OJB.properties file which starts with ConnectionFactoryClass,
comment the
                      current ConnectionFactoryClass and add this:
                      <br></br>
                      <code>
                          ConnectionFactoryClass=org.springframework.orm.ojb.support.LocalDataSourceConnectionFactory
                      </code>
                      This will let OJB to delegate to the Springframework with a has factory
for Spring-managed
                      DataSource beans.  For more information on this look at
                      <a href="http://www.springframework.org/docs/api/org/springframework/orm/ojb/support/LocalDataSourceConnectionFactory.html">the
Springframework API</a>
                      <br></br>
                      The ObjectCacheClass entry.
                      <br></br>
                      Find the line in your OJB.properties file which starts with ObjectCacheClass,
comment the currently
                      used Implementation and uncomment this one:
                      <br></br>
                      <code>
                          ObjectCacheClass=org.apache.ojb.broker.cache.ObjectCachePerBrokerImpl
                      </code>
                  </p>
                  <p>
                      Believe it or not, that's it.  Add your beans and start working with
Springframeowork.
                      I won't go into a tutorial about how to do that, there are many sources
out there to do it.
                      The one thing I will say to help you out is that generally adding a
bean to use with OJB is
                      brainless, here is an example entry from an applicationContext.xml:
                      <br></br>
                      <code>
                          &lt;bean id="ojbUserDAO" name="userDAO" class="com.codepuccino.mesquite.dao.ojb.OJBUserDAO"/&gt;
                      </code>
                  </p>
              </section>
          </section>
      </body>
  </document>
  
  
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org


Mime
View raw message