Requirements for New Repository API

Background

Repositories are used in bnd to:

1. Provide resources for both build and runtime dependencies;
2. Provide baseline resources for version checking;
3. Resolve requirements (answering to the OSGi Repository Service API as specified in Compendium chapter 132);
4. Provide templates for new workspaces, projects and other artifacts.

These use cases all evolved at different times and the API interfaces to support them were invented and evolved organically. Now the repository APIs are a jumble with overlapping and non-intuitive functions. The following interfaces currently exist:

• org.osgi.service.repository.Repository: provides Capabilities matching a specified set of Requirements. Used in Resolution. Can provide the URI of a resource but does not provide API for downloading it, caching it etc.
• aQute.bnd.service.RepositoryPlugin: Enables fetching of a resource based on its ID and version. Also allows listing of available versions for a specified ID. The concept of "version" has been stretched to include many special cases: "project", "snapshot", "latest", "file" and "hash".
• aQute.bnd.service.RemoteRepositoryPlugin (extends aQute.bnd.service.RepositoryPlugin): Adds the ability to query and find a resource without forcing its immediate download. Also adds caching functionality.
• aQute.bnd.service.repository.SearchableRepository: Supports searching for additional resources that are outside the "main" content of the repository.
• aQute.bnd.service.repository.InfoRepository: Adds metadata for repository entries, such as description, SHA256 hash, etc.
• aQute.bnd.service.Actionable: Provides actions that can be executed against resources inside the repository, e.g. force download, upgrade, delete etc.
• aQute.bnd.service.Refreshable: Allows the repository to reload/refresh its contents.

Gaps in Functionality

• Write-only repos: in some scenarios we want a repository that we can deploy build results into, but not allow that repo to provide build/run dependencies.
• Baseline-only repos: we may want a repository for version baselining, but we don't want the contents of this repo to get into the build or runtime.
• No unified approach to progress reporting for downloads.
• Views -- the ability to define local subsets of a large repository, in order to restrict visibility and make resolutions sane. Supported by JPM but this should be generalised.
• Common operations – such as delete, refresh – are not consistently available, but rely on the arbitrary actions that may have been contributed via Actionable. This makes tooling and documentation harder than necessary ("How do I delete a resource?" – answer: "Well it depends on the type of repo...").

Proposal

In bnd/Bndtools 3.2 we should redesign the repository APIs and the implementations we ship with bnd. However since this is 3.2 and not 4.0, we must retain backwards compatibility for workspaces developed with 3.0-3.1. This means all existing repo implementation classes (e.g. FixedIndexedRepo, FileRepo etc) must continue to exist, though they may simply delegate to a new, unified repository implementation.