HADOOP-16098. Fix javadoc warnings in hadoop-aws. Contributed by Masatake Iwasaki.

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InconsistentAmazonS3Client.java

@@ -146,7 +146,8 @@ public class InconsistentAmazonS3Client extends AmazonS3Client {
   /**
    * A way for tests to patch in a different fault injection policy at runtime.
    * @param fs filesystem under test
-   *
+   * @param policy failure injection settings to set
+   * @throws Exception on failure
    */
   public static void setFailureInjectionPolicy(S3AFileSystem fs,
       FailureInjectionPolicy policy) throws Exception {

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InternalConstants.java

@@ -28,7 +28,7 @@ import org.apache.hadoop.classification.InterfaceStability;
 
 /**
  * Constants for internal use in the org.apache.hadoop.fs.s3a module itself.
- * Please don't refer to these outside of this module & its tests.
+ * Please don't refer to these outside of this module & its tests.
  * If you find you need to then either the code is doing something it
  * should not, or these constants need to be uprated to being
  * public and stable entries.

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AOpContext.java

@@ -75,7 +75,7 @@ public class S3AOpContext {
    * @param invoker invoker, which contains retry policy
    * @param stats optional stats object
    * @param instrumentation instrumentation to use
-   * @param dstFileStatus
+   * @param dstFileStatus file status from existence check
    */
   public S3AOpContext(boolean isS3GuardEnabled, Invoker invoker,
       @Nullable FileSystem.Statistics stats, S3AInstrumentation instrumentation,

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AReadOpContext.java

@@ -112,7 +112,7 @@ public class S3AReadOpContext extends S3AOpContext {
 
   /**
    * Get the readahead for this operation.
-   * @return a value >= 0
+   * @return a value {@literal >=} 0
    */
   public long getReadahead() {
     return readahead;

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AUtils.java

@@ -1226,6 +1226,7 @@ public final class S3AUtils {
    * @param conf The Hadoop configuration
    * @param bucket Optional bucket to use to look up per-bucket proxy secrets
    * @return new AWS client configuration
+   * @throws IOException problem creating AWS client configuration
    */
   public static ClientConfiguration createAwsConf(Configuration conf,
       String bucket)

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/TemporaryAWSCredentialsProvider.java

@@ -58,6 +58,7 @@ public class TemporaryAWSCredentialsProvider extends
   /**
    * Construct from just a configuration.
    * @param conf configuration.
+   * @throws IOException on any failure to load the credentials.
    */
   public TemporaryAWSCredentialsProvider(final Configuration conf)
       throws IOException {
@@ -69,6 +70,7 @@ public class TemporaryAWSCredentialsProvider extends
    * to a filesystem.
    * @param uri binding to a filesystem URI.
    * @param conf configuration.
+   * @throws IOException on any failure to load the credentials.
    */
   public TemporaryAWSCredentialsProvider(
       @Nullable final URI uri,

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/AbstractSessionCredentialsProvider.java

@@ -66,6 +66,7 @@ public abstract class AbstractSessionCredentialsProvider
   /**
    * Initialize the credentials by calling
    * {@link #createCredentials(Configuration)} with the current config.
+   * @throws IOException on any failure.
    */
   @Retries.OnceTranslated
   protected void init() throws IOException {

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/MarshalledCredentialBinding.java

@@ -66,6 +66,7 @@ public final class MarshalledCredentialBinding {
    * Create a set of marshalled credentials from a set of credentials
    * issued by an STS call.
    * @param credentials AWS-provided session credentials
+   * @return a set of marshalled credentials.
    */
   public static MarshalledCredentials fromSTSCredentials(
       final Credentials credentials) {
@@ -117,6 +118,7 @@ public final class MarshalledCredentialBinding {
    * Loads the credentials from the owning S3A FS, including
    * from Hadoop credential providers.
    * There is no validation.
+   * @param uri binding URI
    * @param conf configuration to load from
    * @return the component
    * @throws IOException on any load failure
@@ -176,6 +178,7 @@ public final class MarshalledCredentialBinding {
   /**
    * Request a set of credentials from an STS endpoint.
    * @param parentCredentials the parent credentials needed to talk to STS
+   * @param awsConf AWS client configuration
    * @param stsEndpoint an endpoint, use "" for none
    * @param stsRegion region; use if the endpoint isn't the AWS default.
    * @param duration duration of the credentials in seconds. Minimum value: 900.

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/RoleModel.java

@@ -197,6 +197,7 @@ public class RoleModel {
    * @param allow allow or deny
    * @param path path
    * @param isDirectory is this a directory?
+   * @param wildcards add a * to the tail of the key?
    * @param actions action
    * @return the formatted json statement
    */
@@ -220,6 +221,7 @@ public class RoleModel {
    * @param allow allow or deny
    * @param path path
    * @param isDirectory is this a directory?
+   * @param wildcards add a * to the tail of the key?
    * @param actions action
    * @return the formatted json statement
    */

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractDelegationTokenBinding.java

@@ -173,8 +173,10 @@ public abstract class AbstractDelegationTokenBinding extends AbstractDTService {
    * Verify that a token identifier is of a specific class.
    * This will reject subclasses (i.e. it is stricter than
    * {@code instanceof}, then cast it to that type.
+   * @param <T> type of S3A delegation ttoken identifier.
    * @param identifier identifier to validate
    * @param expectedClass class of the expected token identifier.
+   * @return token identifier.
    * @throws DelegationTokenIOException If the wrong class was found.
    */
   protected <T extends AbstractS3ATokenIdentifier> T convertTokenIdentifier(

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractS3ATokenIdentifier.java

@@ -140,6 +140,7 @@ public abstract class AbstractS3ATokenIdentifier
    * Build from a token.
    * This has been written for refresh operations;
    * if someone implements refresh it will be relevant.
+   * @param kind token kind.
    * @param token to to build from
    * @throws IOException failure to build the identifier.
    */
@@ -153,6 +154,7 @@ public abstract class AbstractS3ATokenIdentifier
 
   /**
    * For subclasses to use in their own empty-constructors.
+   * @param kind token kind.
    */
   protected AbstractS3ATokenIdentifier(final Text kind) {
     super(kind);

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/S3ADelegationTokens.java

@@ -146,6 +146,7 @@ public class S3ADelegationTokens extends AbstractDTService {
 
   /**
    * Instantiate.
+   * @throws IOException if login fails.
    */
   public S3ADelegationTokens() throws IOException {
     super("S3ADelegationTokens");

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenBinding.java

@@ -332,6 +332,7 @@ public class SessionTokenBinding extends AbstractDelegationTokenBinding {
   /**
    * Get the client to AWS STS.
    * @return the STS client, when successfully inited.
+   * @throws IOException any failure to bind to STS.
    */
   protected Optional<STSClientFactory.STSClient> prepareSTSClient()
       throws IOException {
@@ -397,6 +398,7 @@ public class SessionTokenBinding extends AbstractDelegationTokenBinding {
    * Expiration date time as passed in from source.
    * If unset, either we are unbound, or the token which came in does not
    * know its expiry.
+   * @return expiration data time.
    */
   protected Optional<OffsetDateTime> getExpirationDateTime() {
     return expirationDateTime;
@@ -409,6 +411,7 @@ public class SessionTokenBinding extends AbstractDelegationTokenBinding {
 
   /**
    * Token identifier bound to.
+   * @return token identifier.
    */
   protected Optional<SessionTokenIdentifier> getTokenIdentifier() {
     return tokenIdentifier;

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenIdentifier.java

@@ -94,6 +94,8 @@ public class SessionTokenIdentifier extends
    * Constructor.
    * @param kind token kind.
    * @param owner token owner
+   * @param renewer token renewer
+   * @param realUser real user running over proxy user
    * @param uri filesystem URI.
    */
   public SessionTokenIdentifier(final Text kind,

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/DirListingMetadata.java

@@ -67,6 +67,7 @@ public class DirListingMetadata extends ExpirableMetadata {
    * @param isAuthoritative true iff listing is the full contents of the
    *     directory, and the calling client reports that this may be cached as
    *     the full and authoritative listing of all files in the directory.
+   * @param lastUpdated last updated time on which expiration is based.
    */
   public DirListingMetadata(Path path, Collection<PathMetadata> listing,
       boolean isAuthoritative, long lastUpdated) {

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3Guard.java

@@ -189,6 +189,7 @@ public final class S3Guard {
    * @param backingStatuses Directory listing from the backing store.
    * @param dirMeta  Directory listing from MetadataStore.  May be null.
    * @param isAuthoritative State of authoritative mode
+   * @param timeProvider Time provider for testing.
    * @return Final result of directory listing.
    * @throws IOException if metadata store update failed
    */
@@ -279,6 +280,7 @@ public final class S3Guard {
    *              dir.
    * @param owner Hadoop user name.
    * @param authoritative Whether to mark new directories as authoritative.
+   * @param timeProvider Time provider for testing.
    */
   @Deprecated
   @Retries.OnceExceptionsSwallowed

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3GuardTool.java

@@ -145,6 +145,7 @@ public abstract class S3GuardTool extends Configured implements Tool {
 
   /**
    * Return sub-command name.
+   * @return sub-dommand name.
    */
   public abstract String getName();
 
@@ -250,6 +251,7 @@ public abstract class S3GuardTool extends Configured implements Tool {
 
   /**
    * Check if bucket or DDB table name is set.
+   * @param paths position arguments in which S3 path is provided.
    */
   protected void checkBucketNameOrDDBTableNameProvided(List<String> paths) {
     String s3Path = null;
@@ -270,6 +272,7 @@ public abstract class S3GuardTool extends Configured implements Tool {
    *
    * @param forceCreate override the auto-creation setting to true.
    * @return a initialized metadata store.
+   * @throws IOException on unsupported metadata store.
    */
   protected MetadataStore initMetadataStore(boolean forceCreate)
       throws IOException {

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/select/InternalSelectConstants.java

@@ -30,7 +30,7 @@ import static org.apache.hadoop.fs.s3a.select.SelectConstants.*;
 
 /**
  * Constants for internal use in the org.apache.hadoop.fs.s3a module itself.
- * Please don't refer to these outside of this module & its tests.
+ * Please don't refer to these outside of this module & its tests.
  * If you find you need to then either the code is doing something it
  * should not, or these constants need to be uprated to being
  * public and stable entries.