Added Javadoc and nullability annotations; adjusted visibility

jwt/src/main/java/org/unbrokendome/jsonwebtoken/BinaryData.java

@@ -9,7 +9,7 @@
 
 /**
  * Stores a blob of binary data.
- *
+ * <p>
  * This is essentially a wrapper over {@link ByteBuffer} to ensure immutability.
  */
 public final class BinaryData {

jwt/src/main/java/org/unbrokendome/jsonwebtoken/Claims.java

@@ -76,8 +76,7 @@ default String getSubject() {
      * with a single audience.</p>
      *
      * @return the value (or the first element) of the audience claim, or
-     *         <code>null</code> if not set
-     *
+     * <code>null</code> if not set
      * @see #getAudiences()
      */
     @Nullable
@@ -113,7 +112,6 @@ default String getAudience() {
      * </blockquote>
      *
      * @return the value of the audience claim, or <code>null</code> if not set
-     *
      * @see #getAudience()
      */
     @Nullable
@@ -138,7 +136,7 @@ default Set<String> getAudiences() {
      * </blockquote>
      *
      * @return the value of the expiration time claim as an {@link Instant}, or
-     *         <code>null</code> if not set
+     * <code>null</code> if not set
      */
     @Nullable
     default Instant getExpiration() {
@@ -162,7 +160,7 @@ default Instant getExpiration() {
      * </blockquote>
      *
      * @return the value of the not-before claim as an {@link Instant}, or
-     *         <code>null</code> if not set
+     * <code>null</code> if not set
      */
     @Nullable
     default Instant getNotBefore() {
@@ -183,7 +181,7 @@ default Instant getNotBefore() {
      * </blockquote>
      *
      * @return the value of the issued-at claim as an {@link Instant}, or
-     *         <code>null</code> if not set
+     * <code>null</code> if not set
      */
     @Nullable
     default Instant getIssuedAt() {
@@ -208,7 +206,7 @@ default Instant getIssuedAt() {
      * </blockquote>
      *
      * @return the value of the issued-at claim as an {@link Instant}, or
-     *         <code>null</code> if not set
+     * <code>null</code> if not set
      */
     @Nullable
     default String getId() {
@@ -218,7 +216,7 @@ default String getId() {
 
     /**
      * Checks whether this set of claims is expired, according to the given {@link Clock}.
-     *
+     * <p>
      * Returns {@code false} if this instance does not contain an {@linkplain #EXPIRATION expiration} claim.
      *
      * @param clock a {@link Clock} that provides the current time

jwt/src/main/java/org/unbrokendome/jsonwebtoken/ClaimsBuilder.java

@@ -9,9 +9,9 @@ public interface ClaimsBuilder extends MapDataBuilder<ClaimsBuilder, Claims>, Cl
 
     /**
      * Sets the value of the issuer (<code>iss</code>) claim.
+     *
      * @param issuer the value of the issuer claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getIssuer()
      */
     @Nonnull
@@ -22,9 +22,9 @@ default ClaimsBuilder setIssuer(String issuer) {
 
     /**
      * Sets the value of the subject (<code>sub</code>) claim.
+     *
      * @param subject the value of the subject claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getSubject()
      */
     @Nonnull
@@ -35,9 +35,9 @@ default ClaimsBuilder setSubject(String subject) {
 
     /**
      * Sets the value of the audience (<code>aud</code>) claim to a single string.
+     *
      * @param audience the value of the audience claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getAudience()
      */
     @Nonnull
@@ -48,9 +48,9 @@ default ClaimsBuilder setAudience(String audience) {
 
     /**
      * Sets the value of the audience (<code>aud</code>) claim to a set of strings.
+     *
      * @param audiences the value of the audience claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getAudiences()
      */
     @Nonnull
@@ -61,9 +61,9 @@ default ClaimsBuilder setAudiences(Set<String> audiences) {
 
     /**
      * Sets the value of the expiration time (<code>exp</code>) claim.
+     *
      * @param expiration the value of the expiration time claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getExpiration()
      */
     @Nonnull
@@ -74,9 +74,9 @@ default ClaimsBuilder setExpiration(Instant expiration) {
 
     /**
      * Sets the value of the not-before (<code>nbf</code>) claim.
+     *
      * @param notBefore the value of the not-before claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getNotBefore()
      */
     @Nonnull
@@ -87,9 +87,9 @@ default ClaimsBuilder setNotBefore(Instant notBefore) {
 
     /**
      * Sets the value of the issued-at (<code>iat</code>) claim.
+     *
      * @param issuedAt the value of the issued-at claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getIssuedAt()
      */
     @Nonnull
@@ -100,9 +100,9 @@ default ClaimsBuilder setIssuedAt(Instant issuedAt) {
 
     /**
      * Sets the value of the JWT ID (<code>jti</code>) claim.
+     *
      * @param id the value of the JWT ID claim
      * @return the current {@link ClaimsBuilder} instance
-     *
      * @see Claims#getId()
      */
     @Nonnull

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JoseHeader.java

@@ -2,7 +2,7 @@
 
 /**
  * Represents a JOSE (JSON Object Signing and Encryption) token header.
- *
+ * <p>
  * A JOSE header is essentially a key-value collection, where the keys are well-known and standardized.
  * Commonly used headers are defined as constants in this interface.
  */

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JoseHeaderBuilder.java

@@ -1,22 +1,53 @@
 package org.unbrokendome.jsonwebtoken;
 
+import javax.annotation.Nonnull;
+
+
 public interface JoseHeaderBuilder extends MapDataBuilder<JoseHeaderBuilder, JoseHeader>, JoseHeader {
 
+    /**
+     * Sets the {@value JoseHeader#TYPE} entry for this header.
+     *
+     * @param type the value for the {@value JoseHeader#TYPE} entry
+     * @return the current builder instance
+     */
+    @Nonnull
     default JoseHeaderBuilder setType(String type) {
         return set(TYPE, type);
     }
 
 
+    /**
+     * Sets the {@value JoseHeader#CONTENT_TYPE} entry for this header.
+     *
+     * @param contentType the value for the {@value JoseHeader#CONTENT_TYPE} entry
+     * @return the current builder instance
+     */
+    @Nonnull
     default JoseHeaderBuilder setContentType(String contentType) {
         return set(CONTENT_TYPE, contentType);
     }
 
 
+    /**
+     * Sets the {@value JoseHeader#ALGORITHM} entry for this header.
+     *
+     * @param algorithm the value for the {@value JoseHeader#ALGORITHM} entry
+     * @return the current builder instance
+     */
+    @Nonnull
     default JoseHeaderBuilder setAlgorithm(String algorithm) {
         return set(ALGORITHM, algorithm);
     }
 
 
+    /**
+     * Sets the {@value JoseHeader#KEY_ID} entry for this header.
+     *
+     * @param keyId the value for the {@value JoseHeader#KEY_ID} entry
+     * @return the current builder instance
+     */
+    @Nonnull
     default JoseHeaderBuilder setKeyId(String keyId) {
         return set(KEY_ID, keyId);
     }

jwt/src/main/java/org/unbrokendome/jsonwebtoken/Jws.java

@@ -1,29 +1,36 @@
 package org.unbrokendome.jsonwebtoken;
 
+import javax.annotation.Nonnull;
 import java.nio.ByteBuffer;
 
 
 public interface Jws {
 
+    @Nonnull
     BinaryData getHeader();
 
 
+    @Nonnull
     default ByteBuffer getHeaderBytes() {
         return getHeader().toByteBuffer();
     }
 
 
+    @Nonnull
     BinaryData getPayload();
 
 
+    @Nonnull
     default ByteBuffer getPayloadBytes() {
         return getPayload().toByteBuffer();
     }
 
 
+    @Nonnull
     BinaryData getSignature();
 
 
+    @Nonnull
     default ByteBuffer getSignatureBytes() {
         return getSignature().toByteBuffer();
     }

jwt/src/main/java/org/unbrokendome/jsonwebtoken/Jwt.java

@@ -4,6 +4,8 @@
 import org.unbrokendome.jsonwebtoken.impl.DefaultJoseHeaderBuilder;
 import org.unbrokendome.jsonwebtoken.impl.DefaultJwtProcessorBuilder;
 
+import javax.annotation.Nonnull;
+
 
 /**
  * Main entry point to the JSON Web Token library.
@@ -20,6 +22,7 @@ private Jwt() {
      *
      * @return a new {@link JoseHeaderBuilder} instance
      */
+    @Nonnull
     public static JoseHeaderBuilder header() {
         return new DefaultJoseHeaderBuilder();
     }
@@ -30,6 +33,7 @@ public static JoseHeaderBuilder header() {
      *
      * @return a new {@link ClaimsBuilder} instance
      */
+    @Nonnull
     public static ClaimsBuilder claims() {
         return new DefaultClaimsBuilder();
     }
@@ -40,6 +44,7 @@ public static ClaimsBuilder claims() {
      *
      * @return a new {@link JwtProcessorBuilder} that can be used to configure and construct the {@link JwtProcessor}
      */
+    @Nonnull
     public static JwtProcessorBuilder processor() {
         return new DefaultJwtProcessorBuilder();
     }

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JwtDecodeOnlyProcessorBuilder.java

@@ -2,4 +2,5 @@
 
 public interface JwtDecodeOnlyProcessorBuilder
         extends JwtDecodingProcessorBuilderBase<JwtDecodingProcessor, JwtDecodeOnlyProcessorBuilder> {
+
 }

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JwtDecodingProcessor.java

@@ -5,6 +5,8 @@
 import org.unbrokendome.jsonwebtoken.signature.JwsSignatureException;
 import org.unbrokendome.jsonwebtoken.signature.JwsUnsupportedAlgorithmException;
 
+import javax.annotation.Nonnull;
+
 
 /**
  * Decodes JSON Web Tokens.
@@ -51,6 +53,7 @@ public interface JwtDecodingProcessor extends JwtProcessorBase {
      *                                          for wrong signatures)
      * @throws IllegalArgumentException         if the payload could not be deserialized into the desired type
      */
+    @Nonnull
     <T> T decode(String encodedToken, Class<T> payloadType) throws JwtMalformedTokenException,
             JwsUnsupportedAlgorithmException, JwsSignatureException;
 

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JwtDecodingProcessorBuilderBase.java

@@ -6,6 +6,7 @@
 import org.unbrokendome.jsonwebtoken.signature.SignatureAlgorithms;
 import org.unbrokendome.jsonwebtoken.signature.VerificationKeyResolver;
 
+import javax.annotation.Nonnull;
 import java.security.Key;
 
 
@@ -30,6 +31,7 @@ public interface JwtDecodingProcessorBuilderBase<T extends JwtDecodingProcessor,
      * @param <TVerificationKey>      the type of the verification key; must be a subclass of {@link Key}
      * @return the current builder instance
      */
+    @Nonnull
     <TVerificationKey extends Key>
     B verifyWith(SignatureAlgorithm<?, TVerificationKey> algorithm,
                  VerificationKeyResolver<TVerificationKey> verificationKeyResolver);
@@ -44,6 +46,7 @@ B verifyWith(SignatureAlgorithm<?, TVerificationKey> algorithm,
      * @param <TVerificationKey> the type of the verification key; must be a subclass of {@link Key}
      * @return the current builder instance
      */
+    @Nonnull
     default <TVerificationKey extends Key>
     B verifyWith(SignatureAlgorithm<?, TVerificationKey> algorithm, TVerificationKey verificationKey) {
         return verifyWith(algorithm, (VerificationKeyResolver<TVerificationKey>) ((h, p) -> verificationKey));
@@ -56,9 +59,10 @@ B verifyWith(SignatureAlgorithm<?, TVerificationKey> algorithm, TVerificationKey
      * This overload does not take a key parameter, and is intended for the {@code NONE} algorithm (which is the only
      * algorithm that does not require a key for verification).
      *
-     * @param algorithm          the signature algorithm to use; usually {@link SignatureAlgorithms#NONE}
+     * @param algorithm the signature algorithm to use; usually {@link SignatureAlgorithms#NONE}
      * @return the current builder instance
      */
+    @Nonnull
     default B verifyWith(SignatureAlgorithm<?, NoneKey> algorithm) {
         return verifyWith(algorithm, NoneKey.getInstance());
     }
@@ -73,6 +77,6 @@ default B verifyWith(SignatureAlgorithm<?, NoneKey> algorithm) {
      * @param payloadDeserializer the custom {@link PayloadDeserializer} to register
      * @return the current builder instance
      */
+    @Nonnull
     B deserializePayloadWith(PayloadDeserializer<?> payloadDeserializer);
-
 }

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JwtEncodeOnlyProcessorBuilder.java

@@ -2,4 +2,5 @@
 
 public interface JwtEncodeOnlyProcessorBuilder
         extends JwtEncodingProcessorBuilderBase<JwtEncodingProcessor, JwtEncodeOnlyProcessorBuilder> {
+
 }

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JwtEncodingProcessor.java

@@ -2,6 +2,8 @@
 
 import org.unbrokendome.jsonwebtoken.signature.JwsSignatureException;
 
+import javax.annotation.Nonnull;
+
 
 /**
  * Encodes objects into JSON Web Tokens.
@@ -39,6 +41,7 @@ public interface JwtEncodingProcessor extends JwtProcessorBase {
      * @return the encoded JSON Web Token as a string
      * @throws JwsSignatureException if the signature for the token cannot be created
      */
+    @Nonnull
     String encode(Object payload) throws JwsSignatureException;
 
 
@@ -53,6 +56,7 @@ public interface JwtEncodingProcessor extends JwtProcessorBase {
      * @return the encoded JSON Web Token as a string
      * @throws IllegalStateException if the signature for the token cannot be created
      */
+    @Nonnull
     default String encodeUnchecked(Object payload) {
         try {
             return encode(payload);

jwt/src/main/java/org/unbrokendome/jsonwebtoken/JwtProcessor.java

@@ -22,4 +22,5 @@
  * All {@link JwtProcessor} instances are immutable and safe for use by concurrent threads.
  */
 public interface JwtProcessor extends JwtEncodingProcessor, JwtDecodingProcessor {
+
 }