Working with the Advanced Interface
In the advanced interface, you can use object oriented API methods to define, invoke, and get the result of an expression.
The following table describes the classes and API methods that are available in the advanced interface:
Class or API Method | Description |
|---|
EDataType class | Enumerates the datatypes for an expression. |
JExprParamMetadata class | Contains the metadata for each parameter in an expression. Parameter metadata includes datatype, precision, and scale. |
defineJExpression API method | Defines the expression. Includes expression string and parameters. |
invokeJExpression API method | Invokes an expression. |
JExpression class | Contains the methods to create, invoke, get the metadata and get the expression result, and check the return datatype. |
Invoking an Expression with the Advanced Interface
You can define, invoke, and get the result of an expression by using the advanced interface.
1. On the Helpers or On Input code entry tab, create an instance of JExprParamMetadata class for each argument for the expression and set the value of the metadata. Optionally, you can instantiate the JExprParamMetadata object in the defineJExpression method.
2. Use the defineJExpression method to get the JExpression object for the expression.
3. On the appropriate code entry tab, invoke the expression with the invokeJExpression method.
4. Check the result of the return value with the isResultNull method.
5. You can get the datatype of the return value or the metadata of the return value with the getResultDataType and getResultMetadata methods.
6. Get the result of the expression by using the appropriate API method. You can use the getInt, getDouble, getStringBuffer, and getBytes methods.
Rules and Guidelines for Working with the Advanced Interface
When you work with the advanced interfaces, you must be aware of rules and guidelines.
Use the following rules and guidelines:
- •If you pass a null value as a parameter or if the result of an expression is null, the value is treated as a null indicator. For example, if the result of an expression is null and the return datatype is String, a string is returned with a value of null. You can check the result of an expression by using the isResultNull method.
- •You must convert input parameters with a Date datatype to a String before you can use them in an expression. To use the string in an expression as a Date datatype, use the to_date() function to convert the string to a Date datatype.
You can get the result of an expression that returns a Date datatype as a String or long datatype.
To get the result of an expression that returns a Date datatype as a String datatype, use the getStringBuffer method. To get the result of an expression that returns a Date datatype as a long datatype, use the getLong method.
EDataType Class
Enumerates the Java datatypes used in expressions. Gets the return datatype of an expression or assign the datatype for a parameter in a JExprParamMetadata object. You do not need to instantiate the EDataType class.
The following table lists the enumerated values for Java datatypes in expressions:
Datatype | Enumerated Value |
|---|
INT | 1 |
DOUBLE | 2 |
STRING | 3 |
BYTE_ARRAY | 4 |
DATE_AS_LONG | 5 |
The following example Java code shows how to use the EDataType class to assign a datatype of String to a JExprParamMetadata object:
JExprParamMetadata params[] = new JExprParamMetadata[2];
params[0] = new JExprParamMetadata (
EDataType.STRING, // data type
20, // precision
0 // scale
);
...
JExprParamMetadata Class
Instantiates an object that represents the parameters for an expression and sets the metadata for the parameters.
You use an array of JExprParamMetadata objects as input to the defineJExpression method to set the metadata for the input parameters. You can create a instance of the JExprParamMetadata object on the Functions code entry tab or in defineJExpression.
Use the following syntax:
JExprParamMetadata paramMetadataArray[] = new JExprParamMetadata[numberOfParameters];
paramMetadataArray[0] = new JExprParamMetadata(datatype, precision, scale);
...
paramMetadataArray[numberofParameters - 1] = new JExprParamMetadata(datatype, precision, scale);;
The following table describes the arguments:
Argument | Argument Type | Argument Datatype | Description |
|---|
datatype | Input | EDataType | Datatype of the parameter. |
precision | Input | Integer | Precision of the parameter. |
scale | Input | Integer | Scale of the parameter. |
For example, use the following Java code to instantiate an array of two JExprParamMetadata objects with String datatypes, precision of 20, and scale of 0:
JExprParamMetadata params[] = new JExprParamMetadata[2];
params[0] = new JExprParamMetadata(EDataType.STRING, 20, 0);
params[1] = new JExprParamMetadata(EDataType.STRING, 20, 0);
return defineJExpression(":LKP.LKP_addresslookup(X1,X2)",params);
defineJExpression
Defines an expression, including the expression string and input parameters. Arguments for the defineJExpression method include an array of JExprParamMetadata objects that contains the input parameters and a string value that defines the expression syntax.
Use the following syntax:
defineJExpression(
String expression,
Object[] paramMetadataArray
);
The following table describes the parameters:
Parameter | Type | Datatype | Description |
|---|
expression | Input | String | String that represents the expression. |
paramMetadataArray | Input | Object[] | Array of JExprParaMetadata objects that contain the input parameters for the expression. |
You can add the defineJExpression method to the Java code on any code entry tab except the Imports and Functions tabs.
To use the defineJExpression method, you must instantiate an array of JExprParamMetadata objects that represent the input parameters for the expression. You set the metadata values for the parameters and pass the array as a parameter to the defineJExpression method.
For example, the following Java code creates an expression to look up the value of two strings:
JExprParaMetadata params[] = new JExprParamMetadata[2];
params[0] = new JExprParamMetadata(EDataType.STRING, 20, 0);
params[1] = new JExprParamMetadata(EDataType.STRING, 20, 0);
defineJExpression(":lkp.mylookup(x1,x2)",params);
JExpression Class
Contains methods to create and invoke an expression, return the value of an expression, and check the return datatype.
The following table lists the methods in the JExpression class:
Method Name | Description |
|---|
invoke | Invokes an expression. |
getResultDataType | Returns the datatype of the expression result. |
getResultMetadata | Returns the metadata of the expression result. |
isResultNull | Checks the result value of an expression result. |
getInt | Returns the value of an expression result as an Integer datatype. |
getDouble | Returns the value of an expression result as a Double datatype. |
getStringBuffer | Returns the value of an expression result as a String datatype. |
getBytes | Returns the value of an expression result as a byte[] datatype. |
Advanced Interface Example
You can use the advanced interface to create and invoke a lookup expression in a Java transformation.
The following example Java code shows how to create a function that calls an expression and how to invoke the expression to get the return value. This example passes the values for two input ports with a String datatype, NAME and COMPANY, to the function myLookup. The myLookup function uses a lookup expression to look up the value for the ADDRESS output port.
Use the following Java code on the Helpers tab:
JExpression addressLookup() throws SDKException
{
JExprParamMetadata params[] = new JExprParamMetadata[2];
params[0] = new JExprParamMetadata (
EDataType.STRING, // data type
50, // precision
0 // scale
);
params[1] = new JExprParamMetadata (
EDataType.STRING, // data type
50, // precision
0 // scale
);
return defineJExpression(":LKP.LKP_addresslookup(X1,X2)",params);
}
JExpression lookup = null;
boolean isJExprObjCreated = false;
Use the following Java code on the On Input tab to invoke the expression and return the value of the ADDRESS port:
...
if(!iisJExprObjCreated)
{
lookup = addressLookup();
isJExprObjCreated = true;
}
lookup = addressLookup();
lookup.invoke(new Object [] {NAME,COMPANY}, ERowType.INSERT);
EDataType addressDataType = lookup.getResultDataType();
if(addressDataType == EDataType.STRING)
{
ADDRESS = (lookup.getStringBuffer()).toString();
} else {
logError("Expression result datatype is incorrect.");
}
...