SOAP Projects

A SOAP project represents a WSDL-based project that contains a collection of SOAP scenarios. A SOAP scenario represents a single WSDL service operation for which a SOAP-based service invocation will be done.   A SOAP project can be created from a local / remote WSDL file. This can be specified by selecting the appropriate value for the WSDL source radio box in the SOAP project creation dialog as shown below:   Uploading a file automatically results in a project name getting suggested.

Using a local WSDL file

To use a local WSDL file you have to upload a WSDL document from your local file system. The SOAP project creation dialog after uploading a WSDL file is shown below:  

Figure 6.4. SOAP Project - New project

SOAP Project - New project


The Create Scenario for all WSDL operations checkbox when enabled causes Examine to create a SOAP scenario for each WSDL operation in the SOAP binding present in the SOAP service. If this option is not enabled, then no scenarios are created for any operation and a new scenario can be created later by using the Create scenario menu option when right clicking on the WSDL operation after the project is created

Using a local WSDL file with references

If the WSDL document references other WSDL documents through wsdl:import or other schemas through the xs:import or xs:include elements, then to create a SOAP project from such a WSDL document, a zip file containing the parent WSDL file and all the referenced documents can be uploaded as a single file to create a project.

Consider an example WSDL file called SimpleStockQuoteService.wsdl that references another WSDL file which in turn references three schema documents.

The above set of files can be uploaded as a single ZIP file as shown below:

Figure 6.5. SOAP Project - Import Zipped WSDL Project

SOAP Project - Import Zipped WSDL Project


When this zip file is uploaded, a dialog displaying the ZIP file contents is displayed in a dialog to allow you to select the root WSDL file from which the SOAP project must be created as shown below:

Figure 6.6. SOAP Project - Zipped project contents listing

SOAP Project - Zipped project contents listing


Note that only WSDL files are displayed by default to help select the WSDL file.

Using a remote WSDL file

To use a remote WSDL file choose the ‘URL’ option for WSDL source and enter the URL of the remote WSDL document.

Figure 6.7. SOAP Project - New project - Remote WSDL

SOAP Project - New project - Remote WSDL


HTTP Authentication Configuration

The ‘Auth’ tab allows for specifying the HTTP Basic Authentication credentials when retrieving the WSDL file:

Figure 6.8. SOAP Project - Remote WSDL - Authentication

SOAP Project - Remote WSDL - Authentication


SSL Configuration

If the WSDL file is accessible over HTTPS, the SSL tab can be used to configure the required Server and Client SSL Authentication settings. The Enable SSL checkbox must be checked to enable SSL configuration. The KeyStore and TrustStorecombo boxes lists all the previously configured keystores. Both the fields are optional. The KeyStore value is only required if the server requires SSL client authentication.

The TrustStore value is required if you would like Examine to verify the server certificate when performing a SSL handshake with the server. If a truststore is not configured, Examine will accept any server provided certificate

Tip

You can leave the TrustStore value unconfigured for Web Services under development or when using self-signed certificates for the SSL endpoint

Figure 6.9. SOAP Project - Remote WSDL - SSL setup

SOAP Project - Remote WSDL - SSL setup


The Verify Hostname checkbox when enabled causes Examine to verify the hostname value in the certificate provided by the server during SSL handshake

SOAP Scenarios

Create and configure SOAP scenarios for a SOAP Project

After a SOAP project is created, a SOAP scenario can be created for the operations listed for each binding. To do this, right click on the displayed service operations and select Create Scenario as shown below:

Figure 6.10. SOAP Project - Create Scenario

SOAP Project - Create Scenario


This will bring up the New SOAP scenario dialog that can be used to specify a scenario name and the transport protocol to use – either HTTP or JMS, defaulted to HTTP.

Figure 6.11. SOAP Project - New Scenario dialog

SOAP Project - New Scenario dialog


Each SOAP scenario groups the operation request, response, test case and security configuration together.

SOAP request contents

Once the soap scenario is created, the request information can be updated through three different viewers (Tree, XML and Raw) in the Request tab. By default, the request XML is displayed in the XML viewer, which displays the request contents in, formatted, pretty-printed form

