0
# Repository System
1

2
Pluggable repository architecture for artifact storage and dependency resolution, enabling flexible bundle management across different storage backends.
3

4
## Capabilities
5

6
### RepositoryPlugin
7

8
Base interface for all repository implementations providing artifact storage and retrieval capabilities.
9

10
```java { .api }
11
/**
12
 * Base interface for all repository implementations
13
 */
14
public interface RepositoryPlugin extends Plugin {
15
    /** Get artifact file by bundle symbolic name and version */
16
    public File get(String bsn, Version version, Map<String,String> properties) throws Exception;
17
    
18
    /** List all bundle symbolic names matching regex pattern */
19
    public List<String> list(String regex) throws Exception;
20
    
21
    /** Get all available versions for a bundle symbolic name */
22
    public SortedSet<Version> versions(String bsn) throws Exception;
23
    
24
    /** Get repository name */
25
    public String getName();
26
    
27
    /** Get repository location */
28
    public String getLocation();
29
    
30
    /** Check if repository can write */
31
    public boolean canWrite();
32
    
33
    /** Store artifact in repository */
34
    public PutResult put(Jar jar, PutOptions options) throws Exception;
35
    
36
    /** Get repository tooltip/description */
37
    public String tooltip(Object... target) throws Exception;
38
    
39
    /** Get repository title */
40
    public String getTitle(Object... target) throws Exception;
41
}
42

43
/**
44
 * Result of put operation
45
 */
46
public class PutResult {
47
    public File artifact;
48
    public String digest;
49
    public boolean isNew;
50
}
51

52
/**
53
 * Options for put operation
54
 */
55
public class PutOptions {
56
    public boolean allowSnapshots = false;
57
    public File context;
58
    public String type;
59
}
60
```
61

62
**Usage Examples:**
63

64
```java
65
import aQute.bnd.service.RepositoryPlugin;
66
import aQute.bnd.version.Version;
67

68
// Use repository plugin
69
RepositoryPlugin repo = workspace.getPlugin(RepositoryPlugin.class).get(0);
70

71
// List available bundles
72
List<String> bundles = repo.list("org\\.apache\\..*");
73
for (String bsn : bundles) {
74
    System.out.println("Bundle: " + bsn);
75
    
76
    // Get available versions
77
    SortedSet<Version> versions = repo.versions(bsn);
78
    System.out.println("  Versions: " + versions);
79
    
80
    // Get latest version
81
    if (!versions.isEmpty()) {
82
        Version latest = versions.last();
83
        File file = repo.get(bsn, latest, null);
84
        if (file != null) {
85
            System.out.println("  Latest: " + file);
86
        }
87
    }
88
}
89
```
90

91
### ResourcesRepository
92

93
In-memory repository implementation for OSGi resources with capability and requirement matching.
94

95
```java { .api }
96
/**
97
 * In-memory repository of OSGi resources
98
 */
99
public class ResourcesRepository implements Repository {
100
    /** Create empty repository */
101
    public ResourcesRepository();
102
    
103
    /** Add resource to repository */
104
    public void add(Resource resource);
105
    
106
    /** Add all resources from collection */
107
    public void addAll(Collection<? extends Resource> resources);
108
    
109
    /** Find providers for a requirement */
110
    public Collection<Capability> findProviders(Requirement requirement);
111
    
112
    /** Get all resources */
113
    public Collection<Resource> getResources();
114
    
115
    /** Remove resource */
116
    public boolean remove(Resource resource);
117
    
118
    /** Clear all resources */
119
    public void clear();
120
    
121
    /** Get repository size */
122
    public int size();
123
}
124
```
125

126
### FileRepo
127

128
File-based repository implementation storing bundles in directory structure.
129

130
```java { .api }
131
/**
132
 * File-based repository implementation
133
 */
134
public class FileRepo implements RepositoryPlugin {
135
    /** Create file repository at location */
136
    public FileRepo(String name, File location, boolean readonly);
137
    
138
    /** Set repository location */
139
    public void setLocation(String location);
140
    
141
    /** Get repository location */
142
    public String getLocation();
143
    
144
    /** Set readonly flag */
145
    public void setReadonly(boolean readonly);
146
    
147
    /** Check if repository is readonly */
148
    public boolean isReadonly();
149
    
150
    /** Get file for bundle */
151
    public File get(String bsn, Version version, Map<String,String> properties) throws Exception;
152
    
153
    /** Store bundle in repository */
154
    public PutResult put(Jar jar, PutOptions options) throws Exception;
155
    
156
    /** List bundles matching pattern */
157
    public List<String> list(String regex) throws Exception;
158
    
159
    /** Get versions for bundle */
160
    public SortedSet<Version> versions(String bsn) throws Exception;
161
    
162
    /** Refresh repository index */
163
    public void refresh() throws Exception;
164
}
165
```
166

