0
# Apereo CAS Core Utilities
1
2
A comprehensive utility library providing essential infrastructure components for the Central Authentication Service (CAS) framework. This library offers functional programming constructs, cryptographic utilities, HTTP clients, configuration helpers, and Spring Framework integration.
3
4
## Package Information
5
6
**Maven Coordinates:**
7
```xml
8
<dependency>
9
<groupId>org.apereo.cas</groupId>
10
<artifactId>cas-server-core-util-api</artifactId>
11
<version>7.2.4</version>
12
</dependency>
13
```
14
15
**Java Compatibility:** Java 11+
16
**Framework Integration:** Spring Framework 6.x, Spring Boot 3.x
17
18
## Core Imports
19
20
```java
21
// Core utility classes
22
import org.apereo.cas.util.CollectionUtils;
23
import org.apereo.cas.util.DateTimeUtils;
24
import org.apereo.cas.util.JsonUtils;
25
import org.apereo.cas.util.function.FunctionUtils;
26
27
// Cryptographic utilities
28
import org.apereo.cas.util.crypto.CipherExecutor;
29
import org.apereo.cas.util.cipher.AbstractCipherExecutor;
30
import org.apereo.cas.util.serialization.SerializationUtils;
31
32
// HTTP clients
33
import org.apereo.cas.util.http.HttpClient;
34
import org.apereo.cas.util.http.SimpleHttpClient;
35
36
// Generators
37
import org.apereo.cas.util.gen.RandomStringGenerator;
38
import org.apereo.cas.util.gen.DefaultRandomStringGenerator;
39
40
// Spring integration
41
import org.apereo.cas.util.spring.ApplicationContextProvider;
42
43
// JWT utilities
44
import org.apereo.cas.util.jwt.JsonWebTokenSigner;
45
import org.apereo.cas.util.jwt.JsonWebTokenEncryptor;
46
```
47
48
## Basic Usage Examples
49
50
### Working with Collections
51
```java
52
import org.apereo.cas.util.CollectionUtils;
53
import java.util.*;
54
55
// Create maps easily
56
Map<String, Object> attributes = CollectionUtils.wrap("key1", "value1", "key2", "value2");
57
58
// Convert to multi-valued map
59
Map<String, List<Object>> multiValued = CollectionUtils.toMultiValuedMap(attributes);
60
61
// Filter by distinct keys
62
List<User> uniqueUsers = users.stream()
63
.filter(CollectionUtils.distinctByKey(User::getEmail))
64
.collect(Collectors.toList());
65
```
66
67
### Date/Time Operations
68
```java
69
import org.apereo.cas.util.DateTimeUtils;
70
import java.time.*;
71
72
// Parse various date formats
73
LocalDateTime dateTime = DateTimeUtils.localDateTimeOf("2024-01-15T10:30:00");
74
ZonedDateTime zonedTime = DateTimeUtils.zonedDateTimeOf(System.currentTimeMillis());
75
76
// Convert time units
77
TimeUnit timeUnit = DateTimeUtils.toTimeUnit(ChronoUnit.HOURS);
78
```
79
80
### Functional Programming with Exception Handling
81
```java
82
import org.apereo.cas.util.function.FunctionUtils;
83
84
// Conditional operations
85
String result = FunctionUtils.doIfNotBlank(inputString, String::toUpperCase);
86
87
// Exception handling
88
String safeResult = FunctionUtils.doAndHandle(() -> riskyOperation(),
89
Exception.class,
90
ex -> "default");
91
92
// Retry operations
93
String retryResult = FunctionUtils.doAndRetry(() -> unreliableOperation(),
94
3,
95
1000);
96
```
97
98
## Architecture
99
100
The CAS Core Utilities library is organized into specialized packages, each providing focused functionality:
101
102
### Core Infrastructure
103
- **org.apereo.cas.util** - Essential utility classes for collections, dates, JSON, logging, and system operations
104
- **org.apereo.cas.util.function** - Functional programming utilities with enhanced exception handling and conditional operations
105
106
### Security & Cryptography
107
- **org.apereo.cas.util.cipher** - Comprehensive cipher executors for encryption, signing, and key management
108
- **org.apereo.cas.util.crypto** - Certificate utilities, password encoders, and cryptographic helper functions
109
- **org.apereo.cas.util.jwt** - JSON Web Token signing and encryption capabilities
110
111
### Data Management
112
- **org.apereo.cas.util.serialization** - Object serialization utilities with Jackson integration
113
- **org.apereo.cas.util.gen** - Random string and numeric generators for tokens and identifiers
114
115
### Network & Communication
116
- **org.apereo.cas.util.http** - HTTP client implementations and request/response utilities
117
118
### Framework Integration
119
- **org.apereo.cas.util.spring** - Deep Spring Framework integration including application context management, conditional beans, and configuration
120
- **org.apereo.cas.util.text** - Message sanitization and text processing utilities
121
122
### Specialized Components
123
- **org.apereo.cas.util.transforms** - Principal name transformation utilities
124
- **org.apereo.cas.util.cache** - Distributed cache management
125
- **org.apereo.cas.util.io** - File system watching and I/O operations
126
127
## Capabilities
128
129
### [Core Utilities](core-utilities.md)
130
Essential utility classes for everyday operations including collection manipulation, date/time handling, JSON processing, and system utilities. Features powerful functional programming constructs with exception handling.
131
132
```java
133
// Collection utilities
134
Map<String, Object> map = CollectionUtils.wrap("user", "john", "role", "admin");
135
Optional<String> first = CollectionUtils.firstElement(collection, String.class);
136
137
// Date/time utilities
138
ZonedDateTime now = DateTimeUtils.zonedDateTimeOf(System.currentTimeMillis());
139
LocalDate date = DateTimeUtils.localDateOf(timestamp);
140
141
// Functional programming with exception handling
142
String result = FunctionUtils.doAndHandle(() -> parseJson(input),
143
JsonException.class,
144
ex -> "{}");
145
```
146
147
### [Cryptography](cryptography.md)
148
Comprehensive cryptographic capabilities including cipher executors, password encoders, certificate utilities, and key management. Supports various encryption algorithms and provides secure defaults.
149
150
```java
151
// Abstract cipher executor
152
public class MyCipher extends AbstractCipherExecutor<String, String> {
153
@Override
154
public String encode(String value, Object[] parameters) {
155
return encrypt(value);
156
}
157
158
@Override
159
public String decode(String value, Object[] parameters) {
160
return decrypt(value);
161
}
162
}
163
164
// Certificate operations
165
X509Certificate cert = CertUtils.readCertificate(certResource);
166
PublicKey publicKey = AbstractCipherExecutor.extractPublicKeyFromResource(keyPath);
167
```
168
169
### [HTTP Clients](http-clients.md)
170
Robust HTTP client implementations with factory patterns, request/response utilities, and integration with Apache HttpClient. Supports various authentication methods and connection pooling.
171
172
```java
173
// HTTP client usage
174
HttpClient client = new SimpleHttpClient();
175
HttpMessage message = new HttpMessage(new URL("https://api.example.com"), "POST");
176
message.setContentType("application/json");
177
message.setEntity("{\"key\":\"value\"}");
178
179
boolean success = client.sendMessageToEndPoint(message);
180
HttpMessage response = client.sendMessageToEndPoint(new URL("https://api.example.com"));
181
```
182
183
### [Generators](generators.md)
184
Random string and numeric generators for creating secure tokens, identifiers, and cryptographic material. Multiple output formats including Base64, hex, and custom alphabets.
185
186
```java
187
// Random string generation
188
RandomStringGenerator generator = new DefaultRandomStringGenerator();
189
String token = generator.getNewString(32);
190
191
// Numeric generation
192
NumericGenerator numGen = new DefaultRandomNumberGenerator();
193
long id = numGen.getNextLong();
194
195
// Specialized generators
196
RandomStringGenerator base64Gen = new Base64RandomStringGenerator();
197
RandomStringGenerator hexGen = new HexRandomStringGenerator();
198
```
199
200
### [Spring Integration](spring-integration.md)
201
Deep Spring Framework integration with application context management, conditional beans, configuration properties, and Spring Boot support. Includes custom conditions and bean lifecycle management.
202
203
```java
204
// Application context access
205
ApplicationContext ctx = ApplicationContextProvider.getApplicationContext();
206
Optional<MyBean> bean = ApplicationContextProvider.getBean("myBean", MyBean.class);
207
208
// Bean registration
209
ApplicationContextProvider.registerBeanIntoApplicationContext(ctx, myBean, "beanName");
210
211
// Configuration properties
212
Optional<CasConfigurationProperties> config =
213
ApplicationContextProvider.getCasConfigurationProperties();
214
```
215
216
### [JWT Utilities](jwt-utilities.md)
217
JSON Web Token signing and encryption utilities with support for various algorithms and key management strategies.
218
219
```java
220
// JWT signing
221
JsonWebTokenSigner signer = new JsonWebTokenSigner(secretKey, algorithm);
222
JwtClaims claims = new JwtClaims();
223
claims.setSubject("user123");
224
String jwt = signer.sign(claims);
225
226
// JWT encryption
227
JsonWebTokenEncryptor encryptor = new JsonWebTokenEncryptor(encryptionKey, keyAlgorithm);
228
String encryptedJwt = encryptor.encrypt(payload);
229
```
230
231
### [Serialization](serialization.md)
232
Object serialization utilities with support for various formats, compression, and encryption. Includes Jackson integration and custom serialization plans.
233
234
```java
235
// Basic serialization
236
byte[] bytes = SerializationUtils.serialize(myObject);
237
MyObject restored = SerializationUtils.deserialize(bytes, MyObject.class);
238
239
// Encrypted serialization
240
byte[] encrypted = SerializationUtils.serializeAndEncodeObject(cipher, myObject);
241
MyObject decrypted = SerializationUtils.decodeAndDeserializeObject(cipher, encrypted,
242
MyObject.class);
243
```
244
245
### [Text Processing](text-processing.md)
246
Message sanitization and text processing utilities for secure handling of user input and system messages.
247
248
```java
249
// Message sanitization
250
MessageSanitizer sanitizer = new DefaultMessageSanitizer();
251
String clean = sanitizer.sanitize(userInput);
252
253
// Principal name transformation
254
PrincipalNameTransformer transformer = new ConvertCasePrincipalNameTransformer();
255
String transformed = transformer.transform("UserName"); // returns "username"
256
```
257
258
### [Functional Programming](functional-programming.md)
259
Advanced functional programming utilities with enhanced exception handling, conditional operations, and retry mechanisms.
260
261
```java { .api }
262
// Conditional functions
263
Function<String, String> processor = FunctionUtils.doIf(
264
StringUtils::isNotBlank,
265
String::toUpperCase,
266
s -> "DEFAULT"
267
);
268
269
// Exception handling with retry
270
String result = FunctionUtils.doAndRetry(() -> {
271
return callExternalService();
272
}, 3, 1000, IOException.class);
273
274
// Null-safe operations
275
FunctionUtils.doIfNotNull(user, u -> updateLastLogin(u));
276
```
277
278
### [Specialized Utilities](specialized-utilities.md)
279
Additional specialized utilities including cache management, file watching, SSL utilities, JPA converters, concurrency utilities, and virtual threading support.
280
281
```java
282
// File watching
283
WatcherService watcher = new FileWatcherService();
284
watcher.start("config", path -> reloadConfiguration());
285
286
// Cache management
287
DistributedCacheManager<String, Object> cache = new MyDistributedCacheManager();
288
cache.set("key", value, Duration.ofMinutes(30));
289
290
// Virtual threading (Java 21+)
291
VirtualThreadDelegate delegate = new VirtualThreadDelegate();
292
ThreadFactory factory = delegate.virtualThreadFactory("cas-");
293
Thread vThread = delegate.newVirtualThread("worker", task);
294
```