org.apache.jackrabbit.mk.api
Interface MicroKernel

All Known Implementing Classes:

MicroKernelImpl

public interface MicroKernel

The MicroKernel design goals/principles:

• manage huge trees of nodes and properties efficiently
• MVCC-based concurrency control (writers don't interfere with readers, snapshot isolation)
• GIT/SVN-inspired DAG-based versioning model
• highly scalable concurrent read & write operations
• stateless API
• portable to C
• efficient support for large number of child nodes
• integrated API for efficiently storing/retrieving large binaries
• human-readable data serialization (JSON)

The MicroKernel Data Model:

• simple JSON-inspired data model: just nodes and properties
• a node consists of an unordered set of name -> item mappings. each property and child node is uniquely named and a single name can only refer to a property or a child node, not both at the same time.
• properties are represented as name/value pairs
• supported property types: string, number, boolean, array
• a property value is stored and used as an opaque, unparsed character sequence

Method Summary

String	commit(String path, String jsonDiff, String revisionId, String message) Applies the specified changes on the specified target node.
String	diff(String fromRevisionId, String toRevisionId, String filter) Returns the JSON diff representation of the changes between the specified revisions.
void	dispose() Dispose this instance.
long	getChildNodeCount(String path, String revisionId) Returns the number of child nodes of the specified node.
String	getHeadRevision() Return the id of the current head revision.
String	getJournal(String fromRevisionId, String toRevisionId, String filter) Returns a revision journal, starting with fromRevisionId and ending with toRevisionId.
long	getLength(String blobId) Returns the length of the specified blob.
String	getNodes(String path, String revisionId) Returns the node tree rooted at the specified parent node with depth 1.
String	getNodes(String path, String revisionId, int depth, long offset, int count, String filter) Returns the node tree rooted at the specified parent node with the specified depth, maximum child node count and offset.
String	getRevisions(long since, int maxEntries) Returns a chronological list of all revisions since a specific point in time.
boolean	nodeExists(String path, String revisionId) Determines whether the specified node exists.
int	read(String blobId, long pos, byte[] buff, int off, int length) Reads up to length bytes of data from the specified blob into the given array of bytes.
String	waitForCommit(String oldHeadRevision, long maxWaitMillis) Wait for a commit to occur that is newer than the given revision number.
String	write(InputStream in) Stores the content of the given stream and returns an associated identifier for later retrieval.

Method Detail

dispose

void dispose()

Dispose this instance.

getHeadRevision

String getHeadRevision()
                       throws MicroKernelException

Return the id of the current head revision.

Returns:

id of head revision

Throws:

MicroKernelException - if an error occurs

getRevisions

String getRevisions(long since,
                    int maxEntries)
                    throws MicroKernelException

Returns a chronological list of all revisions since a specific point in time.

Format:

 [ { "id" : "", "ts" :  }, ... ]
 

Parameters:

since - timestamp (ms) of earliest revision to be returned

maxEntries - maximum #entries to be returned; if < 0, no limit will be applied.

Returns:

a chronological list of revisions in JSON format.

Throws:

MicroKernelException - if an error occurs

waitForCommit

String waitForCommit(String oldHeadRevision,
                     long maxWaitMillis)
                     throws MicroKernelException,
                            InterruptedException

Wait for a commit to occur that is newer than the given revision number.

This method is useful efficient polling. The method will return the current head revision if it is newer than the given old revision number, or wait until the given number of milliseconds passed or a new head revision is available.

Parameters:

maxWaitMillis - the maximum number of milliseconds to wait (0 if the method should not wait).

Returns:

the current head revision

Throws:

MicroKernelException - if an error occurs

InterruptedException - if the thread was interrupted

getJournal

String getJournal(String fromRevisionId,
                  String toRevisionId,
                  String filter)
                  throws MicroKernelException

Returns a revision journal, starting with fromRevisionId and ending with toRevisionId.

Format:

 [ { "id" : "<revisionId>", "ts" : "<revisionTimestamp>", "msg" : "<commitMessage>", "changes" : "<JSON diff>" }, ... ]
 

Parameters:

fromRevisionId - first revision to be returned in journal

toRevisionId - last revision to be returned in journal, if null the current head revision is assumed

filter - (optional) filter criteria (e.g. path, property names, etc); TODO specify format and semantics

Returns:

a chronological list of revisions in JSON format

Throws:

MicroKernelException - if an error occurs

diff

String diff(String fromRevisionId,
            String toRevisionId,
            String filter)
            throws MicroKernelException

Returns the JSON diff representation of the changes between the specified revisions. The changes will be consolidated if the specified range covers intermediary revisions. The revisions need not be in a specified chronological order.

Format:

 [ { "id" : "<revisionId>", "ts" : "<revisionTimestamp>", "msg" : "<commitMessage>", "changes" : "<JSON diff>" }, ... ]
 

Parameters:

fromRevisionId - a revision

toRevisionId - another revision, if null the current head revision is assumed

filter - (optional) filter criteria (e.g. path, property names, etc); TODO specify format and semantics

Returns:

JSON diff representation of the changes

Throws:

MicroKernelException - if an error occurs

nodeExists

boolean nodeExists(String path,
                   String revisionId)
                   throws MicroKernelException

Determines whether the specified node exists.

Parameters:

path - path denoting node

revisionId - revision, if null the current head revision is assumed

Returns:

true if the specified node exists, otherwise false

Throws:

MicroKernelException - if an error occurs

getChildNodeCount

long getChildNodeCount(String path,
                       String revisionId)
                       throws MicroKernelException

Returns the number of child nodes of the specified node.

This is a convenience method since this information could gathered by calling getNodes(path, revisionId, 0, 0, 0) and evaluating the :childNodeCount property.

Parameters:

path - path denoting node

revisionId - revision, if null the current head revision is assumed

Returns:

the number of child nodes

Throws:

MicroKernelException - if an error occurs

getNodes

String getNodes(String path,
                String revisionId)
                throws MicroKernelException

Returns the node tree rooted at the specified parent node with depth 1. Depth 1 means all properties of the node are returned, including the direct child nodes and their properties (including :childNodeCount). Example:

 {
     "someprop": "someval",
     ":childNodeCount": 2,
     "child1" : {
          "prop1": "foo",
          ":childNodeCount": 2
      },
      "child2": {
          "prop1": "bar"
          ":childNodeCount": 0
      }
 }
 

Remarks:

• If the property :childNodeCount equals 0, then the node does not have any child nodes.
• If the value of :childNodeCount is larger than the number of returned child nodes, then the node has more child nodes than those included in the tree. Large number of child nodes can be retrieved in chunks using getNodes(String, String, int, long, int, String)

This method is a convenience method for getNodes(path, revisionId, 1, 0, -1, null)

Parameters:

path - path denoting root of node tree to be retrieved

revisionId - revision, if null the current head revision is assumed

Returns:

node tree in JSON format

Throws:

MicroKernelException - if an error occurs

getNodes

String getNodes(String path,
                String revisionId,
                int depth,
                long offset,
                int count,
                String filter)
                throws MicroKernelException

Returns the node tree rooted at the specified parent node with the specified depth, maximum child node count and offset. The depth of the returned tree is governed by the depth parameter:

depth = 0	properties, including :childNodeCount and child node names (i.e. empty child node objects)
depth = 1	properties, child nodes and their properties (including :childNodeCount)
depth = 2	[and so on...]

The offset and count parameters are only applied to the direct child nodes of the root of the returned node tree.

Parameters:

path - path denoting root of node tree to be retrieved

revisionId - revision, if null the current head revision is assumed

depth - maximum depth of returned tree

offset - start position in the iteration order of child nodes (0 to start at the beginning)

count - maximum number of child nodes to retrieve (-1 for all)

filter - (optional) filter criteria (e.g. names of properties to be included, etc); TODO specify format and semantics

Returns:

node tree in JSON format

Throws:

MicroKernelException - if an error occurs

commit

String commit(String path,
              String jsonDiff,
              String revisionId,
              String message)
              throws MicroKernelException

Applies the specified changes on the specified target node.

If path.length() == 0 the paths specified in the jsonDiff are expected to be absolute.

The implementation tries to merge changes if the revision id of the commit is set accordingly. As an example, deleting a node is allowed if the node existed in the given revision, even if it was deleted in the meantime.

Parameters:

path - path denoting target node

jsonDiff - changes to be applied in JSON diff format.

revisionId - revision the changes are based on, if null the current head revision is assumed

message - commit message

Returns:

id of newly created revision

Throws:

MicroKernelException - if an error occurs

getLength

long getLength(String blobId)
               throws MicroKernelException

Returns the length of the specified blob.

Parameters:

blobId - blob identifier

Returns:

length of the specified blob

Throws:

MicroKernelException - if an error occurs

read

int read(String blobId,
         long pos,
         byte[] buff,
         int off,
         int length)
         throws MicroKernelException

Reads up to length bytes of data from the specified blob into the given array of bytes. An attempt is made to read as many as length bytes, but a smaller number may be read. The number of bytes actually read is returned as an integer.

Parameters:

blobId - blob identifier

pos - the offset within the blob

buff - the buffer into which the data is read.

off - the start offset in array buff at which the data is written.

length - the maximum number of bytes to read

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the blob content has been reached.

Throws:

MicroKernelException - if an error occurs

write

String write(InputStream in)
             throws MicroKernelException

Stores the content of the given stream and returns an associated identifier for later retrieval.

If identical stream content has been stored previously, then the existing identifier will be returned instead of storing a redundant copy.

The stream is closed by this method.

Parameters:

in - InputStream providing the blob content

Returns:

blob identifier associated with the given content

Throws:

MicroKernelException - if an error occurs