org.apache.jackrabbit.mk.client
Class Client

java.lang.Object
  org.apache.jackrabbit.mk.client.Client

All Implemented Interfaces:

MicroKernel

public class Client
extends Object
implements MicroKernel

Client exposing a MicroKernel interface, that "remotes" commands to a server.

Constructor Summary

Client(InetSocketAddress addr)
Create a new instance of this class.

Client(InetSocketAddress addr, SocketFactory socketFactory)
Create a new instance of this class.

Client(String url)
Create a new instance of this class.

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 maxWaitMillis) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Client

public Client(String url)

Create a new instance of this class.

Parameters:

url - socket address

Client

public Client(InetSocketAddress addr)

Create a new instance of this class.

Parameters:

addr - socket address

Client

public Client(InetSocketAddress addr,
              SocketFactory socketFactory)

Create a new instance of this class.

Parameters:

addr - socket address

Method Detail

dispose

public void dispose()

Description copied from interface: MicroKernel

Dispose this instance.

Specified by:

dispose in interface MicroKernel

getHeadRevision

public String getHeadRevision()
                       throws MicroKernelException

Description copied from interface: MicroKernel

Return the id of the current head revision.

Specified by:

getHeadRevision in interface MicroKernel

Returns:

the id of the head revision

Throws:

MicroKernelException - if an error occurs

getRevisionHistory

public String getRevisionHistory(long since,
                                 int maxEntries)
                          throws MicroKernelException

Description copied from interface: MicroKernel

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>"
   },
   ...
 ]
 

Specified by:

getRevisionHistory in interface MicroKernel

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

public String waitForCommit(String oldHeadRevisionId,
                            long maxWaitMillis)
                     throws MicroKernelException,
                            InterruptedException

Description copied from interface: MicroKernel

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().

Specified by:

waitForCommit in interface MicroKernel

Parameters:

oldHeadRevisionId - id of earlier head revision

maxWaitMillis - 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

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

Description copied from interface: MicroKernel

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.

Specified by:

getJournal in interface MicroKernel

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

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

Description copied from interface: MicroKernel

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.

Specified by:

diff in interface MicroKernel

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

public boolean nodeExists(String path,
                          String revisionId)
                   throws MicroKernelException

Description copied from interface: MicroKernel

Determines whether the specified node exists.

Specified by:

nodeExists in interface MicroKernel

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

public long getChildNodeCount(String path,
                              String revisionId)
                       throws MicroKernelException

Description copied from interface: MicroKernel

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.

Specified by:

getChildNodeCount in interface MicroKernel

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

public String getNodes(String path,
                       String revisionId)
                throws MicroKernelException

Description copied from interface: MicroKernel

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 MicroKernel.getNodes(String, String, int, long, int, String)

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

Specified by:

getNodes in interface MicroKernel

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

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

Description copied from interface: MicroKernel

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.

Specified by:

getNodes in interface MicroKernel

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

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

Description copied from interface: MicroKernel

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.

Specified by:

commit in interface MicroKernel

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

public String branch(String trunkRevisionId)
              throws MicroKernelException

Description copied from interface: MicroKernel

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.

Specified by:

branch in interface MicroKernel

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:

MicroKernel.merge(String, String)

merge

public String merge(String branchRevisionId,
                    String message)
             throws MicroKernelException

Description copied from interface: MicroKernel

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.

Specified by:

merge in interface MicroKernel

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:

MicroKernel.branch(String)

getLength

public long getLength(String blobId)
               throws MicroKernelException

Description copied from interface: MicroKernel

Returns the length of the specified blob.

Specified by:

getLength in interface MicroKernel

Parameters:

blobId - blob identifier

Returns:

length of the specified blob

Throws:

MicroKernelException - if an error occurs

read

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

Description copied from interface: MicroKernel

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.

Specified by:

read in interface MicroKernel

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

public String write(InputStream in)
             throws MicroKernelException

Description copied from interface: MicroKernel

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.

Specified by:

write in interface MicroKernel

Parameters:

in - InputStream providing the blob content

Returns:

blob identifier associated with the given content

Throws:

MicroKernelException - if an error occurs