Creating Web services with the IBM WebSphere run-time environment

The IBM WebSphere run-time environment is the default Web services run-time environment. The WebSphere run-time environment is the run-time environment recommended for production use.

 

Overview

WebSphere Application Server uses Java Web services standards developed for Java under the Java Community Process (JCP). These standards are Java API for XML-based RPC (also known as JAX-RPC or JSR 101) and Web services for J2EE (JSR 109 and JSR 921). JAX-RPC covers the programming model and bindings for using WSDL-based Web services in Java. Web services for J2EE covers the use of JAX-RPC in a J2EE environment, as well as the implementation and deployment of Web services implementations in a J2EE server. JAX-RPC and JSR-109 are applicable to the J2EE 1.3 release, while JAX-RPC and JSR-921 are applicable to J2EE 1.4.

Development artifacts enable an enterprise bean or Java bean module to be a Web service. To create a Web service from an enterprise bean or Java bean module, the following files are added to their JAR or WAR module at development time:

Web Services Definition Language (WSDL) XML

The WSDL XML file describes the Web service being implemented.

Service Endpoint Interface (SEI)

SEI is the Java interface corresponding to the Web service port type being implemented. It is defined by the JAX-RPC, which specifies the language mapping from WSDL 1.1 to Java.

webservices.xml

The webservices.xml file is the J2EE (JSR 109) Web service deployment descriptor specifying how the Web service is implemented. It is defined in section 7.1 of the Web Services for J2EE specification.

JAX-RPC mapping file

The JAX-RPC Mapping deployment descriptor specifies how Java elements are mapped to and from WSDL elements. It is defined in section 7.3 of the Web Services for J2EE specification.

ibm-webservices-bnd.xmi and ibm-webservices-ext.xmi

The ibm-webservices-bnd.xmi file contains WebSphere-specific deployment information primarily for secure Web services.

The following files are added to the application client or Web module at assembly time so that a J2EE application client can access Web services:

WSDL

The WSDL file is provided by the Web service implementer.

Java interfaces for the Web service

The Java interfaces are generated from the WSDL file as specified by the Java API for XML-based RPC (JAX-RPC). These bindings are the SEI, which is based on the WSDL port type, or the Service Interface, which is based on the WSDL service.

webservicesclient.xml

The webservicesclient.xml file is the client side deployment descriptor generated by Web services using J2EE 1.3. It describes the services being accessed. It is defined in section 7.2 of the Web Services for J2EE specification. Web services generated using J2EE 1.4 do not create a webservicesclient.xml file, instead place the client descriptor information in the other deployment descriptors such as web.xml.

ibm-webservicesclient-bnd.xmi and ibm-webservicesclient-ext.xmi

This file contains WebSphere product-specific deployment information such as security information. It is defined in the WebSphere Web Services for J2EE Assembly Properties

Other JAX-RPC binding files

Additional JAX-RPC binding files that support the client application in mapping Simple Object Access Protocol (SOAP) and WSDL to Java are generated from WSDL by the WSDL2Java tool.

Note: webservicesclient.xml, ibm-webservicesclient-bnd.xmi and ibm-webservicesclient-ext.xmi are used only when running Web service clients in a container-managed environment, and are not used when running Web service clients in a non-managed environment. Therefore secured Web services can only be accessed from Web service clients running in a container-managed environment, otherwise the required security information is unavailable to the client.

 

Limitations

Limitations of using the IBM WebSphere run-time environments with Web services are listed below. For a complete list of limitations, refer to Limitations.

• The IBM WebSphere Web service run-time environments cannot handle Java beans that use the default Java package. The result is that an exception will be thrown during server startup and the Web service will not work at run time.

• When creating Web service from Java bean or EJB using the WebSphere run-time environments, do not use complex types beans with package name that starts with Java primitive types (such as int, float, double). Otherwise, the schema of the generated WSDL file might incorrectly treat the complex type as a Java primitive type.

• The WebSphere run-time environments have a limitation in their ability to handle Java classes with non-conventionally named identifiers. After the WSDL is generated from the original bean, the operation names in the WSDL are correct. However, after WebSphere generates the bean from the WSDL file, the method name is changed to lowercase to support Java conventions. The Web services wizards discard the generated skeleton and use the original bean. This causes a mismatch between the bean name and the WSDL file.

  For example, if the bean method name is BodyMassIndex, the deployment descriptor operation name would be bodyMassIndex (where 'b' is lowercase) to make it follow standard Java naming conventions.

  There are two possible solutions:
  • Change the original bean's method name.

  • Modify the deployment descriptor and redeploy the service. This is not a recommended solution unless you are familiar with the WebSphere deployment tools.

