0
# bndlib
1

2
bndlib is a comprehensive Java library that serves as the core component of the Bnd OSGi toolkit. It provides extensive functionality for analyzing Java class files, constructing OSGi bundles, and managing OSGi development workflows. The library includes tools for bundle analysis, manifest generation, JAR construction, verification, and a complete workspace management system with plugin architecture.
3

4
## Package Information
5

6
- **Package Name**: biz.aQute.bndlib
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Maven Coordinates**: `biz.aQute.bnd:biz.aQute.bndlib:6.4.1`
10
- **Installation (Maven)**:
11
  ```xml
12
  <dependency>
13
    <groupId>biz.aQute.bnd</groupId>
14
    <artifactId>biz.aQute.bndlib</artifactId>
15
    <version>6.4.1</version>
16
  </dependency>
17
  ```
18
- **Installation (Gradle)**:
19
  ```groovy
20
  implementation 'biz.aQute.bnd:biz.aQute.bndlib:6.4.1'
21
  ```
22

23
## Core Imports
24

25
```java
26
// Core OSGi functionality
27
import aQute.bnd.build.Workspace;
28
import aQute.bnd.build.Project;
29
import aQute.bnd.osgi.Builder;
30
import aQute.bnd.osgi.Analyzer;
31
import aQute.bnd.osgi.Verifier;
32
import aQute.bnd.osgi.Jar;
33

34
// Annotation processing
35
import aQute.bnd.component.DSAnnotations;
36
import aQute.bnd.metatype.MetatypeAnnotations;
37
import aQute.bnd.cdi.CDIAnnotations;
38

39
// Testing and launching
40
import aQute.bnd.build.ProjectLauncher;
41
import aQute.bnd.build.ProjectTester;
42

43
// Maven integration
44
import aQute.bnd.maven.MavenRepository;
45

46
// Baseline and difference analysis
47
import aQute.bnd.differ.Baseline;
48

49
// Export functionality
50
import aQute.bnd.exporter.executable.ExecutableJarExporter;
51
```
52

53
## Basic Usage
54

55
```java
56
import aQute.bnd.build.Workspace;
57
import aQute.bnd.build.Project;
58
import aQute.bnd.osgi.Builder;
59
import aQute.bnd.osgi.Analyzer;
60
import aQute.bnd.differ.Baseline;
61
import java.io.File;
62

63
// Workspace-based usage
64
Workspace workspace = Workspace.getWorkspace(new File("workspace"));
65
Project project = workspace.getProject("my.project");
66
File[] artifacts = project.build();
67

68
// Direct bundle building with annotation processing
69
Builder builder = new Builder();
70
builder.setProperty("Bundle-SymbolicName", "com.example.bundle");
71
builder.setProperty("Bundle-Version", "1.0.0");
72
builder.addClasspath(new File("classes"));
73
Jar bundle = builder.build();
74

75
// Bundle analysis
76
Analyzer analyzer = new Analyzer();
77
analyzer.setJar(bundle);
78
analyzer.analyze();
79
System.out.println("Imports: " + analyzer.getImports());
80
System.out.println("Exports: " + analyzer.getExports());
81

82
// Testing and launching
83
ProjectLauncher launcher = project.getProjectLauncher();
84
int exitCode = launcher.launch();
85

86
ProjectTester tester = project.getProjectTester();
87
boolean testsPass = tester.test();
88

89
// Maven integration  
90
MavenRepository maven = workspace.getMavenRepository();
91
SortedSet<Version> versions = maven.versions("org.apache.commons.lang3");
92

93
// API baseline comparison
94
Baseline baseline = new Baseline();
95
Diff diff = baseline.baseline(newBundle, oldBundle);
96
Version suggestedVersion = baseline.getSuggestedVersion();
97
```
98

99
## Architecture
100

101
bndlib is built around several key architectural components:
102

103
- **Workspace Model**: `Workspace` and `Project` classes provide multi-project management with dependency resolution and build coordination
104
- **Bundle Processing Pipeline**: `Analyzer` → `Builder` → `Verifier` chain for comprehensive bundle lifecycle management
105
- **Plugin Architecture**: Extensive service-based plugin system through `RepositoryPlugin`, `AnalyzerPlugin`, and other service interfaces
106
- **Resource Abstraction**: `Jar` and `Resource` classes provide unified access to JAR files and embedded resources
107
- **Property-Based Configuration**: `Processor` class provides property handling and error reporting throughout the system
108
- **Repository System**: Multiple repository implementations for artifact management and dependency resolution
109

110
## Capabilities
111

112
### Workspace Management
113

114
Multi-project workspace management with dependency resolution, build coordination, and repository integration. Essential for complex OSGi development environments.
115

116
```java { .api }
117
/**
118
 * Get or create a workspace from a directory
119
 * @param dir - Directory containing workspace configuration
120
 * @return Workspace instance for project management
121
 */
122
public static Workspace getWorkspace(File dir) throws Exception;
123

124
/**
125
 * Get all projects in the workspace
126
 * @return Collection of all workspace projects
127
 */
128
public Collection<Project> getAllProjects() throws Exception;
129

130
/**
131
 * Create a new project in the workspace
132
 * @param name - Project name
133
 * @return Newly created project
134
 */
135
public Project createProject(String name) throws Exception;
136
```
137

138
[Workspace Management](./workspace.md)
139

140
### Bundle Building
141

142
Core bundle construction functionality for creating OSGi bundles from classpaths and resources with automatic manifest generation.
143

144
```java { .api }
145
/**
146
 * Build a JAR/bundle from configured classpath and properties
147
 * @return Generated JAR bundle
148
 */
149
public Jar build() throws Exception;
150

151
/**
152
 * Add classpath entry for bundle construction
153
 * @param file - JAR file or directory to add to classpath
154
 */
155
public void addClasspath(File file);
156

157
/**
158
 * Include resources in the bundle
159
 * @param resource - Resource specification string
160
 */
161
public void includeResource(String resource);
162
```
163

164
[Bundle Building](./building.md)
165

166
### Bundle Analysis
167

168
Comprehensive OSGi bundle analysis for examining dependencies, exports, imports, and metadata validation.
169

170
```java { .api }
171
/**
172
 * Analyze the current JAR for OSGi metadata
173
 */
174
public void analyze() throws Exception;
175

176
/**
177
 * Get calculated import packages
178
 * @return Parameters containing import package declarations
179
 */
180
public Parameters getImports();
181

182
/**
183
 * Get calculated export packages  
184
 * @return Parameters containing export package declarations
185
 */
186
public Parameters getExports();
187

188
/**
189
 * Verify bundle compliance and report issues
190
 */
191
public void verify() throws Exception;
192
```
193

194
[Bundle Analysis](./analysis.md)
195

196
### Repository Management
197

198
Repository plugin system for artifact storage, retrieval, and dependency resolution across multiple repository types.
199

200
```java { .api }
201
/**
202
 * List available resources in repository
203
 * @param pattern - Glob pattern to match against bundle symbolic names
204
 * @return List of available resource names
205
 */
206
public List<String> list(String pattern) throws Exception;
207

208
/**
209
 * Get a specific resource from repository
210
 * @param bsn - Bundle symbolic name
211
 * @param range - Version range
212
 * @param properties - Additional properties
213
 * @return File containing the requested resource
214
 */
215
public File get(String bsn, Version range, Map<String,String> properties) throws Exception;
216

217
/**
218
 * Store a JAR in the repository
219
 * @param jar - JAR to store
220
 * @param options - Storage options
221
 */
222
public PutResult put(Jar jar, PutOptions options) throws Exception;
223
```
224

225
[Repository Management](./repositories.md)
226

227
### Plugin Architecture
228

229
Extensible plugin system through service interfaces for customizing analysis, building, verification, and deployment processes.
230

231
```java { .api }
232
/**
233
 * Generic plugin interface for all bnd plugins
234
 */
235
public interface Plugin {
236
    void setProperties(Map<String,String> properties);
237
    void setReporter(Reporter reporter);
238
}
239

240
/**
241
 * Plugin for customizing bundle analysis
242
 */
243
public interface AnalyzerPlugin extends Plugin {
244
    boolean analyzeJar(Analyzer analyzer) throws Exception;
245
}
246

247
/**
248
 * Plugin for performing actions during builds
249
 */
250
public interface Action {
251
    String perform() throws Exception;
252
}
253
```
254

