ZooKeeper
  1. ZooKeeper
  2. ZOOKEEPER-1336

javadoc for multi is confusing, references functionality that doesn't seem to exist

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 3.4.1
    • Fix Version/s: 3.4.3, 3.5.0
    • Component/s: java client
    • Labels:
      None
    • Hadoop Flags:
      Reviewed
    • Release Note:
      Improved Javadoc for multi API's.

      Description

      There's this in org.apache.zookeeper.ZooKeeper.multi(Iterable<Op>)

           * Executes multiple Zookeeper operations or none of them.  On success, a list of results is returned.
           * On failure, only a single exception is returned.  If you want more details, it may be preferable to
           * use the alternative form of this method that lets you pass a list into which individual results are
           * placed so that you can zero in on exactly which operation failed and why.
      

      What is the "alternate form of this method" that's being referred to? Seems like we should add this functionality, or at the very least update the javadoc. (I don't think this is referring to Transaction, although the docs there are pretty thin)

        Activity

        Hide
        Patrick Hunt added a comment -

        Also, is there an implied order to the returned list? specifically is it the same order as the "ops" list? The javadocs should mention this.

        Show
        Patrick Hunt added a comment - Also, is there an implied order to the returned list? specifically is it the same order as the "ops" list? The javadocs should mention this.
        Hide
        Ted Dunning added a comment -

        Taking the easy question first, yes, the order is implied.

        Regarding the javadoc, I believe that this refers to a capability that was removed because it turned out to be redundant after we decided to return a list.

        Show
        Ted Dunning added a comment - Taking the easy question first, yes, the order is implied. Regarding the javadoc, I believe that this refers to a capability that was removed because it turned out to be redundant after we decided to return a list.
        Hide
        Marshall McMullen added a comment -

        Yes, the order of the results will exactly match the order of the operations.

        Ted is correct, the "alternative method" was removed and we instead just return a list. Javadoc comments should be updated accordingly.

        Show
        Marshall McMullen added a comment - Yes, the order of the results will exactly match the order of the operations. Ted is correct, the "alternative method" was removed and we instead just return a list. Javadoc comments should be updated accordingly.
        Hide
        Patrick Hunt added a comment -

        Thanks Marshall/Ted!

        I updated the javadoc to correct the inaccuracies. I also added @since tags to let users know when this was introduced.

        LMK if there's anything else we should add.

        Show
        Patrick Hunt added a comment - Thanks Marshall/Ted! I updated the javadoc to correct the inaccuracies. I also added @since tags to let users know when this was introduced. LMK if there's anything else we should add.
        Hide
        Hadoop QA added a comment -

        -1 overall. Here are the results of testing the latest attachment
        http://issues.apache.org/jira/secure/attachment/12508418/ZOOKEEPER-1336.patch
        against trunk revision 1221868.

        +1 @author. The patch does not contain any @author tags.

        -1 tests included. The patch doesn't appear to include any new or modified tests.
        Please justify why no new tests are needed for this patch.
        Also please list what manual steps were performed to verify this patch.

        +1 javadoc. The javadoc tool did not generate any warning messages.

        +1 javac. The applied patch does not increase the total number of javac compiler warnings.

        +1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings.

        +1 release audit. The applied patch does not increase the total number of release audit warnings.

        -1 core tests. The patch failed core unit tests.

        +1 contrib tests. The patch passed contrib unit tests.

        Test results: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/849//testReport/
        Findbugs warnings: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/849//artifact/trunk/build/test/findbugs/newPatchFindbugsWarnings.html
        Console output: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/849//console

        This message is automatically generated.

        Show
        Hadoop QA added a comment - -1 overall. Here are the results of testing the latest attachment http://issues.apache.org/jira/secure/attachment/12508418/ZOOKEEPER-1336.patch against trunk revision 1221868. +1 @author. The patch does not contain any @author tags. -1 tests included. The patch doesn't appear to include any new or modified tests. Please justify why no new tests are needed for this patch. Also please list what manual steps were performed to verify this patch. +1 javadoc. The javadoc tool did not generate any warning messages. +1 javac. The applied patch does not increase the total number of javac compiler warnings. +1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings. +1 release audit. The applied patch does not increase the total number of release audit warnings. -1 core tests. The patch failed core unit tests. +1 contrib tests. The patch passed contrib unit tests. Test results: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/849//testReport/ Findbugs warnings: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/849//artifact/trunk/build/test/findbugs/newPatchFindbugsWarnings.html Console output: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/849//console This message is automatically generated.
        Hide
        Hadoop QA added a comment -

        -1 overall. Here are the results of testing the latest attachment
        http://issues.apache.org/jira/secure/attachment/12508418/ZOOKEEPER-1336.patch
        against trunk revision 1221868.

        +1 @author. The patch does not contain any @author tags.

        -1 tests included. The patch doesn't appear to include any new or modified tests.
        Please justify why no new tests are needed for this patch.
        Also please list what manual steps were performed to verify this patch.

        +1 javadoc. The javadoc tool did not generate any warning messages.

        +1 javac. The applied patch does not increase the total number of javac compiler warnings.

        +1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings.

        +1 release audit. The applied patch does not increase the total number of release audit warnings.

        -1 core tests. The patch failed core unit tests.

        +1 contrib tests. The patch passed contrib unit tests.

        Test results: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/852//testReport/
        Findbugs warnings: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/852//artifact/trunk/build/test/findbugs/newPatchFindbugsWarnings.html
        Console output: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/852//console

        This message is automatically generated.

        Show
        Hadoop QA added a comment - -1 overall. Here are the results of testing the latest attachment http://issues.apache.org/jira/secure/attachment/12508418/ZOOKEEPER-1336.patch against trunk revision 1221868. +1 @author. The patch does not contain any @author tags. -1 tests included. The patch doesn't appear to include any new or modified tests. Please justify why no new tests are needed for this patch. Also please list what manual steps were performed to verify this patch. +1 javadoc. The javadoc tool did not generate any warning messages. +1 javac. The applied patch does not increase the total number of javac compiler warnings. +1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings. +1 release audit. The applied patch does not increase the total number of release audit warnings. -1 core tests. The patch failed core unit tests. +1 contrib tests. The patch passed contrib unit tests. Test results: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/852//testReport/ Findbugs warnings: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/852//artifact/trunk/build/test/findbugs/newPatchFindbugsWarnings.html Console output: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/852//console This message is automatically generated.
        Hide
        Rakesh R added a comment -

        I feel, it would be good provides sample usage of multi and transaction in javadocs. Below are few suggestions:

        multi usage as method-level javadoc:

        * <P>
        * In the following example of multi-update, <code>zkper</code> represents
        * an active ZK client connection:  
        * <PRE>
        * Op createEphe1 = Op.create("/sample", new String ( "sample" ).getBytes (),
        *        org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode
        *       .fromFlag ( 2 ) );
        * Op createEphe2 = Op.create("/sample", new String ( "sample" ).getBytes (),
        *        org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode
        *        .fromFlag ( 2 ) );
        * List<Op> ops = new ArrayList<Op>();
        * ops.add(createEphe1);
        * ops.add(createEphe2);
        * zkper.multi(ops);
        * </PRE>
        

        Transaction usage as class-level javadoc:

        * <P>
        * In the following example of transaction, <code>zkper</code> represents
        * an active ZK client connection:  
        * <PRE>
        *   Transaction transaction = zkper.transaction();
        *   transaction.create("/sample", new String ( "sample" ).getBytes (),
        *        org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode
        *        .fromFlag ( 2 ) );
        *   transaction.create("/sample", new String ( "sample" ).getBytes (),
        *        org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode
        *        .fromFlag ( 2 ) );
        *   transaction.commit();
        * </PRE>
        

        Thanks,
        Rakesh

        Show
        Rakesh R added a comment - I feel, it would be good provides sample usage of multi and transaction in javadocs. Below are few suggestions: multi usage as method-level javadoc: * <P> * In the following example of multi-update, <code>zkper</code> represents * an active ZK client connection: * <PRE> * Op createEphe1 = Op.create("/sample", new String ( "sample" ).getBytes (), * org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode * .fromFlag ( 2 ) ); * Op createEphe2 = Op.create("/sample", new String ( "sample" ).getBytes (), * org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode * .fromFlag ( 2 ) ); * List<Op> ops = new ArrayList<Op>(); * ops.add(createEphe1); * ops.add(createEphe2); * zkper.multi(ops); * </PRE> Transaction usage as class-level javadoc: * <P> * In the following example of transaction, <code>zkper</code> represents * an active ZK client connection: * <PRE> * Transaction transaction = zkper.transaction(); * transaction.create("/sample", new String ( "sample" ).getBytes (), * org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode * .fromFlag ( 2 ) ); * transaction.create("/sample", new String ( "sample" ).getBytes (), * org.apache.zookeeper.ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode * .fromFlag ( 2 ) ); * transaction.commit(); * </PRE> Thanks, Rakesh
        Hide
        Patrick Hunt added a comment -

        Rakesh, I'd suggest either update this patch or create a new jira/patch with your contribution.

        Show
        Patrick Hunt added a comment - Rakesh, I'd suggest either update this patch or create a new jira/patch with your contribution.
        Hide
        Hadoop QA added a comment -

        -1 overall. Here are the results of testing the latest attachment
        http://issues.apache.org/jira/secure/attachment/12508418/ZOOKEEPER-1336.patch
        against trunk revision 1238176.

        +1 @author. The patch does not contain any @author tags.

        -1 tests included. The patch doesn't appear to include any new or modified tests.
        Please justify why no new tests are needed for this patch.
        Also please list what manual steps were performed to verify this patch.

        +1 javadoc. The javadoc tool did not generate any warning messages.

        +1 javac. The applied patch does not increase the total number of javac compiler warnings.

        +1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings.

        +1 release audit. The applied patch does not increase the total number of release audit warnings.

        +1 core tests. The patch passed core unit tests.

        +1 contrib tests. The patch passed contrib unit tests.

        Test results: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/944//testReport/
        Findbugs warnings: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/944//artifact/trunk/build/test/findbugs/newPatchFindbugsWarnings.html
        Console output: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/944//console

        This message is automatically generated.

        Show
        Hadoop QA added a comment - -1 overall. Here are the results of testing the latest attachment http://issues.apache.org/jira/secure/attachment/12508418/ZOOKEEPER-1336.patch against trunk revision 1238176. +1 @author. The patch does not contain any @author tags. -1 tests included. The patch doesn't appear to include any new or modified tests. Please justify why no new tests are needed for this patch. Also please list what manual steps were performed to verify this patch. +1 javadoc. The javadoc tool did not generate any warning messages. +1 javac. The applied patch does not increase the total number of javac compiler warnings. +1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings. +1 release audit. The applied patch does not increase the total number of release audit warnings. +1 core tests. The patch passed core unit tests. +1 contrib tests. The patch passed contrib unit tests. Test results: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/944//testReport/ Findbugs warnings: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/944//artifact/trunk/build/test/findbugs/newPatchFindbugsWarnings.html Console output: https://builds.apache.org/job/PreCommit-ZOOKEEPER-Build/944//console This message is automatically generated.
        Hide
        Mahadev konar added a comment -

        I just committed this. Thanks Pat.

        Show
        Mahadev konar added a comment - I just committed this. Thanks Pat.
        Hide
        Hudson added a comment -

        Integrated in ZooKeeper-trunk #1451 (See https://builds.apache.org/job/ZooKeeper-trunk/1451/)
        ZOOKEEPER-1336. javadoc for multi is confusing, references functionality that doesn't seem to exist. (phunt via mahadev)

        mahadev : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1240931
        Files :

        • /zookeeper/trunk/CHANGES.txt
        • /zookeeper/trunk/src/java/main/org/apache/zookeeper/KeeperException.java
        • /zookeeper/trunk/src/java/main/org/apache/zookeeper/Transaction.java
        • /zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java
        Show
        Hudson added a comment - Integrated in ZooKeeper-trunk #1451 (See https://builds.apache.org/job/ZooKeeper-trunk/1451/ ) ZOOKEEPER-1336 . javadoc for multi is confusing, references functionality that doesn't seem to exist. (phunt via mahadev) mahadev : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1240931 Files : /zookeeper/trunk/CHANGES.txt /zookeeper/trunk/src/java/main/org/apache/zookeeper/KeeperException.java /zookeeper/trunk/src/java/main/org/apache/zookeeper/Transaction.java /zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java

          People

          • Assignee:
            Patrick Hunt
            Reporter:
            Patrick Hunt
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development