Author: mduerig Date: Tue Apr 24 12:52:14 2012 New Revision: 1329685 URL: http://svn.apache.org/viewvc?rev=1329685&view=rev Log: OAK-18: Define Oak API - update javadoc
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Root.java jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentRepository.java jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentSession.java jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelRoot.java jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelTree.java jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/NodeStore.java jackrabbit/oak/trunk/oak-core/src/test/java/org/apache/jackrabbit/oak/kernel/KernelRootTest.java Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java (original) +++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/ContentSession.java Tue Apr 24 12:52:14 2012 @@ -28,9 +28,6 @@ import java.io.Closeable; * - validate information being written back to the persistent layer. this includes * permission evaluation, node type and name constraints etc. * - * - update the revision ID a given session is operating on when certain actions - * take place (save, refresh, TBD) - * * - Provide access to authentication and authorization related information * * - The implementation of this and all related interfaces are intended to only @@ -66,11 +63,10 @@ public interface ContentSession extends String getWorkspaceName(); /** - * TODO update javadoc - * Branch the current root. Use {@link #commit(Root)} to atomically apply the - * changes made in this branch to the underlying Microkernel. + * The current root as seen by this content session. Use {@link Root#commit()} to + * atomically apply the changes made in that subtree the underlying Microkernel. * - * @return branch of the current root. + * @return the current root */ Root getCurrentRoot(); Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Root.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Root.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Root.java (original) +++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Root.java Tue Apr 24 12:52:14 2012 @@ -19,7 +19,7 @@ package org.apache.jackrabbit.oak.api; /** - * An branch for modifying existing and creating new node states. + * The root of a {@link Tree}. */ public interface Root { @@ -28,10 +28,10 @@ public interface Root { * at {@code destPath}. Do nothing if either the source * does not exist, the parent of the destination does not exist * or the destination exists already. Both paths must resolve - * to a child located in this branch. + * to a child located beneath this root. * - * @param sourcePath source path relative to this branch - * @param destPath destination path relative to this branch + * @param sourcePath source path relative to this root + * @param destPath destination path relative to this root * @return {@code true} on success, {@code false} otherwise. */ boolean move(String sourcePath, String destPath); @@ -41,17 +41,17 @@ public interface Root { * at {@code destPath}. Do nothing if either the source * does not exist, the parent of the destination does not exist * or the destination exists already. Both paths must resolve - * to a child located in this branch. + * to a child located in this root. * - * @param sourcePath source path relative to this branch - * @param destPath destination path relative to this branch + * @param sourcePath source path relative to this root + * @param destPath destination path relative to this root * @return {@code true} on success, {@code false} otherwise. */ boolean copy(String sourcePath, String destPath); /** * Retrieve the {@code ContentTree} at the given {@code path}. - * The path must resolve to a content tree in this branch. + * The path must resolve to a content tree in this root. * * @param path path to the content tree * @return content tree at the given path or {@code null} if no @@ -60,13 +60,17 @@ public interface Root { Tree getTree(String path); /** - * Refresh this content session to the latest revision of the underlying Microkernel. + * Refresh this root to the latest revision. After a call to this method, + * all trees obtained through {@link #getTree(String)} are invalid and fresh + * instances must be obtained. */ void refresh(); /** - * Atomically apply all changes in the passed {@code branch} to the underlying - * Microkernel. + * Atomically apply all changes made to the tree beneath this root to the + * underlying store and refreshes this root. After a call to this method, + * all trees obtained through {@link #getTree(String)} are invalid and fresh + * instances must be obtained. * * @throws CommitFailedException TODO: add description and clarify how JCR exception can be generated from this generic exception */ Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentRepository.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentRepository.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentRepository.java (original) +++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentRepository.java Tue Apr 24 12:52:14 2012 @@ -89,7 +89,6 @@ public class KernelContentRepository imp throw new LoginException("login failed"); } - // TODO set revision!? NodeState wspRoot = nodeStore.getRoot().getChildNode(workspaceName); if (wspRoot == null) { throw new NoSuchWorkspaceException(workspaceName); Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentSession.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentSession.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentSession.java (original) +++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/core/KernelContentSession.java Tue Apr 24 12:52:14 2012 @@ -31,8 +31,7 @@ import javax.jcr.SimpleCredentials; import java.io.IOException; /** - * {@link MicroKernel}-based implementation of - * the {@link ContentSession} interface. + * {@link MicroKernel}-based implementation of the {@link ContentSession} interface. */ class KernelContentSession implements ContentSession { @@ -46,9 +45,8 @@ class KernelContentSession implements Co private final QueryEngine queryEngine; private final CoreValueFactory valueFactory; - public KernelContentSession( - SimpleCredentials credentials, String workspaceName, NodeStore store, - QueryEngine queryEngine, CoreValueFactory valueFactory) { + public KernelContentSession(SimpleCredentials credentials, String workspaceName, + NodeStore store, QueryEngine queryEngine, CoreValueFactory valueFactory) { this.credentials = credentials; this.workspaceName = workspaceName; Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelRoot.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelRoot.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelRoot.java (original) +++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelRoot.java Tue Apr 24 12:52:14 2012 @@ -34,10 +34,8 @@ import static org.apache.jackrabbit.mk.u import static org.apache.jackrabbit.mk.util.PathUtils.getParentPath; /** - * TODO update javadoc - * This {@code Branch} implementation accumulates all changes into a json diff - * and applies them to the microkernel on - * {@link NodeStore#merge(org.apache.jackrabbit.oak.api.Root)} + * This {@code Root} implementation accumulates all changes into a json diff + * and applies them to the microkernel on {@link #commit()} * * TODO: review/rewrite when OAK-45 is resolved * When the MicroKernel has support for branching and merging private working copies, @@ -52,13 +50,13 @@ public class KernelRoot implements Root private final NodeStore store; private final String workspaceName; - /** Base node state of this private branch */ + /** Base node state of this tree */ private KernelNodeState base; - /** Root state of this branch */ + /** Root state of tree */ private KernelTree root; - /** Log of changes to this branch */ + /** Log of changes to tree */ private ChangeLog changeLog = new ChangeLog(); @@ -108,7 +106,6 @@ public class KernelRoot implements Root @Override public void commit() throws CommitFailedException { - // TODO implicit refresh, doc in contract MicroKernel kernel = ((KernelNodeStore) store).kernel; // FIXME don't cast to implementation try { mergeInto(kernel, base); @@ -122,7 +119,7 @@ public class KernelRoot implements Root //------------------------------------------------------------< internal >--- /** - * Return the base node state of this private branch + * Return the base node state of this tree * @return base node state */ NodeState getBaseNodeState() { @@ -130,8 +127,7 @@ public class KernelRoot implements Root } /** - * Atomically merges the changes from this branch back into the - * {@code target}. + * Atomically merges the changes from this tree back into the {@code target}. * * @param microkernel Microkernel instance for applying the changes * @param target target of the merge operation @@ -202,7 +198,7 @@ public class KernelRoot implements Root /** * This {@code Listener} implementation records all changes to - * a associated branch as JSOP. + * a associated tree as JSOP. */ private static class ChangeLog implements Listener { private final StringBuilder jsop = new StringBuilder(); Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelTree.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelTree.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelTree.java (original) +++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/KernelTree.java Tue Apr 24 12:52:14 2012 @@ -135,7 +135,7 @@ public class KernelTree implements Tree } /** - * Create a new instance representing the root of a branch. + * Create a new instance representing the root of a tree * @param persistentState underlying persistent state * @param listener change listener */ Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/NodeStore.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/NodeStore.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/NodeStore.java (original) +++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/kernel/NodeStore.java Tue Apr 24 12:52:14 2012 @@ -20,10 +20,6 @@ package org.apache.jackrabbit.oak.kernel * TODO update javadoc * Storage abstraction for content trees. At any given point in time * the stored content tree is rooted at a single immutable node state. - * Changes in the tree are constructed by branching off a private copy - * using the {@link #branch(NodeState)} method which can be modified - * and merged back using the {@link #merge(org.apache.jackrabbit.oak.api.Root)} - * method. * <p> * This is a low-level interface that doesn't cover functionality like * merging concurrent changes or rejecting new tree states based on some Modified: jackrabbit/oak/trunk/oak-core/src/test/java/org/apache/jackrabbit/oak/kernel/KernelRootTest.java URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/test/java/org/apache/jackrabbit/oak/kernel/KernelRootTest.java?rev=1329685&r1=1329684&r2=1329685&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-core/src/test/java/org/apache/jackrabbit/oak/kernel/KernelRootTest.java (original) +++ jackrabbit/oak/trunk/oak-core/src/test/java/org/apache/jackrabbit/oak/kernel/KernelRootTest.java Tue Apr 24 12:52:14 2012 @@ -60,6 +60,7 @@ public class KernelRootTest { public void getChild() { KernelRoot branch = new KernelRoot(store, "test"); Tree root = branch.getTree("/"); + Tree child = root.getChild("any"); assertNull(child);