255
[Plugin Architecture](./plugins.md)
256

257
### OSGi Annotation Processing
258

259
Comprehensive annotation processing for Declarative Services (DS), Metatype, CDI, and bundle metadata with automatic manifest generation.
260

261
```java { .api }
262
/**
263
 * Process Declarative Services annotations in JAR during analysis
264
 * @param analyzer - Analyzer instance containing the JAR to process
265
 * @return true if DS components were found and processed
266
 */
267
public boolean analyzeJar(Analyzer analyzer) throws Exception;
268

269
/**
270
 * Process Metatype annotations for configuration metadata in JAR
271
 * @param analyzer - Analyzer instance containing the JAR to process  
272
 * @return true if Metatype annotations were found and processed
273
 */
274
public boolean analyzeJar(Analyzer analyzer) throws Exception;
275

276
/**
277
 * Process CDI annotations for dependency injection in JAR
278
 * @param analyzer - Analyzer instance containing the JAR to process
279
 * @return true if CDI annotations were found and processed
280
 */
281
public boolean analyzeJar(Analyzer analyzer) throws Exception;
282
```
283

284
[OSGi Annotation Processing](./annotations.md)
285

286
### Testing and Launching
287

288
Integrated testing framework with JUnit support and application launching for OSGi runtime environments.
289

290
```java { .api }
291
/**
292
 * Create project launcher for OSGi applications
293
 * @return ProjectLauncher configured for the project
294
 */
295
public ProjectLauncher getProjectLauncher() throws Exception;
296

297
/**
298
 * Create project tester for running JUnit tests
299
 * @return ProjectTester configured with test classpath
300
 */
301
public ProjectTester getProjectTester() throws Exception;
302

303
/**
304
 * Launch OSGi application with configured bundles
305
 * @return Exit code from launched application
306
 */
307
public int launch() throws Exception;
308

309
/**
310
 * Run JUnit tests in OSGi environment
311
 * @return true if all tests passed
312
 */
313
public boolean test() throws Exception;
314
```
315

316
[Testing and Launching](./testing.md)
317

318
### Maven Integration
319

320
Maven repository support with dependency resolution, POM generation, and artifact deployment capabilities.
321

322
```java { .api }
323
/**
324
 * Get Maven repository instance for artifact access
325
 * @return MavenRepository configured for workspace
326
 */
327
public MavenRepository getMavenRepository();
328

329
/**
330
 * Get available versions for a bundle symbolic name
331
 * @param bsn - Bundle symbolic name
332
 * @return SortedSet of available versions
333
 */
334
public SortedSet<Version> versions(String bsn) throws Exception;
335

336
/**
337
 * Generate POM from bundle manifest
338
 * @param jar - Bundle JAR to generate POM for
339
 * @return POM content as string
340
 */
341
public String generatePom(Jar jar) throws Exception;
342

343
/**
344
 * Deploy artifact to Maven repository
345
 * @param jar - JAR to deploy
346
 * @param coordinates - Maven coordinates
347
 */
348
public void deploy(Jar jar, String coordinates) throws Exception;
349
```
350

351
[Maven Integration](./maven.md)
352

353
### Baseline and Difference Analysis
354

355
API baseline comparison and bundle difference analysis for maintaining API compatibility and versioning.
356

357
```java { .api }
358
/**
359
 * Compare bundle against baseline for API changes
360
 * @param newer - Current bundle version
361
 * @param older - Baseline bundle version
362
 * @return Diff containing API changes
363
 */
364
public Diff baseline(Jar newer, Jar older) throws Exception;
365

366
/**
367
 * Get suggested version based on API changes
368
 * @return Suggested new version based on baseline analysis
369
 */
370
public Version getSuggestedVersion();
371

372
/**
373
 * Generate baseline report
374
 * @param diff - Diff from baseline comparison
375
 * @return Human-readable baseline report
376
 */
377
public String generateReport(Diff diff);
378
```
379

