Documentation: SQL object store

[Kevin Meyer <ke...@kmz.co.za>]

Hi Everyone,

I've started slowly chipping away at writing the supporting documentation
for the SQL object store (thanks Dan for suggesting 25 minute slots!).

Now my question is: If you have an opinion, what would you like to see
in such a document?

At the moment I'm just putting down whatever comes into my head, with
a view of later editting it into a coherent document, but obviously
there are questions of level of detail, etc. For example, should I
really bother with describing what persistance is, and how the domain
classes are introspected?!

Yes to: what SQL data types are used by default, yes to: how to override
the automappers and provide your own mapper, yes to: how collections
and parent/child relatonships are handled, etc.

What else?

Regards,
Kevin

Re: Documentation: SQL object store

[Kevin Meyer - KMZ <ke...@kmz.co.za>]

On 1 Feb 2011 at 6:57, Dan Haywood wrote:

> > Now my question is: If you have an opinion, what would you like to see
> > in such a document?
> >
> It'd be worth showing examples of all the different types of mappings 
> supported, as well as those that are not supported.
> 

Thanks for these and other comments. Every little bit helps.

Regards,
Kevin

Re: Documentation: SQL object store

[Dan Haywood <dk...@gmail.com>]

On 01/02/2011 06:27, Kevin Meyer wrote:
> Hi Everyone,
>
>
> Now my question is: If you have an opinion, what would you like to see
> in such a document?
>
> At the moment I'm just putting down whatever comes into my head, with
> a view of later editting it into a coherent document, but obviously
> there are questions of level of detail, etc. For example, should I
> really bother with describing what persistance is, and how the domain
> classes are introspected?!
I don't think so, no.

That said, if you do find yourself writing "introductory" material like 
this, we can always move it.  The place for such stuff should probably 
be the "core" documentation (core/src/docbkx/guide/isis-core.xml), which 
is what I'm chipping away at myself.

> Yes to: what SQL data types are used by default, yes to: how to override
> the automappers and provide your own mapper, yes to: how collections
> and parent/child relatonships are handled, etc.
It'd be worth showing examples of all the different types of mappings 
supported, as well as those that are not supported.

For example:
- Id generation - how is that supported?
- optimistic locking - how supported?
- one<->many
- one<-many
- one->many
- two one<->many relationships between same types A and B (if I recall, 
this isn't supported?)
- many<->many
- many->many
- subtype relationships (roll-up, roll-down, table per subtype)
- polymorphic relationships to interfaces


You could also peruse some of the Hibernate ORM docs for examples of 
mappings there; that might prompt you to consider some additional scenarios.



> What else?
Obviously, any additional entries required in isis.properties to enable 
the SQL object store.

In addition, as background it'd be worth explaining about the different 
subcomponents used by the object store: the OidGenerator, 
PersistAlgorithm, TransactionManager

Also, I know that the JPA object store has to configure a different 
ClassSubstitutor/ObjectFactory, because it leaves the ORM to perform 
cglib proxying.  I don't think you have any similar restrictions, but it 
might be worth saying so.

> Regards,
> Kevin
>
>

Pomodoro Technique

[Dan Haywood <dk...@gmail.com>]

On 01/02/2011 06:27, Kevin Meyer wrote:
> I've started slowly chipping away at writing the supporting documentation
> for the SQL object store (thanks Dan for suggesting 25 minute slots!).

What Kevin is referring to here is something I mentioned to him on IRC, 
namely the "Pomodoro Technique" [1].  The idea is to work solely on a 
single task for 25 minutes; if something else pops into your mind while 
working on that task, then make a quick note of it but then carry on 
with what you are meant to be working on.

For myself, I've been using this technique to just do a little on Isis 
each and every day.  I try to do either one or two "pomodoros" on Isis 
before starting getting down to (proper, paid, non-Isis) work, and I try 
to do one or two pomodoros at the end of the working day if I have the 
energy.

I'm keen that we maintain momentum with Isis, but obviously we all have 
"real" jobs to do.  If you'd like to be contributing more to Isis but 
haven't managed to get started, why not try this technique and see if it 
works for you?

Cheers
Dan

PS: as an extension on this technique, keep a calendar and put a X in it 
for every day that you were able to perform a pomodoro.  After a while, 
you won't want to break your streak.  Apparently Jerry Seinfeld (the US 
comedian) uses this to write new material every day.  Some of the 
authors at pragprog.com are also using it as a way of writing their books.

PPS: of course, this technique can be used for anything you want to work 
on, not just Isis !

[1] http://www.pomodorotechnique.com/