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 Java EE (JSR 109 and JSR 921). JAX-RPC covers the programming model and bindings for using WSDL-based web services in Java. web services for Java EE covers the use of JAX-RPC in a Java EE environment, as well as the implementation and deployment of web services implementations in a Java EE server.

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 Java EE (JSR 109) web service deployment descriptor specifying how the web service is implemented. It is defined in section 7.1 of the JSR 109 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 Java EE 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 Java EE 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 Java EE specification. web services generated using J2EE 1.4 do not create a webservicesclient.xml file, instead place the client descriptor information in the Java EE 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.
• 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.
• 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"/>