Access web services using web service bindings

Web services are self-contained applications that perform business functions, ranging from a simple query to complex business process interactions. You can use either of two bindings to invoke web services - a web service binding or an HTTP binding. This topic discusses generating and configuring web service bindings to call web services.


Generating web service bindings for exports

Create a web service binding as an easy way to offer web services. Bindings for imports and exports have different purposes. An import binding describes the specific way an external service is bound to an import component. An export binding describes how that export (or service) will be published or made available to clients outside the module.

The kind of binding determines what kind of client is supported; a web service binding makes the service available to any web-based client.

When use the palette in the assembly editor to create an export, you can generate a web service binding by following these steps:

  1. If there is no interface defined on the export, add the interface first. See related tasks for instructions on adding the interface.

  2. Under Inbound Exports, drag Web Service onto the canvas. Add your interface.
  3. Alternately, under Components, drag an export onto the canvas. Right-click the export and select Generate Binding > Web Service Binding.

  4. Select one of the following transports and click Next:

    1. SOAP1.2/HTTP: Select this transport if your web service conforms to the SOAP 1.2 specification. This selection is based on the Java API for XML Web Services (JAX-WS), a Java programming API for creating web services.
    2. SOAP1.1/HTTP (default): Select this transport if your web service conforms to the SOAP 1.1 specification. This selection is also based on the JAX-WS API.
    3. SOAP1.1/HTTP using JAX-RPC: Select this transport to create web services that use a SOAP-encoded message based on the Java API for XML-Based RPC (JAX-RPC).
    4. SOAP1.1/JMS: Select this transport if your web service conforms to the SOAP 1.1 specification and receives requests from a JMS queue. Note the interaction style of SOAP/JMS is synchronous.

      JAX-RPC versus JAX-WS describes the differences between the two web services programming models.

  5. The Set the Web Service Binding Target Namespace page opens. Select whether you want to use the same namespace as the interface or create a new one:

    • Use the port type (interface) namespace - This selection is best suited if you will be merging this service later with other artifacts and exporting everything in a single file. In such cases, the export is simplified if all artifacts share the same namespace.

    • Specify a new namespace - This selection is suitable to have a unique namespace for your service.

  6. A web service binding is generated without requiring you to supply additional information. Click the Binding tab in the Properties view to see the generated port and service and their namespace. The location of the port is the same as the location of the interface. You can see the port in the Business Integration view.

  7. Optional: Double-click the binding or the port in the Business Integration view to open the WSDL editor to see the WSDL description and edit it if necessary.


The binding will be generated for the export and its icon will change to indicate the type of binding that it has. To change the binding for an export, you can use Regenerate Binding or Remove Binding actions. Exports have binding properties that can be modified in the Properties view. Select the export in the assembly diagram to see its properties in the Properties view.



Generating web service bindings for imports

Create a web service binding as an easy way to consume web services. Bindings for imports and exports have different purposes. An import binding describes the specific way an external service is bound to an import component. An export binding describes how that export (or service) will be published or made available to clients outside the module.

When use the palette in the assembly editor to create an import, you can generate a web service binding by following these steps:

  1. If there is no interface defined on the import, add the interface first or generate an interface by wiring the import to an SCA component. See the related tasks for instructions on adding the interface.

  2. Under Outbound Imports, drag Web Service onto the canvas. Add your interface.
  3. Alternately, under Components, drag an import onto the canvas. Right click the import and select Generate Binding > Web Service Binding. Because the import will connect to some specific service outside the module, identify that service. The editor cannot generate the binding automatically, as it can in some circumstances for an export.

  4. In the Import Details window box, choose one of the three options described below. The first choice sensible choice for most situations.

    • Choose an existing web service port to use for the binding. The port must be in the module or in a shared library. Click Browse to see which ports are available. The editor extracts the needed information from the port WSDL file.
    • Generate a new web service definition and implementation. This choice is for advanced users. Options differ depending on whether you are working top-down (creating an import before creating an export) or bottom-up (you are choosing an existing export from which to import a service). The Web Services wizard will guide you through the choices you need to make and provide a skeleton of what to implement.
    • Do not specify a web service port at this time. To complete the binding in this approach, add details in the Properties for this import's binding. If you are creating the import using the palette, you will have to specify a binding type for the external service technology in order to test it.

  5. If you made the second selection, the Set the Web Service Binding Target Namespace page will also be used. Select whether you want to use the same namespace as the interface or create a new one:

    • Use the port type (interface) namespace - This selection is best suited if you will be merging this service later with other artifacts and exporting everything in a single file. In such cases, the export is simplified if all artifacts share the same namespace.

    • Specify a new namespace - This selection is suitable to have a unique namespace for your service.

  6. The binding will be generated and its icon will change to indicate the type of binding that it has.

  7. Optional: IBM recommends set the Join Transaction qualifier so the import performs the invocation within a transaction. See related information for more details about configuring the Join Transaction qualifier.


To change the binding for an import, you can use Regenerate Binding or Remove Binding actions. Imports have binding properties that can be modified in the Properties view. Select the import in the assembly diagram to see its properties in the Properties view.

If you have created a web service port and you drag it onto the assembly editor in order to regenerate a binding, you will only generate a JAX-RPC binding. To properly regenerate with a choice of bindings, you need to remove the binding and then add another one.



Generating web service bindings for service gateway

Create web service bindings for your service gateway.

You can quickly create all of the starter artifacts for a service gateway, including the data handlers, interfaces and bindings described here, by using pattern generators provided in the Patterns Explorer.

Bindings for imports and exports have different purposes. An import binding describes the specific way an external service is bound to an import component. An export binding describes how that export (or service) will be published or made available to clients outside the module.


Generating the export web service bindings

To use the service gateway with the web service binding, follow these steps for an export:

  1. Add the service gateway interface and schema to your module.

    1. Double-click Dependencies to open the Dependency Editor.

    2. Expand the Predefined Resources section.

    3. Select Service gateway interface.

    4. Select Native Body schema for Native Body DataHandler.

  2. In the Business Integration View, expand your project's Data and Interfaces category. Note the data types and ServiceGateway interface that are created under the StandardImportFilesGen folder in each category.
  3. When you add the interface to your export, select ServiceGateway as your interface.
  4. In generating your web service binding, you will be given the following choice:

    • SOAP1.2/HTTP (default): Select this transport if your web service conforms to the SOAP 1.2 specification. This selection is based on the Java API for XML Web Services (JAX-WS), a Java programming API for creating web services.
    • SOAP1.1/HTTP: Select this transport if your web service conforms to the SOAP 1.1 specification. This selection is also based on the JAX-WS API.

  5. Click OK and the web service binding is generated.
  6. Once generated, in the Binding tab of the Properties view, you will see the service gateway address, port, service name and namespace, which can be modified. Advanced properties shows the function selector, which determines the operation that will be invoked on the SCA application, and the data format for the service gateway. The advanced properties are discussed in Advanced properties for service gateway.


Generating the import web service bindings

To use the service gateway with the web service binding, follow these steps for an import:

  1. Add the service gateway interface and schema to your module.

    1. Double-click Dependencies to open the Dependency Editor.

    2. Expand the Predefined Resources section.

    3. Select Service gateway interface.

    4. Select Native Body schema for Native Body DataHandler.

  2. In the Business Integration View, expand your project's Data and Interfaces category. Note the data types and ServiceGateway interface that are created under the StandardImportFilesGen folder in each category.
  3. When you add the interface to your import, select ServiceGateway as your interface.
  4. In generating your web service binding, you will be given the following choice:

    • SOAP1.2/HTTP (default): Select this transport if your web service conforms to the SOAP 1.2 specification. This selection is based on the Java API for XML Web Services (JAX-WS), a Java programming API for creating web services.
    • SOAP1.1/HTTP: Select this transport if your web service conforms to the SOAP 1.1 specification. This selection is also based on the JAX-WS API.

  5. Click OK and the web service binding is generated.
  6. Once generated, in the Binding tab of the Properties view, you will see the service gateway address, port, service name and namespace, which can be modified. Advanced properties shows the data format for the service gateway. The advanced properties are discussed in Advanced properties for service gateway.


Additional service gateway information

A service gateway with a web service binding allows routing to multiple endpoints. Requests can have headers, body, or both manipulated with a mediation module before being forwarded onto the service provider. Service gateway with web service bindings shows you how to set up two types of service gateways, a static service gateway and a dynamic service gateway, including the setup for the runtime.



Advanced properties for service gateway

Additional properties that you would use if your application works with the service gateway are discussed.

If you are using the service gateway with an application that has web services bindings, you may need to configure some additional fields.


Export

To configure an export for the service gateway follow these steps:

  1. Select the Binding tab and expand Advanced properties.

  2. In the Function selector field, select the function selector. A function selector determines the operation that will invoked in the Service Component Architecture (SCA) application. There will be only one choice.

  3. In the Data format field, select the data format transformation. A data format transformation transforms the data format in a native environment to the data format expected by an SCA application. For example, the incoming data from a web services client might be in a text data format and the data is transformed into an XML data format for the SCA application. This data format transformation also works from the SCA application to the client. There will be only one choice.

    Save your configuration.


Import

Configure your import for the service gateway is the same as configuring an export. However, there is no function selector on the import. Only the data format transformation selection is needed. There will be only one choice.



Work with attachments

Attachments provide a way to pass additional information in a message in an efficient manner by holding the attachment data separate from the message body. For example, a SOAP message or email might contain a person's resume with an attachment that holds the person's photograph.

The following sections provide some conceptual information on attachments.


Bindings and protocols that can be used with attachments

Only the Java API for XML Web Services (JAX-WS) based binding supports attachments in version 6.2.0.1 or higher. Only the SOAP 1.2/HTTP or SOAP1.1/HTTP transport protocols can be used with attachments.


Types of attachments

There are four types of attachments: MTOM, referenced, swaRef type and unreferenced.

MTOM attachments use the SOAP Message Transmission Optimization Mechanism (MTOM) (http://www.w3.org/TR/soap12-mtom/) specified encoding. MTOM attachments are enabled through a configuration option in the import and export bindings as described in Enable MTOM support in JAX-WS bindings and should be used to encode attachments for new applications. Note the MTOM optimization is only available for the xs:base64Binary data type.

Referenced attachments are referenced from the SOAP body; that is, the attachment is defined in the WSDL portType schema for the input or output message for the operation, and the reference appears in the SOAP body as an element that references the attachment using the attachment's content-Id. Referenced and swaRef-type attachments shows you how to create a referenced attachment.

A SOAP with attachment (swaRef) type attachment uses the Web Services Interoperability Organization (WS-I) Attachments Profile. Referenced and swaRef-type attachments shows you how to create a swaRef-type of attachment.

Unreferenced attachments do not have a reference from the SOAP body to the attachment. Unreferenced attachments are discussed in the next section.

In any of the types of attachments, the attachment data itself does not appear inline in the SOAP body XML.


Unreferenced attachments

Unreferenced attachments do not have a reference from the SOAP body to the attachment.

Unreferenced attachments are not modeled in the WSDL portType of messages and do not appear in the business object representation. They can only be accessed through the Service Message Object (SMO). Each attachment appears as a separate element in the attachments list of the SMO. See Service message objects.


Threshold attribute for MTOM

For MTOM enablement, the threshold attribute is used to determine if an attachment is needed for the binary data. If the binary data size is greater than or equal to the value of the threshold, an attachment is generated for that binary data. The exception to this behavior is if a pass-through scenario exists and in that case, the threshold value is ignored for the outgoing message. The pass-through scenario may be one of following situations:

  1. Export (MTOM in) -- connected directly --- Import (MTOM out)
  2. Export (MTOM in) -- MFC (do nothing or do not touch data in MFC ) --- Import (MTOM out)

In both situations, the incoming MTOM SOAP message will be XML semantically equal to the outgoing MTOM SOAP message.


Routing, storing and manipulating attachments

Use a mediation flow, you can route, store or manipulate an attachment passed in as a SMO attachment. You could route the attachment based on the type of attachment, or use a custom primitive to load or save attachment data. See Building mediation flows to see how to route, store, and manipulate elements in messages with mediation flows.


Testing attachments

You can test applications that use attachments in the same way as other applications. The Integration Test Client can be used with little difference in how you use it to test an application using attachments. See Testing Web Service exports with SOAP messages. Note that you must have enabled your server to work with attachments.


Security

A Web Services Security (WS-Security) policy set can be applied when using attachments, however, any privacy or integrity settings will not apply to the attachment data. In order to secure the entire message when using attachments, you should enable transport level security using HTTPS instead of HTTP, by attaching an appropriate policy set. This makes the entire HTTP message secure, including attachments


Limitations



Referenced and swaRef-type attachments

Referenced and swaRef-type attachments can be added to exports with a web services binding.

The following types of attachments are discussed in this section:


Referenced attachments

Referenced attachments allow you to model an attachment in a WSDL file. For example, you might want to send a resume of an employee to a web service from an application created in IBM Integration Designer. In that resume, you might want to include an attachment for a picture of the employee.

To support SOAP messages with referenced attachments for exports, the interface operations must use the document literal non-wrapped binding style or the RPC literal binding style (see Binding style) and the input or output in the operation containing the reference must be binary. Furthermore, the WSDL binding must contain a MIME transport binding. A MIME transport binding is handled for you when use the editors in IBM Integration Designer. Since referenced attachments involve multi-part messages, you should read using document binding style with multi-part messages for an understanding of how the Web Services Interoperability (WS-I) standard and binding style are related.

Referenced attachments can be modeled by using the interface editor. The following steps show you how to model the attachment.

These steps assume that you have a module with an interface that contains one or more input operations. The instructions also assume that you have an export and the interface has been added to it.

  1. Open your interface in the interface editor.

  2. In the interface editor, select the operation or that will contain a referenced attachment. If the binding style is not Document/literal non-wrapped, click Change binding style to document/literal non-wrapped and change the binding style.

  3. In the Type column, select a binary type, for example, hexBinary, for those inputs and outputs that will be passing an attachment.

  4. Click the Properties tab and select an input or output with the binary type.
  5. Beside the Binary content type box, click Add. The Select Binary Content window opens.

  6. In the Binary content type field, select the type category, for example, image/jpg, or type it in the field.

  7. Click OK.

  8. In the assembly editor, right-click your export and select Generate Binding > Web Service Binding. The Transport Protocol Selection wizard opens.

  9. Depending on the SOAP release to use, select one of the following:

    • SOAP1.2/HTTP
    • SOAP1.1/HTTP

    Both of these options support the Java API for XML Web Services (JAX-WS).

  10. Click Finish. If you have selected at least one binary type to use as an attachment, the new WSDL binding file will be generated with a MIME transport binding.
  11. Deploy your application and run it.


swaRef-type attachments

Use the Web Services Interoperability Organization (WS-I) Attachments Profile, you can pass a SOAP with attachment (swaRef) type attachment.

To pass an attachment as a swaRef type using the WS-I Attachments Profile, follow these steps:

  1. Add the WS-I attachment profile to your module. Open Dependencies in the Business Integration view and in the Predefined Resources section select WS-I attachment profile 1.0 swaRef schema file. Save your work.
  2. To add an attachment in a business object, create a business object and for the type select swaRef, which will be available since you added the schema previously.
  3. To add an attachment as a type for an input or output to an operation, create the operation in the interface. Add an input or output to the operation. If using the business object created previously then select the business object as the type to your input or output. If you are not using the business object created earlier, add another input or output and select swaRef as the type.
  4. Generate the binding, deploy the your application and run it.


WS-I compliance with SOAP messages

When working with attachments, previous versions of IBM Integration Designer handled Web Services Interoperability (WS-I) compliance for SOAP messages automatically. A page in the wizard to generate a web services binding lets you select either this previous automatic configuration or lets you choose which of the non-binary parts of an operation should be bound to the message body.

This page in the wizard will only appear if you selected a document literal non-wrapped binding style, which is used for operations with attachments. It lets you choose if your SOAP message will follow the WS-I Attachments Profile 1.0 specification or use an automatic configuration used in earlier versions of IBM Integration Designer.


Export

This page opens after you have selected the transport protocol and the target namespace.

  1. In the Specify WS-I compliance page, select one of the following options:

    • Use WS-I compliant SOAP message: Select this option if you want your SOAP message to comply to the WS-I Attachments Profile 1.0 specification. In this specification, only one non-binary part can be bound to the SOAP body. On the following page you can see the current non-binary part selected and can make a different selection if there are multiple parts. Click Next.

    • Use non WS-I compliant SOAP message (default): This option will automatically handle the configuration though the result is not compliant to the WS-I Attachments Profile 1.0.

  2. If you selected Use WS-I compliant SOAP message and clicked Next, the Set the part to bind to the SOAP body page opens. In a WS-I compliant SOAP message, only one non-binary part can be bound to the SOAP body. For inputs and outputs with multiple non-binary parts, select the one that you want bound to the SOAP body and click Finish.


Import

For an import the page is the same, but the order to get to the page is different. For an import, the selection Generate a new web service definition and implementation leads you to the sequence described previously for an export.



Policy sets

Policy sets reduce the complexity of configuring web services by providing reusable configurations.

A policy set is a collection of policy types, each of which provides a quality of service. These types have been configured and can be associated with a web service provider or consumer. Policy sets work in pairs. You must have the same policy set on the service requester as on the service provider. Therefore, on an export, you should have the same policy set on the export binding as on the client. On an import, you should have the same policy set on the import binding as on the service provider it is calling.

A policy set can be associated with imports and exports. Only the SOAP1.2/HTTP and the SOAP1.1/HTTP transport protocols support policy sets. A policy set cannot be associated with the SOAP1.1/HTTP using JAX-RPC transport protocol.

In this section, we show you where to find the policy set properties and how to set them on the web services binding.

  1. To see the policy set properties, select your import or export and then select the properties view.

  2. Click the Policy Sets tab.
  3. No policy set is specified by default. To select a policy set for your operations, make your selection from the drop-down list of the Default policy set field. A description is shown for each policy set.

    The complete list of available policy sets with BPM including a description of each one can be found by selecting Window > Preferences from the menu bar and selecting Service Policies from the list of preferences.

  4. Select a binding from the Binding drop-down list. It is used to configure how the server implements the default policy set. A description is shown for each binding.
  5. Once you have selected your policy set and binding, save the configuration.

Policy sets can be exported from a WebSphere server as discussed in Export policy sets to client or server environments. To import a policy set into IBM Integration Designer, use the import utility (File > Import from the menu bar). Select Web services > WebSphere Policy Sets on the following page and import the policy set.

A WS-Security policy set cannot be applied to unreferenced attachments. You can use transport level security, that is, HTTPS instead of HTTP, which makes the entire HTTP message including attachments secure.

More information on policy sets can be found in the IBM Redbook WAS Web Services Guide. If security is important for your application, this book also contains a section called on secure conversation that you should read.



Endpoint updates in a web services binding

Web services can be moved to a different server. You should know how to change the endpoint URL address in such cases as the endpoint provides the server location of the web service you are using.


Endpoint updates in a unit test environment

During the development and testing of a web service, you can update an endpoint address in either the properties view of the web services binding or in the WSDL editor.

To update an endpoint from the binding properties view, select the import or export in the assembly editor and open the Properties view. Select the Bindings tab. The endpoint can be viewed and updated from the Address field.

To update an endpoint from the WSDL editor properties view for a web services import binding, click the canvas and open the Properties view. Select the General tab. The endpoint can be viewed and updated from the Address field.

You cannot update the endpoint value in the Address field of a web services export binding.


Endpoint updates in a production environment

After you have deployed a service to a server in a production environment, you can still change an endpoint by using the Process Admin Console.

To change the endpoint on a production server, see Administer bindings. Each binding has a section on viewing and updating the binding information including the endpoint URL.



10. JAX-WS handlers

JAX-WS handlers can be used with the web services binding.

A JAX-WS handler provides a range of handling tasks. For example, a JAX-WS handler could log a message, or transform an incoming or outgoing message. JAX-WS handlers can be chained together to produce complex operations.

There are two types of JAX-WS handlers - logical and protocol. Logical handlers process the message payload and the properties stored in the message context. Protocol handlers operate on protocol-specific messages and message context properties. Currently, only SOAP-specific configurations are implemented.

A JAX-WS handler can be used with an export or an import.

You can create your own JAX-WS handler. If you do, the classes in your JAX-WS handler must implement the javax.xml.ws.handler.LogicalHandler or the javax.xml.ws.handler.soap.SOAPHandler interfaces. Alternately, you can choose to create a JAX-WS handler at the time you work in the properties with them. In making a selection of the handler type, one of these interfaces will be chosen.


Exports

To work with JAX-WS handlers, open the properties view of the export and click the JAX-WS handlers tab.

Follow these steps to work with the JAX-WS handlers:

  1. To add a JAX-WS handler, click Add in the left pane. The available handlers are listed in a handler selection window. You may also create a JAX-WS handler at this time by clicking New, selecting a handler type (SOAP or logical handler), and proceeding with the wizard to create a new JAX-WS handler.

  2. Select the handlers you want to consider for your binding. They are added to a list which you can order. You can also make deletions from the list.
  3. Once you have the handlers you want to work with, select one you want to examine for your binding and its properties are then shown on the right pane.
  4. Once you have made your selection of a handler for your binding and possibly updated the message context properties, save the file.


Imports

To work with JAX-WS handlers, open the properties view of the import and click the JAX-WS handlers tab.

The steps to work with and select a JAX-WS handler for your import binding are the same as an export.


11. SOAP header information with a JAX-WS handler

SOAP header information can be passed to an SOA application by creating a JAX-WS handler and a schema.

Often a specific application needs to manipulate a SOAP header before execution sends the header to the SOAP components. For example, you may want to add a SOAP header, remove a SOAP header or access a SOAP header. To do this, you need to add a JAX-WS handler or JAX-RPC handler to manipulate the SOAP header with Java code. IBM recommends you have a corresponding schema created as well. This section provides an example of the code you would create


Create a JAX-WS handler for SOAP header information

To create a JAX-WS handler to access SOAP header information, first create a basic JAX-WS handler for your export or import. It will create stubs for the methods. You next need to implement the handleMessage method. The following code demonstrates how to create a SOAP header by using APIs in the javax.xml.soap package.

At the beginning of the code, comments indicate the XML output that will result from the handler. To produce that output we create the header entry element followed by two child elements. The first child element has a client type that identifies a JAX-WS client. The second child element has an attribute, which is the information we are looking for in the SOAP header. Our handler creates a user ID identified by an email address.

public boolean handleMessage(SOAPMessageContext context) {

  try {
   SOAPFactory factory = SOAPFactory.newInstance();

   SOAPMessage m = context.getMessage();
   SOAPPart sp = (SOAPPart) m.getSOAPPart();
   SOAPEnvelope soapEnv = sp.getEnvelope();
   SOAPHeader soapHeader = soapEnv.getHeader();

   // the following XML instance will be created by the code below.
   // <hc:Header1ContextElement
   // soapenv:mustUnderstand="0"
   // xmlns:hc="http://JaxwsHandlerTest">
   // <hc:client_type>jaxws client</hc:client_type>
   // <hc:user_id hc:id_type="email">joe@ca.ibm.com</hc:user_id>
   // </hc:Header1ContextElement>

   // create header entry element.
   Name headerContextName = soapEnv.createName(
     "Header1ContextElement", "hc", "http://JaxwsHandlerTest");
   SOAPHeaderElement soapHeaderElement = soapHeader
     .addHeaderElement(headerContextName);
   // mustUnderstand attribute is used to indicate    // whether the header entry is mandatory or optional for the    // recipient to process.
   soapHeaderElement.setMustUnderstand(false);

   // create the first child element and set the value    SOAPElement element1 = soapHeaderElement.addChildElement(
     "client_type", "hc");
   element1.setValue("jaxws client");

   // create the second child element    SOAPElement element2 = soapHeaderElement.addChildElement("user_id",
     "hc");
   // create and set the attribute of second child element.
   Name attributeName = soapEnv.createName("id_type", "hc",
     "http://JaxwsHandlerTest");
   element2.addAttribute(attributeName, "email");
   // set the element value    element2.setValue("joe@ca.ibm.com");

  } catch (SOAPException e1) {
   // TODO Auto-generated catch block
   e1.printStackTrace();
  }

  return true;
 }


Create a schema for a SOAP header

Next, we create a schema for our SOAP header. It is in fact good programming practice to always create a schema for your SOAP messages though IBM Integration Designer does not force you do so. However, create a schema to access SOAP header information in an SCA component. You can create this schema with the Business Object editor or the XML Schema editor.

In the code that follows, we specify a client type element and a user ID element within the header entry element. The namespace name matches the previous one in the JAX-WS handler, JaxwsHandlerTest.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://JaxwsHandlerTest"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:Q1="http://JaxwsHandlerTest">
 <xsd:element name="Header1ContextElement">
  <xsd:complexType>
   <xsd:sequence>
    <xsd:element name="client_type" type="xsd:string" />
    <xsd:element name="user_id">
     <xsd:complexType>
      <xsd:simpleContent>
       <xsd:extension base="xsd:string">
        <xsd:attribute name="id_type" type="xsd:string" />
       </xsd:extension>
      </xsd:simpleContent>
     </xsd:complexType>
    </xsd:element>
   </xsd:sequence>
  </xsd:complexType>
 </xsd:element>
</xsd:schema>



12. Enable MTOM support in JAX-WS bindings

IBM Integration Designer (IID) provides configuration options to enable JAX-WS bindings to send and receive web service messages which include SOAP Message Transmission Optimization Mechanism (MTOM) attachments. This mechanism improves the transmission efficiency of large binary attachments in SOAP messages.

Before configuring a JAX-WS import or export binding to enable MTOM support, note that not all scenarios are supported:

SOAP messages that use the MTOM specification can be sent and received by enabling support in IBM Integration Developer using JAX-WS import and export binding properties.

  1. In IBM Integration Developer, using the Properties for the export or import, click the Binding tab and select the MTOM check box. This will enable the optimization of the transmission of binary data in the SOAP attachment.

  2. Optionally, you can provide an integer value greater than or equal to zero in the Threshold field to indicate the minimum size of binary data to be sent using MTOM. When sending requests from an import or responses from an export, any binary data whose length is greater than or equal to this value will be sent using MTOM. Binary data whose length is less than this value is inlined in the XML document. A value of zero indicates that all binary elements should be sent using MTOM. Note that this value is a hint to the runtime and under some circumstances the value may not apply. For example, where a binary element is received as an attachment from a client using a lower threshold value, the element may remain as an attachment and may not be moved inline into the XML document.



13. Propagation

Context propagation lets you take information associated with a runtime or an application and pass it along with requests that are the result of interactions with that runtime or application.

The following sections describe the aspects of propagation:


Types of propagation

There are several types of context information, which are selectable from the Propagation tab of a binding's properties.

Context propagation is available on both imports and exports with the exception of propagation of the operation name used only on an MQ import binding. SCA imports always propagate the system context.

