0
# NetworkNT Utility Library
1

2
A comprehensive collection of utility classes designed for the Light-4J microservices framework, providing essential utilities for string manipulation, networking operations, I/O operations, security operations, data structure utilities, time and date operations, configuration management, path template matching, and more. This library minimizes external dependencies by incorporating selected functionality from Apache Commons libraries directly, ensuring a lightweight footprint for cloud-native microservices deployment.
3

4
## Package Information
5

6
- **Package Name**: com.networknt/utility
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.networknt</groupId>
13
    <artifactId>utility</artifactId>
14
    <version>2.2.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.networknt.utility.*;
22
```
23

24
For specific utilities:
25

26
```java
27
import com.networknt.utility.StringUtils;
28
import com.networknt.utility.NetUtils;
29
import com.networknt.utility.HashUtil;
30
import com.networknt.utility.PathTemplateMatcher;
31
```
32

33
## Basic Usage
34

35
```java
36
import com.networknt.utility.StringUtils;
37
import com.networknt.utility.NetUtils;
38
import com.networknt.utility.HashUtil;
39

40
// String manipulation
41
String cleaned = StringUtils.trimToEmpty("  hello world  ");
42
boolean isValid = StringUtils.isEmail("user@example.com");
43

44
// Network operations
45
InetAddress localAddr = NetUtils.getLocalAddress();
46
int availablePort = NetUtils.getAvailablePort();
47

48
// Security operations
49
String uuid = HashUtil.generateUUID();
50
String hash = HashUtil.md5Hex("password");
51

52
// Path template matching for REST APIs
53
PathTemplateMatcher<String> matcher = new PathTemplateMatcher<>();
54
matcher.add("/api/users/{id}", "getUserById");
55
PathMatchResult<String> result = matcher.match("/api/users/123");
56
```
57

58
## Architecture
59

60
The utility library is organized around functional areas rather than object hierarchies:
61

62
- **String Processing**: Comprehensive string manipulation, validation, and formatting utilities
63
- **Network Operations**: IP address handling, port management, and network utilities
64
- **Security & Cryptography**: Hashing, PKCE implementation, and certificate fingerprinting
65
- **I/O & NIO**: Stream operations, file handling, and byte conversions
66
- **Path Template Matching**: Fast REST API path routing with parameter extraction
67
- **Data Structures**: Thread-safe collections and null-safe operations
68
- **Configuration Management**: Service mapping and configuration utilities
69
- **Time & Date**: ISO 8601 formatting and time unit conversions
70
- **Framework Integration**: Constants and module registry for Light-4J ecosystem
71

72
All utilities are designed as static methods or simple constructors for easy integration into microservices architectures.
73

74
## Capabilities
75

76
### String Manipulation
77

78
Comprehensive string processing utilities including validation, transformation, formatting, and pattern matching. Includes email validation, JWT token checking, and environment variable expansion.
79

80
```java { .api }
81
public class StringUtils {
82
    public static boolean isNullOrEmpty(String value);
83
    public static String expandEnvVars(String text);
84
    public static boolean isEmail(String userIdEmail);
85
    public static String replace(String text, String searchString, String replacement, int max);
86
    public static String[] split(String str, String separatorChars);
87
    public static String join(Object[] array, char separator);
88
    public static boolean isNumeric(String str);
89
    public static boolean matchPathToPattern(String requestPath, String endpointPattern);
90
}
91
```
92

93
[String Processing](./string-processing.md)
94

95
### Network Operations
96

97
Network utilities for IP address handling, port management, and network validation. Includes local address detection, hostname resolution, and URL formatting for IPv4/IPv6.
98

99
```java { .api }
100
public class NetUtils {
101
    public static InetAddress getLocalAddress();
102
    public static boolean isValidAddress(String address);
103
    public static int getAvailablePort();
104
    public static String resolveHost2Address(String fqdn);
105
    public static String ipAddressToUrlString(InetAddress address);
106
}
107
```
108

109
[Network Operations](./network-operations.md)
110

111
### Security & Cryptography
112

113
Security utilities including hash calculation, UUID generation, PKCE (Proof Key for Code Exchange) implementation, and certificate fingerprinting for OAuth and authentication workflows.
114

115
```java { .api }
116
public class HashUtil {
117
    public static String generateUUID();
118
    public static String md5Hex(String message);
119
    public static String generateStrongPasswordHash(String password);
120
    public static boolean validatePassword(char[] originalPassword, String storedPassword);
121
}
122

123
public class CodeVerifierUtil {
124
    public static String generateRandomCodeVerifier();
125
    public static String deriveCodeVerifierChallenge(String codeVerifier);
126
}
127

128
public class FingerPrintUtil {
129
    public static String getCertFingerPrint(Certificate cert);
130
}
131
```
132

133
[Security & Cryptography](./security-cryptography.md)
134

135
### Path Template Matching
136

137
Fast path template matching system for REST API routing with parameter extraction. Optimized for high-performance microservices with stem-based matching algorithms.
138

139
```java { .api }
140
public class PathTemplateMatcher<T> {
141
    public PathTemplateMatcher<T> add(String pathTemplate, T value);
142
    public PathMatchResult<T> match(String path);
143
    public Set<PathTemplate> getPathTemplates();
144
}
145

