Introduction

The pulse™ plugin framework has built in management for plugin configuration. The plugin author needs only to provide plain Java classes that declare the configuration required, annotated with metadata, and pulse™ takes care of the rest. This page describes how to define such classes.

Defining Configuration Classes

All configuration classes must implement the [Configuration] interface. Usually this is done by extending the [AbstractConfiguration] class, which provides a simple implementation of the interface.

Controlling the Configuration UI

Forms

Each configuration class is mapped to a form in the configuration UI. This form is used to edit the simple properties of the class. More complex properties such as nested configuration objects are presented as child pages. The order that the fields are display in the form is controlled by the @Form annotation.

Collections

Collections of configuration objects are displayed in the configuration UI using tables. Each row in the table corresponds to an element of the collection. To control how a configuration type is displayed in table form, the @Table annotation is used, possibly in combination with an additional formatter class.

Validating the Configuration

There are a number of ways to handle the validation of the configuration.

Annotations

Below is a list of a set of annotations that can be used to indicate that a particular configuration property must confirm to a set of criteria before being considered valid. These annotations are suitable in the context of single properties only.

For example, the following shows the property on the MyConfiguration instance as being required and a valid email address.

public class MyConfiguration extends AbstractConfiguration
{
    @Required @Email
    public String getProperty()
    {
        // ....
    }
}

Validateable Interface

There are times when validation is based on more than one configuration property. In such a case, annotations are not sufficient. Instead, you can directly implement the com.zutubi.validation.Validateable interface and take full control.

/**
 * Base interface implemented by an object that can be validated.
 */
public interface Validateable
{
    /**
     * The implementation of this method carries out the validation processing.
     *
     * @param context in which the validation occurs.  
     */
    void validate(ValidationContext context);
}

public class MyConfiguration implements Validateable
{

    // ... 

    public void validate(ValidationContext context)
    {
        // Here we handle the complex validation rules
    }

}

Configuration Check Handlers

When implementing your own validation rules, it is important to remember that the user is waiting for a response whilst validation is in progress, so validation needs to be quick. However, there are situations where you can not validate data without contacting a remote resource. A classic example of this is where the [svn plugin] validates that it is able to contact the configured svn server.

To support this case, pulse™ provides the ConfigurationCheckHandler. More details for this interface to come.