Skip to content

Latest commit

 

History

History
204 lines (164 loc) · 8.17 KB

chapter-using-plugins.asciidoc

File metadata and controls

204 lines (164 loc) · 8.17 KB

Plugins

{inall}

{oss} and {pro} are built using a plugin architecture, where each version includes a different set of plugins. You can install plugins available from the open source community, other vendors, or created by yourself in addition to the default plugins.

Plugins can provide further functionality for the backend such as support for new repository formats, specific behavior for components, new scheduled tasks, new staging rules, and any other additional functionality as well as new user interface components and modifications. They can also group a number of these features together in one plugin.

Managing Plugins

All plugins supplied by Sonatype are installed as part of the default configuration and can be found in $NEXUS_HOME/nexus/WEB-INF/plugin-repository. Most plugins are enabled by default.

Some plugins expose a capability as documented in [capabilities] and can be enabled, disabled, and otherwise configured in the capability administration. The branding plugin or the outreach plugin are examples of plugins exposing capabilities.

Note
Prior to version 2.7 optional plugins, supplied by Sonatype, can be found in the directory $NEXUS_HOME/nexus/WEB-INF/optional-plugins. To install any of these, simply copy the folder containing the desired plugin into $NEXUS_HOME/nexus/WEB-INF/plugin-repository. When updating the repository manager, redo the install of any optional plugins using the newest version shipping with the download of the new version. Any configuration of the plugin will be preserved from one version to the other.

Plugins supplied by third parties or ones that you authored are installed by copying the folder with the plugin code into sonatype-work/nexus/plugin-repository or extracting the plugin bundle zip file in that folder.

After a restart of the repository manager, the new plugins will be active and ready to use. Upgrades are done by shutting down the repository manager, copying the newer plugin into the folder, removing the older one, and restarting it.

Capability-based plugins can be disabled in the capability administration. Otherwise, plugins can be removed by deleting the respective folder in the plugin-repository and restarting.

Developing Plugins

Developing plugins allow you to customize and further enhance the repository manager beyond the features and capabilities offered. This section provides you with the information to begin developing your own plugins.

The preferred way to write plugins is to use Java as the implementation language and Apache Maven as the build system. The Nexus Example Plugins project demonstrates a number of plugin examples for {oss} and {pro}. Further examples are the plugins of {oss}.

The easiest way to create a new plugin project is to replicate a plugin with a similar functionality from these projects. The existing plugins and codebase should be used as examples for your own functionality. Inspect the source code of plugins with similar functionality, and read the JavaDoc documentation for the involved classes.

Note
The Maven archetype nexus-archetype-quickstart is deprecated.

To gain access to all the components needed for your plugin development, you have to proxy the Sonatype grid repository with the URL below:

https://repository.sonatype.org/content/groups/sonatype-public-grid/

For some {pro} specific plugins, you might need access to the private grid. We suggest that you work with the support team in this situation.

Set up your project to include inheriting from the parent of all the {oss} plugins with the version you are targeting as displayed in Inheriting from the nexus-plugins Parent.

Inheriting from the nexus-plugins Parent
 <parent>
    <groupId>org.sonatype.nexus.plugins</groupId>
    <artifactId>nexus-plugins</artifactId>
    <version>2.12.1-01</version>
 </parent>
Warning
It is best to use the identical version of the parent as the {nxrm} instance no which you want to run your plugin. When developing a plugin you are using large parts of internals, which are subject to change from one version to another. This same logic applies to any dependencies as well.

A plugin Maven project creates a custom build output file in the form of a zip file that contains all dependencies, in addition to your class files and resources from your plugin and some metadata. Enable this by changing the packaging and adding the bundle plugin listed in nexus-plugin Packaging.

nexus-plugin Packaging
<project>
...
  <groupId>com.myorganization.nexus.plugins</groupId>
  <artifactId>example-nexus-plugin</artifactId>
  <version>1.0-SNAPSHOT</
  <packaging>nexus-plugin</packaging>
...
  <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.nexus</groupId>
        <artifactId>nexus-plugin-bundle-maven-plugin</artifactId>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>

Add the dependencies in Adding the Nexus Plugin API and Testsupport to your Maven project pom.xml file, to access the Nexus Plugin API and test support.

Adding the Nexus Plugin API and Testsupport
  <dependencies>
    <dependency>
      <groupId>org.sonatype.nexus</groupId>
      <artifactId>nexus-plugin-api</artifactId>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.sonatype.nexus</groupId>
      <artifactId>nexus-plugin-testsupport</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

These dependencies pull in a large number of transitive dependencies that expose {nxrm} functionality and other libraries to your project. Depending on the type of plugin and functionality you aim to create, additional dependencies and other details can be added to this minimal project setup. A large number of further classes is available and can be used as part of your plugin development. Some of these classes are contained in other plugins. If you want to use these, you have to add a dependency to this plugin to your plugin’s pom.xml.

An example is a plugin you create that exposes a REST API for further integrations with tools outside of the repository manager similar to how all other plugins expose a REST API. The dependency to add is displayed in Adding a Dependency to the Nexus Siesta Plugin.

Adding a Dependency to the Nexus Siesta Plugin
<dependency>
  <groupId>com.sonatype.nexus.plugins</groupId>
  <artifactId>nexus-siesta-plugin</artifactId>
  <type>nexus-plugin</type>
  <scope>provided</scope>
</dependency>

{pro}, {oss} and plugins use JSR-330 annotations like @javax.inject.Inject and the Google Guice dependency injection framework. Typical classes are @Named and are often a @Singleton . Other components are typically injected via constructor injection as displayed in the example from the virusscan example plugin in Constructor Injection.

Constructor Injection
  @Inject
  public VirusScannerRequestProcessor(final EventBus eventBus,
                                      final List<VirusScanner> scanners)
  {
    this.eventBus = Preconditions.checkNotNull(eventBus);
    this.scanners = Preconditions.checkNotNull(scanners);
    ...

Your Maven project setup should follow the typical standard directory layout conventions. In addition, static resources such as JavaScript files, images, and CSS should be placed in src/main/resources/static.

Once you have created your Maven project as described above, you can build the plugin with

mvn clean install

A successful build includes the creation of a *-bundle.zip file in the target folder. To install your plugin into the repository manager you can extract it into the plugin-repository directory as described in Managing Plugins.

Summary

The {nxrm} architecture is largely based on plugins including the differentiation of {oss} and {pro}. By inspecting the example plugins and the {oss} project, you can create additional functionality for yourself as well as potentially share it with the user community.