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 13:57:14 UTC
svn commit: r1083765 -
/jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
Author: stefan
Date: Mon Mar 21 12:57:14 2011
New Revision: 1083765
URL: http://svn.apache.org/viewvc?rev=1083765&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=1083765&r1=1083764&r2=1083765&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 12:57:14 2011
@@ -66,6 +66,9 @@ import java.io.InputStream;
* (e.g. <code>":id" : null</code>), a system-generated unique identifier will be
* assigned and exposed through the same <code>:id</code> property;
* the MicroKernel maintains an id<->path index</li>
+ * <li>should the API provide methods for looking up id/path mappings
+ * (<code>getId/getPath</code>) or should every node with an assigned
+ * id expose a <code>:path</code> property (in addition to <code>:id</code>)?</li>
* <li><code>jcr:uuid</code> is decorated by the SPI on top of MicroKernel;
* <code>jcr:uuid</code> is equivalent to the MicroKernel node identifier (<code>:id</code>)</li>
* <li>should the MicroKernel provide built-in support for shareable nodes?
@@ -86,39 +89,143 @@ import java.io.InputStream;
*/
public interface MicroKernel {
+ //---------------------------------------------------------< REVISION ops >
+
+ /**
+ * Return the id of the current head revision.
+ *
+ * @return id of head revision
+ */
+ String getHeadRevision();
+
+ /**
+ * Returns a chronological list of all revisions since a specific point
+ * in time.
+ * <p/>
+ * Format:
+ * <xmp>
+ * [ { "id" : "<revisionId>", "ts" : <revisionTimestamp> }, ... ]
+ * </xmp>
+ *
+ * @todo provide a per revision size hint? (TBD)
+ *
+ * @param since timestamp (ms) of earliest revision to be returned
+ * @param maxEntries maximum #entries to be returned;
+ * if < 0, no limit will be applied.
+ * @return a chronological list of revisions in JSON format.
+ * @throws MicroKernelException if an error occurs
+ */
+ String /* jsonArray */ getRevisions(long since, int maxEntries)
+ throws MicroKernelException;
+
/**
- * REVISION ops
+ * Returns a revision journal, starting with <code>fromRevisionId</code>
+ * and ending with <code>toRevisionId</code>.
+ * <p/>
+ * Format:
+ * <xmp>
+ * [ { "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
+ * @throws MicroKernelException if an error occurs
*/
- String /* revisionId */ getHeadRevision();
- // revision entry: revisionId, timestamp, size?
- // todo: is the idOrPath parameter required if we're using a DAG model (as opposed to delta-based)
- String /* jsonObject */ getRevisions(long since, int maxEntries) throws MicroKernelException;
- String /* array of revisions (id, ts, jsonDiff) */ getJournal(String revisionId1, String revisionId2) throws MicroKernelException;
+ String /* jsonArray */ getJournal(String fromRevisionId, String toRevisionId)
+ throws MicroKernelException;
+
+
+ //-------------------------------------------------------------< READ ops >
/**
- * READ ops
+ *
+ * @param idOrPath
+ * @param revisionId
+ * @return
+ * @throws MicroKernelException if an error occurs
*/
boolean nodeExists(String idOrPath, String revisionId) throws MicroKernelException;
+ /**
+ *
+ * @param idOrPath
+ * @param depth
+ * @param revisionId
+ * @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;
+ /**
+ *
+ * @param idOrPath
+ * @param offset
+ * @param count
+ * @param depth
+ * @param revisionId
+ * @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
+ * @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) throws MicroKernelException;
+ long getChildNodeCount(String idOrPath, String revisionId)
+ throws MicroKernelException;
+
+
+ //------------------------------------------------------------< WRITE ops >
/**
- * WRITE ops
+ *
+ * @param idOrPath
+ * @param jsonDiff
+ * @return
+ * @throws MicroKernelException if an error occurs
*/
- String /* revisionId */ commit(String idOrPath, String jsonDiff) throws MicroKernelException;
+ String /* revisionId */ commit(String idOrPath, String jsonDiff)
+ throws MicroKernelException;
+
+
+ //--------------------------------------------------< BLOB READ/WRITE ops >
/**
- * DataStore READ/WRITE ops
+ *
+ * @param dsId
+ * @return
+ * @throws MicroKernelException if an error occurs
*/
// @todo encode length in id? => yes
long getLength(String dsId) throws MicroKernelException;
- int /* count */ read(String dsId, byte[] buf, int off, int size) throws MicroKernelException;
+
+ /**
+ *
+ * @param dsId
+ * @param buf
+ * @param off
+ * @param size
+ * @return
+ * @throws MicroKernelException if an error occurs
+ */
+ int /* count */ read(String dsId, byte[] buf, int off, int size)
+ throws MicroKernelException;
+
+ /**
+ *
+ * @param in
+ * @return
+ * @throws MicroKernelException if an error occurs
+ */
String /* dsId */ write(InputStream in) throws MicroKernelException;
}
-