org.apache.jackrabbit.mk.api
Interface MicroKernel

public interface MicroKernel

The MicroKernel Design Goals and 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
• session-less API (there's no concept of sessions; an implementation doesn't need to track/manage session state)
• easily portable to C
• easy to remote
• 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

The Retention Policy for Revisions:

TODO specify retention policy for old revisions, i.e. minimal guaranteed retention period (OAK-114)

The Retention Policy for Binaries:

The MicroKernel implementation is free to remove binaries if both of the following conditions are met:

• If the binary is not references as a property value of the format ":blobId:<blobId>" where <blobId> is the id returned by write(InputStream in). This includes simple property values such as {"bin": ":blobId:1234"} as well as array property values such as {"array": [":blobId:1234", ":blobId:5678"]}.
• If the binary was stored before the last retained revision (this is to keep temporary binaries, and binaries that are not yet referenced).

Field Summary

static String

CONFLICT

Method Summary

String	branch(String trunkRevisionId) Creates a private branch revision off the specified public trunk revision.
String	checkpoint(long lifetime) Creates a new checkpoint of the latest head 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 path, int depth) Returns the JSON diff representation of the changes between the specified revisions.
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, i.e.
String	getJournal(String fromRevisionId, String toRevisionId, String path) 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, int depth, long offset, int maxChildNodes, String filter) Returns the node tree rooted at the specified parent node with the specified depth, maximum child node maxChildNodes and offset.
String	getRevisionHistory(long since, int maxEntries, String path) 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 where the actual number of bytes read is min(length, max(0, blobLength - pos)).
String	rebase(String branchRevisionId, String newBaseRevisionId) Rebases the specified private branch revision on top of specified new base revision.
String	reset(String branchRevisionId, String ancestorRevisionId) Resets the branch identified by branchRevisionId to an ancestor branch commit identified by ancestorRevisionId.
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.

Field Detail

CONFLICT

static final String CONFLICT

See Also:

Constant Field Values

Method Detail

getHeadRevision

String getHeadRevision()
                       throws MicroKernelException

Return the id of the current head revision, i.e. the most recent public trunk revision. Private branch revisions are ignored.

Returns:

the id of the head revision

Throws:

MicroKernelException - if an error occurs

checkpoint

@Nonnull
String checkpoint(long lifetime)
                  throws MicroKernelException

Creates a new checkpoint of the latest head revision. The checkpoint guarantees that revision to remain valid and accessible for at least as long as requested.

Parameters:

lifetime - time (in milliseconds) that the checkpoint should remain available

Returns:

revision id of the created checkpoint

Throws:

MicroKernelException - if the checkpoint could not be created

getRevisionHistory

String getRevisionHistory(long since,
                          int maxEntries,
                          String path)
                          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>"
   },
   ...
 ]
 

The path parameter allows to filter the revisions by path, i.e. only those revisions that affected the subtree rooted at path will be included.

The maxEntries parameter allows to limit the number of revisions returned. if maxEntries < 0 no limit will be applied. otherwise, if the number of revisions satisfying the specified since and path criteria exceeds maxEntries, only maxEntries entries will be returned (in chronological order, starting with the oldest).

Parameters:

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

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

path - optional path filter; if null or "" the default ("/") will be assumed, i.e. no filter 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(oldHeadRevisionId, 0) is equivalent to calling getHeadRevision().

Note that commits on a private branch will be ignored.

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 path)
                  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. [])

The path parameter allows to filter the revisions by path, i.e. only those revisions that affected the subtree rooted at path will be included. The filter will also be applied to the JSON diff, i.e. the diff will include only those changes that affected the subtree rooted at path.

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

If the journal includes private branch revisions, those entries will include a "branchRootId" denoting the head revision the private branch is based on.

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

path - optional path filter; if null or "" the default ("/") will be assumed, i.e. no filter will be applied

Returns:

a chronological list of revisions in JSON format

Throws:

MicroKernelException - if any of the specified revisions doesn't exist or if another error occurs

diff

String diff(String fromRevisionId,
            String toRevisionId,
            String path,
            int depth)
            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.

