jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject svn commit: r1083765 - /jackrabbit/sandbox/microkernel/src/main/java/org/apache/jackrabbit/mk/MicroKernel.java
Date Mon, 21 Mar 2011 12:57:14 GMT
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;
 }
-



Mime
View raw message