fix: normalize exceptions signatures and javadocs

checks/pmd-ruleset.xml

@@ -39,6 +39,7 @@
 
   <rule ref="category/java/multithreading.xml">
     <exclude name="DoNotUseThreads" />
+    <exclude name="UseConcurrentHashMap" />
   </rule>
 
   <rule ref="category/java/performance.xml">

scram-client/src/main/java/com/ongres/scram/client/ChannelBindingException.java

@@ -10,7 +10,7 @@
  * enforcement of SASL SCRAM Channel Binding.
  *
  * <p>This exception typically indicates a mismatch between the client's configured
- * {@code ChannelBindingPolicy} and the server's advertised mechanisms, or a failure
+ * {@link ChannelBindingPolicy} and the server's advertised mechanisms, or a failure
  * in processing cryptographic channel binding data (e.g., TLS server endpoint data).
  *
  * @since 3.3
@@ -22,10 +22,20 @@ public class ChannelBindingException extends MechanismNegotiationException {
   /**
    * Constructs a new {@code ChannelBindingException} with the specified detail message.
    *
-   * @param detail the detail message explaining the cause of the negotiation failure.
+   * @param message A String containing details about the exception
    */
-  public ChannelBindingException(String detail) {
-    super(detail);
+  public ChannelBindingException(String message) {
+    super(message);
   }
 
+  /**
+   * Constructs a new {@code ChannelBindingException} with the specified detail message and cause.
+   *
+   * @param message the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
+   * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method).
+   *        (A null value is permitted,and indicates that the cause is nonexistent or unknown.)
+   */
+  public ChannelBindingException(String message, Throwable cause) {
+    super(message, cause);
+  }
 }

scram-client/src/main/java/com/ongres/scram/client/MechanismNegotiationException.java

@@ -25,10 +25,20 @@ public class MechanismNegotiationException extends ScramRuntimeException {
   /**
    * Constructs a new {@code MechanismNegotiationException} with the specified detail message.
    *
-   * @param detail the detail message explaining the cause of the negotiation failure.
+   * @param message A String containing details about the exception
    */
-  public MechanismNegotiationException(String detail) {
-    super(detail);
+  public MechanismNegotiationException(String message) {
+    super(message);
   }
 
+  /**
+   * Constructs a new {@code MechanismNegotiationException} with the specified detail message and cause.
+   *
+   * @param message the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
+   * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method).
+   *        (A null value is permitted,and indicates that the cause is nonexistent or unknown.)
+   */
+  public MechanismNegotiationException(String message, Throwable cause) {
+    super(message, cause);
+  }
 }

scram-common/src/main/java/com/ongres/scram/common/exception/ScramException.java

@@ -13,21 +13,22 @@ public class ScramException extends Exception {
   private static final long serialVersionUID = 1L;
 
   /**
-   * Constructs a new instance of ScramException with a detailed message.
+   * Constructs a new {@code ScramException} with the specified detail message.
    *
-   * @param detail A String containing details about the exception
+   * @param message A String containing details about the exception
    */
-  public ScramException(String detail) {
-    super(detail);
+  public ScramException(String message) {
+    super(message);
   }
 
   /**
-   * Constructs a new instance of ScramException with a detailed message and a root cause.
+   * Constructs a new {@code ScramException} with the specified detail message and cause.
    *
-   * @param detail A String containing details about the exception
-   * @param ex The root exception
+   * @param message the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
+   * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method).
+   *        (A null value is permitted,and indicates that the cause is nonexistent or unknown.)
    */
-  public ScramException(String detail, Throwable ex) {
-    super(detail, ex);
+  public ScramException(String message, Throwable cause) {
+    super(message, cause);
   }
 }

scram-common/src/main/java/com/ongres/scram/common/exception/ScramInterruptedException.java

@@ -27,20 +27,20 @@ public class ScramInterruptedException extends ScramRuntimeException {
   /**
    * Constructs a new {@code ScramInterruptedException} with the specified detail message.
    *
-   * @param detail the detail message explaining the context of the interruption.
+   * @param message A String containing details about the exception
    */
-  public ScramInterruptedException(String detail) {
-    super(detail);
+  public ScramInterruptedException(String message) {
+    super(message);
   }
 
   /**
-   * Constructs a new {@code ScramInterruptedException} with the specified detail
-   * message and the underlying cause.
+   * Constructs a new {@code ScramInterruptedException} with the specified detail message and cause.
    *
-   * @param detail the detail message explaining the context.
-   * @param ex the cause (which is saved for later retrieval by the {@link #getCause()} method).
+   * @param message the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
+   * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method).
+   *        (A null value is permitted,and indicates that the cause is nonexistent or unknown.)
    */
-  public ScramInterruptedException(String detail, Throwable ex) {
-    super(detail, ex);
+  public ScramInterruptedException(String message, Throwable cause) {
+    super(message, cause);
   }
 }

scram-common/src/main/java/com/ongres/scram/common/exception/ScramInvalidServerSignatureException.java

@@ -17,22 +17,22 @@ public class ScramInvalidServerSignatureException extends ScramException {
   private static final long serialVersionUID = 1L;
 
   /**
-   * Constructs a new instance of ScramInvalidServerSignatureException with a detailed message.
+   * Constructs a new {@code ScramInvalidServerSignatureException} with the specified detail message.
    *
-   * @param detail A String containing details about the exception
+   * @param message A String containing details about the exception
    */
-  public ScramInvalidServerSignatureException(String detail) {
-    super(detail);
+  public ScramInvalidServerSignatureException(String message) {
+    super(message);
   }
 
   /**
-   * Constructs a new instance of ScramInvalidServerSignatureException with a detailed message and a
-   * root cause.
+   * Constructs a new {@code ScramInvalidServerSignatureException} with the specified detail message and cause.
    *
-   * @param detail A String containing details about the exception
-   * @param ex The root exception
+   * @param message the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
+   * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method).
+   *        (A null value is permitted,and indicates that the cause is nonexistent or unknown.)
    */
-  public ScramInvalidServerSignatureException(String detail, Throwable ex) {
-    super(detail, ex);
+  public ScramInvalidServerSignatureException(String message, Throwable cause) {
+    super(message, cause);
   }
 }

scram-common/src/main/java/com/ongres/scram/common/exception/ScramParseException.java

@@ -13,21 +13,22 @@ public class ScramParseException extends ScramException {
   private static final long serialVersionUID = 1L;
 
   /**
-   * Constructs a new instance of ScramParseException with a detailed message.
+   * Constructs a new {@code ScramParseException} with the specified detail message.
    *
-   * @param detail A String containing details about the exception
+   * @param message A String containing details about the exception
    */
-  public ScramParseException(String detail) {
-    super(detail);
+  public ScramParseException(String message) {
+    super(message);
   }
 
   /**
-   * Constructs a new instance of ScramParseException with a detailed message and a root cause.
+   * Constructs a new {@code ScramParseException} with the specified detail message and cause.
    *
-   * @param detail A String containing details about the exception
-   * @param ex The root exception
+   * @param message the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
+   * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method).
+   *        (A null value is permitted,and indicates that the cause is nonexistent or unknown.)
    */
-  public ScramParseException(String detail, Throwable ex) {
-    super(detail, ex);
+  public ScramParseException(String message, Throwable cause) {
+    super(message, cause);
   }
 }

scram-common/src/main/java/com/ongres/scram/common/exception/ScramRuntimeException.java

@@ -13,21 +13,22 @@ public class ScramRuntimeException extends RuntimeException {
   private static final long serialVersionUID = 1L;
 
   /**
-   * Constructs a new instance of ScramRuntimeException with a detailed message.
+   * Constructs a new {@code ScramRuntimeException} with the specified detail message.
    *
-   * @param detail A String containing details about the exception
+   * @param message A String containing details about the exception
    */
-  public ScramRuntimeException(String detail) {
-    super(detail);
+  public ScramRuntimeException(String message) {
+    super(message);
   }
 
   /**
-   * Constructs a new instance of ScramRuntimeException with a detailed message and a root cause.
+   * Constructs a new {@code ScramRuntimeException} with the specified detail message and cause.
    *
-   * @param detail A String containing details about the exception
-   * @param ex The root exception
+   * @param message the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
+   * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method).
+   *        (A null value is permitted,and indicates that the cause is nonexistent or unknown.)
    */
-  public ScramRuntimeException(String detail, Throwable ex) {
-    super(detail, ex);
+  public ScramRuntimeException(String message, Throwable cause) {
+    super(message, cause);
   }
 }

scram-common/src/main/java/com/ongres/scram/common/exception/ScramServerErrorException.java

@@ -27,7 +27,7 @@ public class ScramServerErrorException extends ScramException {
    * @param serverError The SCRAM error in the message
    */
   public ScramServerErrorException(String serverError) {
-    super(ServerErrorValue.getErrorMessage(serverError));
+    super(buildMessage(serverError));
     this.serverError = serverError;
   }
 
@@ -39,10 +39,19 @@ public ScramServerErrorException(String serverError) {
    * @param ex The root exception
    */
   public ScramServerErrorException(String serverError, Throwable ex) {
-    super(ServerErrorValue.getErrorMessage(serverError), ex);
+    super(buildMessage(serverError), ex);
     this.serverError = serverError;
   }
 
+  private static String buildMessage(String serverError) {
+    String description = ServerErrorValue.getErrorMessage(serverError);
+    if (description != null) {
+      return serverError + ": " + description;
+    }
+    String otherError = ServerErrorValue.getErrorMessage("other-error");
+    return serverError + ": " + otherError;
+  }
+
   /**
    * Return the "e=" server-error-value from the server-final-message.
    *

scram-common/src/main/java/com/ongres/scram/common/exception/ServerErrorValue.java

@@ -5,8 +5,9 @@
 
 package com.ongres.scram.common.exception;
 
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.ConcurrentMap;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
 
 /**
  * This attribute specifies an error that occurred during authentication exchange. It is sent by the
@@ -15,14 +16,14 @@
  */
 public final class ServerErrorValue {
 
-  private static final ConcurrentMap<String, String> ERROR_MESSAGE = initServerErrorValue();
+  private static final Map<String, String> ERROR_MESSAGE = buildErrorMessages();
 
   private ServerErrorValue() {
     throw new IllegalStateException();
   }
 
-  private static ConcurrentMap<String, String> initServerErrorValue() {
-    ConcurrentMap<String, String> map = new ConcurrentHashMap<>();
+  private static Map<String, String> buildErrorMessages() {
+    Map<String, String> map = new HashMap<>(16);
     map.put("invalid-encoding", "The message format or encoding is incorrect");
     map.put("extensions-not-supported", "Requested extensions are not recognized by the server");
     map.put("invalid-proof", "The client-provided proof is invalid");
@@ -38,14 +39,14 @@ private static ConcurrentMap<String, String> initServerErrorValue() {
         "The username encoding is invalid (either invalid UTF-8 or SASLprep failure)");
     map.put("no-resources", "The server lacks resources to process the request");
     map.put("other-error", "A generic error occurred that doesn't fit into other categories");
-    return map;
+    return Collections.unmodifiableMap(map);
   }
 
   /**
    * This get the error message used in a {@link ScramServerErrorException}.
    *
    * @param errorValue the {@code server-error-value} send by the server
-   * @return String with a user friendly message about the error
+   * @return String with a user friendly message about the error, or {@code null} if not recognized
    */
   public static String getErrorMessage(String errorValue) {
     return ERROR_MESSAGE.get(errorValue);