jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject svn commit: r1083872 - /jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
Date Mon, 21 Mar 2011 17:10:33 GMT
Author: stefan
Date: Mon Mar 21 17:10:33 2011
New Revision: 1083872

URL: http://svn.apache.org/viewvc?rev=1083872&view=rev
Log:
drafting MicroKernel api (WIP)

Modified:
    jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java

Modified: jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
URL: http://svn.apache.org/viewvc/jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java?rev=1083872&r1=1083871&r2=1083872&view=diff
==============================================================================
--- jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
(original)
+++ jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
Mon Mar 21 17:10:33 2011
@@ -29,7 +29,7 @@ import java.io.InputStream;
  * <li>predefined timeout (e.g. 50ms) for reading methods</li>
  * <li>portable to C</li>
  * <li>efficient support for large number of child nodes</li>
- * <li>integrated API for storing/retrieving large binaries (correspond</li>
+ * <li>integrated API for storing/retrieving large binaries (similar to DataStore API)</li>
  * </ul>
  *
  * The MicroKernel <b>Data Model</b>:
@@ -103,9 +103,9 @@ public interface MicroKernel {
      * in time.
      * <p/>
      * Format:
-     * <xmp>
+     * <pre>
      * [ { "id" : "<revisionId>", "ts" : <revisionTimestamp> }, ... ]
-     * </xmp>
+     * </pre>
      *
      * @todo provide a per revision size hint? (TBD)
      *
@@ -123,9 +123,9 @@ public interface MicroKernel {
      * and ending with <code>toRevisionId</code>.
      * <p/>
      * Format:
-     * <xmp>
+     * <pre>
      * [ { "id" : "<revisionId>", "ts" : <revisionTimestamp>, "changes" : "<JSON
diff>" }, ... ]
-     * </xmp>
+     * </pre>
      *
      * @param fromRevisionId first revision to be returned in journal
      * @param toRevisionId last revision to be returned in journal
@@ -141,7 +141,7 @@ public interface MicroKernel {
     /**
      * Determines whether the specified node exists.
      *
-     * @param idOrPath identifier or path
+     * @param idOrPath identifier or path denoting node
      * @param revisionId revision
      * @return <code>true</code> if the specified node exists, otherwise <code>false</code>
      * @throws MicroKernelException if an error occurs
@@ -149,14 +149,67 @@ public interface MicroKernel {
     boolean nodeExists(String idOrPath, String revisionId) throws MicroKernelException;
 
     /**
+     * Returns the node tree rooted at the specified parent node. The depth of
+     * the returned tree is governed by <code>depth</code> parameter:
+     * <p/>
+     * <table>
+     * <tr><td>depth = 0</td><td>just properties, including <code>:childNodesCount</code></td></tr>
+     * <tr><td>depth = 1</td><td>properties, child nodes and their
properties (including <code>:childNodesCount</code>)</td></tr>
+     * <tr><td>depth = 2</td><td>[and so on...]</td></tr>
+     * </table>
+     * <p/>
+     * Format:
+     * <pre>
+     * {
+     *     ":name" : "parent",
+     *     "someprop" : "someval",
+     *     ":childNodesCount" : 2,
+     *     ":childNodes" : [
+     *         { ":name" : "child1", "prop1" : "foo", ":childNodesCount" : 1, ":childNodes"
: [
+     *             { ":name" : "grandchild", "propA" : "blahblah", ":childNodesCount" : 0
}
+     *         ]},
+     *         { ":name" : "child2", "prop1" : "bar", ":childNodesCount" : 0}
+       *   ]
+     * }
+     * </pre>
+     *
+     * Some remarks:
+     * <ul>
+     * <li><code>:childNodesCount > 0</code> indicates that the node
does have child nodes,
+     * although they might not be included in the tree.</li>
+     * <li><code>:childNodesCount > lengthOf(:childNodes)</code> indicates
that the
+     * node does have more child nodes than those included in the tree. Large number
+     * of child nodes can be retrieved in chunks using the {@link #getChildNodes} method</li>
+     * </ul>
+     *
+     * TBD: Simpler and more intuitive format, albeit not strictly JSON compliant
+     * (the collection of name/value pairs denoting child nodes is assumed to be ordered):
+     * <pre>
+     * {
+     *     ":name" : "parent",
+     *     "someprop" : "someval",
+     *     ":childNodesCount" : 2,
+     *     "child1" : {
+     *         "prop1" : "foo",
+     *         ":childNodesCount" : 1,
+     *         "grandchild" : {
+     *             "propA" : "blahblah",
+     *             ":childNodesCount" : 0
+     *         }
+     *     }
+     *     "child2" : {
+     *         "prop1" : "bar",
+     *         ":childNodesCount" : 0
+     *     }
+     * }
+     * </pre>
      *
-     * @param idOrPath identifier or path
-     * @param depth
+     * @param idOrPath identifier or path denoting root of node tree to be retrieved
+     * @param depth maximum depth of returned tree
      * @param revisionId revision
-     * @return
+     * @return node tree in JSON format
      * @throws MicroKernelException if an error occurs
      */
-    /* @todo how should flat hierarchies be handled/represented? use special child node entry/placeholder
([...]) if child node list is truncated?*/
     String /* jsonTree */ getNodes(String idOrPath, int depth, String revisionId) throws
MicroKernelException;
 
     // specialized methods for reading flat hierarchies
@@ -174,13 +227,15 @@ public interface MicroKernel {
     String /* array of jsonTrees */ getChildNodes(String idOrPath, long offset, long count,
int depth, String revisionId) throws MicroKernelException;
 
     /**
+     * Returns the number of child nodes of the specified parent node.
+     *
+     * @todo could be represented as special property (":childNodeCount") -> no need for
specific api method (TBD)
      *
      * @param idOrPath identifier or path denoting parent node
      * @param revisionId revision
-     * @return
+     * @return number of child nodes
      * @throws MicroKernelException if an error occurs
      */
-    // maybe represented as special property (":childNodeCount") -> no need for specific
api method?
     long /* count */ getChildNodeCount(String idOrPath, String revisionId)
             throws MicroKernelException;
 



Mime
View raw message