0
# Core OSGi Processing
1

2
Core OSGi bundle building and analysis functionality that forms the foundation of all OSGi development workflows in bndlib.
3

4
## Capabilities
5

6
### Processor
7

8
Base class for all BND processors providing macro processing, reporting, and property handling.
9

10
```java { .api }
11
/**
12
 * Base class for all BND processors providing macro processing, reporting, and property handling
13
 */
14
public class Processor extends Domain implements Reporter, Registry, Constants, Closeable {
15
    // Constructors
16
    public Processor();
17
    public Processor(Properties props);
18
    public Processor(Processor parent);
19
    public Processor(Properties props, boolean wrap);
20
    public Processor(Processor parent, Properties props, boolean wrap);
21
    
22
    // Property Management
23
    public Properties getProperties();
24
    public String getProperty(String key);
25
    public String getProperty(String key, String deflt);
26
    public void setProperty(String key, String value);
27
    public void unsetProperty(String key);
28
    public String getUnexpandedProperty(String key);
29
    public void setProperties(Properties properties);
30
    public void addProperties(File file) throws Exception;
31
    public void mergeProperties(File file, boolean overwrite);
32
    public Set<String> getPropertyKeys(boolean inherit);
33
    
34
    // Reporter Interface Methods
35
    public SetLocation error(String msg, Object... args);
36
    public SetLocation warning(String msg, Object... args);
37
    public void progress(float progress, String format, Object... args);
38
    public SetLocation exception(Throwable t, String format, Object... args);
39
    public List<String> getErrors();
40
    public List<String> getWarnings();
41
    public boolean isOk();
42
    public boolean isFailOk();
43
    public void trace(String msg, Object... parms);
44
    public boolean isPedantic();
45
    public Location getLocation(String msg);
46
    
47
    // Registry Interface Methods
48
    public <T> List<T> getPlugins(Class<T> clazz);
49
    public <T> T getPlugin(Class<T> clazz);
50
    
51
    // File and Base Management
52
    public File getBase();
53
    public URI getBaseURI();
54
    public void setBase(File base);
55
    public File getFile(String file);
56
    public static File getFile(File base, String file);
57
    public File getPropertiesFile();
58
    public void setPropertiesFile(File source);
59
    public void setProperties(File propertiesFile);
60
    
61
    // Configuration and Analysis
62
    public void begin();
63
    public boolean refresh();
64
    public void forceRefresh();
65
    public boolean exists();
66
    public void clear();
67
    public Parameters parseHeader(String value);
68
    public static Parameters parseHeader(String value, Processor logger);
69
    
70
    // Lifecycle Management
71
    public void close() throws IOException;
72
    public void addClose(AutoCloseable closeable);
73
    public void removeClose(AutoCloseable closeable);
74
    
75
    // Utility Methods
76
    public static boolean isTrue(String value);
77
    public static String join(Collection<?> list);
78
    public static String join(Collection<?> list, String delimiter);
79
    public static Collection<String> split(String s);
80
    public static String merge(String... strings);
81
    public static String formatArrays(String string, Object... parms);
82
    public static String cleanupVersion(String version);
83
}
84
```
85

86
**Usage Examples:**
87

88
```java
89
import aQute.bnd.osgi.Processor;
90

91
// Basic processor usage
92
Processor processor = new Processor();
93
processor.setProperty("Bundle-Version", "1.0.0");
94
processor.setProperty("Bundle-SymbolicName", "com.example.bundle");
95

96
// Check for errors
97
if (!processor.isOk()) {
98
    for (String error : processor.getErrors()) {
99
        System.err.println("Error: " + error);
100
    }
101
}
102

103
// Clean up
104
processor.close();
105
```
106

107
### Analyzer
108

109
Analyzes JAR files and class files to determine OSGi metadata including imports, exports, and contained packages.
110

