About CAS annotations

The CAS Extension API provides Java annotations that define extensions to the Content Acquisition System and also define configuration properties for an extension. Annotations can describe whether configuration properties are required or optional, whether they have a default value, and their display properties in CAS Console.

An extension requires an annotation of either @CasDataSource or @CasManipulator to indicate whether the extension is a data source or a manipulator.

After a CAS application developer installs a plug-in, the Content Acquisition System scans for extensions by checking for classes that have an annotation of either @CasDataSource or @CasManipulator and by checking the uniqueness of extension IDs.

Here is an example annotation that defines a data source extension: 

@CasDataSource(displayName="CSV File", description="Reads comma separated files")
public class CsvDataSource extends DataSource<CsvDataSourceConfig>

Here is an example annotation that defines a manipulator extension: 

@CasManipulator(
		supportsIncrementals=true, 
		deleteRecordsBypassManipulator = true,
		displayName="Substring Manipulator", 
		description="Generates a new property that is a substring of another property value")
public class SubstringManipulator extends Manipulator<SubstringManipulatorConfig>

You annotate a Java field in a PipelineComponentConfiguration class to expose the field as a configuration property for an extension. The fields that you annotate display in CAS Console and are available to the CAS Server Command-line Utility and the CAS Server API. If you do not annotate a field, CAS Server ignores it.

CAS Console renders all annotated Java fields as configuration properties on the Data Source tab. When a user specifies values for the fields in CAS Console, and saves the data source, then CAS Console sends the value of the field to CAS Server as a configuration property.

Each Java field has a CAS annotation that corresponds to the data type of the Java field. Field annotations include the following:

Annotations contain attributes that specify additional information about a configuration property. This information may control rendering in CAS Console, the order in which fields render, default values for the fields, and so on.

Here is an example annotation of two string fields: 

@StringProperty(isRequired=true, name="inputFile", displayName="Input File", 
 description="Path to the input csv file e.g. c:\\incoming\\data.csv")
	private String mInputFile;
	
@StringProperty(isRequired=true, name="keyColumn", displayName="Key Column", 
	description="Name of the column with the record key")
	private String mKeyColumn;

When CAS Console renders the mInputFile property and the mKeyColumn property, they display as the Input File and Key Column configuration properties shown here:

Here is an example annotation for a field which is a list of strings (a multi-valued property): 

@StringProperty(isRequired=true, name="sourcePropertyList", displayName="Source Property List")
	private List<String> mSourcePropertyList;

Here is an example annotation for an integer field with four attributes: 

@IntegerProperty(isRequired=false, name="startIndex", displayName="Substring Start Index", 
			description="Substring start index (zero based)", defaultValue=0)
	private int mStartIndex;

A group organizes fields for display as configuration properties in CAS Console. You can annotate an extension to organize a set of fields into a group and specify the order of fields in a group.

The @ConfigurationGroup annotation specifies that the fields contained within it are a group from the perspective of CAS Console and from the CAS Server Command-line Utility.

The groupName attribute of @ConfigurationGroup specifies the label for the group, and the propertyOrder attribute specifies the order in which the properties display in CAS Console and display as output from tasks in CAS Server Command-line Utility. If you omit the propertyOrder attribute, the properties are sorted alphabetically and display alphabetically.

Here is an example group named User Credentials that defines three configuration properties: 

@ConfigurationGroup(groupName="User Credentials", propertyOrder={"userName","userPassword"})

You can annotate an extension to specify the order of multiple groups of fields. As mentioned above, you specify each group with a @ConfigurationGroup annotation. You specify the order of multiple groups with a @ConfigurationGroupOrder annotation.

This may be useful if you want to enforce the order of groups and order of the fields within each group. For example, suppose a data source extension accesses a database. The first group is called User Credentials and it displays a userName property and a userPassword property.

Next you want a second group of fields called Database Settings, and it displays serverName, databasePath, and portNumber.

Last you want a third group called Advanced Settings, and it displays settingA, settingB, and settingC.

This scenario requires the following annotations: 

@ConfigurationGroupOrder({
     @ConfigurationGroup(groupName="User Credentials", propertyOrder={
       "userName","userPassword"}) 
     @ConfigurationGroup(groupName="Database settings", propertyOrder={
       "serverName","databasePath","portNumber"}) 
     @ConfigurationGroup(groupName="Advanced Settings", propertyOrder={
       "settingA","settingB","settingC"})})

Copyright © Legal Notices