jwtk#235 Replace usage of java.util.Date with java.time.Instant in JW…

…T claims This commit replaces the usage of java.util.Date with java.time.Instant in handling JWT claims. This means upgrading from JDK7 to JDK8. This is done for better adherence to ISO 8601 standards and better precision in time-related operations. Classes working with claims have been updated to use the newer Instant class, providing better precision and cross-timezone compatibility. Additionally, overloading convenience methods for setting OffsetDateTime and ZonedDateTime on top of Instant have been added on the JwtBuilder and DefaultJwtBuilder.
pveeckhout · Dec 25, 2023 · 9bdbb85 · 9bdbb85
1 parent 917ffbb
commit 9bdbb85
Show file tree

Hide file tree

Showing 28 changed files with 591 additions and 324 deletions.
diff --git a/README.md b/README.md
@@ -991,8 +991,8 @@ String jws = Jwts.builder()
     .issuer("me")
     .subject("Bob")
     .audience("you")
-    .expiration(expiration) //a java.util.Date
-    .notBefore(notBefore) //a java.util.Date 
+    .expiration(expiration) //a java.time.Instant
+    .notBefore(notBefore) //a java.time.Instant
     .issuedAt(new Date()) // for example, now
     .id(UUID.randomUUID().toString()) //just an example id
 

diff --git a/api/src/main/java/io/jsonwebtoken/Claims.java b/api/src/main/java/io/jsonwebtoken/Claims.java
@@ -15,7 +15,7 @@
  */
 package io.jsonwebtoken;
 
-import java.util.Date;
+import java.time.Instant;
 import java.util.Map;
 import java.util.Set;
 
@@ -106,7 +106,7 @@ public interface Claims extends Map<String, Object>, Identifiable {
      *
      * @return the JWT {@code exp} value or {@code null} if not present.
      */
-    Date getExpiration();
+    Instant getExpiration();
 
     /**
      * Returns the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
@@ -116,7 +116,7 @@ public interface Claims extends Map<String, Object>, Identifiable {
      *
      * @return the JWT {@code nbf} value or {@code null} if not present.
      */
-    Date getNotBefore();
+    Instant getNotBefore();
 
     /**
      * Returns the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
@@ -126,7 +126,7 @@ public interface Claims extends Map<String, Object>, Identifiable {
      *
      * @return the JWT {@code iat} value or {@code null} if not present.
      */
-    Date getIssuedAt();
+    Instant getIssuedAt();
 
     /**
      * Returns the JWTs <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7">
@@ -147,7 +147,7 @@ public interface Claims extends Map<String, Object>, Identifiable {
      * Returns the JWTs claim ({@code claimName}) value as a {@code requiredType} instance, or {@code null} if not
      * present.
      *
-     * <p>JJWT only converts simple String, Date, Long, Integer, Short and Byte types automatically. Anything more
+     * <p>JJWT only converts simple String, Date, OffsetDateTime, ZonedDateTime, Long, Integer, Short and Byte types automatically. Anything more
      * complex is expected to be already converted to your desired type by the JSON parser. You may specify a custom
      * JSON processor using the {@code JwtParserBuilder}'s
      * {@link JwtParserBuilder#json(io.jsonwebtoken.io.Deserializer) json(Deserializer)} method. See the JJWT

diff --git a/api/src/main/java/io/jsonwebtoken/ClaimsMutator.java b/api/src/main/java/io/jsonwebtoken/ClaimsMutator.java
@@ -17,8 +17,8 @@
 
 import io.jsonwebtoken.lang.NestedCollection;
 
+import java.time.Instant;
 import java.util.Collection;
-import java.util.Date;
 
 /**
  * Mutation (modifications) to a {@link io.jsonwebtoken.Claims Claims} instance.
@@ -113,10 +113,10 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * @param exp the JWT {@code exp} value or {@code null} to remove the property from the JSON map.
      * @return the {@code Claims} instance for method chaining.
      * @deprecated since 0.12.0 in favor of the shorter and more modern builder-style named
-     * {@link #expiration(Date)}. This method will be removed before the JJWT 1.0 release.
+     * {@link #expiration(Instant)}. This method will be removed before the JJWT 1.0 release.
      */
     @Deprecated
-    T setExpiration(Date exp);
+    T setExpiration(Instant exp);
 
     /**
      * Sets the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4">
@@ -129,7 +129,7 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * @return the {@code Claims} instance for method chaining.
      * @since 0.12.0
      */
-    T expiration(Date exp);
+    T expiration(Instant exp);
 
     /**
      * Sets the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
@@ -141,10 +141,10 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * @param nbf the JWT {@code nbf} value or {@code null} to remove the property from the JSON map.
      * @return the {@code Claims} instance for method chaining.
      * @deprecated since 0.12.0 in favor of the shorter and more modern builder-style named
-     * {@link #notBefore(Date)}. This method will be removed before the JJWT 1.0 release.
+     * {@link #notBefore(Instant)}. This method will be removed before the JJWT 1.0 release.
      */
     @Deprecated
-    T setNotBefore(Date nbf);
+    T setNotBefore(Instant nbf);
 
     /**
      * Sets the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
@@ -157,7 +157,7 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * @return the {@code Claims} instance for method chaining.
      * @since 0.12.0
      */
-    T notBefore(Date nbf);
+    T notBefore(Instant nbf);
 
     /**
      * Sets the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
@@ -169,10 +169,10 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * @param iat the JWT {@code iat} value or {@code null} to remove the property from the JSON map.
      * @return the {@code Claims} instance for method chaining.
      * @deprecated since 0.12.0 in favor of the shorter and more modern builder-style named
-     * {@link #issuedAt(Date)}. This method will be removed before the JJWT 1.0 release.
+     * {@link #issuedAt(Instant)}. This method will be removed before the JJWT 1.0 release.
      */
     @Deprecated
-    T setIssuedAt(Date iat);
+    T setIssuedAt(Instant iat);
 
     /**
      * Sets the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
@@ -185,7 +185,7 @@ public interface ClaimsMutator<T extends ClaimsMutator<T>> {
      * @return the {@code Claims} instance for method chaining.
      * @since 0.12.0
      */
-    T issuedAt(Date iat);
+    T issuedAt(Instant iat);
 
     /**
      * Sets the JWT <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7">

diff --git a/api/src/main/java/io/jsonwebtoken/Clock.java b/api/src/main/java/io/jsonwebtoken/Clock.java
@@ -15,7 +15,7 @@
  */
 package io.jsonwebtoken;
 
-import java.util.Date;
+import java.time.Instant;
 
 /**
  * A clock represents a time source that can be used when creating and verifying JWTs.
@@ -29,5 +29,5 @@ public interface Clock {
      *
      * @return the clock's current timestamp at the instant the method is invoked.
      */
-    Date now();
+    Instant now();
 }
