PR #917

* Ensured `NestedCollection`s do not need their `.and()` method called to apply collection changes. Instead, changes are applied immediately as they occur (via `.add`, `.remove`, etc), and `.and()` is now purely for returning to the parent builder if necessary/desired.
* Updated associated JavaDoc with code examples to make the `.and()` method's purpose a little clearer.
* Updated CHANGELOG.md

Closes #916

Author: lhazlewood

CHANGELOG.md

@@ -1,5 +1,31 @@
 ## Release Notes
 
+### 0.12.5
+
+This patch release:
+
+* Ensures that builders' `NestedCollection` changes are applied to the collection immediately as mutation methods are called, no longer
+  requiring application developers to call `.and()` to 'commit' or apply a change.  For example, prior to this release,
+  the following code did not apply changes:
+  ```java
+  JwtBuilder builder = Jwts.builder();
+  builder.audience().add("an-audience"); // no .and() call
+  builder.compact(); // would not keep 'an-audience'
+  ```
+  Now this code works as expected and all other `NestedCollection` instances like it apply changes immediately (e.g. when calling
+  `.add(value)`).
+  
+  However, standard fluent builder chains are still recommended for readability when feasible, e.g.
+  
+  ```java
+  Jwts.builder()
+      .audience().add("an-audience").and() // allows fluent chaining
+      .subject("Joe")
+      // etc...
+      .compact()
+  ```
+  See [Issue 916](https://github.com/jwtk/jjwt/issues/916).
+
 ### 0.12.4
 
 This patch release includes various changes listed below.

README.md

@@ -993,7 +993,7 @@ String jws = Jwts.builder()
 
     .issuer("me")
     .subject("Bob")
-    .audience("you")
+    .audience().add("you").and()    
     .expiration(expiration) //a java.util.Date
     .notBefore(notBefore) //a java.util.Date 
     .issuedAt(new Date()) // for example, now

api/src/main/java/io/jsonwebtoken/ClaimsMutator.java

@@ -96,6 +96,17 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3"><code>aud</code></a> (audience) Claim
      * set, quietly ignoring any null, empty, whitespace-only, or existing value already in the set.
      *
+     * <p>When finished, the {@code audience} collection's {@link AudienceCollection#and() and()} method may be used
+     * to continue configuration. For example:</p>
+     * <blockquote><pre>
+     *  Jwts.builder() // or Jwts.claims()
+     *
+     *     .audience().add("anAudience")<b>.and() // return parent</b>
+     *
+     *  .subject("Joe") // resume configuration...
+     *  // etc...
+     * </pre></blockquote>
+     *
      * @return the {@link AudienceCollection AudienceCollection} to use for {@code aud} configuration.
      * @see AudienceCollection AudienceCollection
      * @see AudienceCollection#single(String) AudienceCollection.single(String)
@@ -221,6 +232,16 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * A {@code NestedCollection} for setting {@link #audience()} values that also allows overriding the collection
      * to be a {@link #single(String) single string value} for legacy JWT recipients if necessary.
      *
+     * <p>Because this interface extends {@link NestedCollection}, the {@link #and()} method may be used to continue
+     * parent configuration. For example:</p>
+     * <blockquote><pre>
+     *  Jwts.builder() // or Jwts.claims()
+     *
+     *     .audience().add("anAudience")<b>.and() // return parent</b>
+     *
+     *  .subject("Joe") // resume parent configuration...
+     *  // etc...</pre></blockquote>
+     *
      * @param <P> the type of ClaimsMutator to return for method chaining.
      * @see #single(String)
      * @since 0.12.0

api/src/main/java/io/jsonwebtoken/JwtParserBuilder.java

@@ -101,12 +101,25 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * the parser encounters a Protected JWT that {@link ProtectedHeader#getCritical() requires} extensions, and
      * those extensions' header names are not specified via this method, the parser will reject that JWT.
      *
+     * <p>The collection's {@link Conjunctor#and() and()} method returns to the builder for continued parser
+     * configuration, for example:</p>
+     * <blockquote><pre>
+     * parserBuilder.critical().add("headerName")<b>.{@link Conjunctor#and() and()} // etc...</b></pre></blockquote>
+     *
      * <p><b>Extension Behavior</b></p>
      *
      * <p>The {@code critical} collection only identifies header parameter names that are used in extensions supported
      * by the application. <b>Application developers, <em>not JJWT</em>, MUST perform the associated extension behavior
      * using the parsed JWT</b>.</p>
      *
+     * <p><b>Continued Parser Configuration</b></p>
+     * <p>When finished, use the collection's
+     * {@link Conjunctor#and() and()} method to continue parser configuration, for example:
+     * <blockquote><pre>
+     * Jwts.parser()
+     *     .critical().add("headerName").<b>{@link Conjunctor#and() and()} // return parent</b>
+     * // resume parser configuration...</pre></blockquote>
+     *
      * @return the {@link NestedCollection} to use for {@code crit} configuration.
      * @see ProtectedHeader#getCritical()
      * @since 0.12.0
@@ -557,7 +570,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * <p>The collection's {@link Conjunctor#and() and()} method returns to the builder for continued parser
      * configuration, for example:</p>
      * <blockquote><pre>
-     * parserBuilder.enc().add(anAeadAlgorithm).{@link Conjunctor#and() and()} // etc...</pre></blockquote>
+     * parserBuilder.enc().add(anAeadAlgorithm)<b>.{@link Conjunctor#and() and()} // etc...</b></pre></blockquote>
      *
      * <p><b>Standard Algorithms and Overrides</b></p>
      *
@@ -597,7 +610,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * <p>The collection's {@link Conjunctor#and() and()} method returns to the builder for continued parser
      * configuration, for example:</p>
      * <blockquote><pre>
-     * parserBuilder.key().add(aKeyAlgorithm).{@link Conjunctor#and() and()} // etc...</pre></blockquote>
+     * parserBuilder.key().add(aKeyAlgorithm)<b>.{@link Conjunctor#and() and()} // etc...</b></pre></blockquote>
      *
      * <p><b>Standard Algorithms and Overrides</b></p>
      *
@@ -639,7 +652,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * <p>The collection's {@link Conjunctor#and() and()} method returns to the builder for continued parser
      * configuration, for example:</p>
      * <blockquote><pre>
-     * parserBuilder.sig().add(aSignatureAlgorithm).{@link Conjunctor#and() and()} // etc...</pre></blockquote>
+     * parserBuilder.sig().add(aSignatureAlgorithm)<b>.{@link Conjunctor#and() and()} // etc...</b></pre></blockquote>
      *
      * <p><b>Standard Algorithms and Overrides</b></p>
      *
@@ -680,7 +693,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * <p>The collection's {@link Conjunctor#and() and()} method returns to the builder for continued parser
      * configuration, for example:</p>
      * <blockquote><pre>
-     * parserBuilder.zip().add(aCompressionAlgorithm).{@link Conjunctor#and() and()} // etc...</pre></blockquote>
+     * parserBuilder.zip().add(aCompressionAlgorithm)<b>.{@link Conjunctor#and() and()} // etc...</b></pre></blockquote>
      *
      * <p><b>Standard Algorithms and Overrides</b></p>
      *

api/src/main/java/io/jsonwebtoken/ProtectedHeaderMutator.java

@@ -33,9 +33,11 @@ public interface ProtectedHeaderMutator<T extends ProtectedHeaderMutator<T>> ext
     /**
      * Configures names of header parameters used by JWT or JWA specification extensions that <em>MUST</em> be
      * understood and supported by the JWT recipient. When finished, use the collection's
-     * {@link Conjunctor#and() and()} method to return to the header builder, for example:
+     * {@link Conjunctor#and() and()} method to continue header configuration, for example:
      * <blockquote><pre>
-     * builder.critical().add("headerName").{@link Conjunctor#and() and()} // etc...</pre></blockquote>
+     * headerBuilder
+     *     .critical().add("headerName").<b>{@link Conjunctor#and() and()} // return parent</b>
+     * // resume header configuration...</pre></blockquote>
      *
      * @return the {@link NestedCollection} to use for {@code crit} configuration.
      * @see <a href="https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.11">JWS <code>crit</code> (Critical) Header Parameter</a>

api/src/main/java/io/jsonwebtoken/lang/NestedCollection.java

@@ -17,7 +17,12 @@
 
 /**
  * A {@link CollectionMutator} that can return access to its parent via the {@link Conjunctor#and() and()} method for
- * continued configuration.
+ * continued configuration.  For example:
+ * <blockquote><pre>
+ * builder
+ *     .aNestedCollection()// etc...
+ *     <b>.and() // return parent</b>
+ * // resume parent configuration...</pre></blockquote>
  *
  * @param <E> the type of elements in the collection
  * @param <P> the parent to return

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

@@ -109,9 +109,9 @@ public interface JwkBuilder<K extends Key, J extends Jwk<K>, T extends JwkBuilde
      * the key is intended to be used. When finished, use the collection's {@link Conjunctor#and() and()} method to
      * return to the JWK builder, for example:
      * <blockquote><pre>
-     * jwkBuilder.operations().add(aKeyOperation).{@link Conjunctor#and() and()} // etc...</pre></blockquote>
+     * jwkBuilder.operations().add(aKeyOperation)<b>.{@link Conjunctor#and() and()} // etc...</b></pre></blockquote>
      *
-     * <p>The {@code and()} method will throw an {@link IllegalArgumentException} if any of the specified
+     * <p>The {@code add()} method(s) will throw an {@link IllegalArgumentException} if any of the specified
      * {@code KeyOperation}s are not permitted by the JWK's
      * {@link #operationPolicy(KeyOperationPolicy) operationPolicy}. See that documentation for more
      * information on security vulnerabilities when using the same key with multiple algorithms.</p>

impl/src/main/java/io/jsonwebtoken/impl/DefaultJweHeaderMutator.java

@@ -107,9 +107,8 @@ public T setCompressionAlgorithm(String zip) {
     public NestedCollection<String, T> critical() {
         return new DefaultNestedCollection<String, T>(self(), this.DELEGATE.get(DefaultProtectedHeader.CRIT)) {
             @Override
-            public T and() {
+            protected void changed() {
                 put(DefaultProtectedHeader.CRIT, Collections.asSet(getCollection()));
-                return super.and();
             }
         };
     }

impl/src/main/java/io/jsonwebtoken/impl/DefaultJwtParserBuilder.java

@@ -220,9 +220,8 @@ public JwtParserBuilder clock(Clock clock) {
     public NestedCollection<String, JwtParserBuilder> critical() {
         return new DefaultNestedCollection<String, JwtParserBuilder>(this, this.critical) {
             @Override
-            public JwtParserBuilder and() {
+            protected void changed() {
                 critical = Collections.asSet(getCollection());
-                return super.and();
             }
         };
     }
@@ -304,9 +303,8 @@ private JwtParserBuilder decryptWith(final Key key) {
     public NestedCollection<CompressionAlgorithm, JwtParserBuilder> zip() {
         return new DefaultNestedCollection<CompressionAlgorithm, JwtParserBuilder>(this, this.zipAlgs.values()) {
             @Override
-            public JwtParserBuilder and() {
+            protected void changed() {
                 zipAlgs = new IdRegistry<>(StandardCompressionAlgorithms.NAME, getCollection());
-                return super.and();
             }
         };
     }
@@ -315,9 +313,8 @@ public JwtParserBuilder and() {
     public NestedCollection<AeadAlgorithm, JwtParserBuilder> enc() {
         return new DefaultNestedCollection<AeadAlgorithm, JwtParserBuilder>(this, this.encAlgs.values()) {
             @Override
-            public JwtParserBuilder and() {
+            public void changed() {
                 encAlgs = new IdRegistry<>(StandardEncryptionAlgorithms.NAME, getCollection());
-                return super.and();
             }
         };
     }
@@ -326,9 +323,8 @@ public JwtParserBuilder and() {
     public NestedCollection<SecureDigestAlgorithm<?, ?>, JwtParserBuilder> sig() {
         return new DefaultNestedCollection<SecureDigestAlgorithm<?, ?>, JwtParserBuilder>(this, this.sigAlgs.values()) {
             @Override
-            public JwtParserBuilder and() {
+            public void changed() {
                 sigAlgs = new IdRegistry<>(StandardSecureDigestAlgorithms.NAME, getCollection());
-                return super.and();
             }
         };
     }
@@ -337,9 +333,8 @@ public JwtParserBuilder and() {
     public NestedCollection<KeyAlgorithm<?, ?>, JwtParserBuilder> key() {
         return new DefaultNestedCollection<KeyAlgorithm<?, ?>, JwtParserBuilder>(this, this.keyAlgs.values()) {
             @Override
-            public JwtParserBuilder and() {
+            public void changed() {
                 keyAlgs = new IdRegistry<>(StandardKeyAlgorithms.NAME, getCollection());
-                return super.and();
             }
         };
     }

impl/src/main/java/io/jsonwebtoken/impl/DelegatingClaimsMutator.java

@@ -130,12 +130,12 @@ public AudienceCollection<T> audience() {
             @Override
             public T single(String audience) {
                 return audienceSingle(audience);
+                // DO NOT call changed() here - we don't want to replace the value with a collection
             }
 
             @Override
-            public T and() {
+            protected void changed() {
                 put(DefaultClaims.AUDIENCE, Collections.asSet(getCollection()));
-                return super.and();
             }
         };
     }