Mailing-List: contact commits-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@jackrabbit.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1083827 -
 /jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
Date: Mon, 21 Mar 2011 15:18:55 -0000
To: commits@jackrabbit.apache.org
From: stefan@apache.org
Message-Id: <20110321151855.F378B23888EA@eris.apache.org>

Author: stefan
Date: Mon Mar 21 15:18:55 2011
New Revision: 1083827

URL: http://svn.apache.org/viewvc?rev=1083827&view=rev
Log:
drafting a 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=1083827&r1=1083826&r2=1083827&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 15:18:55 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 DataStore for storing/retrieving large binaries</li>
+ * <li>integrated API for storing/retrieving large binaries (correspond</li>
  * </ul>
  *
  * The MicroKernel <b>Data Model</b>:
@@ -127,8 +127,6 @@ public interface MicroKernel {
      * [ { "id" : "<revisionId>", "ts" : <revisionTimestamp>, "changes" : "<JSON diff>" }, ... ]
      * </xmp>
      *
-     * @todo format of embedded JSON diff? encoding? (TBD)
-     *
      * @param fromRevisionId first revision to be returned in journal
      * @param toRevisionId last revision to be returned in journal
      * @return a chronological list of revisions in JSON format
@@ -141,57 +139,60 @@ public interface MicroKernel {
     //-------------------------------------------------------------< READ ops >
 
     /**
+     * Determines whether the specified node exists.
      *
-     * @param idOrPath
-     * @param revisionId
-     * @return
+     * @param idOrPath identifier or path
+     * @param revisionId revision
+     * @return <code>true</code> if the specified node exists, otherwise <code>false</code>
      * @throws MicroKernelException if an error occurs
      */
     boolean nodeExists(String idOrPath, String revisionId) throws MicroKernelException;
 
     /**
      *
-     * @param idOrPath
+     * @param idOrPath identifier or path
      * @param depth
-     * @param revisionId
+     * @param revisionId revision
      * @return
      * @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
+
     /**
      *
-     * @param idOrPath
+     * @param idOrPath identifier or path denoting parent node
      * @param offset
      * @param count
      * @param depth
-     * @param revisionId
+     * @param revisionId revision
      * @return
      * @throws MicroKernelException if an error occurs
      */
-    // specialized methods for reading flat hierarchies
     String /* array of jsonTrees */ getChildNodes(String idOrPath, long offset, long count, int depth, String revisionId) throws MicroKernelException;
 
     /**
      *
-     * @param idOrPath
-     * @param revisionId
+     * @param idOrPath identifier or path denoting parent node
+     * @param revisionId revision
      * @return
      * @throws MicroKernelException if an error occurs
      */
     // maybe represented as special property (":childNodeCount") -> no need for specific api method?
-    long getChildNodeCount(String idOrPath, String revisionId)
+    long /* count */ getChildNodeCount(String idOrPath, String revisionId)
             throws MicroKernelException;
 
 
     //------------------------------------------------------------< WRITE ops >
 
     /**
+     * Applies the specified changes on the specified target node.
      *
-     * @param idOrPath
-     * @param jsonDiff
-     * @return
+     * @param idOrPath identifier or path denoting target node
+     * @param jsonDiff changes to be applied in JSON diff format.
+     * @return id of newly created revision
      * @throws MicroKernelException if an error occurs
      */
     String /* revisionId */ commit(String idOrPath, String jsonDiff)
@@ -201,31 +202,45 @@ public interface MicroKernel {
     //--------------------------------------------------< BLOB READ/WRITE ops >
 
     /**
+     * Returns the length of the specified blob.
      *
-     * @param dsId
-     * @return
+     * @todo encode length in id?
+     *
+     * @param blobId blob identifier
+     * @return length of the specified blob
      * @throws MicroKernelException if an error occurs
      */
-    // @todo encode length in id? => yes
-    long getLength(String dsId) throws MicroKernelException;
+    long getLength(String blobId) throws MicroKernelException;
 
     /**
+     * Reads up to <code>length</code> bytes of data from the specified blob into
+     * the given array of bytes.  An attempt is made to read as many as
+     * <code>length</code> bytes, but a smaller number may be read.
+     * The number of bytes actually read is returned as an integer.
      *
-     * @param dsId
-     * @param buf
-     * @param off
-     * @param size
-     * @return
+     * @param blobId blob identifier
+     * @param buf the buffer into which the data is read.
+     * @param off the start offset in array <code>buff</code>
+     *            at which the data is written.
+     * @param length the maximum number of bytes to read
+     * @return the total number of bytes read into the buffer, or
+     *         <code>-1</code> if there is no more data because the end of
+     *         the blob content has been reached.
      * @throws MicroKernelException if an error occurs
      */
-    int /* count */ read(String dsId, byte[] buf, int off, int size)
+    int /* count */ read(String blobId, byte[] buf, int off, int length)
             throws MicroKernelException;
 
     /**
-     *
-     * @param in
-     * @return
+     * Stores the content of the given stream and returns an associated
+     * identifier for later retrieval.
+     * <p/>
+     * If identical stream content has been stored previously, then the existing
+     * identifier will be returned instead of storing a redundant copy.
+
+     * @param in InputStream providing the blob content
+     * @return blob identifier associated with the given content
      * @throws MicroKernelException if an error occurs
      */
-    String /* dsId */ write(InputStream in) throws MicroKernelException;
+    String /* blobId */ write(InputStream in) throws MicroKernelException;
 }