111
```java { .api }
112
/**
113
 * Analyzes JAR files and class files to determine OSGi metadata
114
 */
115
public class Analyzer extends Processor {
116
    // Constructors
117
    public Analyzer();
118
    public Analyzer(Jar jar) throws Exception;
119
    public Analyzer(Processor parent);
120
    
121
    // Core Analysis
122
    public void analyze() throws Exception;
123
    public Manifest calcManifest() throws Exception;
124
    public void reset();
125
    
126
    // Jar and Classpath Management
127
    public Jar getJar();
128
    public Jar setJar(File file) throws IOException;
129
    public Jar setJar(Jar jar);
130
    public List<Jar> getClasspath();
131
    public void addClasspath(Jar jar);
132
    public void addClasspath(Collection<?> jars) throws IOException;
133
    public void addClasspath(File cp) throws IOException;
134
    public void setClasspath(Collection<?> classpath) throws IOException;
135
    public void setClasspath(File[] classpath) throws IOException;
136
    public void setClasspath(Jar[] classpath);
137
    public void setClasspath(String[] classpath);
138
    
139
    // Package Analysis Results
140
    public Packages getContained();
141
    public Packages getExports();
142
    public Packages getImports();
143
    public Packages getReferred();
144
    public Set<PackageRef> getPrivates();
145
    public Packages getClasspathExports();
146
    public Set<PackageRef> getUnreachable();
147
    public Map<PackageRef, List<PackageRef>> getUses();
148
    public Map<PackageRef, List<PackageRef>> getAPIUses();
149
    
150
    // Class and Type Analysis
151
    public Map<TypeRef, Clazz> getClassspace();
152
    public Clazz findClass(TypeRef typeRef) throws Exception;
153
    public Resource findResource(String path);
154
    public Stream<Resource> findResources(Predicate<String> matches);
155
    
156
    // Bundle Information
157
    public String getBsn();
158
    public String getVersion();
159
    public String getBndVersion();
160
    public long getBndLastModified();
161
    public boolean isNoBundle();
162
    public SortedSet<Clazz.JAVA> getEEs();
163
    public Clazz.JAVA getLowestEE();
164
    public Clazz.JAVA getHighestEE();
165
    
166
    // Type and Package References
167
    public TypeRef getTypeRef(String binaryClassName);
168
    public PackageRef getPackageRef(String binaryName);
169
    public TypeRef getTypeRefFromFQN(String fqn);
170
    public TypeRef getTypeRefFromPath(String path);
171
    public void referTo(TypeRef ref);
172
    public void referToByBinaryName(String binaryClassName);
173
    
174
    // Utility Methods
175
    public String calculateExportsFromContents(Jar bundle);
176
    public Collection<Clazz> getClasses(String... args) throws Exception;
177
    public boolean isImported(PackageRef packageRef);
178
    public boolean assignable(String annoService, String inferredService);
179
    public void mergeManifest(Manifest manifest) throws IOException;
180
    
181
    // Static Utility Methods
182
    public static Properties getManifest(File dirOrJar) throws Exception;
183
    public static String cleanupVersion(String version);
184
}
185
```
186

187
**Usage Examples:**
188

189
```java
190
import aQute.bnd.osgi.Analyzer;
191
import aQute.bnd.osgi.Jar;
192
import aQute.bnd.osgi.Packages;
193

194
// Analyze an existing JAR file
195
Analyzer analyzer = new Analyzer();
196
analyzer.setJar(new Jar(new File("example.jar")));
197
analyzer.analyze();
198

199
// Get discovered packages
200
Packages imports = analyzer.getImports();
201
Packages exports = analyzer.getExports();
202

203
System.out.println("Import packages: " + imports);
204
System.out.println("Export packages: " + exports);
205

206
// Generate manifest
207
Manifest manifest = analyzer.calcManifest();
208
analyzer.close();
209
```
210

211
### Builder
212

213
Builds OSGi bundles from source files and bnd instructions, extending Analyzer with bundle creation capabilities.
214

215
```java { .api }
216
/**
217
 * Builds OSGi bundles from source files and bnd instructions
218
 */
219
public class Builder extends Analyzer {
220
    // Constructors
221
    public Builder();
222
    public Builder(Processor parent);
223
    public Builder(Builder parent);
224
    
225
    // Build Operations
226
    public Jar build() throws Exception;
227
    public Jar[] builds() throws Exception;
228
    public void init() throws Exception;
229
    
230
    // Sub-builder Management
231
    public List<Builder> getSubBuilders() throws Exception;
232
    public Builder getSubBuilder() throws Exception;
233
    public Builder getSubBuilder(File file) throws Exception;
234
    
235
    // Source Path Management
236
    public Collection<File> getSourcePath();
237
    public void setSourcepath(File[] files);
238
    public void addSourcepath(File cp);
239
    public void addSourcepath(Collection<File> sourcepath);
240
    
241
    // Bundle Configuration
242
    public boolean hasSources();
243
    public void setDefaults(String bsn, Version version);
244
    public void removeBundleSpecificHeaders();
245
    public File getOutputFile(String output);
246
    public boolean save(File output, boolean force) throws Exception;
247
    
248
    // Utility and Analysis Methods
249
    public void cleanupVersion(Packages packages, String defaultVersion);
250
    public boolean addAll(Jar to, Jar sub, Instruction filter);
251
    public boolean addAll(Jar to, Jar sub, Instruction filter, String destination);
252
    public boolean isInScope(Collection<File> resources) throws Exception;
253
    public String getClasspathEntrySuffix(File resource) throws Exception;
254
    public boolean doNotCopy(String v);
255
    public boolean doNotCopy(File from);
256
    public Pattern getDoNotCopy();
257
    
258
    // Builder Specification
259
    public Builder from(BuilderSpecification spec) throws IOException;
260
    
261
    // Macro Methods  
262
    public String _maven_version(String args[]);
263
    public String _permissions(String args[]);
264
    public String _githead(String[] args) throws IOException;
265
}
266
```
267

268
**Usage Examples:**
269

