0
# Header Processing
1

2
OSGi manifest header parsing and manipulation utilities for working with bundle metadata and dependency declarations.
3

4
## Capabilities
5

6
### Parameters
7

8
Represents parsed OSGi manifest header parameters as a map of clause names to attributes.
9

10
```java { .api }
11
/**
12
 * Represents parsed OSGi manifest header parameters
13
 */
14
public class Parameters implements Map<String, Attrs> {
15
    /** Create empty parameters */
16
    public Parameters();
17
    
18
    /** Parse parameters from header string */
19
    public Parameters(String header);
20
    
21
    /** Parse parameters from header string with processor */
22
    public Parameters(String header, Processor processor);
23
    
24
    /** Get attributes for clause */
25
    public Attrs get(String clause);
26
    
27
    /** Put clause with attributes */
28
    public Attrs put(String clause, Attrs attrs);
29
    
30
    /** Remove clause */
31
    public Attrs remove(String clause);
32
    
33
    /** Check if clause exists */
34
    public boolean containsKey(String clause);
35
    
36
    /** Get all clause names */
37
    public Set<String> keySet();
38
    
39
    /** Get all attributes collections */
40
    public Collection<Attrs> values();
41
    
42
    /** Get entry set */
43
    public Set<Map.Entry<String, Attrs>> entrySet();
44
    
45
    /** Merge with other parameters */
46
    public void mergeWith(Parameters other, boolean override);
47
    
48
    /** Convert back to header string */
49
    public String toString();
50
    
51
    /** Get size */
52
    public int size();
53
    
54
    /** Check if empty */
55
    public boolean isEmpty();
56
    
57
    /** Clear all parameters */
58
    public void clear();
59
}
60
```
61

62
**Usage Examples:**
63

64
```java
65
import aQute.bnd.header.Parameters;
66
import aQute.bnd.header.Attrs;
67

68
// Parse Export-Package header
69
String exportHeader = "com.example.api;version=\"1.0\";uses:=\"com.example.spi,com.example.util\"," +
70
                     "com.example.impl;version=\"1.0\";x-internal:=true";
71
Parameters exports = new Parameters(exportHeader);
72

73
for (Map.Entry<String, Attrs> entry : exports.entrySet()) {
74
    String packageName = entry.getKey();
75
    Attrs attrs = entry.getValue();
76
    
77
    System.out.println("Package: " + packageName);
78
    System.out.println("  Version: " + attrs.get("version"));
79
    System.out.println("  Uses: " + attrs.get("uses"));
80
    System.out.println("  Internal: " + attrs.get("x-internal"));
81
}
82

83
// Create new parameters
84
Parameters imports = new Parameters();
85
Attrs attrs = new Attrs();
86
attrs.put("version", "[1.0,2.0)");
87
attrs.put("resolution", "optional");
88
imports.put("javax.servlet", attrs);
89

90
System.out.println("Import-Package: " + imports.toString());
91
// Output: javax.servlet;version="[1.0,2.0)";resolution:=optional
92
```
93

94
### Attrs
95

96
Represents attributes in OSGi headers as a map of attribute names to values with type conversion support.
97

98
```java { .api }
99
/**
100
 * Represents attributes in OSGi headers
101
 */
102
public class Attrs extends LinkedHashMap<String, String> {
103
    /** Create empty attributes */
104
    public Attrs();
105
    
106
    /** Create attributes from map */
107
    public Attrs(Map<String, String> map);
108
    
109
    /** Get typed attribute value */
110
    public <T> T getTyped(String key);
111
    
112
    /** Get version attribute */
113
    public Version getVersion();
114
    
115
    /** Get version attribute with key */
116
    public Version getVersion(String key);
117
    
118
    /** Put typed value */
119
    public <T> T putTyped(String key, T value);
120
    
121
    /** Get as version range */
122
    public VersionRange getVersionRange();
123
    
124
    /** Get as version range with key */
125
    public VersionRange getVersionRange(String key);
126
    
127
    /** Get as list */
128
    public List<String> getList(String key);
129
    
130
    /** Put list value */
131
    public void putList(String key, List<String> list);
132
    
133
    /** Get as boolean */
134
    public boolean getBoolean(String key, boolean defaultValue);
135
    
136
    /** Put boolean value */
137
    public void putBoolean(String key, boolean value);
138
    
139
    /** Get as integer */
140
    public int getInt(String key, int defaultValue);
141
    
142
    /** Put integer value */
143
    public void putInt(String key, int value);
144
    
145
    /** Get as long */
146
    public long getLong(String key, long defaultValue);
147
    
148
    /** Put long value */
149
    public void putLong(String key, long value);
150
    
151
    /** Clone attributes */
152
    public Attrs clone();
153
    
154
    /** Merge with other attributes */
155
    public void merge(Attrs other);
156
}
157
```
158