167
**Usage Examples:**
168

169
```java
170
import aQute.bnd.service.RepositoryPlugin.PutOptions;
171
import aQute.bnd.service.RepositoryPlugin.PutResult;
172

173
// Create file repository
174
FileRepo repo = new FileRepo("local", new File("repository"), false);
175

176
// Store bundle
177
Jar bundle = new Jar(new File("mybundle.jar"));
178
PutOptions options = new PutOptions();
179
options.allowSnapshots = true;
180
PutResult result = repo.put(bundle, options);
181

182
if (result.isNew) {
183
    System.out.println("Stored new bundle: " + result.artifact);
184
} else {
185
    System.out.println("Bundle already exists: " + result.artifact);
186
}
187

188
// Retrieve bundle
189
File retrieved = repo.get("com.example.mybundle", 
190
    Version.parseVersion("1.0.0"), null);
191
if (retrieved != null) {
192
    System.out.println("Retrieved: " + retrieved);
193
}
194
```
195

196
### Repository Indexing
197

198
Classes for creating and managing repository indexes for efficient bundle discovery.
199

200
```java { .api }
201
/**
202
 * Creates repository indexes from bundle collections
203
 */
204
public class SimpleIndexer {
205
    /** Index bundles to output stream */
206
    public static void index(Set<File> bundles, OutputStream out, 
207
                           Map<String,String> config) throws Exception;
208
    
209
    /** Index single bundle */
210
    public static Resource indexBundle(File bundle) throws Exception;
211
    
212
    /** Create index from directory */
213
    public static void indexDirectory(File directory, OutputStream out) throws Exception;
214
}
215

216
/**
217
 * Repository index reader
218
 */
219
public class RepositoryIndexReader {
220
    /** Read index from stream */
221
    public static Collection<Resource> readIndex(InputStream in) throws Exception;
222
    
223
    /** Read index from file */
224
    public static Collection<Resource> readIndex(File indexFile) throws Exception;
225
    
226
    /** Parse index XML */
227
    public static Repository parseIndex(InputStream in) throws Exception;
228
}
229
```
230

231
### Remote Repository Support
232

233
Support for remote repositories with HTTP-based access.
234

235
```java { .api }
236
/**
237
 * HTTP-based remote repository
238
 */
239
public class HttpRepository implements RepositoryPlugin {
240
    /** Create HTTP repository */
241
    public HttpRepository(String name, String url);
242
    
243
    /** Set repository URL */
244
    public void setUrl(String url);
245
    
246
    /** Get repository URL */
247
    public String getUrl();
248
    
249
    /** Set authentication credentials */
250
    public void setCredentials(String username, String password);
251
    
252
    /** Set connection timeout */
253
    public void setTimeout(int timeoutMs);
254
    
255
    /** Enable/disable caching */
256
    public void setCaching(boolean enabled);
257
    
258
    /** Set cache directory */
259
    public void setCacheDir(File cacheDir);
260
    
261
    /** Download bundle */
262
    public File get(String bsn, Version version, Map<String,String> properties) throws Exception;
263
    
264
    /** Get remote index */
265
    public Repository getIndex() throws Exception;
266
}
267
```
268

269
### Maven Repository Integration
270

271
Integration with Maven repositories for dependency resolution.
272

273
```java { .api }
274
/**
275
 * Maven repository integration
276
 */
277
public class MavenRepository implements RepositoryPlugin {
278
    /** Create Maven repository */
279
    public MavenRepository(String name, String url);
280
    
281
    /** Set Maven repository URL */
282
    public void setUrl(String url);
283
    
284
    /** Set local repository location */
285
    public void setLocal(File localRepo);
286
    
287
    /** Resolve Maven artifact */
288
    public File get(String bsn, Version version, Map<String,String> properties) throws Exception;
289
    
290
    /** Convert OSGi coordinates to Maven */
291
    public MavenCoordinate toMavenCoordinate(String bsn, Version version);
292
    
293
    /** Convert Maven coordinate to OSGi */
294
    public BundleCoordinate toBundleCoordinate(MavenCoordinate coord);
295
}
296

297
/**
298
 * Maven artifact coordinates
299
 */
300
public class MavenCoordinate {
301
    public String groupId;
302
    public String artifactId;
303
    public String version;
304
    public String classifier;
305
    public String type;
306
    
307
    public String toString(); // groupId:artifactId:version[:classifier][@type]
308
}
309

310
/**
311
 * OSGi bundle coordinates
312
 */
313
public class BundleCoordinate {
314
    public String bundleSymbolicName;
315
    public Version version;
316
    
317
    public String toString(); // bsn;version=version
318
}
319
```
320

