Creating Web services with the IBM WebSphere JAX-RPC runtime environment

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

These files 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 J2EE deployment descriptors such as web.xml ejb-jar.xml, and application-client.xml.

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

These files contains WebSphere product-specific deployment information such as security information. The WebSphere deployment descriptors are discussed in more detail in: Configuring Web services deployment descriptors.

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 runtime environments with Web services are listed below.

• The IBM WebSphere Web service runtime 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 runtime 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 runtime 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 runtime 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.
• After a Web service is deployed on the WebSphere runtime 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 runtime 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 if possible. Note: this only affects Web services targeted to WebSphere Application Server v5.x - it does not affect Web services using WebSphere Application Server v6.x.
• 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"/>
• 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 runtime 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. Note: this only affects Web services targeted to WebSphere Application Server v5.x - it does not affect Web services using WebSphere Application Server v6.x.
• 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. Note: this only affects Web services targeted to WebSphere Application Server v5.x - it does not affect Web services using WebSphere Application Server v6.x.