ZOOKEEPER-2829: Interface usability / compatibility improvements through Java annotation.

This patch uses Apache Yetus audience annotations to label our publicly available interfaces and then generate our javadoc based on the annotations. The javadoc generated by this patch should be identical to our javadoc before with a few extra classes (that I think should have been included before anyway).

HostProvider
Record
StaticHostProvider
Transaction
ZKClientConfig

The "gotcha" with this patch is the way that java classes generated by jute are handled. There are four of these classes that need to be publicly documented: ACL, Id, Stat, StatPersisted (in addition to their superclass Record). I thought it would be safest to have the jute compiler always label these as "Public" and then we can filter out the ones we don't want in the javadoc ant task (by excluding the org.apache.zookeeper.server package and then pulling in the tools classes separately).

Author: Abraham Fine <abefine@cloudera.com>

Reviewers: Michael Han <hanm@apache.org>

Closes #316 from afine/ZOOKEEPER-2829

(cherry picked from commit 1bda92c268b989fcbb35ec1bb47eee6631a183e2)
Signed-off-by: Michael Han <hanm@apache.org>

build.xml

@@ -122,7 +122,9 @@ xmlns:cs="antlib:com.puppycrawl.tools.checkstyle.ant">
     <property name="ivy.jdiff.lib" value="${build.dir}/jdiff/lib"/>
     <property name="ivy.javacc.lib" value="${build.dir}/javacc/lib"/>
     <property name="ivysettings.xml" value="${basedir}/ivysettings.xml"/>
-    
+
+    <property name="audience-annotations.version" value="0.5.0" />
+
     <property name="mvnrepo" value="https://repo1.maven.org/maven2"/>
     <property name="tsk.org" value="/org/apache/maven/maven-ant-tasks/"/>
     <property name="ant-task.version" value="2.1.3"/>
@@ -272,7 +274,7 @@ xmlns:cs="antlib:com.puppycrawl.tools.checkstyle.ant">
     <target name="jute" depends="generate_jute_parser">
         <javac srcdir="${jute_javacc.dir}" destdir="${build.classes}" includeantruntime="false"
             target="${javac.target}" source="${javac.source}"
-            includes="org/apache/jute/**" debug="on" encoding="${build.encoding}">
+            includes="org/apache/jute/**" debug="on" encoding="${build.encoding}" classpath="${ivy.lib}/audience-annotations-${audience-annotations.version}.jar">
           <src path="${java.src.dir}" />
           <src path="${jute_javacc.dir}" />
         </javac>
@@ -343,9 +345,9 @@ xmlns:cs="antlib:com.puppycrawl.tools.checkstyle.ant">
         </java>
     </target>
     
-    <target name="build-generated" depends="compile_jute,version-info,process-template" >
+    <target name="build-generated" depends="compile_jute,version-info,process-template,ivy-retrieve" >
         <javac srcdir="${src_generated.dir}" destdir="${build.classes}" includeantruntime="false"
-            target="${javac.target}" source="${javac.source}" debug="on" encoding="${build.encoding}" />
+            target="${javac.target}" source="${javac.source}" debug="on" encoding="${build.encoding}" classpath="${ivy.lib}/audience-annotations-${audience-annotations.version}.jar" />
     </target>
     
     <target name="ivy-download" unless="ivy.jar.exists" depends="init">
@@ -525,24 +527,23 @@ xmlns:cs="antlib:com.puppycrawl.tools.checkstyle.ant">
          windowtitle="${Name} ${version} API"
          doctitle="${Name} ${version} API"
          bottom="Copyright &amp;copy; ${year} The Apache Software Foundation"
+         doclet="org.apache.yetus.audience.tools.IncludePublicAnnotationsStandardDoclet"
+         docletpath="${ivy.lib}/audience-annotations-${audience-annotations.version}.jar"
          >