diff --git a/api/src/main/java/io/jsonwebtoken/JwtBuilder.java b/api/src/main/java/io/jsonwebtoken/JwtBuilder.java
@@ -40,7 +40,9 @@
 import java.security.SecureRandom;
 import java.security.interfaces.ECKey;
 import java.security.interfaces.RSAKey;
-import java.util.Date;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZonedDateTime;
 import java.util.Map;
 
 /**
@@ -523,14 +525,46 @@ public interface JwtBuilder extends ClaimsMutator<JwtBuilder> {
      *
      * <p>This is a convenience wrapper for:</p>
      * <blockquote><pre>
-     * {@link #claims()}.{@link ClaimsMutator#expiration(Date) expiration(exp)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     * {@link #claims()}.{@link ClaimsMutator#expiration(Instant) expiration(exp)}.{@link BuilderClaims#and() and()}</pre></blockquote>
      *
      * @param exp the JWT {@code exp} value or {@code null} to remove the property from the Claims map.
      * @return the builder instance for method chaining.
      */
     @Override
     // for better/targeted JavaDoc
-    JwtBuilder expiration(Date exp);
+    JwtBuilder expiration(Instant exp);
+
+    /**
+     * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4">
+     * <code>exp</code></a> (expiration) claim. A {@code null} value will remove the property from the Claims.
+     *
+     * <p>A JWT obtained after this timestamp should not be used.</p>
+     *
+     * <p>This is a convenience wrapper for:</p>
+     * <blockquote><pre>
+     * {@link #claims()}.{@link #expiration(Instant) expiration(exp)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     *
+     * @param exp the JWT {@code exp} value or {@code null} to remove the property from the Claims map.
+     * @return the builder instance for method chaining.
+     */
+    // for better/targeted JavaDoc
+    JwtBuilder expiration(OffsetDateTime exp);
+
+    /**
+     * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4">
+     * <code>exp</code></a> (expiration) claim. A {@code null} value will remove the property from the Claims.
+     *
+     * <p>A JWT obtained after this timestamp should not be used.</p>
+     *
+     * <p>This is a convenience wrapper for:</p>
+     * <blockquote><pre>
+     * {@link #claims()}.{@link #expiration(Instant) expiration(exp)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     *
+     * @param exp the JWT {@code exp} value or {@code null} to remove the property from the Claims map.
+     * @return the builder instance for method chaining.
+     */
+    // for better/targeted JavaDoc
+    JwtBuilder expiration(ZonedDateTime exp);
 
     /**
      * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
@@ -540,14 +574,46 @@ public interface JwtBuilder extends ClaimsMutator<JwtBuilder> {
      *
      * <p>This is a convenience wrapper for:</p>
      * <blockquote><pre>
-     * {@link #claims()}.{@link ClaimsMutator#notBefore(Date) notBefore(nbf)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     * {@link #claims()}.{@link ClaimsMutator#notBefore(Instant) notBefore(nbf)}.{@link BuilderClaims#and() and()}</pre></blockquote>
      *
      * @param nbf the JWT {@code nbf} value or {@code null} to remove the property from the Claims map.
      * @return the builder instance for method chaining.
      */
     @Override
     // for better/targeted JavaDoc
