svn commit: r1363328 - /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Tree.java

[an...@apache.org]

Author: angela
Date: Thu Jul 19 13:23:39 2012
New Revision: 1363328

URL: http://svn.apache.org/viewvc?rev=1363328&view=rev
Log:
OAK-160: Make oak interfaces permission aware

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/api/Tree.java

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=1363328&r1=1363327&r2=1363328&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 Thu Jul 19 13:23:39 2012
@@ -107,10 +107,12 @@ public interface Tree {
     PropertyState getProperty(String name);
 
     /**
-     * Get the {@code Status} of a property state
-     * @param name  name of the property state
-     * @return  the status of the property state with the given {@code name}
-     *          or {@code null} in no such property state exists.
+     * Get the {@code Status} of a property state or {@code null}.
+     *
+     * @param name The name of the property state.
+     * @return The status of the property state with the given {@code name}
+     * or {@code null} in no such property state exists or if the name refers
+     * to a property that is not accessible.
      */
     @CheckForNull
     Status getPropertyStatus(String name);
@@ -125,57 +127,66 @@ public interface Tree {
     boolean hasProperty(String name);
 
     /**
-     * Determine the number of properties.
-     * @return  number of properties
+     * Determine the number of properties accessible to the current content session.
+     *
+     * @return The number of accessible properties.
      */
     long getPropertyCount();
 
     /**
-     * All property states. The returned {@code Iterable} has snapshot semantics. That
-     * is, it reflect the state of this {@code Tree} instance at the time of the
-     * call. Later changes to this instance are no visible to iterators obtained from
-     * the returned iterable.
-     * @return  An {@code Iterable} for all property states
+     * All accessible property states. The returned {@code Iterable} has snapshot
+     * semantics. That is, it reflect the state of this {@code Tree} instance at
+     * the time of the call. Later changes to this instance are no visible to
+     * iterators obtained from the returned iterable.
+     *
+     * @return An {@code Iterable} for all accessible property states.
      */
     @Nonnull
     Iterable<? extends PropertyState> getProperties();
 
     /**
-     * Get a child of this {@code Tree} instance
-     * @param name  name of the child
-     * @return  the child with the given {@code name} or {@code null} if no such child
-     * exists.
+     * Get a child of this {@code Tree} instance.
+     *
+     * @param name The name of the child to retrieve.
+     * @return The child with the given {@code name} or {@code null} if no such
+     * child exists or the child is not accessible.
      */
     @CheckForNull
     Tree getChild(String name);
 
     /**
-     * Get the {@code Status} of this tree
-     * @return  the status of this tree
+     * Get the {@code Status} of this tree instance.
+     *
+     * @return The status of this tree instance.
      */
     @Nonnull
     Status getStatus();
 
     /**
-     * Determine if a child of this {@code Tree} instance exists.
-     * @param name  name of the child
-     * @return  {@code true} if and only if a child with the given {@code name}
-     *          exists.
+     * Determine if a child of this {@code Tree} instance exists. If no child
+     * exists or an existing child isn't accessible this method returns {@code false}.
+     *
+     * @param name The name of the child
+     * @return {@code true} if and only if a child with the given {@code name}
+     * exists and is accessible for the current content session.
      */
     boolean hasChild(String name);
 
     /**
-     * Determine the number of children of this {@code Tree} instance.
-     * @return  number of children
+     * Determine the number of children of this {@code Tree} instance taking
+     * access restrictions into account.
+     *
+     * @return The number of accessible children.
      */
     long getChildrenCount();
 
     /**
-     * All children of this {@code Tree} instance. The returned {@code Iterable}
-     * has snapshot semantics. That is, it reflect the state of this {@code Tree}
-     * instance. instance at the time of the call. Later changes to this instance are no
-     * visible to iterators obtained from the returned iterable.
-     * @return  An {@code Iterable} for all children
+     * All accessible children of this {@code Tree} instance. The returned
+     * {@code Iterable} has snapshot semantics. That is, it reflect the state of
+     * this {@code Tree} instance at the time of the call. Later changes to this
+     * instance are not visible to iterators obtained from the returned iterable.
+     *
+     * @return An {@code Iterable} for all accessible children
      */
     @Nonnull
     Iterable<Tree> getChildren();