From f967aa81a6d91df4a5fd0e06f88e190b758e482a Mon Sep 17 00:00:00 2001 From: Max Lambrecht Date: Thu, 18 Jun 2020 11:29:39 -0300 Subject: [PATCH] Fixing javadoc related warnings. Signed-off-by: Max Lambrecht --- build.gradle | 9 +++++++-- .../main/java/io/spiffe/bundle/jwtbundle/JwtBundle.java | 9 +++++++-- .../java/io/spiffe/bundle/jwtbundle/JwtBundleSet.java | 2 +- .../java/io/spiffe/bundle/x509bundle/X509Bundle.java | 6 +++++- .../java/io/spiffe/bundle/x509bundle/X509BundleSet.java | 2 +- .../src/main/java/io/spiffe/svid/jwtsvid/JwtSvid.java | 2 +- .../src/main/java/io/spiffe/svid/x509svid/X509Svid.java | 2 +- .../java/io/spiffe/svid/x509svid/X509SvidValidator.java | 1 + .../src/main/java/io/spiffe/workloadapi/Address.java | 2 +- .../java/io/spiffe/workloadapi/WorkloadApiClient.java | 3 +++ .../workloadapi/internal/ManagedChannelWrapper.java | 5 +++++ .../java/io/spiffe/workloadapi/retry/RetryHandler.java | 2 ++ 12 files changed, 35 insertions(+), 10 deletions(-) diff --git a/build.gradle b/build.gradle index 248b0eb..856a9c5 100644 --- a/build.gradle +++ b/build.gradle @@ -15,13 +15,18 @@ subprojects { apply plugin: 'java-library' + sourceCompatibility = JavaVersion.VERSION_1_8 + targetCompatibility = JavaVersion.VERSION_1_8 + java { withJavadocJar() withSourcesJar() } - sourceCompatibility = JavaVersion.VERSION_1_8 - targetCompatibility = JavaVersion.VERSION_1_8 + javadoc { + exclude "**/grpc/**" + exclude "**/internal/**" + } ext { jupiterVersion = '5.6.2' diff --git a/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundle.java b/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundle.java index 8080c3a..3fae98e 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundle.java +++ b/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundle.java @@ -114,7 +114,7 @@ public class JwtBundle implements BundleSource { } /** - * Returns the JWT authorities in the bundle, keyed by key ID. + * @return the JWT authorities in the bundle, keyed by key ID. */ public Map getJwtAuthorities() { return Collections.unmodifiableMap(jwtAuthorities); @@ -136,7 +136,10 @@ public class JwtBundle implements BundleSource { } /** - * Returns true if the bundle has a JWT authority with the given key ID. + * Looks for a JWT authority id in the JWT bundle. + * + * @param keyId id of a JWT Authority + * @return true if the bundle has a JWT authority with the given key ID. */ public boolean hasJwtAuthority(String keyId) { return jwtAuthorities.containsKey(keyId); @@ -158,6 +161,8 @@ public class JwtBundle implements BundleSource { /** * Removes the JWT authority identified by the key ID from the bundle. + * + * @param keyId The key id of the JWT authority to be removed */ public void removeJwtAuthority(String keyId) { jwtAuthorities.remove(keyId); diff --git a/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundleSet.java b/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundleSet.java index 6634f11..571fcca 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundleSet.java +++ b/java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundleSet.java @@ -56,7 +56,7 @@ public class JwtBundleSet implements BundleSource { } /** - * Returns the map of JWT bundles keyed by trust domain. + * @return the map of JWT bundles keyed by trust domain. */ public Map getBundles() { return Collections.unmodifiableMap(bundles); diff --git a/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java b/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java index 4edce7b..900767f 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java +++ b/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java @@ -107,7 +107,7 @@ public class X509Bundle implements BundleSource { } /** - * Returns the X.509 Authorities in the bundle. + * @return the X.509 Authorities in the bundle. */ public Set getX509Authorities() { return Collections.unmodifiableSet(x509Authorities); @@ -115,6 +115,8 @@ public class X509Bundle implements BundleSource { /** * Checks if the given X.509 authority exists in the bundle. + * @param x509Authority an X.509 certificate + * @return boolean true if the x509Authority is present in the X.509 bundle, false otherwise */ public boolean hasX509Authority(X509Certificate x509Authority) { return x509Authorities.contains(x509Authority); @@ -122,6 +124,7 @@ public class X509Bundle implements BundleSource { /** * Adds an X.509 authority to the bundle. + * @param x509Authority an X.509 certificate */ public void addX509Authority(X509Certificate x509Authority) { x509Authorities.add(x509Authority); @@ -129,6 +132,7 @@ public class X509Bundle implements BundleSource { /** * Removes an X.509 authority from the bundle. + * @param x509Authority an X.509 certificate */ public void removeX509Authority(X509Certificate x509Authority) { x509Authorities.remove(x509Authority); diff --git a/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509BundleSet.java b/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509BundleSet.java index e9e1c6b..564f3a8 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509BundleSet.java +++ b/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509BundleSet.java @@ -66,7 +66,7 @@ public class X509BundleSet implements BundleSource { } /** - * Returns the X.509 bundles of this X.509 Bundle Set. + * @return the X.509 bundles of this X.509 Bundle Set. */ public Map getBundles() { return Collections.unmodifiableMap(bundles); diff --git a/java-spiffe-core/src/main/java/io/spiffe/svid/jwtsvid/JwtSvid.java b/java-spiffe-core/src/main/java/io/spiffe/svid/jwtsvid/JwtSvid.java index 57298a1..b23376d 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/svid/jwtsvid/JwtSvid.java +++ b/java-spiffe-core/src/main/java/io/spiffe/svid/jwtsvid/JwtSvid.java @@ -165,7 +165,7 @@ public class JwtSvid { } /** - * Returns a copy of the expiration date time of the JWT SVID. + * @return a copy of the expiration date time of the JWT SVID. */ public Date getExpiry() { // defensive copying to prevent exposing a mutable object diff --git a/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java b/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java index 9ba0b78..540aa9d 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java +++ b/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java @@ -86,7 +86,7 @@ public class X509Svid implements X509SvidSource { } /** - * Returns the chain of certificates as an array of {@link X509Certificate} + * @return the chain of certificates as an array of {@link X509Certificate} */ public X509Certificate[] getChainArray() { return chain.toArray(new X509Certificate[0]); diff --git a/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509SvidValidator.java b/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509SvidValidator.java index f656bd2..1fd9d7b 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509SvidValidator.java +++ b/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509SvidValidator.java @@ -26,6 +26,7 @@ public class X509SvidValidator { * @param chain a list representing the chain of X.509 certificates to be validated * @param x509BundleSource a {@link BundleSource } to provide the authorities * @throws CertificateException is the chain cannot be verified with an authority from the X.509 bundle source + * @throws BundleNotFoundException if no X.509 bundle for the trust domain could be found in the X.509 bundle source * @throws NullPointerException if the given chain or 509BundleSource are null */ public static void verifyChain( diff --git a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/Address.java b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/Address.java index 11f5259..a742cf2 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/Address.java +++ b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/Address.java @@ -26,7 +26,7 @@ public class Address { private static final List VALID_SCHEMES = Arrays.asList(UNIX_SCHEME, TCP_SCHEME); /** - * Returns the default Workload API address hold by the system environment variable + * @return the default Workload API address hold by the system environment variable * defined by SOCKET_ENV_VARIABLE. */ public static String getDefaultAddress() { diff --git a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/WorkloadApiClient.java b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/WorkloadApiClient.java index b7fb64a..931a9db 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/WorkloadApiClient.java +++ b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/WorkloadApiClient.java @@ -66,6 +66,7 @@ public class WorkloadApiClient implements Closeable { * Creates a new Workload API client using the default socket endpoint address. * * @return a {@link WorkloadApiClient} + * @throws SocketEndpointAddressException if the Workload API socket endpoint address is not valid * @see Address#getDefaultAddress() */ public static WorkloadApiClient newClient() throws SocketEndpointAddressException { @@ -80,6 +81,7 @@ public class WorkloadApiClient implements Closeable { * * @param options {@link ClientOptions} * @return a {@link WorkloadApiClient} + * @throws SocketEndpointAddressException if the Workload API socket endpoint address is not valid */ public static WorkloadApiClient newClient(@NonNull ClientOptions options) throws SocketEndpointAddressException { String spiffeSocketPath; @@ -150,6 +152,7 @@ public class WorkloadApiClient implements Closeable { /** * One-shot blocking fetch call to get an X.509 context. * + * @return an instance of a {@link X509Context} containing the X.509 materials fetched from the Workload API * @throws X509ContextException if there is an error fetching or processing the X.509 context */ public X509Context fetchX509Context() throws X509ContextException { diff --git a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/internal/ManagedChannelWrapper.java b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/internal/ManagedChannelWrapper.java index d70ac2b..1334a35 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/internal/ManagedChannelWrapper.java +++ b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/internal/ManagedChannelWrapper.java @@ -18,6 +18,9 @@ public class ManagedChannelWrapper implements Closeable { /** * Constructor + * + * @param managedChannel an instance of {@link ManagedChannel} + * @param eventLoopGroup an instance of {@link EventLoopGroup} */ public ManagedChannelWrapper(ManagedChannel managedChannel, EventLoopGroup eventLoopGroup) { this.managedChannel = managedChannel; @@ -26,6 +29,8 @@ public class ManagedChannelWrapper implements Closeable { /** * Constructor + * + * @param managedChannel a {@link ManagedChannel} */ public ManagedChannelWrapper(ManagedChannel managedChannel) { this.managedChannel = managedChannel; diff --git a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/retry/RetryHandler.java b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/retry/RetryHandler.java index 2ade1b5..dcd0d6e 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/workloadapi/retry/RetryHandler.java +++ b/java-spiffe-core/src/main/java/io/spiffe/workloadapi/retry/RetryHandler.java @@ -23,6 +23,8 @@ public class RetryHandler { /** * Schedule to execute a Runnable, based on the backoff policy * Updates the next delay and retries count + * + * @param runnable the task to be scheduled for execution */ public void scheduleRetry(Runnable runnable) { if (backoffPolicy.didNotReachMaxRetries(retryCount)) {