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/common/PersistentEnumUserType.java |  113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 109 insertions(+), 4 deletions(-)

diff --git a/securis/src/main/java/net/curisit/securis/db/common/PersistentEnumUserType.java b/securis/src/main/java/net/curisit/securis/db/common/PersistentEnumUserType.java
index 19879f2..e11a355 100644
--- a/securis/src/main/java/net/curisit/securis/db/common/PersistentEnumUserType.java
+++ b/securis/src/main/java/net/curisit/securis/db/common/PersistentEnumUserType.java
@@ -1,3 +1,6 @@
+/*
+* Copyright @ 2013 CurisTEC, S.A.S. All Rights Reserved.
+*/
 package net.curisit.securis.db.common;
 
 import java.io.Serializable;
@@ -10,57 +13,150 @@
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 import org.hibernate.usertype.UserType;
 
+/**
+* PersistentEnumUserType
+* <p>
+* Base Hibernate {@link UserType} for enums implementing {@link CodedEnum}.
+* Stores the enum's <b>short code</b> (VARCHAR) and reconstructs the enum
+* from that code on load.
+*
+* Notes:
+* - SQL type is {@code VARCHAR}.
+* - Immutable by default ({@link #isMutable()} returns false).
+* - {@link #equals(Object, Object)} compares by reference (adequate for enums).
+*
+* @param <T> enum type implementing {@link CodedEnum}
+*
+* @author JRA
+* Last reviewed by JRA on Oct 7, 2025.
+*/
 public abstract class PersistentEnumUserType<T extends CodedEnum> implements UserType {
 
+    /** 
+     * assemble<p>
+     * Return cached value as-is (immutable semantics). 
+     * 
+     * @param cached
+     * @param owner
+     * @return assembleObject
+     * @throws HibernateException
+     */
     @Override
     public Object assemble(Serializable cached, Object owner) throws HibernateException {
         return cached;
     }
 
+    /** 
+     * deepCopy<p>
+     * Enums are immutable; return value as-is. 
+     * 
+     * @param value
+     * @return deepCopy
+     */
     @Override
     public Object deepCopy(Object value) throws HibernateException {
         return value;
     }
 
+    /** 
+     * disassemble<p>
+     * Return value for 2nd-level cache.
+     * 
+     * @param value
+     * @return disassembleObject
+     * @throw HibernateException
+     */
     @Override
     public Serializable disassemble(Object value) throws HibernateException {
         return (Serializable) value;
     }
 
+    /** 
+     * equals<p>
+     * Reference equality is fine for enums.
+     * 
+     * @param x
+     * @param y
+     * @param isEqual
+     * @throws HibernateException
+     */
     @Override
     public boolean equals(Object x, Object y) throws HibernateException {
         return x == y;
     }
 
+    /** 
+     * hashCode<p>
+     * Delegate to value hashCode; 0 for null. 
+     * 
+     * @param object
+     * @return hashCode
+     * @throws HibernateException
+     */
     @Override
     public int hashCode(Object x) throws HibernateException {
         return x == null ? 0 : x.hashCode();
     }
 
+    /** 
+     * isMutable<p>
+     * Enums are immutable. 
+     * 
+     * @return isMutable
+     */
     @Override
     public boolean isMutable() {
         return false;
     }
 
+    /** 
+     * replace<p>
+     * Immutable; return original. 
+     * 
+     * @param original
+     * @param target
+     * @param owner
+     * @return object
+     * @throws HibernateException
+     */
     @Override
     public Object replace(Object original, Object target, Object owner) throws HibernateException {
         return original;
     }
 
+    /** 
+     * returnedClass<p>
+     * Concrete types must provide the enum class. 
+     */
     @Override
     public abstract Class<T> returnedClass();
 
+    /** 
+     * sqlTypes<p>
+     * Persist as single VARCHAR column
+     * 
+     * @return sqlTypes
+     */
     @Override
     public int[] sqlTypes() {
-        return new int[] {
-            Types.VARCHAR
-        };
+        return new int[] { Types.VARCHAR };
     }
 
+    /**
+    * nullSafeGet<p>
+    * Read code from result set and map to the corresponding enum constant.
+    *
+    * @param resultSet
+    * @param names
+    * @param session
+    * @param owner
+    * @return enum instance or null if DB value is null or code not matched
+    */
     @Override
     public Object nullSafeGet(ResultSet rs, String[] names, SharedSessionContractImplementor session, Object owner)
             throws HibernateException, SQLException {
         String code = rs.getString(names[0]);
+        if (code == null) return null;
         for (CodedEnum en : returnedClass().getEnumConstants()) {
             if (en.getCode().equals(code)) {
                 return en;
@@ -69,6 +165,15 @@
         return null;
     }
 
+    /**
+    * nullSafeSet<p>
+    * Write enum code as VARCHAR or set NULL if value is null.
+    * 
+    * @param statement
+    * @param value
+    * @param index
+    * @param session
+    */
     @Override
     public void nullSafeSet(PreparedStatement st, Object value, int index, SharedSessionContractImplementor session)
             throws HibernateException, SQLException {
@@ -78,5 +183,5 @@
             st.setString(index, ((CodedEnum) value).getCode());
         }
     }
-
 }
+

--
Gitblit v1.3.2