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/db/BlockedRequest.java |  123 ++++++++++++++++++++++++++++++++--------
 1 files changed, 97 insertions(+), 26 deletions(-)

diff --git a/securis/src/main/java/net/curisit/securis/db/BlockedRequest.java b/securis/src/main/java/net/curisit/securis/db/BlockedRequest.java
index 74f562b..c2fc300 100644
--- a/securis/src/main/java/net/curisit/securis/db/BlockedRequest.java
+++ b/securis/src/main/java/net/curisit/securis/db/BlockedRequest.java
@@ -1,3 +1,6 @@
+/*
+* Copyright @ 2013 CurisTEC, S.A.S. All Rights Reserved.
+*/
 package net.curisit.securis.db;
 
 import java.io.Serializable;
@@ -21,9 +24,20 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * Entity implementation class for Entity: pack
- * 
- */
+* BlockedRequest
+* <p>
+* Persistent record marking a request (by hash) as blocked.
+* Primary key is the SHA-256 of the original request_data.
+* Useful to avoid replay/duplicate processing.
+*
+* Mapping details:
+* - Table: blocked_request
+* - PK: hash (SHA-256(request_data))
+* - Optional relation 'blockedBy' for auditing.
+*
+* @author JRA
+* Last reviewed by JRA on Oct 7, 2025.
+*/
 @JsonAutoDetect
 @JsonInclude(Include.NON_NULL)
 @Entity
@@ -33,69 +47,126 @@
 
     private static final long serialVersionUID = 1L;
 
+    /** Unique SHA-256 hash of {@link #requestData}. */
     @Id
     private String hash;
 
+    /** Original request payload. */
     @Column(name = "request_data")
     @JsonProperty("request_data")
     private String requestData;
 
+    /** Server-side creation timestamp. */
     @Column(name = "creation_timestamp")
     @JsonProperty("creation_timestamp")
     private Date creationTimestamp;
 
+    /** User who blocked this request (optional, auditing). */
     @JsonIgnore
     @ManyToOne
     @JoinColumn(name = "blocked_by")
     private User blockedBy;
 
-    public Date getCreationTimestamp() {
-        return creationTimestamp;
-    }
+    // ---------------------------------------------------------------------
+    // Getters & setters
+    // ---------------------------------------------------------------------
 
-    public void setCreationTimestamp(Date creationTimestamp) {
-        this.creationTimestamp = creationTimestamp;
-    }
+    /**
+    * getCreationTimestamp<p>
+    * Get the creation timestamp.
+    *
+    * @return creationTimestamp
+    */
+    public Date getCreationTimestamp() { return creationTimestamp; }
 
+    /**
+    * setCreationTimestamp<p>
+    * Set the creation timestamp.
+    *
+    * @param creationTimestamp
+    */
+    public void setCreationTimestamp(Date creationTimestamp) { this.creationTimestamp = creationTimestamp; }
+
+    /**
+    * equals<p>
+    * Identity based on primary key (hash).
+    */
     @Override
     public boolean equals(Object obj) {
-        if (!(obj instanceof BlockedRequest))
-            return false;
+        if (!(obj instanceof BlockedRequest)) return false;
         BlockedRequest other = (BlockedRequest) obj;
-        return (hash == null && other.hash == null) || hash.equals(other.hash);
+        return (hash == null && other.hash == null) || (hash != null && hash.equals(other.hash));
     }
 
+    /**
+    * hashCode<p>
+    * Hash based on primary key (hash).
+    */
     @Override
-    public int hashCode() {
+    public int hashCode() { return (hash == null ? 0 : hash.hashCode()); }
 
-        return (hash == null ? 0 : hash.hashCode());
-    }
+    /**
+    * getRequestData<p>
+    * Get the original serialized request data.
+    *
+    * @return requestData
+    */
+    public String getRequestData() { return requestData; }
 
-    public String getRequestData() {
-        return requestData;
-    }
-
+    /**
+    * setRequestData<p>
+    * Set the original request data and recompute the PK hash immediately.
+    * Hash is computed as SHA-256 over the request string.
+    *
+    * @param requestData
+    */
     public void setRequestData(String requestData) {
         this.requestData = requestData;
         this.hash = generateHash(this.requestData);
     }
 
-    public User getBlockedBy() {
-        return blockedBy;
-    }
+    /**
+    * getBlockedBy<p>
+    * Return the user who blocked this request (if any).
+    *
+    * @return blockedBy
+    */
+    public User getBlockedBy() { return blockedBy; }
 
-    public void setBlockedBy(User blockedBy) {
-        this.blockedBy = blockedBy;
-    }
+    /**
+    * setBlockedBy<p>
+    * Set the user who blocked this request.
+    *
+    * @param blockedBy
+    */
+    public void setBlockedBy(User blockedBy) { this.blockedBy = blockedBy; }
 
+    // ---------------------------------------------------------------------
+    // Static helpers
+    // ---------------------------------------------------------------------
+
+    /**
+    * generateHash<p>
+    * Compute the SHA-256 hex string for the given request data.
+    *
+    * @param reqData
+    * @return sha256(reqData) or null if reqData is null
+    */
     public static String generateHash(String reqData) {
         return (reqData != null ? Utils.sha256(reqData) : null);
     }
 
+    /**
+    * isRequestBlocked<p>
+    * Check if a request payload is blocked by looking up its hash as the PK.
+    *
+    * @param requestData original payload
+    * @param em JPA entity manager
+    * @return true if an entry exists with the same hash
+    */
     public static boolean isRequestBlocked(String requestData, EntityManager em) {
         String hash = generateHash(requestData);
         BlockedRequest br = em.find(BlockedRequest.class, hash);
         return br != null;
     }
-
 }

--
Gitblit v1.3.2