270
```java
271
import aQute.bnd.osgi.Builder;
272
import aQute.bnd.osgi.Jar;
273

274
// Build a bundle from source
275
Builder builder = new Builder();
276
builder.setBase(new File("."));
277
builder.setProperty("Bundle-SymbolicName", "com.example.mybundle");
278
builder.setProperty("Bundle-Version", "1.0.0");
279
builder.setProperty("Export-Package", "com.example.api");
280
builder.setProperty("Private-Package", "com.example.impl");
281

282
// Set source and class paths
283
builder.addSourcepath(new File("src"));
284
builder.addClasspath(new File("lib/dependency.jar"));
285

286
// Build the bundle
287
Jar jar = builder.build();
288
if (builder.isOk()) {
289
    jar.write(new File("mybundle.jar"));
290
    System.out.println("Bundle created successfully");
291
} else {
292
    System.err.println("Build failed: " + builder.getErrors());
293
}
294

295
builder.close();
296
```
297

298
### OSGi Constants
299

300
Essential OSGi and BND constants used throughout the processing pipeline.
301

302
```java { .api }
303
/**
304
 * OSGi and BND constants
305
 */
306
public interface Constants {
307
    // OSGi Manifest Headers
308
    String BUNDLE_SYMBOLICNAME = "Bundle-SymbolicName";
309
    String BUNDLE_VERSION = "Bundle-Version";
310
    String BUNDLE_NAME = "Bundle-Name";
311
    String BUNDLE_DESCRIPTION = "Bundle-Description";
312
    String BUNDLE_VENDOR = "Bundle-Vendor";
313
    String BUNDLE_COPYRIGHT = "Bundle-Copyright";
314
    String BUNDLE_CATEGORY = "Bundle-Category";
315
    String BUNDLE_CLASSPATH = "Bundle-ClassPath";
316
    String BUNDLE_ACTIVATOR = "Bundle-Activator";
317
    String BUNDLE_REQUIREDEXECUTIONENVIRONMENT = "Bundle-RequiredExecutionEnvironment";
318
    String BUNDLE_NATIVECODE = "Bundle-NativeCode";
319
    String EXPORT_PACKAGE = "Export-Package";
320
    String IMPORT_PACKAGE = "Import-Package";
321
    String DYNAMICIMPORT_PACKAGE = "DynamicImport-Package";
322
    String REQUIRE_BUNDLE = "Require-Bundle";
323
    String FRAGMENT_HOST = "Fragment-Host";
324
    String BUNDLE_LOCALIZATION = "Bundle-Localization";
325
    String BUNDLE_MANIFESTVERSION = "Bundle-ManifestVersion";
326
    
327
    // BND Instructions
328
    String PRIVATE_PACKAGE = "Private-Package";
329
    String EXPORT_CONTENTS = "Export-Contents";
330
    String INCLUDE_RESOURCE = "Include-Resource";
331
    String CONDITIONAL_PACKAGE = "Conditional-Package";
332
    String BND_LASTMODIFIED = "Bnd-LastModified";
333
    String CREATED_BY = "Created-By";
334
    String TOOL = "Tool";
335
    
336
    // Version Attributes
337
    String VERSION_ATTRIBUTE = "version";
338
    String SPECIFICATION_VERSION = "specification-version";
339
    String BUNDLE_VERSION_ATTRIBUTE = "bundle-version";
340
    
341
    // Resolution Directives
342
    String RESOLUTION_DIRECTIVE = "resolution";
343
    String RESOLUTION_MANDATORY = "mandatory";
344
    String RESOLUTION_OPTIONAL = "optional";
345
    
346
    // Uses Directive
347
    String USES_DIRECTIVE = "uses";
348
}
349
```
350

351
### Package Information
352

353
Core classes for managing package information and dependencies.
354

355
```java { .api }
356
/**
357
 * Represents a collection of packages with their attributes
358
 */
359
public class Packages implements Map<PackageRef, Attrs> {
360
    /** Get package reference by name */
361
    public PackageRef getByFQN(String packageName);
362
    
363
    /** Add package with attributes */
364
    public Attrs put(PackageRef packageRef, Attrs attrs);
365
    
366
    /** Check if package exists */
367
    public boolean containsKey(PackageRef packageRef);
368
    
369
    /** Get all package references */
370
    public Set<PackageRef> keySet();
371
    
372
    /** Merge with another Packages collection */
373
    public void merge(Packages other);
374
}
375

376
/**
377
 * Reference to a Java package
378
 */
379
public class PackageRef implements Comparable<PackageRef> {
380
    /** Get the fully qualified package name */
381
    public String getFQN();
382
    
383
    /** Get binary name (with slashes) */
384
    public String getBinary();
385
    
386
    /** Check if this is the default package */
387
    public boolean isDefaultPackage();
388
    
389
    /** Create package reference from string */
390
    public static PackageRef packageRef(String binaryName);
391
}
392
```