document java thread-safety

lib/src/main/java/com/auth0/jwt/ClockImpl.java

@@ -4,6 +4,14 @@
 
 import java.util.Date;
 
+/**
+ * Default Clock implementation used for verification.
+ *
+ * @see Clock
+ * @see JWTVerifier
+ * <p>
+ * This class is thread-safe.
+ */
 final class ClockImpl implements Clock {
 
     ClockImpl() {

lib/src/main/java/com/auth0/jwt/JWTCreator.java

@@ -21,6 +21,8 @@
 
 /**
  * The JWTCreator class holds the sign method to generate a complete JWT (with Signature) from a given Header and Payload content.
+ * <p>
+ * This class is thread-safe.
  */
 @SuppressWarnings("WeakerAccess")
 public final class JWTCreator {

lib/src/main/java/com/auth0/jwt/JWTDecoder.java

@@ -16,6 +16,8 @@
 
 /**
  * The JWTDecoder class holds the decode method to parse a given JWT token into it's JWT representation.
+ * <p>
+ * This class is thread-safe.
  */
 @SuppressWarnings("WeakerAccess")
 final class JWTDecoder implements DecodedJWT, Serializable {

lib/src/main/java/com/auth0/jwt/JWTVerifier.java

@@ -13,6 +13,8 @@
 
 /**
  * The JWTVerifier class holds the verify method to assert that a given Token has not only a proper JWT format, but also it's signature matches.
+ * <p>
+ * This class is thread-safe.
  */
 @SuppressWarnings("WeakerAccess")
 public final class JWTVerifier implements com.auth0.jwt.interfaces.JWTVerifier {

lib/src/main/java/com/auth0/jwt/algorithms/Algorithm.java

@@ -6,11 +6,12 @@
 import com.auth0.jwt.interfaces.ECDSAKeyProvider;
 import com.auth0.jwt.interfaces.RSAKeyProvider;
 
-import java.io.ByteArrayOutputStream;
 import java.security.interfaces.*;
 
 /**
  * The Algorithm class represents an algorithm to be used in the Signing or Verification process of a Token.
+ * <p>
+ * This class and its subclasses are thread-safe.
  */
 @SuppressWarnings("WeakerAccess")
 public abstract class Algorithm {
@@ -137,7 +138,7 @@ public static Algorithm RSA512(RSAKey key) throws IllegalArgumentException {
      *
      * @param secret the secret to use in the verify or signing instance.
      * @return a valid HMAC256 Algorithm.
-     * @throws IllegalArgumentException     if the provided Secret is null.
+     * @throws IllegalArgumentException if the provided Secret is null.
      */
     public static Algorithm HMAC256(String secret) throws IllegalArgumentException {
         return new HMACAlgorithm("HS256", "HmacSHA256", secret);
@@ -148,7 +149,7 @@ public static Algorithm HMAC256(String secret) throws IllegalArgumentException {
      *
      * @param secret the secret to use in the verify or signing instance.
      * @return a valid HMAC384 Algorithm.
-     * @throws IllegalArgumentException     if the provided Secret is null.
+     * @throws IllegalArgumentException if the provided Secret is null.
      */
     public static Algorithm HMAC384(String secret) throws IllegalArgumentException {
         return new HMACAlgorithm("HS384", "HmacSHA384", secret);
@@ -159,7 +160,7 @@ public static Algorithm HMAC384(String secret) throws IllegalArgumentException {
      *
      * @param secret the secret to use in the verify or signing instance.
      * @return a valid HMAC512 Algorithm.
-     * @throws IllegalArgumentException     if the provided Secret is null.
+     * @throws IllegalArgumentException if the provided Secret is null.
      */
     public static Algorithm HMAC512(String secret) throws IllegalArgumentException {
         return new HMACAlgorithm("HS512", "HmacSHA512", secret);
@@ -365,20 +366,20 @@ public String toString() {
     /**
      * Sign the given content using this Algorithm instance.
      *
-     * @param headerBytes an array of bytes representing the base64 encoded header content to be verified against the signature.
+     * @param headerBytes  an array of bytes representing the base64 encoded header content to be verified against the signature.
      * @param payloadBytes an array of bytes representing the base64 encoded payload content to be verified against the signature.
      * @return the signature in a base64 encoded array of bytes
      * @throws SignatureGenerationException if the Key is invalid.
      */
     public byte[] sign(byte[] headerBytes, byte[] payloadBytes) throws SignatureGenerationException {
-    	// default implementation; keep around until sign(byte[]) method is removed
-    	byte[] contentBytes = new byte[headerBytes.length + 1 + payloadBytes.length];
-    	
-    	System.arraycopy(headerBytes, 0, contentBytes, 0, headerBytes.length);
-    	contentBytes[headerBytes.length] = (byte)'.';
-    	System.arraycopy(payloadBytes, 0, contentBytes, headerBytes.length + 1, payloadBytes.length);
-    	
-    	return sign(contentBytes);
+        // default implementation; keep around until sign(byte[]) method is removed
+        byte[] contentBytes = new byte[headerBytes.length + 1 + payloadBytes.length];
+
+        System.arraycopy(headerBytes, 0, contentBytes, 0, headerBytes.length);
+        contentBytes[headerBytes.length] = (byte) '.';
+        System.arraycopy(payloadBytes, 0, contentBytes, headerBytes.length + 1, payloadBytes.length);
+
+        return sign(contentBytes);
     }
 
     /**
@@ -389,7 +390,7 @@ public byte[] sign(byte[] headerBytes, byte[] payloadBytes) throws SignatureGene
      * @throws SignatureGenerationException if the Key is invalid.
      * @deprecated Please use the {@linkplain #sign(byte[], byte[])} method instead.
      */
-    
+
     @Deprecated
     public abstract byte[] sign(byte[] contentBytes) throws SignatureGenerationException;
 

lib/src/main/java/com/auth0/jwt/algorithms/CryptoHelper.java

@@ -2,10 +2,14 @@
 
 import javax.crypto.Mac;
 import javax.crypto.spec.SecretKeySpec;
-
 import java.nio.charset.StandardCharsets;
 import java.security.*;
 
+/**
+ * Class used to perform the signature hash calculations.
+ * <p>
+ * This class is thread-safe.
+ */
 class CryptoHelper {
 
     private static final byte JWT_PART_SEPARATOR = (byte)46;

lib/src/main/java/com/auth0/jwt/algorithms/ECDSAAlgorithm.java

@@ -12,6 +12,11 @@
 import java.security.interfaces.ECPrivateKey;
 import java.security.interfaces.ECPublicKey;
 
+/**
+ * Subclass representing an Elliptic Curve signing algorithm
+ * <p>
+ * This class is thread-safe.
+ */
 class ECDSAAlgorithm extends Algorithm {
 
     private final ECDSAKeyProvider keyProvider;
@@ -65,7 +70,7 @@ public byte[] sign(byte[] headerBytes, byte[] payloadBytes) throws SignatureGene
             throw new SignatureGenerationException(this, e);
         }
     }
-    
+
     @Override
     @Deprecated
     public byte[] sign(byte[] contentBytes) throws SignatureGenerationException {

lib/src/main/java/com/auth0/jwt/algorithms/HMACAlgorithm.java

@@ -10,6 +10,11 @@
 import java.security.NoSuchAlgorithmException;
 import java.util.Arrays;
 
+/**
+ * Subclass representing an Hash-based MAC signing algorithm
+ * <p>
+ * This class is thread-safe.
+ */
 class HMACAlgorithm extends Algorithm {
 
     private final CryptoHelper crypto;

lib/src/main/java/com/auth0/jwt/algorithms/RSAAlgorithm.java

@@ -13,6 +13,11 @@
 import java.security.interfaces.RSAPrivateKey;
 import java.security.interfaces.RSAPublicKey;
 
+/**
+ * Subclass representing an RSA signing algorithm
+ * <p>
+ * This class is thread-safe.
+ */
 class RSAAlgorithm extends Algorithm {
 
     private final RSAKeyProvider keyProvider;

lib/src/main/java/com/auth0/jwt/impl/HeaderDeserializer.java

@@ -11,17 +11,24 @@
 import java.io.IOException;
 import java.util.Map;
 
+/**
+ * Jackson deserializer implementation for converting from JWT Header parts.
+ *
+ * @see JWTParser
+ * <p>
+ * This class is thread-safe.
+ */
 class HeaderDeserializer extends StdDeserializer<BasicHeader> {
 
     private final ObjectReader objectReader;
-    
+
     HeaderDeserializer(ObjectReader objectReader) {
         this(null, objectReader);
     }
 
     private HeaderDeserializer(Class<?> vc, ObjectReader objectReader) {
         super(vc);
-        
+
         this.objectReader = objectReader;
     }
 

lib/src/main/java/com/auth0/jwt/impl/PayloadDeserializer.java

@@ -13,17 +13,24 @@
 import java.io.IOException;
 import java.util.*;
 
+/**
+ * Jackson deserializer implementation for converting from JWT Payload parts.
+ *
+ * @see JWTParser
+ * <p>
+ * This class is thread-safe.
+ */
 class PayloadDeserializer extends StdDeserializer<Payload> {
 
     private final ObjectReader objectReader;
-    
+
     PayloadDeserializer(ObjectReader reader) {
         this(null, reader);
     }
 
     private PayloadDeserializer(Class<?> vc, ObjectReader reader) {
         super(vc);
-        
+
         this.objectReader = reader;
     }
 

lib/src/main/java/com/auth0/jwt/impl/PayloadImpl.java

@@ -11,7 +11,11 @@
 import static com.auth0.jwt.impl.JsonNodeClaim.extractClaim;
 
 /**
- * The PayloadImpl class implements the Payload interface.
+ * Decoder of string JSON Web Tokens into their POJO representations.
+ *
+ * @see Payload
+ * <p>
+ * This class is thread-safe.
  */
 class PayloadImpl implements Payload, Serializable {
 

lib/src/main/java/com/auth0/jwt/impl/PayloadSerializer.java

@@ -8,6 +8,13 @@
 import java.util.Date;
 import java.util.Map;
 
+/**
+ * Jackson serializer implementation for converting into JWT Payload parts.
+ *
+ * @see com.auth0.jwt.JWTCreator
+ * <p>
+ * This class is thread-safe.
+ */
 public class PayloadSerializer extends StdSerializer<ClaimsHolder> {
 
     public PayloadSerializer() {
@@ -20,14 +27,14 @@ private PayloadSerializer(Class<ClaimsHolder> t) {
 
     @Override
     public void serialize(ClaimsHolder holder, JsonGenerator gen, SerializerProvider provider) throws IOException {
-        
+
         gen.writeStartObject();
         for (Map.Entry<String, Object> e : holder.getClaims().entrySet()) {
             switch (e.getKey()) {
                 case PublicClaims.AUDIENCE:
                     if (e.getValue() instanceof String) {
                         gen.writeFieldName(e.getKey());
-                        gen.writeString((String)e.getValue());
+                        gen.writeString((String) e.getValue());
                         break;
                     }
                     String[] audArray = (String[]) e.getValue();
@@ -37,7 +44,7 @@ public void serialize(ClaimsHolder holder, JsonGenerator gen, SerializerProvider
                     } else if (audArray.length > 1) {
                         gen.writeFieldName(e.getKey());
                         gen.writeStartArray();
-                        for(String aud : audArray) {
+                        for (String aud : audArray) {
                             gen.writeString(aud);
                         }
                         gen.writeEndArray();