7 Customizing DSA Maps with Java Add-Ins and Algorithms

There are three types of customizations that can be done in a DSA and Transform Map (TMap).

TMap Algorithms (The easiest to use)
TMap Add-in Transforms
DSA Add-in Output Adapters

The TMap Algorithms are the easiest to use and require no special work outside of the Application Studio. The Java code is written directly in the Transform Map Builder in Application Studio and can be tested and run from here. The limitation is that all the Java code needs to be part of the single transform method.

This Java code can contain entire packages of classes and needs to be written in an external Java API and imported into the Oracle DataLens Server.

TMap Algorithms

The following sections describe how to use the TMap Algorithms.

Initial Configuration

Java TMap Algorithms, allow Java code to be embedded into Transform Maps and have the code be executed when the parent DSA is run. The Oracle DataLens Client and Server software is configured ready-to-use to support this with no configuration changes needed.

Client Startup Changes

The Algorithm widget is available in the Process Control folder in the Graphical DSA Builder pane. See Oracle Enterprise Data Quality for Product Data Application Studio Reference Guide.

Creating a New TMap Algorithm

Drag the Algorithm widget into your Transform Map.

Notes on the Algorithm Java method:

The name of the Algorithm can be any valid Java Class name, but the method needs to be declared as public String transform.
The method may contain one or more string parameters. In the previous example, the method is taking two string parameters.

Next, name and create a new algorithm object with your algorithm. In this example, the template Java code was modified to divide two numbers and tested as in the following:

Click OK to save the new custom Algorithm. The Transform Map looks like the following:

The new Custom Algorithm is ready to check-in and deploy to the Oracle DataLens Server and start using in the client applications.

Transform Map Add-In Transforms

Java Transform Map Add-in Transforms allow user-defined widgets to be available for use in DSAs.

For additional information on these classes, see the file, Add2Int.java .

Writing a TMap Add-In Transform

The class may be in any Java package of your choosing.

The class name may be any valid Java Class name.

In the following example, you are using a Transform Map Add-in Transform class that is shipped with the Oracle DataLens Server installation called GetField.

The class must implement a constructor with a single string argument (the name).

public GetField(String name) {
    super(name);
}

The class must implement a method called getResults as follows:

/**
* This is the main method called by the Add-In Transform server code.
     *
     * @param linesOfInputData is an Array of data for each line being
    * processed,
     * where the data is an array of the inputs to a single computation.
     *
     * @param parameters are the input parameters for this TMap Add-in function.
     *
     * @return XfmInfo[] of the results of the transformation, one element
     * for each line of input data.
     */
  public XfmInfo[] getResults(String[][] linesOfInputData,
                                                  Map<String, String> fixedParameters) {
        int inputLength = linesOfInputData.length;
        XfmInfo[] results = new XfmInfo[inputLength];
         // Get the parameters here…
        // Processing happens here…
        return results;
    }

linesOfInputData parameter - An array of arrays of Strings. The 1-D level array has one element for each line of input that must be processed. Each element of the 1-D array has a 2-D String[] containing the column data needed for the transformation. Thus the array looks like:

String[numberOfLines][numberOfColumnsOfInputData]
fixedParameters - These are the parameters to this add-in transform, passed in from the DSA.
Return an XfmInfo[] of the results of the transformation, one element for each line of input data.

Defining the Transform Map Add-In Transform

In the Application Studio, the add-in classes will be toggled on if the system finds the AddInClasses.xml file in the shared config directory on the Oracle DataLens Server.

Server

The class needs to be added to the AddInClasses.xml file, in the C:\Oracle\Middleware\user_projects\domains\dls_domain\opdq\config, directory, as follows:

<AddInClasses>
<Transforms>
      <class>
         <name>Get Field</name>
            <className>com.onerealm.solx.maps.xfm.code.transform.GetField</className>
            <description>Gets the specified field from a string.  The field index,
            field separator, and default value are specified in the fixed parameters.</description>
      </class>
   </Transforms>
</AddInClasses>

Defining the Input Parameters to the Transform Map Add-In Transform

This step can be skipped if the Transform Map Add-in transform does not use any initialization parameters.

The parameters to the new Transform Map add-in transform need to be added to the AddInTramsformParameters.xml configuration file. This file is located in the same configuration directory as the AddInClasses.xml. In this case, our GetField add-in takes three parameters and the AddInTransformParameters.xml file will look like similar to the following:

<TransformParameters>
<AddIn>
        <name>Get Field</name>
        <parameters>
            <parameter>
                <name>separator</name>
                <default>|</default>
                <desc>Separator for splitting string into fields</desc>
                <editable>true</editable>
            </parameter>
            <parameter>
                <name>index</name>
                <default>0</default>
                <desc>Index of field to extract (1-based)</desc>
                <editable>true</editable>
            </parameter>
            <parameter>
                <name>default</name>
                <default></default>
                <desc>Default value to return if field not found</desc>
                <editable>true</editable>
            </parameter>
        </parameters>
    </AddIn>
