Return-Path: X-Original-To: apmail-jackrabbit-oak-commits-archive@minotaur.apache.org Delivered-To: apmail-jackrabbit-oak-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 51C3D9746 for ; Fri, 13 Apr 2012 13:14:56 +0000 (UTC) Received: (qmail 18238 invoked by uid 500); 13 Apr 2012 13:14:56 -0000 Delivered-To: apmail-jackrabbit-oak-commits-archive@jackrabbit.apache.org Received: (qmail 18218 invoked by uid 500); 13 Apr 2012 13:14:56 -0000 Mailing-List: contact oak-commits-help@jackrabbit.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: oak-commits@jackrabbit.apache.org Delivered-To: mailing list oak-commits@jackrabbit.apache.org Received: (qmail 18209 invoked by uid 99); 13 Apr 2012 13:14:56 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 13 Apr 2012 13:14:56 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 13 Apr 2012 13:14:54 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 54BB32388865; Fri, 13 Apr 2012 13:14:34 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: oak-commits@jackrabbit.apache.org From: stefan@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20120413131434.54BB32388865@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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}. *

- * 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. + *

+ * 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 fromRevisionId - * and ending with toRevisionId. + * Returns a revision journal, starting with {@code fromRevisionId} + * and ending with @code toRevisionId}. *

* Format: * 

      * [ { "id" : "<revisionId>", "ts" : "<revisionTimestamp>", "msg" : "<commitMessage>", "changes" : "<JSON diff>" }, ... ]
      *
* - * @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>" }, ... ] * * - * @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 true if the specified node exists, otherwise false + * @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. *

* This is a convenience method since this information could gathered by - * calling getNodes(path, revisionId, 0, 0, 0) and evaluating - * the :childNodeCount 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 - * :childNodeCount). Example: + * {@code :childNodeCount}). Example: * 

      * {
      *     "someprop": "someval",
@@ -188,18 +192,18 @@ public interface MicroKernel {
      *
* Remarks: *
    - *
  • If the property :childNodeCount equals 0, then the + *
  • If the property {@code :childNodeCount} equals 0, then the * node does not have any child nodes. - *
  • If the value of :childNodeCount is larger than the number + *
  • 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)}
    • *
* This method is a convenience method for - * getNodes(path, revisionId, 1, 0, -1, null) + * {@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 depth parameter: + * returned tree is governed by the {@code depth} parameter: * * * - * * * * * + * {@code :childNodeCount}) * * * @@ -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. *

- * If path.length() == 0 the paths specified in the - * jsonDiff are expected to be absolute. + * If {@code path.length() == 0} the paths specified in the + * {@code 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 @@ -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 length 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 - * length 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 buff + * @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 - * -1 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 */

depth = 0properties, including :childNodeCount and + * properties, including {@code :childNodeCount} and * child node names (i.e. empty child node objects)
depth = 1properties, child nodes and their properties (including - * :childNodeCount)
depth = 2