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 Thu, 19 Apr 2012 13:24:09 GMT

Hi,

I updated the proposal in the areas where we seem to have a consensus:

- weakened thread safety requirement for concurrent read access on 
ContentTree.

- moved commit() and refresh() from ContentTree to ContentSession

See 
https://github.com/mduerig/jackrabbit-oak/commit/22f6bd8bc0b61e80b4b10697fcaa73b2ebf1a881

The main open questions now revolve around workspaces and permissions.

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.

Mime
View raw message