0
# BND Utilities
1

2
The BND Utilities package (biz.aQute.bnd.util) provides comprehensive utility classes for the BND OSGi toolchain. It offers essential building blocks for Java bytecode manipulation, functional programming constructs, type signature parsing, stream processing, memoization, and immutable collections - all designed for maximum reusability across OSGi bundle development, build tooling, and enterprise Java applications.
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>7.1.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
// Class file manipulation
22
import aQute.bnd.classfile.ClassFile;
23
import aQute.bnd.classfile.ConstantPool;
24
import aQute.bnd.classfile.builder.ClassFileBuilder;
25

26
// Functional programming
27
import aQute.bnd.result.Result;
28
import aQute.bnd.memoize.Memoize;
29

30
// Stream utilities
31
import aQute.bnd.stream.MapStream;
32

33
// Immutable collections
34
import aQute.bnd.unmodifiable.Lists;
35
import aQute.bnd.unmodifiable.Maps;
36
import aQute.bnd.unmodifiable.Sets;
37

38
// Signature parsing
39
import aQute.bnd.signatures.ClassSignature;
40
import aQute.bnd.signatures.MethodSignature;
41
```
42

43
## Basic Usage
44

45
```java
46
import aQute.bnd.classfile.ClassFile;
47
import aQute.bnd.result.Result;
48
import aQute.bnd.memoize.Memoize;
49
import aQute.bnd.stream.MapStream;
50
import aQute.bnd.unmodifiable.Lists;
51

52
// Parse class file
53
ClassFile classFile = ClassFile.parseClassFile(inputStream);
54
System.out.println("Class: " + classFile.this_class);
55

56
// Use Result for error handling
57
Result<String> result = Result.ok("success");
58
String value = result.orElse("default");
59

60
// Memoize expensive computations
61
Memoize<String> memoized = Memoize.supplier(() -> expensiveComputation());
62
String cached = memoized.get(); // Computed once, cached thereafter
63

64
// Process key-value streams
65
Map<String, Integer> counts = MapStream.of(data)
66
    .filterValue(v -> v > 0)
67
    .mapValue(v -> v * 2)
68
    .collect(MapStream.toMap());
69

70
// Create immutable collections
71
List<String> items = Lists.of("a", "b", "c");
72
```
73

74
## Architecture
75

76
The BND Utilities package is organized into six core modules:
77

78
- **Class File Processing**: Complete Java bytecode manipulation capabilities with full JVM specification compliance
79
- **Functional Programming**: Result monad for exception-safe error handling and function composition
80
- **Memoization**: Advanced caching strategies with configurable eviction policies and resource management
81
- **Stream Processing**: Enhanced stream operations specifically designed for key-value data processing
82
- **Type Signatures**: Complete Java generic signature parsing and resolution system
83
- **Immutable Collections**: High-performance immutable data structures with zero-copy operations
84

85
## Capabilities
86

87
### Class File Manipulation
88

89
Complete Java class file parsing, manipulation, and generation with full support for all JVM bytecode features including modules, records, sealed classes, and type annotations.
90

91
```java { .api }
92
public class ClassFile extends ElementInfo {
93
    public static ClassFile parseClassFile(DataInput in) throws IOException;
94
    public void write(DataOutput out) throws IOException;
95
    public byte[] write() throws IOException;
96
}
97

98
public class ConstantPool {
99
    public int size();
100
    public <T> T entry(int index);
101
    public String utf8(int utf8_index);
102
    public String className(int class_info_index);
103
}
104
```
105

106
[Class File Processing](./classfile.md)
107

108
### Class File Building
109

110
Programmatic construction of Java class files using fluent builder patterns with support for all bytecode features, modules, and reflection-based generation.
111

112
```java { .api }
113
public class ClassFileBuilder {
114
    public ClassFileBuilder(int access_flags, int major_version, int minor_version, String this_class, String super_class, String... interfaces);
115
    public ClassFileBuilder(ClassFile classFile);
116
    public ClassFileBuilder access(int access);
117
    public ClassFileBuilder addField(FieldInfo field);
118
    public ClassFileBuilder addMethod(MethodInfo method);
119
    public ClassFile build();
120
}
121

