Mailing-List: contact oak-dev-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-dev@jackrabbit.apache.org
Received-SPF: pass (nike.apache.org: domain of anchela@adobe.com designates
 64.18.1.183 as permitted sender)
Message-ID: <4F8FD17A.8040204@adobe.com>
Date: Thu, 19 Apr 2012 10:48:58 +0200
From: Angela Schreiber <anchela@adobe.com>
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US;
 rv:1.9.2.18) Gecko/20110616 Thunderbird/3.1.11
MIME-Version: 1.0
To: <oak-dev@jackrabbit.apache.org>
Subject: Re: Oak API - a top down look
References: 
 <CAOFYJNb88iwYpX0w=yQsP_3yTTUnM3QqezBv-Dui8wPbuAOEbw@mail.gmail.com>
In-Reply-To: 
 <CAOFYJNb88iwYpX0w=yQsP_3yTTUnM3QqezBv-Dui8wPbuAOEbw@mail.gmail.com>
Content-Type: text/plain; charset="ISO-8859-1"; format=flowed
Content-Transfer-Encoding: 7bit

hi

> This is just a draft proposal, so please critique or propose
> alternatives, ideally in a format like this so that we'll be able to
> use the resulting consensus as the beginning of more comprehensive API
> documentation.

i like the proposal in general as it seems to summarize what michi
and myself have been discussion regarding the oak-api last week.
two comments from my side:

- the workspace story
- access control restrictions

1. workspace story
------------------------------------------------------------------------

as already stated in reply to felix/jukkas discussion in this thread
that i have a different preference regarding on the relationship
between ContentSession and JCR Session/Workspace... but i am convinced
that we can reach consensus on this once we have a better picture on 
access control, permission evaluation, versioning and representation of 
repository-level content as this most probably will have an impact.


2. access control restrictions
------------------------------------------------------------------------

there is one thing that we have to keep in mind when it comes to
the ContentTree interface and the information it exposes to the oak-jcr:

due to the fact that permission evaluation will be located in oak-core
the ContentTree might be incomplete. a given user may not be able
to read the root node but having access to items somewhere in the
subtree.

thus:

>      ContentSession session = ...;
>      ContentTree tree = session.getCurrentContentTree();

if the tree here really represents a node that might be problematic
(and the name seems rather misleading to me in this case).
however, if we look at ContentTree as an abstract point in the
hierarchy that is identified by an identifier that might work.
but then the ContentTree interface should not have methods that
actually belong to a Node... or we need the possibility to determine
if there is an accessible 'NodeState' with a given 'tree'.

second we need to have the ability to access item information
somewhere in the subtree without having to traverse (see above).

there are for sure multiple possibilities to achieve this, such
as e.g.
- ContentSession.getCurrentContentTree take (must have) a path
   -> contentree was more of a node again
   -> how do you assert then that transient modifications are
      always persisted together since we don't want to support
      Item#save() any more???

- ContentTree in addition has a method getNodeState that would
   actually represent the Node. the tree was then just the
   representation of the path and the modifier/access methods
   should rather be moved to NodeState.

- ...

kind regards
angela


> The returned `ContentTree` instance belongs to the client and its state is
> only modified in response to method calls made by the client. `ContentTree`
> instances are *not* thread-safe, so the client needs to ensure that they are
> not accessed concurrently from multiple threads. Content trees are
> recursive data structures that consist of named properties and subtrees
> that share the same namespace, but are accessed through separate methods
> like outlined below:
>
>      ContentTree tree = ...;
>      for (PropertyState property : tree.getProperties()) {
>          ...;
>      }
>      for (ContentTree subtree : tree.getSubtrees()) {
>          ...;
>      }
>
> The repository content snapshot exposed by a `ContentTree` instance may
> become invalid over time due to garbage collection of old content, at which
> point an outdated snapshot will start throwing `IllegalStateExceptions` to
> indicate that the snapshot is no longer available. To access more recent
> content, a client should either call `getCurrentContentTree()` to acquire
> a fresh now content snapshot or use the `refresh()` method to update a
> given `ContentTree` to the latest state of the content repository:
>
>      ContentTree tree = ...;
>      tree.refresh();
>
> In addition to reading repository content, the client can also make
> modifications to the content tree. Such content changes remain local
> to the particular `ContentTree` instance (and related subtrees) until
> explicitly committed. For example, the following code creates and commits
> a new subtree containing nothing but a simple property:
>
>      ContentTree tree = ...;
>      ContentTree subtree = tree.addSubtree("hello");
>      subtree.setProperty("message", "Hello, World!");
>      tree.commit();
>
> Even other `ContentTree` instances acquired from the same `ContentSession`
> won't see such changes until they've been committed and the other trees
> refreshed. This allows a client to track multiple parallel sets of changes
> with just a single authenticated session.