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 Tue, 17 Apr 2012 23:32:19 GMT


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.


> 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