The path parameter allows to filter the changes included in the JSON diff, i.e. only those changes that affected the subtree rooted at path will be included.

The depth limit applies to the subtree rooted at path. It allows to limit the depth of the diff, i.e. only changes up to the specified depth will be included in full detail. changes at paths exceeding the specified depth limit will be reported as ^"/some/path" : {}, indicating that there are unspecified changes below that path.

depth value	scope of detailed diff
-1	no limit will be applied
0	changes affecting the properties and child node names of the node at path
1	changes affecting the properties and child node names of the node at path and its direct descendants
...	...

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

path - optional path filter; if null or "" the default ("/") will be assumed, i.e. no filter will be applied

depth - depth limit; if -1 no limit will be applied

Returns:

JSON diff representation of the changes

Throws:

MicroKernelException - if any of the specified revisions doesn't exist or if another 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 the specified revision does not exist or if another 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 the number of child nodes can be also determined by calling getNodes(path, revisionId, 0, 0, 0, null) 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 or revision does not exist or if another error occurs

getNodes

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

Returns the node tree rooted at the specified parent node with the specified depth, maximum child node maxChildNodes 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) and their child node names (i.e. empty child node objects)
depth = 2	[and so on...]

Example (depth=0):

 {
   "someprop" : "someval",
   ":childNodeCount" : 2,
   "child1" : {},
   "child2" : {}
 }
 

