| = 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.10 \ |
| -DgroupId=com.googlesource.gerrit.plugins.testplugin \ |
| -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; |
| } |
| |
| [...] |
| } |
| ---- |
| |
| A plugin can get its canonical web URL injected at runtime: |
| |
| [source,java] |
| ---- |
| public class MyClass { |
| |
| private final String url; |
| |
| @Inject |
| public MyClass(@PluginCanonicalWebUrl String url) { |
| this.url = url; |
| } |
| |
| [...] |
| } |
| ---- |
| |
| The URL is composed of the server's canonical web URL and the plugin's |
| name, i.e. `http://review.example.com:8080/plugin-name`. |
| |
| The canonical web URL may be injected into any .jar plugin regardless of |
| whether or not the plugin provides an HTTP servlet. |
| |
| [[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 properly. |
| |
| 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. |
| |
| During their initialization plugins may get access to the |
| `project.config` file of the `All-Projects` project and they are able |
| to store configuration parameters in it. For this a plugin `InitStep` |
| can get `com.google.gerrit.pgm.init.AllProjectsConfig` injected: |
| |
| [source,java] |
| ---- |
| public class MyInitStep implements InitStep { |
| private final String pluginName; |
| private final ConsoleUI ui; |
| private final AllProjectsConfig allProjectsConfig; |
| |
| public MyInitStep(@PluginName String pluginName, ConsoleUI ui, |
| AllProjectsConfig allProjectsConfig) { |
| this.pluginName = pluginName; |
| this.ui = ui; |
| this.allProjectsConfig = allProjectsConfig; |
| } |
| |
| @Override |
| public void run() throws Exception { |
| } |
| |
| @Override |
| public void postRun() throws Exception { |
| ui.message("\n"); |
| ui.header(pluginName + " Integration"); |
| boolean enabled = ui.yesno(true, "By default enabled for all projects"); |
| Config cfg = allProjectsConfig.load(); |
| if (enabled) { |
| cfg.setBoolean("plugin", pluginName, "enabled", enabled); |
| } else { |
| cfg.unset("plugin", pluginName, "enabled"); |
| } |
| allProjectsConfig.save(pluginName, "Initialize " + pluginName + " Integration"); |
| } |
| } |
| ---- |
| |
| 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"); |
| } |
| |
| @Override |
| public void postRun() throws Exception { |
| } |
| } |
| ---- |
| |
| [[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`: |
| + |
| Plugin start and stop |
| |
| * `com.google.gerrit.extensions.events.NewProjectCreatedListener`: |
| + |
| Project creation |
| |
| * `com.google.gerrit.extensions.events.ProjectDeletedListener`: |
| + |
| Project deletion |
| |
| * `com.google.gerrit.extensions.events.HeadUpdatedListener`: |
| + |
| Update of HEAD on a project |
| |
| * `com.google.gerrit.extensions.events.UsageDataPublishedListener`: |
| + |
| Publication of usage data |
| |
| [[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`. |
| |
| [[validation]] |
| == Validation Listeners |
| |
| Certain operations in Gerrit can be validated by plugins by |
| implementing the corresponding link:config-validation.html[listeners]. |
| |
| [[receive-pack]] |
| == Receive Pack Initializers |
| |
| Plugins may provide ReceivePack initializers which will be invoked |
| by Gerrit just before a ReceivePack instance will be used. Usually, |
| plugins will make use of the setXXX methods on the ReceivePack to |
| set additional properties on it. |
| |
| [[post-receive-hook]] |
| == Post Receive-Pack Hooks |
| |
| Plugins may register PostReceiveHook instances in order to get |
| notified when JGit successfully receives a pack. This may be useful |
| for those plugins which would like to monitor changes in Git |
| repositories. |
| |
| [[pre-upload-hook]] |
| == Pre Upload-Pack Hooks |
| |
| Plugins may register PreUploadHook instances in order to get |
| notified when JGit is about to upload a pack. This may be useful |
| for those plugins which would like to monitor usage in Git |
| repositories. |
| |
| [[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; |
| import com.google.gerrit.sshd.CommandMetaData; |
| |
| @CommandMetaData(name="print", description="Print hello command") |
| class PrintHello extends SshCommand { |
| @Override |
| protected 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 { |
| @Override |
| protected 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 { |
| @Override |
| protected void configureCommands() { |
| command(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-commands]] |
| === Multiple Commands bound to one implementation |
| |
| 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 |
| ---- |
| |
| [[root-level-commands]] |
| === Root Level Commands |
| |
| Single command plugins are also supported. In this scenario plugin binds |
| SSH command to its own name. `SshModule` must inherit from |
| `SingleCommandPluginModule` class: |
| |
| [source,java] |
| ---- |
| public class SshModule extends SingleCommandPluginModule { |
| @Override |
| protected void configure(LinkedBindingBuilder<Command> b) { |
| b.to(ShellCommand.class); |
| } |
| } |
| ---- |
| |
| If the plugin above is deployed under sh.jar file in `$site/plugins` |
| directory, generic commands can be called without specifying the |
| actual SSH command. Note in the example below, that the called commands |
| `ls` and `ps` was not explicitly bound: |
| |
| ---- |
| $ ssh -p 29418 review.example.com sh ls |
| $ ssh -p 29418 review.example.com sh ps |
| ---- |
| |
| [[simple-configuration]] |
| == Simple Configuration in `gerrit.config` |
| |
| 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 |
| link:#configuration[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"); |
| ---- |
| |
| [[configuration]] |
| == Configuration in own config file |
| |
| Plugins can store their configuration in an own configuration file. |
| This makes sense if the plugin configuration is rather complex and |
| requires the usage of subsections. Plugins that have a simple |
| key-value pair configuration can store their configuration in a |
| link:#simple-configuration[`plugin` subsection of the `gerrit.config` |
| file]. |
| |
| The plugin configuration file must be named after the plugin and must |
| be located in the `etc` folder of the review site. For example a |
| configuration file for a `default-reviewer` plugin could look like |
| this: |
| |
| .$site_path/etc/default-reviewer.config |
| ---- |
| [branch "refs/heads/master"] |
| reviewer = Project Owners |
| reviewer = john.doe@example.com |
| [match "file:^.*\.txt"] |
| reviewer = My Info Developers |
| ---- |
| |
| Via the `com.google.gerrit.server.config.PluginConfigFactory` class a |
| plugin can easily access its configuration: |
| |
| [source,java] |
| ---- |
| @Inject |
| private com.google.gerrit.server.config.PluginConfigFactory cfg; |
| |
| [...] |
| |
| String[] reviewers = cfg.getGlobalPluginConfig("default-reviewer") |
| .getStringList("branch", "refs/heads/master", "reviewer"); |
| ---- |
| |
| The plugin configuration is loaded only once and is then cached. |
| Similar to changes in 'gerrit.config', changes to the plugin |
| configuration file will only become effective after a Gerrit restart. |
| |
| [[simple-project-specific-configuration]] |
| == Simple Project Specific Configuration in `project.config` |
| |
| 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 |
| link:#project-specific-configuration[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. |
| |
| Plugin configuration values that are stored in the `project.config` |
| file can be exposed in the ProjectInfoScreen to allow project owners |
| to see and edit them from the UI. |
| |
| For this an instance of `ProjectConfigEntry` needs to be bound for each |
| parameter. The export name must be a valid Git variable name. The |
| variable name is case-insensitive, allows only alphanumeric characters |
| and '-', and must start with an alphabetic character. |
| |
| The example below shows how the parameters `plugin.helloworld.enabled` |
| and `plugin.helloworld.language` are bound to be editable from the |
| Web UI. For the parameter `plugin.helloworld.enabled` "Enable Greeting" |
| is provided as display name and the default value is set to `true`. |
| For the parameter `plugin.helloworld.language` "Preferred Language" |
| is provided as display name and "en" is set as default value. |
| |
| [source,java] |
| ---- |
| class Module extends AbstractModule { |
| @Override |
| protected void configure() { |
| bind(ProjectConfigEntry.class) |
| .annotatedWith(Exports.named("enabled")) |
| .toInstance(new ProjectConfigEntry("Enable Greeting", true)); |
| bind(ProjectConfigEntry.class) |
| .annotatedWith(Exports.named("language")) |
| .toInstance(new ProjectConfigEntry("Preferred Language", "en")); |
| } |
| } |
| ---- |
| |
| By overwriting the `onUpdate` method of `ProjectConfigEntry` plugins |
| can be notified when this configuration parameter is updated on a |
| project. |
| |
| [[project-specific-configuration]] |
| == Project Specific Configuration in own config file |
| |
| Plugins can store their project specific configuration in an own |
| configuration file in the projects `refs/meta/config` branch. |
| This makes sense if the plugins project specific configuration is |
| rather complex and requires the usage of subsections. Plugins that |
| have a simple key-value pair configuration can store their project |
| specific configuration in a link:#simple-project-specific-configuration[ |
| `plugin` subsection of the `project.config` file]. |
| |
| The plugin configuration file in the `refs/meta/config` branch must be |
| named after the plugin. For example a configuration file for a |
| `default-reviewer` plugin could look like this: |
| |
| .default-reviewer.config |
| ---- |
| [branch "refs/heads/master"] |
| reviewer = Project Owners |
| reviewer = john.doe@example.com |
| [match "file:^.*\.txt"] |
| reviewer = My Info Developers |
| ---- |
| |
| Via the `com.google.gerrit.server.config.PluginConfigFactory` class a |
| plugin can easily access its project specific configuration: |
| |
| [source,java] |
| ---- |
| @Inject |
| private com.google.gerrit.server.config.PluginConfigFactory cfg; |
| |
| [...] |
| |
| String[] reviewers = cfg.getProjectPluginConfig(project, "default-reviewer") |
| .getStringList("branch", "refs/heads/master", "reviewer"); |
| ---- |
| |
| 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; |
| |
| [...] |
| |
| String[] reviewers = cfg.getProjectPluginConfigWithInheritance(project, "default-reviewer") |
| .getStringList("branch", "refs/heads/master", "reviewer"); |
| ---- |
| |
| Project owners can edit the project configuration by fetching the |
| `refs/meta/config` branch, editing the `<plugin-name>.config` file and |
| pushing the commit back. |
| |
| == React on changes in project configuration |
| |
| If a plugin wants to react on changes in the project configuration, it |
| can implement a `GitReferenceUpdatedListener` and filter on events for |
| the `refs/meta/config` branch: |
| |
| [source,java] |
| ---- |
| public class MyListener implements GitReferenceUpdatedListener { |
| |
| private final MetaDataUpdate.Server metaDataUpdateFactory; |
| |
| @Inject |
| MyListener(MetaDataUpdate.Server metaDataUpdateFactory) { |
| this.metaDataUpdateFactory = metaDataUpdateFactory; |
| } |
| |
| @Override |
| public void onGitReferenceUpdated(Event event) { |
| if (event.getRefName().equals(RefNames.REFS_CONFIG)) { |
| Project.NameKey p = new Project.NameKey(event.getProjectName()); |
| try { |
| ProjectConfig oldCfg = parseConfig(p, event.getOldObjectId()); |
| ProjectConfig newCfg = parseConfig(p, event.getNewObjectId()); |
| |
| if (oldCfg != null && newCfg != null |
| && !oldCfg.getProject().getSubmitType().equals(newCfg.getProject().getSubmitType())) { |
| // submit type has changed |
| ... |
| } |
| } catch (IOException | ConfigInvalidException e) { |
| ... |
| } |
| } |
| } |
| |
| private ProjectConfig parseConfig(Project.NameKey p, String idStr) |
| throws IOException, ConfigInvalidException, RepositoryNotFoundException { |
| ObjectId id = ObjectId.fromString(idStr); |
| if (ObjectId.zeroId().equals(id)) { |
| return null; |
| } |
| return ProjectConfig.read(metaDataUpdateFactory.create(p), id); |
| } |
| } |
| ---- |
| |
| |
| [[capabilities]] |
| == Plugin Owned Capabilities |
| |
| Plugins may provide their own capabilities and restrict usage of SSH |
| commands or `UiAction` 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, capability 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 |
| ---- |
| |
| It is also possible to show some menu entries only if the user has a |
| certain capability: |
| |
| [source,java] |
| ---- |
| public class MyTopMenuExtension implements TopMenu { |
| private final String pluginName; |
| private final Provider<CurrentUser> userProvider; |
| private final List<MenuEntry> menuEntries; |
| |
| @Inject |
| public MyTopMenuExtension(@PluginName String pluginName, |
| Provider<CurrentUser> userProvider) { |
| this.pluginName = pluginName; |
| this.userProvider = userProvider; |
| menuEntries = new ArrayList<TopMenu.MenuEntry>(); |
| |
| // add menu entry that is only visible to users with a certain capability |
| if (canSeeMenuEntry()) { |
| menuEntries.add(new MenuEntry("Top Menu Entry", Collections |
| .singletonList(new MenuItem("Gerrit", "http://gerrit.googlecode.com/")))); |
| } |
| |
| // add menu entry that is visible to all users (even anonymous users) |
| menuEntries.add(new MenuEntry("Top Menu Entry", Collections |
| .singletonList(new MenuItem("Documentation", "/plugins/myplugin/")))); |
| } |
| |
| private boolean canSeeMenuEntry() { |
| if (userProvider.get().isIdentifiedUser()) { |
| CapabilityControl ctl = userProvider.get().getCapabilities(); |
| return ctl.canPerform(pluginName + "-" + MyCapability.ID) |
| || ctl.canAdministrateServer(); |
| } else { |
| return false; |
| } |
| } |
| |
| @Override |
| public List<MenuEntry> getEntries() { |
| return menuEntries; |
| } |
| } |
| ---- |
| |
| [[gwt_ui_extension]] |
| == GWT UI Extension |
| Plugins can extend the Gerrit UI with own GWT code. |
| |
| The Maven archetype 'gerrit-plugin-gwt-archetype' can be used to |
| generate a GWT plugin skeleton. How to use the Maven plugin archetypes |
| is described in the link:#getting-started[Getting started] section. |
| |
| The generated GWT plugin has a link:#top-menu-extensions[top menu] that |
| opens a GWT dialog box when the user clicks on it. |
| |
| In addition to the Gerrit-Plugin API a GWT plugin depends on |
| `gerrit-plugin-gwtui`. This dependency must be specified in the |
| `pom.xml`: |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>com.google.gerrit</groupId> |
| <artifactId>gerrit-plugin-gwtui</artifactId> |
| <version>${Gerrit-ApiVersion}</version> |
| </dependency> |
| ---- |
| |
| A GWT plugin must contain a GWT module file, e.g. `HelloPlugin.gwt.xml`, |
| that bundles together all the configuration settings of the GWT plugin: |
| |
| [source,xml] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <module rename-to="hello_gwt_plugin"> |
| <!-- Inherit the core Web Toolkit stuff. --> |
| <inherits name="com.google.gwt.user.User"/> |
| <!-- Other module inherits --> |
| <inherits name="com.google.gerrit.Plugin"/> |
| <inherits name="com.google.gwt.http.HTTP"/> |
| <!-- Using GWT built-in themes adds a number of static --> |
| <!-- resources to the plugin. No theme inherits lines were --> |
| <!-- added in order to make this plugin as simple as possible --> |
| <!-- Specify the app entry point class. --> |
| <entry-point class="${package}.client.HelloPlugin"/> |
| <stylesheet src="hello.css"/> |
| </module> |
| ---- |
| |
| The GWT module must inherit `com.google.gerrit.Plugin` and |
| `com.google.gwt.http.HTTP`. |
| |
| To register the GWT module a `GwtPlugin` needs to be bound. |
| |
| If no Guice modules are declared in the manifest, the GWT plugin may |
| use auto-registration by using the `@Listen` annotation: |
| |
| [source,java] |
| ---- |
| @Listen |
| public class MyExtension extends GwtPlugin { |
| public MyExtension() { |
| super("hello_gwt_plugin"); |
| } |
| } |
| ---- |
| |
| Otherwise the binding must be done in an `HttpModule`: |
| |
| [source,java] |
| ---- |
| public class HttpModule extends HttpPluginModule { |
| |
| @Override |
| protected void configureServlets() { |
| DynamicSet.bind(binder(), WebUiPlugin.class) |
| .toInstance(new GwtPlugin("hello_gwt_plugin")); |
| } |
| } |
| ---- |
| |
| The HTTP module above must be declared in the `pom.xml` for Maven |
| driven plugins: |
| |
| [source,xml] |
| ---- |
| <manifestEntries> |
| <Gerrit-HttpModule>com.googlesource.gerrit.plugins.myplugin.HttpModule</Gerrit-HttpModule> |
| </manifestEntries> |
| ---- |
| |
| The name that is provided to the `GwtPlugin` must match the GWT |
| module name compiled into the plugin. The name of the GWT module |
| can be explicitly set in the GWT module XML file by specifying |
| the `rename-to` attribute on the module. It is important that the |
| module name be unique across all plugins installed on the server, |
| as the module name determines the JavaScript namespace used by the |
| compiled plugin code. |
| |
| [source,xml] |
| ---- |
| <module rename-to="hello_gwt_plugin"> |
| ---- |
| |
| The actual GWT code must be implemented in a class that extends |
| `com.google.gerrit.plugin.client.PluginEntryPoint`: |
| |
| [source,java] |
| ---- |
| public class HelloPlugin extends PluginEntryPoint { |
| |
| @Override |
| public void onPluginLoad() { |
| // Create the dialog box |
| final DialogBox dialogBox = new DialogBox(); |
| |
| // The content of the dialog comes from a User specified Preference |
| dialogBox.setText("Hello from GWT Gerrit UI plugin"); |
| dialogBox.setAnimationEnabled(true); |
| Button closeButton = new Button("Close"); |
| VerticalPanel dialogVPanel = new VerticalPanel(); |
| dialogVPanel.setWidth("100%"); |
| dialogVPanel.setHorizontalAlignment(VerticalPanel.ALIGN_CENTER); |
| dialogVPanel.add(closeButton); |
| |
| closeButton.addClickHandler(new ClickHandler() { |
| public void onClick(ClickEvent event) { |
| dialogBox.hide(); |
| } |
| }); |
| |
| // Set the contents of the Widget |
| dialogBox.setWidget(dialogVPanel); |
| |
| RootPanel rootPanel = RootPanel.get(HelloMenu.MENU_ID); |
| rootPanel.getElement().removeAttribute("href"); |
| rootPanel.addDomHandler(new ClickHandler() { |
| @Override |
| public void onClick(ClickEvent event) { |
| dialogBox.center(); |
| dialogBox.show(); |
| } |
| }, ClickEvent.getType()); |
| } |
| } |
| ---- |
| |
| This class must be set as entry point in the GWT module: |
| |
| [source,xml] |
| ---- |
| <entry-point class="${package}.client.HelloPlugin"/> |
| ---- |
| |
| In addition this class must be defined as module in the `pom.xml` for the |
| `gwt-maven-plugin` and the `webappDirectory` option of `gwt-maven-plugin` |
| must be set to `${project.build.directory}/classes/static`: |
| |
| [source,xml] |
| ---- |
| <plugin> |
| <groupId>org.codehaus.mojo</groupId> |
| <artifactId>gwt-maven-plugin</artifactId> |
| <version>2.5.1</version> |
| <configuration> |
| <module>com.googlesource.gerrit.plugins.myplugin.HelloPlugin</module> |
| <disableClassMetadata>true</disableClassMetadata> |
| <disableCastChecking>true</disableCastChecking> |
| <webappDirectory>${project.build.directory}/classes/static</webappDirectory> |
| </configuration> |
| <executions> |
| <execution> |
| <goals> |
| <goal>compile</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| ---- |
| |
| To attach a GWT widget defined by the plugin to the Gerrit core UI |
| `com.google.gwt.user.client.ui.RootPanel` can be used to manipulate the |
| Gerrit core widgets: |
| |
| [source,java] |
| ---- |
| RootPanel rootPanel = RootPanel.get(HelloMenu.MENU_ID); |
| rootPanel.getElement().removeAttribute("href"); |
| rootPanel.addDomHandler(new ClickHandler() { |
| @Override |
| public void onClick(ClickEvent event) { |
| dialogBox.center(); |
| dialogBox.show(); |
| } |
| }, ClickEvent.getType()); |
| ---- |
| |
| GWT plugins can come with their own css file. This css file must have a |
| unique name and must be registered in the GWT module: |
| |
| [source,xml] |
| ---- |
| <stylesheet src="hello.css"/> |
| ---- |
| |
| If a GWT plugin wants to invoke the Gerrit REST API it can use |
| `com.google.gerrit.plugin.client.rpc.RestApi` to construct the URL |
| path and to trigger the REST calls. |
| |
| Example for invoking a Gerrit core REST endpoint: |
| |
| [source,java] |
| ---- |
| new RestApi("projects").id(projectName).view("description") |
| .put("new description", new AsyncCallback<JavaScriptObject>() { |
| |
| @Override |
| public void onSuccess(JavaScriptObject result) { |
| // TODO |
| } |
| |
| @Override |
| public void onFailure(Throwable caught) { |
| // never invoked |
| } |
| }); |
| ---- |
| |
| Example for invoking a REST endpoint defined by a plugin: |
| |
| [source,java] |
| ---- |
| new RestApi("projects").id(projectName).view("myplugin", "myview") |
| .get(new AsyncCallback<JavaScriptObject>() { |
| |
| @Override |
| public void onSuccess(JavaScriptObject result) { |
| // TODO |
| } |
| |
| @Override |
| public void onFailure(Throwable caught) { |
| // never invoked |
| } |
| }); |
| ---- |
| |
| The `onFailure(Throwable)` of the provided callback is never invoked. |
| If an error occurs, it is shown in an error dialog. |
| |
| In order to be able to do REST calls the GWT module must inherit |
| `com.google.gwt.json.JSON`: |
| |
| [source,xml] |
| ---- |
| <inherits name="com.google.gwt.json.JSON"/> |
| ---- |
| |
| [[screen]] |
| == Add Screen |
| A link:#gwt_ui_extension[GWT plugin] can link:#top-menu-extensions[add |
| a menu item] that opens a screen that is implemented by the plugin. |
| This way plugin screens can be fully integrated into the Gerrit UI. |
| |
| Example menu item: |
| [source,java] |
| ---- |
| public class MyMenu implements TopMenu { |
| private final List<MenuEntry> menuEntries; |
| |
| @Inject |
| public MyMenu(@PluginName String name) { |
| menuEntries = Lists.newArrayList(); |
| menuEntries.add(new MenuEntry("My Menu", Collections.singletonList( |
| new MenuItem("My Screen", "#/x/" + name + "/my-screen", "")))); |
| } |
| |
| @Override |
| public List<MenuEntry> getEntries() { |
| return menuEntries; |
| } |
| } |
| ---- |
| |
| Example screen: |
| [source,java] |
| ---- |
| public class MyPlugin extends PluginEntryPoint { |
| @Override |
| public void onPluginLoad() { |
| Plugin.get().screen("my-screen", new Screen.EntryPoint() { |
| @Override |
| public void onLoad(Screen screen) { |
| screen.add(new InlineLabel("My Screen"); |
| screen.show(); |
| } |
| }); |
| } |
| } |
| ---- |
| |
| [[settings-screen]] |
| == Plugin Settings Screen |
| |
| If a plugin implements a screen for administrating its settings that is |
| available under "#/x/<plugin-name>/settings" it is automatically linked |
| from the plugin list screen. |
| |
| [[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`. |
| |
| [[links-to-external-tools]] |
| == Links To External Tools |
| |
| Gerrit has extension points that enables development of a |
| light-weight plugin that links commits to external |
| tools (GitBlit, CGit, company specific resources etc). |
| |
| PatchSetWebLinks will appear to the right of the commit-SHA1 in the UI. |
| |
| [source, java] |
| ---- |
| import com.google.gerrit.extensions.annotations.Listen; |
| import com.google.gerrit.extensions.webui.PatchSetWebLink;; |
| |
| @Listen |
| public class MyWeblinkPlugin implements PatchSetWebLink { |
| |
| private String name = "MyLink"; |
| private String placeHolderUrlProjectCommit = "http://my.tool.com/project=%s/commit=%s"; |
| |
| @Override |
| public String getLinkName() { |
| return name ; |
| } |
| |
| @Override |
| public String getPatchSetUrl(String project, String commit) { |
| return String.format(placeHolderUrlProjectCommit, project, commit); |
| } |
| |
| } |
| ---- |
| |
| ProjectWebLinks will appear in the project list in the |
| `Repository Browser` column. |
| |
| [[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. |
| |
| Web UI plugins distributed as single `.js` file can be deployed |
| without the overhead of JAR packaging, for more information refer to |
| 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|js)`. The name of |
| the JAR file, minus the `.jar` or `.js` 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] |
| |
| SEARCHBOX |
| --------- |