XML Editor

The XML viewer provides a text-editor field with syntax highlighting of the XML content. Note that the XML viewer can detect invalid XML such as unclosed tags and the incorrect elements will be highlighted accordingly.

Figure 6.12. SOAP Scenario - XML view

SOAP Scenario - XML view


Raw text editor

The raw text viewer provides a text-editor field to edit the XML contents. This viewer is useful when you would like to send raw unformatted contents to the web service. This view does not display any highlighted or pretty-printed text.

Figure 6.13. SOAP Scenario - Raw text view

SOAP Scenario - Raw text view


Tree-based XML editor

The Tree viewer is the most feature-rich of the three XML viewers and it provides for the following operations on the displayed XML. The XML is displayed in a tree form and right clicking on the different tree nodes displays a context menu that allows for different operations on the node depending on the type of node that was the target. For e.g. the tree nodes are distinguished as DOM Element, Attribute, Comment and Text. Actions applicable on one node may not be applicable for another. For e.g. the ‘Add attribute’ action only works on a node that represents an XML element

Figure 6.14. SOAP Scenario - Tree view

SOAP Scenario - Tree view


The elements and attributes in the XML tree view provide context-sensitive actions to manipulate the XML content.

Figure 6.15. SOAP Scenario - Tree view - Context options

SOAP Scenario - Tree view - Context options


In the above picture, right-clicking on the ‘symbol’ element displays the menu with the following enabled actions:

Add Element

Add a new DOM element with the given name and namespace as a child of the ‘symbol’ element

Add Attribute

Add a new DOM attribute with the given name and value as an attribute of the ‘symbol’ element

Delete

Delete the selected element (symbol element in this case)

Add Text

Add a text element to the selected 'symbol' element

Get XPath

This action retrieves the XPath expression corresponding to the selected DOM element in the tree

Add XOP Include

This is a special action that is useful when sending SOAP attachments with MTOM support. For more details see the ‘##############Sending Attachments…’ section.

All the three views synchronize with each other when switching from viewer to another. So if there is an invalid XML in the XML/Raw view, then the tree view cannot display the updated XML and will instead show an error message and display the old XML.

Updating SOAP request endpoint

Each SOAP scenario contains a SOAP request that will be sent to one specific endpoint. The available endpoints are populated above the XML viewer tabs as a dropdown list. The list of endpoints is based on the WSDL 1.1 Service/Port/address element values.

You can add new request endpoints, edit existing endpoints or remove the listed endpoints using the endpoint action buttons:

Clicking on the Execute button ( ) will send the request to the selected endpoint using the currently selected scenario configuration values.

SOAP Scenario Security Configuration

Configuring WS-Security for the SOAP request

Each SOAP Scenario can be configured with Message-level (WS-Security) security settings that apply to the SOAP request that is part of the SOAP Scenario by clicking on the ‘Security’ tab.   Examine allows specifying the WS-Security configuration using a WS-SecurityPolicy or through a non-policy configuration that involves specifying the different security assertions manually. There are three possible WS-Security Configuration types available for each SOAP scenario:

  • No Security

  • Non-Policy Security configuration

  • WS-SecurityPolicy-based Security Configuration

No Security

This is the default WS-Security configuration type for every SOAP scenario. When this option is selected, no WS-Security header will be sent in the outbound SOAP request and no WS-Security processing of the SOAP response will be done.

Non-policy security configuration

This option allows for configuring the WS-Security settings for the SOAP scenario using a manual approach. This is helpful when there is no WS-SecurityPolicy available to describe the security requirements for the WS endpoint under test. When using a non-policy security configuration, it is possible to either specify a custom in/out security configuration or re-use an existing global security configuration created earlier.

Figure 6.16. SOAP Scenario - NonPolicy Security

SOAP Scenario - NonPolicy Security


Local Configuration

This is the default option for non-policy WS-Security configuration. It allows for manually setting the outbound (request) and inbound (response) security settings for the SOAP scenario request.

Figure 6.17. SOAP Scenario - NonPolicy security - Local configuration

SOAP Scenario - NonPolicy security - Local configuration


