Creating a pipeline component configuration class for a manipulator

A manipulator requires a PipelineComponentConfiguration class to describe the extension's configuration, to validate the manipulator's configuration, and to determine whether a full acquisition is required by the manipulator.

1. In the Java project that contains the Manipulator implementation, create a subclass of PipelineComponentConfiguration. For example:

   public class SubstringManipulatorConfig extends PipelineComponentConfiguration<SubstringManipulatorConfig> {
   
   }

2. Add each field that you want available as a configuration property in the manipulator. For example:

   private String mSourceProperty;
   	
   private String mTargetProperty;
   	
   private int mStartIndex;

3. Add an annotation to each field. The annotation type must match the field's data type. See package com.endeca.cas.extension.annotation in the CAS Extension API Reference (Javadoc) to determine which annotations have required attributes and to determine which attributes are appropriate for the field. For example:

   @StringProperty(isRequired=true, name="sourceProperty", displayName="Source Property")
   	private String mSourceProperty;
   	
   	@StringProperty(isRequired=true, name="targetProperty", displayName="Target Property")
   	private String mTargetProperty;
   	
   	@IntegerProperty(isRequired=false, name="startIndex", displayName="Substring Start Index", 
   			description="Substring start index (zero based)", defaultValue="0")
   	private int mStartIndex;

4. If you want to order fields within a single group, add a @ConfigurationGroupOrder annotation to the PipelineComponentConfiguration class and then add a nested @ConfigurationGroup annotation. For example, here is one group of fields that display in order — sourceProperty, targetProperty, length and startIndex:

   @ConfigurationGroupOrder({
   	@ConfigurationGroup(propertyOrder={"sourceProperty", "targetProperty", "length", "startIndex"})
   })
   public class SubstringManipulatorConfig extends PipelineComponentConfiguration<SubstringManipulatorConfig> {
   
   }

5. If you want to order multiple groups of user-interface fields on a tab, add additional @ConfigurationGroup annotations within @ConfigurationGroupOrder for each group of user-interface fields that you want ordered.
6. Optionally, override the default implementation of isFullAcquisitionRequired(). The default implementation determines whether a configuration change should force full acquisition the next time an acquisition is run by comparing the old PipelineComponentConfiguration and the new PipelineComponentConfiguration using the equals() method. The default implementation of the equals() method uses reflection to compare all non-transient fields for equality. You can write code that checks a specific property to determine if a full acquisition is required (rather than check the entire PipelineComponentConfiguration). If you want to force a full acquisition, write code that always returns true.
7. Optionally, override the default implementation of validate(). CAS Server performs data type and constraint validation (constraints may include minValue and maxValue for integer properties). Any code you write in validate() performs additional custom validation. If validation fails, the PipelineComponentConfiguration.validate() method returns a collection ValidationFailure objects.
8. If it is necessary for unit testing or the implementation of the manipulator runtime, you may also need to write getter and setter methods for each field that you added.