From f05caccdd9d426c7c624ecfcaddf2c7a908283ac Mon Sep 17 00:00:00 2001
From: Jukka Zitting <jukka@apache.org>
Date: Thu, 22 Nov 2012 17:52:58 +0200
Subject: [PATCH] OAK-468: Identifier- or hash-based access in the MicroKernel

Updated MicroKernel contract
---
 .../org/apache/jackrabbit/mk/api/MicroKernel.java  |   21 ++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/oak-mk-api/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java b/oak-mk-api/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java
index 7802551..adae126 100644
--- a/oak-mk-api/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java
+++ b/oak-mk-api/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java
@@ -372,10 +372,27 @@ public interface MicroKernel {
      *     <p>Returning the {@code :hash} property is optional. Some implementations
      *     might only return it on specific nodes or might not support it at all.
      *     If however a {@code :hash} property is returned it has to obey the contract
-     *     described above.</p></li>
+     *     described above.</p>
+     *     <p>Implementations that keep track of the child hash along with
+     *     the child node name can return the {@code :hash} value also as
+     *     a property of the child node objects, even if they'd otherwise
+     *     be empty, for example due to a depth limit. If such child hashes
+     *     are returned, the client can use them as an alternative to child
+     *     paths when accessing those nodes.<p>
+     *     </li>
+     *     <li>
+     *     <li>{@code :id} provides an implementation-specific identifier
+     *     of a node. Identifiers are like content hashes as described above,
+     *     except for the fact that two different identifiers may refer to
+     *     identical subtrees. Also {@code :id} values may be returned for
+     *     child nodes, in which case the client can use them for accessing
+     *     those nodes.
+     *     </li>
      * </ul>
      *
-     * @param path          path denoting root of node tree to be retrieved
+     * @param path          path denoting root of node tree to be retrieved,
+     *                      or alternatively a previously returned
+     *                      {@code :hash} or {@code :id} value
      * @param revisionId    revision id, if {@code null} the current head revision is assumed
      * @param depth         maximum depth of returned tree
      * @param offset        start position in the iteration order of child nodes (0 to start at the
-- 
1.7.10.msysgit.1