159
**Usage Examples:**
160

161
```java
162
import aQute.bnd.header.Attrs;
163
import aQute.bnd.version.Version;
164
import aQute.bnd.version.VersionRange;
165

166
// Create and populate attributes
167
Attrs attrs = new Attrs();
168
attrs.put("version", "1.2.3");
169
attrs.put("resolution", "optional");
170
attrs.put("cardinality", "multiple");
171
attrs.put("effective", "resolve");
172

173
// Type conversion
174
Version version = attrs.getVersion();  // Converts "1.2.3" to Version object
175
System.out.println("Version: " + version);
176

177
// Version range
178
attrs.put("version", "[1.0,2.0)");
179
VersionRange range = attrs.getVersionRange();
180
System.out.println("Range: " + range);
181

182
// Boolean values
183
attrs.put("optional", "true");
184
boolean isOptional = attrs.getBoolean("optional", false);
185
System.out.println("Optional: " + isOptional);
186

187
// List values
188
attrs.put("uses", "com.example.api,com.example.spi");
189
List<String> uses = attrs.getList("uses");
190
System.out.println("Uses: " + uses);
191

192
// Integer values
193
attrs.put("timeout", "5000");
194
int timeout = attrs.getInt("timeout", 1000);
195
System.out.println("Timeout: " + timeout);
196
```
197

198
### OSGiHeader
199

200
Utility class for parsing and manipulating specific OSGi headers.
201

202
```java { .api }
203
/**
204
 * Utility for OSGi header parsing and manipulation
205
 */
206
public class OSGiHeader {
207
    /** Parse header into parameters */
208
    public static Parameters parseHeader(String header);
209
    
210
    /** Parse header with processor for macro expansion */
211
    public static Parameters parseHeader(String header, Processor processor);
212
    
213
    /** Join parameters into header string */
214
    public static String join(Map<String, ? extends Map<String, String>> map);
215
    
216
    /** Join with custom separator */
217
    public static String join(Map<String, ? extends Map<String, String>> map, String separator);
218
    
219
    /** Parse single clause */
220
    public static Map.Entry<String, Attrs> parseClause(String clause);
221
    
222
    /** Quote value if needed */
223
    public static String quote(String value);
224
    
225
    /** Unquote value */
226
    public static String unquote(String value);
227
    
228
    /** Check if value needs quoting */
229
    public static boolean needsQuoting(String value);
230
    
231
    /** Validate header syntax */
232
    public static boolean isValidHeader(String header);
233
}
234
```
235

236
### Manifest Utilities
237

238
Utilities for working with JAR manifests and OSGi headers.
239

240
```java { .api }
241
/**
242
 * Utilities for manifest manipulation
243
 */
244
public class ManifestUtil {
245
    /** Get main attributes from manifest */
246
    public static Attributes getMainAttributes(Manifest manifest);
247
    
248
    /** Set main attribute */
249
    public static void setMainAttribute(Manifest manifest, String name, String value);
250
    
251
    /** Get OSGi header as parameters */
252
    public static Parameters getOSGiHeader(Manifest manifest, String headerName);
253
    
254
    /** Set OSGi header from parameters */
255
    public static void setOSGiHeader(Manifest manifest, String headerName, Parameters params);
256
    
257
    /** Clean manifest (remove empty headers) */
258
    public static void clean(Manifest manifest);
259
    
260
    /** Copy manifest */
261
    public static Manifest copy(Manifest source);
262
    
263
    /** Merge manifests */
264
    public static Manifest merge(Manifest base, Manifest overlay);
265
    
266
    /** Validate manifest for OSGi compliance */
267
    public static List<String> validate(Manifest manifest);
268
}
269
```
270

271
### Header Processing Examples
272

273
Common header processing patterns and use cases.
274

