Mailing-List: contact oak-dev-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-dev@jackrabbit.apache.org
Date: Thu, 23 Aug 2012 23:41:43 +1100 (NCT)
From: =?utf-8?Q?Michael_D=C3=BCrig_=28JIRA=29?= <jira@apache.org>
To: oak-dev@jackrabbit.apache.org
Message-ID: <1720310102.5167.1345725703367.JavaMail.jiratomcat@arcas>
Subject: [jira] [Created] (OAK-275) Introduce TreeLocation interface
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Michael D=C3=BCrig created OAK-275:
---------------------------------

             Summary: Introduce TreeLocation interface
                 Key: OAK-275
                 URL: https://issues.apache.org/jira/browse/OAK-275
             Project: Jackrabbit Oak
          Issue Type: Improvement
          Components: core
            Reporter: Michael D=C3=BCrig


In order to address the issues revolving around access control (i.e OAK-212=
, OAK-214, OAK-218, OAK-220, OAK-226,...) I'd like to introduce a new inter=
face {{TreeLocation}}:=20

{code}
/**
 * A {@code TreeLocation} denotes a location inside a tree.
 * It can either refer to a inner node (that is a {@link org.apache.jackrab=
bit.oak.api.Tree})
 * or to a leaf (that is a {@link org.apache.jackrabbit.oak.api.PropertySta=
te}).
 * {@code TreeLocation} instances provide methods for navigating trees. {@c=
ode TreeLocation}
 * instances are immutable and navigating a tree always results in new {@co=
de TreeLocation}
 * instances. Navigation never fails. Errors are deferred until the underly=
ing item itself is
 * accessed. That is, if a {@code TreeLocation} points to an item which doe=
s not exist or
 * is unavailable otherwise (i.e. due to access control restrictions) acces=
sing the tree
 * will return {@code null} at this point.
 */
public interface TreeLocation {

    /**
     * Navigate to the parent
     * @return  a {@code TreeLocation} for the parent of this location.
     */
    @Nonnull
    TreeLocation getParent();

    /**
     * Navigate to a child
     * @param name  name of the child
     * @return  a {@code TreeLocation} for a child with the given {@code na=
me}.
     */
    @Nonnull
    TreeLocation getChild(String name);

    /**
     * Get the underlying {@link org.apache.jackrabbit.oak.api.Tree} for th=
is {@code TreeLocation}.
     * @return  underlying {@code Tree} instance or {@code null} if not ava=
ilable.
     */
    @CheckForNull
    Tree getTree();

    /**
     * Get the underlying {@link org.apache.jackrabbit.oak.api.PropertyStat=
e} for this {@code TreeLocation}.
     * @return  underlying {@code PropertyState} instance or {@code null} i=
f not available.
     */
    @CheckForNull
    PropertyState getProperty();
}
{code}

Such an interface would decouple navigation from the tree itself while at t=
he same time unifying node and property access. This allows us to enforce a=
ccess control restriction on the tree itself while still being able to acce=
ss items which we are "unlinked" by access control restrictions. In additio=
n unification of node and property access will simplify the code in many pl=
aces. Finally {{TreeLocations}} might better encapsulate the resolution of =
a location in a tree to the actual tree. This is something which currently =
done in {{Node/PropertyDelegate.resolve}} but always bothered me as too ad-=
hoc.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrato=
rs: https://issues.apache.org/jira/secure/ContactAdministrators!default.jsp=
a
For more information on JIRA, see: http://www.atlassian.com/software/jira