From 91dd4ed9a9e478b5c941b0ceda95f1d533b762c2 Mon Sep 17 00:00:00 2001 From: Jorge Solorzano Date: Tue, 16 Jun 2026 15:07:14 +0200 Subject: [PATCH] fix: normalize exceptions signatures and javadocs Signed-off-by: Jorge Solorzano --- checks/pmd-ruleset.xml | 1 + .../scram/client/ChannelBindingException.java | 18 +++++++++++++---- .../client/MechanismNegotiationException.java | 16 ++++++++++++--- .../common/exception/ScramException.java | 19 +++++++++--------- .../exception/ScramInterruptedException.java | 18 ++++++++--------- .../ScramInvalidServerSignatureException.java | 20 +++++++++---------- .../common/exception/ScramParseException.java | 19 +++++++++--------- .../exception/ScramRuntimeException.java | 19 +++++++++--------- .../exception/ScramServerErrorException.java | 13 ++++++++++-- .../common/exception/ServerErrorValue.java | 15 +++++++------- 10 files changed, 96 insertions(+), 62 deletions(-) diff --git a/checks/pmd-ruleset.xml b/checks/pmd-ruleset.xml index b18b4b1..f27fe38 100644 --- a/checks/pmd-ruleset.xml +++ b/checks/pmd-ruleset.xml @@ -39,6 +39,7 @@ + diff --git a/scram-client/src/main/java/com/ongres/scram/client/ChannelBindingException.java b/scram-client/src/main/java/com/ongres/scram/client/ChannelBindingException.java index 226655b..c099154 100644 --- a/scram-client/src/main/java/com/ongres/scram/client/ChannelBindingException.java +++ b/scram-client/src/main/java/com/ongres/scram/client/ChannelBindingException.java @@ -10,7 +10,7 @@ * enforcement of SASL SCRAM Channel Binding. * *

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); + } } diff --git a/scram-client/src/main/java/com/ongres/scram/client/MechanismNegotiationException.java b/scram-client/src/main/java/com/ongres/scram/client/MechanismNegotiationException.java index 4c6d642..e897555 100644 --- a/scram-client/src/main/java/com/ongres/scram/client/MechanismNegotiationException.java +++ b/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); + } } diff --git a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramException.java b/scram-common/src/main/java/com/ongres/scram/common/exception/ScramException.java index fb7f570..4b11552 100644 --- a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramException.java +++ b/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); } } diff --git a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramInterruptedException.java b/scram-common/src/main/java/com/ongres/scram/common/exception/ScramInterruptedException.java index 4082617..66597f1 100644 --- a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramInterruptedException.java +++ b/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); } } diff --git a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramInvalidServerSignatureException.java b/scram-common/src/main/java/com/ongres/scram/common/exception/ScramInvalidServerSignatureException.java index d3517da..eb8de72 100644 --- a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramInvalidServerSignatureException.java +++ b/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); } } diff --git a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramParseException.java b/scram-common/src/main/java/com/ongres/scram/common/exception/ScramParseException.java index 64e19e6..06e0fb3 100644 --- a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramParseException.java +++ b/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); } } diff --git a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramRuntimeException.java b/scram-common/src/main/java/com/ongres/scram/common/exception/ScramRuntimeException.java index 42a77c8..1f5aa90 100644 --- a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramRuntimeException.java +++ b/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); } } diff --git a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramServerErrorException.java b/scram-common/src/main/java/com/ongres/scram/common/exception/ScramServerErrorException.java index 1d055ca..6cd97ca 100644 --- a/scram-common/src/main/java/com/ongres/scram/common/exception/ScramServerErrorException.java +++ b/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. * diff --git a/scram-common/src/main/java/com/ongres/scram/common/exception/ServerErrorValue.java b/scram-common/src/main/java/com/ongres/scram/common/exception/ServerErrorValue.java index fc7c8f6..f2a25ce 100644 --- a/scram-common/src/main/java/com/ongres/scram/common/exception/ServerErrorValue.java +++ b/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 ERROR_MESSAGE = initServerErrorValue(); + private static final Map ERROR_MESSAGE = buildErrorMessages(); private ServerErrorValue() { throw new IllegalStateException(); } - private static ConcurrentMap initServerErrorValue() { - ConcurrentMap map = new ConcurrentHashMap<>(); + private static Map buildErrorMessages() { + Map 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 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);