Add JwtParserBuilder as the preferred way to create a JwtParser insta…

…nce (jwtk#486) - Added new JwtParserBuilder - Copied mutator methods from JwtParser into new JwtParserBuilder - Marked said methods as deprecated in JwtParser - Copied JwtParserTest and JwtsTest to Deprecated*, as to retain coverage on methods that will be removed in 1.0 - Added ImmutableJwtParser This is a stop gap until 1.0, all of the mutable methods will now throw a IllegalStateException. NOTE: this only comes into place when using the new Jwts.parserBuilder(), Jwts.parser() is unchanged. Fixes: jwtk#473
renshengwuhui · Oct 1, 2019 · 94d1511 · 94d1511
1 parent a236656
commit 94d1511
Show file tree

Hide file tree

Showing 18 changed files with 3,601 additions and 129 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,22 @@ This minor release:
 
 * Updates the Jackson dependency version to [2.9.10](https://github.com/FasterXML/jackson/wiki/Jackson-Release-2.9#patches)
 to address three security vulnerabilities in Jackson.
+* A new JwtParserBuilder interface has been added and is the recommended way of creating a JwtParser instance.  Mutable methods in `JwtParser` will be removed before v1.0.
+    Migration to the new signatures is straightforward, for example:
+
+    Previous Version:
+    ```java 
+     Jwts.parser()
+         .requireAudience("string")
+         .parse(jwtString)
+    ```
+    Current Version:
+    ```java
+    Jwts.parserBuilder()
+        .requireAudience("string")
+        .build()
+        .parse(jwtString)
+    ```
 * Adds support for custom types when deserializing with Jackson. To use configure your parser with `Jwts.parserBuilder().deserializeJsonWith(new JacksonDeserializer(Maps.of("claimName", YourType.class).build())).build()`.
 * Adds `io.jsonwebtoken.lang.Maps` utility class to make creation of maps fluent.
 * Moves JSON Serializer/Deserializer implementations to a different package name.

diff --git a/api/pom.xml b/api/pom.xml
@@ -33,4 +33,21 @@
         <jjwt.root>${basedir}/..</jjwt.root>
     </properties>
 
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>com.github.siom79.japicmp</groupId>
+                <artifactId>japicmp-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>japicmp</id>
+                        <goals>
+                            <goal>cmp</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
 </project>
diff --git a/api/src/main/java/io/jsonwebtoken/JwtParser.java b/api/src/main/java/io/jsonwebtoken/JwtParser.java
@@ -41,7 +41,12 @@ public interface JwtParser {
      * @return the parser method for chaining.
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#requireId(String)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser requireId(String id);
 
     /**
@@ -53,7 +58,12 @@ public interface JwtParser {
      * @return the parser for method chaining.
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#requireSubject(String)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser requireSubject(String subject);
 
     /**
@@ -65,7 +75,12 @@ public interface JwtParser {
      * @return the parser for method chaining.
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#requireAudience(String)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser requireAudience(String audience);
 
     /**
@@ -77,7 +92,12 @@ public interface JwtParser {
      * @return the parser for method chaining.
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#requireIssuer(String)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser requireIssuer(String issuer);
 
     /**
@@ -89,7 +109,12 @@ public interface JwtParser {
      * @return the parser for method chaining.
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#requireIssuedAt(Date)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser requireIssuedAt(Date issuedAt);
 
     /**
@@ -101,7 +126,12 @@ public interface JwtParser {
      * @return the parser for method chaining.
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#requireExpiration(Date)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser requireExpiration(Date expiration);
 
     /**
@@ -113,7 +143,12 @@ public interface JwtParser {
      * @return the parser for method chaining
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#requireNotBefore(Date)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser requireNotBefore(Date notBefore);
 
     /**
@@ -126,7 +161,12 @@ public interface JwtParser {
      * @return the parser for method chaining.
      * @see MissingClaimException
      * @see IncorrectClaimException
+     * @deprecated see {@link JwtParserBuilder#require(String, Object)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser require(String claimName, Object value);
 
     /**
@@ -136,7 +176,12 @@ public interface JwtParser {
      * @param clock a {@code Clock} object to return the timestamp to use when validating the parsed JWT.
      * @return the parser for method chaining.
      * @since 0.7.0
+     * @deprecated see {@link JwtParserBuilder#setClock(Clock)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser setClock(Clock clock);
 
     /**
@@ -146,7 +191,12 @@ public interface JwtParser {
      * @param seconds the number of seconds to tolerate for clock skew when verifying {@code exp} or {@code nbf} claims.
      * @return the parser for method chaining.
      * @since 0.7.0
+     * @deprecated see {@link JwtParserBuilder#setAllowedClockSkewSeconds(long)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser setAllowedClockSkewSeconds(long seconds);
 
     /**
@@ -161,7 +211,12 @@ public interface JwtParser {
      * @param key the algorithm-specific signature verification key used to validate any discovered JWS digital
      *            signature.
      * @return the parser for method chaining.
+     * @deprecated see {@link JwtParserBuilder#setSigningKey(byte[])}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser setSigningKey(byte[] key);
 
     /**
@@ -202,7 +257,12 @@ public interface JwtParser {
      * @param base64EncodedSecretKey the BASE64-encoded algorithm-specific signature verification key to use to validate
      *                               any discovered JWS digital signature.
      * @return the parser for method chaining.
+     * @deprecated see {@link JwtParserBuilder#setSigningKey(String)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser setSigningKey(String base64EncodedSecretKey);
 
     /**
@@ -217,7 +277,12 @@ public interface JwtParser {
      * @param key the algorithm-specific signature verification key to use to validate any discovered JWS digital
      *            signature.
      * @return the parser for method chaining.
+     * @deprecated see {@link JwtParserBuilder#setSigningKey(Key)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser setSigningKey(Key key);
 
     /**
@@ -247,7 +312,12 @@ public interface JwtParser {
      * @param signingKeyResolver the signing key resolver used to retrieve the signing key.
      * @return the parser for method chaining.
      * @since 0.4
+     * @deprecated see {@link JwtParserBuilder#setSigningKeyResolver(SigningKeyResolver)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser setSigningKeyResolver(SigningKeyResolver signingKeyResolver);
 
     /**
@@ -269,7 +339,12 @@ public interface JwtParser {
      * @param compressionCodecResolver the compression codec resolver used to decompress the JWT body.
      * @return the parser for method chaining.
      * @since 0.6.0
+     * @deprecated see {@link JwtParserBuilder#setCompressionCodecResolver(CompressionCodecResolver)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser setCompressionCodecResolver(CompressionCodecResolver compressionCodecResolver);
 
     /**
@@ -281,7 +356,12 @@ public interface JwtParser {
      * @param base64UrlDecoder the decoder to use when Base64Url-decoding
      * @return the parser for method chaining.
      * @since 0.10.0
+     * @deprecated see {@link JwtParserBuilder#base64UrlDecodeWith(Decoder)}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser base64UrlDecodeWith(Decoder<String, byte[]> base64UrlDecoder);
 
     /**
@@ -295,9 +375,14 @@ public interface JwtParser {
      * invoked.</p>
      *
      * @param deserializer the deserializer to use when converting JSON Strings (UTF-8 byte arrays) into Map objects.
-     * @return the builder for method chaining.
+     * @return the parser for method chaining.
      * @since 0.10.0
+     * @deprecated see {@link JwtParserBuilder#deserializeJsonWith(Deserializer)} )}.
+     * To construct a JwtParser use the corresponding builder via {@link Jwts#parserBuilder()}. This will construct an
+     * immutable JwtParser.
+     * <p><b>NOTE: this method will be removed before version 1.0</b>
      */
+    @Deprecated
     JwtParser deserializeJsonWith(Deserializer<Map<String,?>> deserializer);
 
     /**