-    	<fileset dir="${java.src.dir}">
-          <include name="org/apache/**/*Main.java"/>
-          <include name="org/apache/zookeeper/AsyncCallback.java"/>
-          <include name="org/apache/zookeeper/CreateMode.java"/>
-          <include name="org/apache/zookeeper/KeeperException.java"/>
-          <include name="org/apache/zookeeper/ServerAdminClient.java"/>
-          <include name="org/apache/zookeeper/Watcher.java"/>
-          <include name="org/apache/zookeeper/WatchedEvent.java"/>
-          <include name="org/apache/zookeeper/ZooDefs.java"/>
-          <include name="org/apache/zookeeper/ZooKeeper.java"/>
-          <include name="org/apache/zookeeper/admin/ZooKeeperAdmin.java"/>
+
+        <fileset dir="${java.src.dir}">
+          <include name="org/apache/zookeeper/server/quorum/QuorumPeerMain.java"/>
+          <include name="org/apache/zookeeper/server/ZooKeeperServerMain.java"/>
           <include name="org/apache/zookeeper/server/LogFormatter.java"/>
-          <include name="org/apache/zookeeper/server/SnapshotFormatter.java"/>
           <include name="org/apache/zookeeper/server/PurgeTxnLog.java"/>
-          <exclude name="org/apache/zookeeper/server/quorum/QuorumPacket"/>
-    	</fileset>
+          <include name="org/apache/zookeeper/server/SnapshotFormatter.java"/>
+        </fileset>
+    	<packageset dir="${java.src.dir}">
+          <include name="org/apache/**"/>
+          <exclude name="org/apache/zookeeper/server/**"/>
+    	</packageset>
     	<packageset dir="${src_generated.dir}">
+          <include name="org/apache/**"/>
           <exclude name="org/apache/zookeeper/proto"/>
           <exclude name="org/apache/zookeeper/txn"/>
           <exclude name="org/apache/zookeeper/version"/>

ivy.xml

@@ -51,6 +51,8 @@
     <dependency org="log4j" name="log4j" rev="1.2.17" transitive="false"/>
     <dependency org="jline" name="jline" rev="2.11" transitive="false" conf="optional->default"/>
 
+    <dependency org="org.apache.yetus" name="audience-annotations" rev="${audience-annotations.version}"/>
+
     <dependency org="io.netty" name="netty" conf="default" rev="3.10.5.Final">
       <artifact name="netty" type="jar" conf="default"/>
     </dependency>

src/java/main/org/apache/jute/Record.java

@@ -18,12 +18,15 @@
 
 package org.apache.jute;
 
+import org.apache.yetus.audience.InterfaceAudience;
+
 import java.io.IOException;
 
 /**
  * Interface that is implemented by generated classes.
  * 
  */