A context service is responsible for propagating the context (including the protocol headers, such as the JMS header, and the user context, such as account ID) along a Service Component Architecture (SCA) invocation path.

When the context service propagation is bi-directional, that is, a request-response situation, the response context will always overwrite the current context. When you are running an invocation from one SCA component to another, a response will contain a different context. A service component will have an incoming context, but when you invoke another service, the other service will overwrite the original outgoing context. The response context becomes the new context.

When the context service propagation is one-way, the original context remains the same.


Lifecycle of a context service

The lifecycle of a context service is associated with an invocation. A request has associated context, and the lifecycle of that context is bound to the processing of that particular request. When that request is finished processing, then the lifecycle of that context ends.

For a short-running Business Process Execution Language (BPEL) process, the response context overwrites the request context. It takes the response context back from the first request and pushes it to the next request. For a long-running BPEL process, the response context is discarded by the BPEL framework. It stores the original context and uses that context when making other outgoing calls.

For example, the context including a protocol header is propagated throughout the invocation path starting with a request coming in to BPEL from a SOAP web service. The BPEL processes it, and calls out of BPEL are made sequentially to a web service binding outbound, and then to another web service binding outbound. A request from the SOAP web service uses the context service to pass on the protocol header. It takes the context service from the inbound request and pushes the protocol header outbound.