380
[Baseline and Difference Analysis](./baseline.md)
381

382
### Export and Packaging
383

384
Bundle export capabilities for creating executable JARs, runbundles, and specialized packaging formats.
385

386
```java { .api }
387
/**
388
 * Export project as executable JAR
389
 * @param options - Export configuration options
390
 * @return File containing exported executable
391
 */
392
public File exportExecutable(ExecutableJarOptions options) throws Exception;
393

394
/**
395
 * Export runbundles for deployment
396
 * @param runSpec - Run specification with bundle list
397
 * @return Directory containing exported bundles
398
 */
399
public File exportRunbundles(Run runSpec) throws Exception;
400

401
/**
402
 * Package bundle with additional resources
403
 * @param packaging - Packaging specification
404
 * @return Packaged bundle file
405
 */
406
public File packageBundle(PackagingSpec packaging) throws Exception;
407
```
408

409
[Export and Packaging](./export.md)
410

411
### Utility Classes
412

413
Essential utility classes for version handling, header parsing, JAR manipulation, and common OSGi operations.
414

415
```java { .api }
416
/**
417
 * Parse OSGi version string
418
 * @param version - Version string to parse
419
 * @return Parsed Version object
420
 */
421
public static Version parseVersion(String version);
422

423
/**
424
 * Parse OSGi header into parameters
425
 * @param header - Header string to parse
426
 * @return Parameters containing parsed header data
427
 */
428
public static Parameters parseHeader(String header);
429

430
/**
431
 * Get resource from JAR
432
 * @param path - Resource path
433
 * @return Resource object or null if not found
434
 */
435
public Resource getResource(String path);
436
```
437

438
[Utility Classes](./utilities.md)
439

440
## Types
441

