0
# Data Structure Utilities
1

2
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 in multi-threaded environments.
3

4
## Capabilities
5

6
### Collection Utilities
7

8
Abstract utility class providing null-safe collection operations and advanced search functionality.
9

10
```java { .api }
11
/**
12
 * Collection manipulation utilities
13
 */
14
public abstract class CollectionUtils {
15
    // Null-safe empty checks
16
    public static boolean isEmpty(Collection<?> collection);
17
    public static boolean isEmpty(Map<?, ?> map);
18
    
19
    // Search operations
20
    public static boolean contains(Iterator<?> iterator, Object element);
21
    public static boolean contains(Enumeration<?> enumeration, Object element);
22
    public static <E> E findFirstMatch(Collection<?> source, Collection<E> candidates);
23
    public static <T> T findValueOfType(Collection<?> collection, Class<T> type);
24
    public static Object findValueOfType(Collection<?> collection, Class<?>[] types);
25
    
26
    // Specialized operations
27
    public static Object matchEndpointKey(String path, Map<String, Object> map);
28
}
29
```
30

31
### Concurrent Hash Set
32

33
Thread-safe Set implementation using ConcurrentHashMap for high-performance concurrent access.
34

35
```java { .api }
36
/**
37
 * Thread-safe Set implementation using ConcurrentHashMap
38
 */
39
public class ConcurrentHashSet<E> extends AbstractSet<E> {
40
    // Constructors
41
    public ConcurrentHashSet();
42
    public ConcurrentHashSet(int initialCapacity);
43
    
44
    // All standard Set methods inherited from AbstractSet
45
    // Thread-safe operations provided by underlying ConcurrentHashMap
46
}
47
```
48

49
### Map Utilities
50

51
Map operations with case-insensitive key lookup and safe value extraction.
52

53
```java { .api }
54
/**
55
 * Map operations with case-insensitive key lookup
56
 */
57
public class MapUtil {
58
    // Case-insensitive operations
59
    public static <V> Optional<V> getValueIgnoreCase(Map<String, V> map, String key);
60
    public static <V> Optional<V> delValueIgnoreCase(Map<String, V> map, String key);
61
}
62
```
63

64
### Object Utilities
65

66
Abstract utility class providing null-safe object operations and array handling.
67

68
```java { .api }
69
/**
70
 * Object manipulation utilities with null-safety
71
 */
72
public abstract class ObjectUtils {
73
    // Type checking
74
    public static boolean isArray(Object obj);
75
    
76
    // Empty checks
77
    public static boolean isEmpty(Object[] array);
78
    public static boolean isEmpty(Object obj);
79
    
80
    // Null-safe operations
81
    public static boolean nullSafeEquals(Object o1, Object o2);
82
    public static int nullSafeHashCode(Object obj);
83
    public static int nullSafeHashCode(Object[] array);
84
    public static int nullSafeHashCode(boolean[] array);
85
    public static int nullSafeHashCode(byte[] array);
86
    public static int nullSafeHashCode(char[] array);
87
    public static int nullSafeHashCode(double[] array);
88
    public static int nullSafeHashCode(float[] array);
89
    public static int nullSafeHashCode(int[] array);
90
    public static int nullSafeHashCode(long[] array);
91
    public static int nullSafeHashCode(short[] array);
92
    
93
    // Array conversion
94
    public static Object[] toObjectArray(Object source);
95
}
96
```
97

98
### Tuple
99

100
Simple pair container for holding two related values with type safety.
101

102
```java { .api }
103
/**
104
 * Simple pair container for two values
105
 */
106
public class Tuple<T, T2> {
107
    public final T first;
108
    public final T2 second;
109
    
110
    // Constructor
111
    public Tuple(T first, T2 second);
112
}
113
```
114

115
**Usage Examples:**
116

117
```java
118
import com.networknt.utility.*;
119
import java.util.*;
120

121
// Collection utilities
122
List<String> names = Arrays.asList("Alice", "Bob", "Charlie");
123
boolean isEmpty = CollectionUtils.isEmpty(names); // false
124

125
List<String> candidates = Arrays.asList("Bob", "David");
126
String match = CollectionUtils.findFirstMatch(names, candidates); // "Bob"
127

128
// Thread-safe set
129
ConcurrentHashSet<String> concurrentSet = new ConcurrentHashSet<>();
130
concurrentSet.add("item1");
131
concurrentSet.add("item2");
132
// Safe for concurrent access
133

134
// Case-insensitive map operations
135
Map<String, String> headers = new HashMap<>();
136
headers.put("Content-Type", "application/json");
137
headers.put("Authorization", "Bearer token");
138

139
Optional<String> contentType = MapUtil.getValueIgnoreCase(headers, "content-type"); // "application/json"
140
Optional<String> auth = MapUtil.getValueIgnoreCase(headers, "AUTHORIZATION"); // "Bearer token"
141

142
// Object utilities
143
Object[] array = {"a", "b", "c"};
144
boolean isArrayType = ObjectUtils.isArray(array); // true
145
boolean arrayEmpty = ObjectUtils.isEmpty(array); // false
146

147
// Null-safe operations
148
boolean equal = ObjectUtils.nullSafeEquals(null, null); // true
149
int hashCode = ObjectUtils.nullSafeHashCode(null); // 0
150

151
// Tuple usage
152
Tuple<String, Integer> userInfo = new Tuple<>("Alice", 25);
153
String name = userInfo.first; // "Alice"
154
Integer age = userInfo.second; // 25
155

156
// Endpoint matching example
157
Map<String, Object> endpoints = Map.of(
158
    "/api/users/{id}", "getUserHandler",
159
    "/api/orders/*", "orderHandler"
160
);
161
Object handler = CollectionUtils.matchEndpointKey("/api/users/123", endpoints);
162
```