Network Deployment (Distributed operating systems), v8.0 > Reference > Troubleshoot tips

Web services gateway troubleshooting tips

Use this set of specific tips to help you troubleshoot problems you experience when using the web services gateway.

To help you identify and resolve web services gateway-related problems, use the WAS trace and logging facilities as described in Trace and logging configuration .

To enable trace for the gateway, set the application server trace string to com.ibm.ws.sib.webservices.*=all=enabled:com.ibm.ws.wsgw.*=all=enabled. If you encounter a problem that you think might be related to the gateway, you can check for error messages in the WAS administrative console, and in the application server SystemOut.log file. We can also enable the application server debug trace to provide a detailed exception dump.

The web services gateway is implemented as an administrative layer on top of service integration bus-enabled web services. Therefore most known problems that you might experience when using the gateway are actually bus-enabled web services-related problems, and are documented in Bus-enabled web services troubleshooting tips.

WAS system messages are logged from a variety of sources, including application server components and applications. Messages logged by application server components and associated IBM products start with a unique message identifier that indicates the component or application that issued the message. The prefix for the web services gateway component is CWWSG and the prefix for the bus-enabled web services component is CWSWS.

The Troubleshooter reference: Messages topic contains information about the gateway and bus-enabled web services messages, indexed by message prefix. For each message there is an explanation of the problem, and details of any action that you can take to resolve the problem.

Here is a set of tips to help you troubleshoot commonly-experienced problems:

• When you pass messages directly to a bus destination, the default RPC-encoded web services string array message does not interoperate successfully with some target service providers.

• A SOAP over JMS web service message is sent by the web services gateway as a JmsBytesMessage, rather than a JmsTextMessage.

• If you create a gateway service, its WSDL description is not created in the SDO repository until you attempt to access the gateway service WSDL file through a web browser.

• You migrate a gateway from WAS v5.1 to a later version. When you try to access a gateway service, your client receives one or more error messages stating No response body is available, or Null response message, or The message body did not match any of the definitions in the WSDL.

• You choose to generate a web service client from the WSDL for the target service, rather than the gateway service. When you try to access the target service through the gateway, your client receives the following error message: CWSIF0304E: The message body did not match any of the definitions in the WSDL.

• You migrate a gateway that contains filters from WAS v5.1 to a later version, and your filters no longer work.

• When you migrated a gateway that contains filters from WAS v5.1 to v7.0 or later, destinations with names ending StorageQueue were created. These destinations are not removed automatically if you subsequently delete the migrated gateway.

• You have a client application that works under WAS v5.1, but under later versions you get problems caused by poorly-formed requests or responses.

• A JAX-RPC client running on WAS v5.1 uses SOAP over JMS to invoke a web service running on a v5.1 application server. No user ID or password is required on the target MQ Series queue. After the application server is migrated to a later version, and to use default messaging, client requests fail because basic authentication is now enabled.

• The gateway panels in the administrative console are only available in WAS Network Deployment if you are working with a dmgr profile.

When you pass messages directly to a bus destination, the default RPC-encoded web services string array message does not interoperate successfully with some target service providers.

We can pass messages directly to a bus destination by overriding the JAX-RPC client binding namespace and endpoint address. However:

• The default RPC-encoded web services string array message that is generated might not interoperate successfully with some target service providers.

• The string array message produced is not exactly the same as the standard JAX-RPC equivalent, which can interoperate successfully.

Here are examples of the two different messages:

• Service integration bus message:

  <partname env:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/
    xsi:type='ns1:ArrayOf_xsd_string'>
  <item xsi:type='xsd:anySimpleType'>namevalue
  </item>
  </partname>
  

• JAX-RPC client message:

  <partname xsi:type="soapenc:Array" soapenc:arrayType="xsd:string[1]">
  <item>namevalue
  </item>
  </partname> 

To modify the default behavior to send a string array message that is fully compatible with standard JAX-RPC, set the following JVM custom property. Setting this property modifies the default behavior for all outbound JMS web services invocations sent from the bus:

1. Start the administrative console.

