0
# Workspace and Project Management
1

2
Multi-project workspace management for organizing and building OSGi bundles in enterprise environments.
3

4
## Capabilities
5

6
### Workspace
7

8
Represents a BND workspace containing multiple projects, providing centralized configuration and project management.
9

10
```java { .api }
11
/**
12
 * Represents a BND workspace containing multiple projects
13
 */
14
public class Workspace extends Processor {
15
    // Constructors
16
    public Workspace(File workspaceDir) throws Exception;
17
    public Workspace(File workspaceDir, String bndDir) throws Exception;
18
    
19
    // Static Factory Methods
20
    public static Workspace getWorkspace(File workspaceDir) throws Exception;
21
    public static Workspace findWorkspace(File base) throws Exception;
22
    public static Workspace getWorkspace(String path) throws Exception;
23
    public static Workspace createDefaultWorkspace() throws Exception;
24
    public static Workspace createWorkspace(File wsdir) throws Exception;
25
    public static Project getProject(File projectDir) throws Exception;
26
    
27
    // Project Management
28
    public Project getProject(String bsn);
29
    public Project getProjectFromFile(File projectDir);
30
    public Collection<Project> getAllProjects();
31
    public Collection<Project> getCurrentProjects();
32
    public Collection<Project> getBuildOrder() throws Exception;
33
    public boolean isPresent(String name);
34
    public Project createProject(String name) throws Exception;
35
    
36
    // Workspace Configuration
37
    public boolean refresh();
38
    public void refreshProjects();
39
    public void forceRefreshProjects();
40
    public void propertiesChanged();
41
    public boolean isValid();
42
    public void checkStructure();
43
    
44
    // Repository Management
45
    public List<RepositoryPlugin> getRepositories();
46
    public Promise<List<RepositoryPlugin>> getInitializedRepositories();
47
    public RepositoryPlugin getRepository(String repo) throws Exception;
48
    public WorkspaceRepository getWorkspaceRepository();
49
    public void refresh(RepositoryPlugin repo);
50
    
51
    // File System
52
    public File getBuildDir();
53
    public void setBuildDir(File buildDir);
54
    public File getCache(String name);
55
    public WorkspaceLayout getLayout();
56
    
57
    // Build and Dependencies
58
    public Maven getMaven();
59
    public boolean isOffline();
60
    public AtomicBoolean getOffline();
61
    public Workspace setOffline(boolean on);
62
    
63
    // Search and Resources  
64
    public Result<Map<String, List<BundleId>>> search(String partialFqn) throws Exception;
65
    public Result<Map<String, List<BundleId>>> search(String packageName, String className) throws Exception;
66
    public Stream<Capability> findProviders(String namespace, String filter) throws Exception;
67
    public Repository getResourceRepository(ResourceRepositoryStrategy strategy) throws Exception;
68
    public Result<File> getBundle(org.osgi.resource.Resource resource);
69
    public Result<File> getBundle(String bsn, Version version, Map<String, String> attrs);
70
    
71
    // Thread Safety
72
    public <T> T readLocked(Callable<T> callable) throws Exception;
73
    public <T> T readLocked(Callable<T> callable, long timeoutInMs) throws Exception;
74
    public <T> T writeLocked(Callable<T> callable) throws Exception;
75
    public <T> T writeLocked(Callable<T> callable, long timeoutInMs) throws Exception;
76
    public void writeLocked(Runnable runnable) throws Exception;
77
    
78
    // Gestalts and Configuration
79
    public static void addGestalt(String part, Attrs attrs);
80
    public Attrs getGestalt(String part);
81
    public Parameters getGestalt();
82
    
83
    // Workspace State
84
    public boolean isDefaultWorkspace();
85
    public boolean isInteractive();
86
    public String getDriver();
87
    public void signal();
88
    public void signal(Reporter reporter);
89
}
90
```
91

92
**Usage Examples:**
93