275
```java { .api }
276
/**
277
 * Common header processing patterns
278
 */
279
public class HeaderProcessingExamples {
280
    
281
    /** Parse Export-Package header */
282
    public static void parseExportPackage(String header) {
283
        Parameters exports = new Parameters(header);
284
        
285
        for (Map.Entry<String, Attrs> entry : exports.entrySet()) {
286
            String packageName = entry.getKey();
287
            Attrs attrs = entry.getValue();
288
            
289
            Version version = attrs.getVersion();
290
            List<String> uses = attrs.getList("uses");
291
            boolean mandatory = "mandatory".equals(attrs.get("resolution"));
292
            
293
            System.out.println("Export: " + packageName + 
294
                             " version=" + version + 
295
                             " uses=" + uses + 
296
                             " mandatory=" + mandatory);
297
        }
298
    }
299
    
300
    /** Parse Import-Package header */
301
    public static void parseImportPackage(String header) {
302
        Parameters imports = new Parameters(header);
303
        
304
        for (Map.Entry<String, Attrs> entry : imports.entrySet()) {
305
            String packageName = entry.getKey();
306
            Attrs attrs = entry.getValue();
307
            
308
            VersionRange versionRange = attrs.getVersionRange();
309
            boolean optional = "optional".equals(attrs.get("resolution"));
310
            
311
            System.out.println("Import: " + packageName + 
312
                             " version=" + versionRange + 
313
                             " optional=" + optional);
314
        }
315
    }
316
    
317
    /** Parse Require-Bundle header */  
318
    public static void parseRequireBundle(String header) {
319
        Parameters requires = new Parameters(header);
320
        
321
        for (Map.Entry<String, Attrs> entry : requires.entrySet()) {
322
            String bundleName = entry.getKey();
323
            Attrs attrs = entry.getValue();
324
            
325
            VersionRange bundleVersion = attrs.getVersionRange("bundle-version");
326
            boolean optional = "optional".equals(attrs.get("resolution"));
327
            String visibility = attrs.get("visibility");
328
            
329
            System.out.println("Require: " + bundleName + 
330
                             " bundle-version=" + bundleVersion + 
331
                             " optional=" + optional + 
332
                             " visibility=" + visibility);
333
        }
334
    }
335
}
336
```
337

338
**Complete Header Processing Example:**
339

340
```java
341
import aQute.bnd.header.*;
342
import aQute.bnd.version.*;
343
import java.util.jar.Manifest;
344

345
// Complete header processing workflow
346
public class HeaderProcessingWorkflow {
347
    
348
    public void processBundle(File bundleFile) throws Exception {
349
        try (Jar jar = new Jar(bundleFile)) {
350
            Manifest manifest = jar.getManifest();
351
            
352
            // Process Export-Package header
353
            String exportHeader = manifest.getMainAttributes().getValue("Export-Package");
354
            if (exportHeader != null) {
355
                Parameters exports = new Parameters(exportHeader);
356
                System.out.println("Exported packages:");
357
                
358
                for (Map.Entry<String, Attrs> entry : exports.entrySet()) {
359
                    String pkg = entry.getKey();
360
                    Attrs attrs = entry.getValue();
361
                    
362
                    Version version = attrs.getVersion();
363
                    List<String> uses = attrs.getList("uses");
364
                    
365
                    System.out.println("  " + pkg + " v" + version);
366
                    if (uses != null && !uses.isEmpty()) {
367
                        System.out.println("    uses: " + uses);
368
                    }
369
                }
370
            }
371
            
372
            // Process Import-Package header
373
            String importHeader = manifest.getMainAttributes().getValue("Import-Package");
374
            if (importHeader != null) {
375
                Parameters imports = new Parameters(importHeader);
376
                System.out.println("Imported packages:");
377
                
378
                for (Map.Entry<String, Attrs> entry : imports.entrySet()) {
379
                    String pkg = entry.getKey();
380
                    Attrs attrs = entry.getValue();
381
                    
382
                    VersionRange range = attrs.getVersionRange();
383
                    boolean optional = "optional".equals(attrs.get("resolution"));
384
                    
385
                    System.out.println("  " + pkg + " " + range + 
386
                                     (optional ? " (optional)" : ""));
387
                }
388
            }
389
            
390
            // Create new headers
391
            Parameters newExports = new Parameters();
392
            
393
            // Add new export
394
            Attrs exportAttrs = new Attrs();
395
            exportAttrs.putTyped("version", new Version(2, 0, 0));
396
            exportAttrs.putList("uses", Arrays.asList("java.util", "java.io"));
397
            newExports.put("com.example.newapi", exportAttrs);
398
            
399
            // Update manifest
400
            manifest.getMainAttributes().putValue("Export-Package", 
401
                exportHeader + "," + newExports.toString());
402
            
403
            // Validate updated manifest
404
            List<String> validationErrors = ManifestUtil.validate(manifest);
405
            if (!validationErrors.isEmpty()) {
406
                System.err.println("Validation errors:");
407
                for (String error : validationErrors) {
408
                    System.err.println("  " + error);
409
                }
410
            } else {
411
                System.out.println("Manifest is valid");
412
            }
413
        }
414
    }
415
}
416
```