Add PatchsetHook extensions

James Moger

2014-04-11 aa89bef3a9e06404afb268426cbab1ef20c3857c

Add PatchsetHook extensions

 src/main/java/com/gitblit/extensions/PatchsetHook.java

New file
@@ -0,0 +1,53 @@
/*
 * Copyright 2014 gitblit.com.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.gitblit.extensions;

import ro.fortsoft.pf4j.ExtensionPoint;

import com.gitblit.models.TicketModel;

/**
 * Extension point for plugins to respond to Ticket patchset changes.
 *
 * @author James Moger
 *
 */
public abstract class PatchsetHook implements ExtensionPoint {

    /**
     * Called after a new patchset has been created.  This patchset
     * may not be the first patchset of the ticket.  The ticket may be a new
     * proposal or it may be a existing ticket that now has a new patchset.
     *
     * @param ticket
     */
    public abstract void onNewPatchset(TicketModel ticket);

    /**
     * Called after a patchset has been FAST-FORWARD updated.
     *
     * @param ticket
     */
    public abstract void onUpdatePatchset(TicketModel ticket);

    /**
     * Called after a patchset has been merged to the integration branch specified
     * in the ticket.
     *
     * @param ticket
     */
    public abstract void onMergePatchset(TicketModel ticket);
}

 src/main/java/com/gitblit/git/PatchsetReceivePack.java

@@ -51,6 +51,7 @@


import com.gitblit.Constants;

import com.gitblit.Keys;

import com.gitblit.extensions.PatchsetHook;

import com.gitblit.manager.IGitblit;

import com.gitblit.models.RepositoryModel;

import com.gitblit.models.TicketModel;