2. Navigate to Servers -> Server Types -> WebSphere application servers -> server_name

   -> [Server Infrastructure] Java and Process Management -> Process Definition > [Additional Properties] Java Virtual Machine -> [Additional Properties] Custom Properties then click New.

3. Create the following JVM custom property. Note that the values shown are case sensitive.

   • Name: com.ibm.websphere.sib.webservices.useTypeSoapArray

   • Value: true

4. Restart the application server.

A SOAP over JMS web service message is sent by the web services gateway as a JmsBytesMessage, rather than a JmsTextMessage.

By default on WAS v6 or later, a SOAP over JMS web service message sent by the web services gateway is sent as a JmsBytesMessage, whereas on WAS v5.1 the web services gateway sends a JmsTextMessage.

To modify the default behavior to send a compatible JmsTextMessage, set the following JVM custom property. Setting this property modifies the default behavior for all outbound JMS web services invocations sent from the bus:

1. Start the administrative console.

2. Navigate to Servers -> Server Types -> WebSphere application servers -> server_name

   -> [Server Infrastructure] Java and Process Management -> Process Definition > [Additional Properties] Java Virtual Machine -> [Additional Properties] Custom Properties then click New.

3. Create the following JVM custom property. Note that the values shown are case sensitive.

   • Name: com.ibm.ws.sib.webservices.useSOAPJMSTextMessages

   • Value: true

4. Restart the application server.

If you create a gateway service, its WSDL description is not created in the SDO repository until you attempt to access the gateway service WSDL file through a web browser.

Every gateway service has an associated inbound service. The gateway service WSDL file is associated with this inbound service and should only be needed if the message originates from an inbound service. Therefore the WSDL description is created in the SDO repository the first time it is called by an inbound service or through a web browser.

If the applications are posting messages into the bus from sources other than the inbound service (for example if you are using mediation handlers to manipulate SDO messages to or from a gateway service), the applications should use either the WSDL associated with the target (outbound) service or some other compatible WSDL.

You migrate a gateway from WAS v5.1 to a later version. When you try to access a gateway service, your client receives one or more error messages stating No response body is available, or Null response message, or The message body did not match any of the definitions in the WSDL.

When the v5 gateway generates WSDL for a gateway service, the generated namespace contains the service name. For example: namespace="http://griddev:9080/wsgw#yourService". However in later versions the generated WSDL for a gateway service does not contain the service name. For example: namespace="http://griddev:9080/wsgw".

If your WSDL binding and encoding style is document literal then your clients still work with the migrated gateway, because document literal style does not use the namespace attribute. However, if you used the v5.1 gateway service WSDL to generate your web service clients and your WSDL binding and encoding style is not document literal, then after migration you must regenerate the client stubs by using the new gateway service WSDL.

You choose to generate a web service client from the WSDL for the target service, rather than the gateway service. When you try to access the target service through the gateway, your client receives the following error message: CWSIF0304E: The message body did not match any of the definitions in the WSDL.

The benefit of choosing to generate a web service client from the WSDL for the target service is that you can move between going to the target service directly or going through the gateway to the target service just by changing the URL in the generated stubs.

To enable this approach in this version of the gateway, use the administrative console to set the custom property com.ibm.websphere.wsgw.mapSoapBodyNamespace to false on each inbound service that is associated with a gateway service.

This approach is not flagged by default as a possible error in WAS v5.1, so you might encounter this problem for the first time when you migrate a gateway configuration from a v5.1 application server to the gateway capability on an application server on a later version. After migration, we have two choices:

• To retain the flexibility to reroute your messages by changing the URL in the generated stubs, set the custom property com.ibm.websphere.wsgw.mapSoapBodyNamespace to false as described above.

• If you no longer need this flexibility, regenerate the client stubs by using the gateway service WSDL of the later version.

You migrate a gateway that contains filters from WAS v5.1 to a later version, and your filters no longer work.

The use of filters was deprecated in v5.1.1 and support for filters was removed in v7.0. The role formerly played by filters is now undertaken by a combination of JAX-RPC handlers and service integration bus mediations. If you migrate a web services gateway that includes a routing filter, you can recreate the filter functions as described in Choosing a target service and port through a routing mediation.