321
**Complete Repository System Example:**
322

323
```java
324
import aQute.bnd.service.RepositoryPlugin;
325
import aQute.bnd.osgi.repository.ResourcesRepository;
326
import aQute.lib.deployer.FileRepo;
327

328
// Complete repository system usage
329
public class RepositoryExample {
330
    
331
    public void demonstrateRepositorySystem() throws Exception {
332
        // Create different repository types
333
        FileRepo localRepo = new FileRepo("local", new File("local-repo"), false);
334
        HttpRepository centralRepo = new HttpRepository("central", 
335
            "https://repo1.maven.org/maven2");
336
        MavenRepository mavenRepo = new MavenRepository("maven-central",
337
            "https://repo1.maven.org/maven2");
338
        
339
        // Store bundle in local repository
340
        Jar myBundle = createBundle();
341
        PutOptions options = new PutOptions();
342
        options.allowSnapshots = true;
343
        
344
        PutResult result = localRepo.put(myBundle, options);
345
        System.out.println("Stored: " + result.artifact);
346
        
347
        // Search across repositories
348
        String[] repositories = {"local", "central", "maven-central"};
349
        String targetBundle = "org.apache.commons.lang3";
350
        
351
        for (String repoName : repositories) {
352
            RepositoryPlugin repo = getRepository(repoName);
353
            
354
            // List available versions
355
            SortedSet<Version> versions = repo.versions(targetBundle);
356
            if (!versions.isEmpty()) {
357
                System.out.println(repoName + " has " + targetBundle + 
358
                                 " versions: " + versions);
359
                
360
                // Get latest version
361
                Version latest = versions.last();
362
                File bundle = repo.get(targetBundle, latest, null);
363
                if (bundle != null) {
364
                    System.out.println("Downloaded: " + bundle);
365
                    
366
                    // Analyze downloaded bundle
367
                    analyzeBundle(bundle);
368
                }
369
                break; // Found it, stop searching
370
            }
371
        }
372
        
373
        // Create in-memory repository for resolution
374
        ResourcesRepository memRepo = new ResourcesRepository();
375
        
376
        // Add resources to memory repository
377
        memRepo.add(createResourceFromBundle(myBundle));
378
        
379
        // Find providers for requirements
380
        Requirement requirement = createRequirement("osgi.wiring.package", 
381
            "com.example.api");
382
        Collection<Capability> providers = memRepo.findProviders(requirement);
383
        
384
        System.out.println("Providers for requirement: " + providers.size());
385
        
386
        // Create repository index
387
        Set<File> bundles = new HashSet<>();
388
        bundles.add(new File("bundle1.jar"));
389
        bundles.add(new File("bundle2.jar"));
390
        
391
        try (FileOutputStream indexOut = new FileOutputStream("repository.xml")) {
392
            SimpleIndexer.index(bundles, indexOut, Collections.emptyMap());
393
        }
394
        
395
        System.out.println("Created repository index");
396
    }
397
    
398
    private Jar createBundle() throws Exception {
399
        // Implementation to create a sample bundle
400
        Jar jar = new Jar("example");
401
        // ... add content
402
        return jar;
403
    }
404
    
405
    private RepositoryPlugin getRepository(String name) {
406
        // Implementation to get repository by name
407
        return null;
408
    }
409
    
410
    private void analyzeBundle(File bundle) throws Exception {
411
        try (Jar jar = new Jar(bundle)) {
412
            System.out.println("  Bundle-SymbolicName: " + jar.getBsn());
413
            System.out.println("  Bundle-Version: " + jar.getVersion());
414
        }
415
    }
416
    
417
    private Resource createResourceFromBundle(Jar bundle) throws Exception {
418
        // Convert bundle to OSGi resource
419
        return null;
420
    }
421
    
422
    private Requirement createRequirement(String namespace, String name) {
423
        // Create OSGi requirement
424
        return null;
425
    }
426
}
427
```