jackrabbit-oak-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Angela Schreiber <anch...@adobe.com>
Subject Re: Oak API - a top down look
Date Thu, 19 Apr 2012 15:42:10 GMT

> 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

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

View raw message