8 Customizing DSA Maps with Java Add-Ins and Algorithms

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

• TMap Algorithms (The easiest to use)

• TMap Add-in Transforms (Usually used by Oracle Consulting Services)

• DSA Add-in Outputters (Usually used by Oracle Consulting Services)

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 Tranform 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.

The TMap Add-in Transforms and DSA Add-in Outputters are really for use by Oracle Consulting Services to create powerful custom widgets for use in the DSAs. 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

Initial Configuration

Java TMap Algorithms, allow Java code to be embedded into Tranform Maps and have the code be executed when the parent DSA is run. The Oracle DataLens Client and Server software is configured "out of the box" to support this with no configuration changes needed.

Client Startup Changes

The Algorithm widget is available in the Process Control Transformation menu in the Tranform Map Builder as follows:

Creating a New TMap Algorithm

Drag the Algorithm object into your Tranform Map as follows:

The following dialog will appear. Name and create a new algorithm object as shown on the left. In this example, we modified the template Java code to divide two numbers as follows:

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.

Test the new code as in the following figure:

Select OK to save the new custom Algorithm. The Tranform 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 your client applications.

TMap Algorithm Debugging

All these Customizations require that the classes directory be part of the Java classpath. This has already been done for you as part of the standard Oracle DataLens Client and Server installations.

Server

If you encounter any problems running the TMap Algorithm on the server, check that the environment variable CATALINA_HOME is set on the Oracle DataLens Server with value C:\Program Files\Apache Software Foundation\Tomcat 5.5.

The classes directory is located in the …/Tomcat/webapps/datalens/WEB-INF/classes directory already and nothing needs to be done.

Client

The script file that starts the Application Studio needs to have the $SOLX_HOME/classes directory added to the classpath as follows:

set CP6=%SOLX_HOME%/classes
set clspath=%CP1%;%CP2%;%CP3%;%CP4%;%CP5%;%CP6%

Note:

This is already done for you in during the Oracle DataLens client software installation.

Transform Map Add-In Transforms

Java Transform Map Add-in Transforms are only created by Oracle Consulting Services.

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, we are using a TMap 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;
    }

1. 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]

2. fixedParameters - These are the parameters to this add-in transform, passed in from the DSA.

3. 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\opdq\data\shared\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:

Drag the Get Field widget into the Transform Map and the parameters are displayed for you to edit as follows:

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 Outputters

Java DSA Add-in Outputters 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 caught and processed by the DSA Map.

Writing a DSA Add-In Outputter

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, we 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 e-mail address or an FTP site. If this returns null, then there will be no e-mail or FTP.

Note:

Even if this object is returned, the e-mail and FTP is only sent if it is defined in the DSA or the DSA job has defined e-mail 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 Outputter.
     * @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 Outputter

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 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, we are not using any input parameters.

Using the DSA Add-In Outputter in the Client

No changes are need for the client configuration to pick up your new DSA Add-In Outputter. 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 Outputter to your DSA map, but this cannot be tested on the client, it can only be tested by running a job on the server.

Now start the Application Studio and the new add-in class will be available in the Transform Map interface s shown below.

Use in the Application Studio

Once the above steps are finished, the new DSA Output Adapter is now available for use in the Application Studio as follows: