Troubleshoot the Web Services Invocation Framework

 

Before you begin

For information on resolving WebSphere-level problems, see Diagnosing and fixing problems.

 

Overview

To identify and resolve Web Services Invocation Framework (WSIF)-related problems, use the standard WAS trace and logging facilities. If you encounter a problem that you think might be related to WSIF, one can check for error messages in the WAS administrative console, and in the application server stdout.log file. We 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

Verify the WAS 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:

 

Steps for this task (dependent on configuration)

  • "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 WAS 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 RPC router is running.

  • There is a permissions problem or security error.

    Check that the WAS 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, 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, 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 WAS Version 5 uses SOAP over JMS to invoke a Web service running on a V5 application server. No username or password is required on the target MQ Series queue. After the application server is migrated to V6, 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.

    When the application server is migrated to V6, and the default messaging provider (service integration technologies) is used, and global security is enabled for the server or cell, then by default the service integration bus queue destination inherits the security characteristics of the server or cell. So if the server or cell has basic authentication enabled, then the client request fails.

    To resolve the problem, you have three choices (in order of security, from least secure to most secure):

    • Disable global security.

    • For an equivalent level of security to the configuration on V5, modify the settings for the service integration bus that hosts the queue destination so that bus security is disabled and therefore the bus does not inherit security characteristics from the server or cell.

    • For a greater level of security than the configuration on V5, configure basic authentication on each client that uses the service.

    To disable global security, refer to either of these topics:

    To disable bus security, use the administrative console to complete the following steps:

    1. Navigate to Service Integration > Buses [Content Pane] > your_bus.

    2. Clear the Secure check box.

    3. Save your changes.

    To configure basic authentication on each client, use either the administrative console or the wsadmin tool. To complete the task using the wsadmin tool, see Configuring Web service client port information with the wsadmin tool and use the WebServicesClientBindPortInfo wsadmin task option. To complete the task using the administrative console, complete the following steps:

    1. Navigate to Applications > Enterprise Applications > application_instance > Web Modules or EJB Modules > module_instance > Web services: Client security bindings.

    2. Click HTTP basic authentication to access the "Configuring HTTP basic authentication with the administrative console" panel.

    3. Enter the values in the panel.

    4. Save your changes.

  • 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.

 

See also


Trace and logging for WSIF
WSIF (Web Services Invocation Framework) messages
WSIF - Known restrictions

 

Related Tasks


Maintaining the WSIF properties file
Enabling security for WSIF