0
# Workspace Management
1

2
Comprehensive multi-project workspace management system providing dependency resolution, build coordination, and repository integration for complex OSGi development environments.
3

4
## Capabilities
5

6
### Workspace Creation and Access
7

8
Create or access existing workspaces from filesystem directories containing bnd workspace configurations.
9

10
```java { .api }
11
/**
12
 * Get or create a workspace from a directory containing workspace configuration
13
 * @param dir - Directory containing workspace configuration files (like cnf/)
14
 * @return Workspace instance for project management
15
 * @throws Exception if workspace cannot be created or accessed
16
 */
17
public static Workspace getWorkspace(File dir) throws Exception;
18

19
/**
20
 * Find workspace by walking up directory tree from given location
21
 * @param start - Starting directory to search from
22
 * @return Workspace instance if found
23
 * @throws Exception if no workspace found or cannot be accessed
24
 */
25
public static Workspace findWorkspace(File start) throws Exception;
26

27
/**
28
 * Create a default workspace in the given directory
29
 * @param dir - Directory where workspace should be created
30
 * @return Newly created workspace
31
 * @throws Exception if workspace creation fails
32
 */
33
public static Workspace createDefaultWorkspace(File dir) throws Exception;
34
```
35

36
**Usage Examples:**
37

38
```java
39
import aQute.bnd.build.Workspace;
40
import java.io.File;
41

42
// Access existing workspace
43
Workspace workspace = Workspace.getWorkspace(new File("/path/to/workspace"));
44

45
// Find workspace from project directory
46
Workspace workspace = Workspace.findWorkspace(new File("/path/to/project"));
47

48
// Create new workspace
49
Workspace workspace = Workspace.createDefaultWorkspace(new File("/path/to/new"));
50
```
51

52
### Project Management
53

54
Manage individual projects within the workspace, including creation, access, and dependency resolution.
55

56
```java { .api }
57
/**
58
 * Get all projects in the workspace
59
 * @return Collection of all workspace projects
60
 * @throws Exception if projects cannot be enumerated
61
 */
62
public Collection<Project> getAllProjects() throws Exception;
63

64
/**
65
 * Get a specific project by name
66
 * @param name - Project name (directory name)
67
 * @return Project instance or null if not found
68
 * @throws Exception if project access fails
69
 */
70
public Project getProject(String name) throws Exception;
71

72
/**
73
 * Create a new project in the workspace
74
 * @param name - Project name (will create directory with this name)
75
 * @return Newly created project
76
 * @throws Exception if project creation fails
77
 */
78
public Project createProject(String name) throws Exception;
79

80
/**
81
 * Get build order for all projects based on dependencies
82
 * @return List of projects in dependency order
83
 * @throws Exception if dependency resolution fails
84
 */
85
public List<Project> getBuildOrder() throws Exception;
86
```
87

88
**Usage Examples:**
89

90
```java
91
// Get all projects
92
Collection<Project> allProjects = workspace.getAllProjects();
93

94
// Access specific project
95
Project myProject = workspace.getProject("com.example.myproject");
96

97
// Create new project
98
Project newProject = workspace.createProject("com.example.newproject");
99

100
// Get build order
101
List<Project> buildOrder = workspace.getBuildOrder();
102
for (Project project : buildOrder) {
103
    project.build();
104
}
105
```
106

107
### Repository Integration
108

109
Access and manage repositories configured for the workspace, including artifact resolution and caching.
110

111
```java { .api }
112
/**
113
 * Get all repositories configured for this workspace
114
 * @return List of repository plugins
115
 */
116
public List<RepositoryPlugin> getRepositories();
117

118
/**
119
 * Get Maven repository integration
120
 * @return Maven repository instance
121
 */
122
public Maven getMaven();
123

124
/**
125
 * Get workspace cache directory
126
 * @param name - Cache name/type
127
 * @return File pointing to cache directory
128
 */
129
public File getCache(String name);
130

131
/**
132
 * Check if workspace is in offline mode
133
 * @return true if operating offline
134
 */
135
public boolean isOffline();
136

137
/**
138
 * Set offline mode for the workspace
139
 * @param offline - true to enable offline mode
140
 */
141
public void setOffline(boolean offline);
142
```
143

144
**Usage Examples:**
145

146
```java
147
// Access repositories
148
List<RepositoryPlugin> repos = workspace.getRepositories();
149
for (RepositoryPlugin repo : repos) {
150
    Set<String> bundles = repo.list(null);
151
}
152

153
// Maven integration
154
Maven maven = workspace.getMaven();
155

156
// Cache management
157
File bundleCache = workspace.getCache("bundles");
158

159
// Offline mode
160
workspace.setOffline(true);
161
boolean offline = workspace.isOffline();
162
```
163

164
### Workspace Configuration
165

166
Manage workspace-level configuration, properties, and settings that apply to all projects.
167

168
```java { .api }
169
/**
170
 * Refresh workspace configuration and project states
171
 * @throws Exception if refresh fails
172
 */
173
public void refresh() throws Exception;
174

175
/**
176
 * Get workspace layout type
177
 * @return WorkspaceLayout enum value
178
 */
179
public WorkspaceLayout getLayout();
180

181
/**
182
 * Get workspace base directory
183
 * @return File pointing to workspace root
184
 */
185
public File getBase();
186

187
/**
188
 * Get configuration directory (typically cnf/)
189
 * @return File pointing to configuration directory
190
 */
191
public File getBuildDir();
192
```
193

194
**Usage Examples:**
195

196
```java
197
// Refresh workspace after external changes
198
workspace.refresh();
199

200
// Check workspace layout
201
WorkspaceLayout layout = workspace.getLayout();
202
if (layout == WorkspaceLayout.BND) {
203
    // Handle bnd-style workspace
204
}
205

206
// Access workspace directories
207
File workspaceRoot = workspace.getBase();
208
File configDir = workspace.getBuildDir();
209
```
210

211
### Project Building and Testing
212

213
Build and test individual projects within the workspace context with proper dependency resolution.
214

215
```java { .api }
216
/**
217
 * Build a specific project
218
 * @param projectName - Name of project to build
219
 * @return Generated JAR bundle
220
 * @throws Exception if build fails
221
 */
222
public Jar buildProject(String projectName) throws Exception;
223

224
/**
225
 * Test a specific project
226
 * @param projectName - Name of project to test
227
 * @return Test results
228
 * @throws Exception if testing fails
229
 */
230
public ProjectTester testProject(String projectName) throws Exception;
231

232
/**
233
 * Clean build artifacts for a project
234
 * @param projectName - Name of project to clean
235
 * @throws Exception if clean operation fails
236
 */
237
public void cleanProject(String projectName) throws Exception;
238
```
239

240
## Types
241

242
```java { .api }
243
/**
244
 * Workspace layout types
245
 */
246
public enum WorkspaceLayout {
247
    BND,      // Traditional bnd workspace layout
248
    MAVEN,    // Maven-style workspace layout  
249
    GRADLE    // Gradle-style workspace layout
250
}
251

252
/**
253
 * Workspace repository implementation
254
 */
255
public class WorkspaceRepository implements RepositoryPlugin, Actionable {
256
    public Set<String> list(String filter) throws Exception;
257
    public File get(String bsn, Version range, Map<String,String> properties) throws Exception;
258
    public PutResult put(Jar jar, PutOptions options) throws Exception;
259
}
260

261
/**
262
 * Maven integration for workspace
263
 */
264
public class Maven {
265
    public File getRepository();
266
    public List<String> getLocalRepository();
267
    public void resolve(Collection<String> dependencies) throws Exception;
268
}
269

270
/**
271
 * Project launcher for running and testing projects
272
 */
273
public class ProjectLauncher {
274
    public int launch() throws Exception;
275
    public void setTimeout(long timeout);
276
    public long getTimeout();
277
    public void setTrace(boolean trace);
278
    public boolean getTrace();
279
}
280

281
/**
282
 * JUnit-specific project launcher
283
 */
284
public class JUnitLauncher extends ProjectLauncher {
285
    public int test() throws Exception;
286
    public List<String> getTestNames();
287
    public void setTests(List<String> tests);
288
}
289

290
/**
291
 * Project tester for running tests
292
 */
293
public class ProjectTester {
294
    public boolean test() throws Exception;
295
    public List<String> getErrors();
296
    public int getFailures();
297
    public int getTests();
298
}
299
```