Outbound SecurityTo enable outbound request security, check the Enable Request Security checkbox. The Add button can be used to add outbound security assertions to the request. The following security assertions are available to be configured for the request:

Timestamp

This action is the same as the global non-policy Timestamp configuration. Please refer to this section for more information.

Username Token

This action is the same as the global non-policy UsernameToken configuration. Please refer to this section for more information.

Signature

This action is same as the global non-policy Signature configuration except how the SOAP part is selected. Please refer to this section for more information.

Selecting SOAP parts to sign

Unlike adding a part in the global Signature configuration section, clicking on the Add Part button brings up the Select Element Part selection dialog as shown below.

Figure 6.18. SOAP Scenario - NonPolicy Security - Selecting Sign parts

SOAP Scenario - NonPolicy Security - Selecting Sign parts


This dialog displays the current SOAP request contents in a tree form. You can either click on a specific element that should be signed or enter the value of the ID attribute (which should be unique within the document) in the Element ID text field.   The Mode combo box value determines whether the ‘content’ of the selected element or the ‘element’ itself will be signed.   After choosing the part to sign, click on the Add button to add the part in the parts table to be signed when the request is sent out.

To delete a previously added part, select the checkbox on the appropriate row and click on Delete

Encryption

This action is the same as configuring the global non-policy Encryption action except how the SOAP part is selected. Please refer to this section for more information.

Selecting SOAP Parts to encrypt

Unlike adding a part in the global non-policy Encryption action, clicking on the Add Part button opens the parts selection dialog similar to the Signature Assertion parts selection dialog box.

The screenshot below shows how a specific XML element within the SOAP Body can be selected to be encrypted. A unique element ID can also be entered as an alternative to selecting an element.

Figure 6.19. SOAP Scenario - NonPolicy Security - Selecting Encrypt parts

SOAP Scenario - NonPolicy Security - Selecting Encrypt parts


The qualified name (QName) of the selected element is displayed in the ‘Selected Element’ field. You can also specify the ‘Element ID’ of the element that should be encrypted. Note that the element ID is a unique value within the XML document.

The Mode element again specifies whether the selected element or the content of the element must be encrypted.

After the element to be encrypted is added, it is displayed in the parts table as shown below.

SAML Assertion

This action is the same as configuring the global non-policy SAML action. Please refer to this section for more information.

Binary Security Token (X.509 token)

This action is the same as configuring the global non-policy Binary Security Token action. Please refer to this section for more information.

Inbound Security

Configuring Inbound (SOAP response) security is similar to the global non-policy inbound security configuration. Please refer to this section for more information.

Global Configuration

If you have already created a global non-policy security configuration as described here, then it can be re-used for enforcing WS-Security for the SOAP request and response in this SOAP scenario. To re-use an existing security configuration, select Global Configuration radio box and select from the list of security configurations shown in the drop-down box.

Figure 6.20. SOAP Scenario - NonPolicy - Global configuration

SOAP Scenario - NonPolicy - Global configuration


Click on Refresh button to reload the available list of security configurations

WS-SecurityPolicy based security configuration

Examine also allows for using a WS-SecurityPolicy to apply security to the outbound SOAP request contents. This can be done by either specifying a shared global security policy configuration, a local policy-based configuration or by using the policy present in the WSDL document used to create the SOAP project and scenario.

Global Policy-based security configuration

Figure 6.21. SOAP Scenario - Global Policy configuration

SOAP Scenario - Global Policy configuration


This option allows for reusing previously created global policy-based security configurations as described here. The selected configuration is a combination of a security policy and the related configuration information. Click on Refresh button to reload the available set of configurations.

Local Policy-based security configuration

Figure 6.22. SOAP Scenario - Local Policy configuration

SOAP Scenario - Local Policy configuration


This option allows for using a WS-SecurityPolicy previously uploaded using the SecurityWS Policies accordion tab as the source of the security requirement for the outbound client request. This option differs from the Global Policy-based configuration in that the configuration values must be specified manually and only the WS-SecurityPolicy is reused, while in the global configuration, both the policy and the values are reused.

