Customizing messages that client applications send to and receive from Web services
You can customize the XML tagging of the messages that client applications send to and receive from Web services.
For each operation that you include in a Web service, the workbench generates a default XML schema that describes the input and output XML messages for that operation. If an input message for a Web service operation is in XML, messages must be tagged according to this default XML schema. All output messages that Web services generate for the operation are also tagged according to the default XML schema.
You can configure XSL transformations of the XML input messages, the output messages, or both types of message for a Web service operation. Those XSL transformations take place during the input and output message flows.
The flow of custom SOAP/HTTP and HTTP POST (text/xml) messages involves two XSL transformations: one for input messages and one for output messages. The flow of custom HTTP GET/POST (url-encoded) messages involves only one XSL transformation, which is for output messages.
The following sections describe the XSL transformations for messages that use the supported message protocols.
- XSL transformations with the
SOAP/HTTP message protocol
- XSL transformations with the
HTTP POST (text/xml) message protocol
- XSL transformations with the HTTP GET/POST (url-encoded) message protocol
XSL transformations with the SOAP/HTTP message protocol
This section describes the default message flow for SOAP/HTTP messages and then describes the flow that incorporates XSL transformations.
The default message flow, which contains no XSL transformations, for a Web service operation follows these steps:
- A client application sends a SOAP/HTTP message that accesses an operation
in a Web service. The body of the message is in XML and is tagged according
to the default schema.
- The Web service receives the message and passes to the database the SQL
statement or stored procedure call that is in the operation.
- The Web service receives the response from the database and packages the
response in an XML message that is tagged according to the default XML schema
for the operation.
- The Web service sends the response to the client application.
Figure 1. Default flow of messages
When you configure XSL transformations, the message flow for a Web service operation follows these steps:
- A client application sends a SOAP/HTTP message that accesses an operation
in a Web service. The XML message in the SOAP body is tagged according to
a custom XML schema.
- The message is transformed so that it is tagged according to the default
XML schema.
- The Web service receives the message and passes to the database the SQL
statement or stored procedure call that is in the operation.
- The Web service receives the response from the database and packages the
response in an XML message that is tagged according to the default XML schema
for the operation.
- The message is transformed so that it is tagged according to the custom
XML schema.
- The Web service sends the response to the client application.
Figure 2. Flow of messages that incorporates XSL transformations
| Input to the XSL transformation | Output from the XSL transformation | |
|---|---|---|
| First XSL transformation | SOAP-wrapped, valid XML document that uses a custom XML schema | SOAP-wrapped, valid XML document that uses the default XML schema |
| Second XSL transformation | SOAP-wrapped, valid XML document that uses the default XML schema | SOAP-wrapped, valid XML document that uses a custom XML schema |
As described in the following table, when you create the Web service supply the following files:
- To enable the first transformation, supply the Web service with
a copy of the custom XML schema and an XSL file that maps the custom XML schema
to the default XML schema.
- To enable the second transformation, supply the Web service with a copy of the custom XML schema and an XSL file that maps the default XML schema to the custom XML schema.
| XSL transformation of input message | XSL transformation of output message | ||
|---|---|---|---|
| Custom XML schema (XSD file) | XSL file | Custom XML schema (XSD file) | XSL file |
| X | X | X | X |
XSL transformations with the HTTP POST (text/xml) message protocol
This section describes the default message flow for HTTP POST (text/xml) messages and then describes the flow that incorporates XSL transformations.
The default message flow, which contains no XSL transformations, for a Web service operation follows these steps:
- A client application sends an HTTP POST (text/xml) message that accesses
an operation in a Web service. The message is in XML and is tagged according
to the default schema.
- The Web service receives the message and passes to the database the SQL
statement or stored procedure call that is in the operation.
- The Web service receives the response from the database and packages the
response in an XML message that is tagged according to the default XML schema
for the operation.
- The Web service sends the response to the client application.
Figure 3. Default flow of messages
When you configure XSL transformations, the message flow for a Web service operation follows these steps:
- A client application sends an HTTP POST (text/xml) message that accesses
an operation in a Web service. The message is tagged according to a custom
XML schema.
- The message is transformed so that it is tagged according to the default
XML schema.
- The Web service receives the message and passes to the database the SQL
statement or stored procedure call that is in the operation.
- The Web service receives the response from the database and packages the
response in an XML message that is tagged according to the default XML schema
for the operation.
- The message is transformed so that it is either in XML and is tagged according
to the custom XML schema, or is in a non-XML format, such as HTML or plain
text.
- The Web service sends the response to the client application.
Figure 4. Flow of messages that incorporates XSL transformations
| Input to the XSL transformation | Output from the XSL transformation | |
|---|---|---|
| First XSL transformation | Valid XML document that uses a custom XML schema | Valid XML document that uses the default XML schema |
| Second XSL transformation | Valid XML document that uses the default XML schema | Non-XML document or a valid XML document that uses a custom XML schema |
As described in the following table, when you create the Web service supply the following files:
- To enable the first transformation, supply the Web service only
with an XSL file that maps a custom XML schema to the default schema. You
do not need to supply a copy of the custom XML schema.
- To enable the second transformation, the files that you provide to the
Web service depend on the output that you want:
- To enable the transformation to XML, supply the Web service only
with an XSL file that maps a custom XML schema to the default schema. You
do not need to supply a copy of the custom XML schema.
- To enable the transformation to a non-XML format, supply an XSL file that maps the default XML schema to the non-XML format.
- To enable the transformation to XML, supply the Web service only
with an XSL file that maps a custom XML schema to the default schema. You
do not need to supply a copy of the custom XML schema.
| XSL transformation of input message | XSL transformation of output message | ||
|---|---|---|---|
| Custom XML schema (XSD file) | XSL file | Custom XML schema (XSD file) | XSL file |
| X | X |
XSL transformations with the HTTP GET/POST (url-encoded) message protocol
This section describes the default message flow for HTTP GET (url-encoded) and HTTP POST (url-encoded) messages and then describes the flow that incorporates an XSL transformation.
The default message flow, which contains no XSL transformation, for a Web service operation follows these steps:
- A client application sends an HTTP GET (url-encoded) or HTTP POST (url-encoded)
message that accesses an operation in a Web service. The message is an encoded
sequence of parameters in string of text.
- The Web service receives the message and passes to the database the SQL
statement or stored procedure call that is in the operation.
- The Web service receives the response from the database and packages the
response in an XML message that is tagged according to the default XML schema
for the operation.
- The Web service sends the response to the client application.
Figure 5. Default flow of messages
When you configure an XSL transformation, the message flow for a Web service operation follows these steps:
- A client application sends an HTTP GET (url-encoded) or HTTP POST (url-encoded)
message that accesses an operation in a Web service. The message encodes the
parameters. XSL transformations are not possible on these messages.
- The Web service receives the message and passes to the database the SQL
statement or stored procedure call that is in the operation.
- The Web service receives the response from the database and packages the
response in an XML message that is tagged according to the default XML schema
for the operation.
- The message is transformed so that it is either in XML and is tagged according
to the custom XML schema, or is in a non-XML format, such as HTML or plain
text.
- The Web service sends the response to the client application.
Figure 6. Flow of messages that incorporates an XSL transformation
| Input to the XSL transformation | Output from the XSL transformation | |
|---|---|---|
| First XSL transformation | XSL transformations are not supported for messages from client applications. | |
| Second XSL transformation | Valid XML document that uses the default XML schema | Non-XML document or a valid XML document that uses a custom XML schema |
As described in the following table, when you create the Web service supply the following files:
- To enable the transformation to XML, supply the Web service only
with an XSL file that maps a custom XML schema to the default schema. You
do not need to supply a copy of the custom XML schema.
- To enable the transformation to a non-XML format, supply an XSL file that maps the default XML schema to the non-XML format.
| XSL transformation of input message | XSL transformation of output message | ||
|---|---|---|---|
| Custom XML schema (XSD file) | XSL file | Custom XML schema (XSD file) | XSL file |
| X |
- Transforming input messages that use the HTTP POST (text/xml) protocol and output messages
If client applications will access an operation with messages that use the HTTP POST (text/xml) protocol, you can transform those messages to use the XML schema that the workbench generated for the operation. You can optionally transform messages that are returned by the Web service from the default XML schema to valid XML documents or into non-XML formats. - Transforming output messages when input messages use the HTTP GET or POST (url-encoded) protocol
If client applications will access an operation with messages that use the HTTP GET or POST (url-encoded) protocol, you can transform messages that are returned by the Web service. The XSL transformation changes messages that are tagged according to the default XML schema to valid XML documents or into non-XML formats. - Transforming input and output messages that use the SOAP/HTTP message protocol
If your client applications will send and receive messages that use SOAP/HTTP message protocol when they access a particular operation in a Web service, you can transform those messages to use the XML schema that the workbench generated for the operation. You can also transform messages that are returned by the Web service from the default XML schema to SOAP-wrapped, valid XML documents that use a custom XML schema. - Customizing web.xml files for Web Archive (WAR) files
You can customize the web.xml file that the workbench uses in the WAR file that the workbench builds for your Web service. You might want to change the web.xml by adding some filters for requests coming into your web service if you want these filters to be deployed along with the service. You might also want to add additional servlets or servlet mapping tags.
Previous topic: Sharing Web services with members of your development team
Next topic: Configuring Web servers to run Web services