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 Martin Kalén <mk...@apache.org> on 2005/04/30 07:45:29 UTC
[rfc] website docs minor changes
Greetings,
I would like some opinions on a few minor changes I would like to do
to the OJB website.
I have set up a beta site here:
http://people.apache.org/~mkalen/ojb/site/index.html
(Please note that the trackmark/trail will include my personal dir,
ie "apache > db.apache > ~mkalen > ojb > site" which will _not_ be
the case on the real website of course.)
If you could please have a look at the "Home" navigation links where
I have done some restructuring. It's mostly reordering/renaming so
no dramatic changes, but it should be a bit more consistent.
Also:
* status: +warning re OTM, please help updating the docs!
* status: +notice/fixme re S.O.D.A., please help updating the docs!
* mailing lists page: "objectbridge" => "ojb"
* list archives page: +MARC dev/user, +Mail Archive dev
* list archives page: put Mail Archive on top until mail-archives @ apache is
fully migrated to EU (I am *not* going to link to the ugly mod_mbox) ;)
* for all pages under "home" tab: include "OJB - " in title
* for all pages under "documentation" tab: don't include OJB in title
* JIRA project-id => "OJB" project name
* update Coding Standards slightly (I guess more will follow after the vote)
Many smaller changes in the doc section:
s/was/is/g (make past tense the present...)
Update the texts for the "Testing" section.
"Basic Technique" in nav => "Basic Mapping", title "Basic O/R Mapping Technique"
"Advanced Technique" in nav => "Advanced Mapping", title "Advanced O/R Mapping Technique".
And the main reason why I started:
http://people.apache.org/~mkalen/ojb/site/docu/guides/repository.html#connection-pool-N1023E
I took the latest descriptions from Commons Pool and Commons DBCP websites and updated
repository.dtd (what you see on the webpage is copied from repository.dtd).
(Note that there is a new 'minIdle' marked "since OJB 1.0.4", since it only exists in
my local codebase yet. When upgrading commons pool we got this one "secretly" with
a backwards compatible default of 0. I will add it to repository.dtd and connection conf.)
As you see, no dramatic changes but since I like to fiddle around with a lot of
small changes to the menu-structure, someone might have objections or better ideas.
Also, please help me solving the "fixme"s here:
http://people.apache.org/~mkalen/ojb/site/status.html (warn/fixme near bottom)
http://people.apache.org/~mkalen/ojb/site/docu/guides/deployment.html#Introduction
Aren't we using only Geronimo now, anyway? In that case I will just remove the
fixme and commit my other changes and we can have a look at making a bigger
update of the deployment guide.
Regards,
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: [rfc] website docs minor changes
Posted by Martin Kalén <mk...@apache.org>.
Armin Waibel wrote:
> AFAIK long time ago it was decided that the SODA support will be removed
> (maybe I'm wrong), because no one ever used this api.
I found this on the Wiki:
"
I [thma] vote for removing support for the S.O.D.A query API ([WWW] http://sodaquery.sourceforge.net/docs/index.html).
I think we should focus on the standards like JDO and ODMG that have found some acceptance in the market.
"
I will keep one reference on the status page saying status=deprecated,
but with a link to sourceforge.
When (if) we remove the code, we can remove the remaining docs.
/Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: [rfc] website docs minor changes
Posted by Martin Kalén <mk...@apache.org>.
Armin Waibel wrote:
>> http://people.apache.org/~mkalen/ojb/site/status.html
>
> Looks a little bit "complex".
> Why not use a html-list or simply paragraphs (<p>) to separate the api's?
+1, it looked so much more readable with simple bullets!
I checked everything in now, including the note about Serializable
that we were discussing with Stas Ostapenko on the user list.
It's now a note in JavaDoc for MM-methods using SerializationUtils
and a NOTE on the metadata manager guide page. Have a look if
I am telling bogus there, since I did not think extremely long
but chose neutral wording instead...
Regarding the # of connections - it was just a joke over my own stupidity,
in my DBCP-test I test things like pool exhausted and abandoned config
invalidation of objects, so I wanted a really really tight limit (max 2).
(For _that_ testcase only though, as I found out the hard way!) ;)
/Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: [rfc] website docs minor changes
Posted by Armin Waibel <ar...@apache.org>.
Martin Kalén wrote:
> Armin Waibel wrote:
>
> (otm status)
>
>> I vote to keep the "eye-catcher" in OTM section of status page (using
>> a <note> element) to emphasize that work currently stopped.
>
>
> It's now a note, but I am not so sure the table option looks OK?
>
> Check out:
> http://people.apache.org/~mkalen/ojb/site/status.html
>
Looks a little bit "complex".
Why not use a html-list or simply paragraphs (<p>) to separate the api's?
<ul>
<li>
<strong>PB API (Persistence Broker API)</strong>
<p>
The PB API implementation is <strong>stable</strong>, known
issues can be found in
<link href="ext:release-notes">release-notes</link>.
</p>
</li>
...
or without the list elements.
>> Thanks. I found redundand TOC/Introduction in doc index page too.
>> http://people.apache.org/~mkalen/ojb/site/docu/index.html
>
>
> Changed, I just uploaded new content ~1hour ago with all changes
> recommended by you.
>
looks very good!
> I was actually done several hours ago but I have been busy trying to
> understand why I got 130 (sic!!) faults in the PB API tests with my new
> testcase.
>
> Lets just say that changing a descriptor to DBCP Connection factory
> and explicit maxActive=2/maxWait=125ms/onExhausted=fail is _not_
> goot for the OJB testsuite when that descriptor i global. *doh*
>
I think at least the test cases need 15 active connections to pass,
because there are several multi-threaded test (10-15 concurrent clients)
and if you set onExhausted=fail it's not good with maxActive=2
That's why I set default maxActive to 30.
> Of course I put my new test first in the testsuite.
>
> I guess I will have to get Tom's -€ for that... ;)
>
>> I would suggest to remove this recommendation. J2EE 1.4/1.3 there is
>> no difference in the JTA and the TxManager is the starting point for
>> OJB to participate in the JTA-tx.
>
>
> Done! I removed the text "we recommend 1.3" ang changed the link to Sun to:
> http://java.sun.com/j2ee/download.html#sdk
>
> (Both J2EE 1.3 and 1.4 can be grabbed from there.)
>
ok!
> I won't upload a new site with only that link change though,
> so I am just waiting until you have a look at the status table
> and say go / no-go for that. (I will just commit to CVS not push to
> db.apache.org yet, since there are a number of new config options
> mentioning OJB1.0.4 in there.)
>
Locally I generate the status site using html-list - looks not bad. But
if you think the html-table based stuff looks better use that.
regards,
Armin
> Cheers,
> Martin
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
> For additional commands, e-mail: ojb-dev-help@db.apache.org
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: [rfc] website docs minor changes
Posted by Martin Kalén <mk...@apache.org>.
Armin Waibel wrote:
(otm status)
> I vote to keep the "eye-catcher" in OTM section of status page (using a
> <note> element) to emphasize that work currently stopped.
It's now a note, but I am not so sure the table option looks OK?
Check out:
http://people.apache.org/~mkalen/ojb/site/status.html
(soda)
>> OK, I'll drop it from the doco again until further notice, but I think:
>> *) if it is usable, why not mention it?
>
> Sorry, I never test it.
>
>> *) if it us unsuable, why not remove it from both docs and code?
>
> Maybe we should discuss about the SODA api in a separate thread again
> and remove it if all agree.
Agreed, I get deja-vù so I think we had this discussion before? :)
Anyway, it's not bothering us at the moment so lets do like you say
and deal with this in a separate thread.
> Thanks. I found redundand TOC/Introduction in doc index page too.
> http://people.apache.org/~mkalen/ojb/site/docu/index.html
Changed, I just uploaded new content ~1hour ago with all changes
recommended by you.
>>> Could we add these properties too (to enable prepared statement
>>> caching in DBCP, as suggested by you in another thread)?
>>> poolPreparedStatements
>>> maxOpenPreparedStatements
>>
>> Yup, they are in my code and I am running tests at the moment. I can't
>> test those very well because they conflict with the same concept
>> (PreparedStatement caching) in the Oracle JDBC-driver, I will run it
>> against HSQLDB also since the DBCP solution is pure POJO-based and
>> has no driver requierments at all. Ie, I _think_ it should be good
>> for MaxDB/SapDB.
>>
>> I'm finishing the tests/comitts for a few smaller updates in connection
>> factories in a few hours.
>
> Great! Don't be in such a hurry, you not paid for it ;-)
I was actually done several hours ago but I have been busy trying to
understand why I got 130 (sic!!) faults in the PB API tests with my new
testcase.
Lets just say that changing a descriptor to DBCP Connection factory
and explicit maxActive=2/maxWait=125ms/onExhausted=fail is _not_
goot for the OJB testsuite when that descriptor i global. *doh*
Of course I put my new test first in the testsuite.
I guess I will have to get Tom's -€ for that... ;)
> I would suggest to remove this recommendation. J2EE 1.4/1.3 there is no
> difference in the JTA and the TxManager is the starting point for OJB to
> participate in the JTA-tx.
Done! I removed the text "we recommend 1.3" ang changed the link to Sun to:
http://java.sun.com/j2ee/download.html#sdk
(Both J2EE 1.3 and 1.4 can be grabbed from there.)
I won't upload a new site with only that link change though,
so I am just waiting until you have a look at the status table
and say go / no-go for that. (I will just commit to CVS not push to
db.apache.org yet, since there are a number of new config options
mentioning OJB1.0.4 in there.)
Cheers,
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: [rfc] website docs minor changes
Posted by Armin Waibel <ar...@apache.org>.
Martin Kalén wrote:
> Armin Waibel wrote:
>
>>> Also:
>>> * status: +warning re OTM, please help updating the docs!
>>
>>
>> Isn't a normal note instead of a warning sufficient or do think a
>> warning is needed because of the unsettled status?
>
>
> That was more of an "eye-catcher" for us, I planned to remove both
> notice/warning before commiting anything. I just put this up big
> where I had no clue what to write. :)
>
I vote to keep the "eye-catcher" in OTM section of status page (using a
<note> element) to emphasize that work currently stopped.
>>> * status: +notice/fixme re S.O.D.A., please help updating the docs!
>>
>>
>> AFAIK long time ago it was decided that the SODA support will be
>> removed (maybe I'm wrong), because no one ever used this api.
>
>
> OK, I'll drop it from the doco again until further notice, but I think:
> *) if it is usable, why not mention it?
Sorry, I never test it.
> *) if it us unsuable, why not remove it from both docs and code?
>
Maybe we should discuss about the SODA api in a separate thread again
and remove it if all agree.
>>> Update the texts for the "Testing" section.
>>
>>
>> +1
>>
>> Suggest to remove in all summary.xml files the <section> element to
>> suppress the TOC at the beginning of the document. On a summary site a
>> TOC is not needed.
>
>
> Yes, I thought so too- it looked a bit strange with a redundand TOC like
> so:
>
> TOC TITLE
> link to boxed title
>
> [BOXED TITLE]
>
> paragraph about title
>
> It's really rubbing it in, in the readers face? :)
>
> I'll have a look a changing the boxed title into just title for all of
> those.
>
Thanks. I found redundand TOC/Introduction in doc index page too.
http://people.apache.org/~mkalen/ojb/site/docu/index.html
>>> I took the latest descriptions from Commons Pool and Commons DBCP
>>> websites and updated
>>> repository.dtd (what you see on the webpage is copied from
>>> repository.dtd).
>>>
>>> (Note that there is a new 'minIdle' marked "since OJB 1.0.4", since
>>> it only exists in
>>> my local codebase yet. When upgrading commons pool we got this one
>>> "secretly" with
>>> a backwards compatible default of 0. I will add it to repository.dtd
>>> and connection conf.)
>>
>>
>> Could we add these properties too (to enable prepared statement
>> caching in DBCP, as suggested by you in another thread)?
>> poolPreparedStatements
>> maxOpenPreparedStatements
>
>
> Yup, they are in my code and I am running tests at the moment. I can't
> test those very well because they conflict with the same concept
> (PreparedStatement caching) in the Oracle JDBC-driver, I will run it
> against HSQLDB also since the DBCP solution is pure POJO-based and
> has no driver requierments at all. Ie, I _think_ it should be good
> for MaxDB/SapDB.
>
> I'm finishing the tests/comitts for a few smaller updates in connection
> factories in a few hours.
>
Great! Don't be in such a hurry, you not paid for it ;-)
>>> http://people.apache.org/~mkalen/ojb/site/docu/guides/deployment.html#Introduction
>>
>>
>>
>> +0, I run my tests against JBoss 3.2.3. Think this version is J2EE 1.3
>> compliant, never tested with JBoss 4.0. Do we have to make a
>> recommendation?
>
>
> Not at all, I just scanned many documents quickly and thought that
> "hey, J2SDK 1.4 is not exactly the void and unknown - do we really
> mean what we say here?".
>
> If you say we do, I agree by default. :)
>
I would suggest to remove this recommendation. J2EE 1.4/1.3 there is no
difference in the JTA and the TxManager is the starting point for OJB to
participate in the JTA-tx.
regards,
Armin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: [rfc] website docs minor changes
Posted by Martin Kalén <mk...@apache.org>.
Armin Waibel wrote:
>> Also:
>> * status: +warning re OTM, please help updating the docs!
>
> Isn't a normal note instead of a warning sufficient or do think a
> warning is needed because of the unsettled status?
That was more of an "eye-catcher" for us, I planned to remove both
notice/warning before commiting anything. I just put this up big
where I had no clue what to write. :)
>> * status: +notice/fixme re S.O.D.A., please help updating the docs!
>
> AFAIK long time ago it was decided that the SODA support will be removed
> (maybe I'm wrong), because no one ever used this api.
OK, I'll drop it from the doco again until further notice, but I think:
*) if it is usable, why not mention it?
*) if it us unsuable, why not remove it from both docs and code?
>> Update the texts for the "Testing" section.
>
> +1
>
> Suggest to remove in all summary.xml files the <section> element to
> suppress the TOC at the beginning of the document. On a summary site a
> TOC is not needed.
Yes, I thought so too- it looked a bit strange with a redundand TOC like so:
TOC TITLE
link to boxed title
[BOXED TITLE]
paragraph about title
It's really rubbing it in, in the readers face? :)
I'll have a look a changing the boxed title into just title for all of those.
>> I took the latest descriptions from Commons Pool and Commons DBCP
>> websites and updated
>> repository.dtd (what you see on the webpage is copied from
>> repository.dtd).
>>
>> (Note that there is a new 'minIdle' marked "since OJB 1.0.4", since it
>> only exists in
>> my local codebase yet. When upgrading commons pool we got this one
>> "secretly" with
>> a backwards compatible default of 0. I will add it to repository.dtd
>> and connection conf.)
>
> Could we add these properties too (to enable prepared statement caching
> in DBCP, as suggested by you in another thread)?
> poolPreparedStatements
> maxOpenPreparedStatements
Yup, they are in my code and I am running tests at the moment. I can't
test those very well because they conflict with the same concept
(PreparedStatement caching) in the Oracle JDBC-driver, I will run it
against HSQLDB also since the DBCP solution is pure POJO-based and
has no driver requierments at all. Ie, I _think_ it should be good
for MaxDB/SapDB.
I'm finishing the tests/comitts for a few smaller updates in connection
factories in a few hours.
>> http://people.apache.org/~mkalen/ojb/site/docu/guides/deployment.html#Introduction
>
> +0, I run my tests against JBoss 3.2.3. Think this version is J2EE 1.3
> compliant, never tested with JBoss 4.0. Do we have to make a
> recommendation?
Not at all, I just scanned many documents quickly and thought that
"hey, J2SDK 1.4 is not exactly the void and unknown - do we really
mean what we say here?".
If you say we do, I agree by default. :)
> Think after the first stable release we should use Geronimo as default
> testing platform for OJB's J2EE integration.
Forget what I said, this was just a guess based on those compile-time
dependency replacements that we have done. I am not running OJB in
any J2EE container, just Tomcat - that's another reason why I didn't
want to change this without asking.
> I must admit that I didn't find time to setup Geronimo with the OJB
> session bean samples (last time I looked on the web-site Geronimo
> doesn't support hot/auto-deployment of resources). Do you have
> experience in using Geronimo?
Very little, we will just keep the documented solution that works IMO!
Regards,
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org
Re: [rfc] website docs minor changes
Posted by Armin Waibel <ar...@apache.org>.
Hi Martin,
Martin Kalén wrote:
> Also:
> * status: +warning re OTM, please help updating the docs!
Isn't a normal note instead of a warning sufficient or do think a
warning is needed because of the unsettled status?
> * status: +notice/fixme re S.O.D.A., please help updating the docs!
AFAIK long time ago it was decided that the SODA support will be removed
(maybe I'm wrong), because no one ever used this api.
> * mailing lists page: "objectbridge" => "ojb"
+1
> * list archives page: +MARC dev/user, +Mail Archive dev
+1
> * list archives page: put Mail Archive on top until mail-archives @
> apache is
> fully migrated to EU (I am *not* going to link to the ugly mod_mbox) ;)
+1
> * for all pages under "home" tab: include "OJB - " in title
+1
> * for all pages under "documentation" tab: don't include OJB in title
+1
> * JIRA project-id => "OJB" project name
+1
> * update Coding Standards slightly (I guess more will follow after the
> vote)
>
+1 like that this site has no summarization at the beginning of the
document (table of content - TOC). Is this also possible for feature.xml
and status.xml?
Think it will be more clearly laid out when the different API's listed
with html-list instead of a single section for each API on status site.
> Many smaller changes in the doc section:
> s/was/is/g (make past tense the present...)
>
Thanks much! Please feel free to correct all docs without request.
> Update the texts for the "Testing" section.
>
+1
Suggest to remove in all summary.xml files the <section> element to
suppress the TOC at the beginning of the document. On a summary site a
TOC is not needed.
> "Basic Technique" in nav => "Basic Mapping", title "Basic O/R Mapping
> Technique"
> "Advanced Technique" in nav => "Advanced Mapping", title "Advanced O/R
> Mapping Technique".
>
+1
>
> And the main reason why I started:
> http://people.apache.org/~mkalen/ojb/site/docu/guides/repository.html#connection-pool-N1023E
>
>
> I took the latest descriptions from Commons Pool and Commons DBCP
> websites and updated
> repository.dtd (what you see on the webpage is copied from repository.dtd).
>
> (Note that there is a new 'minIdle' marked "since OJB 1.0.4", since it
> only exists in
> my local codebase yet. When upgrading commons pool we got this one
> "secretly" with
> a backwards compatible default of 0. I will add it to repository.dtd and
> connection conf.)
>
Could we add these properties too (to enable prepared statement caching
in DBCP, as suggested by you in another thread)?
poolPreparedStatements
maxOpenPreparedStatements
>
> As you see, no dramatic changes but since I like to fiddle around with a
> lot of
> small changes to the menu-structure, someone might have objections or
> better ideas.
>
> Also, please help me solving the "fixme"s here:
> http://people.apache.org/~mkalen/ojb/site/status.html (warn/fixme near
> bottom)
see above
> http://people.apache.org/~mkalen/ojb/site/docu/guides/deployment.html#Introduction
>
+0, I run my tests against JBoss 3.2.3. Think this version is J2EE 1.3
compliant, never tested with JBoss 4.0. Do we have to make a recommendation?
>
> Aren't we using only Geronimo now, anyway?
Think after the first stable release we should use Geronimo as default
testing platform for OJB's J2EE integration.
> In that case I will just
> remove the
> fixme and commit my other changes and we can have a look at making a bigger
> update of the deployment guide.
>
I must admit that I didn't find time to setup Geronimo with the OJB
session bean samples (last time I looked on the web-site Geronimo
doesn't support hot/auto-deployment of resources). Do you have
experience in using Geronimo?
regards,
Armin
> Regards,
> Martin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
> For additional commands, e-mail: ojb-dev-help@db.apache.org
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org