SVN Hook Tools

Presentation

The SVN Hook Tools is a rule engine designed to quickly and easily add task on Subversion repository hooks. For each hook is associated a rule-set where each rule contains a condition and a list of actions to perform. For example, you may block a commit without a comment, allow log message edition from some users only, or even execute programs or Web requests after creating a tag.

Installation

Prerequisites

The SVN Hook Tools requires a 1.7 JVM.

Deployement

To deploy the tool, you will need to copy the svn-hook-tools.jar and its config directory at the same location, for example the hook directory of the repository.

Call the tool

To call the tool, edit the respository hook shell scripts you want to create tasks and add a the following call to the SVN Hook Tools for Linux:

java -jar svn-hook-tools.jar $(basename $0) $@

or for Windows:

java -jar svn-hook-tools.jar %~n0 %*

The arguments needed to call the tool are the hook name and the hook script arguments.

Setup

Logging setup

The SVN Hook Tools uses a java.util.logging logger. You may configure the logging feature using the configuration file available in config/logging.properties. The log will be really useful during the rule definition process to retrieve configuration errors. By default, the tool writes a human readable svn-hook-tools.log file in the user home directory.

Condition and action binding

The tool comes with built-in conditions and actions. Nevertheless, you may also develop and add you own condition or action and use it throw dynamic class loading. The configuration file responsive for loading and binding classes could be found in config/bindings.properties.

Built-in conditions

The tool comes with some built-in conditions. Here is a summary table of conditions.

Name	Description	Parameters
all	An operator condition valid if all nested conditions are valid.
any	An operator condition valid if at least one of nested condition is valid.
author	A condition that test the Subversion user name.	name: mandatory, the name to check, nameComparison: IS by default, the name comparison method.
emptyCommitLog	A condition valid if the commit log message is empty.
minLengthCommitLog	A condition valid if the commit log message length is greater than the requested length.	length: mandatory, the minimum length of the commit log message.
patternCommitLog	A condition valid if the commit log message valid the given pattern.	pattern: mandatory, the pattern of the commit log message.
resource	A condition valid if any resource operation valid all related resource filters.	See resource filters description below.
not	An operator condition valid if the nested condition is not valid.

The resource condition must include resource filters to be validated. Here is a summary table of resource filters.

Name	Description	Parameters
FileExtension	A resource filter based on file extension.	fileExtension: mandatory, the file extension to check, fileExtensionComparison: IS by default, the file extension comparison method.
FileName	A resource filter based on file name.	fileName: mandatory, the file name to check.
FileLocation	A resource filter based on resource location.	type: no check by default, the location type to check (ROOT_LOCATION, TRUNK_LOCATION, BRANCHES_LOCATION, TAGS_LOCATION_, A_BRANCH_LOCATION_, A_TAG_LOCATION, IN_TRUNK_LOCATION, IN_A_BRANCH_LOCATION, IN_A_TAG_LOCATION, IN_ROOT_LOCATION), projectName: no check by default, the project name to check, projectNameComparison: IS by default, the project name comparison method, branchName: no check by default, the branch name to check, branchNameComparison: IS by default, the branch name comparison method, tagName: no check by default, the tag name to check, tagNameComparison: IS by default, the tag name comparison method, path: no check by default, the path to check, pathComparison: CONTAINS by default, the path comparison method.
Operation	A resource filter based on the operation done on the resource.	operation: mandatory, the operation to check (ADDED, COPIED, DELETED, UPDATED, PROPERTY_CHANGED, LOCK, UNLOCK).
PropertyChange	A resource filter based on resource property change.	name: mandatory, the name of the property to check, oldValue: no check by default, the old value of the property to check, oldValueComparison: IS by default, the old value of the property comparison method, newValue: no check by default, the new value of the property to check, newValueComparison: IS by default, the new value of the property comparison method.
FileType	A resource filter based on resource type.	type: mandatory, the type of the resource to check (DIRECTORY or FILE).

Built-in actions

The tool comes with some built-in actions. Here is a summary table of actions.

