0
# bndlib: A Swiss Army Knife for OSGi
1

2
bndlib is a comprehensive Java library that provides essential functionality for OSGi bundle development, analysis, and management. It serves as the foundational component for the entire bnd ecosystem, offering powerful APIs for building OSGi bundles, analyzing dependencies, managing repositories, and performing semantic versioning analysis.
3

4
## Package Information
5

6
- **Package Name**: biz.aQute.bnd:biz.aQute.bndlib
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 7.1.0
10
- **License**: Dual license (Apache-2.0 OR EPL-2.0)
11
- **Installation**: `implementation 'biz.aQute.bnd:biz.aQute.bndlib:7.1.0'` (Gradle) or `<dependency><groupId>biz.aQute.bnd</groupId><artifactId>biz.aQute.bndlib</artifactId><version>7.1.0</version></dependency>` (Maven)
12

13
## Core Imports
14

15
```java
16
import aQute.bnd.osgi.Processor;
17
import aQute.bnd.osgi.Analyzer;
18
import aQute.bnd.osgi.Builder;
19
import aQute.bnd.osgi.Jar;
20
import aQute.bnd.build.Workspace;
21
import aQute.bnd.build.Project;
22
import aQute.bnd.version.Version;
23
```
24

25
## Basic Usage
26

27
```java
28
import aQute.bnd.osgi.Builder;
29
import aQute.bnd.osgi.Jar;
30
import aQute.bnd.build.Workspace;
31
import aQute.bnd.build.Project;
32

33
// Build an OSGi bundle
34
Builder builder = new Builder();
35
builder.setProperty("Bundle-SymbolicName", "com.example.mybundle");
36
builder.setProperty("Bundle-Version", "1.0.0");
37
builder.setProperty("Export-Package", "com.example.api");
38
builder.addSourcepath(new File("src"));
39
Jar jar = builder.build();
40
jar.write(new File("mybundle.jar"));
41

42
// Work with workspace and projects
43
Workspace workspace = Workspace.getWorkspace(new File("."));
44
Project project = workspace.getProject("my.bundle");
45
if (project != null) {
46
    Collection<Container> dependencies = project.getDependencies();
47
    // Process dependencies...
48
}
49
```
50

51
## Architecture
52

53
bndlib is organized around several key architectural components:
54

55
- **Processing Engine**: Core `Processor`, `Analyzer`, and `Builder` classes that handle bundle creation and analysis
56
- **Workspace Management**: `Workspace` and `Project` classes for managing multi-project builds
57
- **Resource Model**: `Jar` and `Resource` abstractions for manipulating bundle contents
58
- **Plugin System**: Extensible plugin architecture with interfaces like `AnalyzerPlugin` and `RepositoryPlugin`
59
- **Repository Layer**: Pluggable repository system for dependency resolution and artifact storage
60
- **Version Management**: Semantic versioning with OSGi compatibility and API change analysis
61

62
## Capabilities
63

64
### Core OSGi Processing
65

66
Essential OSGi bundle building and analysis functionality. The foundation for all OSGi development workflows.
67