When you migrated a gateway that contains filters from WAS v5.1 to v7.0 or later, destinations with names ending StorageQueue were created. These destinations are not removed automatically if you subsequently delete the migrated gateway.

These additional destinations were required to support existing v5.1 gateway filters in the v6 environment. Gateway filters are no longer supported, and so these "StorageQueue" destinations are no longer needed in v7.0 or later. However they are not removed automatically when you migrate to v7.0 or later or you delete the gateway instance.

During migration to v6, these additional destinations were created in one of the following two ways:

• If you specified the -Q parameter (shared filter correlation queue name), then a single queue destination of the specified name was created (if it did not already exist) and shared by all gateway services that had associated filters.

• If you did not specify the -Q parameter, then a separate queue destination was created for each gateway service that had associated filters. Each of these destinations has a name derived from the name of the corresponding gateway service request and reply destinations, and ending in StorageQueue.

After you delete the gateway instance, identify each associated storage queue destination by name, and delete it as described in Delete a non-topic space bus destination .

You have a client application that works under WAS v5.1, but under later versions you get problems caused by poorly-formed requests or responses.

Bus-enabled web services check the validity of web service messages more thoroughly than is done in WAS v5.1. As a result, some client applications that use poorly-formed requests or responses (where the message parts are misnamed), and that work when using v5.1, are identified as poorly-formed in later versions. For the steps to take to resolve the problem, see Toleration of poorly-formed SOAP messages

A JAX-RPC client running on WAS v5.1 uses SOAP over JMS to invoke a web service running on a v5.1 application server. No user ID or password is required on the target MQ Series queue. After the application server is migrated to a later version, and to use default messaging, client requests fail because basic authentication is now enabled.

The problem appears as a log message:

SibMessage    W   [:] CWSIT0009W: A client request failed in the application
server with endpoint
<endpoint_name> in bus your_bus with reason:
CWSIT0016E: The user ID null failed authentication in bus your_bus.

For the steps to take to resolve the problem, see the following service integration technologies troubleshooting tip: After you migrate a v5.1 application server to WAS v7.0 or later, existing web services clients can no longer use SOAP over JMS to access services hosted on the migrated server.

The gateway panels in the administrative console are only available in WAS Network Deployment if you are working with a dmgr profile.

The panels are not available in a WAS Network Deployment stand-alone server profile. However, the wsadmin command scripts that provide equivalent functions by using wsadmin are available for both the stand-alone and dmgr profiles. The gateway administrative commands cover all the main requirements, except for creating a new gateway instance. We can create a gateway instance and its associated default proxy WSDL location information through the wsadmin scripting client by using Jacl. Here is an example script:

### Jython

wsgwAttribs = []
wsgwAttribs.append(["name", wsgwName])
wsgwAttribs.append(["wsdlServiceNamespace", wsgwNamespace])
wsgw = AdminConfig.create("WSGWInstance", bus, wsgwAttribs )
wsgwWsdlAttribs = []
wsgwWsdlAttribs.append(["WSDLLocation", wsgwWsdlLocation])
AdminConfig.create("SIBWSWSDLLocation", wsgw, wsgwWsdlAttribs,  "defaultProxyWSDLLocation" )

### Jacl

set wsgwAttribs {}
lappend wsgwAttribs [list "name" $wsgwName]
lappend wsgwAttribs [list "wsdlServiceNamespace" $wsgwNamespace]
set wsgw [$AdminConfig create "WSGWInstance" $bus $wsgwAttribs]
set wsgwWsdlAttribs {}
lappend wsgwWsdlAttribs [list "WSDLLocation" $wsgwWsdlLocation]
$AdminConfig create "SIBWSWSDLLocation" $wsgw $wsgwWsdlAttribs
 "defaultProxyWSDLLocation"

In this example, bus or $bus is the ID of the service integration bus in which the gateway instance is created. For more information about the WAS AdminConfig object, enter "AdminConfig.help()" from the wsadmin command line.

+

Search Tips   |   Advanced Search