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.25 as permitted sender)
Message-ID: <4F903252.1040204@adobe.com>
Date: Thu, 19 Apr 2012 17:42:10 +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>
 <4F9011F9.405@apache.org>
In-Reply-To: <4F9011F9.405@apache.org>
Content-Type: text/plain; charset="ISO-8859-1"; format=flowed
Content-Transfer-Encoding: 7bit


> The main open questions now revolve around workspaces and permissions.

well, there are actually no questions regarding permissions. it's
pretty clear what we want/have to do and where we need to do it.
the only question is if that's possible and sensible with the
whole-repo-exposure on oak-api. i am not convinced.

but there are IMO open questions regarding versioning and query.

and i would really like to hear what was the use-case of the repo-view
except for workspace.copy, clone and createFromOtherWorkspace.

note in addition all the rest of the cross-workspace operations
are part of the versioning API, which would - according
to our discussions - be reflected on the oak-API anyway.

kind regards
angela

> Michael
>
>
> On 17.4.12 22:28, Jukka Zitting wrote:
>> Hi,
>>
>> Over the past week or two we've been going in a lot of different
>> directions with the Oak API. Rather than comment on individual details
>> in the various related threads and issues, let me step back a bit and
>> outline one possible vision of how the API could/should work. Most of
>> the included bits we already have in various places, and I'm just
>> trying to put them together in a slightly more coherent way.
>>
>> So see below (HTML version at [1]) for a top-down draft of how the
>> concepts of the API could fit together. I'm basically taking the
>> existing RepositoryService, Connection and
>> NodeStateEditor/TransientNodeState interfaces and casting them
>> slightly differently with a new set of names.
>>
>> 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.
>>
>> [1] https://github.com/jukka/jackrabbit-oak/blob/trunk/oak-core/README.md
>>
>> BR,
>>
>> Jukka Zitting
>>
>>
>> Oak API
>> -------
>>
>> The API for accessing core Oak functionality is located in the
>> `org.apache.jackrabbit.oak.api` package and consists of the following
>> key interfaces:
>>
>>     * ContentRepository
>>     * ContentSession
>>     * ContentTree
>>
>> The `ContentRepository` interface represents an entire Oak content repository.
>> The repository may local or remote, or a cluster of any size. These deployment
>> details are all hidden behind this interface.
>>
>> Starting and stopping `ContentRepository` instances is the responsibility of
>> each particular deployment and not covered by these interfaces. Repository
>> clients should use a deployment-specific mechanism (JNDI, OSGi service, etc.)
>> to acquire references to `ContentRepository` instances.
>>
>> All content in the repository is accessed through authenticated sessions
>> acquired through the `ContentRepository.login()` method. The method takes
>> explicit access credentials and other login details and, assuming the
>> credentials are valid, returns a `ContentSession` instance that encapsulates
>> this information. Session instances are `Closeable` and need to be closed
>> to release associated resources once no longer used. The recommended access
>> pattern is:
>>
>>       ContentRepository repository = ...;
>>       ContentSession session = repository.login(...);
>>       try {
>>           ...; // Use the session
>>       } finally {
>>           session.close();
>>       }
>>
>> All `ContentRepository` and `ContentSession` instances are thread-safe.
>>
>> The authenticated `ContentSession` gives you properly authorized access to
>> the hierarchical content tree inside the repository through instances of the
>> `ContentTree` interface. The `getCurrentContentTree()` method returns a
>> snapshot of the current state of the content tree:
>>
>>       ContentSession session = ...;
>>       ContentTree tree = session.getCurrentContentTree();
>>
>> 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.