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 WebSphere® Application Server trace
and logging facilities as described in Tracing 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 WebSphere Application Server administrative console,
and in the application server SystemOut.log file.
You 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.
WebSphere Application Server 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 WebSphere Application Server Version 5.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 WebSphere Application Server Version 5.1 to a later version, and your filters no longer work.
- When you migrated a gateway that contains filters from WebSphere Application Server Version 5.1 to Version 7.0, 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 WebSphere Application Server Version 5.1, but under later versions you get problems caused by poorly-formed requests or responses.
- A JAX-RPC client running on WebSphere Application Server Version 5.1 uses SOAP over JMS to invoke a web service running on a Version 5.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 WebSphere Application Server Network Deployment if you are working with a deployment manager 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.
You 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:
- Start the administrative console.
- Navigate to then
click New.
- Create the following JVM custom property. Note that the values
shown are case sensitive.
- Name: com.ibm.websphere.sib.webservices.useTypeSoapArray
- Value: true
- 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 WebSphere Application Server Version 6 or later, a SOAP over JMS
web service message sent by the web services gateway is sent as a
JmsBytesMessage, whereas on WebSphere Application Server Version 5.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:
- Start the administrative console.
- Navigate to then
click New.
- Create the following JVM custom property. Note that the values
shown are case sensitive.
- Name: com.ibm.ws.sib.webservices.useSOAPJMSTextMessages
- Value: true
- 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
your 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 WebSphere Application Server Version 5.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 Version 5 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 Version 5.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.
Note: This
approach is not flagged by default as a possible error in
WebSphere Application Server Version 5.1, so you might encounter
this problem for the first time when you migrate a gateway configuration
from a
Version 5.1 application
server to the gateway capability on an application server on a later
version. After migration, you have two choices:
- If you want 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 WebSphere Application Server Version 5.1 to a later version, and
your filters no longer work.
The use of filters was deprecated in Version 5.1.1 and support for filters was removed in Version 7.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 WebSphere Application Server Version 5.1 to Version 7.0, 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 Version 5.1 gateway
filters in the Version 6 environment.
Gateway filters are no longer supported, and so these "StorageQueue" destinations
are no longer needed in Version 7.0.
However they are not removed automatically when you migrate to Version 7.0 or you delete the gateway
instance.
During migration to
Version 6, 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 Deleting a non-topic
space bus destination .
You have a client application that works
under WebSphere Application Server Version 5.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 WebSphere Application Server Version 5.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 Version 5.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
The gateway panels in the administrative
console are only available in WebSphere Application Server Network Deployment if
you are working with a deployment manager profile.
The panels
are not available in a
WebSphere Application Server Network Deployment stand-alone
server profile. However, the wsadmin command scripts that provide
equivalent functions by using the wsadmin tool are available for both
the stand-alone and deployment manager profiles. The
gateway administrative
commands cover all the main requirements, except for creating
a new gateway instance. You 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:
- Using 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" )
- Using 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
WebSphere Application Server AdminConfig object,
enter
"AdminConfig.help()" from the
wsadmin command
line.