Requirements for New Repository API
Repositories are used in bnd to:
- Provide resources for both build and runtime dependencies;
- Provide baseline resources for version checking;
- Resolve requirements (answering to the OSGi Repository Service API as specified in Compendium chapter 132);
- 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(extendsaQute.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.
- 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...").
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.
The new API may still consist of multiple interfaces, since extended functionality will not be relevant within every type of repository.
All repos have the ability to search for bundles by BSN and version, but the version may be a special string.
When version is either "project", "snapshot" or "file", bnd should not even consult the repository, so we can ignore these. That leaves "latest", "hash" and actual version ranges.
Bnd defines a strategy for selecting a single version when multiple matches are possible. The strategies are: Lowest, Exact and Highest. Strictly, the repository does not need to know the strategy (it can just return all the versions it knows about within the required range, and bnd will make the selection). However there are useful optimisations if the repository knows the strategy.
Suggestion: the input to the repository search should be a single Search object, with all of the context of the search such as BSN, version, strategy and other properties attached.
Resource identities in Maven are split into group and artifact. We need to have a consistent scheme for addressing these, not just a hacky scheme around our single identity field.
RepositoryPlugin supports listing available BSNs and, for each BSN, available versions. This information is used in the Repositories View and various dialogs/wizards in Bndtools.
Some external repositories do not support listing contents at all (e.g. Maven Central, Nexus) but still support searches and getting specific resources by identity and version. Should we have explicit support for these kinds of repos? Not providing a list of all content is actually sensible in large repos, but the visual feedback in Bndtools is inadequate, we just present an empty repo.