| Gerrit Code Review - Plugin Development |
| ======================================= |
| |
| The Gerrit server functionality can be extended by installing plugins. |
| This page describes how plugins for Gerrit can be developed. |
| |
| Depending on how tightly the extension code is coupled with the Gerrit |
| server code, there is a distinction between `plugins` and `extensions`. |
| |
| [[plugin]] |
| A `plugin` in Gerrit is tightly coupled code that runs in the same |
| JVM as Gerrit. It has full access to all server internals. Plugins |
| are tightly coupled to a specific major.minor server version and |
| may require source code changes to compile against a different |
| server version. |
| |
| [[extension]] |
| An `extension` in Gerrit runs inside of the same JVM as Gerrit |
| in the same way as a plugin, but has limited visibility to the |
| server's internals. The limited visibility reduces the extension's |
| dependencies, enabling it to be compatible across a wider range |
| of server versions. |
| |
| Most of this documentation refers to either type as a plugin. |
| |
| [[getting-started]] |
| Getting started |
| --------------- |
| |
| To get started with the development of a plugin there are two |
| recommended ways: |
| |
| . use the Gerrit Plugin Maven archetype to create a new plugin project: |
| + |
| With the Gerrit Plugin Maven archetype you can create a skeleton for a |
| plugin project. |
| + |
| ---- |
| mvn archetype:generate -DarchetypeGroupId=com.google.gerrit \ |
| -DarchetypeArtifactId=gerrit-plugin-archetype \ |
| -DarchetypeVersion=2.8-SNAPSHOT \ |
| -DgroupId=com.google.gerrit \ |
| -DartifactId=testPlugin |
| ---- |
| + |
| Maven will ask for additional properties and then create the plugin in |
| the current directory. To change the default property values answer 'n' |
| when Maven asks to confirm the properties configuration. It will then |
| ask again for all properties including those with predefined default |
| values. |
| |
| . clone the sample plugin: |
| + |
| This is a project that demonstrates the various features of the |
| plugin API. It can be taken as an example to develop an own plugin. |
| + |
| ---- |
| $ git clone https://gerrit.googlesource.com/plugins/cookbook-plugin |
| ---- |
| + |
| When starting from this example one should take care to adapt the |
| `Gerrit-ApiVersion` in the `pom.xml` to the version of Gerrit for which |
| the plugin is developed. If the plugin is developed for a released |
| Gerrit version (no `SNAPSHOT` version) then the URL for the |
| `gerrit-api-repository` in the `pom.xml` needs to be changed to |
| `https://gerrit-api.storage.googleapis.com/release/`. |
| |
| [[API]] |
| API |
| --- |
| |
| There are two different API formats offered against which plugins can |
| be developed: |
| |
| gerrit-extension-api.jar:: |
| A stable but thin interface. Suitable for extensions that need |
| to be notified of events, but do not require tight coupling to |
| the internals of Gerrit. Extensions built against this API can |
| expect to be binary compatible across a wide range of server |
| versions. |
| |
| gerrit-plugin-api.jar:: |
| The complete internals of the Gerrit server, permitting a |
| plugin to tightly couple itself and provide additional |
| functionality that is not possible as an extension. Plugins |
| built against this API are expected to break at the source |
| code level between every major.minor Gerrit release. A plugin |
| that compiles against 2.5 will probably need source code level |
| changes to work with 2.6, 2.7, and so on. |
| |
| Manifest |
| -------- |
| |
| Plugins may provide optional description information with standard |
| manifest fields: |
| |
| ==== |
| Implementation-Title: Example plugin showing examples |
| Implementation-Version: 1.0 |
| Implementation-Vendor: Example, Inc. |
| Implementation-URL: http://example.com/opensource/plugin-foo/ |
| ==== |
| |
| ApiType |
| ~~~~~~~ |
| |
| Plugins using the tightly coupled `gerrit-plugin-api.jar` must |
| declare this API dependency in the manifest to gain access to server |
| internals. If no `Gerrit-ApiType` is specified the stable `extension` |
| API will be assumed. This may cause ClassNotFoundExceptions when |
| loading a plugin that needs the plugin API. |
| |
| ==== |
| Gerrit-ApiType: plugin |
| ==== |
| |
| Explicit Registration |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| Plugins that use explicit Guice registration must name the Guice |
| modules in the manifest. Up to three modules can be named in the |
| manifest. `Gerrit-Module` supplies bindings to the core server; |
| `Gerrit-SshModule` supplies SSH commands to the SSH server (if |
| enabled); `Gerrit-HttpModule` supplies servlets and filters to the HTTP |
| server (if enabled). If no modules are named automatic registration |
| will be performed by scanning all classes in the plugin JAR for |
| `@Listen` and `@Export("")` annotations. |
| |
| ==== |
| Gerrit-Module: tld.example.project.CoreModuleClassName |
| Gerrit-SshModule: tld.example.project.SshModuleClassName |
| Gerrit-HttpModule: tld.example.project.HttpModuleClassName |
| ==== |
| |
| [[plugin_name]] |
| Plugin Name |
| ~~~~~~~~~~~ |
| |
| A plugin can optionally provide its own plugin name. |
| |
| ==== |
| Gerrit-PluginName: replication |
| ==== |
| |
| This is useful for plugins that contribute plugin-owned capabilities that |
| are stored in the `project.config` file. Another use case is to be able to put |
| project specific plugin configuration section in `project.config`. In this |
| case it is advantageous to reserve the plugin name to access the configuration |
| section in the `project.config` file. |
| |
| If `Gerrit-PluginName` is omitted, then the plugin's name is determined from |
| the plugin file name. |
| |
| If a plugin provides its own name, then that plugin cannot be deployed |
| multiple times under different file names on one Gerrit site. |
| |
| For Maven driven plugins, the following line must be included in the pom.xml |
| file: |
| |
| [source,xml] |
| ---- |
| <manifestEntries> |
| <Gerrit-PluginName>name</Gerrit-PluginName> |
| </manifestEntries> |
| ---- |
| |
| For Buck driven plugins, the following line must be included in the BUCK |
| configuration file: |
| |
| [source,python] |
| ---- |
| manifest_entries = [ |
| 'Gerrit-PluginName: name', |
| ] |
| ---- |
| |
| A plugin can get its own name injected at runtime: |
| |
| [source,java] |
| ---- |
| public class MyClass { |
| |
| private final String pluginName; |
| |
| @Inject |
| public MyClass(@PluginName String pluginName) { |
| this.pluginName = pluginName; |
| } |
| |
| [...] |
| } |
| ---- |
| |
| [[reload_method]] |
| Reload Method |
| ~~~~~~~~~~~~~ |
| |
| If a plugin holds an exclusive resource that must be released before |
| loading the plugin again (for example listening on a network port or |
| acquiring a file lock) the manifest must declare `Gerrit-ReloadMode` |
| to be `restart`. Otherwise the preferred method of `reload` will |
| be used, as it enables the server to hot-patch an updated plugin |
| with no down time. |
| |
| ==== |
| Gerrit-ReloadMode: restart |
| ==== |
| |
| In either mode ('restart' or 'reload') any plugin or extension can |
| be updated without restarting the Gerrit server. The difference is |
| how Gerrit handles the upgrade: |
| |
| restart:: |
| The old plugin is completely stopped. All registrations of SSH |
| commands and HTTP servlets are removed. All registrations of any |
| extension points are removed. All registered LifecycleListeners |
| have their `stop()` method invoked in reverse order. The new |
| plugin is started, and registrations are made from the new |
| plugin. There is a brief window where neither the old nor the |
| new plugin is connected to the server. This means SSH commands |
| and HTTP servlets will return not found errors, and the plugin |
| will not be notified of events that occurred during the restart. |
| |
| reload:: |
| The new plugin is started. Its LifecycleListeners are permitted |
| to perform their `start()` methods. All SSH and HTTP registrations |
| are atomically swapped out from the old plugin to the new plugin, |
| ensuring the server never returns a not found error. All extension |
| point listeners are atomically swapped out from the old plugin to |
| the new plugin, ensuring no events are missed (however some events |
| may still route to the old plugin if the swap wasn't complete yet). |
| The old plugin is stopped. |
| |
| To reload/restart a plugin the link:cmd-plugin-reload.html[plugin reload] |
| command can be used. |
| |
| [[init_step]] |
| Init step |
| ~~~~~~~~~ |
| |
| Plugins can contribute their own "init step" during the Gerrit init |
| wizard. This is useful for guiding the Gerrit administrator through |
| the settings needed by the plugin to work propertly. |
| |
| For instance plugins to integrate Jira issues to Gerrit changes may |
| contribute their own "init step" to allow configuring the Jira URL, |
| credentials and possibly verify connectivity to validate them. |
| |
| ==== |
| Gerrit-InitStep: tld.example.project.MyInitStep |
| ==== |
| |
| MyInitStep needs to follow the standard Gerrit InitStep syntax |
| and behavior: writing to the console using the injected ConsoleUI |
| and accessing / changing configuration settings using Section.Factory. |
| |
| In addition to the standard Gerrit init injections, plugins receive |
| the @PluginName String injection containing their own plugin name. |
| |
| Bear in mind that the Plugin's InitStep class will be loaded but |
| the standard Gerrit runtime environment is not available and the plugin's |
| own Guice modules were not initialized. |
| This means the InitStep for a plugin is not executed in the same way that |
| the plugin executes within the server, and may mean a plugin author cannot |
| trivially reuse runtime code during init. |
| |
| For instance a plugin that wants to verify connectivity may need to statically |
| call the constructor of their connection class, passing in values obtained |
| from the Section.Factory rather than from an injected Config object. |
| |
| Plugins' InitSteps are executed during the "Gerrit Plugin init" phase, after |
| the extraction of the plugins embedded in the distribution .war file into |
| `$GERRIT_SITE/plugins` and before the DB Schema initialization or upgrade. |
| |
| A plugin's InitStep cannot refer to Gerrit's DB Schema or any other Gerrit |
| runtime objects injected at startup. |
| |
| [source,java] |
| ---- |
| public class MyInitStep implements InitStep { |
| private final ConsoleUI ui; |
| private final Section.Factory sections; |
| private final String pluginName; |
| |
| @Inject |
| public GitBlitInitStep(final ConsoleUI ui, Section.Factory sections, @PluginName String pluginName) { |
| this.ui = ui; |
| this.sections = sections; |
| this.pluginName = pluginName; |
| } |
| |
| @Override |
| public void run() throws Exception { |
| ui.header("\nMy plugin"); |
| |
| Section mySection = getSection("myplugin", null); |
| mySection.string("Link name", "linkname", "MyLink"); |
| } |
| } |
| ---- |
| |
| [[classpath]] |
| Classpath |
| --------- |
| |
| Each plugin is loaded into its own ClassLoader, isolating plugins |
| from each other. A plugin or extension inherits the Java runtime |
| and the Gerrit API chosen by `Gerrit-ApiType` (extension or plugin) |
| from the hosting server. |
| |
| Plugins are loaded from a single JAR file. If a plugin needs |
| additional libraries, it must include those dependencies within |
| its own JAR. Plugins built using Maven may be able to use the |
| link:http://maven.apache.org/plugins/maven-shade-plugin/[shade plugin] |
| to package additional dependencies. Relocating (or renaming) classes |
| should not be necessary due to the ClassLoader isolation. |
| |
| [[events]] |
| Listening to Events |
| ------------------- |
| |
| Certain operations in Gerrit trigger events. Plugins may receive |
| notifications of these events by implementing the corresponding |
| listeners. |
| |
| * `com.google.gerrit.common.ChangeListener`: |
| + |
| Allows to listen to change events. These are the same |
| link:cmd-stream-events.html#events[events] that are also streamed by |
| the link:cmd-stream-events.html[gerrit stream-events] command. |
| |
| * `com.google.gerrit.extensions.events.LifecycleListener`: |
| + |
| Gerrit server startup and shutdown |
| |
| * `com.google.gerrit.extensions.events.NewProjectCreatedListener`: |
| + |
| Project creation |
| |
| * `com.google.gerrit.extensions.events.ProjectDeletedListener`: |
| + |
| Project deletion |
| |
| [[stream-events]] |
| Sending Events to the Events Stream |
| ----------------------------------- |
| |
| Plugins may send events to the events stream where consumers of |
| Gerrit's `stream-events` ssh command will receive them. |
| |
| To send an event, the plugin must invoke one of the `postEvent` |
| methods in the `ChangeHookRunner` class, passing an instance of |
| its own custom event class derived from `ChangeEvent`. |
| |
| [[ssh]] |
| SSH Commands |
| ------------ |
| |
| Plugins may provide commands that can be accessed through the SSH |
| interface (extensions do not have this option). |
| |
| Command implementations must extend the base class SshCommand: |
| |
| [source,java] |
| ---- |
| import com.google.gerrit.sshd.SshCommand; |
| |
| class PrintHello extends SshCommand { |
| protected abstract void run() { |
| stdout.print("Hello\n"); |
| } |
| } |
| ---- |
| |
| If no Guice modules are declared in the manifest, SSH commands may |
| use auto-registration by providing an `@Export` annotation: |
| |
| [source,java] |
| ---- |
| import com.google.gerrit.extensions.annotations.Export; |
| import com.google.gerrit.sshd.SshCommand; |
| |
| @Export("print") |
| class PrintHello extends SshCommand { |
| protected abstract void run() { |
| stdout.print("Hello\n"); |
| } |
| } |
| ---- |
| |
| If explicit registration is being used, a Guice module must be |
| supplied to register the SSH command and declared in the manifest |
| with the `Gerrit-SshModule` attribute: |
| |
| [source,java] |
| ---- |
| import com.google.gerrit.sshd.PluginCommandModule; |
| |
| class MyCommands extends PluginCommandModule { |
| protected void configureCommands() { |
| command("print").to(PrintHello.class); |
| } |
| } |
| ---- |
| |
| For a plugin installed as name `helloworld`, the command implemented |
| by PrintHello class will be available to users as: |
| |
| ---- |
| $ ssh -p 29418 review.example.com helloworld print |
| ---- |
| |
| Multiple SSH commands can be bound to the same implementation class. For |
| example a Gerrit Shell plugin can bind different shell commands to the same |
| implementation class: |
| |
| [source,java] |
| ---- |
| public class SshShellModule extends PluginCommandModule { |
| @Override |
| protected void configureCommands() { |
| command("ls").to(ShellCommand.class); |
| command("ps").to(ShellCommand.class); |
| [...] |
| } |
| } |
| ---- |
| |
| With the possible implementation: |
| |
| [source,java] |
| ---- |
| public class ShellCommand extends SshCommand { |
| @Override |
| protected void run() throws UnloggedFailure { |
| String cmd = getName().substring(getPluginName().length() + 1); |
| ProcessBuilder proc = new ProcessBuilder(cmd); |
| Process cmd = proc.start(); |
| [...] |
| } |
| } |
| ---- |
| |
| And the call: |
| |
| ---- |
| $ ssh -p 29418 review.example.com shell ls |
| $ ssh -p 29418 review.example.com shell ps |
| ---- |
| |
| [[configuration]] |
| Configuration |
| ------------- |
| |
| In Gerrit, global configuration is stored in the `gerrit.config` file. |
| If a plugin needs global configuration, this configuration should be |
| stored in a `plugin` subsection in the `gerrit.config` file. |
| |
| This approach of storing the plugin configuration is only suitable for |
| plugins that have a simple configuration that only consists of |
| key-value pairs. With this approach it is not possible to have |
| subsections in the plugin configuration. Plugins that require a complex |
| configuration need to store their configuration in their own |
| configuration file where they can make use of subsections. On the other |
| hand storing the plugin configuration in a 'plugin' subsection in the |
| `gerrit.config` file has the advantage that administrators have all |
| configuration parameters in one file, instead of having one |
| configuration file per plugin. |
| |
| To avoid conflicts with other plugins, it is recommended that plugins |
| only use the `plugin` subsection with their own name. For example the |
| `helloworld` plugin should store its configuration in the |
| `plugin.helloworld` subsection: |
| |
| ---- |
| [plugin "helloworld"] |
| language = Latin |
| ---- |
| |
| Via the `com.google.gerrit.server.config.PluginConfigFactory` class a |
| plugin can easily access its configuration and there is no need for a |
| plugin to parse the `gerrit.config` file on its own: |
| |
| [source,java] |
| ---- |
| @Inject |
| private com.google.gerrit.server.config.PluginConfigFactory cfg; |
| |
| [...] |
| |
| String language = cfg.getFromGerritConfig("helloworld") |
| .getString("language", "English"); |
| ---- |
| |
| [[project-specific-configuration]] |
| Project Specific Configuration |
| ------------------------------ |
| |
| In Gerrit, project specific configuration is stored in the project's |
| `project.config` file on the `refs/meta/config` branch. If a plugin |
| needs configuration on project level (e.g. to enable its functionality |
| only for certain projects), this configuration should be stored in a |
| `plugin` subsection in the project's `project.config` file. |
| |
| This approach of storing the plugin configuration is only suitable for |
| plugins that have a simple configuration that only consists of |
| key-value pairs. With this approach it is not possible to have |
| subsections in the plugin configuration. Plugins that require a complex |
| configuration need to store their configuration in their own |
| configuration file where they can make use of subsections. On the other |
| hand storing the plugin configuration in a 'plugin' subsection in the |
| `project.config` file has the advantage that project owners have all |
| configuration parameters in one file, instead of having one |
| configuration file per plugin. |
| |
| To avoid conflicts with other plugins, it is recommended that plugins |
| only use the `plugin` subsection with their own name. For example the |
| `helloworld` plugin should store its configuration in the |
| `plugin.helloworld` subsection: |
| |
| ---- |
| [plugin "helloworld"] |
| enabled = true |
| ---- |
| |
| Via the `com.google.gerrit.server.config.PluginConfigFactory` class a |
| plugin can easily access its project specific configuration and there |
| is no need for a plugin to parse the `project.config` file on its own: |
| |
| [source,java] |
| ---- |
| @Inject |
| private com.google.gerrit.server.config.PluginConfigFactory cfg; |
| |
| [...] |
| |
| boolean enabled = cfg.getFromProjectConfig(project, "helloworld") |
| .getBoolean("enabled", false); |
| ---- |
| |
| It is also possible to get missing configuration parameters inherited |
| from the parent projects: |
| |
| [source,java] |
| ---- |
| @Inject |
| private com.google.gerrit.server.config.PluginConfigFactory cfg; |
| |
| [...] |
| |
| boolean enabled = cfg.getFromProjectConfigWithInheritance(project, "helloworld") |
| .getBoolean("enabled", false); |
| ---- |
| |
| Project owners can edit the project configuration by fetching the |
| `refs/meta/config` branch, editing the `project.config` file and |
| pushing the commit back. |
| |
| [[capabilities]] |
| Plugin Owned Capabilities |
| ------------------------- |
| |
| Plugins may provide their own capabilities and restrict usage of SSH |
| commands to the users who are granted those capabilities. |
| |
| Plugins define the capabilities by overriding the `CapabilityDefinition` |
| abstract class: |
| |
| [source,java] |
| ---- |
| public class PrintHelloCapability extends CapabilityDefinition { |
| @Override |
| public String getDescription() { |
| return "Print Hello"; |
| } |
| } |
| ---- |
| |
| If no Guice modules are declared in the manifest, UI actions may |
| use auto-registration by providing an `@Export` annotation: |
| |
| [source,java] |
| ---- |
| @Export("printHello") |
| public class PrintHelloCapability extends CapabilityDefinition { |
| [...] |
| } |
| ---- |
| |
| Otherwise the capability must be bound in a plugin module: |
| |
| [source,java] |
| ---- |
| public class HelloWorldModule extends AbstractModule { |
| @Override |
| protected void configure() { |
| bind(CapabilityDefinition.class) |
| .annotatedWith(Exports.named("printHello")) |
| .to(PrintHelloCapability.class); |
| } |
| } |
| ---- |
| |
| With a plugin-owned capability defined in this way, it is possible to restrict |
| usage of an SSH command or `UiAction` to members of the group that were granted |
| this capability in the usual way, using the `RequiresCapability` annotation: |
| |
| [source,java] |
| ---- |
| @RequiresCapability("printHello") |
| @CommandMetaData(name="print", description="Print greeting in different languages") |
| public final class PrintHelloWorldCommand extends SshCommand { |
| [...] |
| } |
| ---- |
| |
| Or with `UiAction`: |
| |
| [source,java] |
| ---- |
| @RequiresCapability("printHello") |
| public class SayHelloAction extends UiAction<RevisionResource> |
| implements RestModifyView<RevisionResource, SayHelloAction.Input> { |
| [...] |
| } |
| ---- |
| |
| Capability scope was introduced to differentiate between plugin-owned |
| capabilities and core capabilities. Per default the scope of the |
| `@RequiresCapability` annotation is `CapabilityScope.CONTEXT`, that means: |
| |
| * when `@RequiresCapability` is used within a plugin the scope of the |
| capability is assumed to be that plugin. |
| |
| * If `@RequiresCapability` is used within the core Gerrit Code Review server |
| (and thus is outside of a plugin) the scope is the core server and will use |
| the `GlobalCapability` known to Gerrit Code Review server. |
| |
| If a plugin needs to use a core capability name (e.g. "administrateServer") |
| this can be specified by setting `scope = CapabilityScope.CORE`: |
| |
| [source,java] |
| ---- |
| @RequiresCapability(value = "administrateServer", scope = |
| CapabilityScope.CORE) |
| [...] |
| ---- |
| |
| [[ui_extension]] |
| UI Extension |
| ------------ |
| |
| Plugins can contribute UI actions on core Gerrit pages. This is useful |
| for workflow customization or exposing plugin functionality through the |
| UI in addition to SSH commands and the REST API. |
| |
| For instance a plugin to integrate Jira with Gerrit changes may |
| contribute a "File bug" button to allow filing a bug from the change |
| page or plugins to integrate continuous integration systems may |
| contribute a "Schedule" button to allow a CI build to be scheduled |
| manually from the patch set panel. |
| |
| Two different places on core Gerrit pages are supported: |
| |
| * Change screen |
| * Project info screen |
| |
| Plugins contribute UI actions by implementing the `UiAction` interface: |
| |
| [source,java] |
| ---- |
| @RequiresCapability("printHello") |
| class HelloWorldAction implements UiAction<RevisionResource>, |
| RestModifyView<RevisionResource, HelloWorldAction.Input> { |
| static class Input { |
| boolean french; |
| String message; |
| } |
| |
| private Provider<CurrentUser> user; |
| |
| @Inject |
| HelloWorldAction(Provider<CurrentUser> user) { |
| this.user = user; |
| } |
| |
| @Override |
| public String apply(RevisionResource rev, Input input) { |
| final String greeting = input.french |
| ? "Bonjour" |
| : "Hello"; |
| return String.format("%s %s from change %s, patch set %d!", |
| greeting, |
| Strings.isNullOrEmpty(input.message) |
| ? Objects.firstNonNull(user.get().getUserName(), "world") |
| : input.message, |
| rev.getChange().getId().toString(), |
| rev.getPatchSet().getPatchSetId()); |
| } |
| |
| @Override |
| public Description getDescription( |
| RevisionResource resource) { |
| return new Description() |
| .setLabel("Say hello") |
| .setTitle("Say hello in different languages"); |
| } |
| } |
| ---- |
| |
| Sometimes plugins may want to be able to change the state of a patch set or |
| change in the `UiAction.apply()` method and reflect these changes on the core |
| UI. For example a buildbot plugin which exposes a 'Schedule' button on the |
| patch set panel may want to disable that button after the build was scheduled |
| and update the tooltip of that button. But because of Gerrit's caching |
| strategy the following must be taken into consideration. |
| |
| The browser is allowed to cache the `UiAction` information until something on |
| the change is modified. More accurately the change row needs to be modified in |
| the database to have a more recent `lastUpdatedOn` or a new `rowVersion`, or |
| the +refs/meta/config+ of the project or any parents needs to change to a new |
| SHA-1. The ETag SHA-1 computation code can be found in the |
| `ChangeResource.getETag()` method. |
| |
| The easiest way to accomplish this is to update `lastUpdatedOn` of the change: |
| |
| [source,java] |
| ---- |
| @Override |
| public Object apply(RevisionResource rcrs, Input in) { |
| // schedule a build |
| [...] |
| // update change |
| ReviewDb db = dbProvider.get(); |
| db.changes().beginTransaction(change.getId()); |
| try { |
| change = db.changes().atomicUpdate( |
| change.getId(), |
| new AtomicUpdate<Change>() { |
| @Override |
| public Change update(Change change) { |
| ChangeUtil.updated(change); |
| return change; |
| } |
| }); |
| db.commit(); |
| } finally { |
| db.rollback(); |
| } |
| [...] |
| } |
| ---- |
| |
| `UiAction` must be bound in a plugin module: |
| |
| [source,java] |
| ---- |
| public class Module extends AbstractModule { |
| @Override |
| protected void configure() { |
| install(new RestApiModule() { |
| @Override |
| protected void configure() { |
| post(REVISION_KIND, "say-hello") |
| .to(HelloWorldAction.class); |
| } |
| }); |
| } |
| } |
| ---- |
| |
| The module above must be declared in the `pom.xml` for Maven driven |
| plugins: |
| |
| [source,xml] |
| ---- |
| <manifestEntries> |
| <Gerrit-Module>com.googlesource.gerrit.plugins.cookbook.Module</Gerrit-Module> |
| </manifestEntries> |
| ---- |
| |
| or in the `BUCK` configuration file for Buck driven plugins: |
| |
| [source,python] |
| ---- |
| manifest_entries = [ |
| 'Gerrit-Module: com.googlesource.gerrit.plugins.cookbook.Module', |
| ] |
| ---- |
| |
| In some use cases more user input must be gathered, for that `UiAction` can be |
| combined with the JavaScript API. This would display a small popup near the |
| activation button to gather additional input from the user. The JS file is |
| typically put in the `static` folder within the plugin's directory: |
| |
| [source,javascript] |
| ---- |
| Gerrit.install(function(self) { |
| function onSayHello(c) { |
| var f = c.textfield(); |
| var t = c.checkbox(); |
| var b = c.button('Say hello', {onclick: function(){ |
| c.call( |
| {message: f.value, french: t.checked}, |
| function(r) { |
| c.hide(); |
| window.alert(r); |
| c.refresh(); |
| }); |
| }}); |
| c.popup(c.div( |
| c.prependLabel('Greeting message', f), |
| c.br(), |
| c.label(t, 'french'), |
| c.br(), |
| b)); |
| f.focus(); |
| } |
| self.onAction('revision', 'say-hello', onSayHello); |
| }); |
| ---- |
| |
| The JS module must be exposed as a `WebUiPlugin` and bound as |
| an HTTP Module: |
| |
| [source,java] |
| ---- |
| public class HttpModule extends HttpPluginModule { |
| @Override |
| protected void configureServlets() { |
| DynamicSet.bind(binder(), WebUiPlugin.class) |
| .toInstance(new JavaScriptPlugin("hello.js")); |
| } |
| } |
| ---- |
| |
| The HTTP module above must be declared in the `pom.xml` for Maven |
| driven plugins: |
| |
| [source,xml] |
| ---- |
| <manifestEntries> |
| <Gerrit-HttpModule>com.googlesource.gerrit.plugins.cookbook.HttpModule</Gerrit-HttpModule> |
| </manifestEntries> |
| ---- |
| |
| or in the `BUCK` configuration file for Buck driven plugins |
| |
| [source,python] |
| ---- |
| manifest_entries = [ |
| 'Gerrit-HttpModule: com.googlesource.gerrit.plugins.cookbook.HttpModule', |
| ] |
| ---- |
| |
| If `UiAction` is annotated with the `@RequiresCapability` annotation, then the |
| capability check is done during the `UiAction` gathering, so the plugin author |
| doesn't have to set `UiAction.Description.setVisible()` explicitly in this |
| case. |
| |
| The following prerequisities must be met, to satisfy the capability check: |
| |
| * user is authenticated |
| * user is a member of a group which has the `Administrate Server` capability, or |
| * user is a member of a group which has the required capability |
| |
| The `apply` method is called when the button is clicked. If `UiAction` is |
| combined with JavaScript API (its own JavaScript function is provided), |
| then a popup dialog is normally opened to gather additional user input. |
| A new button is placed on the popup dialog to actually send the request. |
| |
| Every `UiAction` exposes a REST API endpoint. The endpoint from the example above |
| can be accessed from any REST client, i. e.: |
| |
| ==== |
| curl -X POST -H "Content-Type: application/json" \ |
| -d '{message: "François", french: true}' \ |
| --digest --user joe:secret \ |
| http://host:port/a/changes/1/revisions/1/cookbook~say-hello |
| "Bonjour François from change 1, patch set 1!" |
| ==== |
| |
| A special case is to bind an endpoint without a view name. This is |
| particularly useful for `DELETE` requests: |
| |
| [source,java] |
| ---- |
| public class Module extends AbstractModule { |
| @Override |
| protected void configure() { |
| install(new RestApiModule() { |
| @Override |
| protected void configure() { |
| delete(PROJECT_KIND) |
| .to(DeleteProject.class); |
| } |
| }); |
| } |
| } |
| ---- |
| |
| For a `UiAction` bound this way, a JS API function can be provided. |
| |
| Currently only one restriction exists: per plugin only one `UiAction` |
| can be bound per resource without view name. To define a JS function |
| for the `UiAction`, "/" must be used as the name: |
| |
| [source,javascript] |
| ---- |
| Gerrit.install(function(self) { |
| function onDeleteProject(c) { |
| [...] |
| } |
| self.onAction('project', '/', onDeleteProject); |
| }); |
| ---- |
| |
| [[top-menu-extensions]] |
| Top Menu Extensions |
| ------------------- |
| |
| Plugins can contribute items to Gerrit's top menu. |
| |
| A single top menu extension can have multiple elements and will be put as |
| the last element in Gerrit's top menu. |
| |
| Plugins define the top menu entries by implementing `TopMenu` interface: |
| |
| [source,java] |
| ---- |
| public class MyTopMenuExtension implements TopMenu { |
| |
| @Override |
| public List<MenuEntry> getEntries() { |
| return Lists.newArrayList( |
| new MenuEntry("Top Menu Entry", Lists.newArrayList( |
| new MenuItem("Gerrit", "http://gerrit.googlecode.com/")))); |
| } |
| } |
| ---- |
| |
| Plugins can also add additional menu items to Gerrit's top menu entries |
| by defining a `MenuEntry` that has the same name as a Gerrit top menu |
| entry: |
| |
| [source,java] |
| ---- |
| public class MyTopMenuExtension implements TopMenu { |
| |
| @Override |
| public List<MenuEntry> getEntries() { |
| return Lists.newArrayList( |
| new MenuEntry(GerritTopMenu.PROJECTS, Lists.newArrayList( |
| new MenuItem("Browse Repositories", "https://gerrit.googlesource.com/")))); |
| } |
| } |
| ---- |
| |
| If no Guice modules are declared in the manifest, the top menu extension may use |
| auto-registration by providing an `@Listen` annotation: |
| |
| [source,java] |
| ---- |
| @Listen |
| public class MyTopMenuExtension implements TopMenu { |
| [...] |
| } |
| ---- |
| |
| Otherwise the top menu extension must be bound in the plugin module used |
| for the Gerrit system injector (Gerrit-Module entry in MANIFEST.MF): |
| |
| [source,java] |
| ---- |
| package com.googlesource.gerrit.plugins.helloworld; |
| |
| public class HelloWorldModule extends AbstractModule { |
| @Override |
| protected void configure() { |
| DynamicSet.bind(binder(), TopMenu.class).to(MyTopMenuExtension.class); |
| } |
| } |
| ---- |
| |
| [source,manifest] |
| ---- |
| Gerrit-ApiType: plugin |
| Gerrit-Module: com.googlesource.gerrit.plugins.helloworld.HelloWorldModule |
| ---- |
| |
| [[http]] |
| HTTP Servlets |
| ------------- |
| |
| Plugins or extensions may register additional HTTP servlets, and |
| wrap them with HTTP filters. |
| |
| Servlets may use auto-registration to declare the URL they handle: |
| |
| [source,java] |
| ---- |
| import com.google.gerrit.extensions.annotations.Export; |
| import com.google.inject.Singleton; |
| import javax.servlet.http.HttpServlet; |
| import javax.servlet.http.HttpServletRequest; |
| import javax.servlet.http.HttpServletResponse; |
| |
| @Export("/print") |
| @Singleton |
| class HelloServlet extends HttpServlet { |
| protected void doGet(HttpServletRequest req, HttpServletResponse res) throws IOException { |
| res.setContentType("text/plain"); |
| res.setCharacterEncoding("UTF-8"); |
| res.getWriter().write("Hello"); |
| } |
| } |
| ---- |
| |
| The auto registration only works for standard servlet mappings like |
| `/foo` or `/foo/*`. Regex style bindings must use a Guice ServletModule |
| to register the HTTP servlets and declare it explicitly in the manifest |
| with the `Gerrit-HttpModule` attribute: |
| |
| [source,java] |
| ---- |
| import com.google.inject.servlet.ServletModule; |
| |
| class MyWebUrls extends ServletModule { |
| protected void configureServlets() { |
| serve("/print").with(HelloServlet.class); |
| } |
| } |
| ---- |
| |
| For a plugin installed as name `helloworld`, the servlet implemented |
| by HelloServlet class will be available to users as: |
| |
| ---- |
| $ curl http://review.example.com/plugins/helloworld/print |
| ---- |
| |
| [[data-directory]] |
| Data Directory |
| -------------- |
| |
| Plugins can request a data directory with a `@PluginData` File |
| dependency. A data directory will be created automatically by the |
| server in `$site_path/data/$plugin_name` and passed to the plugin. |
| |
| Plugins can use this to store any data they want. |
| |
| [source,java] |
| ---- |
| @Inject |
| MyType(@PluginData java.io.File myDir) { |
| new FileInputStream(new File(myDir, "my.config")); |
| } |
| ---- |
| |
| [[download-commands]] |
| Download Commands |
| ----------------- |
| |
| Gerrit offers commands for downloading changes using different |
| download schemes (e.g. for downloading via different network |
| protocols). Plugins can contribute download schemes and download |
| commands by implementing |
| `com.google.gerrit.extensions.config.DownloadScheme` and |
| `com.google.gerrit.extensions.config.DownloadCommand`. |
| |
| The download schemes and download commands which are used most often |
| are provided by the Gerrit core plugin `download-commands`. |
| |
| [[documentation]] |
| Documentation |
| ------------- |
| |
| If a plugin does not register a filter or servlet to handle URLs |
| `/Documentation/*` or `/static/*`, the core Gerrit server will |
| automatically export these resources over HTTP from the plugin JAR. |
| |
| Static resources under the `static/` directory in the JAR will be |
| available as `/plugins/helloworld/static/resource`. This prefix is |
| configurable by setting the `Gerrit-HttpStaticPrefix` attribute. |
| |
| Documentation files under the `Documentation/` directory in the JAR |
| will be available as `/plugins/helloworld/Documentation/resource`. This |
| prefix is configurable by setting the `Gerrit-HttpDocumentationPrefix` |
| attribute. |
| |
| Documentation may be written in |
| link:http://daringfireball.net/projects/markdown/[Markdown] style |
| if the file name ends with `.md`. Gerrit will automatically convert |
| Markdown to HTML if accessed with extension `.html`. |
| |
| [[macros]] |
| Within the Markdown documentation files macros can be used that allow |
| to write documentation with reasonably accurate examples that adjust |
| automatically based on the installation. |
| |
| The following macros are supported: |
| |
| [width="40%",options="header"] |
| |=================================================== |
| |Macro | Replacement |
| |@PLUGIN@ | name of the plugin |
| |@URL@ | Gerrit Web URL |
| |@SSH_HOST@ | SSH Host |
| |@SSH_PORT@ | SSH Port |
| |=================================================== |
| |
| The macros will be replaced when the documentation files are rendered |
| from Markdown to HTML. |
| |
| Macros that start with `\` such as `\@KEEP@` will render as `@KEEP@` |
| even if there is an expansion for `KEEP` in the future. |
| |
| [[auto-index]] |
| Automatic Index |
| ~~~~~~~~~~~~~~~ |
| |
| If a plugin does not handle its `/` URL itself, Gerrit will |
| redirect clients to the plugin's `/Documentation/index.html`. |
| Requests for `/Documentation/` (bare directory) will also redirect |
| to `/Documentation/index.html`. |
| |
| If neither resource `Documentation/index.html` or |
| `Documentation/index.md` exists in the plugin JAR, Gerrit will |
| automatically generate an index page for the plugin's documentation |
| tree by scanning every `*.md` and `*.html` file in the Documentation/ |
| directory. |
| |
| For any discovered Markdown (`*.md`) file, Gerrit will parse the |
| header of the file and extract the first level one title. This |
| title text will be used as display text for a link to the HTML |
| version of the page. |
| |
| For any discovered HTML (`*.html`) file, Gerrit will use the name |
| of the file, minus the `*.html` extension, as the link text. Any |
| hyphens in the file name will be replaced with spaces. |
| |
| If a discovered file is named `about.md` or `about.html`, its |
| content will be inserted in an 'About' section at the top of the |
| auto-generated index page. If both `about.md` and `about.html` |
| exist, only the first discovered file will be used. |
| |
| If a discovered file name beings with `cmd-` it will be clustered |
| into a 'Commands' section of the generated index page. |
| |
| If a discovered file name beings with `servlet-` it will be clustered |
| into a 'Servlets' section of the generated index page. |
| |
| If a discovered file name beings with `rest-api-` it will be clustered |
| into a 'REST APIs' section of the generated index page. |
| |
| All other files are clustered under a 'Documentation' section. |
| |
| Some optional information from the manifest is extracted and |
| displayed as part of the index page, if present in the manifest: |
| |
| [width="40%",options="header"] |
| |=================================================== |
| |Field | Source Attribute |
| |Name | Implementation-Title |
| |Vendor | Implementation-Vendor |
| |Version | Implementation-Version |
| |URL | Implementation-URL |
| |API Version | Gerrit-ApiVersion |
| |=================================================== |
| |
| [[deployment]] |
| Deployment |
| ---------- |
| |
| Compiled plugins and extensions can be deployed to a running Gerrit |
| server using the link:cmd-plugin-install.html[plugin install] command. |
| |
| Plugins can also be copied directly into the server's |
| directory at `$site_path/plugins/$name.jar`. The name of |
| the JAR file, minus the `.jar` extension, will be used as the |
| plugin name. Unless disabled, servers periodically scan this |
| directory for updated plugins. The time can be adjusted by |
| link:config-gerrit.html#plugins.checkFrequency[plugins.checkFrequency]. |
| |
| For disabling plugins the link:cmd-plugin-remove.html[plugin remove] |
| command can be used. |
| |
| Disabled plugins can be re-enabled using the |
| link:cmd-plugin-enable.html[plugin enable] command. |
| |
| SEE ALSO |
| -------- |
| |
| * link:js-api.html[JavaScript API] |
| * link:dev-rest-api.html[REST API Developers' Notes] |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |