Removed recently added Reader/Writer concepts for just overloaded met…

…hods in existing Serializer/Deserializer interfaces. This results in less change and is probably more intuitive for existing library users.

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

@@ -15,7 +15,7 @@
  */
 package io.jsonwebtoken;
 
-import io.jsonwebtoken.io.Reader;
+import io.jsonwebtoken.io.Deserializer;
 
 import java.util.Date;
 import java.util.Map;
@@ -150,8 +150,8 @@ public interface Claims extends Map<String, Object>, Identifiable {
      *
      * <p>JJWT only converts simple String, Date, 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 {@link io.jsonwebtoken.io.Reader Reader} with the desired configuration via the
-     * {@link JwtParserBuilder#jsonReader(Reader)} method.
+     * JSON {@link io.jsonwebtoken.io.Deserializer Deserializer} with the desired configuration via the
+     * {@link JwtParserBuilder#json(Deserializer)} method.
      * See <a href="https://github.com/jwtk/jjwt#custom-json-processor">custom JSON processor</a> for more
      * information. If using Jackson, you can specify custom claim POJO types as described in
      * <a href="https://github.com/jwtk/jjwt#json-jackson-custom-types">custom claim types</a>.

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

@@ -20,7 +20,6 @@
 import io.jsonwebtoken.io.Decoders;
 import io.jsonwebtoken.io.Encoder;
 import io.jsonwebtoken.io.Serializer;
-import io.jsonwebtoken.io.Writer;
 import io.jsonwebtoken.lang.MapMutator;
 import io.jsonwebtoken.security.AeadAlgorithm;
 import io.jsonwebtoken.security.InvalidKeyException;
@@ -1017,25 +1016,25 @@ public interface JwtBuilder extends ClaimsMutator<JwtBuilder> {
      * @param serializer the serializer to use when converting Map objects to JSON strings.
      * @return the builder for method chaining.
      * @since 0.10.0
-     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link #jsonWriter(Writer)}
+     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link #json(Serializer)}
      */
     @SuppressWarnings("DeprecatedIsStillUsed")
     @Deprecated
     JwtBuilder serializeToJsonWith(Serializer<Map<String, ?>> serializer);
 
     /**
-     * Perform Map-to-JSON serialization with the specified writer.  This is used by the builder to convert
+     * Perform Map-to-JSON serialization with the specified Serializer.  This is used by the builder to convert
      * JWT/JWS/JWE headers and Claims Maps to JSON strings as required by the JWT specification.
      *
-     * <p>If this method is not called, JJWT will use whatever Writer it can find at runtime, checking for the
+     * <p>If this method is not called, JJWT will use whatever Serializer it can find at runtime, checking for the
      * presence of well-known implementations such Jackson, Gson, and org.json.  If one of these is not found
      * in the runtime classpath, an exception will be thrown when the {@link #compact()} method is invoked.</p>
      *
-     * @param writer the writer to use when converting Map objects to JSON strings.
+     * @param serializer the Serializer to use when converting Map objects to JSON strings.
      * @return the builder for method chaining.
      * @since JJWT_RELEASE_VERSION
      */
-    JwtBuilder jsonWriter(Writer<Map<String, ?>> writer);
+    JwtBuilder json(Serializer<Map<String, ?>> serializer);
 
     /**
      * Actually builds the JWT and serializes it to a compact, URL-safe string according to the

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

@@ -18,7 +18,6 @@
 import io.jsonwebtoken.io.CompressionAlgorithm;
 import io.jsonwebtoken.io.Decoder;
 import io.jsonwebtoken.io.Deserializer;
-import io.jsonwebtoken.io.Reader;
 import io.jsonwebtoken.lang.Builder;
 import io.jsonwebtoken.security.AeadAlgorithm;
 import io.jsonwebtoken.security.KeyAlgorithm;
@@ -729,27 +728,27 @@ public interface JwtParserBuilder extends Builder<JwtParser> {
      *
      * @param deserializer the deserializer to use when converting JSON Strings (UTF-8 byte arrays) into Map objects.
      * @return the builder for method chaining.
-     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link #jsonReader(Reader)}.
+     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link #json(Deserializer)}.
      * This method will be removed before the JJWT 1.0 release.
      */
     @Deprecated
     JwtParserBuilder deserializeJsonWith(Deserializer<Map<String, ?>> deserializer);
 
     /**
-     * Uses the specified JSON {@link Reader} to deserialize JSON (UTF-8 byte streams) into Java Map objects.  This is
-     * used by the parser after Base64Url-decoding to convert JWT/JWS/JWT headers and Claims into Java Map
+     * Uses the specified JSON {@link Deserializer} to deserialize JSON (UTF-8 byte streams) into Java Map objects.
+     * This is used by the parser after Base64Url-decoding to convert JWT/JWS/JWT headers and Claims into Java Map
      * instances.
      *
-     * <p>If this method is not called, JJWT will use whatever Reader it can find at runtime, checking for the
+     * <p>If this method is not called, JJWT will use whatever Deserializer it can find at runtime, checking for the
      * presence of well-known implementations such Jackson, Gson, and org.json.  If one of these is not found
      * in the runtime classpath, an exception will be thrown when one of the various {@code parse}* methods is
      * invoked.</p>
      *
-     * @param reader the reader to use to deserialize JSON (UTF-8 byte streams) into Map instances.
+     * @param deserializer the deserializer to use to deserialize JSON (UTF-8 byte streams) into Map instances.
      * @return the builder for method chaining.
      * @since JJWT_RELEASE_VERSION
      */
-    JwtParserBuilder jsonReader(Reader<Map<String, ?>> reader);
+    JwtParserBuilder json(Deserializer<Map<String, ?>> deserializer);
 
     /**
      * Returns an immutable/thread-safe {@link JwtParser} created from the configuration from this JwtParserBuilder.

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

@@ -0,0 +1,72 @@
+/*
+ * Copyright © 2023 jsonwebtoken.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.jsonwebtoken.io;
+
+import io.jsonwebtoken.lang.Assert;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+
+/**
+ * Convenient base class to use to implement {@link Deserializer}s, with only the {@link #doDeserialize(InputStream)}.
+ *
+ * @param <T> the type of object returned after deserialization
+ * @since JJWT_RELEASE_VERSION
+ */
+public abstract class AbstractDeserializer<T> implements Deserializer<T> {
+
+    /**
+     * EOF (End of File) marker, equal to {@code -1}.
+     */
+    protected static final int EOF = -1;
+
+    private static final byte[] EMPTY_BYTES = new byte[0];
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public final T deserialize(byte[] bytes) throws DeserializationException {
+        bytes = bytes == null ? EMPTY_BYTES : bytes; // null safe
+        return deserialize(new ByteArrayInputStream(bytes));
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public final T deserialize(InputStream in) throws DeserializationException {
+        Assert.notNull(in, "InputStream argument cannot be null.");
+        try {
+            return doDeserialize(in);
+        } catch (Throwable t) {
+            if (t instanceof DeserializationException) {
+                throw (DeserializationException) t;
+            }
+            String msg = "Unable to deserialize: " + t.getMessage();
+            throw new DeserializationException(msg, t);
+        }
+    }
+
+    /**
+     * Reads the specified {@code InputStream} and returns the corresponding Java object.
+     *
+     * @param in the input stream to read
+     * @return the deserialized Java object
+     * @throws DeserializationException if there is a problem reading the stream or creating the expected Java object
+     */
+    protected abstract T doDeserialize(InputStream in) throws Exception;
+}

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

@@ -0,0 +1,46 @@
+/*
+ * Copyright © 2023 jsonwebtoken.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.jsonwebtoken.io;
+
+import io.jsonwebtoken.lang.Objects;
+
+import java.io.ByteArrayOutputStream;
+import java.io.OutputStream;
+
+public abstract class AbstractSerializer<T> implements Serializer<T> {
+
+    @Override
+    public final byte[] serialize(T t) throws SerializationException {
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+        serialize(t, out);
+        return out.toByteArray();
+    }
+
+    @Override
+    public void serialize(T t, OutputStream out) throws SerializationException {
+        try {
+            doSerialize(t, out);
+        } catch (Throwable e) {
+            if (e instanceof SerializationException) {
+                throw (SerializationException) e;
+            }
+            String msg = "Unable to serialize object of type " + Objects.nullSafeClassName(t) + ": " + e.getMessage();
+            throw new SerializationException(msg, e);
+        }
+    }
+
+    protected abstract void doSerialize(T t, OutputStream out) throws Exception;
+}

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

@@ -15,14 +15,14 @@
  */
 package io.jsonwebtoken.io;
 
+import java.io.InputStream;
+
 /**
- * A {@code Deserializer} is able to convert serialized data byte arrays into Java objects.
+ * A {@code Deserializer} is able to convert serialized byte streams into Java objects.
  *
  * @param <T> the type of object to be returned as a result of deserialization.
  * @since 0.10.0
- * @deprecated since JJWT_RELEASE_VERSION in favor of {@link io.jsonwebtoken.io.Reader}
  */
-@Deprecated
 public interface Deserializer<T> {
 
     /**
@@ -31,8 +31,18 @@ public interface Deserializer<T> {
      * @param bytes the formatted data byte array to convert
      * @return the reconstituted Java object
      * @throws DeserializationException if there is a problem converting the byte array to an object.
-     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link Reader#read(java.io.Reader)}
+     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link #deserialize(InputStream)}
      */
     @Deprecated
     T deserialize(byte[] bytes) throws DeserializationException;
+
+    /**
+     * Reads the specified {@code InputStream} and returns the corresponding Java object.
+     *
+     * @param in the input stream to read
+     * @return the deserialized Java object
+     * @throws DeserializationException if there is a problem reading the stream or creating the expected Java object
+     * @since JJWT_RELEASE_VERSION
+     */
+    T deserialize(InputStream in) throws DeserializationException;
 }

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

@@ -40,15 +40,15 @@ public interface ParserBuilder<T, B extends ParserBuilder<T, B>> extends Builder
     B provider(Provider provider);
 
     /**
-     * Uses the specified reader to convert JSON Strings (UTF-8 byte streams) into Java Map objects.  The
+     * Uses the specified {@code Deserializer} to convert JSON Strings (UTF-8 byte streams) into Java Map objects.  The
      * resulting Maps are then used to construct respective JWT objects (JWTs, JWKs, etc).
      *
-     * <p>If this method is not called, JJWT will use whatever Reader it can find at runtime, checking for the
+     * <p>If this method is not called, JJWT will use whatever Deserializer it can find at runtime, checking for the
      * presence of well-known implementations such as Jackson, Gson, and org.json.  If one of these is not found
      * in the runtime classpath, an exception will be thrown when the {@link #build()} method is called.
      *
-     * @param reader the Reader to use when converting JSON Strings (UTF-8 byte streams) into Map objects.
+     * @param reader the Deserializer to use when converting JSON Strings (UTF-8 byte streams) into Map objects.
      * @return the builder for method chaining.
      */
-    B jsonReader(Reader<Map<String, ?>> reader);
+    B json(Deserializer<Map<String, ?>> reader);
 }

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

@@ -15,25 +15,37 @@
  */
 package io.jsonwebtoken.io;
 
+import java.io.OutputStream;
+
 /**
- * A {@code Serializer} is able to convert a Java object into a formatted data byte array.  It is expected this data
+ * A {@code Serializer} is able to convert a Java object into a formatted byte stream.  It is expected this byte stream
  * can be reconstituted back into a Java object with a matching {@link Deserializer}.
  *
  * @param <T> The type of object to serialize.
  * @since 0.10.0
- * @deprecated since JJWT_RELEASE_VERSION in favor of {@link io.jsonwebtoken.io.Writer}
  */
-@Deprecated
 public interface Serializer<T> {
 
     /**
-     * Convert the specified Java object into a formatted data byte array.
+     * Converts the specified Java object into a formatted data byte array.
      *
      * @param t the object to serialize
      * @return the serialized byte array representing the specified object.
      * @throws SerializationException if there is a problem converting the object to a byte array.
-     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link Writer#write(java.io.Writer, Object)}
+     * @deprecated since JJWT_RELEASE_VERSION in favor of {@link #serialize(Object, OutputStream)}
      */
     @Deprecated
     byte[] serialize(T t) throws SerializationException;
+
+    /**
+     * Converts the specified Java object into a formatted data byte stream, writing the bytes to the specified
+     * {@code out}put stream.
+     *
+     * @param t   the object to convert to a byte stream
+     * @param out the stream to write to
+     * @throws SerializationException if there is a problem converting the object to a byte stream or writing the
+     *                                bytes to the {@code out}put stream.
+     * @since JJWT_RELEASE_VERSION
+     */
+    void serialize(T t, OutputStream out) throws SerializationException;
 }