Merge branch '940-req-res-builders' into 940-jwts-util-migration

Author: lhazlewood

api/src/main/java/io/jsonwebtoken/security/DecryptAeadRequest.java

@@ -30,6 +30,7 @@ public interface DecryptAeadRequest extends AeadRequest, IvSupplier, DigestSuppl
     /**
      * Named parameters (setters) used to configure an {@link AeadRequest AeadRequest} instance.
      *
+     * @param <M> the instance type returned for method chaining.
      * @since JJWT_RELEASE_VERSION
      */
     interface Params<M extends Params<M>> extends AeadRequest.Params<M> {

api/src/main/java/io/jsonwebtoken/security/DecryptionKeyRequest.java

@@ -67,6 +67,8 @@ interface Builder<K extends Key> extends Params<K, Builder<K>>, io.jsonwebtoken.
      * Returns a new {@link DecryptionKeyRequest.Builder} for creating immutable {@link DecryptionKeyRequest}s used to
      * get a JWE decryption key via {@link KeyAlgorithm#getDecryptionKey(DecryptionKeyRequest)}.
      *
+     * @param <K> the type of key used to obtain the JWE decryption key via
+     *            {@link KeyAlgorithm#getDecryptionKey(DecryptionKeyRequest)}.
      * @return a new {@link DecryptionKeyRequest.Builder} for creating immutable {@link DecryptionKeyRequest}s used to
      * get a JWE decryption key via {@link KeyAlgorithm#getDecryptionKey(DecryptionKeyRequest)}.
      * @since JJWT_RELEASE_VERSION

api/src/main/java/io/jsonwebtoken/security/HashAlgorithm.java

@@ -44,26 +44,79 @@
  */
 public interface HashAlgorithm extends DigestAlgorithm<Request<InputStream>, VerifyDigestRequest> {
 
+    /**
+     * Computes a digest of a request {@link Request#getPayload() payload} {@code InputStream} using configured
+     * parameters. This is a lambda-style method to execute the request in-line instead of requiring the caller to
+     * first use a {@link Request.Builder} to construct the request.
+     *
+     * <p>Callers are expected to {@link InputStream#close() close} or {@link InputStream#reset() reset} the request
+     * payload stream if necessary after calling this method.</p>
+     *
+     * @param c consumer supporting lambda-style specification of digest {@link Request.Params}.
+     * @return the computed digest of the request {@link Request#getPayload() payload}.
+     * @since JJWT_RELEASE_VERSION
+     */
     default byte[] digest(Consumer<Request.Params<InputStream, ?>> c) {
         Request.Builder<InputStream> b = Request.builder();
         c.accept(b);
         Request<InputStream> r = b.build();
         return digest(r);
     }
 
+    /**
+     * Computes a digest of the specified {@code is} input stream.
+     *
+     * <p>Callers are expected to {@link InputStream#close() close} or {@link InputStream#reset() reset} the payload
+     * stream if necessary after calling this method.</p>
+     *
+     * @param is the {@code InputStream} that will be consumed to compute the digest. Callers are expected to
+     *           {@link InputStream#close() close} or {@link InputStream#reset() reset} the payload stream if necessary
+     *           after calling this method.
+     * @return the computed digest of the specified {@code is} input stream.
+     * @since JJWT_RELEASE_VERSION
+     */
     default byte[] digest(InputStream is) {
         return digest(c -> c.payload(is));
     }
 
+    /**
+     * Returns {@code true} if the request's specified {@link VerifyDigestRequest#getDigest() digest} matches (equals)
+     * the algorithm's computed digest of the request {@link VerifyDigestRequest#getPayload() payload}, {@code false}
+     * otherwise. This is a lambda-style method to execute the request in-line instead of requiring the caller to first
+     * use a {@link VerifyDigestRequest.Builder} to construct the request.
+     *
+     * <p>Callers are expected to {@link InputStream#close() close} or {@link InputStream#reset() reset} the request
+     * payload stream if necessary after calling this method.</p>
+     *
+     * @param c consumer supporting lambda-style specification of {@link VerifyDigestRequest.Params}.
+     * @return {@code true} if the request's specified {@link VerifyDigestRequest#getDigest() digest} matches (equals)
+     * the algorithm's computed digest of the request {@link VerifyDigestRequest#getPayload() payload}, {@code false}
+     * otherwise.
+     * @since JJWT_RELEASE_VERSION
+     */
     default boolean verify(Consumer<VerifyDigestRequest.Params<?>> c) {
         VerifyDigestRequest.Builder b = VerifyDigestRequest.builder();
         c.accept(b);
         VerifyDigestRequest r = b.build();
         return verify(r);
     }
 
+    /**
+     * Returns {@code true} if the specified {@code digest} matches (equals) the algorithm's computed digest of the
+     * specified {@code is} input stream, {@code false} otherwise.
+     *
+     * <p>Callers are expected to {@link InputStream#close() close} or {@link InputStream#reset() reset} the payload
+     * stream if necessary after calling this method.</p>
+     *
+     * @param is     the {@code InputStream} that will be consumed to compute the digest. Callers are expected to
+     *               {@link InputStream#close() close} or {@link InputStream#reset() reset} the payload stream if
+     *               necessary after calling this method.
+     * @param digest the previously-computed digest to compare with the algorithm's computed digest of {@code is}.
+     * @return {@code true} if the specified {@code digest} matches (equals) the algorithm's computed digest of the
+     * specified {@code is} input stream, {@code false} otherwise.
+     * @since JJWT_RELEASE_VERSION
+     */
     default boolean verify(InputStream is, byte[] digest) {
         return verify(c -> c.payload(is).digest(digest));
     }
-
 }

api/src/main/java/io/jsonwebtoken/security/KeyRequest.java

@@ -136,6 +136,7 @@ interface Builder<K extends Key> extends Params<K, Builder<K>>, io.jsonwebtoken.
      * Returns a new {@link KeyRequest.Builder} for creating immutable {@link KeyRequest}s used to get a JWE
      * encryption key via {@link KeyAlgorithm#getEncryptionKey(KeyRequest)}.
      *
+     * @param <K> the type of {@link java.security.Key Key} used to obtain the JWE content encryption key.
      * @return a new {@link KeyRequest.Builder} for creating immutable {@link KeyRequest}s used to get a JWE
      * encryption key via {@link KeyAlgorithm#getEncryptionKey(KeyRequest)}.
      * @since JJWT_RELEASE_VERSION

impl/src/main/java/io/jsonwebtoken/impl/security/DefaultHashAlgorithm.java

@@ -15,13 +15,11 @@
  */
 package io.jsonwebtoken.impl.security;
 
-import io.jsonwebtoken.impl.lang.CheckedFunction;
 import io.jsonwebtoken.lang.Assert;
 import io.jsonwebtoken.security.HashAlgorithm;
 import io.jsonwebtoken.security.Request;
 import io.jsonwebtoken.security.VerifyDigestRequest;
 
-import java.io.IOException;
 import java.io.InputStream;
 import java.security.MessageDigest;
 import java.util.Locale;
@@ -38,17 +36,14 @@ public final class DefaultHashAlgorithm extends CryptoAlgorithm implements HashA
     public byte[] digest(final Request<InputStream> request) {
         Assert.notNull(request, "Request cannot be null.");
         final InputStream payload = Assert.notNull(request.getPayload(), "Request payload cannot be null.");
-        return jca(request).withMessageDigest(new CheckedFunction<MessageDigest, byte[]>() {
-            @Override
-            public byte[] apply(MessageDigest md) throws IOException {
-                byte[] buf = new byte[1024];
-                int len = 0;
-                while (len != -1) {
-                    len = payload.read(buf);
-                    if (len > 0) md.update(buf, 0, len);
-                }
-                return md.digest();
+        return jca(request).withMessageDigest(md -> {
+            byte[] buf = new byte[1024];
+            int len = 0;
+            while (len != -1) {
+                len = payload.read(buf);
+                if (len > 0) md.update(buf, 0, len);
             }
+            return md.digest();
         });
     }