jackrabbit-oak-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Dürig <mdue...@apache.org>
Subject Re: Oak API - a top down look
Date Wed, 18 Apr 2012 05:47:47 GMT


On 18.4.12 0:32, Michael Dürig wrote:
>
> Hi,
>
> On 17.4.12 22:28, Jukka Zitting wrote:
>>
>> 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
>
> Thanks Jukka for that proposal. This seems to be largely a wrap up/clean
> up of what's already there and I quite like the names you are proposing!
> Two things:
>
> - ContentSession.getCurrentContentTree() returns a snapshot of the whole
> tree. Wouldn't it be useful to be able to get snapshots of just a
> sub-tree? Like it is currently possible with NodeStore.branch()?
>
> - Having a refresh() method on ContentTree is troublesome. What would it
> refresh if you call it on a sub-tree? That sub-tree only? The underlying
> implementation would then effectively have to manage a MK revision for
> each node (i.e. SubTree) of the content tree. Worse, on commit, against
> which revision would such a tree be committed? In the current
> implementation the refresh method would go into the Branch class.

The same actually goes for the commit method. I think it is somewhat 
miss placed on ContentTree too. What about introducing a ContentRoot 
extends ContentTree class which contained said methods? An instance of 
that class would then be returned from 
ContentSession.getCurrentContentTree().

Michael

>
> Michael
>
>>
>> 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.


Mime
View raw message