Creating the Plug-in

Creating the Plug-in Project

A Semarchy plug-in is developed as part of a Plug-in Project, into which you declare extension points for each plug-in contained in this project.

Creating a New Plug-in Project

A plug-in project contains one or more Semarchy plug-ins and can be deployed as a single jar.

To create a new plug-in project:

  1. In Eclipse, select File > New > Others....
  2. In the Wizards filter, enter Plug-in. The list shows the Plug-in Project wizard.
  3. Select the Plug-in Project wizard and then click Next
  4. In the Project Name, enter the name of your project. For example: com.acme.phoneStandardizer. Leave the other fields as is.
  5. Click Next. In the Content page, change the following fields:
  6. Click Next
  7. Un-select the Create a plug-in using one of the templates option.
  8. Click Finish
  9. If asked, click Yes to switch to the development perspective.

Adding the Extensions to the Project

In order to define Semarchy extension points, you need to add these extensions points' types to the project.

To add the Semarchy extension points to the project:

  1. In the plug-in editor, select the Dependencies tab
  2. In the Required Plug-ins, click Add... and then select the com.semarchy.engine.extensionpoint. The extension point is added to the dependencies.
  3. The extension point is added with a minimum version required equal to the version of the plug-in SDK. For example, if you have installed the SDK in version 2.0.4, the minimum server version required is 2.0.4. To make your plug-in compatible with previous minor versions of the server (for example, to install the plug-in on a 2.0.0 server), you must modify this dependency.
    1. Select the extension point in the list and then click the Properties... button.
    2. In the com.semarchy.engine.extensionpoint dialog, edit the Minimum Version field. For example, replace 2.0.6 with 2.0.0 to make this plug-in dependent on any server version after 2.0.0.
    3. Click OK to close the dialog.
  4. Select the Overview tab.
  5. In the Overview tab, click the Extensions hyperlink. The editor switches to the Extensions tab.
  6. In the Extensions tab, click Add..., and select the extension point corresponding to the type of plug-in that you want to deliver in this project:
  7. Repeat the previous step to add both types of extensions if you want to mix enrichers and validations in your project.

Defining the Plug-in

A project can contain several Semarchy plug-ins (for example, a plug-in to enrich telephone numbers, and another one to validate email addresses). Each plug-in is declared as an extension endpoint of the rowTransformer or rowValidator endpoint type.

An extension endpoint is declared with all the plug-in metadata: The name, version, provider, as well as the parameters, input and output fields definition.

Declaring an Extension EndPoint

Note: For the rest of this book, we will focus on creating an Enricher (Row Transformer). Validation plug-in follow the same development path.

To create an extension endpoint:

  1. Right-click the com.semarchy.integration.extensions.rowTransformer extension that you just added, right-click and select New > Row Transformer.
  2. In the Extension Element Details section, enter the following values:
  3. Click the Class link.
  4. In the New Java Class wizard, enter the following:
  5. Click Finish. The code editor for your class opens.

Declaring the Parameters and Input/Output Fields

Declaring the Parameters

Parameters allow customizing the behavior of the plug-in.

To declare the plug-in parameters:

  1. In the plug-in editor, select the Extensions tab
  2. Select the parameters node under your Extension Point, right-click and select New > param.
  3. In the Extension Element Details section, enter the following values:
  4. Repeat the two previous steps to add more parameters.

Declaring the Input Fields

Input fields are the values received by an enricher or validation plug-in.

To declare the plug-in input fields:

  1. In the plug-in editor, select the Extensions tab
  2. Select the inputFields node under your Extension Point, right-click and select New > field.
  3. In the Extension Element Details section, enter the following values:
  4. Repeat the two previous steps to add more input fields.

Declaring the Output Fields

Output fields are the values returned by an enricher plug-in.