</TransformParameters>

Using the Transform Map Add-In Transform in the Client

No changes are need for the client configuration to pick up your new Tmap Add-In Transformation. The Oracle DataLens Server just needs to be restarted whenever the CustomClasses.xml file is updated (because the server reads this file on startup).

Note:

You will be able to add the new Tmap Add-in to your DSA map, but this cannot be tested on the client, it can only be tested by running a job on the server.

Start the Application Studio. The new add-in class is available in the Transform Map as follows:

Surrounding text describes getfield1.png.

Drag the Get Field widget into the Transform Map, then click the Parameters tab so that the parameters are displayed for you to edit as follows:

Surrounding text describes getfield2.png.

Using TMap Add-in Transforms to Process Exception Data

The individual Tmaps that comprise the complete DSA, have a limitation in that the same number of records input to the Tmap must be output from the Tmap. If the Tmap is processing data and some of the records cannot be processed, then these individual records must be flagged as exception records and routed in the DSA for separate processing.

You can flag exception records to be processed separately using the XfmError class as in the following example:

if (returnUnmatchedRows) {
   // This is a good row of data
   finalResults[i] = new XfmData(classification.getId()+"|0|||||", 0);
} else {
   // Return a line failure (exception)  for this line
   finalResults[i] = new XfmError("unknownMap", getName(), "No Match");
}

The XfmError constructor uses the following three parameters that are all string values:

mapName: The name of the DSA.
xfmName: The name of the Tmap transform.
errorMsg: The error message associated with the line of data.

DSA Add-In Output Adapters

Java DSA Add-in Output Adapters can write data out in any user-defined format. Since this is an output step, there is no routing of data past this step in the DSA Map, so this should be used only by Java code that will not be throwing any exceptions that need to be trapped and processed by the DSA Map.

Writing a DSA Add-In Output Adapters

The class may be in any Java package of your choosing.

The class name may be any valid Java Class name.

In the following example, you are using a Transform Map add-in transform class that is shipped with the Oracle DataLens Server installation called SCS XML.

The main method that is called is writeOutput. This returns a WfgCustomOutputReturn object, which contains information needed to forward the result data to an email address or an FTP site. If this returns null, then there will be no email or FTP.

Note:

Even if this object is returned, the email and FTP is only sent if it is defined in the DSA or the DSA job has defined email or FTP output.

Following is an example of the structure of the Output Adapter Class:

package com.onerealm.solx.maps.wfg.code.output;
    /**
     * @param job  PMap job information
     * @param data Wfg Job data
     * @param outputDir The directory to write the xml file
     * @param parameters The input parameters to the Add-in Output Adapters.
     * @return Custom output
     * @throws SaException Superclass for all SCS exceptions
     * @throws IOException Signals that an I/O exception of some sort has occurred
     */
public WfgCustomOutputReturn writeOutput(WfgJob job, WfgInputData data, String outputDir,
                                             Map<String, String> parameters)    {
        List<WfgDataLine> lines;
        while ((lines = 
data.getNextGoodLines(WfgConstants.MAX_MEMORY_LINES)) != null) {
            for (WfgDataLine line : lines) {
                System.out.println(line.getData());
            }
        }
        return null;
    }

Defining the DSA Add-In Output Adapter

In the Application Studio, the add-in classes will be toggled on if the system finds the AddInClasses.xml file in the shared/config directory on the Oracle DataLens Server.

Server

The class needs to be added to the AddInClasses.xml file as follows:

<AddInClasses>
   <Outputs>
        <class>
            <name>SCS XML</name>
             <className>com.onerealm.solx.maps.wfg.code.output.scspim.ScsStepPimProducts</className>
             <description>This will output a STEP PIM Product XML document 
with SCS processed data; The default file is 
/tmp/ScsStepPimProductData_jobId.xml</description>
        </class>
  </Outputs>
</AddInClasses>

Note:

There is no client file that needs to be updated for use with the Application Studio.

The server file needs to be updated for use running DSAs on the Oracle DataLens Server and to make this available to the Application Studio Clients.

Follow the instructions in the Transform Map Add-in Transforms section for changing the startup scripts and adding the new classes to the classpath.

Defining the Input Parameters to the Transform Map Add-In Transform

This step can be skipped if the Transform Map Add-in transform does not use any initialization parameters. In this example, you are not using any input parameters.

Using the DSA Add-In Output Adapter in the Client

No changes are need for the client configuration to use your new DSA Add-In Output Adapter. The Oracle DataLens Server just needs to be restarted whenever the CustomClasses.xml file is updated (because the server reads this file on startup).

Note:

You will be able to add the new DSA Add-in Output Adapter to your DSA map, but this cannot be tested on the client, it can only be tested by running a job on the server.

Use in the Application Studio

Once all of the steps in the preceding sections are completed, the new DSA Output Adapter is now available for use in the Application Studio as follows: