Xslt

The XSLT component allows user to configure source and target document structures using Fiorano Mapper and create an XSL used for transforming documents. Alternatively, it allows users to define XSL created using external tools. Documents passed to the component are transformed using the XSL defined.

Configuration and Testing

Component Configuration

The Component Configuration for XSLT is defined in the Configuration Property Sheet panel as shown in Figure 1.

Attributes

Validate Input

Please refer to the respective section Common Configurations page for information.

Error handling configuration

The remedial actions to be taken when a particular error occurs can be configured here.

Click on the ellipsis button against the Error Handling Configuration property to configure Error Handling properties.

Please refer to the following subsections under Error Handling section in Common Configurations page for more details.

• JMS Error
• Response Generation Error
• Request Processing Error
• Invalid Request Error

The remedial actions to be taken when a particular error occurs can be configured in Response Generator Error section.

The default actions configured are:

• Log to Error logs
• Send to error port

Use Mapper to define transformation

This property determines the means of defining XSL that will be used for transformation.

Fiorano Mapper can be used to define transformation if this property is enabled.

• If enabled, another property called Mappings will be visible and the property XSL is made expert.

• If disabled:
  • Mappings property will not be visible and property XSL is visible as a normal property. Fiorano Mapper cannot be used to define transformation and XSL for transformation has to be manually provided.
  • Removes value defined for Mappings property.

Any mappings previously defined using Fiorano Mapper will have to be redone. However, the XSL(s) computed from mappings and set against properties XSL and JMS-Message XSL will still be present and can be used for transformation.

• Enabling it back (selecting the checkbox after clearing it) will not restore the value of Mappings property.
• Enabling it back removes values from properties XSL and JMS-Message XSL, and thereby XSL(s) have to be redefined.

Expert Properties

Mappings

The property defines the Fiorano Mapper project (contents of .tmf file) that can be created using Fiorano Mapper. XSL required for transformation is created automatically based on the mappings defined in Fiorano Mapper. Click the ellipsis 

Every time the Fiorano Mapper is closed after saving the mappings defined, XSL(s) computed using the mappings defined are set against the properties XSL and JMS-Message XSL. Any previously set XSL (s) content against these properties will be overwritten.

Loading Input and Output Structures in Fiorano Mapper

• A maximum of two structures can be loaded in the Input Structures panel of Fiorano Mapper: Application Context of the Event Process, structure of the XML instance present in the body of input message or both. The Application Context, if loaded, will always be the first structure.
• A maximum of two structures can be loaded in the Output Structures panel of Fiorano Mapper.
  • First structure describes output XML instance which is the result of transformation: Application Context of the Event Process or the structure of the XML instance present in the body of input message

  • Second structure is the JMS-Message structure available from the Import Structure From.. option.

    

    Any other structure than the JMS Message structure will result in erroneous behavior at the component's runtime.

• When the Fiorano Mapper is launched, input structures are loaded as described below:
  
  • If the component is already configured, previously configured structures will be loaded in Input Structures panel.
    
    • If the Input Structure has an application context, and if the application context schema for the Event Process is modified after the previous configuration, the new structure is loaded.
    • If the Input Structure has an input message structure, the modified structure is retained even if the structure defined on the output port of the component connected to the input port of this component is changed.
  • If the component was not previously configured, the application context structure defined in the Event Process or default application context structure (<!ELEMENT Context (#PCDATA)>), if no structure is defined, will be loaded as the first structure. One of the structures on other components' output port which is connected to this component's input port is loaded as the second structure. If the component's input port is not connected to any other component's output port which has a structure, the second structure will not be loaded automatically. A Structure can be loaded manually by typing-in or copying the structure from the file system.
    
    
• When the Fiorano Mapper is launched, output structures are loaded as described below:
  • If the component is already configured, previously configured structures will be loaded in Output Structures panel.
    • If the Output Structure has Application Context, and if the application context schema for the Event Process is modified after the previous configuration, the new Structure is loaded.
    • If the Output Structure has output message structure, the modified structure is retained even if the structure defined on the input port of component connected to output port of this component is changed.
    • If the JMS Message structure is loaded during previous configuration, then it will be loaded as the second structure.

  • If the component was not previously configured, one of the structures on other component's input port which is connected to this component's output port is loaded as the only structure. If the component's output port is not connected to any other component's input port which has a structure, the Output Structure will be empty. A structure can be loaded manually by typing in or by copying the structure from the file system. Application Context can be loaded to the Output Structures panel by using the Import Structure From.. button and selecting Application-Context option.

    

    Only one of the application context or output message structure can be loaded to the Output Structures panel in a given mapping.

• When the structure of the connected component's input port or output is changed but the previously configured structure is restored, to update the structure right-click the structure that should be changed and click on Update with imported structure... and select IN_PORT or OUT_PORT respectively.

  

  When the structure is changed, mappings for nodes that are not at the same Xpath location before and after the change will be discarded.

• When the Fiorano Mapper is closed, structures defined for the message body, if any, in Input Structure or Output Structure will be set on the input port or the output port of the component respectively.

XSL

When the Use Mapper to define transformation property is

• Enabled: XSL value will be automatically populated after defining mappings in the Fiorano Mapper.
• Disabled: XSL needs to be manually provided here.

• If the XSL has an Input structure and an Application Context, the XML instance of the application context is treated as a primary source. Elements in primary source can be referenced directly in XSL, whereas elements of other structures should be referenced as document (<StructureName>)/<ElementName>.
   
• If the XSL contains any custom Java functions or uses any custom Java funclets, then jar files with the classes related to these functions should be added as resources to the XSLT component.
  • To add jar files, follow the same steps as mentioned in the Adding Resources to a Microservice section.

JMS-Message XSL

This property defines the XSL that will be used to transform source data from Input Structures to required interim XML which defines JMS message properties and text that has to be set. The component parses this interim XML and sets the required JMS properties and their values on the output message.

When the Use Mapper to define transformation property is

• Enabled: JMS-MEssage XSL value will be automatically populated after defining mappings in the Fiorano Mapper.
• Disabled: XSL which generates XML corresponding to the structure shown in Figure 4 should be manually provided here.

JMS properties can be set alternatively using JMS Message Functions in Funclet tab of Fiorano Mapper.

Defining JMS-Message XSL using Fiorano Mapper

To define JMS-Message XML using Fiorano Mapper, perform the following actions:

1. Define the first output structure which represents the structure of the message body or application context that has to be set on the output message.
2. Click the Import Structure From.. button and choose JMS-Message option as shown in the figure below.
   
   

   

   
   Figure 5: Loading JMS-Message structure on output
   
   An output structure JMS-Message is added in the Output Structure as shown in figure 6.
   
   

   

   
   Figure 6: JMS-Message Structure loaded on output
   
   

3. For the property that has to be set on the output message, the name and type of the property should be mapped to the attribute name and type respectively. The value of the property should be mapped to the element Property. Figures 6 shows the mappings for name, type, and Property respectively.

   

   type can values Byte, Short, Integer, Long, Float, Double, Boolean. Any other value defined for type is treated as String type.

   
   

   

   
   Figure 7: Mappings for defining a String property with name "FileName" and value "samplefile.txt"
   
   

4. Multiple properties can be added by duplicating the element Property.
   
   

   

   Figure 8: Duplicating Property node
   
   

5. To set the content of message body on the output message, required content should be mapped to Text as shown in figure 9.
   
   

   

   
   Figure 9: Setting message body
   

   When content is mapped to Text element of JMS-Message structure and the structure of the output message body XML is loaded in the mapping, content mapped to Text element of JMS-Message structure takes precedence of result of transformation and the body of output message contains content mapped to Text element of JMS-Message structure.

Xslt Engine

Specify the transformer implementation that is used for performing the transformation. Xalan (2.7.0) and Saxon (8.4) transformer implementations along with "Other" for custom class are bundled with Fiorano environment for performing transformations:

• Xalan
  Xalan implementation (org.apache.xalan.processor.TransformerFactoryImpl) is used to perform transformation.

  

  Xalan(2.7.0) does not support XSLT 2.0

• Saxon
  Saxon implementation (net.sf.saxon.TransformerFactoryImpl) is used to perform transformation.

  

  Saxon implementation does not support custom functions

• Other
  This option should be used when a custom transformer implementation has to be used. When this option is selected, the Transformer factory class property will be displayed where the custom transformation factory implementation can be provided.

Transformer factory class

This property determines the fully qualified name of the class that should be used to perform transformation when the transformer implementation other than Saxon or Xalan provided by Xslt Engine has to be used.

• This property appears only when the Xslt Engine property is chosen as 'Other'.
• The class provided should be an implementation of javax.xml.transform.TransformerFactory.

Resources (jar files) containing the java class specified against this property should be added as resources to the XSLT component.

Strip White Spaces

This property determines whether elements in input XML that have only whitespace content should be stripped of the content unconditionally before the transformation is done.

This property works only with Saxon

• None
  Attribute to strip whitespace is not set at all. The behavior will be dependent on the transformer's implementation. For Saxon implementation shipped with Fiorano, the behavior is the same as that of False

• True
  Whitespace content is stripped from input XML before the transformation is done

• False
  Whitespace content is retained as it is.

Example: Figure 10 shows a sample transformation defined.

Xslt Engine is chosen as Saxon and Strip White Spaces property is set to True as shown in figure 11. Input XML in figure 12 contains Title element which has whitespace.

Fail transformation on error

This property determines how the problems that occur during the transformation have to be handled. There are three levels of problems that can occur during the transformation. Warnings, errors and fatal errors

• Enabled
  • Transformer warnings are only logged at log level WARNING
  • Transformer errors are only logged at log level WARNING
  • Transformer fatal errors are reported as errors in component
• Disabled
  • Transformer warnings are logged at level WARNING and are also treated as errors in component if Throw fault on warnings remedial action is enabled under Request Processing Error in Error Handling (figure 2)
  • Transformer errors are reported as errors in component and remedial actions, if any, defined in Error Handling panel are taken.
  • Transformer fatal error are reported as errors in component

Optimization

This property determines whether some internal structures can be cleared so as to make some additional memory available for transformation.
When property Set transformation result as is set to Body, message body is cleared from input message after message body is loaded into input for transformer and before transformation begins. In this case, Text-Content and Byte-Content functions of JMS Message functions in Fiorano mapper (shown in the figure below) cannot be used.

When property Set transformation result as is set to Context, content in application context is cleared from input message after content in application context is loaded into input for transformer and before transformation begins.

This property will come into effect only when there is no JMS-Message XSL defined.

Enable Thread Pool

If enabled, component processes multiple messages at once in a single session and sends the responses in batches.

When Thread Pool is used, the input port property "Number of Sessions" has to be set to '1', else the sequence of the component will be unpredictable.

Pool Size

Number of parallel request processors that are created by the component instance to process messages received on the input port. Messages are processed in a separate thread. This property is used to increase the number of threads that can process the requests and thereby increase the through put.

The property needs to be tuned incrementally. Starting with 2, the number can be increased till the required throughput is achieved. Beyond a certain number, the performance increase might not be significant due to synchronization of more number of threads.

Batch Eviction Interval (in ms)

Time interval in milliseconds after which responses are sent.

Functional Demonstration

Scenario 1

The scenario demonstrates a simple XSLT mapping. In this mapping,

• The String Hello is appended before the Name in the Input message
• Element Message is mapped to Message
• Email is ignored
• The response is sent to the output port.

Configure the XSLT component as described in Configuration and Testing section and use feeder and display component to send sample input and check the response respectively.

Use Case Scenario

In EAI Demo sample, XSLT is used in extracting the Email ID, Order ID from the input XML and some mappings are defined between them with the POP3 schema elements and to construct the message body.

The event process demonstrating this scenario is bundled with the installer.
Documentation of the scenario and instructions to run the flow can be found in the Help tab of flow present in the eStudio tool.

Useful Tips

• Suitable JDBC drivers required for Lookup functions have to be added as Service Dependencies or as Resources to XSLTFunctions System Lib. Refer Adding Resources to a Microservice section for directions to perform this.

• To understand the service better, refer the DB Replication example which demonstrates XSLT service features.
• Also refer Adding User XSLT to understand how to customize a generated XSLT code.