org.apache.jackrabbit.mk.api
Interface MicroKernel

All Known Implementing Classes:

Client, 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	branch(String trunkRevisionId) Creates a private branch revision off the specified public trunk revision.
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 in chronological order.
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	getRevisionHistory(long since, int maxEntries) Returns a list of all currently available (historical) head revisions in chronological order since a specific point.
String	merge(String branchRevisionId, String message) Merges the specified private branch revision with the current head revision.
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 oldHeadRevisionId, long timeout) Waits for a commit to occur that is more recent than oldHeadRevisionId.
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:

the id of the head revision

Throws:

MicroKernelException - if an error occurs

getRevisionHistory

String getRevisionHistory(long since,
                          int maxEntries)
                          throws MicroKernelException

Returns a list of all currently available (historical) head revisions in chronological order since a specific point. Private branch revisions won't be included in the result.

Format:

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

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 list of revisions in chronological order in JSON format.

Throws:

MicroKernelException - if an error occurs

waitForCommit

String waitForCommit(String oldHeadRevisionId,
                     long timeout)
                     throws MicroKernelException,
                            InterruptedException

Waits for a commit to occur that is more recent than oldHeadRevisionId.

This method allows for efficient polling for new revisions. The method will return the id of the current head revision if it is more recent than oldHeadRevisionId, or waits if either the specified amount of time has elapsed or a new head revision has become available.

if a zero or negative timeout value has been specified the method will return immediately, i.e. calling waitForCommit(0) is equivalent to calling getHeadRevision().

Parameters:

oldHeadRevisionId - id of earlier head revision

timeout - the maximum time to wait in milliseconds

Returns:

the id of the 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 in chronological order.

Format:

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

If fromRevisionId and toRevisionId are not in chronological order the returned journal will be empty (i.e. [])

A MicroKernelException is thrown if either fromRevisionId or toRevisionId doesn't exist, denotes a private branch revision or if another error occurs.

Parameters:

fromRevisionId - id of first revision to be returned in journal

toRevisionId - id of 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. fromRevisionId and toRevisionId don't need not be in a specific chronological order.

Parameters:

fromRevisionId - a revision id, if null the current head revision is assumed

toRevisionId - another revision id, 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 id, 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 id, if null the current head revision is assumed

Returns:

the number of child nodes

Throws:

MicroKernelException - if the specified node does not exist or 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 id, if null the current head revision is assumed

Returns:

node tree in JSON format or null if the specified node does not exist

Throws:

MicroKernelException - if the specified revision does not exist or if another 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 id, 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 or null if the specified node does not exist

Throws:

MicroKernelException - if the specified revision does not exist or if another 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 - id of 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

branch

String branch(String trunkRevisionId)
              throws MicroKernelException

Creates a private branch revision off the specified public trunk revision.

A MicroKernelException is thrown if trunkRevisionId doesn't exist, if it's not a trunk revision (i.e. it's not reachable by traversing the revision history in reverse chronological order starting from the current head revision) or if another error occurs.

Parameters:

trunkRevisionId - id of public trunk revision to base branch on, if null the current head revision is assumed

Returns:

id of newly created private branch revision

Throws:

MicroKernelException - if trunkRevisionId doesn't exist, if it's not a trunk revision or if another error occurs

See Also:

merge(String, String)

merge

String merge(String branchRevisionId,
             String message)
             throws MicroKernelException

Merges the specified private branch revision with the current head revision.

A MicroKernelException is thrown if branchRevisionId doesn't exist, if it's not a branch revision, if the merge fails because of conflicting changes or if another error occurs.

Parameters:

branchRevisionId - id of private branch revision

message - commit message

Returns:

id of newly created head revision

Throws:

MicroKernelException - if branchRevisionId doesn't exist, if it's not a branch revision, if the merge fails because of conflicting changes or if another error occurs.

See Also:

branch(String)

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