0
# biz.aQute.bnd.util
1

2
OSGi utility classes for bnd/bndtools providing essential utility functionality for OSGi bundle analysis and manipulation. This library contains comprehensive APIs for Java class file processing, functional programming patterns, stream operations, and immutable data structures optimized for OSGi development environments.
3

4
## Package Information
5

6
- **Package Name**: biz.aQute.bnd.util
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>biz.aQute.bnd</groupId>
13
    <artifactId>biz.aQute.bnd.util</artifactId>
14
    <version>6.4.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
// Java class file processing
22
import aQute.bnd.classfile.ClassFile;
23
import aQute.bnd.classfile.ConstantPool;
24
import aQute.bnd.classfile.MethodInfo;
25
import aQute.bnd.classfile.FieldInfo;
26

27
// Memoization utilities
28
import aQute.bnd.memoize.Memoize;
29
import aQute.bnd.memoize.CloseableMemoize;
30

31
// Result type for error handling
32
import aQute.bnd.result.Result;
33

34
// Stream utilities
35
import aQute.bnd.stream.MapStream;
36

37
// Immutable collections
38
import aQute.bnd.unmodifiable.Lists;
39
import aQute.bnd.unmodifiable.Maps;
40
import aQute.bnd.unmodifiable.Sets;
41

42
// Signature processing
43
import aQute.bnd.signatures.ClassSignature;
44
import aQute.bnd.signatures.MethodSignature;
45
```
46

47
## Basic Usage
48

49
```java
50
import aQute.bnd.classfile.ClassFile;
51
import aQute.bnd.result.Result;
52
import aQute.bnd.memoize.Memoize;
53
import aQute.bnd.unmodifiable.Lists;
54

55
// Parse a Java class file
56
try (DataInputStream in = new DataInputStream(Files.newInputStream(classPath))) {
57
    ClassFile classFile = ClassFile.parseClassFile(in);
58
    System.out.println("Class: " + classFile.this_class);
59
    System.out.println("Super: " + classFile.super_class);
60
}
61

62
// Use Result type for error handling
63
Result<String> result = processData("input");
64
if (result.isOk()) {
65
    System.out.println("Success: " + result.value());
66
} else {
67
    System.err.println("Error: " + result.error());
68
}
69

70
// Create immutable collections
71
List<String> immutableList = Lists.of("alpha", "beta", "gamma");
72
Map<String, Integer> immutableMap = Maps.of("key1", 1, "key2", 2);
73

74
// Use memoization for expensive operations
75
Memoize<String> expensiveComputation = Memoize.supplier(() -> {
76
    // Expensive computation here
77
    return "computed result";
78
});
79
String result1 = expensiveComputation.get(); // Computes
80
String result2 = expensiveComputation.get(); // Returns cached result
81
```
82

83
## Architecture
84

85
The biz.aQute.bnd.util library is organized into eight main functional areas:
86

87
- **Class File Processing**: Complete Java bytecode analysis and manipulation capabilities
88
- **Builder Patterns**: Fluent APIs for constructing class file structures
89
- **Memoization**: Thread-safe caching utilities for expensive computations
90
- **Functional Error Handling**: Monadic Result type for safe error management
91
- **Generic Signatures**: Comprehensive Java generic type signature processing
92
- **Enhanced Streams**: Map-specialized stream operations extending Java 8 streams
93
- **Immutable Collections**: Thread-safe, unmodifiable collection implementations
94
- **Preview Features**: Support for experimental Java class file features
95

96
## Capabilities
97

98
### Java Class File Processing
99

100
Complete Java class file parsing, analysis, and manipulation capabilities for OSGi bundle tooling. Supports all class file attributes, constant pool operations, and bytecode analysis.
101

102
```java { .api }
103
public static ClassFile parseClassFile(DataInput in) throws IOException;
104

105
public class ClassFile extends ElementInfo {
106
    public final int minor_version;
107
    public final int major_version;
108
    public final ConstantPool constant_pool;
109
    public final String this_class;
110
    public final String super_class;
111
    public final String[] interfaces;
112
    public final FieldInfo[] fields;
113
    public final MethodInfo[] methods;
114
}
115

116
public class ConstantPool {
117
    public int size();
118
    public Object entry(int index);
119
    public String utf8(int index);
120
    public String className(int index);
121
}
122
```
123

124
[Class File Processing](./classfile.md)
125

126
### Class File Builder
127

128
Fluent builder patterns for constructing Java class files programmatically with full type safety and validation.
129

130
```java { .api }
131
public class ClassFileBuilder {
132
    public ClassFileBuilder minor_version(int version);
133
    public ClassFileBuilder major_version(int version);
134
    public ClassFileBuilder this_class(String className);
135
    public ClassFileBuilder super_class(String superClass);
136
    public ClassFile build();
137
}
138