94
```java
95
import aQute.bnd.build.Workspace;
96
import aQute.bnd.build.Project;
97

98
// Open workspace
99
Workspace workspace = Workspace.getWorkspace(new File("."));
100
if (workspace.isValid()) {
101
    System.out.println("Workspace: " + workspace.getBase());
102
    
103
    // List all projects
104
    for (Project project : workspace.getProjects()) {
105
        System.out.println("Project: " + project.getName());
106
    }
107
    
108
    // Get specific project
109
    Project myProject = workspace.getProject("com.example.bundle");
110
    if (myProject != null) {
111
        System.out.println("Found project: " + myProject.getName());
112
    }
113
}
114

115
workspace.close();
116
```
117

118
### Project
119

120
Represents a BND project within a workspace, managing build configuration and dependencies.
121

122
```java { .api }
123
/**
124
 * Represents a BND project within a workspace
125
 */
126
public class Project extends Processor {
127
    // Constructors
128
    public Project(Workspace workspace, File buildDir);
129
    public Project(Workspace workspace, File unused, File buildFile);
130
    
131
    // Static Factory Methods
132
    public static Project getUnparented(File propertiesFile) throws Exception;
133
    
134
    // Project Identity and State
135
    public String getName();
136
    public boolean isValid();
137
    public boolean isCnf();
138
    public Workspace getWorkspace();
139
    public int getChanged();
140
    public void setChanged();
141
    public boolean refresh();
142
    public void propertiesChanged();
143
    
144
    // Project Builder Management
145
    public ProjectBuilder getBuilder(ProjectBuilder parent) throws Exception;
146
    public Builder getSubBuilder(File bndFile) throws Exception;
147
    public ProjectBuilder getSubBuilder(String string) throws Exception;
148
    
149
    // Bundle and Container Management
150
    public List<Container> getBundles(Strategy strategyx, String spec, String source) throws Exception;
151
    public List<Container> getBundlesWildcard(String bsnPattern, String range, Strategy strategyx, Map<String, String> attrs) throws Exception;
152
    public Container getBundle(String bsn, String range, Strategy strategy, Map<String, String> attrs) throws Exception;
153
    public Container getBundle(org.osgi.resource.Resource r) throws Exception;
154
    public Container getDeliverable(String bsn, Map<String, String> attrs) throws Exception;
155
    public Collection<Container> getDeliverables() throws Exception;
156
    
157
    // Path Management
158
    public Collection<Container> getBuildpath() throws Exception;
159
    public Collection<Container> getTestpath() throws Exception;
160
    public Collection<Container> getRunpath() throws Exception;
161
    public Collection<Container> getRunbundles() throws Exception;
162
    public Collection<Container> getRunFw() throws Exception;
163
    public Collection<Container> getBootclasspath() throws Exception;
164
    public Collection<Container> getClasspath();
165
    public Collection<File> getSourcePath() throws Exception;
166
    public Collection<File> getAllsourcepath() throws Exception;
167
    
168
    // File System and Directories
169
    public File getTarget() throws Exception;
170
    public File getTargetDir();
171
    public File getSrc() throws Exception; // @Deprecated
172
    public File getSrcOutput();
173
    public File getTestSrc();
174
    public File getTestOutput();
175
    public File getOutput() throws Exception;
176
    public File getRunStorage() throws Exception;
177
    
178
    // Build Operations
179
    public void prepare() throws Exception;
180
    public File[] build() throws Exception;
181
    public File[] build(boolean underTest) throws Exception;
182
    public File[] buildLocal(boolean underTest) throws Exception;
183
    public File[] getBuildFiles() throws Exception;
184
    public File[] getBuildFiles(boolean buildIfAbsent) throws Exception;
185
    public boolean isStale() throws Exception;
186
    public boolean getRunBuilds();
187
    public void clean() throws Exception;
188
    
189
    // Dependencies and Projects
190
    public Collection<Project> getDependson() throws Exception;
191
    public Set<Project> getBuildDependencies() throws Exception;
192
    public Set<Project> getTestDependencies() throws Exception;
193
    public Set<Project> getDependents() throws Exception;
194
    
195
    // Release and Deployment
196
    public File release(String jarName, InputStream jarStream) throws Exception;
197
    public URI releaseURI(String jarName, InputStream jarStream) throws Exception;
198
    public File release(String name, String jarName, InputStream jarStream) throws Exception;
199
    public void release() throws Exception;
200
    public void release(String name) throws Exception;
201
    public void release(boolean test) throws Exception;
202
    public void deploy(File file) throws Exception;
203
    public void deploy(String name, File file) throws Exception;
204
    public void deploy() throws Exception;
205
    
206
    // Testing and Running
207
    public void run() throws Exception;
208
    public void runLocal() throws Exception;
209
    public void test() throws Exception;
210
    public void test(List<String> tests) throws Exception;
211
    public void test(File reportDir, List<String> tests) throws Exception;
212
    public void junit() throws Exception;
213
    public ProjectLauncher getProjectLauncher() throws Exception;
214
    public ProjectTester getProjectTester() throws Exception;
215
    public boolean isRunTrace();
216
    public boolean getRunKeep();
217
    public Collection<String> getRunVM();
218
    public Collection<String> getRunProgramArgs();
219
    public Map<String, String> getRunProperties();
220
    
221
    // File and Output Management
222
    public File[] getFiles();
223
    public File getOutputFile(String bsn, String version) throws Exception;
224
    public File getOutputFile(String bsn) throws Exception;
225
    public File saveBuild(Jar jar) throws Exception;
226
    
227
    // Versioning and Packages
228
    public void bump(String mask) throws Exception;
229
    public void bump() throws Exception;
230
    public Map<String, Version> getVersions() throws Exception;
231
    public Collection<String> getBsns() throws Exception;
232
    public Version getVersion(String bsn) throws Exception;
233
    public Packages getExports();
234
    public Packages getImports();
235
    public Packages getContained();
236
    public void setPackageInfo(String packageName, Version newVersion) throws Exception;
237
    public Version getPackageInfo(String packageName) throws Exception;
238
    
239
    // Actions and Commands
240
    public Map<String, Action> getActions();
241
    public void action(String command) throws Exception;
242
    public void action(String command, Object... args) throws Exception;
243
    public void script(String type, String script) throws Exception;
244
    public void script(String type, String script, Object... args) throws Exception;
245
    
246
    // Validation and Analysis
247
    public Jar getValidJar(File f) throws Exception;
248
    public Jar getValidJar(URL url) throws Exception;
249
    public Jar getValidJar(Jar jar, String id) throws Exception;
250
    public void baseline() throws Exception;
251
    public void verifyDependencies(boolean test) throws Exception;
252
    public void compile(boolean test) throws Exception;
253
    
254
    // Utility and Miscellaneous
255
    public boolean isNoBundles();
256
    public boolean isInteractive();
257
    public boolean isStandalone();
258
    public String getChecksum();
259
    public void remove() throws Exception;
260
    public void addClasspath(File f);
261
    public void clearClasspath();
262
    public Jar pack(String profile) throws Exception;
263
    public void setDelayRunDependencies(boolean x);
264
    public List<org.osgi.resource.Resource> getResources();
265
    public RunSpecification getSpecification();
266
    public Parameters getRunSystemPackages();
267
    public Parameters getRunSystemCapabilities();
268
    public ProjectGenerate getGenerate();
269
    public Optional<Processor> findProcessor(File file);
270
    public List<SubProject> getSubProjects();
271
}
272
```
273