+@InterfaceAudience.Public
 public interface Record {
     public void serialize(OutputArchive archive, String tag)
         throws IOException;

src/java/main/org/apache/jute/compiler/JRecord.java

@@ -425,6 +425,8 @@ public class JRecord extends JCompType {
             jj.write("\n");
             jj.write("package " + getJavaPackage() + ";\n\n");
             jj.write("import org.apache.jute.*;\n");
+            jj.write("import org.apache.yetus.audience.InterfaceAudience;\n");
+            jj.write("@InterfaceAudience.Public\n");
             jj.write("public class " + getName() + " implements Record {\n");
             for (Iterator<JField> i = mFields.iterator(); i.hasNext(); ) {
                 JField jf = i.next();

src/java/main/org/apache/zookeeper/AsyncCallback.java

@@ -19,6 +19,7 @@ package org.apache.zookeeper;
 
 import java.util.List;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.data.ACL;
 import org.apache.zookeeper.data.Stat;
 
@@ -29,11 +30,13 @@ import org.apache.zookeeper.data.Stat;
  * <p/>
  * ZooKeeper provides asynchronous version as equivalent to synchronous APIs.
  */
+@InterfaceAudience.Public
 public interface AsyncCallback {
 
     /**
      * This callback is used to retrieve the stat of the node.
      */
+    @InterfaceAudience.Public
     interface StatCallback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.
@@ -68,6 +71,7 @@ public interface AsyncCallback {
     /**
      * This callback is used to retrieve the data and stat of the node.
      */
+    @InterfaceAudience.Public
     interface DataCallback extends AsyncCallback {
         /**
          * Process the result of asynchronous calls.
@@ -100,6 +104,7 @@ public interface AsyncCallback {
     /**
      * This callback is used to retrieve the ACL and stat of the node.
      */
+    @InterfaceAudience.Public
     interface ACLCallback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.
@@ -132,6 +137,7 @@ public interface AsyncCallback {
     /**
      * This callback is used to retrieve the children of the node.
      */
+    @InterfaceAudience.Public
     interface ChildrenCallback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.
@@ -162,6 +168,7 @@ public interface AsyncCallback {
     /**
      * This callback is used to retrieve the children and stat of the node.
      */
+    @InterfaceAudience.Public
     interface Children2Callback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.
@@ -183,6 +190,7 @@ public interface AsyncCallback {
     /**
      * This callback is used to retrieve the name and stat of the node.
      */
+    @InterfaceAudience.Public
     interface Create2Callback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.
@@ -205,6 +213,7 @@ public interface AsyncCallback {
     /**
      * This callback is used to retrieve the name of the node.
      */
+    @InterfaceAudience.Public
     interface StringCallback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.
@@ -248,6 +257,7 @@ public interface AsyncCallback {
      * org.apache.zookeeper.ZooKeeper#sync(String,
      * org.apache.zookeeper.AsyncCallback.VoidCallback, Object)}.
      */
+    @InterfaceAudience.Public
     interface VoidCallback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.
@@ -289,6 +299,7 @@ public interface AsyncCallback {
      * a single multi call.
      * See {@link org.apache.zookeeper.ZooKeeper#multi} for more information.
      */
+    @InterfaceAudience.Public
     interface MultiCallback extends AsyncCallback {
         /**
          * Process the result of the asynchronous call.

src/java/main/org/apache/zookeeper/CreateMode.java

@@ -17,12 +17,14 @@
  */
 package org.apache.zookeeper;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /***
  *  CreateMode value determines how the znode is created on ZooKeeper.
  */
+@InterfaceAudience.Public
 public enum CreateMode {
     
     /**

src/java/main/org/apache/zookeeper/KeeperException.java

@@ -18,6 +18,8 @@
 
 package org.apache.zookeeper;
 
+import org.apache.yetus.audience.InterfaceAudience;
+
 import java.util.ArrayList;
 import java.util.EnumSet;
 import java.util.HashMap;
@@ -25,6 +27,7 @@ import java.util.List;
 import java.util.Map;
 
 @SuppressWarnings("serial")
+@InterfaceAudience.Public
 public abstract class KeeperException extends Exception {
     /**
      * All multi-requests that result in an exception retain the results
@@ -172,6 +175,7 @@ public abstract class KeeperException extends Exception {
      * javadoc to include in the user API spec.
      */
     @Deprecated
+    @InterfaceAudience.Public
     public interface CodeDeprecated {
         /**
          * @deprecated deprecated in 3.1.0, use {@link Code#OK} instead
@@ -317,6 +321,7 @@ public abstract class KeeperException extends Exception {
      * constants. The old, deprecated, values are in "camel case" while the new
      * enum values are in all CAPS.
      */
+    @InterfaceAudience.Public
     public static enum Code implements CodeDeprecated {
         /** Everything is OK */
         OK (Ok),
@@ -546,6 +551,7 @@ public abstract class KeeperException extends Exception {
     /**
      *  @see Code#APIERROR
      */
+    @InterfaceAudience.Public
     public static class APIErrorException extends KeeperException {
         public APIErrorException() {
             super(Code.APIERROR);
@@ -555,6 +561,7 @@ public abstract class KeeperException extends Exception {
     /**
      *  @see Code#AUTHFAILED
      */
+    @InterfaceAudience.Public
     public static class AuthFailedException extends KeeperException {
         public AuthFailedException() {
             super(Code.AUTHFAILED);
@@ -564,6 +571,7 @@ public abstract class KeeperException extends Exception {
     /**
      *  @see Code#BADARGUMENTS
      */
+    @InterfaceAudience.Public
     public static class BadArgumentsException extends KeeperException {
         public BadArgumentsException() {
             super(Code.BADARGUMENTS);
@@ -576,6 +584,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#BADVERSION
      */
+    @InterfaceAudience.Public
     public static class BadVersionException extends KeeperException {
         public BadVersionException() {
             super(Code.BADVERSION);
@@ -588,6 +597,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#CONNECTIONLOSS
      */
+    @InterfaceAudience.Public
     public static class ConnectionLossException extends KeeperException {
         public ConnectionLossException() {
             super(Code.CONNECTIONLOSS);
@@ -597,6 +607,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#DATAINCONSISTENCY
      */
+    @InterfaceAudience.Public
     public static class DataInconsistencyException extends KeeperException {
         public DataInconsistencyException() {
             super(Code.DATAINCONSISTENCY);
@@ -606,6 +617,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#INVALIDACL
      */
+    @InterfaceAudience.Public
     public static class InvalidACLException extends KeeperException {
         public InvalidACLException() {
             super(Code.INVALIDACL);
@@ -618,6 +630,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#INVALIDCALLBACK
      */
+    @InterfaceAudience.Public
     public static class InvalidCallbackException extends KeeperException {
         public InvalidCallbackException() {
             super(Code.INVALIDCALLBACK);
@@ -627,6 +640,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#MARSHALLINGERROR
      */
+    @InterfaceAudience.Public
     public static class MarshallingErrorException extends KeeperException {
         public MarshallingErrorException() {
             super(Code.MARSHALLINGERROR);
@@ -636,6 +650,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NOAUTH
      */
+    @InterfaceAudience.Public
     public static class NoAuthException extends KeeperException {
         public NoAuthException() {
             super(Code.NOAUTH);
@@ -645,6 +660,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NEWCONFIGNOQUORUM
      */
+    @InterfaceAudience.Public
     public static class NewConfigNoQuorum extends KeeperException {
         public NewConfigNoQuorum() {
             super(Code.NEWCONFIGNOQUORUM);
@@ -654,6 +670,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#RECONFIGINPROGRESS
      */
+    @InterfaceAudience.Public
     public static class ReconfigInProgress extends KeeperException {
         public ReconfigInProgress() {
             super(Code.RECONFIGINPROGRESS);
@@ -663,6 +680,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NOCHILDRENFOREPHEMERALS
      */
+    @InterfaceAudience.Public
     public static class NoChildrenForEphemeralsException extends KeeperException {
         public NoChildrenForEphemeralsException() {
             super(Code.NOCHILDRENFOREPHEMERALS);
@@ -675,6 +693,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NODEEXISTS
      */
+    @InterfaceAudience.Public
     public static class NodeExistsException extends KeeperException {
         public NodeExistsException() {
             super(Code.NODEEXISTS);
@@ -687,6 +706,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NONODE
      */
+    @InterfaceAudience.Public
     public static class NoNodeException extends KeeperException {
         public NoNodeException() {
             super(Code.NONODE);
@@ -699,6 +719,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NOTEMPTY
      */
+    @InterfaceAudience.Public
     public static class NotEmptyException extends KeeperException {
         public NotEmptyException() {
             super(Code.NOTEMPTY);
@@ -711,6 +732,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#OPERATIONTIMEOUT
      */
+    @InterfaceAudience.Public
     public static class OperationTimeoutException extends KeeperException {
         public OperationTimeoutException() {
             super(Code.OPERATIONTIMEOUT);
@@ -720,6 +742,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#RUNTIMEINCONSISTENCY
      */
+    @InterfaceAudience.Public
     public static class RuntimeInconsistencyException extends KeeperException {
         public RuntimeInconsistencyException() {
             super(Code.RUNTIMEINCONSISTENCY);
@@ -729,6 +752,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#SESSIONEXPIRED
      */
+    @InterfaceAudience.Public
     public static class SessionExpiredException extends KeeperException {
         public SessionExpiredException() {
             super(Code.SESSIONEXPIRED);
@@ -738,6 +762,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#UNKNOWNSESSION
      */
+    @InterfaceAudience.Public
     public static class UnknownSessionException extends KeeperException {
         public UnknownSessionException() {
             super(Code.UNKNOWNSESSION);
@@ -747,6 +772,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#SESSIONMOVED
      */
+    @InterfaceAudience.Public
     public static class SessionMovedException extends KeeperException {
         public SessionMovedException() {
             super(Code.SESSIONMOVED);
@@ -756,6 +782,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NOTREADONLY
      */
+    @InterfaceAudience.Public
     public static class NotReadOnlyException extends KeeperException {
         public NotReadOnlyException() {
             super(Code.NOTREADONLY);
@@ -765,6 +792,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#EPHEMERALONLOCALSESSION
      */
+    @InterfaceAudience.Public
     public static class EphemeralOnLocalSessionException extends KeeperException {
         public EphemeralOnLocalSessionException() {
             super(Code.EPHEMERALONLOCALSESSION);
@@ -774,6 +802,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#SYSTEMERROR
      */
+    @InterfaceAudience.Public
     public static class SystemErrorException extends KeeperException {
         public SystemErrorException() {
             super(Code.SYSTEMERROR);
@@ -783,6 +812,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#UNIMPLEMENTED
      */
+    @InterfaceAudience.Public
     public static class UnimplementedException extends KeeperException {
         public UnimplementedException() {
             super(Code.UNIMPLEMENTED);
@@ -792,6 +822,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#NOWATCHER
      */
+    @InterfaceAudience.Public
     public static class NoWatcherException extends KeeperException {
         public NoWatcherException() {
             super(Code.NOWATCHER);
@@ -805,6 +836,7 @@ public abstract class KeeperException extends Exception {
     /**
      * @see Code#RECONFIGDISABLED
      */
+    @InterfaceAudience.Public
     public static class ReconfigDisabledException extends KeeperException {
         public ReconfigDisabledException() { super(Code.RECONFIGDISABLED); }
         public ReconfigDisabledException(String path) {

src/java/main/org/apache/zookeeper/ServerAdminClient.java

@@ -24,9 +24,12 @@ import java.io.OutputStream;
 import java.net.InetSocketAddress;
 import java.net.Socket;
 import java.nio.ByteBuffer;
+
+import org.apache.yetus.audience.InterfaceAudience;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InterfaceAudience.Public
 public class ServerAdminClient {
     private static final Logger LOG = LoggerFactory.getLogger(ServerAdminClient.class);
 

src/java/main/org/apache/zookeeper/Transaction.java

@@ -17,6 +17,7 @@
 
 package org.apache.zookeeper;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.AsyncCallback.MultiCallback;
 import org.apache.zookeeper.data.ACL;
 import java.util.ArrayList;
@@ -29,6 +30,7 @@ import java.util.List;
  * @since 3.4.0
  *
  */
+@InterfaceAudience.Public
 public class Transaction {
     private ZooKeeper zk;
     private List<Op> ops = new ArrayList<Op>();

src/java/main/org/apache/zookeeper/WatchedEvent.java

@@ -17,6 +17,7 @@
  */
 package org.apache.zookeeper;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.proto.WatcherEvent;
 import org.apache.zookeeper.Watcher.Event.EventType;
 import org.apache.zookeeper.Watcher.Event.KeeperState;
@@ -27,6 +28,7 @@ import org.apache.zookeeper.Watcher.Event.KeeperState;
  *  the current state of the ZooKeeper, and the path of the znode that
  *  was involved in the event.
  */
+@InterfaceAudience.Public
 public class WatchedEvent {
     final private KeeperState keeperState;
     final private EventType eventType;

src/java/main/org/apache/zookeeper/Watcher.java

@@ -18,6 +18,8 @@
 
 package org.apache.zookeeper;
 
+import org.apache.yetus.audience.InterfaceAudience;
+
 /**
  * This interface specifies the public interface an event handler class must
  * implement. A ZooKeeper client will get various events from the ZooKeeper
@@ -26,15 +28,18 @@ package org.apache.zookeeper;
  * is expected to be an instance of a class that implements Watcher interface.
  * 
  */
+@InterfaceAudience.Public
 public interface Watcher {
 
     /**
      * This interface defines the possible states an Event may represent
      */
+    @InterfaceAudience.Public
     public interface Event {
         /**
          * Enumeration of states the ZooKeeper may be at the event
          */
+        @InterfaceAudience.Public
         public enum KeeperState {
             /** Unused, this state is never generated by the server */
             @Deprecated
@@ -112,6 +117,7 @@ public interface Watcher {
         /**
          * Enumeration of types of events that may occur on the ZooKeeper
          */
+        @InterfaceAudience.Public
         public enum EventType {
             None (-1),
             NodeCreated (1),
@@ -152,6 +158,7 @@ public interface Watcher {
     /**
      * Enumeration of types of watchers
      */
+    @InterfaceAudience.Public
     public enum WatcherType {
         Children(1), Data(2), Any(3);
 

src/java/main/org/apache/zookeeper/ZooDefs.java

@@ -21,13 +21,16 @@ package org.apache.zookeeper;
 import java.util.ArrayList;
 import java.util.Collections;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.data.ACL;
 import org.apache.zookeeper.data.Id;
 
+@InterfaceAudience.Public
 public class ZooDefs {
    
    final public static String CONFIG_NODE = "/zookeeper/config";
-   
+
+   @InterfaceAudience.Public
     public interface OpCode {
         public final int notification = 0;
 
@@ -84,6 +87,7 @@ public class ZooDefs {
         public final int error = -1;
     }
 
+    @InterfaceAudience.Public
     public interface Perms {
         int READ = 1 << 0;
 
@@ -98,6 +102,7 @@ public class ZooDefs {
         int ALL = READ | WRITE | CREATE | DELETE | ADMIN;
     }
 
+    @InterfaceAudience.Public
     public interface Ids {
         /**
          * This Id represents anyone.

src/java/main/org/apache/zookeeper/ZooKeeper.java

@@ -19,6 +19,7 @@
 package org.apache.zookeeper;
 
 import org.apache.jute.Record;
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.AsyncCallback.ACLCallback;
 import org.apache.zookeeper.AsyncCallback.Children2Callback;
 import org.apache.zookeeper.AsyncCallback.ChildrenCallback;
@@ -137,6 +138,7 @@ import java.util.Set;
  * signature for backwards compatibility purposes.
 */
 @SuppressWarnings("try")
+@InterfaceAudience.Public
 public class ZooKeeper implements AutoCloseable {
 
     /**
@@ -616,6 +618,7 @@ public class ZooKeeper implements AutoCloseable {
         }
     }
 
+    @InterfaceAudience.Public
     public enum States {
         CONNECTING, ASSOCIATING, CONNECTED, CONNECTEDREADONLY,
         CLOSED, AUTH_FAILED, NOT_CONNECTED;

src/java/main/org/apache/zookeeper/ZooKeeperMain.java

@@ -34,6 +34,7 @@ import java.util.Map;
 import java.util.Map.Entry;
 import java.util.NoSuchElementException;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.cli.CliException;
 import org.apache.zookeeper.cli.CommandNotFoundException;
 import org.apache.zookeeper.cli.MalformedCommandException;
@@ -72,6 +73,7 @@ import org.apache.zookeeper.admin.ZooKeeperAdmin;
  * The command line client to ZooKeeper.
  *
  */
+@InterfaceAudience.Public
 public class ZooKeeperMain {
     private static final Logger LOG = LoggerFactory.getLogger(ZooKeeperMain.class);
     static final Map<String,String> commandMap = new HashMap<String,String>( );

src/java/main/org/apache/zookeeper/admin/ZooKeeperAdmin.java

@@ -21,6 +21,7 @@ package org.apache.zookeeper.admin;
 import java.io.IOException;
 import java.util.List;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.ZooKeeper;
 import org.apache.zookeeper.ZooDefs;
 import org.apache.zookeeper.Watcher;
@@ -49,6 +50,7 @@ import org.slf4j.LoggerFactory;
  */
 // See ZooKeeper.java for an explanation of why we need @SuppressWarnings("try")
 @SuppressWarnings("try")
+@InterfaceAudience.Public
 public class ZooKeeperAdmin extends ZooKeeper {
     private static final Logger LOG = LoggerFactory.getLogger(ZooKeeperAdmin.class);
 

src/java/main/org/apache/zookeeper/client/FourLetterWordMain.java

@@ -31,11 +31,13 @@ import javax.net.ssl.SSLContext;
 import javax.net.ssl.SSLSocket;
 import javax.net.ssl.SSLSocketFactory;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.common.X509Exception.SSLContextException;
 import org.apache.zookeeper.common.X509Util;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+@InterfaceAudience.Public
 public class FourLetterWordMain {
     //in milliseconds, socket should connect/read within this period otherwise SocketTimeoutException
     private static final int DEFAULT_SOCKET_TIMEOUT = 5000;

src/java/main/org/apache/zookeeper/client/HostProvider.java

@@ -18,6 +18,8 @@
 
 package org.apache.zookeeper.client;
 
+import org.apache.yetus.audience.InterfaceAudience;
+
 import java.net.InetSocketAddress;
 import java.net.UnknownHostException;
 import java.util.Collection;
@@ -41,6 +43,7 @@ import java.util.Collection;
  * * A HostProvider that re-resolves the InetSocketAddress after a timeout. 
  * * A HostProvider that prefers nearby hosts.
  */
+@InterfaceAudience.Public
 public interface HostProvider {
     public int size();
 

src/java/main/org/apache/zookeeper/client/StaticHostProvider.java

@@ -27,6 +27,7 @@ import java.util.Collections;
 import java.util.List;
 import java.util.Random;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -34,6 +35,7 @@ import org.slf4j.LoggerFactory;
  * Most simple HostProvider, resolves only on instantiation.
  * 
  */
+@InterfaceAudience.Public
 public final class StaticHostProvider implements HostProvider {
     private static final Logger LOG = LoggerFactory
             .getLogger(StaticHostProvider.class);

src/java/main/org/apache/zookeeper/client/ZKClientConfig.java

@@ -20,6 +20,7 @@ package org.apache.zookeeper.client;
 
 import java.io.File;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.ZooKeeper;
 import org.apache.zookeeper.common.ZKConfig;
 import org.apache.zookeeper.server.quorum.QuorumPeerConfig.ConfigException;
@@ -28,6 +29,7 @@ import org.apache.zookeeper.server.quorum.QuorumPeerConfig.ConfigException;
  * Handles client specific properties
  * @since 3.5.2
  */
+@InterfaceAudience.Public
 public class ZKClientConfig extends ZKConfig {
     public static final String ZK_SASL_CLIENT_USERNAME = "zookeeper.sasl.client.username";
     public static final String ZK_SASL_CLIENT_USERNAME_DEFAULT = "zookeeper";

src/java/main/org/apache/zookeeper/server/LogFormatter.java

@@ -28,6 +28,7 @@ import java.util.zip.Checksum;
 
 import org.apache.jute.BinaryInputArchive;
 import org.apache.jute.Record;
+import org.apache.yetus.audience.InterfaceAudience;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.apache.zookeeper.server.persistence.FileHeader;
@@ -35,6 +36,7 @@ import org.apache.zookeeper.server.persistence.FileTxnLog;
 import org.apache.zookeeper.server.util.SerializeUtils;
 import org.apache.zookeeper.txn.TxnHeader;
 
+@InterfaceAudience.Public
 public class LogFormatter {
     private static final Logger LOG = LoggerFactory.getLogger(LogFormatter.class);
 

src/java/main/org/apache/zookeeper/server/PurgeTxnLog.java

@@ -28,6 +28,7 @@ import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.server.persistence.FileTxnSnapLog;
 import org.apache.zookeeper.server.persistence.Util;
 import org.slf4j.Logger;
@@ -41,6 +42,7 @@ import org.slf4j.LoggerFactory;
  * files and snapdir files keeping the last "-n" snapshot files
  * and the corresponding logs.
  */
+@InterfaceAudience.Public
 public class PurgeTxnLog {
     private static final Logger LOG = LoggerFactory.getLogger(PurgeTxnLog.class);
 

src/java/main/org/apache/zookeeper/server/ServerConfig.java

@@ -22,6 +22,7 @@ import java.io.File;
 import java.net.InetSocketAddress;
 import java.util.Arrays;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.server.quorum.QuorumPeerConfig;
 import org.apache.zookeeper.server.quorum.QuorumPeerConfig.ConfigException;
 
@@ -31,6 +32,7 @@ import org.apache.zookeeper.server.quorum.QuorumPeerConfig.ConfigException;
  * We use this instead of Properties as it's typed.
  *
  */
+@InterfaceAudience.Public
 public class ServerConfig {
     ////
     //// If you update the configuration parameters be sure

src/java/main/org/apache/zookeeper/server/SnapshotFormatter.java

@@ -31,12 +31,14 @@ import java.util.zip.CheckedInputStream;
 
 import org.apache.jute.BinaryInputArchive;
 import org.apache.jute.InputArchive;
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.data.StatPersisted;
 import org.apache.zookeeper.server.persistence.FileSnap;
 
 /**
  * Dump a snapshot file to stdout.
  */
+@InterfaceAudience.Public
 public class SnapshotFormatter {
 
     /**

src/java/main/org/apache/zookeeper/server/ZooKeeperServerMain.java

@@ -24,6 +24,7 @@ import java.util.concurrent.TimeUnit;
 
 import javax.management.JMException;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.jmx.ManagedUtil;
 import org.apache.zookeeper.server.admin.AdminServer;
 import org.apache.zookeeper.server.admin.AdminServer.AdminServerException;
@@ -37,6 +38,7 @@ import org.slf4j.LoggerFactory;
 /**
  * This class starts and runs a standalone ZooKeeperServer.
  */
+@InterfaceAudience.Public
 public class ZooKeeperServerMain {
     private static final Logger LOG =
         LoggerFactory.getLogger(ZooKeeperServerMain.class);

src/java/main/org/apache/zookeeper/server/admin/AdminServer.java

@@ -18,6 +18,7 @@
 
 package org.apache.zookeeper.server.admin;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.server.ZooKeeperServer;
 
 /**
@@ -25,11 +26,13 @@ import org.apache.zookeeper.server.ZooKeeperServer;
  * functional implementation, JettyAdminServer. DummyAdminServer, which does
  * nothing, is used when we do not wish to run a server.
  */
+@InterfaceAudience.Public
 public interface AdminServer {
     public void start() throws AdminServerException;
     public void shutdown() throws AdminServerException;
     public void setZooKeeperServer(ZooKeeperServer zkServer);
 
+    @InterfaceAudience.Public
     public class AdminServerException extends Exception {
         private static final long serialVersionUID = 1L;
         public AdminServerException(String message, Throwable cause) {
@@ -39,4 +42,4 @@ public interface AdminServer {
             super(cause);
         }
     }
-}
+}

src/java/main/org/apache/zookeeper/server/quorum/QuorumPeerConfig.java

@@ -36,6 +36,7 @@ import java.util.Map;
 import java.util.Properties;
 import java.util.Map.Entry;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.apache.zookeeper.common.StringUtils;
 import org.apache.zookeeper.common.ZKConfig;
 import org.slf4j.Logger;
@@ -53,7 +54,7 @@ import org.apache.zookeeper.server.quorum.flexible.QuorumMaj;
 import org.apache.zookeeper.server.quorum.flexible.QuorumVerifier;
 import org.apache.zookeeper.server.util.VerifyingFileFactory;
 
-
+@InterfaceAudience.Public
 public class QuorumPeerConfig {
     private static final Logger LOG = LoggerFactory.getLogger(QuorumPeerConfig.class);
     private static final int UNSET_SERVERID = -1;

src/java/main/org/apache/zookeeper/server/quorum/QuorumPeerMain.java

@@ -21,6 +21,7 @@ import java.io.IOException;
 
 import javax.management.JMException;
 
+import org.apache.yetus.audience.InterfaceAudience;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.apache.zookeeper.jmx.ManagedUtil;
@@ -61,6 +62,7 @@ import org.apache.zookeeper.server.quorum.QuorumPeerConfig.ConfigException;
  * "myid" that contains the server id as an ASCII decimal value.
  *
  */
+@InterfaceAudience.Public
 public class QuorumPeerMain {
     private static final Logger LOG = LoggerFactory.getLogger(QuorumPeerMain.class);