0
# Core Utilities
1

2
Essential utility classes providing fundamental operations for collections, date/time handling, JSON processing, system operations, and functional programming with enhanced exception handling.
3

4
## Core Imports
5

6
```java
7
import org.apereo.cas.util.CollectionUtils;
8
import org.apereo.cas.util.DateTimeUtils; 
9
import org.apereo.cas.util.JsonUtils;
10
import org.apereo.cas.util.AopUtils;
11
import org.springframework.util.MultiValueMap;
12
import java.time.*;
13
import java.util.*;
14
import java.util.concurrent.TimeUnit;
15
import java.util.function.*;
16
```
17

18
## CollectionUtils
19

20
Comprehensive collection manipulation utilities for maps, lists, and sets.
21

22
```java { .api }
23
@UtilityClass 
24
public class CollectionUtils {
25
    
26
    // Map creation utilities - basic overloads
27
    public static <K, V> Map<K, V> wrap(String key, Object value);
28
    public static <K, V> Map<K, V> wrap(String key, Object value, String key2, Object value2);
29
    public static <K, V> Map<K, V> wrap(String key, Object value, String key2, Object value2, String key3, Object value3);
30
    public static <K, V> Map<K, V> wrap(String key, Object value, String key2, Object value2, String key3, Object value3, String key4, Object value4);
31
    public static <K, V> Map<K, V> wrap(String key, Object value, String key2, Object value2, String key3, Object value3, String key4, Object value4, String key5, Object value5);
32
    public static <K, V> Map<K, V> wrap(String key, Object value, String key2, Object value2, String key3, Object value3, String key4, Object value4, String key5, Object value5, String key6, Object value6);
33
    
34
    // Map/Collection wrapping utilities
35
    public static <K, V> Map<K, V> wrap(Multimap<K, V> source);
36
    public static <K, V> Map<K, V> wrap(Map<K, V> source);
37
    public static <T> List<T> wrap(T source);
38
    public static <T> List<T> wrap(List<T> source);
39
    public static <T> Set<T> wrap(Set<T> source);
40
    
41
    // Collection creation utilities
42
    public static <T> Set<T> wrapSet(T source);
43
    public static <T> Set<T> wrapSet(T... source);
44
    public static <T> Set<T> wrapHashSet(T... source);
45
    public static <T> Set<T> wrapHashSet(Collection<T> source);
46
    public static <T> List<T> wrapList(T... source);
47
    public static <T> List<T> wrapArrayList(T... source);
48
    public static <T> Map<String, T> wrapLinkedHashMap(String key, T source);
49
    public static <T> Collection<T> wrapCollection(T... source);
50
    
51
    // Collection conversion utilities  
52
    public static Map<String, Object> toSingleValuedMap(
53
        Map<String, Object> attributes, 
54
        List<String> singleValuedAttributes
55
    );
56
    
57
    public static Map<String, List<Object>> toMultiValuedMap(
58
        Map<String, Object> attributes
59
    );
60
    
61
    public static Map<String, List<Object>> fromCommaDelimitedValues(
62
        Map<String, String> attributes  
63
    );
64
    
65
    // Element extraction
66
    public static Optional<Object> firstElement(Object obj);
67
    public static <T> Optional<T> firstElement(Object obj, Class<T> clazz);
68
    
69
    // Collection type conversion
70
    public static <T extends Collection> T toCollection(Object obj, Class<T> clazz);
71
    public static Set<Object> toCollection(Object obj);
72
    
73
    // MultiValueMap operations
74
    public static MultiValueMap<String, Object> asMultiValueMap(Map<String, ?> source);
75
    public static MultiValueMap<String, Object> asMultiValueMap(
76
        Map<String, ?> source, 
77
        String keyPattern
78
    );
79
    
80
    // Utility operations
81
    public static <T> Predicate<T> distinctByKey(Function<? super T, ?> keyExtractor);
82
    public static Map<String, String> convertDirectedListToMap(Collection<String> inputList);
83
    public static Map<String, Object> merge(Map<String, ?>... attributes);
84
}
85
```
86

87
### Usage Examples
88

