Mailing-List: contact oak-commits-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-commits@jackrabbit.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1329968 - in /jackrabbit/oak/trunk/oak-core: README.md
 src/main/java/org/apache/jackrabbit/oak/api/Tree.java
Date: Tue, 24 Apr 2012 19:48:28 -0000
To: oak-commits@jackrabbit.apache.org
From: jukka@apache.org
Message-Id: <20120424194828.CAA8C238890B@eris.apache.org>

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 {