From 6c999fe4b0181720c8e55be8388bd592196c8c87 Mon Sep 17 00:00:00 2001 From: Masatake Iwasaki Date: Tue, 12 Feb 2019 06:07:47 +0900 Subject: [PATCH] HADOOP-16098. Fix javadoc warnings in hadoop-aws. Contributed by Masatake Iwasaki. --- .../org/apache/hadoop/fs/s3a/InconsistentAmazonS3Client.java | 3 ++- .../main/java/org/apache/hadoop/fs/s3a/InternalConstants.java | 2 +- .../src/main/java/org/apache/hadoop/fs/s3a/S3AOpContext.java | 2 +- .../main/java/org/apache/hadoop/fs/s3a/S3AReadOpContext.java | 2 +- .../src/main/java/org/apache/hadoop/fs/s3a/S3AUtils.java | 1 + .../apache/hadoop/fs/s3a/TemporaryAWSCredentialsProvider.java | 2 ++ .../hadoop/fs/s3a/auth/AbstractSessionCredentialsProvider.java | 1 + .../apache/hadoop/fs/s3a/auth/MarshalledCredentialBinding.java | 3 +++ .../src/main/java/org/apache/hadoop/fs/s3a/auth/RoleModel.java | 2 ++ .../fs/s3a/auth/delegation/AbstractDelegationTokenBinding.java | 2 ++ .../fs/s3a/auth/delegation/AbstractS3ATokenIdentifier.java | 2 ++ .../hadoop/fs/s3a/auth/delegation/S3ADelegationTokens.java | 1 + .../hadoop/fs/s3a/auth/delegation/SessionTokenBinding.java | 3 +++ .../hadoop/fs/s3a/auth/delegation/SessionTokenIdentifier.java | 2 ++ .../org/apache/hadoop/fs/s3a/s3guard/DirListingMetadata.java | 1 + .../main/java/org/apache/hadoop/fs/s3a/s3guard/S3Guard.java | 2 ++ .../java/org/apache/hadoop/fs/s3a/s3guard/S3GuardTool.java | 3 +++ .../apache/hadoop/fs/s3a/select/InternalSelectConstants.java | 2 +- 18 files changed, 31 insertions(+), 5 deletions(-) diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InconsistentAmazonS3Client.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InconsistentAmazonS3Client.java index 2cd1aae5baf..2e77dc83a07 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InconsistentAmazonS3Client.java +++ b/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 { diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InternalConstants.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InternalConstants.java index bcf894f96be..509217f9036 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/InternalConstants.java +++ b/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. diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AOpContext.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AOpContext.java index 553d02fb761..4e0aac5138e 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AOpContext.java +++ b/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, diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AReadOpContext.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AReadOpContext.java index 73c219498f0..e49a7e9c947 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AReadOpContext.java +++ b/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; diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AUtils.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AUtils.java index 8428831bea0..f3235545c49 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AUtils.java +++ b/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) diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/TemporaryAWSCredentialsProvider.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/TemporaryAWSCredentialsProvider.java index f124bd0337c..9c71ab45862 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/TemporaryAWSCredentialsProvider.java +++ b/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, diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/AbstractSessionCredentialsProvider.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/AbstractSessionCredentialsProvider.java index 7822035ebe8..42c7d818734 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/AbstractSessionCredentialsProvider.java +++ b/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 { diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/MarshalledCredentialBinding.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/MarshalledCredentialBinding.java index 58c9c8035f2..120d0f0a5a8 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/MarshalledCredentialBinding.java +++ b/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. diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/RoleModel.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/RoleModel.java index 1082e93f5e0..24a5397a590 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/RoleModel.java +++ b/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 */ diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractDelegationTokenBinding.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractDelegationTokenBinding.java index 73660ea88b4..11427c4fee5 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractDelegationTokenBinding.java +++ b/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 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 convertTokenIdentifier( diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractS3ATokenIdentifier.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractS3ATokenIdentifier.java index 7c1c0e3891d..d8ee749c39d 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/AbstractS3ATokenIdentifier.java +++ b/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); diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/S3ADelegationTokens.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/S3ADelegationTokens.java index b8eeca13507..55915c02a1b 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/S3ADelegationTokens.java +++ b/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"); diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenBinding.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenBinding.java index 67933c7cb86..b81ffe3c587 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenBinding.java +++ b/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 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 getExpirationDateTime() { return expirationDateTime; @@ -409,6 +411,7 @@ public class SessionTokenBinding extends AbstractDelegationTokenBinding { /** * Token identifier bound to. + * @return token identifier. */ protected Optional getTokenIdentifier() { return tokenIdentifier; diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenIdentifier.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenIdentifier.java index 3928a0d454c..a45bba57b45 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/auth/delegation/SessionTokenIdentifier.java +++ b/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, diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/DirListingMetadata.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/DirListingMetadata.java index c6f826bbbff..88f24aa9841 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/DirListingMetadata.java +++ b/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 listing, boolean isAuthoritative, long lastUpdated) { diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3Guard.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3Guard.java index bb8d9b9c579..b462489f68e 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3Guard.java +++ b/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 diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3GuardTool.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3GuardTool.java index e4fd06436ae..fbc8bf5ef1c 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/s3guard/S3GuardTool.java +++ b/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 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 { diff --git a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/select/InternalSelectConstants.java b/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/select/InternalSelectConstants.java index ae3dc0816d6..912b73ba100 100644 --- a/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/select/InternalSelectConstants.java +++ b/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.