Enhance documentation and add a logging statement for outdated jjwt l…

…ibraries

src/main/java/org/kohsuke/github/extras/authorization/JwtBuilderUtil.java

@@ -4,18 +4,48 @@
 import java.security.PrivateKey;
 import java.time.Instant;
 import java.util.Date;
+import java.util.logging.Logger;
 
 import io.jsonwebtoken.JwtBuilder;
 import io.jsonwebtoken.Jwts;
 import io.jsonwebtoken.SignatureAlgorithm;
 import io.jsonwebtoken.jackson.io.JacksonSerializer;
 
+/**
+ * This is a util to build a JWT.
+ *
+ * <p>
+ * This class is used to build a JWT using the jjwt library. It uses reflection
+ * to support older versions of jjwt. The class may be removed again, once we
+ * are sure, we do no longer need to support pre-0.12.x versions of jjwt.
+ * </p>
+ */
 final class JwtBuilderUtil {
+
+    private static final Logger LOGGER = Logger.getLogger(JwtBuilderUtil.class.getName());
+
+    /**
+     * Get a method from an object.
+     *
+     * @param obj    object
+     * @param method method name
+     * @param params parameters of the method
+     * @return method
+     * @throws NoSuchMethodException if the method does not exist
+     */
     private static Method getMethod(Object obj, String method, Class<?>... params) throws NoSuchMethodException {
         Class<?> type = obj.getClass();
         return type.getMethod(method, params);
     }
 
+    /**
+     * Check if an object has a method.
+     *
+     * @param obj    object
+     * @param method method name
+     * @param params parameters of the method
+     * @return true if the method exists
+     */
     private static boolean hasMethod(Object obj, String method, Class<?>... params) {
         try {
             return JwtBuilderUtil.getMethod(obj, method, params) != null;
@@ -24,6 +54,15 @@ private static boolean hasMethod(Object obj, String method, Class<?>... params)
         }
     }
 
+    /**
+     * Build a JWT.
+     *
+     * @param issuedAt      issued at
+     * @param expiration    expiration
+     * @param applicationId application id
+     * @param privateKey    private key
+     * @return JWT
+     */
     static String buildJwt(Instant issuedAt, Instant expiration, String applicationId, PrivateKey privateKey) {
         JwtBuilder jwtBuilder = Jwts.builder();
         if (JwtBuilderUtil.hasMethod(jwtBuilder, "issuedAt", Date.class)) {
@@ -34,16 +73,31 @@ static String buildJwt(Instant issuedAt, Instant expiration, String applicationI
             return jwtBuilder.json(new JacksonSerializer<>()).compact();
         }
 
+        LOGGER.warning(
+                "You are using an outdated version of the io.jsonwebtoken:jjwt-* suite. Please consider an update.");
+
         // older jjwt library versions
         try {
             return JwtBuilderUtil.buildByReflection(jwtBuilder, issuedAt, expiration, applicationId, privateKey);
         } catch (ReflectiveOperationException e) {
             throw new JwtReflectiveBuilderException(
-                    "Exception building a JWT with reflective access to outdated versions of jjwt. Please consider an update.",
+                    "Exception building a JWT with reflective access to outdated versions of the io.jsonwebtoken:jjwt-* suite. Please consider an update.",
                     e);
         }
     }
 
+    /**
+     * This method builds a JWT using older (pre 0.12.x) versions of jjwt library by
+     * leveraging reflection.
+     *
+     * @param jwtBuilder    builder object
+     * @param issuedAt      issued at
+     * @param expiration    expiration
+     * @param applicationId application id
+     * @param privateKey    private key
+     * @return JWT
+     * @throws ReflectiveOperationException if reflection fails
+     */
     private static String buildByReflection(JwtBuilder jwtBuilder, Instant issuedAt, Instant expiration,
             String applicationId,
             PrivateKey privateKey) throws ReflectiveOperationException {