122
public class ModuleInfoBuilder extends ClassFileBuilder {
123
    public ModuleInfoBuilder(int major_version, int minor_version, String module_name);
124
    public ModuleInfoBuilder requires(String module, int flags);
125
    public ModuleInfoBuilder exports(String pkg, String... to);
126
    public ModuleInfoBuilder provides(String service, String... providers);
127
}
128

129
public static class ReflectBuilder {
130
    public static ClassFileBuilder fromClass(Class<?> clazz);
131
}
132
```
133

134
[Class File Building](./builder.md)
135

136
### Functional Programming
137

138
Exception-safe functional programming constructs including Result monad for error handling and memoization utilities for performance optimization.
139

140
```java { .api }
141
public interface Result<V> {
142
    static <V> Result<V> ok(V value);
143
    static <V> Result<V> err(CharSequence error);
144
    boolean isOk();
145
    boolean isErr();
146
    V unwrap();
147
    V orElse(V orElse);
148
    <U> Result<U> map(FunctionWithException<? super V, ? extends U> mapper);
149
    <U> Result<U> flatMap(FunctionWithException<? super V, ? extends Result<? extends U>> mapper);
150
}
151

152
public interface Memoize<S> extends Supplier<S> {
153
    static <T> Memoize<T> supplier(Supplier<? extends T> supplier);
154
    S peek();
155
    boolean isPresent();
156
    <R> Memoize<R> map(Function<? super S, ? extends R> mapper);
157
}
158
```
159

160
[Functional Programming](./functional.md)
161

162
### Stream Processing
163

164
Advanced stream operations for key-value data processing with MapStream interface providing specialized operations for Map-like data structures.
165

166
```java { .api }
167
public interface MapStream<K, V> extends BaseStream<Entry<K, V>, MapStream<K, V>> {
168
    static <K, V> MapStream<K, V> of(Map<? extends K, ? extends V> map);
169
    static <K, V> MapStream<K, V> empty();
170
    Stream<K> keys();
171
    Stream<V> values();
172
    MapStream<K, V> filterKey(Predicate<? super K> predicate);
173
    MapStream<K, V> filterValue(Predicate<? super V> predicate);
174
    <R> MapStream<K, R> mapValue(Function<? super V, ? extends R> mapper);
175
    <R> MapStream<R, V> mapKey(Function<? super K, ? extends R> mapper);
176
}
177
```
178

179
[Stream Processing](./stream.md)
180

181
### Type Signature Parsing
182

183
Complete Java generic signature parsing and resolution system supporting all aspects of the Java generic type system including wildcards, bounds, and complex type hierarchies.
184

185
```java { .api }
186
public class ClassSignature implements Signature {
187
    public final TypeParameter[] typeParameters;
188
    public final ClassTypeSignature superClass;
189
    public final ClassTypeSignature[] superInterfaces;
190
    public static ClassSignature of(String signature);
191
}
192

193
public class MethodSignature implements Signature {
194
    public final TypeParameter[] typeParameters;
195
    public final JavaTypeSignature[] parameterTypes;
196
    public final Result resultType;
197
    public final ThrowsSignature[] throwTypes;
198
    public static MethodSignature of(String signature);
199
}
200
```
201

202
[Type Signature Parsing](./signatures.md)
203

204
### Immutable Collections
205

206
High-performance immutable collection implementations providing List, Set, and Map variants with efficient copy-on-write semantics and builder patterns.
207

208
```java { .api }
209
public class Lists {
210
    public static <E> List<E> of();
211
    public static <E> List<E> of(E e1);
212
    public static <E> List<E> of(E... elements);
213
    public static <E> List<E> copyOf(Collection<? extends E> collection);
214
    public static <E> Collector<E, ?, List<E>> toList();
215
}
216

217
public class Maps {
218
    public static <K, V> Map<K, V> of();
219
    public static <K, V> Map<K, V> of(K k1, V v1);
220
    public static <K, V> Map<K, V> copyOf(Map<? extends K, ? extends V> map);
221
}
222
```
223

224
[Immutable Collections](./collections.md)