#235 Replace usage of java.util.Date

CHANGELOG.md

@@ -732,7 +732,7 @@ would be very strange if a machine's clock was more than 5 minutes difference fr
 #### Custom Clock Support
 
 Timestamps created during parsing can now be obtained via a custom time source via an implementation of
- the new `io.jsonwebtoken.Clock` interface.  The default implementation simply returns `new Date()` to reflect the time
+ the new `io.jsonwebtoken.Clock` interface.  The default implementation simply returns `new Instant()` to reflect the time
   when parsing occurs, as most would expect.  However, supplying your own clock could be useful, especially during test 
   cases to guarantee deterministic behavior.
 

README.adoc

@@ -1063,9 +1063,9 @@ String jws = Jwts.builder()
     .issuer("me")
     .subject("Bob")
     .audience().add("you").and()
-    .expiration(expiration) //a java.util.Date
-    .notBefore(notBefore) //a java.util.Date
-    .issuedAt(new Date()) // for example, now
+    .expiration(expiration) //a java.time.Instant
+    .notBefore(notBefore) //a java.time.Instant
+    .issuedAt(Instant.now) // for example, now
     .id(UUID.randomUUID().toString()) //just an example id
 
     /// ... etc ...
@@ -1530,7 +1530,7 @@ Clock clock = new MyClock();
 Jwts.parser().clock(myClock) //... etc ...
 ----
 
-The ``JwtParser``'s default `Clock` implementation simply returns `new Date()` to reflect the time when parsing occurs,
+The ``JwtParser``'s default `Clock` implementation simply returns `Instant.now()` to reflect the time when parsing occurs,
 as most would expect.  However, supplying your own clock could be useful, especially when writing test cases to
 guarantee deterministic behavior.
 
@@ -3406,7 +3406,7 @@ Jwts.parser()
 
 ==== Parsing of Custom Claim Types
 
-By default, JJWT will only convert simple claim types: String, Date, Long, Integer, Short and Byte.  If you need to
+By default, JJWT will only convert simple claim types: String, Instant, Long, Integer, Short and Byte.  If you need to
 deserialize other types you can configure the `JacksonDeserializer` by passing a `Map` of claim names to types in
 through a constructor. For example:
 
@@ -3634,7 +3634,7 @@ last char) are significant. The last two bits are not decoded. Thus all of:
 dGVzdCBzdHJpbmo
 dGVzdCBzdHJpbmp
 dGVzdCBzdHJpbmq
-dGVzdCBzdHJpbmr 
+dGVzdCBzdHJpbmr
 ----
 All decode to the same 11 bytes (116, 101, 115, 116, 32, 115, 116, 114, 105, 110, 106).
 ====

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, Instant, 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

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

@@ -17,6 +17,7 @@
 
 import io.jsonwebtoken.lang.NestedCollection;
 
+import java.time.Instant;
 import java.util.Collection;
 import java.util.Date;
 
@@ -124,7 +125,7 @@ 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);
@@ -140,7 +141,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">
@@ -152,7 +153,7 @@ 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);
@@ -168,7 +169,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">
@@ -180,7 +181,7 @@ 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);
@@ -196,7 +197,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">

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();
 }

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">

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;
 
 /**
@@ -195,7 +195,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
@@ -207,7 +207,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
@@ -219,7 +219,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
@@ -236,7 +236,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
 
     /**
      * Sets the {@link Clock} that determines the timestamp to use when validating the parsed JWT.
-     * The parser uses a default Clock implementation that simply returns {@code new Date()} when called.
+     * The parser uses a default Clock implementation that simply returns {@code new Instant()} when called.
      *
      * @param clock a {@code Clock} object to return the timestamp to use when validating the parsed JWT.
      * @return the parser builder for method chaining.
@@ -248,7 +248,7 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
 
     /**
      * Sets the {@link Clock} that determines the timestamp to use when validating the parsed JWT.
-     * The parser uses a default Clock implementation that simply returns {@code new Date()} when called.
+     * The parser uses a default Clock implementation that simply returns {@code new Instant()} when called.
      *
      * @param clock a {@code Clock} object to return the timestamp to use when validating the parsed JWT.
      * @return the parser builder for method chaining.