• You cannot mix SOAP encoding and literal encoding for RPC style messages. However, this is the kind of WSDL document that DADX will generate. Therefore, a WebSphere client can not be properly created from a WSDL file which was generated for a DADX Web service using RPC. To counteract this problem, create a DADX Web service using DOC style. The WebSphere run-time environments can create a client from this WSDL without a problem. To use DOC style DADX Web services, set the useDocumentStyle parameter in the group.properties file for the DADX group to true. This can also be done through the DADX group configuration wizard.

• When creating a Web service from a Java bean or EJB, if the Java or EJB implementation has references to Java classes that are located in different packages, then the generated WSDL, more specifically, the <schema> sections of the WSDL file, may have missing <import> statements.

• When generating a Java or EJB skeleton from a WSDL file, if the WSDL file you use contains an XML type that does not have a standard JAX-RPC mapping (for example, a <choice> group), the generated skeleton implementation does not create the corresponding javax.xml.soap.SOAPElement correctly. As a result, the Web service may return malformed SOAP responses.

  The following may fix this problem:

  1. Open the implementation class.

  2. Go to the line where the SOAPElement is instantiated (should look similar to the following:createSOAPElement("http://schems.ibm.com/wswrapper",">D"

  3. Remove the > character.

  4. Save the it and restart the EAR project.

• After a Web service is deployed on the WebSphere run-time environments, if you change one of the classes used by the Web service, the changes might not get refreshed and you may get a ClassCastException in the server console. If that happens, right-click on the server in the Servers view, select Restart project, then select the EAR containing the project that has the classes that have changed.

• If creating a Web services client using the WebSphere run-time environments, the client proxy's JNDI lookup does not work in the Universal Test Client. As a result, client configurations defined in the client's deployment descriptions (these include: webservicesclient.xml, ibm-webservicesclient-ext.xmi, and ibm-webservicesclient-bnd.xmi) will not be picked up. An example of such client configuration is security. Use the sample JSPs instead of the Universal Test Client to test the proxy.

• Array not supported in RPC/literal: When creating a RPC/literal service, the method signature cannot contain an array in it. If it does, the service cannot be invoked with the generated client code. There is currently no workaround for this problem. Please try to use document/literal or RPC/encoded if possible.

• WSDL import: WSDL import statement can only have absolute URLs or relative URLs in the same directory. For example, relative import in the following form is not supported: <import namespace="http://someNamespace/" location="../someFile.wsdl"/>

• Document literal with wrap on: When creating bottom-up Web service using document literal, by default, the wrap option is turned on. You might run into interoperability problem if you have more than one input with different types or no input at all. The workaround is to use RPC/literal.

• When generating skeleton EJB from WSDL file, if the WSDL file uses SOAP over JMS as transport, ensure that the router project is a pre-existing EJB project, not a Web project. If you do not already have an EJB project to use as a router project, the wizard will generate a Web project as your router project and you will then only be able to select SOAP over HTTP as your transport method.

• When generating EJB skeleton, if a J2EE level 1.2 Web project is chosen as the Router project in the Service Deployment Configuration page, make sure an existing level 1.1 EJB project contained in the same EAR as the Web project is chosen as the EJB project before proceeding any further into the wizard. If you rely on the wizard to automatically create the EJB project, the wizard will create a level 2.0 EJB project, which is incompatible with a level 1.2 EAR and level 1.2 Web project.

• When generating EJB skeletons from a WSDL file that uses types without any default JAX-RPC mappings, a run time exception will be returned when the user tries to invoke the Web service. The problem is that the run-time has difficulties deserializing javax.xml.soap.SOAPElement. java.xml.soap.SOAPElement is used when a type does not have any mappings associated with it, as a result, is mapped as a document fragment.

• When generating EJB skeletons from a WSDL file with an operation that has inout parameters, errors will surface when generating deployment codes for the EJB. The problem is that inout parameters are mapped to javax.xml.rpc.holders.Holder classes. Since java.xml.rpc.holders.Holder do not implement java.io.Serializable, they cause EJB deployment errors.

 

Related Concepts

Web services
Tools for Web services development
JAX-RPC
JSR 109 - Implementing Enterprise Web services

Related Tasks
Developing Web services