E-mail
|
Key
This line was removed.
This word was removed. This word was added.
This line was added.
|
Changes (29)
View Page History{section}
{column}
{column}
h1. Features
The XSLT Service-Engine allows to transform Petals messages using XSL style sheets.
\\
Each configuration of this component embeds an XSL style sheet.
When such a configuration (i.e. service, i.e. service-unit) is called, it transforms the received message into another one.
The XML payload of the input message is transformed using the XSL style sheet.
The resulting XML document is then returned in the response, either as the payload, or as an attachment.
\\
This component only acts as service provider, not as a service consumer.
In fact, it provides a transformation service.
\\
Additional information about XSLT can be found at [http://www.w3.org/TR/xslt].
{multi-excerpt-include:Petals-SE-XSLT|name=features|nopanel=true}
{column}
...
{column:width=350px} {section}
h1. Recommended usage
\\
{tip}
The XSLT component should be used when chaining calls to services whose output and input do not match.
It can also be used to expose XSL transformations as a service, provided that the content to transform is passed in the message payload, and not as attachment.
{tip}
h2. Taking an example
Let's take the example of two "white pages" services.
These services aims at helping in finding where a person lives (or how to contact this person).
\\
First, you want to call the operation *lookup* of a service "*White Pages*".
This operation takes the first name and the family name of a person, and returns a list of phone numbers.
Each phone number is given as a string.
Its prototype looks like
{code:lang=javascript}
lookup( String firstName, String familyName ) --> String[] phoneNumbers
{code}
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.
It is the operation *resolve* from a service "*PrefixToAreaLocalizer*".
From a phone prefix, it returns a geographical area.
Its prototype looks like
{code:lang=javascript}
resolve( int phonePrefix ) --> String areaName
{code}
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*.
Indeed, you cannot directly execute
{code:lang=java}
resolve( lookup( "Pierre", "Paul"));
{code}
\\
What you will do in your XSL style sheet is extracting the phone prefix from a phone number.
The list go-through will most likely not be made in the XSLT transformation.
\\
There is no more simple way to make the transformation.
In Petals, as well as in most of SOA-related technologies, messages are XML messages.
And for every service, the operations, with their in and out parameters, are described in their WSDL interface.
So, the output message of the *resolve* operation is an XML (SOAP) message, and the input message of *resolve* operation is an XML message too.
These XML messages must match the WSDL descriptions of these services.
\\
Obviously, this example is extremely simple.
But the usage remains the same, even with complex XML structures.
h2. XSLT and chaining services
Following 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 would do the following calls:
# Message from the chaining service to a first service.
# Response from the first service to the chaining service (we assume the first service works in InOut message exchange pattern).
# Message from the chaining service to the XSLT service.
# Response from the XSLT service to the chaining service (the MEP is InOut, always).
# Message from the chaining service to a second service. The transformed message is sent to it.
# Optional response, depending on the MEP for the second service.
\\
This chaining service can be implemented by a POJO (an home made Java Class) or an Enterprise Integration Pattern (EIP).
It could also be implemented by a BPEL process, but in fact, that would not be a great idea.
BPEL supports the extraction of data from XML messages during the orchestration. When you have a BPEL process, you do not need XSLT. You can use XPath expressions and functions directly in the BPEL. Besides, working with BPEL would require the XSLT configuration to have a WSDL interface while they do not always have one.
h2. Limitations and warnings
{note}
The transformed content is always the payload from the input message.
{note}
\\
{note}
Do not mistake XSLT services for interceptors.
{note}
A XSL transformation service cannot transform messages addressed to another service.
Neither to transform attachments, nor to intercept messages on the fly. An orchestration service is required to make the link.
Interceptors would better fit this kind of use case.
\\
{note}
You have to use Java *endorsed* mechanism to work with XSL style sheets of more than 1000 lines.
{note}
This is due to a bug of Xalan. To by-pass it, you have to use a newer version of Xalan (2.7.1 \+).
Since the JDK already embeds Xalan, you have to force it to use your version with the [Java *endorsed* mechanism|http://download.oracle.com/javase/6/docs/technotes/guides/standards/index.html].
\\
{tip}
The XSLT component should be used when chaining calls to services whose output and input do not match.
It can also be used to expose XSL transformations as a service, provided that the content to transform is passed in the message payload, and not as attachment.
{tip}
h2. Taking an example
Let's take the example of two "white pages" services.
These services aims at helping in finding where a person lives (or how to contact this person).
\\
First, you want to call the operation *lookup* of a service "*White Pages*".
This operation takes the first name and the family name of a person, and returns a list of phone numbers.
Each phone number is given as a string.
Its prototype looks like
{code:lang=javascript}
lookup( String firstName, String familyName ) --> String[] phoneNumbers
{code}
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.
It is the operation *resolve* from a service "*PrefixToAreaLocalizer*".
From a phone prefix, it returns a geographical area.
Its prototype looks like
{code:lang=javascript}
resolve( int phonePrefix ) --> String areaName
{code}
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*.
Indeed, you cannot directly execute
{code:lang=java}
resolve( lookup( "Pierre", "Paul"));
{code}
\\
What you will do in your XSL style sheet is extracting the phone prefix from a phone number.
The list go-through will most likely not be made in the XSLT transformation.
\\
There is no more simple way to make the transformation.
In Petals, as well as in most of SOA-related technologies, messages are XML messages.
And for every service, the operations, with their in and out parameters, are described in their WSDL interface.
So, the output message of the *resolve* operation is an XML (SOAP) message, and the input message of *resolve* operation is an XML message too.
These XML messages must match the WSDL descriptions of these services.
\\
Obviously, this example is extremely simple.
But the usage remains the same, even with complex XML structures.
h2. XSLT and chaining services
Following 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 would do the following calls:
# Message from the chaining service to a first service.
# Response from the first service to the chaining service (we assume the first service works in InOut message exchange pattern).
# Message from the chaining service to the XSLT service.
# Response from the XSLT service to the chaining service (the MEP is InOut, always).
# Message from the chaining service to a second service. The transformed message is sent to it.
# Optional response, depending on the MEP for the second service.
\\
This chaining service can be implemented by a POJO (an home made Java Class) or an Enterprise Integration Pattern (EIP).
It could also be implemented by a BPEL process, but in fact, that would not be a great idea.
BPEL supports the extraction of data from XML messages during the orchestration. When you have a BPEL process, you do not need XSLT. You can use XPath expressions and functions directly in the BPEL. Besides, working with BPEL would require the XSLT configuration to have a WSDL interface while they do not always have one.
h2. Limitations and warnings
{note}
The transformed content is always the payload from the input message.
{note}
\\
{note}
Do not mistake XSLT services for interceptors.
{note}
A XSL transformation service cannot transform messages addressed to another service.
Neither to transform attachments, nor to intercept messages on the fly. An orchestration service is required to make the link.
Interceptors would better fit this kind of use case.
\\
{note}
You have to use Java *endorsed* mechanism to work with XSL style sheets of more than 1000 lines.
{note}
This is due to a bug of Xalan. To by-pass it, you have to use a newer version of Xalan (2.7.1 \+).
Since the JDK already embeds Xalan, you have to force it to use your version with the [Java *endorsed* mechanism|http://download.oracle.com/javase/6/docs/technotes/guides/standards/index.html].
{multi-excerpt-include:Petals-SE-XSLT|name=recommended-usage|nopanel=true}
h1. Creating a XSL Transformation service (Provides modes)
...A XSLT service cannot add additional operations. It only has the ones of the XSLT component.
\\
The version 2.4 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.
* *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.
h2. The "transform" operation
...* 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.
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 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.
...{code}
h2. The "transformToMtomAttachment" operation
...* 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.
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 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.
The result of the transformation has always the same shape.
...... 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.
...* [http://projects.ischool.washington.edu/tabrooks/545/ContentManagement/PassingParameters.htm]
\\
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.
* The first one is a static definition in the jbi.xml.
...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.
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.
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.
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.
\\
{tip}
Beginning by creating a WSDL, and then continuing by the XSL style sheet appears as the best practice to have.
{tip}
Beginning by creating a WSDL, and then continuing by the XSL style sheet appears as the best practice to have.
{tip}
h2. JBI descriptor
...{code}
\\
A JBI descriptor for an XSLT service-unit can only define one _provides_ block.
\\
{include:0 CDK SU Provide Configuration}
\\
\\
...{table-plus}
\\
A *xsl-parameter* element has the following structure:
...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:
...{noformat}
h1. Configuring the component
...</jbi>{code}
\\
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.
\\
{include:0 CDK Component Configuration Table 2.0}
{include:0 CDK Parameter scope}
{include:0 CDK Component Interceptor configuration}
{include:0 CDK Parameter scope}
{include:0 CDK Component Interceptor configuration}
\\
This component does not have any specific configuration parameter.