JwtParser.parse* method renames (#845)

* Closes #834

- Deprecated JwtParser parseContentJwt, parseClaimsJwt, parseContentJws and parseClaimsJws in favor of parseUnprotectedContent, parseUnprotectedClaims, parseSignedContent, and parseSignedClaims

- Renamed the not-yet-released JwtParser parseContentJwe and parseClaimsJwe to parseEncryptedContent and parseEncryptedClaims

- Renamed the not-yet-released JwtParser overloaded unencoded payload parseContentJws and parseClaimsJws methods to parseSignedContent and parseSignedClaims

- Deprecated JwtHandler and JwtHandlerAdapter in favor of JwtVisitor and SupportedJwtVisitor

CHANGELOG.md

@@ -44,7 +44,7 @@ AeadAlgorithm enc = Jwts.ENC.A256GCM;
 SecretKey key = enc.key().build();
 String compact = Jwts.builder().setSubject("Joe").encryptWith(key, enc).compact();
 
-Jwe<Claims> jwe = Jwts.parser().decryptWith(key).build().parseClaimsJwe(compact);
+Jwe<Claims> jwe = Jwts.parser().decryptWith(key).build().parseEncryptedClaims(compact);
 ```
 
 Many other RSA and Elliptic Curve examples are in the full README documentation. 
@@ -137,6 +137,11 @@ deprecate some concepts, or in some cases, completely break backwards compatibil
   support expected congruent behavior with `Jwe` instances (both have digests).
 
 
+* `io.jsonwebtoken.JwtParser`'s `parseContentJwt`, `parseClaimsJwt`, `parseContentJws`, and `parseClaimsJws` methods
+  have been deprecated in favor of more intuitive respective `parseUnsecuredContent`, `parseUnsecuredClaims`,
+  `parseSignedContent` and `parseSignedClaims` methods.
+
+
 * `io.jsonwebtoken.CompressionCodec` is now deprecated in favor of the new `io.jsonwebtoken.io.CompressionAlgorithm`
   interface. This is to guarantee API congruence with all other JWT-identifiable algorithm IDs that can be set as a 
   header value.

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

@@ -24,6 +24,38 @@
  */
 public interface Jwe<B> extends ProtectedJwt<JweHeader, B> {
 
+    /**
+     * Visitor implementation that ensures the visited JWT is a JSON Web Encryption ('JWE') message with an
+     * authenticated and decrypted {@code byte[]} array payload, and rejects all others with an
+     * {@link UnsupportedJwtException}.
+     *
+     * @see SupportedJwtVisitor#onDecryptedContent(Jwe)
+     * @since JJWT_RELEASE_VERSION
+     */
+    @SuppressWarnings("UnnecessaryModifier")
+    public static final JwtVisitor<Jwe<byte[]>> CONTENT = new SupportedJwtVisitor<Jwe<byte[]>>() {
+        @Override
+        public Jwe<byte[]> onDecryptedContent(Jwe<byte[]> jwe) {
+            return jwe;
+        }
+    };
+
+    /**
+     * Visitor implementation that ensures the visited JWT is a JSON Web Encryption ('JWE') message with an
+     * authenticated and decrypted {@link Claims} payload, and rejects all others with an
+     * {@link UnsupportedJwtException}.
+     *
+     * @see SupportedJwtVisitor#onDecryptedClaims(Jwe)
+     * @since JJWT_RELEASE_VERSION
+     */
+    @SuppressWarnings("UnnecessaryModifier")
+    public static final JwtVisitor<Jwe<Claims>> CLAIMS = new SupportedJwtVisitor<Jwe<Claims>>() {
+        @Override
+        public Jwe<Claims> onDecryptedClaims(Jwe<Claims> jwe) {
+            return jwe;
+        }
+    };
+
     /**
      * Returns the Initialization Vector used during JWE encryption and decryption.
      *

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

@@ -18,10 +18,42 @@
 /**
  * An expanded (not compact/serialized) Signed JSON Web Token.
  *
- * @param <B> the type of the JWS body contents, either a String or a {@link Claims} instance.
+ * @param <P> the type of the JWS payload, either a byte[] or a {@link Claims} instance.
  * @since 0.1
  */
-public interface Jws<B> extends ProtectedJwt<JwsHeader, B> {
+public interface Jws<P> extends ProtectedJwt<JwsHeader, P> {
+
+    /**
+     * Visitor implementation that ensures the visited JWT is a JSON Web Signature ('JWS') message with a
+     * cryptographically authenticated/verified {@code byte[]} array payload, and rejects all others with an
+     * {@link UnsupportedJwtException}.
+     *
+     * @see SupportedJwtVisitor#onVerifiedContent(Jws)
+     * @since JJWT_RELEASE_VERSION
+     */
+    @SuppressWarnings("UnnecessaryModifier")
+    public static final JwtVisitor<Jws<byte[]>> CONTENT = new SupportedJwtVisitor<Jws<byte[]>>() {
+        @Override
+        public Jws<byte[]> onVerifiedContent(Jws<byte[]> jws) {
+            return jws;
+        }
+    };
+
+    /**
+     * Visitor implementation that ensures the visited JWT is a JSON Web Signature ('JWS') message with a
+     * cryptographically authenticated/verified {@link Claims} payload, and rejects all others with an
+     * {@link UnsupportedJwtException}.
+     *
+     * @see SupportedJwtVisitor#onVerifiedClaims(Jws)
+     * @since JJWT_RELEASE_VERSION
+     */
+    @SuppressWarnings("UnnecessaryModifier")
+    public static final JwtVisitor<Jws<Claims>> CLAIMS = new SupportedJwtVisitor<Jws<Claims>>() {
+        @Override
+        public Jws<Claims> onVerifiedClaims(Jws<Claims> jws) {
+            return jws;
+        }
+    };
 
     /**
      * Returns the verified JWS signature as a Base64Url string.

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

@@ -24,6 +24,36 @@
  */
 public interface Jwt<H extends Header, P> {
 
+    /**
+     * Visitor implementation that ensures the visited JWT is an unsecured content JWT (one not cryptographically
+     * signed or encrypted) and rejects all others with an {@link UnsupportedJwtException}.
+     *
+     * @see SupportedJwtVisitor#onUnsecuredContent(Jwt)
+     * @since JJWT_RELEASE_VERSION
+     */
+    @SuppressWarnings("UnnecessaryModifier")
+    public static final JwtVisitor<Jwt<Header, byte[]>> UNSECURED_CONTENT = new SupportedJwtVisitor<Jwt<Header, byte[]>>() {
+        @Override
+        public Jwt<Header, byte[]> onUnsecuredContent(Jwt<Header, byte[]> jwt) {
+            return jwt;
+        }
+    };
+
+    /**
+     * Visitor implementation that ensures the visited JWT is an unsecured {@link Claims} JWT (one not
+     * cryptographically signed or encrypted) and rejects all others with an {@link UnsupportedJwtException}.
+     *
+     * @see SupportedJwtVisitor#onUnsecuredClaims(Jwt)
+     * @since JJWT_RELEASE_VERSION
+     */
+    @SuppressWarnings("UnnecessaryModifier")
+    public static final JwtVisitor<Jwt<Header, Claims>> UNSECURED_CLAIMS = new SupportedJwtVisitor<Jwt<Header, Claims>>() {
+        @Override
+        public Jwt<Header, Claims> onUnsecuredClaims(Jwt<Header, Claims> jwt) {
+            return jwt;
+        }
+    };
+
     /**
      * Returns the JWT {@link Header} or {@code null} if not present.
      *
@@ -54,4 +84,13 @@ public interface Jwt<H extends Header, P> {
      * @since JJWT_RELEASE_VERSION
      */
     P getPayload();
+
+    /**
+     * Invokes the specified {@code visitor}'s appropriate type-specific {@code visit} method based on this JWT's type.
+     *
+     * @param visitor the visitor to invoke.
+     * @param <T>     the value type returned from the {@code visit} method.
+     * @return the value returned from visitor's {@code visit} method implementation.
+     */
+    <T> T accept(JwtVisitor<T> visitor);
 }

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

@@ -21,17 +21,20 @@
  *
  * @param <T> the type of object to return to the parser caller after handling the parsed JWT.
  * @since 0.2
+ * @deprecated since JJWT_RELEASE_VERSION in favor of calling {@link Jwt#accept(JwtVisitor)}.
  */
-public interface JwtHandler<T> {
+@SuppressWarnings("DeprecatedIsStillUsed")
+@Deprecated
+public interface JwtHandler<T> extends JwtVisitor<T> {
 
     /**
      * This method is invoked when a {@link io.jsonwebtoken.JwtParser JwtParser} determines that the parsed JWT is
-     * an unprotected content JWT.  An unprotected content JWT has a byte array payload that is not
+     * an unsecured content JWT.  An unsecured content JWT has a byte array payload that is not
      * cryptographically signed or encrypted.  If the JWT creator set the (optional)
      * {@link Header#getContentType() contentType} header value, the application may inspect that value to determine
      * how to convert the byte array to the final content type as desired.
      *
-     * @param jwt the parsed Unprotected content JWT
+     * @param jwt the parsed unsecured content JWT
      * @return any object to be used after inspecting the JWT, or {@code null} if no return value is necessary.
      */
     T onContentJwt(Jwt<Header, byte[]> jwt);

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

@@ -28,41 +28,71 @@
  * @param <T> the type of object to return to the parser caller after handling the parsed JWT.
  * @since 0.2
  */
-public abstract class JwtHandlerAdapter<T> implements JwtHandler<T> {
+public abstract class JwtHandlerAdapter<T> extends SupportedJwtVisitor<T> implements JwtHandler<T> {
 
     /**
      * Default constructor, does not initialize any internal state.
      */
     public JwtHandlerAdapter() {
     }
 
+    @Override
+    public T onUnsecuredContent(Jwt<Header, byte[]> jwt) {
+        return onContentJwt(jwt); // bridge for existing implementations
+    }
+
+    @Override
+    public T onUnsecuredClaims(Jwt<Header, Claims> jwt) {
+        return onClaimsJwt(jwt);
+    }
+
+    @Override
+    public T onVerifiedContent(Jws<byte[]> jws) {
+        return onContentJws(jws);
+    }
+
+    @Override
+    public T onVerifiedClaims(Jws<Claims> jws) {
+        return onClaimsJws(jws);
+    }
+
+    @Override
+    public T onDecryptedContent(Jwe<byte[]> jwe) {
+        return onContentJwe(jwe);
+    }
+
+    @Override
+    public T onDecryptedClaims(Jwe<Claims> jwe) {
+        return onClaimsJwe(jwe);
+    }
+
     @Override
     public T onContentJwt(Jwt<Header, byte[]> jwt) {
-        throw new UnsupportedJwtException("Unprotected content JWTs are not supported.");
+        return super.onUnsecuredContent(jwt);
     }
 
     @Override
     public T onClaimsJwt(Jwt<Header, Claims> jwt) {
-        throw new UnsupportedJwtException("Unprotected Claims JWTs are not supported.");
+        return super.onUnsecuredClaims(jwt);
     }
 
     @Override
     public T onContentJws(Jws<byte[]> jws) {
-        throw new UnsupportedJwtException("Signed content JWTs are not supported.");
+        return super.onVerifiedContent(jws);
     }
 
     @Override
     public T onClaimsJws(Jws<Claims> jws) {
-        throw new UnsupportedJwtException("Signed Claims JWTs are not supported.");
+        return super.onVerifiedClaims(jws);
     }
 
     @Override
     public T onContentJwe(Jwe<byte[]> jwe) {
-        throw new UnsupportedJwtException("Encrypted content JWTs are not supported.");
+        return super.onDecryptedContent(jwe);
     }
 
     @Override
     public T onClaimsJwe(Jwe<Claims> jwe) {
-        throw new UnsupportedJwtException("Encrypted Claims JWTs are not supported.");
+        return super.onDecryptedClaims(jwe);
     }
 }