You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by ju...@apache.org on 2012/04/24 21:48:28 UTC
svn commit: r1329968 - in /jackrabbit/oak/trunk/oak-core: README.md
src/main/java/org/apache/jackrabbit/oak/api/Tree.java
Author: jukka
Date: Tue Apr 24 19:48:28 2012
New Revision: 1329968
URL: http://svn.apache.org/viewvc?rev=1329968&view=rev
Log:
OAK-18: Define Oak API
Update documentation to match recent renamings and other changes
Modified:
jackrabbit/oak/trunk/oak-core/README.md
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Tree.java
Modified: jackrabbit/oak/trunk/oak-core/README.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/README.md?rev=1329968&r1=1329967&r2=1329968&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/README.md (original)
+++ jackrabbit/oak/trunk/oak-core/README.md Tue Apr 24 19:48:28 2012
@@ -10,7 +10,7 @@ key interfaces:
* ContentRepository
* ContentSession
- * ContentTree
+ * Root / Tree
The `ContentRepository` interface represents an entire Oak content repository.
The repository may local or remote, or a cluster of any size. These deployment
@@ -41,19 +41,19 @@ All `ContentRepository` and `ContentSess
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
+`Root` and `Tree` interfaces. The `getCurrentRoot()` method returns a
snapshot of the current state of the content tree:
ContentSession session = ...;
- ContentTree tree = session.getCurrentContentTree();
+ Root root = session.getCurrentRoot();
+ Tree tree = root.getTree();
-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 for write access, so writing clients need
-to ensure that they are not accessed concurrently from multiple threads.
-`ContentTree` instances *are* however thread-safe for read access, so
-implementations need to ensure that all reading clients see a coherent
-state.
+The returned `Tree` instance belongs to the client and its state is only
+modified in response to method calls made by the client. `Tree` instances
+are *not* thread-safe for write access, so writing clients need to ensure
+that they are not accessed concurrently from multiple threads. `Tree`
+instances *are* however thread-safe for read access, so implementations
+need to ensure that all reading clients see a coherent state.
Content trees are recursive data structures that consist of named properties
and subtrees that share the same namespace, but are accessed through separate
@@ -63,36 +63,36 @@ methods like outlined below:
for (PropertyState property : tree.getProperties()) {
...;
}
- for (ContentTree subtree : tree.getSubtrees()) {
+ for (Tree 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
+The repository content snapshot exposed by a `Tree` 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:
+content, a client should either call `getCurrentRoot()` to acquire a fresh
+new content snapshot or use the `refresh()` method to update a given `Root`
+to the latest state of the content repository:
- ContentSession session = ...;
- ContentTree tree = ...;
- session.refresh(tree);
+ Root root = ...;
+ root.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:
+modifications to the content tree. Such content changes remain local to the
+particular `Root` instance (and related subtrees) until explicitly committed.
+For example, the following code creates and commits a new subtree containing
+nothing but a simple property:
ContentSession session = ...;
- ContentTree tree = ...;
- ContentTree subtree = tree.addSubtree("hello");
+ Root root = session.getCurrentRoot();
+ Tree tree = root.getTree("/");
+ Tree subtree = tree.addSubtree("hello");
subtree.setProperty("message", "Hello, World!");
- session.commit(tree);
+ root.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.
+Even other `Root` 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.
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Tree.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Tree.java?rev=1329968&r1=1329967&r2=1329968&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Tree.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Tree.java Tue Apr 24 19:48:28 2012
@@ -21,25 +21,24 @@ package org.apache.jackrabbit.oak.api;
import java.util.List;
/**
- * A content tree represents a snapshot of the content in a
- * {@code ContentRepository} at the time the instance was acquired.
- * {@code ContentTree} instances may become invalid over time due to
- * garbage collection of old content, at which point an outdated
- * snapshot will start throwing {@code IllegalStateException}s to
- * indicate that the snapshot is no longer available.
+ * A tree instance represents a snapshot of the {@code ContentRepository}
+ * content tree at the time the instance was acquired. Tree instances may
+ * become invalid over time due to garbage collection of old content, at
+ * which point an outdated snapshot will start throwing
+ * {@code IllegalStateException}s to indicate that the snapshot is no
+ * longer available.
* <p>
- * {@code ContentTree} instance belongs to the client and its state
- * is only modified in response to method calls made by the client.
- * The various accessors on this class mirror these of {@code NodeState}.
- * However, since instances of this class are mutable return values may
- * change between invocations.
+ * A tree instance belongs to the client and its state is only modified
+ * in response to method calls made by the client. The various accessors
+ * on this interface mirror these of the underlying {@code NodeState}
+ * interface. However, since instances of this class are mutable return
+ * values may change between invocations.
* <p>
- * {@code ContentTree} instances are not thread-safe for write access, so
- * writing clients need to ensure that they are not accessed concurrently
- * from multiple threads. {@code ContentTree} instances are however
- * thread-safe for read access, so implementations need to ensure that all
- * reading clients see a coherent state.
- *
+ * Tree instances are not thread-safe for write access, so writing clients
+ * need to ensure that they are not accessed concurrently from multiple
+ * threads. Instances are however thread-safe for read access, so
+ * implementations need to ensure that all reading clients see a
+ * coherent state.
*/
public interface Tree {