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 16:18:55 UTC
svn commit: r1083827 -
/jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
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;
}