@@ -716,6 +717,15 @@
                RefLogUtils.updateRefLog(user, getRepository(),

                        Arrays.asList(new ReceiveCommand(cmd.getOldId(), cmd.getNewId(), cmd.getRefName())));



                // call any patchset hooks

                for (PatchsetHook hook : gitblit.getExtensions(PatchsetHook.class)) {

                    try {

                        hook.onNewPatchset(ticket);

                    } catch (Exception e) {

                        LOGGER.error("Failed to execute extension", e);

                    }

                }



                return ticket;

            } else {

                sendError("FAILED to create ticket");

@@ -742,6 +752,20 @@
                // log the new patchset ref

                RefLogUtils.updateRefLog(user, getRepository(),

                    Arrays.asList(new ReceiveCommand(cmd.getOldId(), cmd.getNewId(), cmd.getRefName())));



                // call any patchset hooks

                final boolean isNewPatchset = change.patchset.rev == 1;

                for (PatchsetHook hook : gitblit.getExtensions(PatchsetHook.class)) {

                    try {

                        if (isNewPatchset) {

                            hook.onNewPatchset(ticket);

                        } else {

                            hook.onUpdatePatchset(ticket);

                        }

                    } catch (Exception e) {

                        LOGGER.error("Failed to execute extension", e);

                    }

                }



                // return the updated ticket

                return ticket;

@@ -1167,6 +1191,15 @@
                        ObjectId.fromString(mergeResult.sha), oldRef.getName());

                RefLogUtils.updateRefLog(user, getRepository(), Arrays.asList(cmd));

            }



            // call patchset hooks

            for (PatchsetHook hook : gitblit.getExtensions(PatchsetHook.class)) {

                try {

                    hook.onMergePatchset(ticket);

                } catch (Exception e) {

                    LOGGER.error("Failed to execute extension", e);

                }

            }

            return mergeResult.status;

        } else {

            LOGGER.error("FAILED to resolve ticket {} by merge from web ui", ticketId);


 src/site/setup_plugins.mkd

@@ -1,106 +1,122 @@


## Gitblit Plugins



*SINCE 1.5.0*



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.



### 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.



The zip plugins are stored in `${baseFolder}/plugins` and are unpacked on startup into folders of the same name.



A plugin defines it's metadata in the META-INF/MANIFEST.MF file:



    Plugin-Class: com.gitblit.plugin.powertools.Powertools

    Plugin-Dependencies: 
    Plugin-Id: com.gitblit.plugin:powertools

    Plugin-Provider: James Moger

    Plugin-Version: 1.1.0



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.



    Plugin-Dependencies: foo, bar



**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.



### Managing Plugins



Administrators may manage plugins through the `plugin` SSH dispatch command:



    ssh host plugin



Through this command interface plugins can be started, stopped, disabled, enabled, installed, uninstalled, listed, etc.



### Default Plugin Registry



Gitblit provides a simple default registry of plugins. The registry is a JSON file and it lists plugin metadata and download locations.



    plugins.registry = http://plugins.gitblit.com/plugins.json



The [registry](http://plugins.gitblit.com/plugins.json) is currently hosted in a [Git repository on Github](https://github.com/gitblit/gitblit-registry).  This git repository is also a [Maven-compatible repository](http://plugins.gitblit.com), which hosts some plugin binaries.



### Contributing Plugins to the Default Registry



If you develop your own plugins that you want hosted by or linked in the default registry, open pull request for the registry repository.  Any contributed binaries hosted in this repository must have Maven metadata and the SHA-1 & MD5 checksums.  By default, Gitblit enforces checksum validation on all downloads.



### Hosting your Own Registry / Allowing Multiple Registries



The `plugins.json` file is parameterized with the `${self}` placeholder.  This parameter is substituted on download with with the source URL of the registry file.  This allows you to clone and serve your own copy of this git repository or just server your own `plugins.json` on your own network.



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 ro.fortsoft.pf4j.Extension;



@Extension

public class MyHook extends ReceiveHook {



    @Override

    public void onPreReceive(GitblitReceivePack receivePack, Collection<ReceiveCommand> commands) {

        RepositoryModel repository = receivePack.getRepositoryModel();

        UserModel user = receivePack.getUserModel();

        receivePack.sendInfo("Hi {0}, I see {1} commands for {2} onPreReceive",

                        user.getDisplayName(),

                        commands.size(),

                        repository.name);

    }



    @Override

    public void onPostReceive(GitblitReceivePack receivePack, Collection<ReceiveCommand> commands) {

        RepositoryModel repository = receivePack.getRepositoryModel();

        UserModel user = receivePack.getUserModel();

        receivePack.sendInfo("Hi {0}, I see {1} commands for {2} onPostReceive",

                        user.getDisplayName(),

                        commands.size(),

                        repository.name);

    }

}



```



### 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.



[6x12.dfont](6x12.dfont)

[6x13.dfont](6x13.dfont)

[7x13.dfont](7x13.dfont)

[7x14.dfont](7x14.dfont)




## Gitblit Plugins

*SINCE 1.5.0*

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.

### 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.

The zip plugins are stored in `${baseFolder}/plugins` and are unpacked on startup into folders of the same name.

A plugin defines it's metadata in the META-INF/MANIFEST.MF file:

    Plugin-Class: com.gitblit.plugin.powertools.Powertools
    Plugin-Dependencies: 
    Plugin-Id: com.gitblit.plugin:powertools
    Plugin-Provider: James Moger
    Plugin-Version: 1.1.0

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.

    Plugin-Dependencies: foo, bar

**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.

### Managing Plugins

Administrators may manage plugins through the `plugin` SSH dispatch command:

    ssh host plugin

Through this command interface plugins can be started, stopped, disabled, enabled, installed, uninstalled, listed, etc.

### Default Plugin Registry

Gitblit provides a simple default registry of plugins. The registry is a JSON file and it lists plugin metadata and download locations.

    plugins.registry = http://plugins.gitblit.com/plugins.json

The [registry](http://plugins.gitblit.com/plugins.json) is currently hosted in a [Git repository on Github](https://github.com/gitblit/gitblit-registry).  This git repository is also a [Maven-compatible repository](http://plugins.gitblit.com), which hosts some plugin binaries.

### Contributing Plugins to the Default Registry

If you develop your own plugins that you want hosted by or linked in the default registry, open pull request for the registry repository.  Any contributed binaries hosted in this repository must have Maven metadata and the SHA-1 & MD5 checksums.  By default, Gitblit enforces checksum validation on all downloads.

### Hosting your Own Registry / Allowing Multiple Registries

The `plugins.json` file is parameterized with the `${self}` placeholder.  This parameter is substituted on download with with the source URL of the registry file.  This allows you to clone and serve your own copy of this git repository or just server your own `plugins.json` on your own network.

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<ReceiveCommand> commands) {
    }

    @Override
    public void onPostReceive(GitblitReceivePack receivePack, Collection<ReceiveCommand> 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) {
    }
}
```

### 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.

[6x12.dfont](6x12.dfont)
[6x13.dfont](6x13.dfont)
[7x13.dfont](7x13.dfont)
[7x14.dfont](7x14.dfont)