Why and when to perform this task
To identify and resolve Web Services Invocation Framework (WSIF)-related
problems, you can use the standard WebSphere Application Server trace and logging facilities. If you encounter a problem
that you think might be related to WSIF, you can check for error messages
in the WebSphere Application Server administrative console, and in the application
server stdout.log file. You can also enable the application
server debug trace to provide a detailed exception dump.
A list of the
WSIF run-time system messages, with details of what each message means, is
provided in Message reference
for WSIF.
A list of the main known restrictions that apply when
using WSIF is provided in WSIF
- Known restrictions.
Here is a checklist of major WSIF activities,
with advice on common problems associated with each activity:
- Create service
- Handcrafted WSDL can
cause numerous problems. To help ensure that your WSDL is valid, use a tool
such as WebSphere Studio to create your service.
- Define transport mechanism
- For the Java Message Service (JMS), check that you have set up the Java
Naming and Directory Interface (JNDI) correctly, and created the necessary
connection factories and queues.
- For SOAP, make sure that the deployment
descriptor file dds.xml is correct - preferably by creating
it using WebSphere Studio or similar tooling.
- Create client - Java code
- Follow the correct format for creating a WSIF service, port, operation
and message. For examples of correct code, see the Address Book Sample.
- Compile code (client and service)
- Check that the build path against code is correct, and that it contains
the correct levels of JAR files.
- Create a valid EAR file for your service in preparation for deployment
to a Web server.
- Deploy service
- When you install and deploy the service EAR file, check carefully any
messages given when the service is deployed.
- Server setup and start
- Make sure that the WebSphere Application Server server.policy file
(in the /properties directory) has the correct security settings.
For more information, see Enabling
security for WSIF.
- WSIF setup
- Check that the wsif.properties file is correctly set
up. For more information, see Maintaining
the WSIF properties file.
- Run client
- Either check that you have defined the class path correctly to include
references to your client classes, WSIF JAR files and any other necessary
JAR files, or (preferably) run your client using the WebSphere Application
Server launchClient tool.
Here is a list of common errors, and information on their
probable causes:
- "No class definition" errors received when running client
code.
This problem usually indicates an error in the class
path setup. Check that the relevant JAR files are included.
- "Cannot find WSDL" error.
Some likely
causes are:
- The application server is not running.
- The server location and port number in the WSDL are not correct.
- The WSDL is badly formed (check the error messages in the application
server stdout.log file).
- The application server has not been restarted since the service was installed.
You might also try the following checks:
- Can you load the WSDL into your Web browser from the location specified
in the error message?
- Can you load the corresponding WSDL binding files into your Web browser?
- Your Web service EAR file does not install correctly onto the
application server.
It is likely that the EAR file is badly
formed. Verify the installation by completing the following steps:
- For an EJB binding, run the WebSphere Application Server tool \bin\dumpnamespace.
This tool lists the current contents of the JNDI directory.
- For a SOAP over HTTP binding, open the http://pathToServer/WebServiceName/admin/list.jsp page
(if you have the SOAP administration pages installed). This page lists all
currently installed Web services.
- For a SOAP over JMS binding, complete the following checks:
- Check that the queue manager is running.
- Check that the necessary queues are defined.
- Check the JNDI setup.
- Use the "display context" option in the jmsadmin tool
to list the current JNDI definitions.
- Check that the Remote Procedure Call (RPC) router is running.
- There is a permissions problem or security error.
Check that the WebSphere Application Server server.policy file
(in the /properties directory) has the correct security settings.
For more information, see Enabling
security for WSIF.
- Using WSIF with multiple clients causes a SOAP parsing error.
Before you deploy a Web service to WebSphere Application Server,
you must decide on the scope of the Web service. The deployment descriptor
file dds.xml for the Web service includes the following line:
<isd:provider type="java" scope="Application" ......
You
can set the Scope attribute to Application or Session.
The default setting is Application, and this value is correct
if each request to the Web service does not require objects to be maintained
for longer than a single instance. If Scope is set to Application the
objects are not available to another request during the execution of the
single instance, and they are released on completion. If your Web service
needs objects to be maintained for multiple requests, and to be unique within
each request, you must set the scope to Session. If Scope is
set to Session, the objects are not available to another
request during the life of the session, and they are released on completion
of the session. If scope is set to Application instead of Session,
you might get the following SOAP error:
SOAPException: SOAP-ENV:ClientParsing error, response was:
FWK005 parse may not be called while parsing.;
nested exception is:
[SOAPException: faultCode=SOAP-ENV:Client; msg=Parsing error, response was:
FWK005 parse may not be called while parsing.;
targetException=org.xml.sax.SAXException:
FWK005 parse may not be called while parsing.]
- Using the same names for JMS messaging queues and queue connection
factories that run on application servers on different machines can cause
JNDI lookup errors. You should not use the same names for
messaging queues and queue connection factories that run on application servers
on different machines, because WSIF always looks first for JMS destinations
locally, and only uses the full JNDI reference if it cannot find the destination
locally. For example, if you run a Web service on a remote machine, and have
an application server running locally that uses the same names for the messaging
queues and queue connection factories, then WSIF will find and use the local
queues even if the remote JNDI destination is provided in full in the WSDL
service definition.
- A JAX-RPC client running on WebSphere Application Server Version
5 uses SOAP over JMS to invoke a Web service running on a Version 5 application
server. No user ID or password is required on the target MQ Series queue.
After the application server is migrated to Version 6, and using Version
6 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 an application server to WebSphere
Application Server Version 6, existing Web services clients can no longer
use SOAP over JMS to access services hosted on the migrated server.
- The current WSIF default SOAP provider (the IBM Web Service
SOAP provider) does not fully interoperate with services that are running
on the former (Apache SOAP) provider. This restriction is due
to the fact that the IBM Web Service SOAP provider is designed to interoperate
fully with a JAX-RPC compliant Web service, and Apache SOAP cannot provide
such a service. To enable interoperation, modify either your Web service or
the WSIF default SOAP provider as described in WSIF SOAP provider: working with legacy applications.