FeaturesThe XSLT Service-Engine allows to transform Petals messages using XSL style sheets. Each configuration of this component embeds an XSL style sheet. This component only acts as service provider, not as a service consumer. Additional information about XSLT can be found at http://www.w3.org/TR/xslt.
XSLT Component overview
Recommended usage
Taking an exampleLet's take the example of two "white pages" services. First, you want to call the operation lookup of a service "White Pages". Its prototype looks like lookup( String firstName, String familyName ) --> String[] phoneNumbers Do not forget this prototype would be in fact described in the WSDL interface of the service (under an XML shape). Then, you want to call a service that finds a geographical area (e.g. a city) from a phone prefix. Its prototype looks like resolve( int phonePrefix ) --> String areaName Once again, this prototype is described in the WSDL interface of this second service. To chain these calls, you have to transform the output of the operation lookup to match the input of the operation resolve. resolve( lookup( "Pierre", "Paul")); What you will do in your XSL style sheet is extracting the phone prefix from a phone number. There is no more simple way to make the transformation. Obviously, this example is extremely simple. XSLT and chaining servicesFollowing our previous example, it appears that chaining and transforming service calls implies using a chaining service (some could say an orchestration service).
This chaining service can be implemented by a POJO (an home made Java Class) or an Enterprise Integration Pattern (EIP). Limitations and warnings
A XSL transformation service cannot transform messages addressed to another service.
This is due to a bug of Xalan of versions previous than 2.7.1. To bypass it, you have to use a newer version of Xalan (2.7.1 +) or another XSLT engine using a Shared-Library. |
Table of contents
Contributors
No contributors found for: authors on selected page(s)
|
Creating a XSL Transformation service (Provides modes)
Each XSLT service runs on the Petals XSLT component.
The Petals XSLT component has native operations to invoke. These operations are inherited by the XSLT services.
A XSLT service cannot add additional operations. It only has the ones of the XSLT component.
The version 2.5 of the Petals XSLT component exposes two operations.
- transform: the received message is transformed with the XSL style sheet. The transformation result is returned as the response payload.
- transformToMtomAttachment: the received message is transformed with the XSL style sheet. The transformation result is attached to the response in MTOM mode.
The "transform" operation
The fully qualified name of this operation is:
- Name space URI: any URI, provided it is not null (e.g. *http://petals.ow2.org/components/xslt/version-2*)
- Local part: transform
This operation only supports the InOut message exchange pattern (MEP).
When invoking this operation, you must call it using its fully qualified name.
It must also be the operation name in the WSDL of any XSLT service.
Here is the execution flow for this operation:
- The received message is transformed with the XSL style sheet.
- The transformation result is returned as the response payload.
The result of the transformation depends on the XSL style sheet.
If an error occurs during the transformation, then a fault is raised.
<?xml version="1.0" encoding="UTF-8"?> <xsltFault xmlns="the name space of the invoked operation"> <message>An error message</message> <details>A stack trace (optional)</details> </xsltFault>
Don't forget to enable the attachment forward (forward-attachments) when transforming an incoming request containing MTOM reference. |
The "transformToMtomAttachment" operation
The fully qualified name of this operation is:
- Name space URI: any URI, provided it is not null (e.g. *http://petals.ow2.org/components/xslt/version-2*)
- Local part: transformToMtomAttachment
This operation only supports the InOut message exchange pattern (MEP).
When invoking this operation, you must call it using its fully qualified name.
This operation cannot be described in a WSDL, because of the result it returns.
Here is the execution flow for this operation:
- The received message is transformed with the XSL style sheet.
- The transformation result is attached to the response in MTOM mode.
The attachment is not sent in MTOM mode.
The result of the transformation has always the same shape.
<<attachedTransformResponse xmlns="..." xmlns:xop="http://www.w3.org/2004/08/xop/include"> <fileContent> <xop:include href="cid:attachmentName" /> </fileContent> <<attachedTransformResponse>
... where attachmentName is the name of the attachment (as specified in the service-unit, or a default value otherwise).
If an error occurs during the transformation, then a fault is raised.
<?xml version="1.0" encoding="UTF-8"?> <xsltFault xmlns="the name space of the invoked operation"> <message>An error message</message> <details>A stack trace (optional)</details> </xsltFault>
XSL parameters
XSL style sheets supports the definition of parameters.
These parameters can be passed dynamically when executing it.
You can find additional information about it on these web sites:
- http://www.w3schools.com/XSL/el_param.asp
- http://projects.ischool.washington.edu/tabrooks/545/ContentManagement/PassingParameters.htm
- http://www.xml.com/pub/a/2001/02/07/trxml9.html
The Petals XSLT component allows you to set XSL parameters in two different ways:
- The first one is a static definition in the jbi.xml.
- It allows you to reuse a same XSL style sheet in several services.
- Take a look at the jbi.xml parameters for more information.
- The second way is by setting them at runtime, in the message properties.
- Please, understand that this is not the message payload that defines the parameter values.
- It is the properties of the incoming Petals service (called an exchange). For more details, see Exchange#setInMessageProperty( String, Object ).
Static parameter values may be overriden by dynamic ones.
But only if the static values were defines as overridable.
Trying to override a parameter value that is not overridable will result in a fault.
Remember, XSL parameters are declared with a param element in the XSL style-sheet. A XSL parameter can be global (declared as a root element) or local (declared inside a template). The value of a XSL parameter can be retrieved with $parameter_name or {$parameter_name}, depending on the parameter usage. |
XSLT transformer processor
The Petals XSLT component enables you to choose the XSLT processor.
By default, Xalan 2.7.0 (shipped with Java 7) is used as the default XSLT engine. It is possible to select another XSLT processor for a specific SU than the default one by:
- installing a shared library containing the XSLT processor to use,
- setting this shared library into the Petals XSLT component,
- AND the XSL transformer factory classname parameter in the jbi.xml of the SU.
To set the shared library to use into the Petals XSLT component, use the Petals maven plugin. |
XSLT efficiency
A pool of XSL transformers is created for each SU at its start in order to obtain better performance. Two parameters enable you to set the number of XSL transformers to create at the start of the SU and the maximum number of transformers to instantiate. If all the XSL transformers are used (because of receiving a lot of requests concurrently on the service), the request blocks until a transformer is released.
WSDL definitions
Configurations (service-units) for the XSLT component do not have, in general, a WSDL definition.
However, it is possible to define one which describes the transform and "transformToMtomAttachment" operations.
The input and output messages for the transform operation are related to the XSL style sheet.
In fact, the input message should be the output message of the previous chained service (the one whose output must be transformed).
And the output message should be the input message of the next chained service.
The input message for the transformToMtomAttachment operation is related to the XSL style sheet.
In fact, the input message should be the output message of the previous chained service (the one whose output must be transformed). The WSDL message should reference a XML element of the same type than the input message of the transform operation.
And the output message should describe the MTOM structure that was documented above. In this structure, fileContent is a base64Binary element and the xop:include element does not appear.
As said at the beginning of this section, WSDL are not mandatory though. Typically, integration use cases do not require one. But not having one is bad practice in SOA.
Your XSLT service is then not reusable, and no one else will ever use it unless you give him the XSL style sheet to determine the expected input and output.
Beginning by creating a WSDL, and then continuing by the XSL style sheet appears as the best practice to have. |
JBI descriptor
The Service-Unit descriptor file ( jbi.xml ) looks like this:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?> <!-- JBI descriptor for the Petals' "petals-se-xslt" component (XSLT). Originally created for the version 2.5 of the component. --> <jbi:jbi version="1.0" xmlns:generatedNs="http://petals.ow2.org/components/xslt/version-2" xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xslt="http://petals.ow2.org/components/xslt/version-2"> <!-- Import a Service into Petals or Expose a Petals Service => use a BC. --> <jbi:services binding-component="false"> <!-- Import a Service into Petals => provides a Service. --> <jbi:provides interface-name="generatedNs:XsltInterface" service-name="generatedNs:Test" endpoint-name="TestEndpoint"> <!-- CDK specific elements --> <petalsCDK:timeout>30000</petalsCDK:timeout> <petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl> <petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject> <petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties> <petalsCDK:forward-attachments>false</petalsCDK:forward-attachments> <petalsCDK:wsdl>XsltService.wsdl</petalsCDK:wsdl> <!-- Component specific elements --> <xslt:stylesheet>transformation.xsl</xslt:stylesheet> <!-- XSL parameters --> <generatedNs:xsl-parameters> <generatedNs:xsl-parameter name="street" overridable="true"> 17, rue du Parc </generatedNs:xsl-parameter> <generatedNs:xsl-parameter name="city" overridable="false"> Grenoble </generatedNs:xsl-parameter> </generatedNs:xsl-parameters> </jbi:provides> </jbi:services> </jbi:jbi>
A JBI descriptor for an XSLT service-unit can only define one provides block.
Parameter | Description |
Default |
Required |
---|---|---|---|
provides | Describe the JBI service that will be exposed into the JBI bus. Interface (QName), Service (QName) and Endpoint (String) attributes are required. | - | Yes |
A xsl-parameter element has the following structure:
<xs:complexType name="XslParameter"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="name" type="xs:string" /> <xs:attribute name="overridable" type="xs:boolean" default="false" /> </xs:extension> </xs:simpleContent> </xs:complexType>
- Its value is a text.
- The name attribute must match the name of a XSL parameter.
- The overridable attribute defines whether this static value can be overriden by a dynamic value (from an incoming message).
Interceptor
Example of an interceptor configuration:
<?xml version="1.0" encoding="UTF-8"?> <!--...--> <petalsCDK:su-interceptors> <petalsCDK:send> <petalsCDK:interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:send> <petalsCDK:accept> <petalsCDK:interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:accept> <petalsCDK:send-response> <petalsCDK:Interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:Interceptor> </petalsCDK:send-response> <petalsCDK:accept-response> <petalsCDK:Interceptor name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> </petalsCDK:Interceptor> </petalsCDK:accept-response> </petalsCDK:su-interceptors> <!--...-->
Interceptors configuration for SU (CDK)
Parameter | Description | Default | Required |
---|---|---|---|
send | Interceptor dedicated to send phase, for an exchange sent by a consumer | - | No |
accept | Interceptor dedicated to receive phase, for an exchange received by a provider | - | No |
send-response | Interceptor dedicated to send phase, for an exchange (a response) received by a consumer | - | No |
accept-response | Interceptor dedicated to receive phase, for an exchange sent (a response) by a provider | - | No |
interceptor - name | Logical name of the interceptor instance. It can be referenced to add extended parameters by a SU Interceptor configuration. | - | Yes |
param[] - name | The name of the parameter to use for the interceptor for this SU | - | No |
param[] | The value of the parameter to use for the interceptor for this SU | - | No |
Service-Unit content
The service unit must contain the XSL style sheet.
It is also highly recommended to provide a WSDL description for this service.
This WSDL is not mandatory, but not providing it will prevent your service from interacting with other Petals services and components.
The archive may also embed a JAR containing the custom functions referenced in the XSL style sheet, if any.
The directory structure of a SU for the Petals-SE-XSLT looks like this:
su-xslt-TransformationName-provide.zip + META-INF - jbi.xml + XsltService.wsdl (recommended) + <XSL style sheet>.xsl + customFunctions.jar (optional)
Configuring the component
The component can be configured through its JBI descriptor file, as shown below.
<?xml version="1.0" encoding="UTF-8"?> <jbi version="1.0" xmlns='http://java.sun.com/xml/ns/jbi' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5" xmlns:xslt="http://petals.ow2.org/components/xslt/version-2"> <component type="service-engine"> <identification> <name>petals-se-xslt</name> <description>A Xslt Service Engine</description> </identification> <component-class-name description="Xslt Component class">org.ow2.petals.se.xslt.XsltSe</component-class-name> <component-class-path><path-element/></component-class-path> <bootstrap-class-name>org.ow2.petals.component.framework.DefaultBootstrap</bootstrap-class-name> <bootstrap-class-path><path-element/></bootstrap-class-path> <petalsCDK:acceptor-pool-size>3</petalsCDK:acceptor-pool-size> <petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size> <petalsCDK:processor-max-pool-size>50</petalsCDK:processor-max-pool-size> <petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status> <petalsCDK:properties-file></petalsCDK:properties-file> <petalsCDK:notifications>false</petalsCDK:notifications> <petalsCDK:jbi-listener-class-name>org.ow2.petals.se.xslt.XsltJBIListener</petalsCDK:jbi-listener-class-name> </component> </jbi>
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.
Parameter | Description | Default | Scope |
---|---|---|---|
acceptor-pool-size | The size of the thread pool used to accept Message Exchanges from the NMR. Once a message is accepted, its processing is delegated to the processor pool thread. | 1 |
Runtime |
acceptor-retry-number | Number of tries to submit a message exchange to a processor for processing before to declare that it cannot be processed. | 40 |
Installation |
acceptor-retry-wait | Base duration, in milliseconds, to wait between two processing submission tries. At each try, the new duration is the previous one plus this base duration. | 250 |
Installation |
acceptor-stop-max-wait | The max duration (in milliseconds) before, on component stop, each acceptor is stopped by force. | 500 |
Runtime |
processor-pool-size | The size of the thread pool used to process Message Exchanges. Once a message is accepted, its processing is delegated to one of the thread of this pool. | 10 | Runtime |
processor-max-pool-size | The maximum size of the thread pool used to process Message Exchanges. The difference between this size and the processor-pool-size represents the dynamic threads that can be created and destroyed during overhead processing time. |
50 |
Runtime |
processor-keep-alive-time | When the number of processors is greater than the core, this is the maximum time that excess idle processors will wait for new tasks before terminating, in seconds. |
300 |
Runtime |
processor-stop-max-wait | The max duration (in milliseconds) of message exchange processing on stop phase (for all processors). |
15000 |
Runtime |
time-beetween-async-cleaner-runs | The time (in milliseconds) between two runs of the asynchronous message exchange cleaner. |
2000 |
Installation |
properties-file | Name of the file containing properties used as reference by other parameters. Parameters reference the property name using a placeholder in the following pattern ${myPropertyName}. At runtime, the expression is replaced by the value of the property. The properties file can be reloaded using the JMX API of the component. The runtime configuration MBean provides an operation to reload these place holders. Check the service unit parameters that support this reloading. The value of this parameter is :
|
- | Installation |
monitoring-sampling-period | Period, in seconds, of a sample used by response time probes of the monitoring feature. |
300 |
Installation |
Definition of CDK parameter scope :
- Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
- Runtime: The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.
Interceptor
Interceptors can be defined to inject some post or pre processing in the component during service processing.
Using interceptor is very sensitive and must be manipulate only by power users. An non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.
Example of an interceptor configuration:
<?xml version="1.0" encoding="UTF-8"?> <!--...--> <petalsCDK:component-interceptors> <petalsCDK:interceptor active="true" class="org.ow2.petals.myInterceptor" name="myInterceptorName"> <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param> <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param> </petalsCDK:interceptor> </petalsCDK:component-interceptors> <!--...-->
Interceptors configuration for Component (CDK)
Parameter | Description | Default | Required |
---|---|---|---|
interceptor - class | Name of the interceptor class to implement. This class must extend the abstract class org.ow2.petals.component.common.interceptor.Interceptor. This class must be loadable from the component classloader, or in a dependent Shared Library classloader. | - | Yes |
interceptor - name | Logical name of the interceptor instance. It can be referenced to add extended parameters by a SU Interceptor configuration. | - | Yes |
interceptor - active | If true, the Interceptor instance is activated for every SU deployed on the component. If false, the Interceptor can be activated: -by the InterceptorManager Mbean at runtime, to activate the interceptor for every deployed SU. -by a SU configuration |
- | Yes |
param[] - name | The name of the parameter to use for the interceptor. | - | No |
param[] | The value of the parameter to use for the interceptor. | - | No |
This component does not have any specific configuration parameter.
Monitoring the component
Using metrics
Several probes providing metrics are included in the component, and are available through the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.
Common metrics
The following metrics are provided through the Petals CDK, and are common to all components:
Metrics, as MBean attribute | Description | Detail of the value | Configurable |
---|---|---|---|
MessageExchangeAcceptorThreadPoolMaxSize | The maximum number of threads of the message exchange acceptor thread pool | integer value, since the last startup of the component | yes, through acceptor-pool-size |
MessageExchangeAcceptorThreadPoolCurrentSize | The current number of threads of the message exchange acceptor thread pool. Should be always equals to MessageExchangeAcceptorThreadPoolMaxSize. | instant integer value | no |
MessageExchangeAcceptorCurrentWorking | The current number of working message exchange acceptors. | instant long value | no |
MessageExchangeAcceptorMaxWorking | The max number of working message exchange acceptors. | long value, since the last startup of the component | no |
MessageExchangeAcceptorAbsoluteDurations | The aggregated durations of the working message exchange acceptors since the last startup of the component. | n-tuple value containing, in nanosecond:
|
no |
MessageExchangeAcceptorRelativeDurations | The aggregated durations of the working message exchange acceptors on the last sample. | n-tuple value containing, in nanosecond:
|
no |
MessageExchangeProcessorAbsoluteDurations | The aggregated durations of the working message exchange processor since the last startup of the component. | n-tuple value containing, in milliseconds:
|
no |
MessageExchangeProcessorRelativeDurations | The aggregated durations of the working message exchange processor on the last sample. | n-tuple value containing, in milliseconds:
|
no |
MessageExchangeProcessorThreadPoolActiveThreadsCurrent | The current number of active threads of the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolActiveThreadsMax | The maximum number of threads of the message exchange processor thread pool that was active | integer value, since the last startup of the component | no |
MessageExchangeProcessorThreadPoolIdleThreadsCurrent | The current number of idle threads of the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolIdleThreadsMax | The maximum number of threads of the message exchange processor thread pool that was idle | integer value, since the last startup of the component | no |
MessageExchangeProcessorThreadPoolMaxSize | The maximum size, in threads, of the message exchange processor thread pool | instant integer value | yes, through http-thread-pool-size-max |
MessageExchangeProcessorThreadPoolMinSize | The minimum size, in threads, of the message exchange processor thread pool | instant integer value | yes, through http-thread-pool-size-min |
MessageExchangeProcessorThreadPoolQueuedRequestsCurrent | The current number of enqueued requests waiting to be processed by the message exchange processor thread pool | instant integer value | no |
MessageExchangeProcessorThreadPoolQueuedRequestsMax | The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool since the last startup of the component | instant integer value | no |
ServiceProviderInvocations | The number of service provider invocations grouped by:
|
integer counter value since the last startup of the component | no |
ServiceProviderInvocationsResponseTimeAbs | The aggregated response times of the service provider invocations since the last startup of the component grouped by:
|
n-tuple value containing, in millisecond:
|
no |
ServiceProviderInvocationsResponseTimeRel | The aggregated response times of the service provider invocations on the last sample, grouped by:
|
n-tuple value containing, in millisecond:
|
no |
Dedicated metrics
No dedicated metric is available.
Receiving alerts
Several alerts are notified by the component through notification of the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.
To integrate these alerts with Nagios, see Receiving Petals ESB defects in Nagios. |
Common alerts
Defect | JMX Notification |
---|---|
A message exchange acceptor thread is dead |
|
No more thread is available in the message exchange acceptor thread pool |
|
No more thread is available to run a message exchange processor |
|
Dedicated alerts
No dedicated alert is available.