From 146a0fb8b0e90f9196e569152f649baf60d6cc8f Mon Sep 17 00:00:00 2001
From: Joaquín Reñé <jrene@curisit.net>
Date: Tue, 07 Oct 2025 14:52:57 +0000
Subject: [PATCH] #4410 - Comments on classes

---
 securis/src/main/java/net/curisit/securis/services/exception/SeCurisServiceException.java |  111 +++++++++++++++++++++++++++++++++++++------------------
 1 files changed, 75 insertions(+), 36 deletions(-)

diff --git a/securis/src/main/java/net/curisit/securis/services/exception/SeCurisServiceException.java b/securis/src/main/java/net/curisit/securis/services/exception/SeCurisServiceException.java
index bfe790c..e44e944 100644
--- a/securis/src/main/java/net/curisit/securis/services/exception/SeCurisServiceException.java
+++ b/securis/src/main/java/net/curisit/securis/services/exception/SeCurisServiceException.java
@@ -1,51 +1,90 @@
+/*
+ * Copyright @ 2013 CurisTEC, S.A.S. All Rights Reserved.
+ */
 package net.curisit.securis.services.exception;
 
 import net.curisit.integrity.exception.CurisException;
 
+/**
+ * SeCurisServiceException
+ * <p>
+ * Checked exception for service-layer errors with an attached numeric error code.
+ * Extends {@link CurisException} and is intended to be translated to HTTP responses
+ * by upstream exception mappers/handlers.
+ *
+ * Usage:
+ *  - Prefer specific {@code ErrorCodes.*} when throwing.
+ *  - Use the single-arg constructor to default to UNEXPECTED_ERROR.
+ *  
+ *  @author JRA
+ * Last reviewed by JRA on Oct 5, 2025.
+ */
 public class SeCurisServiceException extends CurisException {
 
-	private int errorCode = 0;
+    /** Numeric error code associated with this exception. */
+    private int errorCode = 0;
 
-	public SeCurisServiceException(int errorCode, String msg) {
-		super(msg);
-		this.errorCode = errorCode;
-	}
+    /**
+     * Constructor with explicit error code.
+     *
+     * @param errorCode See {@link ErrorCodes}.
+     * @param msg       Human-readable message (safe to expose).
+     */
+    public SeCurisServiceException(int errorCode, String msg) {
+        super(msg);
+        this.errorCode = errorCode;
+    }
 
-	public SeCurisServiceException(String msg) {
-		super(msg);
-		this.errorCode = ErrorCodes.UNEXPECTED_ERROR;
-	}
+    /**
+     * Constructor defaulting to {@link ErrorCodes#UNEXPECTED_ERROR}.
+     *
+     * @param msg Human-readable message (safe to expose).
+     */
+    public SeCurisServiceException(String msg) {
+        super(msg);
+        this.errorCode = ErrorCodes.UNEXPECTED_ERROR;
+    }
 
-	public int getStatus() {
-		return errorCode;
-	}
+    /**
+     * getStatus
+     * <p>
+     * Returns the stored numeric error code.
+     *
+     * @return integer error code.
+     */
+    public int getStatus() {
+        return errorCode;
+    }
 
-	/**
-	 * 
-	 */
-	private static final long serialVersionUID = 1L;
+    private static final long serialVersionUID = 1L;
 
-	public static class ErrorCodes {
-		public static int UNEXPECTED_ERROR = 1000;
-		public static int INVALID_CREDENTIALS = 1001;
-		public static int UNAUTHORIZED_ACCESS = 1002;
-		public static int NOT_FOUND = 1003;
-		public static int INVALID_FORMAT = 1004;
-		public static int WRONG_STATUS = 1005;
-		public static int UNNECESSARY_RENEW = 1006;
+    /**
+     * ErrorCodes
+     * <p>
+     * Canonical set of service-layer error codes.
+     * Grouped by feature areas (1000 generic, 11xx license, 12xx request data, 13xx validation).
+     */
+    public static class ErrorCodes {
+        public static int UNEXPECTED_ERROR = 1000;
+        public static int INVALID_CREDENTIALS = 1001;
+        public static int UNAUTHORIZED_ACCESS = 1002;
+        public static int NOT_FOUND = 1003;
+        public static int INVALID_FORMAT = 1004;
+        public static int WRONG_STATUS = 1005;
+        public static int UNNECESSARY_RENEW = 1006;
 
-		public static int INVALID_LICENSE_REQUEST_DATA = 1100;
-		public static int LICENSE_NOT_READY_FOR_RENEW = 1101;
-		public static int LICENSE_DATA_IS_NOT_VALID = 1102;
-		public static int LICENSE_IS_EXPIRED = 1103;
-		public static int LICENSE_PACK_IS_NOT_VALID = 1104;
+        public static int INVALID_LICENSE_REQUEST_DATA = 1100;
+        public static int LICENSE_NOT_READY_FOR_RENEW = 1101;
+        public static int LICENSE_DATA_IS_NOT_VALID = 1102;
+        public static int LICENSE_IS_EXPIRED = 1103;
+        public static int LICENSE_PACK_IS_NOT_VALID = 1104;
 
-		public static int INVALID_REQUEST_DATA = 1201;
-		public static int INVALID_REQUEST_DATA_FORMAT = 1202;
-		public static int BLOCKED_REQUEST_DATA = 1203;
-		public static int DUPLICATED_REQUEST_DATA = 1204;
-		public static int NO_AVAILABLE_LICENSES = 1205;
+        public static int INVALID_REQUEST_DATA = 1201;
+        public static int INVALID_REQUEST_DATA_FORMAT = 1202;
+        public static int BLOCKED_REQUEST_DATA = 1203;
+        public static int DUPLICATED_REQUEST_DATA = 1204;
+        public static int NO_AVAILABLE_LICENSES = 1205;
 
-		public static int INVALID_DATA = 1301;
-	}
+        public static int INVALID_DATA = 1301;
+    }
 }

--
Gitblit v1.3.2