Support for a New Repository Format

This section examines the efforts required to implement support for a new repository format in the Nexus Repository Manager. By default, the repository manager includes support for various repository formats including raw-format, maven2-format and others.

When considering to implement support for a new repository format, it is important to get a good understanding of the format itself as well as the tools and the community working with the format. It might even be necessary to read and understand the source code of potential native, upstream implementations to support a format.

Following are a few questions that can provide some useful answers leading to a better understanding of the format
and necessary steps for implementation;

  • What is this format all about?
  • What tools (client/server) are involved?
  • What communication is performed between client and server?
  • Do any protocols or specifications exist?
  • What authentication method needs to be supported by the repository manager?
  • How can the repository manager authenticate against a proxied remote server?
  • How does the concepts of components and assets used in Nexus Repository Manager map to the format?
  • What is the best way to map the component identifier of name, version and group to the format?
  • What format specific attributes should be stored as components and assets?
  • Is it necessary to rewrite proxied metadata? E.g. proxied metadata contains absolute URLs to proxied server that it has to rewrite to point to repository manager.
  • Are there any special features that should be considered?

To provide sufficient support for users, a new repository format needs to include a number of features:

  • proxying components from remote repositories
  • storing and managing components in a hosted repository
  • exposing multiple repositories to users as a single repository group
  • format-specific search criteria and the related search functionality

Depending on the specific of the repository format being implemented a number of other features have to be provided or can optionally provide additional value to the user:

  • any required tasks for maintenance of the repositories and their content
  • client side tools to allow the standard tools to interact with the repositories on the repository manager
  • custom features to display information about the repositories or their content in the user interface

The implementation of all these features for the raw -format can be found in the module plugins/nexus-repository-raw. The raw format is a good example code-base to expose as it presents the most simplistic repository format.

The Maven repository format as used by Apache Maven and many other tools is implemented in the plugins/nexus-repository-maven module. It can serve as another, slightly more complex, example. Examining the code base can be especially useful, if you know the Maven repository format.

Format, Recipe, and Facet

Extending Format allows you define support for your new repository format. Proxy, hosted and group functionality are implemented in a corresponding Recipe implementation each. The recipe enables the system to configures the view of a repository. It configures the facets that decorate the implementation, and matches up routes with appropriate handlers. Some handlers like the SecurityHandler are required for all repositories, while others are used to implement format specific functionality like managing the content (i.e. RawContentHandler).

Facets are used to decorate the format and provide additional functionality like proxy support (e.g. RawProxyFacet).

Each format plugin is required to extend RepositoryFormatSecurityConfigurationResource to provide security configuration. This simple implementation can be used to enhance the security rules as necessary.

Storage

An addressable component in a repository is described as a Component. Typically it defines common metadata like name and version and acts as the parent for one or multiple assets. An Asset represents binary content of any type - usually a JAR file, ZIP archive or some other binary format and additional files associated with the package (i.e. pom.xml for maven). Some metadata is automatically collected for Assets, like check-sums, while each format can also contribute its own specific metadata. An asset should always have a sha1 check-sum, but certain formats may require other types of check-sum and should extend the Asset.attributes.checksum map as required to store these.

User Interface

The user interface for supporting a new repository format is following a standard-pattern and is implemented as a recipe in the nexus-coreui-plugin bundle in src/main/resources/static/rapture/NX/coreui/view/repository/recipe/. These merely compose configuration for specific facets which should be implemented in .../repository/facet.

If a given format requires any additional specific configuration you have to add a new facet configuration screen with the required fields. They have to be mapped to the key/value map called attributes of the repository. E.g. a repository format foo has to be mapped to attributes.foo.someConfigProperty. New format configurations need to be registered in the views configuration of the controller in .../coreui/controller/Repositories.js.

Tasks

Tasks are be implemented for scheduled maintenance and similar tasks that operate on a repository as a whole. The Maven repository bundle includes a number of tasks that can serve as an example in the org.sonatype.nexus.repository.maven.tasks package.