To declare the plug-in output fields:

  1. In the plug-in editor, select the Extensions tab
  2. Select the outputFields node under your Extension Point, right-click and select New > field.
  3. In the Extension Element Details section, enter the following values:
  4. Repeat the two previous steps to add more output fields.

Warning: Make sure to use uppercase for the parameter and field names. These names are not visible to the end-users.

Implementing the Plug-in Code

Now that the plug-in is declared, it is possible to implement the specified behavior.

To implement the plug-in code:

  1. Switch to the class editor.
  2. If needed, Use the Eclipse quick fix feature to add the interface methods currently unimplemented in the code.
  3. Implement the required methods for your plug-in:

Tip: The full code of the IntlPhoneStandardizer.java class rowTransformer is provided in Appendix A. You can copy and paste the code from the appendix in the class editor.

The following sections describe the methods implemented in the plug-in code.

SetUp/TearDown Methods

These methods are respectively used to initialize the plug-in – typically by setting the value of the parameters – and to release the resources used by the plug-in.

In this case, the only parameter is NULLIFYONERROR. This parameter’s value is stored in a private Boolean variable called nullifyOnError which is set using the setNullify private method.

  private boolean nullifyOnError;
  ...  	
	@Override
	public void setUp(IRowTransformerSetupInfo pSetupInfo) {
		Map<String, Object> paramList = pSetupInfo.getParameters();
		Object nullifyOnErrorParamValue = paramList.get("NULLIFYONERROR");
		if (nullifyOnErrorParamValue != null)
			setNullify(nullifyOnErrorParamValue.equals("1")); //$NON-NLS-1$
	}

	@Override
	public void tearDown() {

	}
	

Warning: String referring to parameter names should always be in uppercase in the Java code.

Important: The value received for parameters is an object, but is always of String type, regardless of the parameter definition. When implementing the setUp method, make sure to perform the appropriate conversion from the string type.

TransformOneRow/transform Method (Enricher Plug-ins)

TransformOneRow

The transformOneRow method transforms an input data row (IDataRow) into an output data row.

In the example below, the input data row only contains the INPUTPHONE field and the output data row is built only with the STANDARDIZEDPHONE field.
The core of the transformation takes place in the private method normalizePhoneNumber. The code of this method can be reviewed in Appendix A

	public IDataRow transformOneRow(IDataRow pDataRow) {
		// First, create the returned IDataRow.
		DataRow outputDataRow = new DataRow();
		// Make sure to set a null value for each output field in the
		// outputDataRow.
		outputDataRow.setValue("STANDARDIZEDPHONE", null);
		// The transformation is done below. It uses the normalizePhoneNumber
		// method defined in the class.
		if (pDataRow.getValue("INPUTPHONE") != null) {
			outputDataRow.setValue("STANDARDIZEDPHONE",
					normalizePhoneNumber(pDataRow.getValue("INPUTPHONE")
							.toString()));
		}
		return outputDataRow;
	}

Note: It is recommended to set all the field values to null immediately after creating the output IDataRow, to avoid returning partially complete IDataRow as the output. This is done by issuing the following code for each output field outputDataRow.setValue("<output_field_name>", null);.

Warning: String referring to input/output field names should always be in uppercase in the Java code.

Transform (Enricher Plug-ins)

This method enriches a list of data rows by calling TranformOneRow, as shown in the example below.

	@Override
	public List<IDataRow> transform(List<IDataRow> pDataRowsBatch) {
		ArrayList<IDataRow> outputDataRowList = new ArrayList<IDataRow>();
		for (IDataRow inputRow : pDataRowsBatch) {
			outputDataRowList.add(transformOneRow(inputRow));
		}
		return outputDataRowList;
	} 

isValid Method (Validation Plug-ins)

The isValid method is required for a validation plug-in.
This method is similar to the transform method. It takes as an input a list of data rows and returns a list of boolean values indicating whether the input data rows comply with the validation specified in the plug-in. Typically, this method uses an isValidOneRow method that validates a single data row.