146
public class PathTemplate implements Comparable<PathTemplate> {
147
    public static PathTemplate create(String inputPath);
148
    public boolean matches(String path, Map<String, String> pathParameters);
149
    public Set<String> getParameterNames();
150
}
151
```
152

153
[Path Template Matching](./path-template-matching.md)
154

155
### I/O & File Operations
156

157
Stream processing, NIO operations, file handling, and byte conversions. Includes zip file handling, stream copying, and ByteBuffer operations for efficient I/O.
158

159
```java { .api }
160
public class StreamUtils {
161
    public static byte[] copyToByteArray(InputStream in);
162
    public static String copyToString(InputStream in, Charset charset);
163
    public static int copy(InputStream in, OutputStream out);
164
    public static long copyRange(InputStream in, OutputStream out, long start, long end);
165
}
166

167
public class NioUtils {
168
    public static void unzip(String zipFilename, String destDirname);
169
    public static ByteBuffer toByteBuffer(String s);
170
    public static String getFileExtension(String name);
171
}
172
```
173

174
[I/O & File Operations](./io-file-operations.md)
175

176
### Data Structure Utilities
177

178
Thread-safe collections and null-safe operations for working with maps, sets, and collections. Includes concurrent data structures and utility methods for safe data manipulation.
179

180
```java { .api }
181
public class ConcurrentHashSet<E> extends AbstractSet<E> {
182
    public ConcurrentHashSet();
183
    public ConcurrentHashSet(int initialCapacity);
184
}
185

186
public class CollectionUtils {
187
    public static boolean isEmpty(Collection<?> collection);
188
    public static <E> E findFirstMatch(Collection<?> source, Collection<E> candidates);
189
    public static Object matchEndpointKey(String path, Map<String, Object> map);
190
}
191

192
public class MapUtil {
193
    public static <V> Optional<V> getValueIgnoreCase(Map<String, V> map, String key);
194
}
195
```
196

197
[Data Structure Utilities](./data-structure-utilities.md)
198

199
### Configuration Management
200

201
Configuration utilities for service mapping, path normalization, and key management in microservices environments. Designed for Light-4J framework configuration patterns.
202

203
```java { .api }
204
public class ConfigUtils {
205
    public static String findServiceEntry(String method, String searchKey, Map<String, Object> mapping);
206
    public static String normalisePath(String requestPath);
207
    public static String toInternalKey(String method, String path);
208
    public static Map<String, Object> normalizeMap(Map<String, Object> map, List<String> keysToNotSort);
209
}
210
```
211

212
[Configuration Management](./configuration-management.md)
213

214
### Time & Date Operations
215

216
Time unit conversions and ISO 8601 date formatting utilities for consistent time handling across microservices.
217

218
```java { .api }
219
public class TimeUtil {
220
    public static long oneTimeUnitMillisecond(TimeUnit timeUnit);
221
    public static long nextStartTimestamp(TimeUnit timeUnit, long start);
222
}
223

224
public class DateUtil {
225
    public static String formatIso8601Date(Instant date);
226
    public static Instant parseIso8601Date(String dateString);
227
    public static long parseIso8601DateToMillis(String dateString);
228
}
229
```
230

231
[Time & Date Operations](./time-date-operations.md)
232

233
### Framework Constants & Integration
234

235
Framework constants and module registry functionality for Light-4J ecosystem integration, including HTTP headers, JWT claims, and component registration.
236

237
```java { .api }
238
public class Constants {
239
    public static final String CORRELATION_ID_STRING = "X-Correlation-Id";
240
    public static final String USER_ID_STRING = "user_id";
241
    public static final String CLIENT_ID_STRING = "client_id";
242
    public static final String LIGHT_4J = "light-4j";
243
    // ... 60+ additional constants
244
}
245

246
public class ModuleRegistry {
247
    public static void registerModule(String configName, String moduleClass, Map<String, Object> config, List<String> masks);
248
    public static Map<String, Object> getModuleRegistry();
249
    public static void registerPlugin(String pluginName, String pluginVersion, String configName, String pluginClass, Map<String, Object> config, List<String> masks);
250
}
251
```
252

253
[Framework Constants & Integration](./framework-integration.md)
254

255
## Types
256

257
```java { .api }
258
public class Tuple<T, T2> {
259
    public final T first;
260
    public final T2 second;
261
    
262
    public Tuple(T first, T2 second);
263
}
264

265
public class PathTemplateMatch {
266
    public PathTemplateMatch(String matchedTemplate, Map<String, String> parameters);
267
    public String getMatchedTemplate();
268
    public Map<String, String> getParameters();
269
}
270

271
public interface PathMatchResult<T> extends PathTemplateMatch {
272
    T getValue();
273
}
274
```