442
```java { .api }
443
/**
444
 * Workspace management and project coordination
445
 */
446
public class Workspace extends Processor {
447
    public static Workspace getWorkspace(File dir) throws Exception;
448
    public Collection<Project> getAllProjects() throws Exception;
449
    public Project getProject(String name) throws Exception;
450
    public Project createProject(String name) throws Exception;
451
    public List<RepositoryPlugin> getRepositories();
452
}
453

454
/**
455
 * Individual project within a workspace
456
 */
457
public class Project extends Processor {
458
    public File[] build() throws Exception;
459
    public void test() throws Exception;
460
    public Collection<Container> getBuildpath() throws Exception;
461
    public String getBsn();
462
    public Version getVersion();
463
}
464

465
/**
466
 * OSGi bundle builder with classpath and resource management
467
 */
468
public class Builder extends Analyzer {
469
    public Jar build() throws Exception;
470
    public void addClasspath(File file);
471
    public void includeResource(String resource);
472
    public void sign(File keystore) throws Exception;
473
}
474

475
/**
476
 * OSGi bundle analyzer for dependency analysis
477
 */
478
public class Analyzer extends Processor {
479
    public void analyze() throws Exception;
480
    public Parameters getImports();
481
    public Parameters getExports();
482
    public Set<String> getContained();
483
    public void setJar(Jar jar);
484
    public Jar getJar();
485
}
486

487
/**
488
 * Bundle verification and validation
489
 */
490
public class Verifier extends Analyzer {
491
    public void verify() throws Exception;
492
    public void verifyActivator();
493
    public void verifyComponent();
494
}
495

496
/**
497
 * JAR file abstraction and manipulation
498
 */
499
public class Jar implements Closeable {
500
    public Resource getResource(String path);
501
    public void putResource(String path, Resource resource);
502
    public Map<String,Resource> getResources();
503
    public Manifest getManifest();
504
    public void setManifest(Manifest manifest);
505
    public void write(OutputStream out) throws IOException;
506
}
507

508
/**
509
 * OSGi version representation
510
 */
511
public class Version implements Comparable<Version> {
512
    public static Version parseVersion(String version);
513
    public int getMajor();
514
    public int getMinor();
515
    public int getMicro();
516
    public String getQualifier();
517
}
518

519
/**
520
 * OSGi header parameters (like Import-Package, Export-Package)
521
 */
522
public class Parameters extends LinkedHashMap<String,Attrs> {
523
    public static Parameters parseHeader(String header);
524
    public String toString();
525
}
526

527
/**
528
 * Header attributes map
529
 */
530
public class Attrs extends LinkedHashMap<String,String> {
531
    public Version getVersion();
532
    public String getType();
533
    public String getDirective(String name);
534
}
535

536
/**
537
 * Repository plugin interface for artifact management
538
 */
539
public interface RepositoryPlugin extends Plugin {
540
    List<String> list(String pattern) throws Exception;
541
    File get(String bsn, Version range, Map<String,String> properties) throws Exception;
542
    PutResult put(Jar jar, PutOptions options) throws Exception;
543
    
544
    interface PutOptions {
545
        boolean isOverwrite();
546
        Jar getContext();
547
    }
548
    
549
    class PutResult {
550
        public String artifact;
551
        public boolean isOk();
552
    }
553
}
554

555
/**
556
 * Base processor with property handling and error reporting
557
 */
558
public class Processor implements Closeable, Reporter {
559
    public void setProperty(String key, String value);
560
    public String getProperty(String key);
561
    public void error(String format, Object... args);
562
    public void warning(String format, Object... args);
563
    public List<String> getErrors();
564
    public List<String> getWarnings();
565
}
566

567
/**
568
 * Resource abstraction for JAR entries and files
569
 */
570
public interface Resource {
571
    InputStream openInputStream() throws IOException;
572
    long lastModified();
573
    long size();
574
}
575

576
/**
577
 * Declarative Services component definition
578
 */
579
public class ComponentDef {
580
    public String getName();
581
    public String getImplementationClass();
582
    public List<String> getServiceInterfaces();
583
    public Map<String,Object> getProperties();
584
    public List<ReferenceDef> getReferences();
585
}
586

587
/**
588
 * Metatype configuration definition
589
 */
590
public class MetatypeDef {
591
    public String getId();
592
    public String getName();
593
    public String getDescription();
594
    public List<AttributeDef> getAttributes();
595
}
596

597
/**
598
 * CDI bean definition
599
 */
600
public class BeanDef {
601
    public String getBeanClass();
602
    public List<String> getQualifiers();
603
    public String getScope();
604
    public List<InjectionPoint> getInjectionPoints();
605
}
606

607
/**
608
 * Project launcher for OSGi applications
609
 */
610
public class ProjectLauncher {
611
    public int launch() throws Exception;
612
    public void setTimeout(long timeout);
613
    public long getTimeout();
614
    public void setTrace(boolean trace);
615
    public boolean getTrace();
616
}
617

618
/**
619
 * Project tester for running tests
620
 */
621
public abstract class ProjectTester {
622
    public abstract boolean test() throws Exception;
623
    public abstract List<String> getTests();
624
    public abstract Map<String,Object> getReports();
625
}
626

627
/**
628
 * Maven repository implementation
629
 */
630
public class MavenRepository implements RepositoryPlugin {
631
    public List<String> list(String pattern) throws Exception;
632
    public File get(String bsn, Version range, Map<String,String> properties) throws Exception;
633
    public PutResult put(Jar jar, PutOptions options) throws Exception;
634
    public SortedSet<Version> versions(String bsn) throws Exception;
635
}
636

637
/**
638
 * API difference analysis result
639
 */
640
public class Diff {
641
    public Delta getDelta();
642
    public Collection<String> getPackages();
643
    public boolean isCompatible();
644
    public Version getSuggestedVersion();
645
}
646

647
/**
648
 * Executable JAR export options
649
 */
650
public class ExecutableJarOptions {
651
    public void setMainClass(String mainClass);
652
    public void setOutputFile(File outputFile);
653
    public void setIncludeResources(boolean includeResources);
654
}
655

656
/**
657
 * Run specification for bundle execution
658
 */
659
public class Run extends Processor {
660
    public List<String> getRunbundles();
661
    public String getRunee();
662
    public Map<String,String> getRunproperties();
663
    public List<String> getRunpath();
664
}
665
```