Use propagate system context

This property passes system information in the context. It is selected by default. SCA imports always propagate the system context.

System information is helpful when debugging an application that involves multiple environments such as clients and servers using various protocols and operating systems. Since the context is passed through the environments, you can effectively trace errors to a particular system. This system information is displayed in the server logs view, a view which is typically used when debugging an application using cross component trace.

There is a slight cost to performance for having this property selected.


Set up propagation context in a client

The following code shows how you would setup a context on the client to be used with propagation support in your modules.

//Import the necessary classes;
import com.ibm.bpm.context.ContextService;
import com.ibm.websphere.bo.BOFactory;
import com.ibm.websphere.sca.ServiceManager;
import com.ibm.websphere.sibx.smobo.HeadersType;
import com.ibm.websphere.sibx.smobo.SOAPHeaderType;
import com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory;
import commonj.sdo.DataObject;

//Locate ContextService;
ContextService contextService = (ContextService)ServiceManager.INSTANCE.locateService("com/ibm/bpm/context/ContextService");

//Get the protocol headers;
HeadersType smoHeaders = contextService.getHeaders();

//operate the protocol headers;
.....

//set the modified protocol headers back to ContextService;
contextService.setHeaders(smoHeaders);

See Service message objects for more information on context and its structure in a message.


14. Use SOAP-encoded arrays

Passing SOAP-encoded arrays can cause problems if not understood.

Though commonly used in web services, SOAP-encoded arrays can cause problems when used with Web Service Description Language (WSDL) based applications. SOAP-encoded arrays are often created when you work with tools from Microsoft. SOAP-encoded arrays are not Web Services Interoperability (WS-I) compliant, which is the standard for IBM Integration Designer.

Since these arrays are sometimes used with a web services binding based on JAX-RPC, IBM Integration Designer provides a quick fix that you can use should errors appear in the problems view. The quick fix changes the XML Schema Definition (XSD) using these arrays to have an unbounded attribute assigned to the field using the array type. In most cases, this quick fix will resolve problems with this kind of array.

You should only use SOAP-encoded arrays with the JAX-RPC transport protocol.


15. Limitations of the web services binding

Limitations of using the web services binding are discussed.


Headers propagation

Some web service bindings do not propagate the header part of message.


Web services bindings in the same module

The following combinations of web service bindings cannot be used on exports in the same module. If you need to expose components using more than one of these export bindings, you need to have each in a separate module and then connect those modules to your components using the SCA binding:



+

Search Tips   |   Advanced Search