Creating the Plug-in | ||
---|---|---|
Previous | Next | |
Setting up the Environment | Testing the Plug-in |
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.
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:
Plug-in
. The list shows the
Plug-in Project wizard.
com.acme.phoneStandardizer
. Leave the other fields as is.
1.0.0
)
Phone Standardizer
)
ACME Corp.
)
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:
com.semarchy.engine.extensionpoint
. The extension point is added to the dependencies.
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.
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:
com.acme.phoneStandardizer.intlPhoneStandardizer
International Phone Standardizer
ACME Corp.
)
com.acme.phonestandardizer
IntlPhoneStandardizer
Parameters allow customizing the behavior of the plug-in.
To declare the plug-in parameters:
NULLIFYONERROR
STRING
Nullify on Error
If set to '1', returns null for a phone number that cannot be processed. Otherwise returns the original phone number.
Input fields are the values received by an enricher or validation plug-in.
To declare the plug-in input fields:
INPUTPHONE
STRING
Input Phone
Phone Number to be standardized
.
Output fields are the values returned by an enricher plug-in.
To declare the plug-in output fields:
STANDARDIZEDPHONE
STRING
Standardized Phone
Standardized Phone Number
.
Warning: Make sure to use uppercase for the parameter and field names. These names are not visible to the end-users.
Now that the plug-in is declared, it is possible to implement the specified behavior.
To implement the plug-in code:
setUp
,
tearDown
and
transform
Methods.
setUp
,
tearDown
and
isValid
Methods.
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.
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.
Enrichers plug-ins enrich a list of data rows by calling
transform
method. This method returns the list of enriched data rows.
In our example, this method simply calls a private method called
transformOneRow
to process one of these data rows.
@Override
public List<IDataRow> transform(List<IDataRow> pDataRowsBatch) {
ArrayList<IDataRow> outputDataRowList = new ArrayList<IDataRow>();
for (IDataRow inputRow : pDataRowsBatch) {
outputDataRowList.add(transformOneRow(inputRow));
}
return outputDataRowList;
}
The
transformOneRow
method transforms an input data row (IDataRow) into an output data row.
pDataRow
variable, and contains the input fields passed to the enricher. You access each field value using the
getValue
method.
setValue
method.
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
private 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.
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
private method that validates a single data row.
Previous | Top | Next |
Setting up the Environment | Testing the Plug-in |