/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.jackrabbit.oak.api;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;

/**
 * The root of a {@link Tree}.
 */
public interface Root {

    /**
     * Move the child located at {@code sourcePath} to a child at {@code destPath}.
     * Both paths must resolve to a child located beneath this root.<br>
     *
     * This method does nothing and returns {@code false} if
     * <ul>
     *     <li>the tree at {@code sourcePath} does not exist or is not accessible,</li>
     *     <li>the parent of the tree at {@code destinationPath} does not exist or is not accessible,</li>
     *     <li>a tree already exists at {@code destinationPath}.</li>
     * </ul>
     * If a tree at {@code destinationPath} exists but is not accessible to the
     * editing content session this method succeeds but a subsequent
     * {@link #commit(ConflictHandler)} will detect the violation and fail.
     *
     * @param sourcePath The source path relative to this root
     * @param destPath The destination path relative to this root
     * @return {@code true} on success, {@code false} otherwise.
     */
    boolean move(String sourcePath, String destPath);

    /**
     * Copy the child located at {@code sourcePath} to a child at {@code destPath}.
     * Both paths must resolve to a child located in this root.<br>
     *
     * This method does nothing an returns {@code false} if
     * <ul>
     *     <li>The tree at {@code sourcePath} does exist or is not accessible,</li>
     *     <li>the parent of the tree at {@code destinationPath} does not exist or is not accessible,</li>
     *     <li>a tree already exists at {@code destinationPath}.</li>
     * </ul>
     * If a tree at {@code destinationPath} exists but is not accessible to the
     * editing content session this method succeeds but a subsequent
     * {@link #commit(ConflictHandler)} will detect the violation and fail.
     *
     * @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 Tree} at the given {@code path}. The path must resolve to
     * a tree in this root.
     *
     * @param path  path to the tree
     * @return tree at the given path or {@code null} if no such tree exists or
     * if the tree at {@code path} is not accessible.
     */
    @CheckForNull
    Tree getTree(String path);

    /**
     * Get a tree location for a given {@code path}
     * @param path  path to the location
     * @return  the tree location for {@code path}
     */
    @Nonnull
    TreeLocation getLocation(String path);

    /**
     * Rebase this root instance to the latest revision. After a call to this method,
     * all trees obtained through {@link #getTree(String)} become invalid and fresh
     * instances must be obtained.
     *
     * @param conflictHandler A {@link ConflictHandler} for resolving conflicts.
     */
    void rebase(ConflictHandler conflictHandler);

    /**
     * Reverts all changes made to this root and refreshed to the latest trunk.
     * After a call to this method, all trees obtained through {@link #getTree(String)}
     * become invalid and fresh instances must be obtained.
     */
    void refresh();

    /**
     * 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)} become invalid and fresh
     * instances must be obtained.
     *
     * @param conflictHandler  {@link ConflictHandler} for resolving conflicts.
     * @throws CommitFailedException
     */
    void commit(ConflictHandler conflictHandler) throws CommitFailedException;

    /**
     * Determine whether there are changes on this tree
     * @return  {@code true} iff this tree was modified
     */
    boolean hasPendingChanges();

    /**
     * Return a {@link ChangeExtractor} for this {@code Root}.
     * @return a {@code ChangeExtractor}.
     */
    @Nonnull
    ChangeExtractor getChangeExtractor();
}

@@ -1084,32 +1084,48 @@
 Both paths must 
+be absolute and 
 resolve to a chi
@@ -1143,24 +1143,31 @@
 beneath this
+%0A     *
  root.%3Cbr%3E%0A 
@@ -1795,38 +1795,16 @@
 rce path
- relative to this root
 %0A     * 
@@ -1839,38 +1839,16 @@
 ion path
- relative to this root
 %0A     * 
@@ -2079,24 +2079,40 @@
  paths must 
+be absolute and 
 resolve to a
@@ -2765,38 +2765,16 @@
 rce path
- relative to this root
 %0A     * 
@@ -2809,30 +2809,8 @@
 path
- relative to this root
 %0A   
@@ -2985,24 +2985,33 @@
 t the given 
+absolute 
 %7B@code path%7D
@@ -3020,16 +3020,23 @@
 The path
+%0A     *
  must re
@@ -3043,23 +3043,16 @@
 solve to
-%0A     *
  a tree 
@@ -3083,32 +3083,40 @@
   * @param path 
+absolute
  path to the tre
@@ -3203,16 +3203,24 @@
 r%0A     *
+        
  if the 
@@ -3364,16 +3364,25 @@
 a given 
+absolute 
 %7B@code p
@@ -3382,24 +3382,31 @@
 @code path%7D%0A
+     *%0A
      * @para
@@ -3412,16 +3412,24 @@
 am path 
+absolute
  path to
@@ -3457,17 +3457,16 @@
 @return 
- 
 the tree

Clarify paths in Root