The Policy drop-down component displays all the available WS-Security Policy files currently available for use. The Refresh button can be used to reload the available policy files.   The Save As... button allows for saving this local security configuration as a shared global configuration that can be reused in other SOAP scenarios without having to re-select the policy and configuration values to use.  

WSDL-based security policy

Figure 6.23. SOAP Scenario - WSDL-based policy configuration

SOAP Scenario - WSDL-based policy configuration


It is also possible to use the WS-SecurityPolicy already present in the WSDL document used to create the SOAP scenario. This option is useful when the WSDL obtained from a service provider already specifies the policy that the client should use when interacting with the service

The effective policy is computed at runtime before the request is sent to the service provider. The final request effective policy is a merge of the policies on the following policy subjects:  

  • Service policy

  • Endpoint policy

  • Operation policy

  • Input Message policy

If there are no policies that are referenced (or specified) by the policy subjects, the effective policy cannot be computed. To view the computed effective policy click on the ‘View Effective Policy’ link. The screenshot below displays the final policy for a sample WSDL service port:

Figure 6.24. SOAP Scenario - View Effective Request Policy

SOAP Scenario - View Effective Request Policy


Specifying the WS-SecurityPolicy security requirements

The security policy usually does not specify the required data such as the time stamp value, username or keystores to use for signing or encryption to satisfy the policy requirements. When using either a WSDL-based WS-SecurityPolicy or a local policy file, the required configuration values must be specified for Examine to create the correct security header.

The ‘Time-To-Live’, ‘Username Token’, ‘Signature’ and ‘Encryption’ options allow for specifying the required configuration values as required by the WS-SecurityPolicy chosen.

Figure 6.25. SOAP Scenario - Specifying Security Policy data

SOAP Scenario - Specifying Security Policy data

For the Signature value, a private key alias must be selected in the keystore dialog box shown when clicking on ‘Select’.

For the Encryption value, a public key alias must be selected in the keystore dialog shown when clicking on ‘Select’.

The ‘Remove’ button can be used to clear any previous selection.

Note

Specifying the configuration values does not imply that, that particular action would be applied automatically. The actions taken at runtime depend on the policy assertions present in the chosen policy. For e.g. specifying Username Token values does not imply that the request would contain a UsernameToken header. The policy determines if a UsernameToken header would be added to the WS-Security header in the SOAP request.

By default, Examine does not verify if the response from the service under test conforms to the selected WS-SecurityPolicy. To enable checking if the response is valid according to the policy, the Verify Reponse conforms to policy checkbox should be enabled

Configuring the Test Case for SOAP Scenario

Grouping a scenario test case in a TestSuite

Every SOAP scenario also contains a TestCase as part of it. A TestCase can be added to a TestSuite to be grouped with TestCase’s from other SOAP Scenarios. TestSuite’s allow for execution of multiple TestCase’s from different SOAP scenarios together. To learn more about how to use TestSuite’s please refer to the chapter on TestSuite configuration

Click on the ‘Add to Suite’ button to open the ‘Available SOAP Test Suites’ dialog as shown below. Any previously created test suites are displayed in the drop-down box.

Figure 6.26. SOAP Scenario - Available Test Suites

SOAP Scenario - Available Test Suites


To add the test case to a new suite, click on the ‘Create New TestSuite’ and specify a unique test suite name. The test case of this soap scenario is added to the newly created test suite.

Figure 6.27. SOAP Scenario - Add new Test Suite dialog

SOAP Scenario - Add new Test Suite dialog


Available test assertions

Each test case is a collection of test assertions. Examine provides the following built-in assertions that can be added to a test case for evaluation on the SOAP response.

Figure 6.28. SOAP Scenario - Test Assertions

SOAP Scenario - Test Assertions


Assert HTTP Response Code:

This assertion verifies that the HTTP response code is a particular code such as 200 (OK) or 401 (Unauthorized)

Assert HTTP Header:

This assertion can be used to check if a particular HTTP header is present, absent or is equal to a certain value.

Assert HTTP Response time:

This assertion can be used to verify if the HTTP response was either less than or greater than a certain threshold value specified in milliseconds.

Assert Response Contains:

This assertion can be used to check for the presence of a particular token in the HTTP response. If the ‘Regular Expression’ checkbox is checked, then the specified text is used a regex pattern against the SOAP response body. The regex pattern should follow the Java regular expression rules.

Tip

For more information on how to use Regular Expressions, please refer to this page: http://download.oracle.com/javase/tutorial/essential/regex/

Assert XPath Result:

This assertion can be used to check if an XPath expression evaluates properly against the SOAP response Envelope. Click on the ‘Configure’ button to open the XPath Expression dialog box where you can enter the XPath expression to use and declare the namespace URIs for any prefixes used in the expression.

Each namespace declaration should be entered on a new line and is of the form:prefix = URI

The result of evaluating the XPath expression will be a Boolean true/false. If the xpath expression results in DOM Nodes, then the result is True and if no there are matching nodes, the result is false. If the expression contains a predicate clause, then the result is either true/ false as well.

Assert XQuery Result:

This assertion can be used to evaluate an XQuery expression against the SOAP response envelope contents. Click on the ‘Configure’ button to bring up the XQuery Expression dialog where you can enter the XQuery contents that will be run against the SOAP envelope, and the expected result of the execution. The result of the xquery run will be compared against the specified expected result value after removing any whitespace characters that are present in both of them (for e.g the comparison is will be done after stripping out any new line, tabs and other whitespace characters)

Assert XML Schema:

This assertion can be used to perform XML Schema validation of the SOAP response body contents. Click on the Configure button to open the XML Schema configuration dialog as shown below.

Click on the ‘Add’ button to upload a single XML schema file. If the schema has other references (includes / imports) then a zip file containing the main schema file and the schema references as local relative paths can be uploaded as well.

Uploading a schemas zip file

When a zip file containing the schemas is uploaded, Examine will prompt you to choose the main schema file. The main schema file is the one that contains relative references to other schema files. For e.g. consider the following XSD and its references:

catalog.xsd - with two <xs:include/> references to pricing.xsd and sequence.xsd

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <xsd:include schemaLocation="pricing.xsd"/>
    <xsd:include schemaLocation="sequence.xsd"/> 
    ... 
</xsd:schema>

The above schemas can be uploaded as a single zip file (catalog.zip). This results in the following dialog that prompts you to select the root schema file (catalog.xsd):

Note

The schemaLocation attribute value for all schema references (import / include elements) must be relative paths to the importing schema. This ensures that Examine is able to resolve all referneces to load the schema model correctly

Configuring HTTP Transport

Each SOAP scenario can either be based on either the HTTP or JMS transport protocol. For HTTP, the following can be configured for each SOAP request:

HTTP Headers
Authentication
SSL configuration
HTTP Headers

To configure the outbound HTTP headers, click on the HTTP link at the bottom of the request XML editor to bring up the ‘Request Configuration’ section and select the ‘Headers’ tab as shown below:

Figure 6.29. SOAP Scenario - HTTP headers

SOAP Scenario - HTTP headers


To add / remove header names and their values click on the ‘Add’ or ‘Delete’ button. (For delete, you need to select the headers to be deleted by selecting the appropriate checkbox next to each row)

Authentication

To setup the outbound HTTP authentication information (Authorization HTTP header), select the ‘Authentication’ tab under the ‘HTTP’ tab.  

Click on the ‘Enable HTTP Auth’ checkbox to enable the username, password and related fields.  

The ‘Do Preemptive Authentication’ checkbox if enabled results in the Authorization header being sent to the service even before the service challenges for the credentials.  

The Authentication Type field can be either Basic or Digest and it results in the use of either HTTP Basic Authentication or HTTP Digest Authentication as outlined in the RFC 2617 (http://www.ietf.org/rfc/rfc2617.txt)

Figure 6.30. SOAP Scenario - HTTP Authentication

SOAP Scenario - HTTP Authentication


SSL Configuration

If the service endpoint is accessible over HTTPS, then it is possible to specify the keystore and / or truststore to use for SSL key negotiation. To do this select the ‘SSL’ tab under the ‘HTTP’ tab as shown below.  

Click on the ‘Enable SSL’ checkbox to enable specifying a keystore and/or truststore to use.  

The KeyStore and TrustStore drop-down boxes display all the available keystores in the system for the currently logged in user.  

If SSL Client Authentication must be performed, then select the keystore that contains the private key whose equivalent public key is known to the service provider. To disable SSL Client Authentication, leave the KeyStore field empty.  

To specify a custom truststore that contains the service provider’s X.509 certificate, select a truststore from the available stores. This truststore must contain the server certificate imported as a public key in it.  

The ‘Verify Hostname’ field determines if the hostname specified in the X.509 certificate obtained during SSL handshake will be compared against the hostname of the endpoint to which the request is sent.  

The ‘Refresh keystores’ button reloads all the available keystores and truststores.

Figure 6.31. SOAP Scenario - HTTP SSL configuration

SOAP Scenario - HTTP SSL configuration


Configuring JMS Transport

If the SOAP Scenario is based on the Java Message Service (JMS) protocol, then the connection information must be specified correctly inorder for the request to succeed.

To configure the JMS server and destination type (Queues / Topics) to use, click on the JMS link below the Request editor to bring up the JMS tab.   This tab in turn contains the ‘Connection’, ‘QoS Parameters’ and ‘Properties’ tabs

Connection Configuration

The Connection tab as shown in the screenshot below is used to specify the JMS server connection information:

Figure 6.32. SOAP Scenario - JMS Connection

SOAP Scenario - JMS Connection


Examine comes bundled with the Apache ActiveMQ libraries by default. If the JMS server being used is also ActiveMQ, then selecting the ‘Use ActiveMQ’ checkbox automatically populates the Connection Factory Name to ConnectionFactory and the Initial Context Factory Name to org.apache.activemq.jndi.ActiveMQInitialContextFactory.

The initial context factory name is the fully-qualified class name of the class implementing javax.naming.spi.InitialContextFactory. When using ActiveMQ, the value is defaulted to org.apache.activemq.jndi.ActiveMQInitialContextFactory.

Note

If you would like to use a different JMS provider, then the client library for the provider must be copied under WEB-INF/lib folder of the Examine web application. You must also enter the correct values for the Connection Factory and Initial Context Factory names in the JMS configuration screen. Please refer to the provider documentation for these values

The Provider URL is of the form: tcp://server:port   where tcp is the protocol to use, server is the host name of the JMS server and port is the port that the JMS server is listening on for incoming connections.

The Destination name specifies the name of the Queue or Topic to which the message must be sent.

The Type value specifies the destination type – either Queue or Topic

The ReplyTo value specifies the destination name to which the server should send the response. If it is not specified, an anonymous destination name will be used.

If the JMS provider requires any authentication, then enter the username and password to use under the Credentials section.

Specifying Quality-of-Service parameters

The QoS Parameters tab is used to specify the Quality-of-Server parameters for the outbound JMS request

Figure 6.33. SOAP Scenario - JMS QoS Parameters

SOAP Scenario - JMS QoS Parameters

The Time-To-Live field captures the value in milli-seconds of the JMSExpiration header. This is the duration for which the message produced by the producer is valid after which it won’t be delivered to any consumer. Default value = 0 which means the message does not expire.  

The ‘Send as bytes message’ field if selected will cause the message to sent as JMS BytesMessage in which the payload sent as an array of bytes which is not transparent to the client. If not selected, the SOAP request payload is sent as plain text string. Default value is false which means the message is send as plain text.  

The Priority slider controls the value of the message priority and can take a value between 0 and 9. It is set as the value of the JMSPriority header. Default value = 0.  

The Delivery mode controls the value of the JMSDeliveryMode header and can be either Persistent or Non-Persistent. Persistent means that the message will be delivered until it is received by the consumer but only once and Non-Persistent means the message won’t be redelivered if the initial delivery attempt fails. Default value = Persistent.  

The Receive Timeout value is the time to wait to a response from the provider. Default value = 1000 ms or 1s.

Specifying Application-specific properties

JMS allows for adding custom application-specific properties as JMS Properties. The Properties tab can be used to add name-value pairs that will be sent as JMS Properties in the JMS message.

Figure 6.34. SOAP Scenario - JMS Properties

SOAP Scenario - JMS Properties


Configuring WS-Addressing

To enable WS-Addressing support for SOAP requests click on the ‘WS-Addressing’ link shown below the request XML view. This will bring up the WS-Addressing tab in the ‘Request Configuration’ view.  

By default, the ‘Enable WS-Addressing’ checkbox is disabled to prevent WSA headers from being added to the outbound request. To send WSA headers, enable the checkbox.

Figure 6.35. SOAP Scenario - WS-Addressing

SOAP Scenario - WS-Addressing


The To field corresponds to the /wsa:To element which is an optional element. If this value is not specified, it is defaulted to http://www.w3.org/2005/08/addressing/anonymous

To Action field corresponds to the /wsa:Action element, which is a required element. Either a valid value must be specified or the checkbox Use Default Action must be selected to use the default SOAPAction value.  

The Message ID field corresponds to the optional /wsa:MessageID element. This must contain an unique value for each request. Selecting the Auto generate checkbox results in a random message id for each request.  

The From, ReplyTo and FaultTo EPR (Endpoint Reference) fields correspond to the source, reply and fault endpoint properties of WSA, which are all of /wsa:EndpointReferenceType type. Each EPR consists of a single destination address and a collection of parameters or metadata.

Each EPR takes the XML form:

<wsa:EndpointReference>
    <wsa:Address>xs:anyURI</wsa:Address>
    <wsa:ReferenceParameters>xs:any*</wsa:ReferenceParameters> ?
    <wsa:Metadata>xs:any*</wsa:Metadata>?
</wsa:EndpointReference>
Reference parameters: xs:any (0..unbounded)

A reference may contain a number of individual parameters that are associated with the endpoint to facilitate a particular interaction. Reference parameters are namespace-qualified element information items that are required to properly interact with the endpoint. Reference parameters are provided by the issuer of the endpoint reference and are assumed to be opaque to other users of an endpoint reference.

Metadata: xs:any (0..unbounded)

A reference may contain metadata that describes the behavior, policies and capabilities of the endpoint. Metadata may be included in an endpoint reference to facilitate easier processing by a user of an endpoint reference, or because the metadata was dynamically generated

Tip

Please refer to the Endpoint Reference Information Model description for more information (http://www.w3.org/TR/ws-addr-core/#eprinfomodel)

Since the Reference Parameters and Metadata content model is of type xs:any, it can contain any valid XML element. So specify a Reference Parameter or Metadata, click on the equivalent Reference Parameters or Metadata link next to the EPR to which it should be added and specify a valid XML content that should be added to the EPR element

The figure below shows a sample Metadata information added to the ‘From’ EPR WSA header:

For the three EPRs (from, replyTo or faultTo), if either the address, reference parameters or metadata is specified, the equivalent WSA EndpointReferenceType element (wsa:From / wsa:ReplyTo / wsa:FaultTo ) will be added to the outbound SOAP request header.  

For e.g. the sample request below shows the WSA headers added when the ‘from’ address is not specified, but a valid Reference Parameters and Metadata values are specified.


<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/”>
    <Action xmlns="http://www.w3.org/2005/08/addressing">http://apache.org/hello_world_soap_http/Greeter/greetMeRequest
    </Action>
    <MessageID xmlns="http://www.w3.org/2005/08/addressing">urn:uuid:04feb301-7e50-4716-b745-57987cd63cfd</MessageID>
    <To xmlns="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing/anonymous</To>
    <From xmlns="http://www.w3.org/2005/08/addressing">
        <Address>http://xyz.com</Address>
        <ReferenceParameters>
            <MyRefParam xmlns="" xmlns:ns2="http://www.w3.org/2005/08/addressing">1234</MyRefParam>
        </ReferenceParameters>
        <Metadata>
            <ns:name xmlns:ns="http://xyz">test</ns:name>
        </Metadata>
    </From>
</SOAP-ENV:Header>

Configuring SOAP Request Attachments

Examine has support for sending attachments as part of the SOAP request to the WS endpoint. There are three ways to send binary content as part of a SOAP message:

Inline binary content as base64-encoded text

This approach involves converting the binary content of the file to be sent in base64-encoded form and embedding the text as part of the SOAP message. This is the least efficient way of sending binary data as it involves base64-encoding the content that typically bloats the size of the input data by 33%.

Soap with Attachments (SwA)

This approach involves sending the binary attachments in their native format in a multipart MIME structure. This is similar to how email messages are sent with attachments. There is a separate MIME part added to the message that contains the binary content in its native content type format. This is more efficient than the previous approach in that there is no base64-encoding of the binary content involved.

E.g. consider a WS that receives a SOAP message and expects a binary attachment using the SwA approach. Below is the request XML as configured in Examine:

The request XML takes the target destination where the file will be saved by the service (/ns:name) and the id of the attachment being sent to the service (/ns:attachmentID)

Below is the attachment configured in the Attachments tab under Request Configuration:

Figure 6.36. SOAP Scenario - Attachments

SOAP Scenario - Attachments


Note that the Enable MTOM checkbox is NOT enabled as we are using SwA. The CONTENT ID column in the table specifies the attachment id. This will be the value of the Content-ID header in the MIME part corresponding to the file attachment in the HTTP request.

The response XML for the above request sent with attachment is shown below:

Tip

Refer to the SwA specification for more information: http://www.w3.org/TR/SOAP-attachments

Message Transmission Optimized Mechanism (MTOM)

This approach is similar to the SwA approach in that the attachment is sent as a separate MIME part in the request message, but differs in the way the MIME part is referenced by the root part (SOAP message). SwA has a fundamental flaw in that the binary attachment is not part of the SOAP message and the receiving service must know how to reference the correct attachment in the request message. This usually involves specifying the attachment id as part of the message and the service must know in advance which element / attribute specifies the attachment id.

MTOM solves this problem by using the mechanism proposed by XML-binary Optimized Packaging or XOP (http://www.w3.org/TR/xop10/). XOP allows for separating the binary data from the XML message through the use of a special XML element called <xop:Include/> that references the attachment via a content identifier value. Thus the XML processor knows how access the specified reference and replace the contents of the element (with the <xop:Include/> with the attachment contents)

Tip

Refer to the SOAP-MTOM specification for more information: http://www.w3.org/TR/soap12-mtom/

Consider a WS that accepts a binary attachment with the following SOAP request content:

<?xml version="1.0" encoding="UTF-8"?>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Header/>
  <env:Body>
    <tns:AttachmentRequest xmlns:tns="http://ws.apache.org/axis2/mtomsample/">
      <tns:fileName>string value</tns:fileName>
      <tns:binaryData xmlns:xmime="http://www.w3.org/2005/05/xmlmime" xmime:contentType="">dGVzdA==</tns:binaryData>
    </tns:AttachmentRequest>
  </env:Body>
</env:Envelope>

The service expects a destination file name (tns:fileName) and the binary content to be transferred (tns:binaryData). The tns:binaryData element expects a base64-encoded binary content. But since we are using MTOM, the tns:binaryData element can specify a <xop:Include/> element with a reference to the attached MIME part.

Adding the <xop:Include/> element

Examine provides a convenient way to add the XOP Include element through the XML Tree view. To do this, right click on the element that should contain the <xop:Include/> element as shown below:

Figure 6.37. SOAP Scenario - MTOM Attachment - Adding XOP Include

SOAP Scenario - MTOM Attachment - Adding XOP Include


Tip

The XOP specification expects the <xop:Include/> element to be the only child of the element of type xs:base64Binary (http://www.w3.org/TR/xop10/#xop_include). So it is recommended to use the Raw XML view to send the request instead of the Tree / Formatted XML Views as they send the request with whitespace characters present in the message

The Add XOP Include button then prompts you to specify the value of the href attribute of the <xop:Include/> element as shown below:

Note

The Content ID value must not include the "cid:" prefix, as this will be added automatically to the specified value

Below is the attachment configured in the Attachments tab under Request Configuration

Note

The Enable MTOM checkbox must be enabled to use MTOM