68
```java { .api }
69
public class Processor extends Domain implements Reporter, Registry, Constants, Closeable {
70
    // Constructors
71
    public Processor();
72
    public Processor(Properties props);
73
    public Processor(Processor parent);
74
    
75
    // Property Management
76
    public Properties getProperties();
77
    public String getProperty(String key);
78
    public String getProperty(String key, String deflt);
79
    public void setProperty(String key, String value);
80
    public void unsetProperty(String key);
81
    public void setProperties(Properties properties);
82
    
83
    // Reporter Interface
84
    public SetLocation error(String msg, Object... args);
85
    public SetLocation warning(String msg, Object... args);
86
    public List<String> getErrors();
87
    public List<String> getWarnings();
88
    public boolean isOk();
89
    
90
    // Registry Interface  
91
    public <T> List<T> getPlugins(Class<T> clazz);
92
    public <T> T getPlugin(Class<T> clazz);
93
    
94
    // File Management
95
    public File getBase();
96
    public void setBase(File base);
97
    public File getFile(String file);
98
    
99
    // Configuration and Lifecycle
100
    public void begin();
101
    public boolean refresh();
102
    public Parameters parseHeader(String value);
103
    public void close() throws IOException;
104
}
105

106
public class Analyzer extends Processor {
107
    // Constructors
108
    public Analyzer();
109
    public Analyzer(Jar jar) throws Exception;
110
    public Analyzer(Processor parent);
111
    
112
    // Core Analysis
113
    public void analyze() throws Exception;
114
    public Manifest calcManifest() throws Exception;
115
    public void reset();
116
    
117
    // Jar and Classpath Management  
118
    public Jar getJar();
119
    public Jar setJar(File file) throws IOException;
120
    public Jar setJar(Jar jar);
121
    public List<Jar> getClasspath();
122
    public void addClasspath(Jar jar);
123
    public void addClasspath(File cp) throws IOException;
124
    public void setClasspath(Collection<?> classpath) throws IOException;
125
    public void setClasspath(File[] classpath) throws IOException;
126
    
127
    // Package Analysis Results
128
    public Packages getContained();
129
    public Packages getExports();
130
    public Packages getImports();
131
    public Packages getReferred();
132
    public Set<PackageRef> getPrivates();
133
    public Map<PackageRef, List<PackageRef>> getUses();
134
    
135
    // Bundle Information
136
    public String getBsn();
137
    public String getVersion();
138
    public boolean isNoBundle();
139
    
140
    // Type and Package References
141
    public TypeRef getTypeRef(String binaryClassName);
142
    public PackageRef getPackageRef(String binaryName);
143
    public void referTo(TypeRef ref);
144
}
145

146
public class Builder extends Analyzer {
147
    // Constructors
148
    public Builder();
149
    public Builder(Processor parent);
150
    
151
    // Build Operations
152
    public Jar build() throws Exception;
153
    public Jar[] builds() throws Exception;
154
    public void init() throws Exception;
155
    
156
    // Sub-builder Management
157
    public List<Builder> getSubBuilders() throws Exception;
158
    public Builder getSubBuilder() throws Exception;
159
    
160
    // Source Path Management
161
    public Collection<File> getSourcePath();
162
    public void setSourcepath(File[] files);
163
    public void addSourcepath(File cp);
164
    public void addSourcepath(Collection<File> sourcepath);
165
    
166
    // Bundle Configuration
167
    public boolean hasSources();
168
    public void setDefaults(String bsn, Version version);
169
    public File getOutputFile(String output);
170
    public boolean save(File output, boolean force) throws Exception;
171
}
172
```
173

174
[Core OSGi Processing](./core-osgi-processing.md)
175

176
### Workspace and Project Management
177

178
Multi-project workspace management for organizing and building OSGi bundles in enterprise environments.
179

180
```java { .api }  
181
public class Workspace extends Processor {
182
    // Constructors and Factory Methods
183
    public Workspace(File workspaceDir) throws Exception;
184
    public static Workspace getWorkspace(File workspaceDir) throws Exception;
185
    public static Workspace findWorkspace(File base) throws Exception;
186
    public static Workspace createWorkspace(File wsdir) throws Exception;
187
    
188
    // Project Management
189
    public Project getProject(String bsn);
190
    public Collection<Project> getAllProjects();
191
    public Collection<Project> getCurrentProjects();
192
    public Collection<Project> getBuildOrder() throws Exception;
193
    public Project createProject(String name) throws Exception;
194
    
195
    // Repository Management
196
    public List<RepositoryPlugin> getRepositories();
197
    public RepositoryPlugin getRepository(String repo) throws Exception;
198
    public WorkspaceRepository getWorkspaceRepository();
199
    
200
    // Configuration and State
201
    public boolean refresh();
202
    public boolean isValid();
203
    public boolean isOffline();
204
    public WorkspaceLayout getLayout();
205
    
206
    // Thread Safety
207
    public <T> T readLocked(Callable<T> callable) throws Exception;
208
    public <T> T writeLocked(Callable<T> callable) throws Exception;
209
}
210

211
public class Project extends Processor {
212
    // Constructors
213
    public Project(Workspace workspace, File buildDir);
214
    
215
    // Project State and Identity
216
    public String getName();
217
    public boolean isValid();
218
    public Workspace getWorkspace();
219
    public boolean refresh();
220
    
221
    // Builder Management
222
    public ProjectBuilder getBuilder(ProjectBuilder parent) throws Exception;
223
    public Builder getSubBuilder(File bndFile) throws Exception;
224
    
225
    // Bundle and Container Management
226
    public List<Container> getBundles(Strategy strategyx, String spec, String source) throws Exception;
227
    public Container getBundle(String bsn, String range, Strategy strategy, Map<String, String> attrs) throws Exception;
228
    public Collection<Container> getDeliverables() throws Exception;
229
    
230
    // Path Management
231
    public Collection<Container> getBuildpath() throws Exception;
232
    public Collection<Container> getTestpath() throws Exception;
233
    public Collection<Container> getRunpath() throws Exception;
234
    public Collection<File> getSourcePath() throws Exception;
235
    
236
    // Build Operations
237
    public void prepare() throws Exception;
238
    public File[] build() throws Exception;
239
    public File[] build(boolean underTest) throws Exception;
240
    public boolean isStale() throws Exception;
241
    public void clean() throws Exception;
242
    
243
    // Dependencies
244
    public Collection<Project> getDependson() throws Exception;
245
    public Set<Project> getBuildDependencies() throws Exception;
246
    public Set<Project> getTestDependencies() throws Exception;
247
    
248
    // Release and Testing
249
    public void release() throws Exception;
250
    public void test() throws Exception;
251
    public void run() throws Exception;
252
}
253
```
254

255
[Workspace and Project Management](./workspace-project-management.md)
256

257
### JAR and Resource Management
258

259
Low-level JAR file manipulation and resource handling for OSGi bundles.
260

261
```java { .api }
262
public class Jar implements Closeable {
263
    public void putResource(String path, Resource resource);
264
    public Resource getResource(String path);
265
    public void write(File file) throws Exception;
266
    public Manifest getManifest() throws Exception;
267
}
268

269
public interface Resource extends Closeable {
270
    public InputStream openInputStream() throws IOException;
271
    public void write(OutputStream out) throws Exception;
272
    public long lastModified();
273
    public void setExtra(String extra);
274
}
275
```
276

277
[JAR and Resource Management](./jar-resource-management.md)
278

279
### Version Management
280

281
OSGi-compliant version handling and semantic versioning for dependency resolution.
282

283
```java { .api }
284
public class Version implements Comparable<Version> {
285
    public Version(int major, int minor, int micro, String qualifier);
286
    public int getMajor();
287
    public int getMinor(); 
288
    public int getMicro();
289
    public String getQualifier();
290
}
291

292
public class VersionRange {
293
    public boolean includes(Version version);
294
    public static VersionRange parseVersionRange(String range);
295
}
296
```
297

298
[Version Management](./version-management.md)
299

300
### Repository System
301

302
Pluggable repository architecture for artifact storage and dependency resolution.
303

304
```java { .api }
305
public interface RepositoryPlugin extends Plugin {
306
    public File get(String bsn, Version version, Map<String,String> properties) throws Exception;
307
    public List<String> list(String regex) throws Exception;
308
    public SortedSet<Version> versions(String bsn) throws Exception;
309
}
310

311
public class ResourcesRepository implements Repository {
312
    public void add(Resource resource);
313
    public Collection<Capability> findProviders(Requirement requirement);
314
}
315
```
316

317
[Repository System](./repository-system.md)
318

319
### Header Processing
320

321
OSGi manifest header parsing and manipulation utilities.
322

323
```java { .api }
324
public class Parameters implements Map<String, Attrs> {
325
    public Parameters(String header);
326
    public Attrs get(String key);
327
    public Attrs put(String key, Attrs value);
328
}
329

330
public class Attrs extends LinkedHashMap<String, String> {
331
    public Version getVersion();
332
    public <T> T getTyped(String key);
333
}
334
```
335

336
[Header Processing](./header-processing.md)
337

338
### API Comparison and Diffing
339

340
Semantic versioning analysis based on API changes between bundle versions.
341

342
```java { .api }
343
public class DiffImpl implements Diff {
344
    public Diff diff(Jar newer, Jar older) throws Exception;
345
    public Tree tree(Jar jar) throws Exception;
346
}
347

348
public class Baseline {
349
    public Set<Info> baseline(Jar jar, Jar baseline, Instructions instructions) throws Exception;
350
}
351
```
352

353
[API Comparison and Diffing](./api-comparison-diffing.md)
354

355
### Plugin Architecture
356

357
Extensible plugin system for customizing build processes and analysis.
358

359
```java { .api }
360
public interface Plugin {
361
    public void setProperties(Map<String,String> map);
362
    public void setReporter(Reporter processor);
363
}
364

365
public interface AnalyzerPlugin extends Plugin {
366
    public boolean analyzeJar(Analyzer analyzer) throws Exception;
367
}
368
```
369

370
[Plugin Architecture](./plugin-architecture.md)
371

372
## Types
373

374
```java { .api }
375
public interface Constants {
376
    String BUNDLE_SYMBOLICNAME = "Bundle-SymbolicName";
377
    String BUNDLE_VERSION = "Bundle-Version";
378
    String EXPORT_PACKAGE = "Export-Package";
379
    String IMPORT_PACKAGE = "Import-Package";
380
    // ... extensive constants for OSGi headers
381
}
382

383
public interface Reporter {
384
    void error(String msg, Object... args);
385
    void warning(String msg, Object... args);
386
    void progress(float progress, String msg, Object... args);
387
}
388

389
public class Container {
390
    public File getFile();
391
    public String getBundleSymbolicName();
392
    public Version getVersion();
393
    public String getError();
394
}
395
```