YARN-11385. Fix hadoop-yarn-server-common module Java Doc Errors. (#5182)

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/lib/ZKClient.java

@@ -40,18 +40,19 @@ public class ZKClient {
    * the zookeeper client library to 
    * talk to zookeeper 
    * @param string the host
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
    */
   public ZKClient(String string) throws IOException {
     zkClient = new ZooKeeper(string, 30000, new ZKWatcher());
   }
   
   /**
-   * register the service to a specific path
+   * register the service to a specific path.
+   *
    * @param path the path in zookeeper namespace to register to
    * @param data the data that is part of this registration
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
-   * @throws InterruptedException
+   * @throws InterruptedException if any thread has interrupted.
    */
   public void registerService(String path, String data) throws
     IOException, InterruptedException {
@@ -64,13 +65,14 @@ public void registerService(String path, String data) throws
   }
   
   /**
-   * unregister the service. 
+   * unregister the service.
+   *
    * @param path the path at which the service was registered
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
-   * @throws InterruptedException
+   * @throws InterruptedException if any thread has interrupted.
    */
   public void unregisterService(String path) throws IOException,
-    InterruptedException {
+      InterruptedException {
     try {
       zkClient.delete(path, -1);
     } catch(KeeperException ke) {
@@ -79,15 +81,16 @@ public void unregisterService(String path) throws IOException,
   }
 
   /**
-   * list the services registered under a path
+   * list the services registered under a path.
+   *
    * @param path the path under which services are
    * registered
    * @return the list of names of services registered
-   * @throws IOException 
+   * @throws IOException if there are I/O errors.
-   * @throws InterruptedException
+   * @throws InterruptedException if any thread has interrupted.
    */
   public List<String> listServices(String path) throws IOException, 
-    InterruptedException {
+      InterruptedException {
     List<String> children = null;
     try {
       children = zkClient.getChildren(path, false);
@@ -98,14 +101,15 @@ public List<String> listServices(String path) throws IOException,
   }
   
   /**
-   * get data published by the service at the registration address
+   * get data published by the service at the registration address.
+   *
    * @param path the path where the service is registered 
    * @return  the data of the registered service
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
-   * @throws InterruptedException
+   * @throws InterruptedException  if any thread has interrupted.
    */
   public String getServiceData(String path) throws IOException,
-    InterruptedException {
+      InterruptedException {
     String data;
     try {
       Stat stat = new Stat();

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/lib/package-info.java

@@ -15,7 +15,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Private
+
-package org.apache.hadoop.yarn.lib;
+/**
-import org.apache.hadoop.classification.InterfaceAudience;
+ * This package contains zkClient related classes.
+ */
+@Private
+package org.apache.hadoop.yarn.lib;
+import org.apache.hadoop.classification.InterfaceAudience.Private;
 

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/AMHeartbeatRequestHandler.java

@@ -153,6 +153,7 @@ public void resetLastResponseId() {
 
   /**
    * Set the UGI for RM connection.
+   * @param ugi UserGroupInformation.
    */
   public void setUGI(UserGroupInformation ugi) {
     this.userUgi = ugi;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/api/SCMUploaderProtocol.java

@@ -53,8 +53,8 @@ public interface SCMUploaderProtocol {
    *          to the shared cache
    * @return response indicating if the newly uploaded resource should be
    *         deleted
-   * @throws YarnException
+   * @throws YarnException exceptions from yarn servers.
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
    */
   public SCMUploaderNotifyResponse
       notify(SCMUploaderNotifyRequest request)
@@ -73,8 +73,8 @@ public interface SCMUploaderProtocol {
    *
    * @param request whether the resource can be uploaded to the shared cache
    * @return response indicating if resource can be uploaded to the shared cache
-   * @throws YarnException
+   * @throws YarnException exceptions from yarn servers.
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
    */
   public SCMUploaderCanUploadResponse
       canUpload(SCMUploaderCanUploadRequest request)

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/api/ServerRMProxy.java

@@ -49,7 +49,7 @@ private ServerRMProxy() {
    * @param protocol Server protocol for which proxy is being requested.
    * @param <T> Type of proxy.
    * @return Proxy to the ResourceManager for the specified server protocol.
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
    */
   public static <T> T createRMProxy(final Configuration configuration,
       final Class<T> protocol) throws IOException {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/api/protocolrecords/NMContainerStatus.java

@@ -120,14 +120,18 @@ public static NMContainerStatus newInstance(ContainerId containerId,
   public abstract void setPriority(Priority priority);
 
   /**
-   * Get the time when the container is created
+   * Get the time when the container is created.
+   *
+   * @return CreationTime.
    */
   public abstract long getCreationTime();
 
   public abstract void setCreationTime(long creationTime);
   
   /**
-   * Get the node-label-expression in the original ResourceRequest
+   * Get the node-label-expression in the original ResourceRequest.
+   *
+   * @return NodeLabelExpression.
    */
   public abstract String getNodeLabelExpression();
 
@@ -167,6 +171,7 @@ public void setExecutionType(ExecutionType executionType) { }
 
   /**
    * Get and set the Allocation tags associated with the container.
+   * @return Allocation tags.
    */
   public Set<String> getAllocationTags() {
     return Collections.emptySet();

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/api/protocolrecords/RemoteNode.java

@@ -148,7 +148,7 @@ public static RemoteNode newInstance(NodeId nodeId, String httpAddress,
 
   /**
    * Set Node Partition.
-   * @param nodePartition
+   * @param nodePartition node Partition.
    */
   @Private
   @Unstable

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/federation/policies/amrmproxy/LocalityMulticastAMRMProxyPolicy.java

@@ -290,6 +290,10 @@ public Map<SubClusterId, List<ResourceRequest>> splitResourceRequests(
 
   /**
    * For unit test to override.
+   *
+   * @param bookKeeper bookKeeper
+   * @param allocationId allocationId.
+   * @return SubClusterId.
    */
   protected SubClusterId getSubClusterForUnResolvedRequest(
       AllocationBookkeeper bookKeeper, long allocationId) {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/federation/utils/FederationRegistryClient.java

@@ -111,6 +111,7 @@ public synchronized void cleanAllApplications() {
   /**
    * Write/update the UAM token for an application and a sub-cluster.
    *
+   * @param appId ApplicationId.
    * @param subClusterId sub-cluster id of the token
    * @param token the UAM of the application
    * @return whether the amrmToken is added or updated to a new value

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/scheduler/ResourceRequestSet.java

@@ -71,7 +71,7 @@ public ResourceRequestSet(ResourceRequestSet other) {
    * with the same resource name, override it and update accordingly.
    *
    * @param ask the new {@link ResourceRequest}
-   * @throws YarnException
+   * @throws YarnException indicates exceptions from yarn servers.
    */
   public void addAndOverrideRR(ResourceRequest ask) throws YarnException {
     if (!this.key.equals(new ResourceRequestSetKey(ask))) {
@@ -102,7 +102,7 @@ public void addAndOverrideRR(ResourceRequest ask) throws YarnException {
    * Merge a requestSet into this one.
    *
    * @param requestSet the requestSet to merge
-   * @throws YarnException
+   * @throws YarnException indicates exceptions from yarn servers.
    */
   public void addAndOverrideRRSet(ResourceRequestSet requestSet)
       throws YarnException {
@@ -149,7 +149,7 @@ public int getNumContainers() {
    * Force set the # of containers to ask for this requestSet to a given value.
    *
    * @param newValue the new # of containers value
-   * @throws YarnException
+   * @throws YarnException indicates exceptions from yarn servers.
    */
   public void setNumContainers(int newValue) throws YarnException {
     if (this.numContainers == 0) {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/security/BaseNMTokenSecretManager.java

@@ -111,6 +111,11 @@ public NMTokenIdentifier createIdentifier() {
   
   /**
    * Helper function for creating NMTokens.
+   *
+   * @param applicationAttemptId application AttemptId.
+   * @param nodeId node Id.
+   * @param applicationSubmitter application Submitter.
+   * @return NMToken.
    */
   public Token createNMToken(ApplicationAttemptId applicationAttemptId,
       NodeId nodeId, String applicationSubmitter) {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/service/package-info.java

@@ -19,9 +19,8 @@
  * Package org.apache.hadoop.yarn.server.service contains service related
  * classes.
  */
-@InterfaceAudience.Private @InterfaceStability.Unstable
+@Private
-
+@Unstable
 package org.apache.hadoop.yarn.server.service;
-
+import org.apache.hadoop.classification.InterfaceAudience.Private;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
-import org.apache.hadoop.classification.InterfaceStability;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/timeline/security/package-info.java

@@ -21,6 +21,6 @@
  * to timeline authentication filters and abstract delegation token service for
  * ATSv1 and ATSv2.
  */
-@InterfaceAudience.Private
+@Private
 package org.apache.hadoop.yarn.server.timeline.security;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Private;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/util/timeline/package-info.java

@@ -20,6 +20,6 @@
  * Package org.apache.hadoop.server.util.timeline contains utility classes used
  * by ATSv1 and ATSv2 on the server side.
  */
-@InterfaceAudience.Private
+@Private
 package org.apache.hadoop.yarn.server.util.timeline;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Private;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/utils/LeveldbIterator.java

@@ -41,21 +41,28 @@ public class LeveldbIterator implements Iterator<Map.Entry<byte[], byte[]>>,
   private DBIterator iter;
 
   /**
-   * Create an iterator for the specified database
+   * Create an iterator for the specified database.
+   *
+   * @param db database.
    */
   public LeveldbIterator(DB db) {
     iter = db.iterator();
   }
 
   /**
-   * Create an iterator for the specified database
+   * Create an iterator for the specified database.
+   *
+   * @param db db.
+   * @param options ReadOptions.
    */
   public LeveldbIterator(DB db, ReadOptions options) {
     iter = db.iterator(options);
   }
 
   /**
-   * Create an iterator using the specified underlying DBIterator
+   * Create an iterator using the specified underlying DBIterator.
+   *
+   * @param iter DB Iterator.
    */
   public LeveldbIterator(DBIterator iter) {
     this.iter = iter;
@@ -64,6 +71,9 @@ public LeveldbIterator(DBIterator iter) {
   /**
    * Repositions the iterator so the key of the next BlockElement
    * returned greater than or equal to the specified targetKey.
+   *
+   * @param key key of the next BlockElement.
+   * @throws DBException db Exception.
    */
   public void seek(byte[] key) throws DBException {
     try {
@@ -116,6 +126,9 @@ public boolean hasNext() throws DBException {
 
   /**
    * Returns the next element in the iteration.
+   *
+   * @return the next element in the iteration.
+   * @throws DBException DB Exception.
    */
   @Override
   public Map.Entry<byte[], byte[]> next() throws DBException {
@@ -131,6 +144,9 @@ public Map.Entry<byte[], byte[]> next() throws DBException {
   /**
    * Returns the next element in the iteration, without advancing the
    * iteration.
+   *
+   * @return the next element in the iteration.
+   * @throws DBException db Exception.
    */
   public Map.Entry<byte[], byte[]> peekNext() throws DBException {
     try {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/utils/YarnServerSecurityUtils.java

@@ -56,7 +56,7 @@ private YarnServerSecurityUtils() {
    * current application.
    *
    * @return the AMRMTokenIdentifier instance for the current user
-   * @throws YarnException
+   * @throws YarnException exceptions from yarn servers.
    */
   public static AMRMTokenIdentifier authorizeRequest() throws YarnException {
 
@@ -137,9 +137,9 @@ public static void updateAMRMToken(
    * Parses the container launch context and returns a Credential instance that
    * contains all the tokens from the launch context.
    *
-   * @param launchContext
+   * @param launchContext ContainerLaunchContext.
    * @return the credential instance
-   * @throws IOException
+   * @throws IOException if there are I/O errors.
    */
   public static Credentials parseCredentials(
       ContainerLaunchContext launchContext) throws IOException {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/volume/csi/package-info.java

@@ -19,9 +19,8 @@
 /**
  * This package contains common volume related classes.
  */
-@InterfaceAudience.Private
+@Private
-@InterfaceStability.Unstable
+@Unstable
 package org.apache.hadoop.yarn.server.volume.csi;
-
+import org.apache.hadoop.classification.InterfaceAudience.Private;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
-import org.apache.hadoop.classification.InterfaceStability;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/webapp/LogServlet.java

@@ -187,7 +187,10 @@ private void validateUserInput(ApplicationId applicationId,
    * Returns the user qualified path name of the remote log directory for
    * each pre-configured log aggregation file controller.
    *
+   * @param user remoteUser.
+   * @param applicationId applicationId.
    * @return {@link Response} object containing remote log dir path names
+   * @throws IOException if there are I/O errors.
    */
   public Response getRemoteLogDirPath(String user, String applicationId)
       throws IOException {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/webapp/LogWebService.java

@@ -138,6 +138,9 @@ private void initForReadableEndpoints(HttpServletResponse response) {
    * @param containerIdStr     The container ID
    * @param nmId               The Node Manager NodeId
    * @param redirectedFromNode Whether this is a redirected request from NM
+   * @param clusterId          clusterId the id of the cluster
+   * @param manualRedirection  whether to return a response with a Location
+   *                           instead of an automatic redirection
    * @return The log file's name and current file size
    */
   @GET
@@ -242,6 +245,9 @@ public BasicAppInfo getApp(HttpServletRequest req, String appId,
    * @param size               the size of the log file
    * @param nmId               The Node Manager NodeId
    * @param redirectedFromNode Whether this is the redirect request from NM
+   * @param clusterId          the id of the cluster
+   * @param manualRedirection  whether to return a response with a Location
+   *                           instead of an automatic redirection
    * @return The contents of the container's log file
    */
   @GET

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-common/src/main/java/org/apache/hadoop/yarn/server/webapp/WrappedLogMetaRequest.java

@@ -155,6 +155,7 @@ public ContainerId getContainerId() {
    *
    * @return list of {@link ContainerLogMeta} objects that belong
    *         to the application, attempt or container
+   * @throws IOException if there are I/O errors.
    */
   public List<ContainerLogMeta> getContainerLogMetas() throws IOException {
     ApplicationId applicationId = ApplicationId.fromString(getAppId());