You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ojb-dev@db.apache.org by ol...@apache.org on 2002/12/02 18:21:19 UTC
cvs commit: jakarta-ojb/src/test/org/apache/ojb OJB.properties
olegnitz 2002/12/02 09:21:19
Modified: src/test/org/apache/ojb OJB.properties
Log:
added the BatchMode paremeter that allows to turn on or off the batch mode for ODMG
Revision Changes Path
1.33 +5 -1 jakarta-ojb/src/test/org/apache/ojb/OJB.properties
Index: OJB.properties
===================================================================
RCS file: /home/cvs/jakarta-ojb/src/test/org/apache/ojb/OJB.properties,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -r1.32 -r1.33
--- OJB.properties 29 Nov 2002 17:41:04 -0000 1.32
+++ OJB.properties 2 Dec 2002 17:21:19 -0000 1.33
@@ -264,6 +264,10 @@
#LockAssociations=READ
LockAssociations=WRITE
#
+# The BatchMode entry defines if batch updates will be used to improve
+# performance.
+BatchMode=true
+#
#
#----------------------------------------------------------------------------------------
# Logging
@@ -405,4 +409,4 @@
#
#----------------------------------------------------------------------------------------
# End of OJB.properties file
-#----------------------------------------------------------------------------------------
\ No newline at end of file
+#----------------------------------------------------------------------------------------
Re: Patch for tutorial1.xml
Posted by Thomas Mahler <th...@apache.org>.
Hi Tim,
O'brien, Tim wrote:
> Good catches Antony, see below.... I'm going to submit a patch in a sec.
>
> OJB commiters, do you prefer email patches or patches via Scarab? (I'm
> partial to patches via email because they do often spark a good discussion
> like the one below, but I found out recently that the Struts proejcts likes
> to have all patches submitted via Bugzilla.)
>
Currently it's better to post patches via email. I'm currently working
on getting Scarab to post emails to the developer list. Once this works
we should use scarab alone for changes requests, bug reports, fixes etc.
I'll keep you updated.
>
>>-----Original Message-----
>>From: Antony S. Kraievoy [mailto:archvile@ukr.net]
>
>
>>[PersistenceBroker tutorial/deleting objects subpart/useCase code
>>sample] contains this line:
>>
>> >Query query = new QueryByExample(example);
>>
>
>
>>From what I see QueryByExample is not in the current release of OJB, but it
> was in OJB 0.9.4. My own confusion stemmed from the fact that the Javadoc
> on the site was pointing to the 0.9.4 release. This is fixed in tutorial1
> for the patch.
>
>
>>don't know why, but this part of docs is too wide for IE & NS browsers
>>at 1024x768 resolution.
>
>
> I have the same problem, when I run the "xslt" task in build.xml, I get a
> site that looks dramatically different from the published site, I'm not sure
> how this can be fixed. Anyone?
>
>
>>[ODMG API tutorial/updating object subpart/useCase code sample]
>>
>> >tx.lock(toBeEdited, tx.WRITE);
>>
>>the WRITE field is static - i think there should be
>>
>> tx.lock(toBeEdited, Transaction.WRITE);
>
>
> Referencing a public static constant through an instance variable is covered
> by Section 10.2 in Sun's Code Conventions.
> http://java.sun.com/docs/codeconv/html/CodeConventions.doc9.html#587, not
> that we should necessarily conform to Sun's standards, but I've found it a
> good practice.
>
> I fixed this in the patch in tutorial2 and the faq.
>
>
>>call to lock(...,...) may raise LockNotGrantedException
>>
>>by the way, indentation of this piece of code makes me think
>>that there
>>WAS some try/catch block :)
>
>
> It is something that could cause issues, I added a try/catch back to that
> code example, just so that someone doesn't run into the same problem down
> the road. You'll notice that I added catch block with a comment "removed
> for brevity", is this a good solution?
>
>
>>[FAQ\I don't like OQL, can I use the PersistenceBroker
>>Queries within ODMG?] >If you have a look at
>>org.apache.ojb.odmg.oql.OqlQueryImpl.execute()
>>you will see ...
>> this class is named org.apache.ojb.odmg.oql.OQLQueryImpl
>
>
> I looked at this, and changed it to "the <code>execute()</code> method in
> <code>org.apache.ojb.odmg.oql.OqlQueryImpl</code>". I didn't find it
> generally confusing in the original form, but I can see how it might be
> visually confusing.
>
>
>
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
>
>
Re: thoughts on patches and Scarab (was RE: Patch for tutorial1.xml)
Posted by Thomas Mahler <th...@apache.org>.
Hi all,
J. Russell Smyth wrote:
> I am not a commiter, but I tend to supply my 2c anyway!
>
> I would think that a central source like the scarab instance would
> serve better as you would simply have to go there and look for
> un-applied patches, rather than dig through mailing list messages
> and hope they dont get missed.
+1
We are looking for a good change management system for a very long time
now. Now that scarab performance is much better I'm confident that it
will do a good job for us.
> Thomas is trying to get the scarab instance configured properly to
> mail the list when an issue is changed, so once that is done putting
> items in scarab would be just as effective as sending to the list, plus
> add tracking to the patch.
+1
> I know that the OJB commiters are not completely used to using the
> Scarab system yet, but I think as it starts to see more use, it will
> help improve the OJB project even more by providing a central resource
> for bug reports and resolution.
>
> Of course for this to work does require all of the scarab commiters to
> "commit" to use of the scarab system and that they try to review what is
> there on a regular basis and apply any usefull/needed/good patches.
Once developers detect that something is really helping them and not
just adding overhead they will use it.
So I hope that by getting around the last remaining scarab problems
(emailing to the list, custom issue types, etc.) we will see that scarab
get's part of our day by day development job.
cheers,
Thomas
> Russell
>
>
> On Sat, 2002-12-07 at 12:58, O'brien, Tim wrote:
>
>>Good catches Antony, see below.... I'm going to submit a patch in a sec.
>>
>>OJB commiters, do you prefer email patches or patches via Scarab? (I'm
>>partial to patches via email because they do often spark a good discussion
>>like the one below, but I found out recently that the Struts proejcts likes
>>to have all patches submitted via Bugzilla.)
>>
>>
>>>-----Original Message-----
>>>From: Antony S. Kraievoy [mailto:archvile@ukr.net]
>>
>>>[PersistenceBroker tutorial/deleting objects subpart/useCase code
>>>sample] contains this line:
>>>
>>> >Query query = new QueryByExample(example);
>>>
>>
>>>From what I see QueryByExample is not in the current release of OJB, but it
>>was in OJB 0.9.4. My own confusion stemmed from the fact that the Javadoc
>>on the site was pointing to the 0.9.4 release. This is fixed in tutorial1
>>for the patch.
>>
>>
>>>don't know why, but this part of docs is too wide for IE & NS browsers
>>>at 1024x768 resolution.
>>
>>I have the same problem, when I run the "xslt" task in build.xml, I get a
>>site that looks dramatically different from the published site, I'm not sure
>>how this can be fixed. Anyone?
>>
>>
>>>[ODMG API tutorial/updating object subpart/useCase code sample]
>>>
>>> >tx.lock(toBeEdited, tx.WRITE);
>>>
>>>the WRITE field is static - i think there should be
>>>
>>> tx.lock(toBeEdited, Transaction.WRITE);
>>
>>Referencing a public static constant through an instance variable is covered
>>by Section 10.2 in Sun's Code Conventions.
>>http://java.sun.com/docs/codeconv/html/CodeConventions.doc9.html#587, not
>>that we should necessarily conform to Sun's standards, but I've found it a
>>good practice.
>>
>>I fixed this in the patch in tutorial2 and the faq.
>>
>>
>>>call to lock(...,...) may raise LockNotGrantedException
>>>
>>>by the way, indentation of this piece of code makes me think
>>>that there
>>>WAS some try/catch block :)
>>
>>It is something that could cause issues, I added a try/catch back to that
>>code example, just so that someone doesn't run into the same problem down
>>the road. You'll notice that I added catch block with a comment "removed
>>for brevity", is this a good solution?
>>
>>
>>>[FAQ\I don't like OQL, can I use the PersistenceBroker
>>>Queries within ODMG?] >If you have a look at
>>>org.apache.ojb.odmg.oql.OqlQueryImpl.execute()
>>>you will see ...
>>> this class is named org.apache.ojb.odmg.oql.OQLQueryImpl
>>
>>I looked at this, and changed it to "the <code>execute()</code> method in
>><code>org.apache.ojb.odmg.oql.OqlQueryImpl</code>". I didn't find it
>>generally confusing in the original form, but I can see how it might be
>>visually confusing.
>>
>>
>>
>>
>>--
>>To unsubscribe, e-mail: <ma...@jakarta.apache.org>
>>For additional commands, e-mail: <ma...@jakarta.apache.org>
>>
>
>
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
>
>
thoughts on patches and Scarab (was RE: Patch for tutorial1.xml)
Posted by "J. Russell Smyth" <dr...@cox.net>.
I am not a commiter, but I tend to supply my 2c anyway!
I would think that a central source like the scarab instance would
serve better as you would simply have to go there and look for
un-applied patches, rather than dig through mailing list messages
and hope they dont get missed.
Thomas is trying to get the scarab instance configured properly to
mail the list when an issue is changed, so once that is done putting
items in scarab would be just as effective as sending to the list, plus
add tracking to the patch.
I know that the OJB commiters are not completely used to using the
Scarab system yet, but I think as it starts to see more use, it will
help improve the OJB project even more by providing a central resource
for bug reports and resolution.
Of course for this to work does require all of the scarab commiters to
"commit" to use of the scarab system and that they try to review what is
there on a regular basis and apply any usefull/needed/good patches.
Russell
On Sat, 2002-12-07 at 12:58, O'brien, Tim wrote:
> Good catches Antony, see below.... I'm going to submit a patch in a sec.
>
> OJB commiters, do you prefer email patches or patches via Scarab? (I'm
> partial to patches via email because they do often spark a good discussion
> like the one below, but I found out recently that the Struts proejcts likes
> to have all patches submitted via Bugzilla.)
>
> > -----Original Message-----
> > From: Antony S. Kraievoy [mailto:archvile@ukr.net]
>
> > [PersistenceBroker tutorial/deleting objects subpart/useCase code
> > sample] contains this line:
> >
> > >Query query = new QueryByExample(example);
> >
>
> >From what I see QueryByExample is not in the current release of OJB, but it
> was in OJB 0.9.4. My own confusion stemmed from the fact that the Javadoc
> on the site was pointing to the 0.9.4 release. This is fixed in tutorial1
> for the patch.
>
> > don't know why, but this part of docs is too wide for IE & NS browsers
> > at 1024x768 resolution.
>
> I have the same problem, when I run the "xslt" task in build.xml, I get a
> site that looks dramatically different from the published site, I'm not sure
> how this can be fixed. Anyone?
>
> > [ODMG API tutorial/updating object subpart/useCase code sample]
> >
> > >tx.lock(toBeEdited, tx.WRITE);
> >
> > the WRITE field is static - i think there should be
> >
> > tx.lock(toBeEdited, Transaction.WRITE);
>
> Referencing a public static constant through an instance variable is covered
> by Section 10.2 in Sun's Code Conventions.
> http://java.sun.com/docs/codeconv/html/CodeConventions.doc9.html#587, not
> that we should necessarily conform to Sun's standards, but I've found it a
> good practice.
>
> I fixed this in the patch in tutorial2 and the faq.
>
> >
> > call to lock(...,...) may raise LockNotGrantedException
> >
> > by the way, indentation of this piece of code makes me think
> > that there
> > WAS some try/catch block :)
>
> It is something that could cause issues, I added a try/catch back to that
> code example, just so that someone doesn't run into the same problem down
> the road. You'll notice that I added catch block with a comment "removed
> for brevity", is this a good solution?
>
> > [FAQ\I don't like OQL, can I use the PersistenceBroker
> > Queries within ODMG?] >If you have a look at
> > org.apache.ojb.odmg.oql.OqlQueryImpl.execute()
> > you will see ...
> > this class is named org.apache.ojb.odmg.oql.OQLQueryImpl
>
> I looked at this, and changed it to "the <code>execute()</code> method in
> <code>org.apache.ojb.odmg.oql.OqlQueryImpl</code>". I didn't find it
> generally confusing in the original form, but I can see how it might be
> visually confusing.
>
>
>
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
RE: Patch for tutorial1.xml
Posted by .
Good catches Antony, see below.... I'm going to submit a patch in a sec.
OJB commiters, do you prefer email patches or patches via Scarab? (I'm
partial to patches via email because they do often spark a good discussion
like the one below, but I found out recently that the Struts proejcts likes
to have all patches submitted via Bugzilla.)
> -----Original Message-----
> From: Antony S. Kraievoy [mailto:archvile@ukr.net]
> [PersistenceBroker tutorial/deleting objects subpart/useCase code
> sample] contains this line:
>
> >Query query = new QueryByExample(example);
>
Re: Patch for tutorial1.xml
Posted by "Antony S. Kraievoy" <ar...@ukr.net>.
O'brien, Tim wrote:
> Here is a patch for tutorial1, I'm only half done refactoring the
> grammar and refining some of the language, but I thought I'd submit
> something sooner rather than later.
>
hi
this might be helpful, i read docs downloaded a bit more than a month
ago, and some inconsistencies were found while reading OJB docs - these
things just bothered me a little while i wrote my first OJB-based code:
[PersistenceBroker tutorial/deleting objects subpart/useCase code
sample] contains this line:
>Query query = new QueryByExample(example);
left from some older versions of docs? I think should be this:
Query query = new QueryByIdentity(example);
don't know why, but this part of docs is too wide for IE & NS browsers
at 1024x768 resolution.
[ODMG API tutorial/updating object subpart/useCase code sample]
>tx.lock(toBeEdited, tx.WRITE);
the WRITE field is static - i think there should be
tx.lock(toBeEdited, Transaction.WRITE);
sometimes these useCases do not catch exceptions that could be raised
and do not declare
them to be trown out from apply() method... look at the
[ODMG API tutorial / storing object subpart / useCase code sample]
>// 4. acquire write lock on new object
>tx.lock(newProduct, tx.WRITE);
call to lock(...,...) may raise LockNotGrantedException
by the way, indentation of this piece of code makes me think that there
WAS some try/catch block :)
> // now perform persistence operations
> Transaction tx = null;
> // 3. open transaction
> tx = odmg.newTransaction();
> tx.begin();
>
> // 4. acquire write lock on new object
> tx.lock(newProduct, tx.WRITE);
>
> // 5. commit transaction
> tx.commit();
[JavaDoc/org/odmg/Transaction.html#begin()]
here javadoc text tells me some scary stories about exceptions that
could be raised - but sources and
autogenerated parts of javadoc specify none of them.
[FAQ\I don't like OQL, can I use the PersistenceBroker Queries within ODMG?]
>If you have a look at org.apache.ojb.odmg.oql.OqlQueryImpl.execute()
you will see ...
this class is named org.apache.ojb.odmg.oql.OQLQueryImpl
Best regards
AV
Re: Patch for tutorial1, tutorial2, faq, and site.xsl
Posted by Thomas Mahler <th...@apache.org>.
Hi again Tim
O'brien, Tim wrote:
> Here is a patch for some docs..
>
> ** site.xsl
>
> - If a section or subsection has an "anchor" parameter that is used in the
> <a name.../>. The system was using @name in the anchor name, and for
> something like FAQ where the section and subsection names are so large it
> was not desirable to have to reference FAQ entries with the entire question.
> There is an xsl:choose in the variable declaration which will ensure that
> existing pages do not break.
>
> QUESTION: It doesn't look like site.vsl or site_printable.vsl are being
> referenced in jakarta-ojb, is this correct?
>
The OJB website is generated by MAVEN. I provided the site.xsl only to
have a convenient way to build the documentation fast and without Maven
installed. Now that Maven (and the OJB Maven scripts) have improved a
lot site.xsl is somewhat obsolete.
> ** tutorial1
>
> - Removed references to QueryByExample, replaced them with QueryByCriteria
> - Added in an example showing a complex QueryByCriteria example.
> - incremental grammar, spelling
>
> ** tutorial2
>
> - Added a try/catch around tx.lock().
> - Change reference to static member variable tx.WRITE -> Transaction.WRITE
> - incremental grammar, spelling
>
> ** faq
>
> - Added an unordered list that links to all questions.
> - Improved wording of first question.
> - Changed tx.READ to Transaction.READ
> - incremental grammar, spelling
>
Thanks for the patches. I'll check them in !
cheers,
Thomas
>
> --------
> Tim O'Brien
> Transolutions, Inc.
> W 847-574-2143
> M 847-863-7045
>
>
>
> ------------------------------------------------------------------------
>
> Index: xdocs/faq.xml
> ===================================================================
> RCS file: /home/cvspublic/jakarta-ojb/xdocs/faq.xml,v
> retrieving revision 1.9
> diff -u -r1.9 faq.xml
> --- xdocs/faq.xml 29 Jul 2002 15:28:50 -0000 1.9
> +++ xdocs/faq.xml 7 Dec 2002 20:07:12 -0000
> @@ -1,131 +1,142 @@
> <?xml version="1.0"?>
> <document>
>
> - <properties>
> - <author email="thma@apache.org">Thomas Mahler</author>
> - <title>ObJectRelationalBridge FAQ</title>
> - </properties>
> -
> -<body>
> -
> -<section name="frequently asked questions">
> -
> -<subsection name="Help! I don't get OJB installed!">
> - <ul>
> - <li>
> - Please read the document <a href="quickstart.html">quickstart.html</a>.
> - </li>
> - <li>
> - Be sure to follow all steps mentioned in that document.
> - </li>
> - <li>
> - Don't try to use any shortcuts. Don't try to do it in a
> - somewhat different way.
> - </li>
> - <li>
> - Read the respective documentation before you try to
> - <a href="platforms.html">run OJB against your target database</a>
> - and before you try to
> - <a href="deployment.html">deploy OJB within your specific target environment</a>.
> - </li>
> - </ul>
> -</subsection>
> -
> -<subsection name="Help! I still don't get OJB installed!">
> -<p>
> - The following answer is quoted from the OJB user-list. It is from a
> - reply to a user who had serious troubles in getting started with OJB.
> -</p>
> -<p>
> - I would say it was stupid not to understand OJB. How can you know what
> - another programmer wrote. I've been a Java programmer for quite some time
> - and I could show you stuff I wrote that I know you wouldn't understand.
> - I'll just break it down the best I can on what, where and why.
> -</p>
> -<p>
> - OJB is a data persistence layer for Java. I'll just use an example of how I
> - use it. I have an RDMS. I would like to save Java object states to this
> - database and I would like to be able to search this information as well. If
> - you serialize objects it's hard to search and if you use SQL it won't work
> - with any different database. Plus it's a mess having to work with all that
> - SQL in your code. And by using SQL you don't get to work with just Java
> - objects. But, with OJB your separated from having to work outside the
> - object world and unlike serialization you can preform SQL like searches on
> - your data. Also, there's things like caching and connection pooling in OJB
> - that help with performance. After setting up OJB you will us either ODMG or
> - JDO to access your information in a object centric manner. ODMG is a
> - standard for the api for accessing your data. That means you can use any
> - ODMG compliant api if you don't want to use OJB. The JDO part is like ODMG
> - except it's the SUN JDO standard. I use ODMG because the JDO interface is
> - not ready yet.
> -</p>
> -<p>
> - OJB is easy to use. I'll just break it down into two sides. There's the
> - side your writing your code for your application and there's the side that
> - you configure to make OJB connect to your database. Starting with your
> - application side, all that is needed is to use the interface you wish. I
> - use ODMG because JDO is not complete yet. Here's a link to the ODMG part
> - with some code for examples. http://jakarta.apache.org/ojb/tutorial2.html
> - That's all you need on the application side. Next there's the configuration
> - side. This is the one your fighting with. Here you need to setup the core
> - tables for OJB and you will define the classes you wish to store in your
> - database.
> -</p>
> -<p>
> - First thing to do is to build the cvs's with the default database HSQL,
> - because you know it will work. If you get past this point you should have a
> - working OJB compiled. Now if your using JDK 1.4 you will need to set in
> - build.properties JDBC=+JDBC30 and do a build.sh preprocess first. Next you
> - will do a build.sh junit and this will build OJB and test everything for
> - you. If you get a build successful then your in business. Then you will
> - want to run build.sh jar to create the OJB jar to put in your /lib. You
> - will need a couple other jars in you /lib directory to make it all work.
> - See this page for those. http://jakarta.apache.org/ojb/deployment.html
> -</p>
> -<p>
> - Next you will need some xml and configuration files in your class path for
> - OJB. You will find those files under {$OJB_base_dir}/target/test/ojb. All
> - the repository.xml's and OJB.properties for sure. With all these files in
> - place with your application you should be ready to use OJB and start
> - writing your application.
> -</p>
> -<p>
> - Finally you will want to setup your connection to your database and define
> - your classes you will be storing in your database. In the repository.xml
> - file you can configure your JDBC parameters so OJB can connect to your
> - database. You will also need your JDBC jar somewhere in your class path.
> - Then you will define your classes in the repository_user.xml file. Look
> - here for examples. http://jakarta.apache.org/ojb/tutorial1.html Note you
> - will want to comment out the junit part in repository.xml because it's just
> - for testing.
> -</p>
> -<p>
> - The final thing to do is to make sure the OJB core tables are in your
> - database. Look on this page for the core tables.
> - http://jakarta.apache.org/ojb/platforms.html. These core tables are used by
> - OJB to store internal data while it's running. It needs these. Then there's
> - the tables you define. The ones you mapped in the repository_user.xml file.
> -</p>
> -<p>
> - Sorry if any of this is off. OJB is growing so fast that it's hard to keep
> - up with all changes. The order I gave the steps in is just how I would
> - think it's understood better. You can go in any order you want. The steps
> - I've shown are mostly for deployment. Hope this helps you understand OJB a
> - little better. I'm not sure if this is what your wanting or not.
> -</p>
> -</subsection>
> -
> -
> -
> -<subsection name="Why OJB, why yet another O/R mapping tool?">
> -<p>
> - here are some outstanding OJB features:
> - <ul>
> - <li>It's fully ODMG 3.0 compliant</li>
> - <li>It will have a full JDO implementation</li>
> - <li>It's higly scalable (Loadbalanced Multiserver scenario)</li>
> - <li>It provides multiple APIs:
> - <ul>
> + <properties>
> + <author email="thma@apache.org">Thomas Mahler</author>
> + <author email="tobrien@transolutions.net">Tim O'Brien</author>
> + <title>ObJectRelationalBridge FAQ</title>
> + </properties>
> +
> + <body>
> +
> + <section name="Frequently Asked Questions" anchor="faq">
> + <ul>
> + <li><a href="#1">Help! I'm having problems installing and using OJB!</a></li>
> + <li><a href="#2">Help! I still have serious problems installing OJB!</a></li>
> + <li><a href="#3">Why OJB? Why do we need another O/R mapping tool?</a></li>
> + <li><a href="#4">Does OJB support my RDBMS?</a></li>
> + <li><a href="#5">How to use OJB with my RDBMS?</a></li>
> + <li><a href="#6">How to page and sort?</a></li>
> + <li><a href="#7">What about performance and memory usage if thousands of objects matching a query are returned as a Collection?</a></li>
> + <li><a href="#8">How is OJB related to ODMG and JDO?</a></li>
> + <li><a href="#9">What are the differences between the PersistenceBroker API and the ODMG API? Which one should I use in my applications?</a></li>
> + <li><a href="#10">What are the OJB internal tables for?</a></li>
> + <li><a href="#11">When is it helpful to use Proxy Classes?</a></li>
> + <li><a href="#12">How can I convert data between RDBMS and OJB?</a></li>
> + <li><a href="#13">How can I trace and/or profile SQL statements executed by OJB?</a></li>
> + <li><a href="#14">How does OJB manage foreign keys?</a></li>
> + <li><a href="#15">I don't like OQL, can I use the PersistenceBroker Queries within ODMG?</a></li>
> + <li><a href="#16">The OJB JDO implementation is not finished, how can I start using OJB?</a></li>
> + </ul>
> +
> + <subsection name="Help! I'm having problems installing and using OJB!" anchor="1">
> + <p>
> + Please read the <a href="quickstart.html">OJB Quick Start</a> document. OJB is a
> + powerful and complex system - installing and configuring OJB is not a trivial task.
> + Be sure to follow <b>all the steps</b> mentioned in that document - don't skip any steps
> + when first installing OJB on your systems.
> + </p>
> + <p>
> + If you are having problems running OJB against your target database, read the
> + respective <a href="platforms.html">platform documentation</a>. Before you
> + try to deploy OJB to your environment, read the
> + <a href="deployment.html">deployment guide</a>.
> + </p>
> + </subsection>
> +
> + <subsection name="Help! I still have serious problems installing OJB!" anchor="2">
> + <p>
> + The following answer is quoted from the OJB user-list. It is from a
> + reply to a user who had serious problems getting started with OJB.
> + </p>
> + <p>
> + I would say it was stupid not to understand OJB. How can you know what
> + another programmer wrote. I've been a Java programmer for quite some time
> + and I could show you stuff I wrote that I know you wouldn't understand.
> + I'll just break it down the best I can on what, where and why.
> + </p>
> + <p>
> + OJB is a data persistence layer for Java. I'll just use an example of how I
> + use it. I have an RDMS. I would like to save Java object states to this
> + database and I would like to be able to search this information as well. If
> + you serialize objects it's hard to search and if you use SQL it won't work
> + with any different database. Plus it's a mess having to work with all that
> + SQL in your code. And by using SQL you don't get to work with just Java
> + objects. But, with OJB your separated from having to work outside the
> + object world and unlike serialization you can preform SQL like searches on
> + your data. Also, there's things like caching and connection pooling in OJB
> + that help with performance. After setting up OJB you will us either ODMG or
> + JDO to access your information in a object centric manner. ODMG is a
> + standard for the api for accessing your data. That means you can use any
> + ODMG compliant api if you don't want to use OJB. The JDO part is like ODMG
> + except it's the SUN JDO standard. I use ODMG because the JDO interface is
> + not ready yet.
> + </p>
> + <p>
> + OJB is easy to use. I'll just break it down into two sides. There's the
> + side your writing your code for your application and there's the side that
> + you configure to make OJB connect to your database. Starting with your
> + application side, all that is needed is to use the interface you wish. I
> + use ODMG because JDO is not complete yet. Here's a link to the ODMG part
> + with some code for examples. http://jakarta.apache.org/ojb/tutorial2.html
> + That's all you need on the application side. Next there's the configuration
> + side. This is the one your fighting with. Here you need to setup the core
> + tables for OJB and you will define the classes you wish to store in your
> + database.
> + </p>
> + <p>
> + First thing to do is to build the cvs's with the default database HSQL,
> + because you know it will work. If you get past this point you should have a
> + working OJB compiled. Now if your using JDK 1.4 you will need to set in
> + build.properties JDBC=+JDBC30 and do a build.sh preprocess first. Next you
> + will do a build.sh junit and this will build OJB and test everything for
> + you. If you get a build successful then your in business. Then you will
> + want to run build.sh jar to create the OJB jar to put in your /lib. You
> + will need a couple other jars in you /lib directory to make it all work.
> + See this page for those. http://jakarta.apache.org/ojb/deployment.html
> + </p>
> + <p>
> + Next you will need some xml and configuration files in your class path for
> + OJB. You will find those files under {$OJB_base_dir}/target/test/ojb. All
> + the repository.xml's and OJB.properties for sure. With all these files in
> + place with your application you should be ready to use OJB and start
> + writing your application.
> + </p>
> + <p>
> + Finally you will want to setup your connection to your database and define
> + your classes you will be storing in your database. In the repository.xml
> + file you can configure your JDBC parameters so OJB can connect to your
> + database. You will also need your JDBC jar somewhere in your class path.
> + Then you will define your classes in the repository_user.xml file. Look
> + here for examples. http://jakarta.apache.org/ojb/tutorial1.html Note you
> + will want to comment out the junit part in repository.xml because it's just
> + for testing.
> + </p>
> + <p>
> + The final thing to do is to make sure the OJB core tables are in your
> + database. Look on this page for the core tables.
> + http://jakarta.apache.org/ojb/platforms.html. These core tables are used by
> + OJB to store internal data while it's running. It needs these. Then there's
> + the tables you define. The ones you mapped in the repository_user.xml file.
> + </p>
> + <p>
> + Sorry if any of this is off. OJB is growing so fast that it's hard to keep
> + up with all changes. The order I gave the steps in is just how I would
> + think it's understood better. You can go in any order you want. The steps
> + I've shown are mostly for deployment. Hope this helps you understand OJB a
> + little better. I'm not sure if this is what your wanting or not.
> + </p>
> + </subsection>
> +
> + <subsection name="Why OJB? Why do we need another O/R mapping tool?" anchor="3">
> + <p>
> + here are some outstanding OJB features:
> + <ul>
> + <li>It's fully ODMG 3.0 compliant</li>
> + <li>It will have a full JDO implementation</li>
> + <li>It's higly scalable (Loadbalanced Multiserver scenario)</li>
> + <li>It provides multiple APIs:
> + <ul>
> <li>The full fledged ODMG-API,</li>
> <li>The JDO API (planned) </li>
> <li>
> @@ -133,108 +144,108 @@
> kernel which can be used to build higher level APIs (like the ODMG and
> JDO Implementations)
> </li>
> - </ul>
> - </li>
> - <li>It's able to handle multible RDBMS simultaneously.</li>
> - <li>
> - it has a slick MetaLevel Architecture: By changing the MetaData at runtime
> - you can change the O/R mapping behaviour. (E.G. turning on/off usage of
> - Proxies.)
> - </li>
> - <li>
> - It has a simple CacheMechanisms that is fully garbage collectable by usage
> - of weak references.
> - </li>
> - <li>It has a simple and clean pattern based design.</li>
> - <li>
> - It uses a configurable plugin concept. This allows to replace components
> - (e.g. the ObjectCache) by user defined Replacements.
> - </li>
> - <li>
> - It has a modular architecture (you can quite easily reuse some components
> - in your own applications if you don't want to use the whole thing:
> - <ul>
> - <li>The PersistenceBroker (e.g. to build your own PersistenceManager)</li>
> + </ul>
> + </li>
> + <li>It's able to handle multiple RDBMS simultaneously.</li>
> + <li>
> + it has a slick MetaLevel Architecture: By changing the MetaData at runtime
> + you can change the O/R mapping behaviour. (E.G. turning on/off usage of
> + Proxies.)
> + </li>
> + <li>
> + It has a simple CacheMechanisms that is fully garbage collectable by usage
> + of weak references.
> + </li>
> + <li>It has a simple and clean pattern based design.</li>
> + <li>
> + It uses a configurable plugin concept. This allows to replace components
> + (e.g. the ObjectCache) by user defined Replacements.
> + </li>
> + <li>
> + It has a modular architecture (you can quite easily reuse some components
> + in your own applications if you don't want to use the whole thing:
> + <ul>
> + <li>The PersistenceBroker (e.g. to build your own PersistenceManager)</li>
> <li>The Query Interface as an abstract query syntax</li>
> <li>The OQL Parser</li>
> <li>The MetaData Layer</li>
> <li>The JDBC Accesslayer</li>
> - </ul>
> - </li>
> - <li>
> - It has a very sharp focus: It's concerned with O/R mapping and nothing
> - else.
> - </li>
> - </ul>
> -
> - Before making OJB an OpenSource project I had a look around at the
> - emerging OpenSource O/R scene and was asking myself if there is
> - really a need for yet another O/R tool.
> -</p>
> -<p>
> - I came to the conclusion that there was a need for OJB because:
> - <ul>
> - <li>There was no ODMG/JDO compliant opensource tool available</li>
> - <li>There was no scalable opensource O/R tool available</li>
> - <li>
> - there was no tool available with the idea of a PersistenceBroker Kernel
> - that could be easiliy extended
> - </li>
> - <li>The tools available had no dynamic MetaData architectures.</li>
> - <li>
> - The tools available were not as clearly designed as I hoped,
> - thus extending one of them would have been very difficult.
> - </li>
> - </ul>
> -</p>
> -</subsection>
> -
> -<subsection name="Does OJB support my RDBMS?">
> - <p>
> - <A HREF="platforms.html">please refer to this document</A>.
> - </p>
> -</subsection>
> -
> -<subsection name="How to use OJB with my RDBMS?">
> - <p>
> - <A HREF="platforms.html">please refer to this document</A>.
> - </p>
> -</subsection>
> -
> -<subsection name="How to page and sort?">
> - <p>
> - Sorting can be configured by
> - org.apache.ojb.broker.query.Criteria::orderBy(column_name).
> - </p>
> - <p>
> - There is no paging support in OJB. OJB is concerned with Object/Relational
> - mapping and not with application specific presentation details like
> - presenting a scrollable page of items.
> - </p>
> - <p>
> - OJB returns query results as Collections or Iterators.
> - </p>
> - <p>
> - You can easily implement your partial display of result data by using an
> - Iterator as returned by ojb.broker.PersistenceBroker::getIteratorByQuery(...).
> - </p>
> -</subsection>
> -
> -<subsection name="What about performance and memory usage if thousands of
> -objects matching a query are returned as a Collection?">
> - <p>
> - You can do two things to enhance performance if you have to process queries
> - that produce thousands of result objects:
> - </p>
> - <ol>
> - <li>
> + </ul>
> + </li>
> + <li>
> + It has a very sharp focus: It's concerned with O/R mapping and nothing
> + else.
> + </li>
> + </ul>
> +
> + Before making OJB an OpenSource project I had a look around at the
> + emerging OpenSource O/R scene and was asking myself if there is
> + really a need for yet another O/R tool.
> + </p>
> + <p>
> + I came to the conclusion that there was a need for OJB because:
> + <ul>
> + <li>There was no ODMG/JDO compliant opensource tool available</li>
> + <li>There was no scalable opensource O/R tool available</li>
> + <li>
> + there was no tool available with the idea of a PersistenceBroker Kernel
> + that could be easiliy extended
> + </li>
> + <li>The tools available had no dynamic MetaData architectures.</li>
> + <li>
> + The tools available were not as clearly designed as I hoped,
> + thus extending one of them would have been very difficult.
> + </li>
> + </ul>
> + </p>
> + </subsection>
> +
> + <subsection name="Does OJB support my RDBMS?" anchor="4">
> + <p>
> + <A HREF="platforms.html">please refer to this document</A>.
> + </p>
> + </subsection>
> +
> + <subsection name="How to use OJB with my RDBMS?" anchor="5">
> + <p>
> + <A HREF="platforms.html">please refer to this document</A>.
> + </p>
> + </subsection>
> +
> + <subsection name="How to page and sort?" anchor="6">
> + <p>
> + Sorting can be configured by
> + org.apache.ojb.broker.query.Criteria::orderBy(column_name).
> + </p>
> + <p>
> + There is no paging support in OJB. OJB is concerned with Object/Relational
> + mapping and not with application specific presentation details like
> + presenting a scrollable page of items.
> + </p>
> + <p>
> + OJB returns query results as Collections or Iterators.
> + </p>
> + <p>
> + You can easily implement your partial display of result data by using an
> + Iterator as returned by ojb.broker.PersistenceBroker::getIteratorByQuery(...).
> + </p>
> + </subsection>
> +
> + <subsection name="What about performance and memory usage if thousands of
> + objects matching a query are returned as a Collection?" anchor="7">
> + <p>
> + You can do two things to enhance performance if you have to process queries
> + that produce thousands of result objects:
> + </p>
> + <ol>
> + <li>
> Use getIteratorByQuery() rather than getCollectionByQuery().
> The returned Iterator is lazy and does not materialize Objects in
> advance.Objects are only materialized if you call the Iterators
> next() method. Thus you have total control about when and how many
> Objects get materialized!
> - </li>
> - <li>
> + </li>
> + <li>
> You can define Proxy Objects as placeholder for your
> persistent business objects. Proxys are lighweight objects that
> contain only primary key information. Thus their materialization is
> @@ -244,252 +255,246 @@
> are accessed directly. Thus you can build similar lazy paging as
> with the Iterator. You will find examples in the packages
> test.ojb.broker
> - </li>
> - </ol>
> - <p>
> - The Perfomance of 1. will be better than 2. This approach will
> - also work for VERY large resultsets, as there are no references to
> - result objects that would prevent their garbage collectability.
> - </p>
> -</subsection>
> -
> -<subsection name="How is OJB related to ODMG and JDO?">
> - <p>
> - ODMG is a standard API for Object Persistence specified by the ODMG
> - consortium (www.odmg.org).
> - JDO is Sun's API specification for Object Persistence. ODMG may
> - well be regarded as a Precursor to JDO.
> - In fact JDO incorporates
> - many ideas from ODMG and several people who have been involved in
> - the ODMG spec are now in the JDO team.
> - <br/>
> - I assume JDO will have
> - tremendous influence on OODBMS-, RDBMS-, J2EE-server and O/R-tool-vendors
> - to provide compliant products.
> - <br/>
> - OJB wants to provide first class support for JDO and ODMG APIs.
> - </p>
> - <p>
> - OJB currently contains of four main layers, each with its own API:
> - <ol>
> -
> - <li>
> - A low-level <b>PersistenceBroker</b> API which serves as the OJB persistence
> - kernel. The PersistenceBroker also provides a scalable
> - multi-server architecture that allows to used it in heavy-duty
> - app-server scenarios.
> - <br/>
> - This API can also be used directly by applications that don't need full
> - fledged object level transactions (see <a href="tutorial1.html">
> - tutorial1</a> for details).
> - </li>
> -
> - <li>
> - An Object Transaction Manager (OTM) layer that contains all features that
> - JDO and ODMG have in common as Object level transactions, lock-management,
> - instance lifecyle etc.
> - (See <a href="jdo-proposal.html">jdo-proposal.html</a> for details.)
> - The OTM is work in progress.
> - </li>
> -
> - <li>
> - A full featured <b>ODMG 3.0</b> compliant API. (See <a href="tutorial2.html">
> - tutorial2</a> for an introduction.)
> - <br/> Currently this API is implemented on top the PersistenceBroker. Once the
> - OTM layer is finished ODMG will be implemented on top of OTM.
> - </li>
> -
> - <li>
> - A <b>JDO</b> compliant API. This is work in progress.
> - (See <a href="tutorial4.html">
> - tutorial4</a> for an introduction.)
> - <br/> Currently this API is implemented on top the PersistenceBroker. Once the
> - OTM layer is finished JDO will be implemented on top of OTM.
> -
> - </li>
> -
> + </li>
> </ol>
> - </p>
> -
> <p>
> - The following graphics shows the layering of these APIs. Please note that the
> - layers coloured in yellow are not yet implemented.
> - <center>
> - <img src="images/ojb-layers.png"/>
> - </center>
> - </p>
> + The Perfomance of 1. will be better than 2. This approach will
> + also work for VERY large resultsets, as there are no references to
> + result objects that would prevent their garbage collectability.
> + </p>
> + </subsection>
>
> + <subsection name="How is OJB related to ODMG and JDO?" anchor="8">
> + <p>
> + ODMG is a standard API for Object Persistence specified by the ODMG
> + consortium (www.odmg.org).
> + JDO is Sun's API specification for Object Persistence. ODMG may
> + well be regarded as a Precursor to JDO.
> + In fact JDO incorporates
> + many ideas from ODMG and several people who have been involved in
> + the ODMG spec are now in the JDO team.
> + <br/>
> + I assume JDO will have
> + tremendous influence on OODBMS-, RDBMS-, J2EE-server and O/R-tool-vendors
> + to provide compliant products.
> + <br/>
> + OJB wants to provide first class support for JDO and ODMG APIs.
> + </p>
> + <p>
> + OJB currently contains of four main layers, each with its own API:
> + <ol>
> + <li>
> + A low-level <b>PersistenceBroker</b> API which serves as the OJB persistence
> + kernel. The PersistenceBroker also provides a scalable
> + multi-server architecture that allows to used it in heavy-duty
> + app-server scenarios.
> + <br/>
> + This API can also be used directly by applications that don't need full
> + fledged object level transactions (see <a href="tutorial1.html">
> + tutorial1</a> for details).
> + </li>
> +
> + <li>
> + An Object Transaction Manager (OTM) layer that contains all features that
> + JDO and ODMG have in common as Object level transactions, lock-management,
> + instance lifecyle etc.
> + (See <a href="jdo-proposal.html">jdo-proposal.html</a> for details.)
> + The OTM is work in progress.
> + </li>
> +
> + <li>
> + A full featured <b>ODMG 3.0</b> compliant API. (See <a href="tutorial2.html">
> + tutorial2</a> for an introduction.)
> + <br/> Currently this API is implemented on top the PersistenceBroker. Once the
> + OTM layer is finished ODMG will be implemented on top of OTM.
> + </li>
> +
> + <li>
> + A <b>JDO</b> compliant API. This is work in progress.
> + (See <a href="tutorial4.html">
> + tutorial4</a> for an introduction.)
> + <br/> Currently this API is implemented on top the PersistenceBroker. Once the
> + OTM layer is finished JDO will be implemented on top of OTM.
> + </li>
> +
> + </ol>
> + </p>
>
> + <p>
> + The following graphics shows the layering of these APIs. Please note that the
> + layers coloured in yellow are not yet implemented.
> + <center>
> + <img src="images/ojb-layers.png"/>
> + </center>
> + </p>
>
> -</subsection>
> + </subsection>
>
> -<subsection name="What are the differences between the PersistenceBroker API and
> -the ODMG API? Which one should I use in my applications?">
> - <p>
> - The PersistenceBroker (PB) provides a minimal API for transparent
> - persistence:
> - <ul>
> + <subsection name="What are the differences between the PersistenceBroker API and
> + the ODMG API? Which one should I use in my applications?" anchor="9">
> + <p>
> + The PersistenceBroker (PB) provides a minimal API for transparent
> + persistence:
> + <ul>
> <li>O/R mapping</li>
> <li>Retrieval of objects with a simple query interface from RDBMS</li>
> <li>storing (insert, update) of objects to RDBMS</li>
> <li>deleting of objects from RDBMS</li>
> - </ul>
> - </p>
> - <p>This is all you need for simple applications as in tutorial1.</p>
> - <p>
> - The OJB ODMG implementation uses the PB as its persistence kernel.
> - But it provides much more functionality to the application developer.
> - ODMG is a full fledged API for Object Persistence, including:
> - <ul>
> + </ul>
> + </p>
> + <p>This is all you need for simple applications as in tutorial1.</p>
> + <p>
> + The OJB ODMG implementation uses the PB as its persistence kernel.
> + But it provides much more functionality to the application developer.
> + ODMG is a full fledged API for Object Persistence, including:
> + <ul>
> <li>OQL Query interface</li>
> <li>real Object Transactions</li>
> <li>
> - A Locking Mechanism for management of concurrent threads (apps)
> - accessing the same objects
> + A Locking Mechanism for management of concurrent threads (apps)
> + accessing the same objects
> </li>
> <li>predefined persistent capable Collections and Hashtables</li>
> - </ul>
> - </p>
> - <p>
> - Some examples explaining the implications of these functional differences:
> - <ol>
> + </ul>
> + </p>
> + <p>
> + Some examples explaining the implications of these functional differences:
> + <ol>
> <li>
> - Say you use the PB to query an object O that has a collection
> - attribute col with five elements a,b,c,d,e. Next you delete Objects
> - d and e from col and store O again with
> - PersistenceBroker.store(O);<br/>
> - PB will store the remaining objects a,b,c. But it will not delete d and
> - e ! If you then requery object O it will again contain a,b,c,d,e !!!<br/>
> - The PB keeps no transactional state of the persistent Objects, thus it
> - does not know that d and e have to be deleted. (as a side note: deletion
> - of d and e could also be an error, as there might be references to them
> - from other objects !!!)<br/>
> - Using ODMG for the above scenario will eliminate all trouble: Objects
> - are registered to a transaction so that on commit of the transaction it
> - knows that d and e do not longer belong to the collection. the ODMG
> - collection will not delete the objects d and e but only the REFERENCES
> - from the collection to those objects!
> - </li>
> - <li>
> - Say you have two threads (applications) that try to access
> - and modify the same object O. The PB has no means to check whether
> - objects are used by concurrent threads. Thus it has no locking
> - facilities. You can get all kind of trouble by this situation. The
> - ODMG implementation has a Lockmanager that is capable of
> - synchronizing concurrent threads. You can even use four transaction
> - isolation levels:<br/>read-uncommitted, read-committed,
> - repeatable-read, serializable.
> + Say you use the PB to query an object O that has a collection
> + attribute col with five elements a,b,c,d,e. Next you delete Objects
> + d and e from col and store O again with
> + PersistenceBroker.store(O);<br/>
> + PB will store the remaining objects a,b,c. But it will not delete d and
> + e ! If you then requery object O it will again contain a,b,c,d,e !!!<br/>
> + The PB keeps no transactional state of the persistent Objects, thus it
> + does not know that d and e have to be deleted. (as a side note: deletion
> + of d and e could also be an error, as there might be references to them
> + from other objects !!!)<br/>
> + Using ODMG for the above scenario will eliminate all trouble: Objects
> + are registered to a transaction so that on commit of the transaction it
> + knows that d and e do not longer belong to the collection. the ODMG
> + collection will not delete the objects d and e but only the REFERENCES
> + from the collection to those objects!
> </li>
> - </ol>
> - </p>
> - <p>
> - In my eyes the PB is a persistence kernel that can be used to
> - build high-level PersistenceManagers like an ODMG or JDO
> - implementation. It can also be used to write simple applications, but
> - you have to do all management things (locking, tracking objects
> - state, object transactions) on your own.
> - </p>
> -</subsection>
> -
> -<subsection name="what are the OJB internal tables for?">
> - <p>
> - <a href="platforms.html">please refer to this document</a>.
> - </p>
> -</subsection>
> -
> -<subsection name="When is it helpful to use Proxy Classes?">
> - <p>
> - Proxy classes can be used for "lazy loading" aka
> - "lazy materialization". Using Proxy classes can help you in
> - reducing unneccessary db lookups. Example:
> - </p>
> - <p>
> - Say you load a ProductGroup object from the db which contains a
> - collection of 15 Article objects.
> - </p>
> - <p>
> - Without proxies all 15 Article objects are immediately loaded from
> - the db, even if you are not interested in them but just want to
> - lookup the description-attribute of the ProductGroup object.
> - </p>
> - <p>
> - With a proxy class, the collection is filled with 15 proxy
> - objects, that implement the same interface as the "real objects"
> - but contain only an OID and a void reference.
> - </p>
> - <p>
> - Once you access such a proxy object it loads its "real
> - subject" by OID and delegates the method call to it.
> - </p>
> - <p>
> - have a look at <A HREF="tutorial3.html">tutorial3.html</A>.
> - This document has a large section on proxies.
> - </p>
> -</subsection>
> -
> -<subsection name="How can I convert data between RDBMS and OJB?">
> - <p>
> - For Example I have a DB column of type INTEGER but a class atribute of type
> - boolean. How can I provide an automatic mapping with OJB?
> - </p>
> - <p>
> - OJB provides a concept of ConversionStrategies that can be used for such
> - conversion tasks. <A HREF="jdbc-types.html">Have a look at the respective
> - document</A>.
> - </p>
> -</subsection>
> -
> -
> -<subsection name="How can I trace and/or profile SQL statements executed by OJB?">
> - <p>
> - OJB ships with out of the box support for P6Spy.
> + <li>
> + Say you have two threads (applications) that try to access
> + and modify the same object O. The PB has no means to check whether
> + objects are used by concurrent threads. Thus it has no locking
> + facilities. You can get all kind of trouble by this situation. The
> + ODMG implementation has a Lockmanager that is capable of
> + synchronizing concurrent threads. You can even use four transaction
> + isolation levels:<br/>read-uncommitted, read-committed,
> + repeatable-read, serializable.
> + </li>
> + </ol>
> + </p>
> + <p>
> + In my eyes the PB is a persistence kernel that can be used to
> + build high-level PersistenceManagers like an ODMG or JDO
> + implementation. It can also be used to write simple applications, but
> + you have to do all management things (locking, tracking objects
> + state, object transactions) on your own.
> + </p>
> + </subsection>
> +
> + <subsection name="What are the OJB internal tables for?" anchor="10">
> + <p>
> + <a href="platforms.html">please refer to this document</a>.
> + </p>
> + </subsection>
> +
> + <subsection name="When is it helpful to use Proxy Classes?" anchor="11">
> + <p>
> + Proxy classes can be used for "lazy loading" aka
> + "lazy materialization". Using Proxy classes can help you in
> + reducing unneccessary db lookups. Example:
> + </p>
> + <p>
> + Say you load a ProductGroup object from the db which contains a
> + collection of 15 Article objects.
> + </p>
> + <p>
> + Without proxies all 15 Article objects are immediately loaded from
> + the db, even if you are not interested in them but just want to
> + lookup the description-attribute of the ProductGroup object.
> + </p>
> + <p>
> + With a proxy class, the collection is filled with 15 proxy
> + objects, that implement the same interface as the "real objects"
> + but contain only an OID and a void reference.
> + </p>
> + <p>
> + Once you access such a proxy object it loads its "real
> + subject" by OID and delegates the method call to it.
> + </p>
> + <p>
> + have a look at <A HREF="tutorial3.html">tutorial3.html</A>.
> + This document has a large section on proxies.
> + </p>
> + </subsection>
> +
> + <subsection name="How can I convert data between RDBMS and OJB?" anchor="12">
> + <p>
> + For Example I have a DB column of type INTEGER but a class atribute of type
> + boolean. How can I provide an automatic mapping with OJB?
> + </p>
> + <p>
> + OJB provides a concept of ConversionStrategies that can be used for such
> + conversion tasks. <A HREF="jdbc-types.html">Have a look at the respective
> + document</A>.
> + </p>
> + </subsection>
> +
> +
> + <subsection name="How can I trace and/or profile SQL statements executed by OJB?" anchor="13">
> + <p>
> + OJB ships with out of the box support for P6Spy.
> P6Spy is a JDBC proxy. It delegates all JDBC calls to the
> real JDBC driver and traces all calls to a log file.
> - </p>
> - <p>
> - In the file <code>build.properties</code> you have to set the switch
> + </p>
> + <p>
> + In the file <code>build.properties</code> you have to set the switch
> <code>useP6Spy</code> to <code>true</code> in order to activate it:
> - </p>
> - <source>
> + </p>
> + <source>
> # The useP6Spy switch determines if the tracing JDBC driver P6Spy is used.
> # If you enable this switch, you must also edit the file
> # jakarta-ojb/src/test/org/apache/ojb/spy.properties
> # to tell P6Spy which JDBC driver to use and where to write the log.
> # By default the HSQLDB driver is used.
> useP6Spy=true
> - </source>
> - <p>
> + </source>
> + <p>
> This setup uses P6Spy to trace and profile all executed
> - SQL to a file <code>target/test/ojb/spy.log</code>.
> + SQL to a file <code>target/test/ojb/spy.log</code>.
> It also measures the time needed to execute each statement!
> - </p>
> -</subsection>
> + </p>
> + </subsection>
>
> -<subsection name="How does OJB manage foreign keys ?">
> -<p>
> - Automatically! you just define 1:1, 1:n or m:n associations in the
> - repository_user.xml file.
> - OJB does the rest!
> -</p>
> -<p>
> - Please refer to <a href="tutorial3.html">tutorial3</a> and
> - <a href="repository.html">repository.html</a> for details.
> -</p>
> -</subsection>
> -
> -<subsection name="I don't like OQL, can I use the PersistenceBroker Queries within ODMG?">
> -
> -<p>
> - Yes you can! The ODMG implementation relies on PB Queries internally!
> - Several users (including myself) are doing this.
> -</p>
> -<p>
> - If you have a look at <code>org.apache.ojb.odmg.oql.OqlQueryImpl.execute()</code>
> - you will see how OJB Query objects can be used withing ODMG transactions.
> - The most important thing is to lock all objects returned by a query to the current transaction.
> -</p>
> -
> -<source>
> + <subsection name="How does OJB manage foreign keys?" anchor="14">
> + <p>
> + Automatically! you just define 1:1, 1:n or m:n associations in the
> + repository_user.xml file.
> + OJB does the rest!
> + </p>
> + <p>
> + Please refer to <a href="tutorial3.html">tutorial3</a> and
> + <a href="repository.html">repository.html</a> for details.
> + </p>
> + </subsection>
> +
> + <subsection name="I don't like OQL, can I use the PersistenceBroker Queries within ODMG?" anchor="15">
> + <p>
> + Yes you can! The ODMG implementation relies on PB Queries internally!
> + Several users (including myself) are doing this.
> + </p>
> + <p>
> + If you have a look at the <code>execute()</code> method in <code>org.apache.ojb.odmg.oql.OqlQueryImpl</code>
> + you will see how OJB Query objects can be used withing ODMG transactions.
> + The most important thing is to lock all objects returned by a query to the current transaction.
> + </p>
> + <source>
> public Object execute() throws org.odmg.QueryException
> {
> try
> @@ -519,7 +524,7 @@
> toBeLocked = iter.next();
> //we can only lock objects, not attributes
> if (broker.hasClassDescriptor(toBeLocked.getClass()))
> - tx.lock(toBeLocked, tx.READ);
> + tx.lock(toBeLocked, Transaction.READ);
> }
>
> ...
> @@ -532,62 +537,59 @@
> throw new org.odmg.QueryException(t.getMessage());
> }
> }
> -</source>
> + </source>
> + </subsection>
>
> -</subsection>
> -
> -<subsection name="The OJB JDO implementation is not finished, how can I start using OJB?">
> -<p>
> - I recommend to not use JDO now, but to use the existing ODMG api
> - for the time being.
> -</p>
> -<p>
> - Migrating to JDO later will be smooth if you follow the following steps.
> - I recommend to first divide your model layer into Activity- (or Process-)
> - classes and Entity classes.
> -</p>
> -<p>
> - Entity classes represent classes that must be made persistent at some
> - point in time, say a "Customer" or a "Order" object.
> - These persistent classes and the repsective O/R mapping in repository.xml will
> - remain unchanged.
> -</p>
> -<p>
> - Activities are classes that perform business tasks and work upon
> - entities, e.g. "edit a Customer entry", "enter a new Order"...
> - They implement (parts of) use cases.
> -</p>
> -<p>
> - Activities are driving transactions against the persistent storage.
> -</p>
> -<p>
> - I recommend to have a Transaction interface that your Activities can
> - use. This Transaction interface can be implemented by ODMG or by JDO
> - Transactions (which are quite similar). The implementation should be made
> - configurable to allow to switch from ODMG to JDO later.
> -</p>
> -<p>
> - The most obvious difference between ODMG and JDO are the query
> - languages: ODMG uses OQL, JDO define JDOQL.
> - As an OO developer you won't like both of them.
> - I recommend to use the ojb Query objects that allow an abstract syntax
> - representation of queries.
> - It is possible to use these queries within ODMG transactions and it will
> - also be possible to use them within JDO Transactions. (this is contained in the FAQ too).
> -</p>
> -<p>
> - Using your own Transaction interface in conjunction with the OJB query
> - api will provide a simple but powerful abstraction of the underlying
> - persistence layer.
> -</p>
> -<p>
> - We are using this concept to provide an abstract layer above OJB-ODMG,
> - TopLink and LDAP servers in my company.
> - Making it work with OJB-JDO will be easy!
> -</p>
> -</subsection>
> -
> -</section>
> -
> -</body>
> + <subsection name="The OJB JDO implementation is not finished, how can I start using OJB?" anchor="16">
> + <p>
> + I recommend to not use JDO now, but to use the existing ODMG api
> + for the time being.
> + </p>
> + <p>
> + Migrating to JDO later will be smooth if you follow the following steps.
> + I recommend to first divide your model layer into Activity- (or Process-)
> + classes and Entity classes.
> + </p>
> + <p>
> + Entity classes represent classes that must be made persistent at some
> + point in time, say a "Customer" or a "Order" object.
> + These persistent classes and the repsective O/R mapping in repository.xml will
> + remain unchanged.
> + </p>
> + <p>
> + Activities are classes that perform business tasks and work upon
> + entities, e.g. "edit a Customer entry", "enter a new Order"...
> + They implement (parts of) use cases.
> + </p>
> + <p>
> + Activities are driving transactions against the persistent storage.
> + </p>
> + <p>
> + I recommend to have a Transaction interface that your Activities can
> + use. This Transaction interface can be implemented by ODMG or by JDO
> + Transactions (which are quite similar). The implementation should be made
> + configurable to allow to switch from ODMG to JDO later.
> + </p>
> + <p>
> + The most obvious difference between ODMG and JDO are the query
> + languages: ODMG uses OQL, JDO define JDOQL.
> + As an OO developer you won't like both of them.
> + I recommend to use the ojb Query objects that allow an abstract syntax
> + representation of queries.
> + It is possible to use these queries within ODMG transactions and it will
> + also be possible to use them within JDO Transactions. (this is contained in the FAQ too).
> + </p>
> + <p>
> + Using your own Transaction interface in conjunction with the OJB query
> + api will provide a simple but powerful abstraction of the underlying
> + persistence layer.
> + </p>
> + <p>
> + We are using this concept to provide an abstract layer above OJB-ODMG,
> + TopLink and LDAP servers in my company.
> + Making it work with OJB-JDO will be easy!
> + </p>
> + </subsection>
> + </section>
> + </body>
> </document>
> Index: xdocs/tutorial1.xml
> ===================================================================
> RCS file: /home/cvspublic/jakarta-ojb/xdocs/tutorial1.xml,v
> retrieving revision 1.12
> diff -u -r1.12 tutorial1.xml
> --- xdocs/tutorial1.xml 4 Dec 2002 21:03:22 -0000 1.12
> +++ xdocs/tutorial1.xml 7 Dec 2002 20:07:14 -0000
> @@ -412,13 +412,18 @@
>
> <p>
> Selecting an object from the PersistenceBroker is simple - we must
> - first create a QueryByExample object. A QueryByExample object is
> + first create a QueryByCriteria object. A QueryByCriteria object is
> created with a new Product object that contains an "id" property
> which has been populated with the id the user supplied. You will
> notice that all of the other properties of the Product object
> - remain unpopulated. We have essentially defined a filter by
> - specifying our desire for a Product object that matches this
> - product id.
> + remain unpopulated. We have essentially defined a <b>filter</b> by
> + populating only the "productId" property - our query will retrieve only
> + the product that has this productId. Instead of passing an object to the
> + query constructor, we could have passed a Class, and a Criteria object.
> + Constructing a Criteria object directly allows you
> + to specify an arbitrarily complex collection of query criteria such as "productId"
> + must be greater than 2 and less than 5. A complex query is demonstrated later in this
> + tutorial.
> </p>
>
> <p>
> @@ -443,8 +448,8 @@
> Product example = new Product();
> example.setId(id);
>
> - // 2. build a QueryByExample from this sample instance:
> - Query query = new QueryByExample(example);
> + // 2. build a QueryByCriteria from this sample instance:
> + Query query = new QueryByCriteria(example);
> try
> {
> // 3. start broker transaction
> @@ -500,8 +505,8 @@
> // 1. build an example object with matching primary key values:
> Product example = new Product();
> example.setId(id);
> - // 2. build a QueryByExample from this sample instance:
> - Query query = new QueryByExample(example);
> + // 2. build a QueryByCriteria from this sample instance:
> + Query query = new QueryByCriteria(example);
> try
> {
> // start broker transaction
> @@ -523,16 +528,35 @@
> ]]></source>
>
> <p>
> - I did use a QueryByExample in this case as it needs a minimum of code
> - for primary key lookups. But you can also build a query based on
> - filter criteria. In this use case the query building would look like
> - follows:
> + A QueryByCriteria was used to simplify this tutorial and reduce the
> + amount of code necessary to demonstrate the essential components of OJB.
> + It is important to note that one can also build a query based on
> + filter criteria through the Criteria object. The following code demonstrates
> + the construction of a same query using a Criteria object:
> </p>
>
> <source><![CDATA[
> // build filter criteria:
> Criteria criteria = new Criteria();
> criteria.addEqualTo(_id, new Integer(id));
> + // build a query for the class Product with these filter criteria:
> + Query query = new QueryByCriteria(Product.class, criteria);
> + ...
> + ]]></source>
> +
> + <p>
> + An arbitrary number of criteria can be added to produce very complex
> + queries. The following code demonstrates a more complex use of the Criteria
> + object, one that is not present in this tutorial application. This code
> + retrieves all products which are priced less than 5.40 (USD, Yen, Euros, etc.)
> + and of which we have at least 2 million in stock:
> + </p>
> +
> + <source><![CDATA[
> + // build filter criteria:
> + Criteria criteria = new Criteria();
> + criteria.addLessThan("price", new Double( 5.40 ));
> + criteria.addGreaterThan("stock", new Integer( 2000000 ));
> // build a query for the class Product with these filter criteria:
> Query query = new QueryByCriteria(Product.class, criteria);
> ...
> Index: xdocs/tutorial2.xml
> ===================================================================
> RCS file: /home/cvspublic/jakarta-ojb/xdocs/tutorial2.xml,v
> retrieving revision 1.5
> diff -u -r1.5 tutorial2.xml
> --- xdocs/tutorial2.xml 31 Jul 2002 10:45:39 -0000 1.5
> +++ xdocs/tutorial2.xml 7 Dec 2002 20:07:13 -0000
> @@ -3,6 +3,7 @@
>
> <properties>
> <author email="thma@apache.org">Thomas Mahler</author>
> + <author email="tobrien@transolutions.net">Tim O'Brien</author>
> <title>ObJectRelationalBridge Tutorial - Part 2</title>
> </properties>
>
> @@ -270,15 +271,20 @@
>
> // now perform persistence operations
> Transaction tx = null;
> +
> + try {
> // 3. open transaction
> tx = odmg.newTransaction();
> tx.begin();
> -
> +
> // 4. acquire write lock on new object
> - tx.lock(newProduct, tx.WRITE);
> + tx.lock(newProduct, Transaction.WRITE);
>
> // 5. commit transaction
> tx.commit();
> + } catch( LockNotGrantedException lnge ) {
> + // Code omitted for tutorial brevity....
> + }
> }
> ]]></source>
>
> @@ -322,7 +328,7 @@
> Product toBeEdited = (Product) result.get(0);
>
> // 4. lock the product for write access
> - tx.lock(toBeEdited, tx.WRITE);
> + tx.lock(toBeEdited, Transaction.WRITE);
>
> // 5. Edit the product entry
> System.out.println("please edit existing product");
> Index: xdocs/stylesheets/site.vsl
> ===================================================================
> RCS file: /home/cvspublic/jakarta-ojb/xdocs/stylesheets/site.vsl,v
> retrieving revision 1.1
> diff -u -r1.1 site.vsl
> --- xdocs/stylesheets/site.vsl 1 Jul 2002 20:35:19 -0000 1.1
> +++ xdocs/stylesheets/site.vsl 7 Dec 2002 20:07:14 -0000
> @@ -131,7 +131,7 @@
> <table border="0" cellspacing="0" cellpadding="2" width="100%">
> <tr><td bgcolor="$subbannerbg">
> <font color="$subbannerfg" face="arial,helvetica,sanserif">
> - <a name="$subsection.getAttributeValue("name")"><strong>$subsection.getAttributeValue("name")</strong></a>
> + <a name="$subsection.getAttributeValue("anchor")"><strong>$subsection.getAttributeValue("name")</strong></a>
> </font>
> </td></tr>
> <tr><td>
> @@ -157,7 +157,7 @@
> <table border="0" cellspacing="0" cellpadding="2" width="100%">
> <tr><td bgcolor="$bannerbg">
> <font color="$bannerfg" face="arial,helvetica,sanserif">
> - <a name="$section.getAttributeValue("name")"><strong>$section.getAttributeValue("name")</strong></a>
> + <a name="$section.getAttributeValue("anchor")"><strong>$section.getAttributeValue("name")</strong></a>
> </font>
> </td></tr>
> <tr><td>
> Index: xdocs/stylesheets/site.xsl
> ===================================================================
> RCS file: /home/cvspublic/jakarta-ojb/xdocs/stylesheets/site.xsl,v
> retrieving revision 1.3
> diff -u -r1.3 site.xsl
> --- xdocs/stylesheets/site.xsl 14 Jul 2002 12:06:23 -0000 1.3
> +++ xdocs/stylesheets/site.xsl 7 Dec 2002 20:07:14 -0000
> @@ -171,11 +171,22 @@
> <xsl:variable name="name">
> <xsl:value-of select="@name"/>
> </xsl:variable>
> + <xsl:variable name="anchor">
> + <xsl:choose>
> + <xsl:when test="@anchor">
> + <xsl:value-of select="@anchor"/>
> + </xsl:when>
> + <xsl:otherwise>
> + <xsl:value-of select="@name"/>
> + </xsl:otherwise>
> + </xsl:choose>
> + </xsl:variable>
> +
> <table border="0" cellspacing="0" cellpadding="2" width="100%">
> <!-- Section heading -->
> <tr><td bgcolor="{$banner-bg}">
> <font color="{$banner-fg}" face="arial,helvetica.sanserif">
> - <a name="{$name}">
> + <a name="{$anchor}">
> <strong><xsl:value-of select="@name"/></strong></a></font>
> </td></tr>
> <!-- Section body -->
> @@ -191,11 +202,21 @@
> <xsl:variable name="name">
> <xsl:value-of select="@name"/>
> </xsl:variable>
> + <xsl:variable name="anchor">
> + <xsl:choose>
> + <xsl:when test="@anchor">
> + <xsl:value-of select="@anchor"/>
> + </xsl:when>
> + <xsl:otherwise>
> + <xsl:value-of select="@name"/>
> + </xsl:otherwise>
> + </xsl:choose>
> + </xsl:variable>
> <table border="0" cellspacing="0" cellpadding="2" width="100%">
> <!-- Subsection heading -->
> <tr><td bgcolor="{$sub-banner-bg}">
> <font color="{$sub-banner-fg}" face="arial,helvetica.sanserif">
> - <a name="{$name}">
> + <a name="{$anchor}">
> <strong><xsl:value-of select="@name"/></strong></a></font>
> </td></tr>
> <!-- Subsection body -->
>
>
> ------------------------------------------------------------------------
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
Patch for tutorial1, tutorial2, faq, and site.xsl
Posted by .
Here is a patch for some docs..
** site.xsl
- If a section or subsection has an "anchor" parameter that is used in the
<a name.../>. The system was using @name in the anchor name, and for
something like FAQ where the section and subsection names are so large it
was not desirable to have to reference FAQ entries with the entire question.
There is an xsl:choose in the variable declaration which will ensure that
existing pages do not break.
QUESTION: It doesn't look like site.vsl or site_printable.vsl are being
referenced in jakarta-ojb, is this correct?
** tutorial1
- Removed references to QueryByExample, replaced them with QueryByCriteria
- Added in an example showing a complex QueryByCriteria example.
- incremental grammar, spelling
** tutorial2
- Added a try/catch around tx.lock().
- Change reference to static member variable tx.WRITE -> Transaction.WRITE
- incremental grammar, spelling
** faq
- Added an unordered list that links to all questions.
- Improved wording of first question.
- Changed tx.READ to Transaction.READ
- incremental grammar, spelling
--------
Tim O'Brien
Transolutions, Inc.
W 847-574-2143
M 847-863-7045
Re: Patch for tutorial1.xml
Posted by Thomas Mahler <th...@apache.org>.
Thanks!
O'brien, Tim wrote:
> Here is a patch for tutorial1, I'm only half done refactoring the
> grammar and refining some of the language, but I thought I'd submit
> something sooner rather than later.
>
> Here are the changes I made
>
> 1. Word choice and grammar fixes
> 2. Changed some of the subsections
> 3. Added a reference to tutorial 3 for Mapping.
> 4. Changed function references from "Class::function()" to
> "Class.function()". This is trivial, but I think Java programmers will
> be more familiar with this referencing.
>
> Meanwhile, I'll finish proofreading tutorial1, and move on to the next
> one....
>
> --------
> Tim O'Brien
> Transolutions, Inc.
> W 847-574-2143
> M 847-863-7045
>
>
>
> ------------------------------------------------------------------------
>
> Index: tutorial1.xml
> ===================================================================
> RCS file: /home/cvspublic/jakarta-ojb/xdocs/tutorial1.xml,v
> retrieving revision 1.11
> diff -u -r1.11 tutorial1.xml
> --- tutorial1.xml 31 Jul 2002 10:45:40 -0000 1.11
> +++ tutorial1.xml 4 Dec 2002 18:15:21 -0000
> @@ -3,6 +3,7 @@
>
> <properties>
> <author email="thma@apache.org">Thomas Mahler</author>
> + <author email="tobrien@transolutions.net">Tim O'Brien</author>
> <title>ObJectRelationalBridge Tutorial - Part 1</title>
> </properties>
>
> @@ -20,64 +21,96 @@
> <B><code>org.apache.ojb.tutorial1</code></B>.
> </p>
> <p>
> - I begin with explaining the application and outlining its
> - architecture. After that I will explain how the
> - ObJectRelationalBridge API can be used in the implementations of the
> - use cases to perform persistence operations like retrieval, storage
> - and deletion of objects. Finally I will show how the O/R mapping is
> - built for the applications persistent class <code>Product</code>.
> + This document explains the architecture of a simple application which
> + uses the ObJectRelationalBridge API (PersistenceBroker) to
> + implement five use cases which include persistence operations (retrieval,
> + storage, deletion of objects). This document will also demonstrate how a
> + simple persistence object <code>Product</code> is mapped to a table in
> + a relational database.
> </p>
> </subsection>
>
> -<subsection name="The sample application">
> - <p>
> - The sample application is a console based data entry application.
> - It's a product catalog database with simple use cases:
> -
> - <ol>
> - <li>
> - List all Products in catalog (all Products entered in this or earlier
> - sessions and did not get deleted must be displayed)
> - </li>
> - <li>
> - Enter a new Product (the new Product must be made persistent)
> - </li>
> - <li>
> - Edit an existing Product record
> - </li>
> - <li>
> - Delete a Product record (the Product must be removed from the persistent
> - store)
> - </li>
> - <li>
> - To keep a homogenous design quitting the application is also modelled as
> - a use case.
> - </li>
> - </ol>
> -
> - These use case shall implement only a rudimentary functionality.
> - Thus we don't have to care about special cases or variants.
> +<subsection name="The Tutorial Application">
> + <p>
> + The sample application is a console based data entry application -
> + a program to manipulate a product catalog database with five simple
> + use cases:
> + </p>
> +
> + <ol>
> + <li>
> + <b>List all Products</b> -
> + display all products from the persistent store.
> + </li>
> + <li>
> + <b>Enter a new Product</b> -
> + create a new product in the persistent store
> + </li>
> + <li>
> + <b>Edit an existing Product record</b> -
> + update a product in the persistent store
> + </li>
> + <li>
> + <b>Delete a Product record</b> -
> + remove a product from the persistent store
> + </li>
> + <li>
> + <b>Quit the application</b> -
> + for consistency we implement this as a use case
> + </li>
> + </ol>
> +
> + <p>
> + Only these five basic use cases have been implemented in the
> + interest of keeping this tutorial focused on conveying only the basic
> + concepts of OJB. This tutorial does not explain the necessary steps
> + to model or implement 1:1, 1:n, or m:n mapping. For information about
> + this please refer to Tutorial 3 <a href="tutorial3.html">Advanced O/R</a>.
> </p>
> </subsection>
>
> -<subsection name="see it running...">
> +<subsection name="Running the Tutorial Application">
>
> <p>
> - To see the tutorial application at work you first have to compile the sources
> - and to setup the test database
> - by executing <code>bin\build prepare-tutorials</code> under Win32 or
> - <code>bin/build.sh prepare-tutorials</code> under Unix/Linux
> - from the ojb toplevel directory.
> - </p>
> + To execute the application described in this tutorial,
> + you must prepare the tutorials from the source distribution of
> + OJB. This is accomplished via Ant build scripts which are executed
> + by a script in the "bin" directory of the OJB distribution. (Note:
> + This tutorial assumes that you have already downloaded the OJB
> + source distribution.) Note: There is no need to configure a
> + database in order to run these applications. The tutorial applications
> + ship with HSQLDB integration, all you need to do is run the
> + prepare-tutorials Ant target.
> + </p>
> +
> + <p>
> + Unpack the OJB source distribution, make sure that your current
> + working directory is the top level directory of the OJB
> + distribution and run the following script:
> + </p>
> +
> + <ul>
> + <li>On Windows 9x/NT/2000/XP:
> + <ul>
> + <li><b>Prepare the Tutorials:</b>
> + <code>bin\build.bat prepare-tutorials</code></li>
> + <li><b>Execute this Tutorial:</b>
> + <code>bin\tutorial1.bat</code></li>
> + </ul>
> + </li>
> + <li>On Unix/Linux:
> + <ul>
> + <li><b>Prepare the Tutorials:</b>
> + <code>bin/build.sh prepare-tutorials</code></li>
> + <li><b>Execute this Tutorial:</b>
> + <code>bin/tutorial1.bat</code></li>
> + </ul>
> + </li>
> + </ul>
>
> - <p>
> - Now you can start the tutorial application by executing
> - <code>bin\tutorial1</code> or <code>bin/tutorial1.sh</code>
> - from the ojb toplevel directory.
> - </p>
> </subsection>
>
> -<subsection name="Architectural scetch">
> +<subsection name="Tutorial Application Architecture">
> <p>
> The overall architecture of the application is outlined in the
> class diagram below.
> @@ -89,8 +122,7 @@
> provides some convenience code useful for all concrete
> implementations. There are four concrete UseCase Implementations:
> UCListAllProducts, UCEnterNewProduct, UCDeleteProduct and
> - UCQuitApplication. These concrete classes implement the functionality
> - of the above mentioned Use Cases. The class <code>Product</code>
> + UCQuitApplication. The class <code>Product</code>
> represents a product entry in the product database and is the only
> persistent class in this application.<br/><br/><br/>
> </p>
> @@ -99,14 +131,15 @@
> <br/><br/>
> </p>
> <p>
> - figure 1: Class Diagram with the application classes of the
> + Figure 1: Class Diagram with the application classes of the
> tutorial application
> </p>
> <p>
> - The Application::run() method runs a non-terminating driver loop.
> - It does the following: let the user select a use case and perform
> - this use case and so forth:
> - </p>
> + The <code>Application.run()</code> method runs a main event loop. The
> + program waits for user input in <code>Application.selectUserCase()</code>.
> + Once a UseCase is selected, it is executed via the
> + <code>UseCase.apply()</code> method. This UseCase class is a simple
> + implementation of the well-known Command design pattern.</p>
> <source><![CDATA[
> while (true)
> {
> @@ -123,16 +156,18 @@
> }
> ]]></source>
> <p>
> - A UseCase must implement two methods: <code>getDescription()</code> and
> - <code>apply()</code>. <code>UseCase::getDescription()</code> is used to
> - display a short information on the use case. This method is used in
> - <code>Application::selectUseCase()</code> to display each use case.
> - <code>UseCase::apply()</code> performs the business logic implemented by the
> - use case.
> + The UseCase interface contains two methods: <code>getDescription()</code>
> + and <code>apply()</code>. <code>UseCase.getDescription()</code> is used
> + to display a short description of the use case to the user.
> + This method is used in <code>Application.selectUseCase()</code> to
> + display each use case in a menu. <code>UseCase.apply()</code> performs
> + the business logic implemented by the specific implementation of
> + <code>UseCase</code>.
> </p>
> <p>
> - Let's start with the most simple use case: <code>UCQuitApplication</code>.
> - Here is its <code>apply()</code> method:
> + Starting with the simplest use case in our application -
> + <code>UCQuitApplication</code>. Here is the <code>apply()</code> method
> + from the quit application use case:
> </p>
> <source><![CDATA[
> public void apply()
> @@ -144,37 +179,48 @@
> </subsection>
> </section>
>
> -<section name="Using the OJB PersistenceBroker API in the UseCase implementations">
> +<section name="Using the OJB PersistenceBroker API in the UseCase Implementations">
> <p>
> - Ok, that was rather trivial as no persistence operations were
> - involved. Now to some real work: <code>UCListAllProducts</code>.
> - This use case must lookup a Collection containing all products from
> - the persistent storage. Then it must iterate over this collection and
> - print each product. <br/>
> - To lookup the collection from the persistent
> - storage we need a method from the OJB API. OJB provides three major
> - APIs. The PersistenceBroker, ODMG implementation, and JDO implementation. In this
> - first tutorial I will only use the PersistenceBroker API as it is
> - simpler to use. <a HREF="tutorial2.html">Using the ODMG API</a> and
> - <a href="tutorial4.html">Using the JDO API</a> are
> - covered in separate tutorials.
> + The code example above was trivial - there are no persistence operations
> + involved in quitting the application. Let's move on to a more relevant
> + example - <code>UCListAllProducts</code>.
> + This use case must retreive a <code>Collection</code> containing all
> + products from the database. It must then iterate over this collection
> + and print each product.To retreive the collection from the database we need a method from the
> + OJB API.
> + </p>
> +
> + <p><b>OJB provides three major APIs.</b>
> +
> + <ul>
> + <li>The PersistenceBroker</li>
> + <li>An ODMG implementation</li>
> + <li>A JDO implementation</li>
> + </ul>
> +
> + <p>
> + In this first tutorial only the <b>PersistenceBroker API</b> is used as it
> + is the most straightforward of the three options. Tutorial 2:
> + <a HREF="tutorial2.html">Using the ODMG API</a> and
> + Tutorial 4: <a href="tutorial4.html">Using the JDO API</a> will
> + implement the same application using these different methods of
> + database access.
> </p>
> <p>
> You will find the source for the PersistenceBroker API in the
> package <code>org.apache.ojb.broker</code>. <A HREF="javadoc/ojb/broker/package-summary.html">The
> - JavaDoc is here</A>. The Most important part of this API is the
> + JavaDoc is here</A>. The key component in this package is the
> interface <code>PersistenceBroker</code>. It
> provides methods for retrieval, storage and deletion of objects. To
> use it in your application you must know how to retrieve a Broker
> instance, how to configure its O/R mapping repository and how to use
> - its API.
> + the available functionsI.
> </p>
>
> - <subsection name="Obtaining a broker instance">
> + <subsection name="Obtaining a Broker Instance">
> <p>
> - To learn how to obtain a Broker instance lets have a look at the
> - Application class. The public constructor of this class looks like
> - follows:
> + How do we obtain a Broker instance? Take a look at the public constructor
> + of the Application class to find the answer to this question.
> </p>
> <source><![CDATA[
> public Application()
> @@ -197,29 +243,28 @@
> }
> ]]></source>
> <p>
> - We just ask the PersistenceBrokerFactory to create an instance that
> - uses the file ./repository.xml as mapping repository (more details on
> - this repository in the <A HREF="#def_or">section on the Object
> - /Relational mapping</A>). This broker instance is reached to the
> - constructors of the UseCases. The constructors just store it in a
> - protected attribute <code>broker</code> for
> - further usage.
> + The PersistenceBrokerFactory creates an instance of PersistenceBroker
> + using the resource ./repository.xml as a mapping repository (more
> + details on this repository in the <A HREF="#def_or">section on the
> + Object/Relational mapping</A>. The PersistenceBroker instance is
> + passed to the constructor of the four UseCase objects which
> + store this PersistenceBroker instance as a protected member variable.
> </p>
> </subsection>
> -<subsection name="Retrieving collections and iterators">
> + <subsection name="Retrieving Collections and Iterators">
> <p>
> - The next thing we need to know is how to use this broker instance to help us
> - in our persistence operations. In this use case we have to retrieve a
> - collection containing all product entries from the persistent store. To
> + The next thing we need to know is how to use this broker instance to implement
> + our persistence operations. In this use case, we have to retrieve a
> + collection containing all product entries from the database. To
> retrieve a collection containing objects matching some criteria we can use
> - <code>PersistenceBroker::getCollectionByQuery(Query query)</code>.
> - Where <code>Query</code> is a Class that allows to formulate criteria like
> - price > 100. In our case we want to select <I>all</I> persistent
> - instances, so we need no filtering criteria, they can thus be left
> - <code>null</code>.
> + <code>PersistenceBroker.getCollectionByQuery(Query query)</code>.
> + Where <code>Query</code> is a class that allows to specify criteria like
> + price > 100 or userId == 3. In our case we want to select <I>all</I>
> + of the persistence objects stored in the Product table. We need <b>no</b>
> + (or <i>null</i>) filtering criteria.
> </p>
> <p>
> - Here is the code of the <code>UCListAllProducts::apply()</code>method:
> + Here is the code of the <code>UCListAllProducts.apply()</code>method:
> </p>
>
> <source><![CDATA[
> @@ -249,17 +294,24 @@
> ]]></source>
>
> <p>
> - If you don't need the resulting collection for further reference as in this
> - example where we just want to iterate over all products once, it may be a
> - good idea not to use getCollectionByQuery() but getIteratorByQuery() which
> - returns an Iterator.
> - </p>
> - <p>
> - This method is extremely useful if you write applications that have to
> - iterate over large resultsets. Instances are not created all at once but
> - only on demand, and instances that are not longer referenced by the
> - application my be reclaimed by the garbage collector. Using this method the
> - code will look like follows:
> + Imagine that there are 10,000 products in the product table:
> + Retrieving a collection of all Products from the persistent store
> + would be a very expensive operation - new objects are created and an
> + entire table is loaded into memory. In this tutorial application,
> + performance is not a major issue, but in a real-world application OJB
> + provides a more efficient mechanism for iterating through all the
> + available products. If your application does not need to maintain a
> + collection of product objects in memory, you should call
> + getIteratorByQuery() which returns an Iterator instead of a Collection.
> + </p>
> + <p>
> + This method is extremely useful if you write applications that
> + need to iterate over large resultsets. Instances are not created
> + all at once, they are created on an "as needed" basis as you
> + iterate through the result. Instances of persistent objects which
> + are no longer referenced by the application can be reclaimed by
> + the garbage collector. Using this method the code will resemble
> + the following:
> </p>
>
> <source><![CDATA[
> @@ -273,7 +325,7 @@
> try
> {
> // ask the broker to retrieve an Iterator
> - java.util.Iterator iter = broker.getIteratorB
> + java.util.Iterator iter = broker.getIteratorByQuery(query);
> // now iterate over the result to print each product
> while (iter.hasNext())
> {
> @@ -301,7 +353,7 @@
> product's data (productname, price and available stock). These data
> is stored in the new objects attributes. Then we must store the newly
> created object in the persistent store. We can use the method
> -<code>PersistenceBroker::store(Object obj)</code>
> +<code>PersistenceBroker.store(Object obj)</code>
> for this task.
> </p>
> <source><![CDATA[
> @@ -349,14 +401,33 @@
>
> </subsection>
> <subsection name="Updating Objects">
> +
> <p>
> - Editing and updating a product entry works quite similar. The user
> - enters the products unique id and the broker tries to lookup the
> - respective object. This lookup is necessary as our application does
> - not hold a list of all products. The found product is then edited and
> - then stored. The PersistenceBroker uses the <code>.store(...)</code>
> - method for inserting new objects as well as for updating existing
> - objects. Here is the code:
> + When a user wants to edit a product ( by selecting item #2 from the
> + menu ), a user must first enter the "id" of the product to be
> + edited. Since the application does not maintain a list of product
> + objects, the system must first retrieve a product from persistent
> + storage via the PersistenceBroker.
> + </p>
> +
> + <p>
> + Selecting an object from the PersistenceBroker is simple - we must
> + first create a QueryByExample object. A QueryByExample object is
> + created with a new Product object that contains an "id" property
> + which has been populated with the id the user supplied. You will
> + notice that all of the other properties of the Product object
> + remain unpopulated. We have essentially defined a filter by
> + specifying our desire for a Product object that matches this
> + product id.
> + </p>
> +
> + <p>
> + The Product object is retrieved, with the call to
> + <code>broker.getObjectByQuery(query)</code>. This retreived object is then
> + edited by setting properties based on the user input, and this
> + object is then stored in the persistence storage through a call to
> + <code>broker.store(toBeEdited)</code>. Here is the code from
> + <code>UCEditProduct</code>.
> </p>
>
> <source><![CDATA[
> @@ -468,7 +539,13 @@
> ]]></source>
>
> </subsection>
> -<subsection name="Finishing this application is left as an exercise to the interested reader">
> +<subsection name="Completing the Tutorial Application">
> +
> + <p>
> + The completion of this tutorial program is left as an exercise for
> + the tutorial reader.
> + </p>
> +
>
> <p>
> Now you are familiar with the basic functionalities of the OJB
> @@ -530,7 +607,7 @@
> In the following sections I will show how the O/R mapping is
> defined for the tutorial application.
> </p>
> -<subsection name="the persistent class Product">
> +<subsection name="A Persistent Class: Product">
> <p>
> There is only one persistent class in our tutorial application,
> the class <code>Product</code>. Here it's definition:
> @@ -560,7 +637,7 @@
> </p>
> </subsection>
>
> -<subsection name="The corresponding database table">
> +<subsection name="The Product Database Table">
> <p>
> Now we take a look at a corresponding table definition, in SQL DDL
> (I give the instantDB syntax here, the syntax may vary slightly for
> @@ -628,7 +705,7 @@
>
> </subsection>
>
> -<subsection name="The Mapping">
> +<subsection name="The Product Mapping">
> <p>
> Now we have to describe the mapping from the class <code>Product</code>
> to the database table <code>PRODUCT</code>. This
> @@ -812,7 +889,7 @@
> <a href="repository.html">found here</a>.
> </p>
> </subsection>
> -<subsection name="tool support">
> +<subsection name="Tool Support">
> <p>
> Generally speaking there are three approaches in building an O/R mapping:
> </p>
>
>
> ------------------------------------------------------------------------
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
Patch for tutorial1.xml
Posted by .
Here is a patch for tutorial1, I'm only half done refactoring the
grammar and refining some of the language, but I thought I'd submit
something sooner rather than later.
Here are the changes I made
1. Word choice and grammar fixes
2. Changed some of the subsections
3. Added a reference to tutorial 3 for Mapping.
4. Changed function references from "Class::function()" to
"Class.function()". This is trivial, but I think Java programmers will
be more familiar with this referencing.
Meanwhile, I'll finish proofreading tutorial1, and move on to the next
one....
--------
Tim O'Brien
Transolutions, Inc.
W 847-574-2143
M 847-863-7045
Re: OJB Docs
Posted by Thomas Mahler <th...@apache.org>.
Hi again Brian,
Brian McCallister wrote:
> On Tue, 2002-12-03 at 16:50, Thomas Mahler wrote:
>
>>I did write most of the existing OJB docs. It took me weeks, so I'm a
>>bit confused to here that there is not sufficient documentation avaible.
>>I don't say it's perfect. But alone tutorial3.html prints out as 40 pages...
>
>
> Sorry if I came across as denegrating your work, my feelings are
> anything but that!
No problem. I just was not sure you did find the existing stuff.
> The configuration and mapping information is thorough
> and clear - getting to the point where you can actually use it is a bit
> less clear.
+1
I'd be happy to see improvements here! It would also be good to see some
simple cookbook style articles.
It would also be important to write stuff from a user (or even better a
newcomer perspsective). This is extremely difficult for me, as I know
OJB already ;-)
So any help in this area would be appreciated.
> There are some things that are pretty difficult to work out
> -- like what exact the .jdo files contain. ( "TODO: Put information
> about the .jdo files") ;-)
>
+1
> I am quite happy digging and playing, but the goal of good docs is to
> prevent the head scratching parts for people who don't have time to dig
> and scratch.
+1 That's why it is a good idea to write down your experiences and
findings of this learning process to help others. This is something I
cannot do as mentioned above.
> Besides all that, I cannot help seing the advertisement for a documentor
> for the JDO effort, which is what drew me to OJB in the first place.
> getting up to speed on the architecture would take enough time for you
> to finish it according to Matt Baird, so I figure I can at least
> contribute while learning.
>
Yes, that would be a big help!
> My apologies for coming across poorly!
No problem! Please excuse my yesterday rantings. (I'm just allergic to
"OJB lacks documentation" statements.)
You are most welcome to help on documentation and all other things as well.
cheers,
Thomas
> -Brian
>
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
>
>
Re: OJB Docs
Posted by Brian McCallister <mc...@forthillcompany.com>.
On Tue, 2002-12-03 at 16:50, Thomas Mahler wrote:
> I did write most of the existing OJB docs. It took me weeks, so I'm a
> bit confused to here that there is not sufficient documentation avaible.
> I don't say it's perfect. But alone tutorial3.html prints out as 40 pages...
Sorry if I came across as denegrating your work, my feelings are
anything but that! The configuration and mapping information is thorough
and clear - getting to the point where you can actually use it is a bit
less clear. There are some things that are pretty difficult to work out
-- like what exact the .jdo files contain. ( "TODO: Put information
about the .jdo files") ;-)
I am quite happy digging and playing, but the goal of good docs is to
prevent the head scratching parts for people who don't have time to dig
and scratch.
Besides all that, I cannot help seing the advertisement for a documentor
for the JDO effort, which is what drew me to OJB in the first place.
getting up to speed on the architecture would take enough time for you
to finish it according to Matt Baird, so I figure I can at least
contribute while learning.
My apologies for coming across poorly!
-Brian
Re: OJB Docs
Posted by Thomas Mahler <th...@apache.org>.
Hi Brian,
Brian McCallister wrote:
> Is anyone actively working on docs for OJB?
There is a volunteer working on polishing style and grammar of the
tutorials.
> Having just started nosing
> around the sources and trying to use OJB (ODMG and JDO, no PB yet) it
> doesn't seem like there is a whole lot of documentation -- usage or
> architecture.
I did write most of the existing OJB docs. It took me weeks, so I'm a
bit confused to here that there is not sufficient documentation avaible.
I don't say it's perfect. But alone tutorial3.html prints out as 40 pages...
Are sure you built the docs with ant xslt and read everything in
target/docs?
> I am considering writing up my notes as more formal docs, and diving
> into some architectural docs.
That's great! Of course it's good to have some more in depth
architectural docs.
> Normally I would post them to a personal
> site for people to use as they may, but as there doesn't seem to be an
> awful lot with OJB already, I figured it might be best to just write
> docs for the project itself.
That's a good idea. We will integrate such docs into the existing stuff!
> I don't want to double up on effort or step
> on anyone's toes though... so this email.
Apart from the mentioned stylistic corrections there are currently no
documentation efforts I know of.
So just let me know what you would like to add to the docs, and we'll
plan how to integrate the missing stuff into the xisting structure.
thanks,
Thomas
OJB Docs
Posted by Brian McCallister <mc...@forthillcompany.com>.
Is anyone actively working on docs for OJB? Having just started nosing
around the sources and trying to use OJB (ODMG and JDO, no PB yet) it
doesn't seem like there is a whole lot of documentation -- usage or
architecture.
I am considering writing up my notes as more formal docs, and diving
into some architectural docs. Normally I would post them to a personal
site for people to use as they may, but as there doesn't seem to be an
awful lot with OJB already, I figured it might be best to just write
docs for the project itself. I don't want to double up on effort or step
on anyone's toes though... so this email.
--
Brian McCallister < mccallister@forthillcompany.com >
Systems Administrator and Software Engineer
Fort Hill Company -- www.forthillcompany.com