net.haefelingerit.tagmod
Class Plugin

java.lang.Object
  net.haefelingerit.tagmod.Plugin

All Implemented Interfaces:

Serializable, SourceControl

public class Plugin
extends Object
implements SourceControl

This class implements a SourceControl element to be plugged into CruiseControl as a method to detected modifications.

The modification to be detected is whether a CVS tag got assigned to a CVS project. CVS does not provide a direct way to detect this. Instead it is assumed that a tag handler is plugged into the CVS server which records relevant tag operations^[1].

This plugin assumes then, that a local file exists which contains all recorded tag operations. The content of this file must follow some simple syntax rules - see class Parser for further details. How the content of this file is transferred from the CVS server side to the side hosting CruiseControl is not subject of this plugin. The default implementation of the CVS script saves each tag operation itself into CVS as log message of a particular log file. Getting a list of all tag operations is than as simple as calling

 % cvs rlog $somefile
 

This command can then also be used in CruiseControl to regularly query the current list of all tag operations.

About the life-cycle of a source control element within CruiseControl:

For each XML element, a instance of this class gets created. After creation, the object is validated by calling method validate(). If the configuration file changes, the object will be thrown away eventually and a new object gets created and validated.

[1] A example implementation of a tag handler is part of this package. See the folder named scripts.

Author:

geronimo

See Also:

Serialized Form

Field Summary

protected boolean	debug A flag to enable individual debugging.
protected File	file The file to read and parse tag related actions from, see also setFile(File).
List	mods The list of modifications, see also getModifications(Date, Date)
protected Parser	parser The parser to use for parsing tag related actions from.
protected Hashtable	properties A hash table for all those properties to be passed down to the build engine, see also getProperties().
protected String	stem The prefix to use for naming properties, see also setStem(String).

Constructor Summary

Plugin()

Method Summary

protected void	checkfilestatus() A helper method to check (internal) file's status.
protected boolean	debugmode() Check whether debug has been enabled.
protected void	fetch(Date last, Date now) Fetch all tag related changes between [last, now].
List	getModifications(Date last, Date now) Returns a list of modifications detailing all the changes between the last build and now.
Map	getProperties() Returns properties defined by this modification to be passed down to a build engine.
void	setDebug(boolean b) If set to true, then debug messages will be sent to the log stream using level info for this particular element.
void	setFile(File file) The file to be parsed.
void	setProject(String project) The name of the project to watch for tag related action.
void	setPropertyOnDelete(String propertyOnDelete) Name of property to define if a deletion is detected.
void	setStem(String stem) Set the stem to be used as prefix for properties passed to CruiseControl.
void	setTagaction(String s) Use this method to trigger a build if the tag operation matches a given regular expression.
void	setTagvalue(String re) Use this method to filter specific tag values.
void	validate() Called once CruiseControl whenever the underlying configuration got changed or when starting up CruiseControl.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

debug

protected boolean debug

A flag to enable individual debugging. See also setDebug(boolean).

properties

protected Hashtable properties

A hash table for all those properties to be passed down to the build engine, see also getProperties().

file

protected File file

The file to read and parse tag related actions from, see also setFile(File).

stem

protected String stem

The prefix to use for naming properties, see also setStem(String).

parser

protected Parser parser

The parser to use for parsing tag related actions from.

mods

public List mods

The list of modifications, see also getModifications(Date, Date)

Constructor Detail

Plugin

public Plugin()

Method Detail

setFile

public void setFile(File file)

The file to be parsed.

This file is expected to contain tag related events in a well defined format. For further information on this format, see class Parser.

