Confusions about API's and Flavours in the documentation ...

[KÖLL Claus <C....@TIROL.GV.AT>]

Hi,

After looking more and more into the oak codebase i feel sometimes a little bit confused with the documentation. 
I think the documentation doesn't reflect the reality in the codebase regarding the Microkernel API and NodeStore API for the two flavours (microkernel / nodestore).

In the big picture we have the NodeStore Layer and underneath the SegmentMK, DocumentMK and the KernelNodeStore.
I think SegmentNodeStore and DocumentNodeStore would be correct ??

One confusing thing is that the SegmentMK (also used in other pages) isn't really a implementation but the DocumentMK is one.
DocumentMK is also used here http://jackrabbit.apache.org/oak/docs/nodestore/documentmk.html but i think this page describes more the 
NodeStore API from the document flavour or not ?

A little bit confusing is also the configuration of a DocumentNodeStore. You will get a dependency to the DocumentMK which belongs in my view to
the Microkernel API. Maybe it would be better to move the Builder to its own class so it could be used in both API's.

greets
claus

AW: Confusions about API's and Flavours in the documentation ...

[KÖLL Claus <C....@TIROL.GV.AT>]

Hi,

Ok thanks for your feedback ...

>And yes, it's confusing.
.. so I'm not alone here :-)

I would change the documentation to better fit the right terms.

greets
claus

Re: Confusions about API's and Flavours in the documentation ...

[Thomas Mueller <mu...@adobe.com>]

Hi,

I think the documentation shouldn't talk about SegmentMK, specially
because such a class doesn't exist. Instead, I think it should talk about
the high level concepts "segment storage" and "document storage", plus
concrete implementations "tar file persistence" (based on the segment
storage), and "MongoDB persistence" / "relational database persistence"
(both based on the document storage).

I don't think we should use internal class and internal interface names in
the user documentation, as those can still change: it's an implementation
detail. And yes, it's confusing.

Regards,
Thomas


On 12/08/14 13:24, "KÖLL Claus" <C....@TIROL.GV.AT> wrote:

>Hi,
>
>After looking more and more into the oak codebase i feel sometimes a
>little bit confused with the documentation.
>I think the documentation doesn't reflect the reality in the codebase
>regarding the Microkernel API and NodeStore API for the two flavours
>(microkernel / nodestore).
>
>In the big picture we have the NodeStore Layer and underneath the
>SegmentMK, DocumentMK and the KernelNodeStore.
>I think SegmentNodeStore and DocumentNodeStore would be correct ??
>
>One confusing thing is that the SegmentMK (also used in other pages)
>isn't really a implementation but the DocumentMK is one.
>DocumentMK is also used here
>http://jackrabbit.apache.org/oak/docs/nodestore/documentmk.html but i
>think this page describes more the
>NodeStore API from the document flavour or not ?
>
>A little bit confusing is also the configuration of a DocumentNodeStore.
>You will get a dependency to the DocumentMK which belongs in my view to
>the Microkernel API. Maybe it would be better to move the Builder to its
>own class so it could be used in both API's.
>
>greets
>claus

Re: Confusions about API's and Flavours in the documentation ...

[Michael Dürig <md...@apache.org>]

On 12.8.14 1:24 , KÖLL Claus wrote:
> Hi,
>
> After looking more and more into the oak codebase i feel sometimes a little bit confused with the documentation.
> I think the documentation doesn't reflect the reality in the codebase regarding the Microkernel API and NodeStore API for the two flavours (microkernel / nodestore).

Unfortunately these terms are not used consistently. There is an 
Microkernel API and a NodeStore API, which are roughly equivalent in the 
provided functionality. The term Microkernel however is often used in 
the broader sense to refer to any implementation of either of the two APIs.

Michael

>
> In the big picture we have the NodeStore Layer and underneath the SegmentMK, DocumentMK and the KernelNodeStore.
> I think SegmentNodeStore and DocumentNodeStore would be correct ??
>
> One confusing thing is that the SegmentMK (also used in other pages) isn't really a implementation but the DocumentMK is one.
> DocumentMK is also used here http://jackrabbit.apache.org/oak/docs/nodestore/documentmk.html but i think this page describes more the
> NodeStore API from the document flavour or not ?
>
> A little bit confusing is also the configuration of a DocumentNodeStore. You will get a dependency to the DocumentMK which belongs in my view to
> the Microkernel API. Maybe it would be better to move the Builder to its own class so it could be used in both API's.
>
> greets
> claus
>