From c5dfd60d174a9841e64e4097cecab5aea5c422d0 Mon Sep 17 00:00:00 2001 From: James Moger Date: Sat, 12 Apr 2014 12:26:17 -0400 Subject: [PATCH] Documentation --- build.xml | 6 +- src/site/plugins_extensions.mkd | 115 ++++++++++++++++++ ...setup_plugins.mkd => plugins_overview.mkd} | 102 +++------------- 3 files changed, 134 insertions(+), 89 deletions(-) create mode 100644 src/site/plugins_extensions.mkd rename src/site/{setup_plugins.mkd => plugins_overview.mkd} (53%) diff --git a/build.xml b/build.xml index f9b171dc..c5fd3318 100644 --- a/build.xml +++ b/build.xml @@ -576,7 +576,8 @@ - + + @@ -899,7 +900,8 @@ - + + diff --git a/src/site/plugins_extensions.mkd b/src/site/plugins_extensions.mkd new file mode 100644 index 00000000..d7469ac6 --- /dev/null +++ b/src/site/plugins_extensions.mkd @@ -0,0 +1,115 @@ +## Extension Points + +Gitblit offers several extension points for enhancing and customizing it's runtime behavior. + +Each available extension point has a sample implementation in the [gitblit-cookbook-plugin (Maven project)](https://dev.gitblit.com/summary/gitblit-cookbook-plugin.git). + +### SSH Dispatch Command + +*SINCE 1.5.0* + +You can provide your own custom SSH commands by subclassing the *DispatchCommand* class. + +```java +import ro.fortsoft.pf4j.Extension; + +import com.gitblit.models.UserModel; +import com.gitblit.transport.ssh.commands.CommandMetaData; +import com.gitblit.transport.ssh.commands.DispatchCommand; + +@Extension +@CommandMetaData(name = "mycommands", description = "Sample SSH dispatcher") +public class MyDispatcher extends DispatchCommand { + + @Override + protected void setup(UserModel user) { + // commands in this dispatcher + register(user, CommandA.class); + register(user, CommandB.class); + + // nested dispatchers + register(user, SubDispatcher1.class); + register(user, SubDispatcher2.class); + } +} +``` + +### Pre- and Post- Receive Hook + +*SINCE 1.5.0* + +You can provide your own custom pre and/or post receive hooks by subclassing the *ReceiveHook* class. + +```java +import com.gitblit.extensions.ReceiveHook; +import java.util.Collection; +import org.eclipse.jgit.transport.ReceiveCommand; +import ro.fortsoft.pf4j.Extension; + +@Extension +public class MyReceiveHook extends ReceiveHook { + + @Override + public void onPreReceive(GitblitReceivePack receivePack, Collection commands) { + } + + @Override + public void onPostReceive(GitblitReceivePack receivePack, Collection commands) { + } +} + +``` + +### Patchset Hook + +*SINCE 1.5.0* + +You can provide your own custom patchset hook by subclassing the *PatchsetHook* class. + +```java +import com.gitblit.extensions.PatchsetHook; +import com.gitblit.models.TicketModel; +import ro.fortsoft.pf4j.Extension; + +@Extension +public class MyPatchsetHook extends PatchsetHook { + + @Override + public void onNewPatchset(TicketModel ticket) { + } + + @Override + public void onUpdatePatchset(TicketModel ticket) { + } + + @Override + public void onMergePatchset(TicketModel ticket) { + } +} +``` + +### Ticket Hook + +*SINCE 1.5.0* + +You can provide your own custom ticket hook by subclassing the *TicketHook* class. + +```java +import com.gitblit.extensions.TicketHook; +import com.gitblit.models.TicketModel; +import com.gitblit.models.TicketModel.Change; +import ro.fortsoft.pf4j.Extension; + +@Extension +public class MyTicketHook extends TicketHook { + + @Override + public void onNewTicket(TicketModel ticket) { + } + + @Override + public void onUpdateTicket(TicketModel ticket, Change change) { + } +} +``` + diff --git a/src/site/setup_plugins.mkd b/src/site/plugins_overview.mkd similarity index 53% rename from src/site/setup_plugins.mkd rename to src/site/plugins_overview.mkd index 6e4e92a7..29fc8aa8 100644 --- a/src/site/setup_plugins.mkd +++ b/src/site/plugins_overview.mkd @@ -5,6 +5,12 @@ Gitblit supports extending and enhancing the core functionality through plugins. This mechanism is very young and incomplete with few extension points, but you can expect it to evolve rapidly in upcoming releases. +### What is a plugin? + +A plugin is a collection of Java classes and required jar dependencies bundled together in a zip file. A plugin may optionally include *Extensions* which enhance Gitblit at specific Gitblit-specified *ExtensionPoints*. + +*Plugins* are singleton instances that are *STARTED* when Gitblit launches and *STOPPED* when Gitblit terminates. *Extensions* are dynamic instances that are created when Gitblit processes requests that trigger *ExtensionPoints*. + ### Architecture The existing plugin mechanism is based on [pf4j](https://github.com/decebals/pf4j). Plugins are distributed as zip files and may include their runtime dependencies or may rely on the bundled dependencies of other plugins and/or Gitblit core. @@ -13,11 +19,11 @@ The zip plugins are stored in `${baseFolder}/plugins` and are unpacked on startu A plugin defines it's metadata in the META-INF/MANIFEST.MF file: + Plugin-Id: powertools + Plugin-Description: Gitblit Powertools Plugin-Class: com.gitblit.plugin.powertools.Powertools - Plugin-Dependencies: - Plugin-Id: com.gitblit.plugin:powertools - Plugin-Provider: James Moger - Plugin-Version: 1.1.0 + Plugin-Version: 1.2.0 + Plugin-Provider: gitblit.com In addition to extending Gitblit core, plugins can also define extension points that may be implemented by other plugins. Therefore a plugin may depend on other plugins. @@ -26,6 +32,10 @@ In addition to extending Gitblit core, plugins can also define extension points **NOTE:** The pf4j plugin framework relies on a javac apt processor to generate compile-time extension information, so be sure to enable apt processing in your build process. +#### Limitations of Dependencies & Requires + +Plugins may specify dependencies by ID, but may not specify specific versions of a dependency. The plugin registry allows you to specify a *requires* version of Gitblit, but this is not currently enforced. + ### Managing Plugins Administrators may manage plugins through the `plugin` SSH dispatch command: @@ -52,91 +62,9 @@ The `plugins.json` file is parameterized with the `${self}` placeholder. This p Gitblit also supports loading multiple plugin registries. Just place another **properly formatted** `.json` file in `${baseFolder}/plugins` and Gitblit will load that as an additional registry. -### Extension Point: SSH DispatchCommand - -You can provide your own custom SSH commands by extending the *DispatchCommand* class. - -For some examples of how to do this, please see: - -[gitblit-cookbook-plugin (Maven project)](https://dev.gitblit.com/summary/gitblit-cookbook-plugin.git) -[gitblit-powertools-plugin (Ant/Moxie project)](https://dev.gitblit.com/summary/gitblit-powertools-plugin.git) - -### Extension Point: Pre- and Post- Receive Hook - -You can provide your own custom pre and/or post receive hooks by extending the *ReceiveHook* class. - -```java -import com.gitblit.extensions.ReceiveHook; -import java.util.Collection; -import org.eclipse.jgit.transport.ReceiveCommand; -import ro.fortsoft.pf4j.Extension; - -@Extension -public class MyReceiveHook extends ReceiveHook { - - @Override - public void onPreReceive(GitblitReceivePack receivePack, Collection commands) { - } - - @Override - public void onPostReceive(GitblitReceivePack receivePack, Collection commands) { - } -} - -``` - -### Extension Point: Patchset Hook - -You can provide your own custom patchset hook by extending the *PatchsetHook* class. - -```java -import com.gitblit.extensions.PatchsetHook; -import com.gitblit.models.TicketModel; -import ro.fortsoft.pf4j.Extension; - -@Extension -public class MyPatchsetHook extends PatchsetHook { - - @Override - public void onNewPatchset(TicketModel ticket) { - } - - @Override - public void onUpdatePatchset(TicketModel ticket) { - } - - @Override - public void onMergePatchset(TicketModel ticket) { - } -} -``` - -### Extension Point: Ticket Hook - -You can provide your own custom ticket hook by extending the *TicketHook* class. - -```java -import com.gitblit.extensions.TicketHook; -import com.gitblit.models.TicketModel; -import com.gitblit.models.TicketModel.Change; -import ro.fortsoft.pf4j.Extension; - -@Extension -public class MyTicketHook extends TicketHook { - - @Override - public void onNewTicket(TicketModel ticket) { - } - - @Override - public void onUpdateTicket(TicketModel ticket, Change change) { - } -} -``` - ### Mac OSX Fonts -Gitblit's core SSH commands and those in the *powertools* plugin rely on use of ANSI border characters to provide a pretty presentation of data. Unfortunately, the fonts provided by Apple - while very nice - don't work well with ANSI border characters. The following public domain fixed-width, fixed-point, bitmapped fonts work very nicely. I find the 6x12 font with a line spacing of ~0.8 to be quite acceptable. +Gitblit's core SSH commands and those in the *powertools* plugin rely on ANSI border characters to provide a pretty presentation of data. Unfortunately, the fonts provided by Apple - while very nice - don't work well with ANSI border characters. The following public domain fixed-width, fixed-point, bitmapped fonts work very nicely. I find the 6x12 font with a line spacing of ~0.8 to be quite acceptable. [6x12.dfont](6x12.dfont) [6x13.dfont](6x13.dfont) -- 2.39.5