89
**Creating and manipulating maps:**
90
```java
91
// Create maps from key-value pairs  
92
Map<String, Object> user = CollectionUtils.wrap(
93
    "name", "John Doe",
94
    "email", "john@example.com"
95
);
96

97
// For more complex data, use multiple wrap calls and merge
98
Map<String, Object> roles = CollectionUtils.wrap("roles", Arrays.asList("USER", "ADMIN"));
99
Map<String, Object> fullUser = CollectionUtils.merge(user, roles);
100

101
// Convert to single-valued attributes
102
List<String> singleValued = Arrays.asList("name", "email");
103
Map<String, Object> singleValuedMap = CollectionUtils.toSingleValuedMap(user, singleValued);
104

105
// Convert to multi-valued map
106
Map<String, List<Object>> multiValuedMap = CollectionUtils.toMultiValuedMap(user);
107
```
108

109
**Working with collections:**
110
```java
111
// Extract first elements safely
112
List<String> names = Arrays.asList("John", "Jane", "Bob");
113
Optional<String> firstName = CollectionUtils.firstElement(names, String.class);
114

115
// Filter by distinct keys
116
List<User> users = getUsers();
117
List<User> uniqueByEmail = users.stream()
118
    .filter(CollectionUtils.distinctByKey(User::getEmail))
119
    .collect(Collectors.toList());
120

121
// Merge multiple maps
122
Map<String, Object> defaults = CollectionUtils.wrap("timeout", 30);
123
Map<String, Object> overrides = CollectionUtils.wrap("timeout", 60, "retries", 3);
124
Map<String, Object> merged = CollectionUtils.merge(defaults, overrides);
125
```
126

127
## DateTimeUtils
128

129
Date and time utility methods for parsing, converting, and working with various temporal types.
130

131
```java { .api }
132
@UtilityClass
133
public class DateTimeUtils {
134
    
135
    // LocalDateTime operations
136
    public static LocalDateTime localDateTimeOf(String value);
137
    public static LocalDateTime localDateTimeOf(long time);
138
    public static LocalDateTime localDateTimeOf(Date time);
139
    
140
    // LocalDate operations  
141
    public static LocalDate localDateOf(long time);
142
    
143
    // ZonedDateTime operations
144
    public static ZonedDateTime zonedDateTimeOf(String value);
145
    public static ZonedDateTime zonedDateTimeOf(TemporalAccessor time);
146
    public static ZonedDateTime zonedDateTimeOf(Instant time);
147
    public static ZonedDateTime zonedDateTimeOf(long time);
148
    public static ZonedDateTime zonedDateTimeOf(long time, ZoneId zoneId);
149
    public static ZonedDateTime zonedDateTimeOf(Date time);
150
    public static ZonedDateTime zonedDateTimeOf(Calendar time);
151
    
152
    // Date conversion
153
    public static Date dateOf(ChronoZonedDateTime time);
154
    public static Date dateOf(LocalDate time);
155
    public static Date dateOf(LocalDateTime time);
156
    public static Date dateOf(Instant time);
157
    
158
    // Parsing utilities
159
    public static ZonedDateTime convertToZonedDateTime(String value);
160
    
161
    // Time unit conversion
162
    public static TimeUnit toTimeUnit(ChronoUnit chronoUnit);
163
    public static ChronoUnit toChronoUnit(TimeUnit timeUnit);
164
}
165
```
166

167
### Usage Examples
168

169
**Date/time creation and conversion:**
170
```java
171
// Create from various sources
172
LocalDateTime now = DateTimeUtils.localDateTimeOf(System.currentTimeMillis());
173
LocalDateTime parsed = DateTimeUtils.localDateTimeOf("2024-01-15T10:30:00");
174
ZonedDateTime zoned = DateTimeUtils.zonedDateTimeOf(System.currentTimeMillis(), ZoneId.of("America/New_York"));
175

176
// Convert to legacy Date objects
177
Date legacyDate = DateTimeUtils.dateOf(now);
178
Date zonedDate = DateTimeUtils.dateOf(zoned);
179

180
// Parse ISO strings with timezone
181
ZonedDateTime fromIso = DateTimeUtils.convertToZonedDateTime("2024-01-15T10:30:00-05:00");
182
```
183

184
**Time unit operations:**
185
```java
186
// Convert between time units
187
TimeUnit minutes = DateTimeUtils.toTimeUnit(ChronoUnit.MINUTES);
188
ChronoUnit hours = DateTimeUtils.toChronoUnit(TimeUnit.HOURS);
189

190
// Use in cache configurations
191
Duration timeout = Duration.of(30, DateTimeUtils.toChronoUnit(TimeUnit.SECONDS));
192
```
193

194
## JsonUtils
195

196
JSON utility methods for rendering objects and validating JSON strings.
197

198
```java { .api }
199
@UtilityClass
200
public class JsonUtils {
201
    
202
    // Object rendering  
203
    public String render(Object model);
204
    public String render(ObjectMapper mapper, Object model);
205
    
206
    // HTTP response rendering
207
    public void render(Object model, HttpServletResponse response);
208
    public void render(HttpServletResponse response);
209
    public void renderException(Exception ex, HttpServletResponse response);
210
    
211
    // Validation
212
    public boolean isValidJson(String json);
213
}
214
```
215

216
### Usage Examples
217

218
**JSON serialization:**
219
```java
220
// Render objects to JSON
221
User user = new User("John", "john@example.com");
222
String json = JsonUtils.render(user);
223

224
// Custom ObjectMapper
225
ObjectMapper mapper = new ObjectMapper();
226
mapper.configure(SerializationFeature.INDENT_OUTPUT, true);
227
String prettyJson = JsonUtils.render(mapper, user);
228

229
// Render to HTTP response
230
@RequestMapping("/api/user")
231
public void getUser(HttpServletResponse response) {
232
    User user = userService.getCurrentUser();
233
    JsonUtils.render(user, response);
234
}
235
```
236

237
**JSON validation:**
238
```java
239
// Validate JSON strings
240
String userInput = request.getParameter("json");
241
if (JsonUtils.isValidJson(userInput)) {
242
    // Process valid JSON
243
    processUserData(userInput);
244
} else {
245
    // Handle invalid JSON
246
    throw new IllegalArgumentException("Invalid JSON format");
247
}
248
```
249

250
## AopUtils
251

252
Utility class for Aspect-Oriented Programming operations.
253

254
```java { .api }
255
@UtilityClass
256
public class AopUtils {
257
    
258
    // JoinPoint utilities
259
    public static JoinPoint unWrapJoinPoint(JoinPoint point);
260
}
261
```
262

263
### Usage Examples
264

265
**AOP join point handling:**
266
```java
267
@Aspect
268
@Component
269
public class SecurityAspect {
270
    
271
    @Around("@annotation(Secured)")
272
    public Object checkSecurity(ProceedingJoinPoint joinPoint) throws Throwable {
273
        // Unwrap nested join points
274
        JoinPoint unwrapped = AopUtils.unWrapJoinPoint(joinPoint);
275
        
276
        // Perform security checks
277
        checkPermissions(unwrapped.getSignature().getName());
278
        
279
        return joinPoint.proceed();
280
    }
281
}
282
```
283

284
## Additional Core Utilities
285

286
The library includes several other utility classes for specialized operations:
287

288
### CompressionUtils
289
Compression and decompression utilities for data processing.
290

291
### DigestUtils  
292
Hashing and digest utilities for data integrity verification.
293

294
### EncodingUtils
295
Text encoding and decoding utilities supporting various character sets.
296

297
### InetAddressUtils
298
Network address utilities for IP address validation and manipulation.
299

300
### LoggingUtils
301
Logging configuration and message formatting utilities.
302

303
### RegexUtils
304
Regular expression utilities with pre-compiled patterns for common operations.
305

306
### ResourceUtils  
307
Spring resource handling utilities for classpath and file system resources.
308

309
### SocketUtils
310
Network socket utilities for port availability checking and socket configuration.
311

312
### SystemUtils
313
System information and environment utilities for runtime introspection.
314

315
### Usage Example - System Information
316
```java
317
// Get system properties and environment info
318
Map<String, String> systemInfo = SystemUtils.getSystemProperties();
319
String javaVersion = SystemUtils.getJavaVersion();
320
boolean isUnix = SystemUtils.isUnix();
321

322
// Resource handling
323
Resource configResource = ResourceUtils.getResourceFrom("classpath:config.properties");
324
InputStream stream = ResourceUtils.getResourceStream(configResource);
325
```