-    JwtBuilder notBefore(Date nbf);
+    JwtBuilder notBefore(Instant nbf);
+
+    /**
+     * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
+     * <code>nbf</code></a> (not before) claim. A {@code null} value will remove the property from the Claims.
+     *
+     * <p>A JWT obtained before this timestamp should not be used.</p>
+     *
+     * <p>This is a convenience wrapper for:</p>
+     * <blockquote><pre>
+     * {@link #claims()}.{@link #notBefore(Instant) notBefore(nbf)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     *
+     * @param nbf the JWT {@code nbf} value or {@code null} to remove the property from the Claims map.
+     * @return the builder instance for method chaining.
+     */
+    // for better/targeted JavaDoc
+    JwtBuilder notBefore(OffsetDateTime nbf);
+
+    /**
+     * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5">
+     * <code>nbf</code></a> (not before) claim. A {@code null} value will remove the property from the Claims.
+     *
+     * <p>A JWT obtained before this timestamp should not be used.</p>
+     *
+     * <p>This is a convenience wrapper for:</p>
+     * <blockquote><pre>
+     * {@link #claims()}.{@link #notBefore(Instant) notBefore(nbf)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     *
+     * @param nbf the JWT {@code nbf} value or {@code null} to remove the property from the Claims map.
+     * @return the builder instance for method chaining.
+     */
+    // for better/targeted JavaDoc
+    JwtBuilder notBefore(ZonedDateTime nbf);
 
     /**
      * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
@@ -557,14 +623,46 @@ public interface JwtBuilder extends ClaimsMutator<JwtBuilder> {
      *
      * <p>This is a convenience wrapper for:</p>
      * <blockquote><pre>
-     * {@link #claims()}.{@link ClaimsMutator#issuedAt(Date) issuedAt(iat)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     * {@link #claims()}.{@link ClaimsMutator#issuedAt(Instant) issuedAt(iat)}.{@link BuilderClaims#and() and()}</pre></blockquote>
      *
      * @param iat the JWT {@code iat} value or {@code null} to remove the property from the Claims map.
      * @return the builder instance for method chaining.
      */
     @Override
     // for better/targeted JavaDoc
-    JwtBuilder issuedAt(Date iat);
+    JwtBuilder issuedAt(Instant iat);
+
+    /**
+     * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
+     * <code>iat</code></a> (issued at) claim. A {@code null} value will remove the property from the Claims.
+     *
+     * <p>The value is the timestamp when the JWT was created.</p>
+     *
+     * <p>This is a convenience wrapper for:</p>
+     * <blockquote><pre>
+     * {@link #claims()}.{@link #issuedAt(Instant) issuedAt(iat)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     *
+     * @param iat the JWT {@code iat} value or {@code null} to remove the property from the Claims map.
+     * @return the builder instance for method chaining.
+     */
+    // for better/targeted JavaDoc
+    JwtBuilder issuedAt(OffsetDateTime iat);
+
+    /**
+     * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6">
+     * <code>iat</code></a> (issued at) claim. A {@code null} value will remove the property from the Claims.
+     *
+     * <p>The value is the timestamp when the JWT was created.</p>
+     *
+     * <p>This is a convenience wrapper for:</p>
+     * <blockquote><pre>
+     * {@link #claims()}.{@link #issuedAt(Instant) issuedAt(iat)}.{@link BuilderClaims#and() and()}</pre></blockquote>
+     *
+     * @param iat the JWT {@code iat} value or {@code null} to remove the property from the Claims map.
+     * @return the builder instance for method chaining.
+     */
+    // for better/targeted JavaDoc
+    JwtBuilder issuedAt(ZonedDateTime iat);
 
     /**
      * Sets the JWT Claims <a href="https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7">

diff --git a/api/src/main/java/io/jsonwebtoken/JwtParserBuilder.java b/api/src/main/java/io/jsonwebtoken/JwtParserBuilder.java
@@ -31,7 +31,7 @@
 import java.security.PrivateKey;
 import java.security.Provider;
 import java.security.PublicKey;
-import java.util.Date;
+import java.time.Instant;
 import java.util.Map;
 
 /**
@@ -182,7 +182,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * @see MissingClaimException
      * @see IncorrectClaimException
      */
-    JwtParserBuilder requireIssuedAt(Date issuedAt);
+    JwtParserBuilder requireIssuedAt(Instant issuedAt);
 
     /**
      * Ensures that the specified {@code exp} exists in the parsed JWT.  If missing or if the parsed
@@ -194,7 +194,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * @see MissingClaimException
      * @see IncorrectClaimException
      */
-    JwtParserBuilder requireExpiration(Date expiration);
+    JwtParserBuilder requireExpiration(Instant expiration);
 
     /**
      * Ensures that the specified {@code nbf} exists in the parsed JWT.  If missing or if the parsed
@@ -206,7 +206,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      * @see MissingClaimException
      * @see IncorrectClaimException
      */
-    JwtParserBuilder requireNotBefore(Date notBefore);
+    JwtParserBuilder requireNotBefore(Instant notBefore);
 
     /**
      * Ensures that the specified {@code claimName} exists in the parsed JWT.  If missing or if the parsed