If the argument is null, a default value will be used (see validate() for a table of default values.

The file specified does not need to exist prior to starting up CruiseControl. A warning message will be logged however, if CruiseControl calls getModifications(Date, Date) and the file does not exist or is otherwise not accessible.

setDebug

public void setDebug(boolean b)

If set to true, then debug messages will be sent to the log stream using level info for this particular element. This may help to debug this particular element.

setProject

public void setProject(String project)

The name of the project to watch for tag related action. When using CVS, the string to be used here is the repository and not the module name. If the project is either null or empty, the default value will be used.

setTagvalue

public void setTagvalue(String re)

Use this method to filter specific tag values.

By default, every tag value is taken into account. However, not every tag value indicates a release, a version or, in general, something that should trigger a project build.

Therefore a regular expression can be set to filter interesting tag values while ignoring others. When a tag value is ignored, no build is triggered. For example, assume that the convention exists, that tags starting with either r- or v- indicate a version or release while other values are used to preserve the current project's state. You would then use the regular expression (?:r|v)-.*? as filter to trigger a version or release build.

When grouping, care must be taken. In the example above, (r|v)-.*? would match exactly the same text. The problem is that using capturing groups will break the underlying algorithm. You are therefore asked to use non capturing groups.

For performance reasons, it is wise to use non greedy quantifiers. So instead of using .* (to match everything), you would use .*? instead.

For details on regular expressions see Pattern and see also Mastering Regular Expressions, an outstanding good book on this subject by Jeffrey Friedl.

If the value given is null or empty, a default value is being used.

setTagaction

public void setTagaction(String s)

Use this method to trigger a build if the tag operation matches a given regular expression.

By default, add tag operations are processed. Other operations like mov and del are ignored.

See also setTagvalue(String) for further details on using regular expressions.

If the value given is null or empty, a default value is being used.

setPropertyOnDelete

public void setPropertyOnDelete(String propertyOnDelete)

Name of property to define if a deletion is detected. The property should be added to the set of properties returned by the getProperties() call.

This is an (unsupported) interface method.

Parameters:

propertyOnDelete - (not used)

setStem

public void setStem(String stem)

Set the stem to be used as prefix for properties passed to CruiseControl. The communication between this source control element and the actual builder element is implemented in CruiseControl via properties. Once a modification has been detected, CruiseControl calls method getProperties(). Each property k found therein is then passed to the builder like -Dk=v. This element passes a couple of properties. Rather than using fixed named properties, each property will be prefixed with a stem. By default, this prefix is tagmod.. The properties passed are: tagmod.act = mov | add | del tagmod.val = the tag value used (like v-1_0) tagmod.user = the user which tagged (if known) tagmod.date = the time string It is possible to pass an empty string as stem.

getProperties

public Map getProperties()

Returns properties defined by this modification to be passed down to a build engine.

The following properties are defined and set by this plug-in:

Property	Value
stemtag	tag value
stemtagdate	date (D) field
stemtaguser	user (U) field
stemtagop	operation (o) field

The stem is a prefix that can be set via attribute stem to make properties unique.

Specified by:

getProperties in interface SourceControl

Returns:

never null

debugmode

protected boolean debugmode()

Check whether debug has been enabled.

checkfilestatus

protected void checkfilestatus()

A helper method to check (internal) file's status. A helper method to log the status of the file being parsed. This method is intended to be called if an IO exception has been raised. Then often a improved error message is helpful.

fetch

protected void fetch(Date last,
                     Date now)
              throws Exception

Fetch all tag related changes between [last, now].

The behavior is undefined, if last is newer than now.

Throws:

Exception

validate

public void validate()
              throws CruiseControlException

Called once CruiseControl whenever the underlying configuration got changed or when starting up CruiseControl.

Rather than throwing an exception, this implementation provides a default value for every property. Whether chosen default values are useful is a different story. If a default value is chosen, a warning message is once logged.

The following default values are used:

Method	plugin's attribute name	value
setFile(File)	file	tag.log
setStem(String)	stem	tagmod.
setTagaction(String)	tagaction	add
setTagvalue(String)	tagvalue	.*?
setProject(String)	project	foo/bar

Specified by:

validate in interface SourceControl

Throws:

CruiseControlException - in case the underlying parser can not be properly configured. This is most likely the case if the combined regular expression is not valid.

getModifications

public List getModifications(Date last,
                             Date now)

Returns a list of modifications detailing all the changes between the last build and now. This method is regularly invoked by CruiseControl during the build loop.

Specified by:

getModifications in interface SourceControl

Parameters:

last - last build time

now - current date

Returns:

never null