Example (depth=1):

 {
   "someprop" : "someval",
   ":childNodeCount" : 2,
   "child1" : {
     "prop1" : 123,
     ":childNodeCount" : 2,
     "grandchild1" : {},
     "grandchild2" : {}
   },
   "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 returned tree.

The offset parameter is only applied to the direct child nodes of the root of the returned node tree. maxChildNodes however is applied on all hierarchy levels.

An IllegalArgumentException is thrown if both an offset greater than zero and a filter on node names (see below) have been specified.

The order of the child nodes is stable for any given revisionId, i.e. calling getNodes repeatedly with the same revisionId is guaranteed to return the child nodes in the same order, but the specific order used is implementation-dependent and may change across different revisions of the same node.

The optional filter parameter allows to specify glob patterns for names of nodes and/or properties to be included or excluded.

Example:

 {
   "nodes": [ "foo*", "-foo1" ],
   "properties": [ "*", "-:childNodeCount" ]
 }
 

In the above example all child nodes with names starting with "foo" will be included, except for nodes named "foo1"; similarly, all properties will be included except for the ":childNodeCount" metadata property (see below).

Glob Syntax:

• a nodes or properties filter consists of one or more globs.
• a glob prefixed by - (dash) is treated as an exclusion pattern; all others are considered inclusion patterns.
• a leading - (dash) must be escaped by prepending \ (backslash) if it should be interpreted as a literal.
• * (asterisk) serves as a wildcard, i.e. it matches any substring in the target name.
• * (asterisk) occurrences within the glob to be interpreted as literals must be escaped by prepending \ (backslash).
• a filter matches a target name if any of the inclusion patterns match but none of the exclusion patterns.

If no filter is specified the implicit default filter is assumed: {"nodes":["*"],"properties":["*"]}

System-provided metadata properties:

• :childNodeCount provides the actual number of direct child nodes; this property is included by the implicit default filter. it can be excluded by specifying a filter such as {properties:["*", "-:childNodeCount"]}
• :hash provides a content-based identifier for the subtree rooted at the :hash property's parent node. :hash values are similar to fingerprints. they can be compared to quickly determine if two subtrees are identical. if the :hash values are different the respective subtrees are different with regard to structure and/or properties. if on the other hand the :hash values are identical the respective subtrees are identical with regard to structure and properties. :hash is not included by the implicit default filter. it can be included by specifying a filter such as {properties:["*", ":hash"]}.

  Returning the :hash property is optional. Some implementations might only return it on specific nodes or might not support it at all. If however a :hash property is returned it has to obey the contract described above.

  Implementations that keep track of the child hash along with the child node name can return the :hash value also as a property of the child node objects, even if they'd otherwise be empty, for example due to a depth limit. If such child hashes are returned, the client can use them as an alternative to child paths when accessing those nodes.

• :id provides an implementation-specific identifier of a node. Identifiers are like content hashes as described above, except for the fact that two different identifiers may refer to identical subtrees. Also :id values may be returned for child nodes, in which case the client can use them for accessing those nodes.

Parameters:

path - path denoting root of node tree to be retrieved, or alternatively a previously returned :hash or :id value; in the latter case the revisionId parameter is ignored.

revisionId - revision id, if null the current head revision is assumed; the revisionId parameter is ignored if path is an identifier (i.e. a :hash or :id value).

depth - maximum depth of returned tree

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

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

filter - optional filter on property and/or node names; if null or "" the default filter will be 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

IllegalArgumentException - if both an offset > 0 and a filter on node names have been specified

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 the specified revision doesn't exist or if another 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)

rebase

@Nonnull
String rebase(@Nonnull
                      String branchRevisionId,
                      String newBaseRevisionId)
              throws MicroKernelException

Rebases the specified private branch revision on top of specified new base revision.

A MicroKernelException is thrown if branchRevisionId doesn't exist, if it's not a branch revision, if newBaseRevisionId doesn't exist, if it's a branch revision or if another error occurs.

If rebasing results in a conflict, conflicting nodes are annotated with a conflict marker denoting the type of the conflict and the value(s) before the rebase operation. The conflict marker is an internal node with the name CONFLICT and is added to the node whose properties or child nodes are in conflict.

type of conflicts:

addExistingProperty:

A property has been added that has a different value than a property with the same name that has been added in trunk.

deleteDeletedProperty:

A property has been removed while a property of the same name has been removed in trunk.

deleteChangedProperty:

A property has been removed while a property of the same name has been changed in trunk.

changeDeletedProperty:

A property has been changed while a property of the same name has been removed in trunk.

changeChangedProperty:

A property has been changed while a property of the same name has been changed to a different value in trunk.

addExistingNode:

A node has been added that can't be merged with a node of them same name that has been added to the trunk. How and whether merging takes place is up to the implementation. Merging must not cause data to be lost however.

deleteDeletedNode:

A node has been removed while a node of the same name has been removed in trunk.

deleteChangedNode:

A node has been removed while a node of the same name has been changed in trunk.

changeDeletedNode:

A node has been changed while a node of the same name has been removed in trunk.

In this context a node is regarded as changed if a property was added, a property was removed, a property was set to a different value, a child node was added, a child node was removed or a child node was changed.

On conflict the conflict marker node carries the conflicting value of the branch while the rebased value in the branch itself will be set to the conflicting value of the trunk. In the case of conflicting properties, the conflicting value is the property value from the branch. In the case of conflicting node, the conflicting value is the node from the branch.

Parameters:

branchRevisionId - id of private branch revision

newBaseRevisionId - id of new base revision

Returns:

id of the rebased branch revision

Throws:

MicroKernelException - if branchRevisionId doesn't exist, if it's not a branch revision, if newBaseRevisionId doesn't exist, if it's a branch revision, or if another error occurs.

reset

@Nonnull
String reset(@Nonnull
                     String branchRevisionId,
                     @Nonnull
                     String ancestorRevisionId)
             throws MicroKernelException

Resets the branch identified by branchRevisionId to an ancestor branch commit identified by ancestorRevisionId.

Parameters:

branchRevisionId - id of the private branch revision

ancestorRevisionId - id of the ancestor commit to reset the branch to.

Returns:

the id of the new head of the branch. This may not necessarily be the same as ancestorRevisionId. An implementation is free to create a new id for the reset branch.

Throws:

MicroKernelException - if branchRevisionId doesn't exist, if it's not a branch revision, if ancestorRevisionId is not a revision on that branch or if another 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 the specified blob does not exist or if another 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 where the actual number of bytes read is min(length, max(0, blobLength - pos)).

If the returned value is smaller than length, no more data is available. This method never returns negative values.

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.

Throws:

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