#4410 - Comments on classes

Joaquín Reñé

2025-10-07 146a0fb8b0e90f9196e569152f649baf60d6cc8f

 securis/src/main/java/net/curisit/securis/db/common/PersistentEnumUserType.java
..
..
@@ -1,3 +1,6 @@
1
+/*
2
+* Copyright @ 2013 CurisTEC, S.A.S. All Rights Reserved.
3
+*/
1
4
 package net.curisit.securis.db.common;
2
5
 
3
6
 import java.io.Serializable;
..
..
@@ -10,57 +13,150 @@
10
13
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
11
14
 import org.hibernate.usertype.UserType;
12
15
 
16
+/**
17
+* PersistentEnumUserType
18
+* <p>
19
+* Base Hibernate {@link UserType} for enums implementing {@link CodedEnum}.
20
+* Stores the enum's <b>short code</b> (VARCHAR) and reconstructs the enum
21
+* from that code on load.
22
+*
23
+* Notes:
24
+* - SQL type is {@code VARCHAR}.
25
+* - Immutable by default ({@link #isMutable()} returns false).
26
+* - {@link #equals(Object, Object)} compares by reference (adequate for enums).
27
+*
28
+* @param <T> enum type implementing {@link CodedEnum}
29
+*
30
+* @author JRA
31
+* Last reviewed by JRA on Oct 7, 2025.
32
+*/
13
33
 public abstract class PersistentEnumUserType<T extends CodedEnum> implements UserType {
14
34
 
35
+    /** 
36
+     * assemble<p>
37
+     * Return cached value as-is (immutable semantics). 
38
+     * 
39
+     * @param cached
40
+     * @param owner
41
+     * @return assembleObject
42
+     * @throws HibernateException
43
+     */
15
44
     @Override
16
45
     public Object assemble(Serializable cached, Object owner) throws HibernateException {
17
46
         return cached;
18
47
     }
19
48
 
49
+    /** 
50
+     * deepCopy<p>
51
+     * Enums are immutable; return value as-is. 
52
+     * 
53
+     * @param value
54
+     * @return deepCopy
55
+     */
20
56
     @Override
21
57
     public Object deepCopy(Object value) throws HibernateException {
22
58
         return value;
23
59
     }
24
60
 
61
+    /** 
62
+     * disassemble<p>
63
+     * Return value for 2nd-level cache.
64
+     * 
65
+     * @param value
66
+     * @return disassembleObject
67
+     * @throw HibernateException
68
+     */
25
69
     @Override
26
70
     public Serializable disassemble(Object value) throws HibernateException {
27
71
         return (Serializable) value;
28
72
     }
29
73
 
74
+    /** 
75
+     * equals<p>
76
+     * Reference equality is fine for enums.
77
+     * 
78
+     * @param x
79
+     * @param y
80
+     * @param isEqual
81
+     * @throws HibernateException
82
+     */
30
83
     @Override
31
84
     public boolean equals(Object x, Object y) throws HibernateException {
32
85
         return x == y;
33
86
     }
34
87
 
88
+    /** 
89
+     * hashCode<p>
90
+     * Delegate to value hashCode; 0 for null. 
91
+     * 
92
+     * @param object
93
+     * @return hashCode
94
+     * @throws HibernateException
95
+     */
35
96
     @Override
36
97
     public int hashCode(Object x) throws HibernateException {
37
98
         return x == null ? 0 : x.hashCode();
38
99
     }
39
100
 
101
+    /** 
102
+     * isMutable<p>
103
+     * Enums are immutable. 
104
+     * 
105
+     * @return isMutable
106
+     */
40
107
     @Override
41
108
     public boolean isMutable() {
42
109
         return false;
43
110
     }
44
111
 
112
+    /** 
113
+     * replace<p>
114
+     * Immutable; return original. 
115
+     * 
116
+     * @param original
117
+     * @param target
118
+     * @param owner
119
+     * @return object
120
+     * @throws HibernateException
121
+     */
45
122
     @Override
46
123
     public Object replace(Object original, Object target, Object owner) throws HibernateException {
47
124
         return original;
48
125
     }
49
126
 
127
+    /** 
128
+     * returnedClass<p>
129
+     * Concrete types must provide the enum class. 
130
+     */
50
131
     @Override
51
132
     public abstract Class<T> returnedClass();
52
133
 
134
+    /** 
135
+     * sqlTypes<p>
136
+     * Persist as single VARCHAR column
137
+     * 
138
+     * @return sqlTypes
139
+     */
53
140
     @Override
54
141
     public int[] sqlTypes() {
55
-        return new int[] {
56
-            Types.VARCHAR
57
-        };
142
+        return new int[] { Types.VARCHAR };
58
143
     }
59
144
 
145
+    /**
146
+    * nullSafeGet<p>
147
+    * Read code from result set and map to the corresponding enum constant.
148
+    *
149
+    * @param resultSet
150
+    * @param names
151
+    * @param session
152
+    * @param owner
153
+    * @return enum instance or null if DB value is null or code not matched
154
+    */
60
155
     @Override
61
156
     public Object nullSafeGet(ResultSet rs, String[] names, SharedSessionContractImplementor session, Object owner)
62
157
             throws HibernateException, SQLException {
63
158
         String code = rs.getString(names[0]);
159
+        if (code == null) return null;
64
160
         for (CodedEnum en : returnedClass().getEnumConstants()) {
65
161
             if (en.getCode().equals(code)) {
66
162
                 return en;
..
..
@@ -69,6 +165,15 @@
69
165
         return null;
70
166
     }
71
167
 
168
+    /**
169
+    * nullSafeSet<p>
170
+    * Write enum code as VARCHAR or set NULL if value is null.
171
+    * 
172
+    * @param statement
173
+    * @param value
174
+    * @param index
175
+    * @param session
176
+    */
72
177
     @Override
73
178
     public void nullSafeSet(PreparedStatement st, Object value, int index, SharedSessionContractImplementor session)
74
179
             throws HibernateException, SQLException {
..
..
@@ -78,5 +183,5 @@
78
183
             st.setString(index, ((CodedEnum) value).getCode());
79
184
         }
80
185
     }
81
-
82
186
 }
187
+