Gitblit devel
view | history | commit | commitdiff
David Ostrovsky
2014-06-16 5441436f507a8b1b0dbd24b523e4a27bd30840e6
commit | author | age
c5dfd6 1 ## Extension Points
JM 2
3 Gitblit offers several extension points for enhancing and customizing it's runtime behavior.
4
2d73a0 5 Each available extension point has a sample implementation in the [gitblit-cookbook-plugin (Maven project)](https://github.com/gitblit/gitblit-cookbook-plugin).
JM 6
7 **NOTE:**
8 Gitblit does not yet offer a comprehensize dependency injection architecture.  This will be addressed in a subsequent release.  For now you may access all of Gitblit's core managers through a static singleton app context:
9
10 ```java
11 import com.gitblit.extensions.GitblitPlugin;
12 import com.gitblit.servlet.GitblitContext;
13 import com.gitblit.manager.IRuntimeManager;
14 import com.gitblit.manager.IUserManager;
15 import com.gitblit.manager.IAuthenticationManager;
16 import com.gitblit.manager.INotificationManager;
17 import com.gitblit.manager.IRepositoryManager;
18 import com.gitblit.manager.IProjectManager;
19 import com.gitblit.manager.IFederationManager;
20 import com.gitblit.manager.IPluginManager;
21 import com.gitblit.manager.IGitblit;
cf4004 22 import ro.fortsoft.pf4j.Version;
2d73a0 23
JM 24 public class ExamplePlugin extends GitblitPlugin {
25
26     @Override
27     public void start() {
28         IRuntimeManager runtime = GitblitContext.getManager(IRuntimeManager.class);
29         IUserManager users = GitblitContext.getManager(IUserManager.class);
30         IAuthenticationManager auth = GitblitContext.getManager(IAuthenticationManager.class);
31         INotificationManager notifications = GitblitContext.getManager(INotificationManager.class);
32         IRepositoryManager repos = GitblitContext.getManager(IRepositoryManager.class);
33         IProjectManager projects = GitblitContext.getManager(IProjectManager.class);
34         IFederationManager federation = GitblitContext.getManager(IFederationManager.class);
35         IPluginManager plugins = GitblitContext.getManager(IPluginManager.class);
36         IGitblit gitblit = GitblitContext.getManager(IGitblit.class);
37     }
cf4004 38
JM 39     @Override
40     public void stop() {
41     }
42
43     @Override
44     public void onInstall() {
45     }
46
47     @Override
48     public void onUpgrade(Version oldVersion) {
49     }
50
51     @Override
52     public void onUninstall() {
53     }
2d73a0 54 }
7a401a 55
JM 56 /**
c59584 57  * You can also create Webapp plugins that register pages.
7a401a 58  */
JM 59 public class ExampleWicketPlugin extends GitblitWicketPlugin {
60     @Override
61     public void start() {
62     }
63
64     @Override
65     public void stop() {
66     }
67
68     @Override
69     public void onInstall() {
70     }
71
72     @Override
73     public void onUpgrade(Version oldVersion) {
74     }
75
76     @Override
77     public void onUninstall() {
78     }
79
80     @Override
81     protected void init(GitblitWicketApp app) {
82         app.mount("/logo", LogoPage.class);
83         app.mount("/hello", HelloWorldPage.class);
84     }
85 }
2d73a0 86 ```
c5dfd6 87
JM 88 ### SSH Dispatch Command
89
90 *SINCE 1.5.0*
91
2d73a0 92 You can provide your own custom SSH command hierarchies by subclassing the *DispatchCommand* class.
c5dfd6 93
JM 94 ```java
95 import ro.fortsoft.pf4j.Extension;
2d73a0 96 import org.kohsuke.args4j.Option;
JM 97 import org.slf4j.Logger;
98 import org.slf4j.LoggerFactory;
c5dfd6 99 import com.gitblit.transport.ssh.commands.CommandMetaData;
JM 100 import com.gitblit.transport.ssh.commands.DispatchCommand;
2d73a0 101 import com.gitblit.transport.ssh.commands.UsageExample;
c5dfd6 102
JM 103 @Extension
104 @CommandMetaData(name = "mycommands", description = "Sample SSH dispatcher")
105 public class MyDispatcher extends DispatchCommand {
106
107     @Override
8cbdf3 108     protected void setup() {
c5dfd6 109         // commands in this dispatcher
8cbdf3 110         register(CommandA.class);
JM 111         register(CommandB.class);
c5dfd6 112
JM 113         // nested dispatchers
8cbdf3 114         register(SubDispatcher1.class);
JM 115         register(SubDispatcher2.class);
c5dfd6 116     }
2d73a0 117
JM 118     @CommandMetaData(name = "commanda", aliases = { "ca" }, description = "description of command a")
119     @UsageExample(syntax = "${cmd} --myflag", description = "description of commanda with --myflag")
120     public static class CommandA extends SshCommand {
121
122         protected final Logger log = LoggerFactory.getLogger(getClass());
123
124         @Option(name = "--myflag", aliases = { "-m" }, usage = "enable myflag")
125         boolean myflag;
126
127         @Override
128         public void run() throws Failure {
129             if (myflag) {
130                 log.info("Run with --myflag");
131             } else {
132                 log.info("Run without --myflag");
133             }
134         }
135     }
c5dfd6 136 }
JM 137 ```
138
139 ### Pre- and Post- Receive Hook
140
141 *SINCE 1.5.0*
142
143 You can provide your own custom pre and/or post receive hooks by subclassing the *ReceiveHook* class.
144
145 ```java
146 import com.gitblit.extensions.ReceiveHook;
147 import java.util.Collection;
148 import org.eclipse.jgit.transport.ReceiveCommand;
149 import ro.fortsoft.pf4j.Extension;
150
151 @Extension
152 public class MyReceiveHook extends ReceiveHook {
153
154     @Override
155     public void onPreReceive(GitblitReceivePack receivePack, Collection<ReceiveCommand> commands) {
156     }
157
158     @Override
159     public void onPostReceive(GitblitReceivePack receivePack, Collection<ReceiveCommand> commands) {
160     }
161 }
162
163 ```
164
165 ### Patchset Hook
166
167 *SINCE 1.5.0*
168
169 You can provide your own custom patchset hook by subclassing the *PatchsetHook* class.
170
171 ```java
172 import com.gitblit.extensions.PatchsetHook;
173 import com.gitblit.models.TicketModel;
174 import ro.fortsoft.pf4j.Extension;
175
176 @Extension
177 public class MyPatchsetHook extends PatchsetHook {
178
179     @Override
180     public void onNewPatchset(TicketModel ticket) {
181     }
182
183     @Override
184     public void onUpdatePatchset(TicketModel ticket) {
185     }
186
187     @Override
188     public void onMergePatchset(TicketModel ticket) {
189     }
190 }
191 ```
192
193 ### Ticket Hook
194
195 *SINCE 1.5.0*
196
197 You can provide your own custom ticket hook by subclassing the *TicketHook* class.
198
199 ```java
200 import com.gitblit.extensions.TicketHook;
201 import com.gitblit.models.TicketModel;
202 import com.gitblit.models.TicketModel.Change;
203 import ro.fortsoft.pf4j.Extension;
204
205 @Extension
206 public class MyTicketHook extends TicketHook {
207
208     @Override
209     public void onNewTicket(TicketModel ticket) {
210     }
211
212     @Override
213     public void onUpdateTicket(TicketModel ticket, Change change) {
214     }
215 }
216 ```
217
ec2456 218 ### Request Filter
DO 219
220 *SINCE 1.6.0*
221
222 You can provide your own custom request filter by subclassing the *HttpRequestFilter* class.
223
224 ```java
225 import com.gitblit.extensions.HttpRequestFilter;
226 import ro.fortsoft.pf4j.Extension;
227
228 @Extension
229 public class MyRequestFilter extends HttpRequestFilter {
230
231     @Override
232     public void doFilter(ServletRequest request, ServletResponse response,
233             FilterChain chain) throws IOException, ServletException {
234     }
235 }
236 ```
237
859deb 238 ### User Menu Items
856f3f 239
JM 240 *SINCE 1.6.0*
241
859deb 242 You can provide your own user menu items by subclassing the *UserMenuExtension* class.
856f3f 243
JM 244 ```java
245 import java.util.Arrays;
246 import java.util.List;
247 import ro.fortsoft.pf4j.Extension;
859deb 248 import com.gitblit.extensions.UserMenuExtension;
856f3f 249 import com.gitblit.models.Menu.ExternalLinkMenuItem;
JM 250 import com.gitblit.models.Menu.MenuItem;
251 import com.gitblit.models.UserModel;
252
253 @Extension
859deb 254 public class MyUserMenuContributor extends UserMenuExtension {
856f3f 255
JM 256     @Override
257     public List<MenuItem> getMenuItems(UserModel user) {
7a401a 258         MenuItem item = new ExternalLinkMenuItem("Github", String.format("https://github.com/%s", user.username));
JM 259         return Arrays.asList(item);
260     }
261 }
262 ```
263
264 ### Navigation Links
265
266 *SINCE 1.6.0*
267
268 You can provide your own top-level navigation links by subclassing the *NavLinkExtension* class.
269
270 ```java
271 import java.util.Arrays;
272 import java.util.List;
273 import ro.fortsoft.pf4j.Extension;
274 import com.gitblit.extensions.NavLinkExtension;
275 import com.gitblit.models.UserModel;
276
277 @Extension
278 public class MyNavLink extends NavLinkExtension {
279
280     @Override
281     public List<NavLink> getNavLinks(UserModel user) {
282         NavLink link = new ExternalLinkMenuItem("Github", String.format("https://github.com/%s", user.username));
283         return Arrays.asList(link);
856f3f 284     }
JM 285 }
286 ```
c59584 287
ca4d98 288 ### Server Lifecycle Listener
c59584 289
JM 290 *SINCE 1.6.0*
291
292 You can provide a lifecycle listener to be notified when Gitblit has completely started and just before Gitblit is gracefully terminated.
293
294 ```java
295 import org.slf4j.Logger;
296 import org.slf4j.LoggerFactory;
297 import ro.fortsoft.pf4j.Extension;
298 import com.gitblit.extensions.LifeCycleListener;
299
300 @Extension
301 public class MyLifeCycleListener extends LifeCycleListener {
302
303     final Logger log = LoggerFactory.getLogger(getClass());
304     
305     @Override
306     public void onStartup() {
307         log.info("Gitblit is Ready!!");
308     }
309
310     @Override
311     public void onShutdown() {
312         log.info("Gitblit is Going Down!!");
313     }
314 }
ca4d98 315 ```
JM 316
317 ### Repository Lifecycle Listener
318
319 *SINCE 1.6.0*
320
321 You can provide a lifecycle listener to be notified when Gitblit has created or deleted a repository.
322
323 ```java
324 import org.slf4j.Logger;
325 import org.slf4j.LoggerFactory;
326 import ro.fortsoft.pf4j.Extension;
327 import com.gitblit.extensions.RepositoryLifeCycleListener;
328 import com.gitblit.models.RepositoryModel;
329
330 @Extension
331 public class MyRepoLifeCycleListener extends RepositoryLifeCycleListener {
332
333     final Logger log = LoggerFactory.getLogger(getClass());
334     
335     @Override
336     public void onCreation(RepositoryModel repo) {
337         log.info("Gitblit created {}", repo);
338     }
339
340     @Override
341     public void onDeletion(RepositoryModel repo) {
342         log.info("Gitblit deleted {}", repo);
343     }
344 }
345 ```
346
347 ### User/Team Lifecycle Listener
348
349 *SINCE 1.6.0*
350
351 You can provide a lifecycle listener to be notified when Gitblit has created or deleted a user or a team.
352
353 ```java
354 import org.slf4j.Logger;
355 import org.slf4j.LoggerFactory;
356 import ro.fortsoft.pf4j.Extension;
357 import com.gitblit.extensions.UserTeamLifeCycleListener;
358 import com.gitblit.models.TeamModel;
359 import com.gitblit.models.UserModel;
360
361 @Extension
362 public class MyUserTeamLifeCycleListener extends UserTeamLifeCycleListener {
363
364     final Logger log = LoggerFactory.getLogger(getClass());
365     
366     @Override
367     public void onCreation(UserModel user) {
368         log.info("Gitblit created user {}", user);
369     }
370
371     @Override
372     public void onDeletion(UserModel user) {
373         log.info("Gitblit deleted user {}", user);
374     }
375
376     @Override
377     public void onCreation(TeamModel team) {
378         log.info("Gitblit created team {}", team);
379     }
380
381     @Override
382     public void onDeletion(TeamModel team) {
383         log.info("Gitblit deleted team {}", team);
384     }
385 }
386 ```