You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by st...@apache.org on 2011/03/21 18:10:33 UTC
svn commit: r1083872 -
/jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
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;