139
public class MutableConstantPool extends ConstantPool {
140
    public MutableConstantPool();
141
    public <T> T add(Class<T> type, Supplier<T> supplier);
142
}
143
```
144

145
[Class File Builder](./classfile-builder.md)
146

147
### Memoization Utilities
148

149
Thread-safe memoization utilities for caching expensive computations with configurable eviction policies and resource management.
150

151
```java { .api }
152
public interface Memoize<S> extends Supplier<S> {
153
    static <T> Memoize<T> supplier(Supplier<? extends T> supplier);
154
    static <T> Memoize<T> refreshingSupplier(Supplier<? extends T> supplier, long duration, TimeUnit unit);
155
    
156
    S get();
157
    Optional<S> peek();
158
    boolean isPresent();
159
    <R> Memoize<R> map(Function<? super S, ? extends R> mapper);
160
}
161

162
public interface CloseableMemoize<S extends AutoCloseable> extends Memoize<S>, AutoCloseable {
163
    static <T extends AutoCloseable> CloseableMemoize<T> closeableSupplier(Supplier<? extends T> supplier);
164
    boolean isClosed();
165
}
166
```
167

168
[Memoization](./memoize.md)
169

170
### Result Type for Error Handling
171

172
Monadic error handling similar to Rust's Result type, providing safe and composable error management without exceptions.
173

174
```java { .api }
175
public interface Result<V> {
176
    static <T> Result<T> ok(T value);
177
    static <T> Result<T> err(CharSequence error);
178
    
179
    boolean isOk();
180
    boolean isErr();
181
    V value();
182
    String error();
183
    V unwrap();
184
    <U> Result<U> map(FunctionWithException<? super V, ? extends U> mapper);
185
    <U> Result<U> flatMap(FunctionWithException<? super V, ? extends Result<? extends U>> mapper);
186
    V orElse(V defaultValue);
187
}
188
```
189

190
[Result Type](./result.md)
191

192
### Java Generic Signatures
193

194
Comprehensive processing and analysis of Java generic type signatures for advanced type introspection and OSGi metadata generation.
195

196
```java { .api }
197
public interface Signature {
198
    Set<String> erasedBinaryReferences();
199
}
200

201
public class ClassSignature implements Signature {
202
    public static ClassSignature of(String signature);
203
    public final TypeParameter[] typeParameters;
204
    public final ClassTypeSignature superClass;
205
    public final ClassTypeSignature[] superInterfaces;
206
}
207

208
public class MethodSignature implements Signature {
209
    public final TypeParameter[] typeParameters;
210
    public final JavaTypeSignature[] parameters;
211
    public final JavaTypeSignature returnType;
212
    public final ThrowsSignature[] exceptions;
213
}
214
```
215

216
[Generic Signatures](./signatures.md)
217

218
### Enhanced Stream Operations
219

220
Map-specialized stream operations extending Java 8 streams with fluent APIs for key-value pair processing and transformations.
221

222
```java { .api }
223
public interface MapStream<K, V> extends BaseStream<Map.Entry<K, V>, MapStream<K, V>> {
224
    static <K, V> MapStream<K, V> of(Map<? extends K, ? extends V> map);
225
    static <K, V> MapStream<K, V> empty();
226
    
227
    Stream<Map.Entry<K, V>> entries();
228
    Stream<K> keys();
229
    Stream<V> values();
230
    <R> MapStream<K, R> mapValue(Function<? super V, ? extends R> mapper);
231
    <R> MapStream<R, V> mapKey(Function<? super K, ? extends R> mapper);
232
    MapStream<K, V> filterKey(Predicate<? super K> predicate);
233
    MapStream<K, V> filterValue(Predicate<? super V> predicate);
234
}
235
```
236

237
[Stream Operations](./stream.md)
238

239
### Immutable Collections
240

241
Thread-safe, unmodifiable collection implementations with factory methods compatible with Java 9+ collection APIs but available for earlier Java versions.
242

243
```java { .api }
244
public final class Lists {
245
    public static <E> List<E> of();
246
    public static <E> List<E> of(E element);
247
    public static <E> List<E> of(E... elements);
248
    public static <E> List<E> copyOf(Collection<? extends E> collection);
249
}
250

251
public final class Maps {
252
    public static <K, V> Map<K, V> of();
253
    public static <K, V> Map<K, V> of(K key, V value);
254
    public static <K, V> Map<K, V> copyOf(Map<? extends K, ? extends V> map);
255
    public static <K, V> Map.Entry<K, V> entry(K key, V value);
256
}
257

258
public final class Sets {
259
    public static <E> Set<E> of();
260
    public static <E> Set<E> of(E element);
261
    public static <E> Set<E> of(E... elements);
262
    public static <E> Set<E> copyOf(Collection<? extends E> collection);
263
}
264
```
265

266
[Immutable Collections](./unmodifiable.md)
267

268
### Preview Features
269

270
Support for experimental and preview-level Java class file features, enabling forward compatibility with future Java versions.
271

272
[Preview Features](./preview.md)