com.orchestranetworks.addon.dex.transformation (EBX® Add-ons Version 6.1.4 Java API)

Classes and interfaces to call {addon.label} transformation functions for the import, export and transfer data services.

Creating a transformation function for data transfer, and import and export of XML, Excel, and CSV

As shown below, you must define a custom transformation function before adding it to your TransformationCatalog:

public final class ConvertNumberDefinition implements TransformationDefinition
{
        public String getCode()
        {
                return "TEST";
        }

        public UserMessage getLabel()
        {
                return UserMessage.createInfo("Convert number to string number with new API");
        }

        public UserMessage getDescription()
        {
                return UserMessage.createInfo("Convert number to string number with new API");
        }

        public List<InputDefinition> getInputDefinitions()
        {
                List<InputDefinition> inputDefinitions = new ArrayList<InputDefinition>();
                inputDefinitions.add(
                        new InputDefinition(
                                "Input string",
                                UserMessage.createInfo("Input number has Integer data type."),
                                SchemaTypeName.XS_STRING,
                                false));
                return inputDefinitions;
        }

        public OutputDefinition getOutputDefinition()
        {
                return new OutputDefinition(
                        UserMessage.createInfo("Formats the integer input as a string."),
                        SchemaTypeName.XS_STRING,
                        false);
        }

        public List<ParameterDefinition> getParameterDefinitions()
        {
                return new ArrayList<ParameterDefinition>();
        }

        public Transformation getTransformation(ServiceType serviceType)
        {
                switch (serviceType)
                {
                        case XML_IMPORT:
                        case SPREADSHEET_IMPORT:
                        case CSV_IMPORT:
                                return new ConvertNumberForImport();
                        case XML_EXPORT:
                        case SPREADSHEET_EXPORT:
                        case CSV_EXPORT:
                                return new ConvertNumberForExport();
                        case TRANSFER:
                                return new ConvertNumberForTransfer();
                        default:
                                return null;
                }
        }

        public boolean isBidirectional()
        {
                return false;
        }

        public boolean isAggregation()
        {
                return false;
        }

}

Create the implementation definition.

The following example can be used for importing XML, Excel, and CSV:

public final class ConvertNumberForImport
        implements Transformation<ImportTransformationExecutionContext>
{
        private Locale locale;
        public void setup(TransformationConfigurationContext configurationContext)
                throws DataExchangeException
        {
                if (configurationContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }
                this.locale = configurationContext.getSession().getLocale();
        }

        public Object execute(ImportTransformationExecutionContext executionContext)
                throws DataExchangeException
        {
                if (executionContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }

                Object inputValue = executionContext.getInputValue();
                if (inputValue == null)
                {
                        return null;
                }
                
                SchemaNode schemaNode = null;
                if (EBXField.class.isInstance(executionContext.getTargetField()))
                {
                        EBXField ebxField = (EBXField) executionContext.getTargetField();
                        schemaNode = ebxField.getSchemaNode();

                        if (schemaNode.isComplex())
                        {
                                throw new DataExchangeException(
                                        UserMessage.createError(
                                                schemaNode.getLabel(this.locale)
                                                        + " is a complex type node. The transformation function 'Convert an integer to a string and vice versa' only supports simple type node."));
                        }
                }

                try
                {
                        if (Integer.class.isInstance(inputValue))
                        {
                                return schemaNode.formatToXsString(inputValue);
                        }

                        if (String.class.isInstance(inputValue))
                        {
                                String tmpValue = String.valueOf(inputValue);
                                if (tmpValue == null)
                                {
                                        return null;
                                }
                                return schemaNode.parseXsString(tmpValue);
                        }

                        throw new DataExchangeException(UserMessage.createError("Invalid input data."));
                }
                catch (ClassCastException ex)
                {
                        throw new DataExchangeException(ex);
                }
                catch (ConversionException ex)
                {
                        throw new DataExchangeException(ex);
                }
                catch (Exception ex)
                {
                        throw new DataExchangeException(ex);
                }
        }
}

The following example shows XML, Excel and CSV export:

public final class ConvertNumberForExport
        implements Transformation<ExportTransformationExecutionContext>
{
        private Locale locale;
        public void setup(TransformationConfigurationContext configurationContext)
                throws DataExchangeException
        {
                if (configurationContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }
                this.locale = configurationContext.getSession().getLocale();
        }

        public Object execute(ExportTransformationExecutionContext executionContext)
                throws DataExchangeException
        {
                if (executionContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }

                Object inputValue = executionContext.getInputValue();
                if (inputValue == null)
                {
                        return null;
                }
                
                SchemaNode schemaNode = null;
                if (EBXField.class.isInstance(executionContext.getSourceField()))
                {
                        EBXField ebxField = (EBXField) executionContext.getSourceField();
                        schemaNode = ebxField.getSchemaNode();

                        if (schemaNode.isComplex())
                        {
                                throw new DataExchangeException(
                                        UserMessage.createError(
                                                schemaNode.getLabel(this.locale)
                                                        + " is a complex type node. The transformation function 'Convert an integer to a string and vice versa' only supports simple type node."));
                        }
                }

                try
                {
                        if (Integer.class.isInstance(inputValue))
                        {
                                return schemaNode.formatToXsString(inputValue);
                        }

                        if (String.class.isInstance(inputValue))
                        {
                                String tmpValue = String.valueOf(inputValue);
                                if (tmpValue == null)
                                {
                                        return null;
                                }
                                return schemaNode.parseXsString(tmpValue);
                        }

                        throw new DataExchangeException(UserMessage.createError("Invalid input data."));
                }
                catch (ClassCastException ex)
                {
                        throw new DataExchangeException(ex);
                }
                catch (ConversionException ex)
                {
                        throw new DataExchangeException(ex);
                }
                catch (Exception ex)
                {
                        throw new DataExchangeException(ex);
                }
        }
}

Example of data transfer:

public final class ConvertNumberForTransfer
        implements Transformation<TransferTransformationExecutionContext>
{
        private Locale locale;
        public void setup(TransformationConfigurationContext configurationContext)
                throws DataExchangeException
        {
                if (configurationContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }
                this.locale = configurationContext.getSession().getLocale();
        }

        public Object execute(TransferTransformationExecutionContext executionContext)
                throws DataExchangeException
        {
                if (executionContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }

                Object inputValue = executionContext.getInputValue();
                if (inputValue == null)
                {
                        return null;
                }
                
                SchemaNode schemaNode = null;
                if (EBXField.class.isInstance(executionContext.getSourceField()))
                {
                        EBXField ebxField = executionContext.getSourceField();
                        schemaNode = ebxField.getSchemaNode();

                        if (schemaNode.isComplex())
                        {
                                throw new DataExchangeException(
                                        UserMessage.createError(
                                                schemaNode.getLabel(this.locale)
                                                        + " is a complex type node. The transformation function 'Convert an integer to a string and vice versa' only supports simple type node."));
                        }
                }

                try
                {
                        if (Integer.class.isInstance(inputValue))
                        {
                                return schemaNode.formatToXsString(inputValue);
                        }

                        if (String.class.isInstance(inputValue))
                        {
                                String tmpValue = String.valueOf(inputValue);
                                if (tmpValue == null)
                                {
                                        return null;
                                }
                                return schemaNode.parseXsString(tmpValue);
                        }

                        throw new DataExchangeException(UserMessage.createError("Invalid input data."));
                }
                catch (ClassCastException ex)
                {
                        throw new DataExchangeException(ex);
                }
                catch (ConversionException ex)
                {
                        throw new DataExchangeException(ex);
                }
                catch (Exception ex)
                {
                        throw new DataExchangeException(ex);
                }
        }
}

Register the transformation function with the add-on via the catalog so that it can be used in the configuration:
```
        TransformationCatalog.add(new ConvertNumberDefinition());
```

Creating an aggregation transformation function

To create an aggregation transformation function:

Create the custom aggregation transformation function definition.

public class AggregationDefinitionTest implements TransformationDefinition
{
        public String getCode()
        {
                return "AGGREGATION_DEFINITION_TEST";
        }
        
        public UserMessage getLabel()
        {
                return UserMessage.createInfo("Aggregate of integer numbers");
        }
        
        public UserMessage getDescription()
        {
                return UserMessage.createInfo("The sum of the input integers");
        }
        
        public List<InputDefinition> getInputDefinitions()
        {
                List<InputDefinition> inputDefinitions = new ArrayList<InputDefinition>();
                inputDefinitions.add(new InputDefinition(
                        "Source field values",
                        UserMessage.createInfo("List of input integers to calculate."),
                        SchemaTypeName.XS_INT,
                        true));
                return inputDefinitions;
        }
        
        public OutputDefinition getOutputDefinition()
        {
                return new OutputDefinition(
                        UserMessage.createInfo("The sum of the input integers."),
                        SchemaTypeName.XS_INT,
                        false);
        }

        public List<ParameterDefinition> getParameterDefinitions()
        {
                return new ArrayList<ParameterDefinition>();
        }
        
        public Transformation getTransformation(ServiceType serviceType)
        {
                return new AggregationTransformationTest();
        }
        
        public boolean isBidirectional()
        {
                return false;
        }
        
        public boolean isAggregation()
        {
                return true;
        }
}

Create the implementation definition:

public class AggregationTransformationTest implements AggregationTransformation
{
        private Locale locale;
        public void setup(TransformationConfigurationContext configurationContext)
                throws DataExchangeException
        {
                if (configurationContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }
                this.locale = configurationContext.getSession().getLocale();
        }
        
        public Object execute(AggregationTransformationExecutionContext executionContext)
                        throws DataExchangeException
        {
                if (executionContext == null)
                {
                        throw new DataExchangeException(UserMessage.createError("Context is not initialized."));
                }
                
                if (EBXField.class.isInstance(executionContext.getTargetField()))
                {
                        EBXField ebxField = (EBXField) executionContext.getTargetField();

                        if (ebxField.getSchemaNode().isComplex())
                        {
                                throw new DataExchangeException(
                                        UserMessage.createError(
                                                ebxField.getSchemaNode().getLabel(this.locale)
                                                        + " is a complex type node. The transformation function 'Aggregate of integer numbers' only supports simple type node."));
                        }
                }
        
                List<AggregationTransformationExecutionValue> inputs = executionContext.getInputValues();
                if (inputs == null || inputs.isEmpty())
                {
                        return inputs;
                }
        
                int sumOfInput = 0;
                boolean isEmpty = true;
                for (AggregationTransformationExecutionValue executeValue : inputs)
                {
                        if (executeValue == null)
                        {
                                continue;
                        }
                        if (executeValue.getField() != null)
                        {
                                if (EBXField.class.isInstance(executeValue.getField()))
                                {
                                        EBXField inputEBXField = (EBXField) executeValue.getField();
                                        
                                        if (inputEBXField.getSchemaNode().isComplex())
                                        {
                                                throw new DataExchangeException(
                                                        UserMessage.createError(
                                                                inputEBXField.getSchemaNode().getLabel(this.locale)
                                                                        + " is a complex type node. The transformation function 'Aggregate of integer numbers' only supports simple type node."));
                                        }
                                }
                        }
                        
                        Object input = executeValue.getValue();
                        if(input == null || AddonStringUtils.isEmpty(input.toString()))
                        {
                                continue;
                        }
        
                        if (List.class.isInstance(input))
                        {
                                List<Object> objects = (List<Object>) input;
                                for (Object object : objects)
                                {
                                        if (object == null || AddonStringUtils.isEmpty(object.toString()))
                                        {
                                                continue;
                                        }
                                        sumOfInput += this.sumOfInput(object);
                                        isEmpty = false;
                                }
                                continue;
                        }
                        sumOfInput += this.sumOfInput(input);
                        isEmpty = false;
                }
                
                if(isEmpty)
                {
                        return null;
                }
                return Integer.valueOf(sumOfInput);
        }
        
        private int sumOfInput(Object inputValue) throws DataExchangeException
        {
                if (Integer.class.isInstance(inputValue))
                {
                        return ((Integer) inputValue).intValue();
                }
        
                try
                {
                        return Integer.valueOf((String) inputValue).intValue();
                }
                catch (Exception ex)
                {
                        throw new DataExchangeException(UserMessage.createError("Invalid input data."));
                }
        }
}

Register the aggregation transformation function with the add-on via the catalog so that it will be available to use in the configuration:
```
        TransformationCatalog.add(new AggregationDefinitionTest());
```

Interface Summary
Interface	Description
AggregationTransformation	Provides the method used in an aggregation transformation.
AggregationTransformationExecutionContext<SC extends Field,TC extends Field>	Provides a context for an aggregation transformation when transferring, exporting, or importing data.
ExportTransformationExecutionContext<SC extends Field,TC extends Field>	Provides the transformation context when exporting data.
ImportTransformationExecutionContext<SC extends Field,TC extends Field>	Provides the transformation context when importing data.
TransferTransformationExecutionContext	Provides the context for a transformation when transferring data in EBX®.
Transformation<T extends TransformationExecutionContext>	Provides transformation methods.
TransformationConfigurationContext	Provides configuration attributes for the `Transformation` implementation that executes during import, export, or transfer.
TransformationDefinition	Defines attributes for `Transformation` implementations.
TransformationExecutionContext<SC extends Field,TC extends Field>	Provides the transformation context.

Class Summary
Class	Description
AggregationTransformationExecutionValue	Specifies the configuration used to import data into a file.
InputDefinition	Defines the input data for a `Transformation` class.
OutputDefinition	Defines the output data for a `Transformation` class.
ParameterDefinition	Defines the parameter for a `Transformation` class.
TransformationCatalog	Lists transformations to register.

Package com.orchestranetworks.addon.dex.transformation

Creating a transformation function for data transfer, and import and export of XML, Excel, and CSV

Creating an aggregation transformation function