objectbridge-jdo-dev — OJB JDO developer list

Re: [Objectbridge-jdo-dev] progress

[Thomas M. <tho...@ho...>]

Hi Peter,

thanks for your interest.

We have not started coding. We are just discussing different approaches.
(Please refer to the mailinglist archive to get familiar with the
current dicussions).

cu,

Thomas

pge...@za... wrote:

 > hi
 > i recently joined the list and would like to know how far you guys 
are with
 > implementation?
 > i would like to contribute....
 > regards
 > peter
 >
 >
 >
 > _______________________________________________
 > Objectbridge-jdo-dev mailing list
 > Obj...@li...
 > https://lists.sourceforge.net/lists/listinfo/objectbridge-jdo-dev
 >
 >
 >
 >

[Objectbridge-jdo-dev] progress

[<pge...@za...>]

hi
i recently joined the list and would like to know how far you guys are with
implementation?
i would like to contribute....
regards
peter

[Objectbridge-jdo-dev] FYI: [ Re: JDO Stories]

[Mahler T. <tho...@it...>]

Hi all,

A few days ago Akmal Chaudhri on comp.databases.object announced that he
plans to publish a collection of articles regarding JDO.
He invited to contribute to this publication.
below you find the conversation I had with him. 

cu,

Thomas

> 
> -------- Original Message --------
> Subject: Re: JDO Stories
> Date: Fri, 22 Feb 2002 18:13:17 +0000 (GMT)
> From: "akmal @ city" <ak...@so...>
> To: Thomas Mahler <tho...@ho...>
> 
> On Thu, 21 Feb 2002, Thomas Mahler wrote:
> 
>  > Hi Akmal,
>  >
>  > I'm the architect and maintainer of the opensource O/R 
> mapping tool OJB
>  > (http://objectbridge.sf.net).
>  > OJB supports ODMG 3.0 already. We started working on a JDO 
> compliant API
>  > in January.
>  > There's not much to see right now but I could provide a short paper
>  > presenting our approach.
>  >
>  > If you have a special focus of interest just let me know!
>  >
>  > thanks,
>  >
>  > Thomas Mahler
>  >
> 
> Thomas,
> 
> Thanks for emailing. I know about your work! I just haven't 
> had time to
> look at ObjectBridge.
> 
> Yes, your idea sounds good. There is plenty of time, so don't 
> worry. I'll
> send more details if I get enough critical mass to get this project
> moving.
> 
> In the meantime, if you are interested in contributing 
> anything to the IBM
> developerWorks web site, let me know, as I will be responsible for the
> Open Source Projects. It will give you a chance to get your work more
> widely known.
> 
> Have a good weekend.
> 
> akmal chaudhri
> IBM developerWorks
> 
> 
> 
> 
> 
> 

[Objectbridge-jdo-dev] CVS is up again!

[Mahler T. <tho...@it...>]

Hi all,

I set up the CVS at sourceforge again.

The CVS entry page is here: http://sourceforge.net/cvs/?group_id=13647

The active module is called ojb-1-0. You can view it at:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/objectbridge/ojb-1-0/

With 
cvs -z3
-d:pserver:ano...@cv...:/cvsroot/objectbridge
co ojb-1-0 
you can checkout the latest snapshot.
(When prompted for a password for anonymous, simply press the Enter key)

Those who wish to check in code should contact me and send me their
SourceForge account so that I can add them to the developer list.

We need some strict rules to avoid problems with CVS. I want to have have
basic guidelines similar to the Jakarta guidelines
(http://jakarta.apache.org/site/guidelines.html)

cu,

Thomas

AW: [Objectbridge-jdo-dev] Intermediate results

[Budde, F. <fri...@vi...>]

Hi Thomas,
> that's great! I loaded your model with the just released 
> Poseidon 1.1 CE
> without problems.
> I intend to have more and more OJB details modeled in 
> Argo/Poseidon CE.
So do I :-)

> 
> I will setup a CVS soon to have this model shared. 
Very good!

> I suggest to keep not everything in one model but to have 
> (say) one .zargo
> per package.
> The reason: .zargo can only be handled as a monolithic binary 
> file by CVS.
> Thus concurrent edits are very difficult to maintain. What do 
> you think?
That's a difficult question. Since there are a lot of inter-package
dependencies I'd suggest to build a single model (at present). 
If we could get rid of some of these dependencies and if we
could define some (kind of) components with one or at most a few facade(s)
which
control access to the component we'd be able
to split the model into separate models for each component.

> I've a question how to use Poseidon diagrams with html (or xml)
> documentation: Until now I simply exported  GIF or PNG files 
> that have to be
> kept up to date manually :-(
> Is there a way to do this automatically or to have some kind 
> of hyperlink
> mechanism from the HTML document into the Poseidon model?
None that I know of. I do it the same way as you do it :-(. 
A kind of scripting language for Poseidon would be nice.

> Another question: how to keep the model in sync with the 
> code? I know Argo
> supports reverse engineering, but does it help to show diffs? 
> 
Actually I haven't used reverse engineering and I'd propose to 
keep on doing it that way. Here is my approach to modeling OJB
- Only model important (logical) features. Keep technical 
  details in the javadoc.
- Use round-trip engineering only for single classes or
  packages and remove or hide technical details after
  importing the class(es).
- Keeping model and code in sync has to be done (mostly) manually.
  It shouldn't be too difficult if the model doesn't contain
  to many technical details (s.above) and if we can find out
  what changed by comparing different cvs versions of the code.

  Frido

AW: [Objectbridge-jdo-dev] Intermediate results

[Mahler T. <tho...@it...>]

Hi Frido,

that's great! I loaded your model with the just released Poseidon 1.1 =
CE
without problems.
I intend to have more and more OJB details modeled in Argo/Poseidon CE.

I will setup a CVS soon to have this model shared.=20
I suggest to keep not everything in one model but to have (say) one =
.zargo
per package.
The reason: .zargo can only be handled as a monolithic binary file by =
CVS.
Thus concurrent edits are very difficult to maintain. What do you =
think?

I've a question how to use Poseidon diagrams with html (or xml)
documentation: Until now I simply exported  GIF or PNG files that have =
to be
kept up to date manually :-(
Is there a way to do this automatically or to have some kind of =
hyperlink
mechanism from the HTML document into the Poseidon model?

Another question: how to keep the model in sync with the code? I know =
Argo
supports reverse engineering, but does it help to show diffs?=20


Thanks for your efforts,

Thomas

> -----Urspr=FCngliche Nachricht-----
> Von: Budde, Frido [mailto:fri...@vi...]
> Gesendet: Samstag, 26. Januar 2002 12:48
> An: 'obj...@li... '
> Betreff: [Objectbridge-jdo-dev] Intermediate results
>=20
>=20
>=20
> Hi,
> thought you might want to have a look at some of my intermediate
> documentation results. It's neither complete nor do I claim=20
> correctness but
> nevertheless it might help to understand the way OJB works.=20
> I'll try to add
> more details in the near future. The most interesting part of=20
> the model at
> present is the interaction diagram describing how a newly=20
> persisted object
> is written to the database.
>=20
> I forgot: It's a uml model created with the community edition=20
> of poseidon (a
> commercial version of argo created by www.gentleware.com).
>=20
> I'd appreciate any comments on the model. Thanks in advance.
>=20
> Frido
>=20
> Thomas: Could you set up a cvs repository so I'd be able to=20
> check in updates
> of the documentation instead of posting it to the newsgroup?
>=20
>=20

[Objectbridge-jdo-dev] Intermediate results

[Budde, F. <fri...@vi...>]

Hi,
thought you might want to have a look at some of my intermediate
documentation results. It's neither complete nor do I claim correctness but
nevertheless it might help to understand the way OJB works. I'll try to add
more details in the near future. The most interesting part of the model at
present is the interaction diagram describing how a newly persisted object
is written to the database.

I forgot: It's a uml model created with the community edition of poseidon (a
commercial version of argo created by www.gentleware.com).

I'd appreciate any comments on the model. Thanks in advance.

Frido

Thomas: Could you set up a cvs repository so I'd be able to check in updates
of the documentation instead of posting it to the newsgroup?

RE: [Objectbridge-jdo-dev] food for thought

[Li, S. (T. - 22 Front) <siy...@ca...>]

Greetings,

I just came across this article. Thought you guys might like to take a look.

http://www.onjava.com/pub/a/onjava/2002/01/23/jdo.html


Siyan Li
Database Administrator

AW: [Objectbridge-jdo-dev] Object Bridge JDO

[Mahler T. <tho...@it...>]

Hi Mihail,

Thanks for you offer to help!
Currently we are not yet coding but are discussing design issues and =
try to
organize the work.

Did you register to the objectbridge-jdo-dev already? Please also have =
a
look at the mailinglist's archive to get an overview about the ongoing
discussions.

Thanks,

Thomas

> -----Urspr=FCngliche Nachricht-----
> Von: Mihail Chirita [mailto:mih...@ya...]
> Gesendet: Mittwoch, 23. Januar 2002 04:10
> An: obj...@li...
> Betreff: [Objectbridge-jdo-dev] Object Bridge JDO
>=20
>=20
> Thomas,
>=20
> I would like to help with this project. I have 3 years
> of Java programming experience and 1.5 years of J2EE.
>=20
> Cheers,
> Mihail
>=20
> __________________________________________________
> Do You Yahoo!?
> Send FREE video emails in Yahoo! Mail!
> http://promo.yahoo.com/videomail/
>=20
> _______________________________________________
> Objectbridge-jdo-dev mailing list
> Obj...@li...
> https://lists.sourceforge.net/lists/listinfo/objectbridge-jdo-dev
>=20

[Objectbridge-jdo-dev] Object Bridge JDO

[Mihail C. <mih...@ya...>]

Thomas,

I would like to help with this project. I have 3 years
of Java programming experience and 1.5 years of J2EE.

Cheers,
Mihail

__________________________________________________
Do You Yahoo!?
Send FREE video emails in Yahoo! Mail!
http://promo.yahoo.com/videomail/

AW: [Objectbridge-jdo-dev] some questions

[Mahler T. <tho...@it...>]

Hi Ros,

> 
> Hi all,
> 
> We're using Castor  as our o-r mapping but we're seeking some 
> replacement
> for our future projects so I want to participate in this 
> project. 

Thanks for considering OJB as a worthy candidate!

> But I've
> some questions already:
> 
> 1. Where I can get RI ? I can't use Sun's site because I'm in 
> Russia so they
> can't verify that my ip doesn't belong to restricted country list.
> 

Oops, I wasn't aware of such problems. I don't know whether SUN is doing
this intentionally. I guess the best thing will be to contact SUN's JDO
group directly to ask them if it is possible to hand the source code to you.

This raises another problem I was not aware of. I thought of building a
OJB-JDO Prototype by simply modifying the RI sources. But I gues we won't be
able to publish these results for copyright- and other legal reasons.

I'm planning to contact SUN's JDO  group and ask them if it is OK to build a
RI based Prototype and publish it at SourceForge.

> 2. I've seen that PersistenceBroker (and its infrastructure) 
> tries to handle
> all issues related to interaction with various jdbc drivers 
> itself (for ex.
> catching specific exception or generating specific sql). 

I'm not ware that any specific SQL is generated. AFAIK there is only one
spot where a specific exception is caught (In class StatementsForClass in
the code for obtaining Statements from a JDBC Connection).

> Castor "engines"
> model ( one sql engine per one db ) for abstracting such 
> issues seems more
> convinient.
> For ex.: interface SQLEngine and some impls are PostgresSQLEngine,
> OracleSQLEngine.
> 

Sure: if there were a lot of places where RDBMS specific programming was
needed it would be a good idea to have such kind of abstraction.
But currently that is IMHO not the case. 
Currently I'm working on getting OJB to work with MS Access. I hope to get
it done without any specific code.


> 3. Can we use CVS on sourceforge instead of providing 
> snapshots ? So we
> won't loose history of changes.
> 

Yes. I offered to work as the projects code integrator. I will setup a
SourceForge CVS once we are starting to share code.

My experience with the OJB-ODMG implementation show that it is important to
have some generally accepted dicipline among the developers:
- don't check in code that does not compile with the build scripts
- don't check in code that requires jars that are not part of our
distribution
- don't check in code that does not pass the JUnit regression tests
- if you check in new code provide JUnit tests that test its functionality
- make your changes only to the latest version of a file (don't just
overwrite important changes of previous checkins)
- mark files as "edit" once you start working on them ( to avoid difficult
merging of code)

I was not successful in getting a common agreement on such minimal standards
of conduct in the OJB-ODMG implementation thus I shutdown the public CVS.
I hope we will be more successful with these issues in the OJB-JDO job!

-- Thomas

> 
> Thanks,
> Ros
> 
> 
> _______________________________________________
> Objectbridge-jdo-dev mailing list
> Obj...@li...
> https://lists.sourceforge.net/lists/listinfo/objectbridge-jdo-dev
> 

[Objectbridge-jdo-dev] some questions

[Rostislav B. <ro...@pl...>]

Hi all,

We're using Castor  as our o-r mapping but we're seeking some replacement
for our future projects so I want to participate in this project. But I've
some questions already:

1. Where I can get RI ? I can't use Sun's site because I'm in Russia so they
can't verify that my ip doesn't belong to restricted country list.

2. I've seen that PersistenceBroker (and its infrastructure) tries to handle
all issues related to interaction with various jdbc drivers itself (for ex.
catching specific exception or generating specific sql). Castor "engines"
model ( one sql engine per one db ) for abstracting such issues seems more
convinient.
For ex.: interface SQLEngine and some impls are PostgresSQLEngine,
OracleSQLEngine.

3. Can we use CVS on sourceforge instead of providing snapshots ? So we
won't loose history of changes.


Thanks,
Ros

[Objectbridge-jdo-dev] (no subject)

[Arthur G. <ag...@ya...>]

Hi Thomas,

I'd like to help with this project.

I've gone through the mailing list archive. Your
proposal and JDO spec will be my readings for next few
days.

Please let me know how I can help.
Thanks for the initiative!

Arthur Gong


__________________________________________________
Do You Yahoo!?
Send FREE video emails in Yahoo! Mail!
http://promo.yahoo.com/videomail/

[Objectbridge-jdo-dev] food for thought

[Thomas M. <tho...@ho...>]

hi all,

For those of you that are not yet JDO experts I have attached a gzipped 
overview. This presentation was held by Craig Russel, JDO specification 
lead back in 2000.
This presentation is not up to date but gives a useful overall picture.
(thanks to Cristian Rath for pointing me to this presentation).

I had several offline discussions with Christian. We came to the 
conclusion that it may be a good idea to form several loose "working 
groups" that focus on several aspects of our JDO implementation.

This may help us in several ways:
- people may share knowledge and ideas
- we will get some common understanding about what we have to do
- it's a way of socialising and getting in touch with each other

Christian prepared a list of topics that we should discuss.
This list is mainly based on the JDO spec.


1. Life Cycle of JDO Instances
  - Term of the JDO Instance (Persistence Capable)
  - JDO identity and uniquing of data store objects (persistent data)
    Application (primary key) identity, Data store identity,
    Non-data store identity
    JDO object id and the characteristics of the implementing class
  - Difference between transient instances and persistent instances
  - Terms of transient transactional, persistent transactional,
    Nontransactional,
    Optimistic Transactions
  - State Transitions (Life Cycle States)

2. JDO Object Model
  - Requirements on JDO instances
  - references to other JDO instances
  - Mapping to the data store
  - Terms of First Class Objects, Second Class Objects,
    System-Defined Classes,
  - Field types of Persistent-capable classes
    Primitive types, Arrays, Immutable Class types, Mutable Class types,
    PersistenceCapable Class types, Object Class types,
    Collection Interface types
  - Inheritance

3. Important API classes
  - Interface PersistenceCapable
  - Interface InstanceCallbacks
  - Interface PersistenceManagerFactory
    Connection Factories for application server support
  - Interface PersistenceManager
    non-managed, non-managed with extended features, managed,
    Threading and synchronization, automatic and transparent
    cache management

4. Transactions
  - Connection Management
    Native, Non-native
    connection pooling, distributed transactions, managed transactions,
    J2EE Connection Architecture (ManagedConnection, ConnectionManager),
    Optimistic Transactions
  - Interface Transaction
  - Relation to PersistenceManager
  - J2EE integration CMT, BMT, etc.

5. Query
  - Relation to the PersistenceManager
  - JDOQL
  - Query execution strategies, large result set support,
    compiled query support,
    thread safe execution
  - Namespace in Queries
  - Element binding, options, Filter specification,
    Parameter declaration,
    Import statements, Variable declaration, Ordering statement
  - Extent interface and the concept


6. The Big Picture
   - get an overall model that presents the essential concepts
   - what are the basic parts and components
   - how do all parts fit together
   - how to they collaborate
   - what structures do we have to build to implement the JDO concepts


Thats our list of topics We believe that it will be good to have 
discussions on these topics.

Christian is interested in participating in the discussion on the big 
picture and on the transaction concepts.

I'm interested in LifeCycle and in the central API classes.

Please contribute your thoughts !

How can we communicate?
- by sending emails to this list
- by sending in code fragments
- by using the discussion forums on the SF site
- by sending offline emails


cu,

Thomas

[Objectbridge-jdo-dev] did you already have a look at the JDO reference implementation ?

[Thomas M. <tho...@ho...>]

Hi all,

I had a look at SUN's JDO Reference Implementation recently.
They have implemented a File based implementation called FOStore.

The RI contains a lot of things that maybe useful for us.
A lot of things are kept completely generic and are not mixed with 
FOStore specific things.

I found that there is even an abstraction of the underlying datastore. 
Its the interface com.sun.jdori.StoreManager:

/**
  * StoreManager represents the datastore to the rest of the JDO components.
  * It provides the means to write and read instances, to get the extent of
  * classes, and to get the object id for a persistence capable object.
  */


 From what I saw I came to the following working hypothesis:
"We can build a OJB-JDO prototype by simply implementing a OJB 
PersistenceBroker based StoreManager implementation"


1. Do you agree ? Or did I miss something? All thoughts are welcome.

2. Is there anyone who would like to work on such a prototype?
    I'm quite busy with maintaining the main OJB distribution and
    supporting OJB users. That's why I can't spend much time on
    coding right now. But of course I'm availabe to dicuss design
    issues.

I'm well aware that JDO is much more complex than ODMG. We will need 
much more in depth knowledge to implement JDO than to build an ODMG 
implementation.

But: I also believe that learning by doing is a valid approach. When I 
started with the ODMG implementation I definitely had NO design concept. 
I started with simply writing empty implementations of all methods! 
(Have a look at the 0.1.1. and 0.1.9 releases to see how it all started...)

That's all for the moment,

cu,

Thomas

[Objectbridge-jdo-dev] Re: OJB-JDO Implementation

[Thomas M. <tho...@ho...>]

Hi Michael,

thanks for you interest and your offer to help!

Michael Azzi wrote:

> Hi Thomas,
> 
> First I would like to thank you from the bottom of my heart
> for the great job that you are doing in leading such a worthy endeavor. 
> I have been following the slow and agonizing progress of the JDO 
> specification since its early days. And the one thing that bothered 
> me the most in this whole JDO process, is the lack of a decent open 
> source implementation that could quickly propel JDO into mainstream
> adoption. 


Yes there are so many commercial tools around that claim to support JDO 
already (don't know about their quality) but no open source projects.
CASTOR claims to have a JDO implementation. But their "JDO" has not much 
in common with SUN's JDO (apart from the name ;-))


> JDO was in dire need for such an implementation as it tries to compete for
> the
> mind share of the developers against other well entrenched technologies 
> such as all these proprietary O/R mapping tools, and CMP entity beans. 


One of my main reasons to launch OJB was my disliking of the EJB entity 
beans concepts. (that's why "OJB" sounds so much like "EJB").


> Now why didn't I start an open source project to do just that, you
> might ask. It's simply because I lacked the expertise in the area
> of transparent persistence, and also due to time constraints on my
> part.


Yes it's really a lot of work !!!


> It is such a welcome relief to see that someone is working on that
> very thing. And I am willing to offer all the support that I can give
> within my limits to make sure that this project is successful, and delivered
> on time. I have extensive experience in server side java development, and
> I think I can put some of that experience to some good use on this project.
> 


That's great! Every helping hand is most welcome!
Have you already read my Proposal 
(http://objectbridge.sf.net/jdo/jdo-proposal.html) and registered to the 
mailinglist?


> On a more technical note, I am wondering if you are contemplating providing
> a connector adaptor for your JDO implementation, that will allow it to be
> integrated with all compliant app servers.


Yes, we should do this. That's still lacking in OJB.


> The other question that I have is, will there ever be support  for LDAP
> servers 
> as data stores in this JDO implementation, instead of RDBMS.
> Just the way Castor DAX once did it. Or is this too much of a distraction
> at this point.


In the early days of OJB I once stated that I want to have it focused on 
  O/R mapping and nothing else.
I believe it was a good decision to get OJB started.

But more and more people are contributing code.
And more and more people are requesting new feature like LDAP integration.
Thus I believe its OK to integrate such features.

(In fact there have been succeful  efforts in my company to reuse the 
OJB abstract query syntax to represent LDAP queries.

The OJB PersistenceBroker API is abstract enough to allow simple LDAP 
implementations. This will integrate smoothly into our overall concepts.)


So, how to get you involved? you should

- register to the jdo-dev mailinglist (all our communication goes 
through this list)
- study the discussions in the mailinglist archive
- read the jdo spec (I guess you know it better than me)


Currently the work is not very well organized. But that is no problem at 
this early stage. We discussion design issues, organization issues, 
documentation concepts, etc.

feel free to comment on these posting. You might also share your ideas 
on how we could get the job done.

Thanks,

Thomas

 

AW: [Objectbridge-jdo-dev] documentation of java packages

[Mahler T. <tho...@it...>]

Hi again,

> > 
> I think package level documentation should not be as detailed as 
> class level documentation. 
>It should focus on on classes and their
> interaction as a whole. (This is an application of the 
> DRY (Don't Repeat Yourself) principle.) Anyone who wants to know 
> how a class works internally should refer to the class level javadoc
> or the source code. Instead of explaining low level details we could
> include a link to the javadoc then the information is just a 
> click away
> 

Ok, now I see clearer: Your prosal covered only the package level but not
the class level (or component level).
I totally agree on this documentation structure !

> 
> > For the ojb.broker.cache package your apporach works fine!
> > But: 
> > 1. there are packages that contains much more classes that 
> > have only little
> > logical coherence (e.g. the ojb.broker.util package).
> > 2. There are packages that contain more classes that are 
> > focussed on more
> > than one logical component.
> > 
> > The package view will only provide a rough overview.
> > I see two options:
> > 1. create suppackages grouped around one logical component 
> 
> Isn't that the way it's meant to be ( :-) ) ...

I agree. And you will find some example for this in OJB. But there are of
course places where several components are kept in one package. But this may
well be a result of the documentation process:
a feedback that things are not separated cleanly enough to have a consistent
package level documentation paradigma.
If we find such "dark spots" we should take this as an opportunity for
refactoring.

> > (this will be
> > very difficult if not impossible for packages like the util package)
> > 2. Introduce an additional level of documentation below the 
> > package level.
> > Say a "component" level.
> > 
> 
> I'd prefer lots of little packages over big packages which 
> contain more
> than one concept  (Thomas: This wasn't hard to guess since you know my
> style of programming :-) ). Nevertheless I see the advantages 
> of grouping
> a lot of helper classes into a util package. I'd propose 
> - trying to group these classes (if that is possible)

That's good! Once we identify such groups we may decide if it makes sense to
create a new subpackage.

> - writing a separate package level documentation for each group
> - writing a separate package level documentation for the rest of
>   the classes which do not belong to any of the groups mentioned above
> - writing a package.html file for the package that contains 
> descriptions
>   of the groups and links to the 'real' documentation.
> This approach would provide for easy refactoring. Simply put all 
> classes mentioned in the documentation in a separate package and
> move the documentation describing these classes in that 
> package as well.

that's a good approach to deal with changing (improving !) structures.

> 
> Nevertheless I think Thomas is right when he said that there exist
> kinds of documentation which do not fit well into package level
> documentation e.g. information which cover the whole or a major
> part of OJB. What about having some extra documents like concepts
> or (similar to the jdc) trails which have a broader scope than
> package or class level documentation.
>  

Yes, general concepts, tutorials, overviews are also needed.
 

> 
> > > Is the information presented in the right order/hierachy?
> > 
> > I guess It depends on the focus you have if the order seems right. 
> > I would prefer to have the  conceptual things at the top of 
> > the document,
> > like in this structure:
> > 
> > Intent
> > Detailed Description
> > Diagramms
> > Patterns used
> > Dependencies on other packages
> > Hints for extending and maintaining this package
> > Todo
> > 
> > But I can imagine that others are more interested to see a 
> > more structural
> > overview first. 
> > 
> If you don't miss a whole section then it's easy to change
> the order of sections within the xml files (I'll happily
> supply a xsl stylesheet which will reorder the sections.)

Using XSLT we can thus provide user specific perspectives on the
documentation. 

> The problem is that the first time you look into 
> package level documentation you'll probably want to get an
> overview. Once you've understood the concepts and start using
> or changing the package you'll probably want to have a look 
> at the details...

Yup, that makes sense too...

> 
> > Where can I get the docbook dtd (or xsd) ?
> > 
> http://www.oasis-open.org/docbook/#documents
> Also have a look at
> http://www.docbook.org
> where you'll find a html version of the book
> "DocBook: The Definitive Guide"
> And last but not least
> www.nwalsh.com and http://sourceforge.net/projects/docbook
> which contain a wealth of tools and valuable
> information about docbook.
> 

thanks for the links! 


cu,

Thomas

AW: [Objectbridge-jdo-dev] documentation of java packages

[Budde, F. <fri...@vi...>]

Hi,

> 
> > Too much/little detail?
> 
> Maybe we need more indepth information (see my old
> http://objectbridge.sourceforge.net/system/objectcache.html where I'm
> explaining the softreference mechanism)
> But maybe it's better to have such details not on the package level ?
> 
> > Which kind of documentation did you miss?
> 
> in my old system docs I used the following structure:
> - what it does 
> - how it works
> - write your own implementations
> 
> For me the "how it works" part is not covered enough.
> Again: maybe its better not have this kind of information on 
> the package
> level.
> 
I think package level documentation should not be as detailed as 
class level documentation. It should focus on on classes and their
interaction as a whole. (This is an application of the 
DRY (Don't Repeat Yourself) principle.) Anyone who wants to know 
how a class works internally should refer to the class level javadoc
or the source code. Instead of explaining low level details we could
include a link to the javadoc then the information is just a click away


> For the ojb.broker.cache package your apporach works fine!
> But: 
> 1. there are packages that contains much more classes that 
> have only little
> logical coherence (e.g. the ojb.broker.util package).
> 2. There are packages that contain more classes that are 
> focussed on more
> than one logical component.
> 
> The package view will only provide a rough overview.
> I see two options:
> 1. create suppackages grouped around one logical component 

Isn't that the way it's meant to be ( :-) ) ...

> (this will be
> very difficult if not impossible for packages like the util package)
> 2. Introduce an additional level of documentation below the 
> package level.
> Say a "component" level.
> 

I'd prefer lots of little packages over big packages which contain more
than one concept  (Thomas: This wasn't hard to guess since you know my
style of programming :-) ). Nevertheless I see the advantages of grouping
a lot of helper classes into a util package. I'd propose 
- trying to group these classes (if that is possible)
- writing a separate package level documentation for each group
- writing a separate package level documentation for the rest of
  the classes which do not belong to any of the groups mentioned above
- writing a package.html file for the package that contains descriptions
  of the groups and links to the 'real' documentation.
This approach would provide for easy refactoring. Simply put all 
classes mentioned in the documentation in a separate package and
move the documentation describing these classes in that package as well.

Nevertheless I think Thomas is right when he said that there exist
kinds of documentation which do not fit well into package level
documentation e.g. information which cover the whole or a major
part of OJB. What about having some extra documents like concepts
or (similar to the jdc) trails which have a broader scope than
package or class level documentation.
  

> > Is the information presented in the right order/hierachy?
> 
> I guess It depends on the focus you have if the order seems right. 
> I would prefer to have the  conceptual things at the top of 
> the document,
> like in this structure:
> 
> Intent
> Detailed Description
> Diagramms
> Patterns used
> Dependencies on other packages
> Hints for extending and maintaining this package
> Todo
> 
> But I can imagine that others are more interested to see a 
> more structural
> overview first. 
> 
If you don't miss a whole section then it's easy to change
the order of sections within the xml files (I'll happily
supply a xsl stylesheet which will reorder the sections.)
The problem is that the first time you look into 
package level documentation you'll probably want to get an
overview. Once you've understood the concepts and start using
or changing the package you'll probably want to have a look 
at the details...

> Where can I get the docbook dtd (or xsd) ?
> 
http://www.oasis-open.org/docbook/#documents
Also have a look at
http://www.docbook.org
where you'll find a html version of the book
"DocBook: The Definitive Guide"
And last but not least
www.nwalsh.com and http://sourceforge.net/projects/docbook
which contain a wealth of tools and valuable
information about docbook.


  Frido

PS: I'd like to thank everyone for the comments on the documentation format.

Re: [Objectbridge-jdo-dev] documentation of java packages

[Bruce S. <fe...@fr...>]

Frido, All, 

Nice job on the documentation. I second Thomas in saying that it's a
very strategic move to author the documentation in XML. Because the
build will be handled by Ant, the XML can be rendered into any format
necessary on the fly (HTML, PDF, etc.). 

Bruce Snyder

AW: [Objectbridge-jdo-dev] documentation of java packages

[Mahler T. <tho...@it...>]

Hi Frido, hi all,

> Hi,
> since I volunteered for documenting the project I'd like to 
> ask you for
> comments about a java package documentation template for 
> docbook I've made
> up during the weekend.

Thanks for your proposal!


> To put it to the test I chose the (simply structured) java package
> ojb.broker.cache.
> 
> I've attached
> - the html version of the documentation template,
> - the html version of the documentation of ojb.broker.cache,
> - a gif of a class diagram of ojb.broke.cache made with poseidon and
> - the xml version of the documentation of ojb.broker.cache.
> 

> I'd appreciate any kind of comment on the template (and the cache
> documentation). Especially I'd like to know:
> Do you think the information is relevant?

I gives a brieve and clear overview  about the cache package! I like the
Pattern and Diagram section! 

> Too much/little detail?

Maybe we need more indepth information (see my old
http://objectbridge.sourceforge.net/system/objectcache.html where I'm
explaining the softreference mechanism)
But maybe it's better to have such details not on the package level ?

> Which kind of documentation did you miss?

in my old system docs I used the following structure:
- what it does 
- how it works
- write your own implementations

For me the "how it works" part is not covered enough.
Again: maybe its better not have this kind of information on the package
level.

For the ojb.broker.cache package your apporach works fine!
But: 
1. there are packages that contains much more classes that have only little
logical coherence (e.g. the ojb.broker.util package).
2. There are packages that contain more classes that are focussed on more
than one logical component.

The package view will only provide a rough overview.
I see two options:
1. create suppackages grouped around one logical component (this will be
very difficult if not impossible for packages like the util package)
2. Introduce an additional level of documentation below the package level.
Say a "component" level.

> Is the information presented in the right order/hierachy?

I guess It depends on the focus you have if the order seems right. 
I would prefer to have the  conceptual things at the top of the document,
like in this structure:

Intent
Detailed Description
Diagramms
Patterns used
Dependencies on other packages
Hints for extending and maintaining this package
Todo

But I can imagine that others are more interested to see a more structural
overview first. 


> What do you think about the format docbook?

The docbook format is quite readable! helps to build good organized
structures.

> Thanks in advance for your comments.
> 
> Of course there is still a lot to do
> - Create a stylesheet to improve the graphical 
>   representation of the documentation (Currently it looks 
>   much nicer in the XXE editor than in the browser)
> - Customize the xsl docbook stylesheet to integrate
>   the generated html with javadoc

Where can I get the docbook dtd (or xsd) ?

cu,

Thomas

> 
> Awaiting your replies
>   Frido
> 
> PS: English is not my native language. Therefore I'd very 
> much appreciate
> any hints on incorrectly used words or phrases because I think that
> documentation should be as accurate and intelligible as possible.
> 
> 

[Objectbridge-jdo-dev] package documentation

[Christian R. <chr...@we...>]

Hi Frido,

I like the structure of the package documentation.
The sections "Patterns used",=20
"Dependencies on other packages",
"Hints for extending and maintaining this package"
are a very good idea.=20
Helpful information for extending and maintaining the framework.
I think there's nothing to add.
The descriptions are short, meaningful and plain.

To make a short story short.
Good work.

 Christian
=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=5F=
=5F=5F=5F=5F
Eine Klasse f=FCr sich - der WEB.DE Club. High End Kommunikation & MEHR.
Mehr Speicher, mehr Leistung, mehr Vorteile - http://club.web.de

[Objectbridge-jdo-dev] documentation of java packages

[Budde, F. <fri...@vi...>]

Hi,
since I volunteered for documenting the project I'd like to ask you for
comments about a java package documentation template for docbook I've made
up during the weekend.
To put it to the test I chose the (simply structured) java package
ojb.broker.cache.

I've attached
- the html version of the documentation template,
- the html version of the documentation of ojb.broker.cache,
- a gif of a class diagram of ojb.broke.cache made with poseidon and
- the xml version of the documentation of ojb.broker.cache.

I'd appreciate any kind of comment on the template (and the cache
documentation). Especially I'd like to know:
Do you think the information is relevant?
Too much/little detail?
Which kind of documentation did you miss?
Is the information presented in the right order/hierachy?
What do you think about the format docbook?
Thanks in advance for your comments.

Of course there is still a lot to do
- Create a stylesheet to improve the graphical 
  representation of the documentation (Currently it looks 
  much nicer in the XXE editor than in the browser)
- Customize the xsl docbook stylesheet to integrate
  the generated html with javadoc

Awaiting your replies
  Frido

PS: English is not my native language. Therefore I'd very much appreciate
any hints on incorrectly used words or phrases because I think that
documentation should be as accurate and intelligible as possible.

[Objectbridge-jdo-dev] Re: cvs?

[Thomas M. <tho...@ho...>]

Hi Mike,

Thanks for your interest and your offer to help!

Mike Perham wrote:

> I'm interested in helping out.  I've read through your proposals, where
> can I get the latest source?
>


We are currently discussing design issues and how the work can be 
organized, etc.

an archive of the objectbridge-jdo-dev mailinglist can be found here:
http://www.geocrawler.com/lists/3/SourceForge/18443/0/

You should register to  the objectbridge-jdo-dev discussionlist here:
http://lists.sourceforge.net/lists/listinfo/objectbridge-jdo-dev

We have not yet started coding. That's why there is no CVS archive right 
now.

To get impression about the work to be done you should have a look at 
the existing OJB ODMG implementation as contained in the latest OJB 
source distribution (release 0.7.290).

You also should read the JDO spec.

that's all for the moment!

cu,

Thomas

--------------------------------
OJB: There is no JDO like we do.

 

[Objectbridge-jdo-dev] Re: Ref: Help Wanted

[Thomas M. <tho...@ho...>]

Hi Vikas,

thanks for your interest and your offer to help!

Vikas Lamba wrote:

> I was going through the project source and 
> functionality and am impressed by it. I would 
> like to contribute to the project if developers 
> are still required as advertised on the project 
> page.
> 
> I'm working as an Analyst in a software company 
> in New Delhi, India. I have two and a half years 
> of work experience in the software field.
> 
> Hoping for a favourable reply.
> 
> Vikas
> 



We are still in the launch phase of the JDO implementation. That is 
there no design or implementation work going on.

We are currently discussing design issues and how the work can be organized.

Things may seem a bit unorganized right now. There is no centralized 
organization right now and we have find our style how things can be done 
  in a team distributed around the globe.

an archive of our discussions in the objectbridge-jdo-dev mailinglist 
can be found here:
http://www.geocrawler.com/lists/3/SourceForge/18443/0/

You should register to  the objectbridge-jdo-dev mailinglist here:
http://lists.sourceforge.net/lists/listinfo/objectbridge-jdo-dev

The work is coordinated through this list. Currently there is not that much
traffic as we are not yet that organized...

To get started you should read my proposal:
http://objectbridge.sourceforge.net/jdo/jdo-proposal.html,

Comments are most welcome !

study the JDO specification and
study the architecture of the OJB ODMG implementation.

that's all for the moment!

cu,

Thomas

[Objectbridge-jdo-dev] Re: [OJB-developers] Stable branch for version 1.0 ?

[Thomas M. <tho...@ho...>]

Hi Lasse,



Lasse Lindgard wrote:

> Will ORB development branch for the version 2.0 development ?
> 
> With the rather large refactorings that Thomas suggests I find it hard to
> belive that the interface won't change and that bugs won't be introduced.
> 
> I belive that keeping a branch for stablizing version 1.0 would make it
> possible for a lot of developers to start using ORB in production sites.
> 



You are right.
The development of OJB 2.0 should not destabilize the existing release!
If necessary we will have to maintain a branch.
But I hope it will not be necessary as it will be a lot of unproductive 
work to maintain a branch.

Just my 0.02EUR

Thomas




> Just my 2?
> 
> /Lasse
> 
> 
> 
> _______________________________________________
> Objectbridge-developers mailing list
> Obj...@li...
> https://lists.sourceforge.net/lists/listinfo/objectbridge-developers
> 
> 
> 
>