274
**Usage Examples:**
275

276
```java
277
import aQute.bnd.build.Project;
278
import aQute.bnd.build.Container;
279
import aQute.bnd.osgi.Jar;
280

281
// Work with project
282
Project project = workspace.getProject("my.bundle");
283
if (project != null) {
284
    // Get dependencies
285
    Collection<Container> dependencies = project.getDependencies();
286
    for (Container dep : dependencies) {
287
        System.out.println("Dependency: " + dep.getBundleSymbolicName() + 
288
                         " v" + dep.getVersion());
289
    }
290
    
291
    // Build project
292
    try {
293
        project.prepare();
294
        File[] deliverables = project.build();
295
        for (File deliverable : deliverables) {
296
            System.out.println("Built: " + deliverable);
297
        }
298
    } catch (Exception e) {
299
        System.err.println("Build failed: " + e.getMessage());
300
    }
301
    
302
    // Get project builder for custom builds
303
    ProjectBuilder builder = project.getBuilder(null);
304
    Jar jar = builder.build();
305
    if (builder.isOk()) {
306
        jar.write(new File("custom-build.jar"));
307
    }
308
    builder.close();
309
}
310
```
311

312
### Container
313

314
Represents a dependency container (JAR, bundle, etc.) with metadata and file access.
315

316
```java { .api }
317
/**
318
 * Represents a dependency container (JAR, bundle, etc.)
319
 */
320
public class Container {
321
    /** Get container file */
322
    public File getFile();
323
    
324
    /** Get bundle symbolic name */
325
    public String getBundleSymbolicName();
326
    
327
    /** Get container version */
328
    public Version getVersion();
329
    
330
    /** Get error message if container is invalid */
331
    public String getError();
332
    
333
    /** Get container type */
334
    public TYPE getType();
335
    
336
    /** Get container manifest */
337
    public Manifest getManifest() throws Exception;
338
    
339
    /** Get container attributes */
340
    public Map<String,String> getAttributes();
341
    
342
    /** Check if container contributes to classpath */
343
    public boolean contributeToClasspath();
344
    
345
    /** Get project reference if container is a project */
346
    public Project getProject();
347
    
348
    /** Get repository plugin that provides this container */
349
    public RepositoryPlugin getRepository();
350
}
351

352
/**
353
 * Container types
354
 */
355
public enum TYPE {
356
    REPO,       // From repository
357
    PROJECT,    // From workspace project  
358
    EXTERNAL,   // External JAR
359
    LIBRARY,    // Library definition
360
    ERROR       // Error container
361
}
362
```
363

364
### ProjectBuilder
365

366
Specialized builder for project-based bundle creation.
367

368
```java { .api }
369
/**
370
 * Specialized builder for project-based bundle creation
371
 */
372
public class ProjectBuilder extends Builder {
373
    /** Get associated project */
374
    public Project getProject();
375
    
376
    /** Build with project configuration */
377
    public Jar build() throws Exception;
378
    
379
    /** Get project dependencies as containers */
380
    public Collection<Container> getClasspath() throws Exception;
381
    
382
    /** Check if dependencies have changed */
383
    public boolean hasSources();
384
    
385
    /** Get last build time */
386
    public long lastModified();
387
}
388
```
389

390
### Build Strategies
391

392
```java { .api }
393
/**
394
 * Strategies for obtaining bundles
395
 */
396
public enum Strategy {
397
    LOWEST,     // Get lowest version
398
    HIGHEST,    // Get highest version
399
    EXACT       // Get exact version match
400
}
401
```
402

403
**Complete Project Workflow Example:**
404

405
```java
406
import aQute.bnd.build.Workspace;
407
import aQute.bnd.build.Project;
408
import aQute.bnd.build.Container;
409
import aQute.bnd.osgi.Jar;
410

411
// Complete project workflow
412
try {
413
    // Open workspace
414
    Workspace workspace = Workspace.getWorkspace(new File("."));
415
    
416
    // Get project
417
    Project project = workspace.getProject("com.example.mybundle");
418
    if (project == null) {
419
        throw new RuntimeException("Project not found");
420
    }
421
    
422
    // Analyze dependencies
423
    Collection<Container> buildPath = project.getBuildpath();
424
    System.out.println("Build dependencies:");
425
    for (Container container : buildPath) {
426
        if (container.getError() != null) {
427
            System.err.println("Dependency error: " + container.getError());
428
        } else {
429
            System.out.println("- " + container.getBundleSymbolicName() + 
430
                             " v" + container.getVersion());
431
        }
432
    }
433
    
434
    // Build project
435
    project.prepare();
436
    File[] deliverables = project.build();
437
    
438
    // Verify build results
439
    for (File deliverable : deliverables) {
440
        System.out.println("Built: " + deliverable);
441
        
442
        // Analyze built bundle
443
        try (Jar jar = new Jar(deliverable)) {
444
            System.out.println("Bundle-SymbolicName: " + 
445
                             jar.getBsn());
446
            System.out.println("Bundle-Version: " + 
447
                             jar.getVersion());
448
        }
449
    }
450
    
451
    workspace.close();
452
    
453
} catch (Exception e) {
454
    System.err.println("Build failed: " + e.getMessage());
455
    e.printStackTrace();
456
}
457
```