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.
