jackrabbit-oak-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject svn commit: r1325754 - /jackrabbit/oak/trunk/oak-mk/src/main/java/org/apache/jackrabbit/mk/api/MicroKernel.java
Date Fri, 13 Apr 2012 13:14:34 GMT
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" : "&lt;revisionId&gt;", "ts" : "&lt;revisionTimestamp&gt;",
"msg" : "&lt;commitMessage&gt;", "changes" : "&lt;JSON diff&gt;" }, ... ]
      * </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" : "&lt;revisionId&gt;", "ts" : "&lt;revisionTimestamp&gt;",
"msg" : "&lt;commitMessage&gt;", "changes" : "&lt;JSON diff&gt;" }, ... ]
      * </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
      */



Mime
View raw message