You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by st...@apache.org on 2012/04/13 15:14:34 UTC
svn commit: r1325754 -
/jackrabbit/oak/trunk/oak-mk/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java
Author: stefan
Date: Fri Apr 13 13:14:33 2012
New Revision: 1325754
URL: http://svn.apache.org/viewvc?rev=1325754&view=rev
Log:
OAK-11 cleanup api javadoc (WIP)
Modified:
jackrabbit/oak/trunk/oak-mk/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java
Modified: jackrabbit/oak/trunk/oak-mk/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-mk/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java?rev=1325754&r1=1325753&r2=1325754&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-mk/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java (original)
+++ jackrabbit/oak/trunk/oak-mk/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java Fri Apr 13 13:14:33 2012
@@ -56,7 +56,7 @@ public interface MicroKernel {
/**
* Return the id of the current head revision.
*
- * @return id of head revision
+ * @return the id of the head revision
* @throws MicroKernelException if an error occurs
*/
String getHeadRevision() throws MicroKernelException;
@@ -80,32 +80,36 @@ public interface MicroKernel {
throws MicroKernelException;
/**
- * Wait for a commit to occur that is newer than the given revision number.
+ * Waits for a commit to occur that is more recent than {@code oldHeadRevisionId}.
* <p/>
- * This method is useful efficient polling. The method will return the current head revision
- * if it is newer than the given revision ID, or wait until the given number of
- * milliseconds passed or a new head revision is available.
- *
- * @param oldHeadRevisionId A revision Id
- * @param maxWaitMillis the maximum number of milliseconds to wait (0 if the
- * method should not wait).
- * @return the current head revision Id
+ * 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
+ * {@code oldHeadRevisionId}, or waits if either the specified amount of time
+ * has elapsed or a new head revision has become available.
+ * <p/>
+ * if a zero or negative {@code timeout} value has been specified the method
+ * will return immediately, i.e. calling {@code waitForCommit(0)} is
+ * equivalent to calling {@code getHeadRevision()}.
+ *
+ * @param oldHeadRevisionId id of previous head revision
+ * @param timeout the maximum time to wait in milliseconds
+ * @return the id of the head revision
* @throws MicroKernelException if an error occurs
* @throws InterruptedException if the thread was interrupted
*/
- String waitForCommit(String oldHeadRevisionId, long maxWaitMillis) throws MicroKernelException, InterruptedException;
+ String waitForCommit(String oldHeadRevisionId, long timeout) throws MicroKernelException, InterruptedException;
/**
- * Returns a revision journal, starting with <code>fromRevisionId</code>
- * and ending with <code>toRevisionId</code>.
+ * Returns a revision journal, starting with {@code fromRevisionId}
+ * and ending with @code toRevisionId}.
* <p/>
* Format:
* <pre>
* [ { "id" : "<revisionId>", "ts" : "<revisionTimestamp>", "msg" : "<commitMessage>", "changes" : "<JSON diff>" }, ... ]
* </pre>
*
- * @param fromRevisionId first revision to be returned in journal
- * @param toRevisionId last revision to be returned in journal, if null the current head revision is assumed
+ * @param fromRevisionId id of first revision to be returned in journal
+ * @param toRevisionId id of last revision to be returned in journal, if null the current head revision is assumed
* @param filter (optional) filter criteria
* (e.g. path, property names, etc);
* TODO specify format and semantics
@@ -128,8 +132,8 @@ public interface MicroKernel {
* [ { "id" : "<revisionId>", "ts" : "<revisionTimestamp>", "msg" : "<commitMessage>", "changes" : "<JSON diff>" }, ... ]
* </pre>
*
- * @param fromRevisionId a revision
- * @param toRevisionId another revision, if null the current head revision is assumed
+ * @param fromRevisionId a revision id
+ * @param toRevisionId another revision id, if null the current head revision is assumed
* @param filter (optional) filter criteria
* (e.g. path, property names, etc);
* TODO specify format and semantics
@@ -146,8 +150,8 @@ public interface MicroKernel {
* Determines whether the specified node exists.
*
* @param path path denoting node
- * @param revisionId revision, if null the current head revision is assumed
- * @return <code>true</code> if the specified node exists, otherwise <code>false</code>
+ * @param revisionId revision id, if null the current head revision is assumed
+ * @return {@code true} if the specified node exists, otherwise {@code false}
* @throws MicroKernelException if an error occurs
*/
boolean nodeExists(String path, String revisionId) throws MicroKernelException;
@@ -156,12 +160,12 @@ public interface MicroKernel {
* Returns the number of child nodes of the specified node.
* <p/>
* This is a convenience method since this information could gathered by
- * calling <code>getNodes(path, revisionId, 0, 0, 0)</code> and evaluating
- * the <code>:childNodeCount</code> property.
+ * calling {@code getNodes(path, revisionId, 0, 0, 0)} and evaluating
+ * the {@code :childNodeCount} property.
*
*
* @param path path denoting node
- * @param revisionId revision, if null the current head revision is assumed
+ * @param revisionId revision id, if null the current head revision is assumed
* @return the number of child nodes
* @throws MicroKernelException if an error occurs
*/
@@ -171,7 +175,7 @@ public 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
- * <code>:childNodeCount</code>). Example:
+ * {@code :childNodeCount}). Example:
* <pre>
* {
* "someprop": "someval",
@@ -188,18 +192,18 @@ public interface MicroKernel {
* </pre>
* Remarks:
* <ul>
- * <li>If the property <code>:childNodeCount</code> equals 0, then the
+ * <li>If the property {@code :childNodeCount} equals 0, then the
* node does not have any child nodes.
- * <li>If the value of <code>:childNodeCount</code> is larger than the number
+ * <li>If the value of {@code :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 {@link #getNodes(String, String, int, long, int, String)}</li>
* </ul>
* This method is a convenience method for
- * <code>getNodes(path, revisionId, 1, 0, -1, null)</code>
+ * {@code getNodes(path, revisionId, 1, 0, -1, null)}
*
* @param path path denoting root of node tree to be retrieved
- * @param revisionId revision, if null the current head revision is assumed
+ * @param revisionId revision id, if null the current head revision is assumed
* @return node tree in JSON format
* @throws MicroKernelException if an error occurs
*/
@@ -208,17 +212,17 @@ public 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 <code>depth</code> parameter:
+ * returned tree is governed by the {@code depth} parameter:
* <table>
* <tr>
* <td>depth = 0</td>
- * <td>properties, including <code>:childNodeCount</code> and
+ * <td>properties, including {@code :childNodeCount} and
* child node names (i.e. empty child node objects)</td>
* </tr>
* <tr>
* <td>depth = 1</td>
* <td>properties, child nodes and their properties (including
- * <code>:childNodeCount</code>)</td>
+ * {@code :childNodeCount})</td>
* </tr>
* <tr>
* <td>depth = 2</td>
@@ -230,7 +234,7 @@ public interface MicroKernel {
* direct child nodes of the root of the returned node tree.
*
* @param path path denoting root of node tree to be retrieved
- * @param revisionId revision, if null the current head revision is assumed
+ * @param revisionId revision id, if null the current head revision is assumed
* @param depth maximum depth of returned tree
* @param offset start position in the iteration order of child nodes (0 to start at the
* beginning)
@@ -248,8 +252,8 @@ public interface MicroKernel {
/**
* Applies the specified changes on the specified target node.
* <p>
- * If <code>path.length() == 0</code> the paths specified in the
- * <code>jsonDiff</code> are expected to be absolute.
+ * If {@code path.length() == 0} the paths specified in the
+ * {@code jsonDiff} are expected to be absolute.
* <p>
* 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
@@ -258,7 +262,7 @@ public interface MicroKernel {
*
* @param path path denoting target node
* @param jsonDiff changes to be applied in JSON diff format.
- * @param revisionId revision the changes are based on, if null the current head revision is assumed
+ * @param revisionId id of revision the changes are based on, if null the current head revision is assumed
* @param message commit message
* @return id of newly created revision
* @throws MicroKernelException if an error occurs
@@ -279,19 +283,19 @@ public interface MicroKernel {
long getLength(String blobId) throws MicroKernelException;
/**
- * Reads up to <code>length</code> bytes of data from the specified blob into
+ * Reads up to {@code length} bytes of data from the specified blob into
* the given array of bytes. An attempt is made to read as many as
- * <code>length</code> bytes, but a smaller number may be read.
+ * {@code length} bytes, but a smaller number may be read.
* The number of bytes actually read is returned as an integer.
*
* @param blobId blob identifier
* @param pos the offset within the blob
* @param buff the buffer into which the data is read.
- * @param off the start offset in array <code>buff</code>
+ * @param off the start offset in array {@code buff}
* at which the data is written.
* @param length the maximum number of bytes to read
* @return the total number of bytes read into the buffer, or
- * <code>-1</code> if there is no more data because the end of
+ * {@code -1} if there is no more data because the end of
* the blob content has been reached.
* @throws MicroKernelException if an error occurs
*/