Name	Description	Parameters
error	An action that raise an error to the Subversion client.	code: mandatory, the error code to return, message: the error message to send.
exec	An action that execute a program.	command: mandatory, the program command to execute, parameters: empty by default, the program parameters to pass, waitFor: FALSE by default, the flag to define if the engine should wait for the terminaison of the executed program.
log	An action that write a log entry.	message: mandatory, the log message, level: INFO by default, the log level (FINEST, FINER, FINE, CONFIG, INFO, WARNING_ or SEVERE).
request	An action that make a HTTP request.	url: mandatory, the URL to request, type: GET by default, the request type (POST or GET), headers: the request headers, data: the request data to send.

Rules declaration

A rule-set for a hook is described in a XML file. The name of the file must be the same of the hook script suffixed by -rules.xml and be located in the config directory, config/pre-commit-rules.xml for example. The root node should be a ruleset node containing one rule node for each task you want to make. A rule node must have a name attribute to describe it.

<rule-set>
	<rule name="Empty commit log">
	</rule>
	<rule name="Block in trunk modification">
	</rule>
</rule-set>

The rule node may contains a condition node. If the condition node is missing, the rule actions will always be triggered with the hook. The condition node must have a type attribute to define the kind of condition. All available condition types are defined in the config/bindings.properties configuration file.

<rule-set>
	<rule name="Empty commit log">
		<condition type="emptyCommitLog" />
	</rule>
	<rule name="Block in trunk modification">
		<condition type="resource">
			<filter type="location">
				<parameter name="type">IN_TRUNK_LOCATION</parameter>
			</filter>
		</condition>
	</rule>
</rule-set>

If you want to add more than one condition, you may imbricate condition nodes in operator typed condition (all, any, not). For example, if you want to block in trunk modification for all user except admin, you will have the following condition imbrication.

<rule-set>
	<rule name="Empty commit log">
		<condition type="emptyCommitLog" />
	</rule>
	<rule name="Block non admin in trunk modification">
		<condition type="all">
			<condition type="not">
				<condition type="author">
					<parameter name="name" value="admin" />
				</condition>
			</condition>
			<condition type="resource">
				<filter type="location">
					<parameter name="type">IN_TRUNK_LOCATION</parameter>
				</filter>
			</condition>
		</condition>
	</rule>
</rule-set>

After defining your condition, add any action node for each task you want to perform if the condition is met. The action node must have a type parameter. All available action types are defined in the config/bindings.properties configuration file.

<rule-set>
	<rule name="Empty commit log">
		<condition type="emptyCommitLog" />
		<action type="error">
			<parameter name="code">-10</parameter>
			<parameter name="message">The commit message could not be empty.</parameter>
		</action>
	</rule>
	<rule name="Block in trunk modification">
		<condition type="resource">
			<filter type="location">
				<parameter name="type">IN_TRUNK_LOCATION</parameter>
			</filter>
		</condition>
		<action type="error">
			<parameter name="code">-11</parameter>
			<parameter name="message">Forbidden to touch trunk.</parameter>
		</action>
	</rule>
</rule-set>

Doing so, you will define your entire hook rule-set. Each rule performs independently in the sequential order.

Extending the tool

The SVN Hook Tools may be extended by developping conditions and actions. Create a Java project with svn-hook-tools.jar dependency and extend the following classes:

Class	Purpose
action.AbstractAction	Create a new action.
condition.AbstractCondition	Create a new condition.
condition.operator.AbstractGroupCondition	Create a new operator condition.
condition.resource.filter.AbstractResourceFilter	Create a new resource filter (for resource condition).

Each child of those classes may have parameters. Add them public member annoted with @ConfigurationParameter to dynamically load and set parameter value on rule-set parsing. The class field name must match the name attribute value of the related parameter node. Once the child classes done, export you project as jar and add it to the callpath when you call the tool. To be able to use your new conditions and actions, you must declare theirs types in the config/bindings.properties (a mapping between type names and fully qualified class names).