Web Services Invocation Framework @ WEBSPHERE JOURNAL

Web Services Invocation Framework

Today's most popular Web services APIs - JAX-RPC and JAXM - support two very different programming models for invocation of Web services, one synchronous, one asynchronous. If users need both models in a single application, they are forced to use two sets of very different APIs. This article, the first of a two-part series, describes an architecture and programming model - the Web Services Invocation Framework (WSIF) - that provides a single set of APIs that supports both models.

JAX-RPC, which is currently part of J2EE and consequently is a mandatory implementation for all J2EE application services vendors, defines and uses an XML-based remote procedure call mechanism. JAX-RPC is a very powerful, easy-to-use API for RPC-style Web services communications. The relative simplicity of the RPC model, which is very similar to the method invocation of the local Java class, explains its widespread popularity. Nearly all Web services tool vendors provide out-of-the-box support for these APIs, allowing for automatic generation of JAX-RPC stub- and proxy-based service implementation (either Java class or EJB). Incorporation of the decorating filters pattern allows for a very powerful mechanism for extending the JAX-RPC programming model and support for additional emerging Web services standards.

The drawback of using JAX-RPC, according to some experts, is that it usually leads to the creation of brittle applications. Remote procedures are strongly typed and possess a static signature that defines fixed parameters and return values. If there are any changes in the procedure signature, all dependent clients must be modified to reflect these changes. In addition, RPC by definition is a synchronous programming model, so a caller cannot continue execution until the procedure has returned. Although asynchronous invocations are occasionally supported or can be simulated, most JAX-RPC procedures are synchronous, and therefore not responsive to changing network conditions. This leads many experts to believe that RPC-style invocations are not applicable to building evolving, fault-tolerant or fault-recoverable systems.

The Java API for XML Messaging (JAXM) was introduced to assist developers in creating business-to-business messaging applications using XML. JAXM defines an asynchronous, loosely coupled, document-based messaging model, which is at the moment less used, but allows achieving the full value offered by Web services. JAXM was designed to support the SOAP (and SOAP with attachments) messaging infrastructure over different transports, including, but not limited to, HTTP, MOM (most notably JMS), and mail.

JAXM provides an implementation of very powerful messaging APIs, allowing for the creation of an extremely flexible and extensible messaging infrastructure. The fact that JAXM does not dictate the content of the XML messages (only SOAP as an enveloping mechanism) allows system designers to use a very wide variety of messaging approaches, ranging from strongly typed messages using XML Schema definitions or JAX-RPC data type mappings to very complex semantic messages that provide very loose coupling between message senders and receivers.

The JAXM specification and reference implementation provide good support for synchronous messaging but are inadequate for implementing asynchronous messaging, experts agree. It is impossible to send an asynchronous message using JAXM without an explicit destination and a specific profile. (A profile is a domain-specific application of SOAP such as ebXML.) Therefore, usage of a particular profile requires specific knowledge of the implementation-specific profile classes involved, as there are no generic interfaces supported by all profile implementations. The requirement to use a specific profile to send an asynchronous message through a provider renders it impossible to send an arbitrary document-based SOAP message to an arbitrary destination using asynchronous guaranteed message delivery.

Unlike JAX-RPC and JAXM, the Web Service Invocation Framework (WSIF) is an API that directly supports constructs of WSDL as an abstract service definition model. With WSIF the user programs directly to the abstract service representations expressed in WSDL, thus taking full advantage of the flexibility and richness of this service definition model, which:

Views network applications as encapsulated services identified by their ability to exchange messages according to a set of predefined patterns - their supported portTypes

Provides a standard-, protocol-, and platform-independent, unified view of network applications

Separates core functionality from protocol and deployment details

Allows clients to optimize access to desired functionality based on available protocols

WSIF allows for support of both synchronous and asynchronous communications. It also allows either usage of a fixed set of parameters and return values (similar to RPC-style communication) or sending arbitrary XML documents (wrapped as SOAP documents) as service requests and replies, similar to JAXM.

WSIF APIs also provide binding-independent access to any Web service. WSIF allows completely dynamic usage of different transport and transport support implementation for invocation of Web services based on examination of the metadata about the service at runtime. It also allows updated implementations of a binding to be plugged into WSIF at runtime.

I will describe the WSIF architecture and programming model. I will also provide code examples and explain how it works.

WSIF Architecture
WSIF is composed of three major parts:

WSIF kernel: Implements Java APIs that allow clients to program against an abstract model of the service, without any concern about the specifics of communication transport or message packaging structure.

WSIF providers: Implement WSIF support over different encoding and transport implementation. WSIF is shipped with providers for Java, EJB, native JMS, Apache SOAP (over HTTP and JMS), Apache Axis (over HTTP and JMS), SOAP over RMI, and J2C (Java Connectors).

WSIF utilities: Implement support functionality for both the WSIF kernel and WSIF provider implementations.

The architecture of WSIF is based on a number of factories. The reason for using factories is that they allow for hiding the provider's implementation, providing for the use of the same interface, regardless of the actual provider used.

WSIF implementation encompasses the following main classes, defined in the org.apache.wsif package:

Service Factory class: The WSIFServiceFactory class is a root class in WSIF hierarchy that allows for the instantiation of a service from a WSDL document at a known URL or known location on the hard drive. Service instantiation is done by parsing the WSDL document and building an internal service model.

Service class: A WSIFService is a factory via which WSIFPorts are retrieved. A specific port can be requested by using its name, or a service can choose a port on its own, either based on the internal algorithm or port preference, which can be set by a service class. An actual port implementation is part of the provider implementation. The WSIF environment stores a list of providers that can each support a particular WSDL binding. The service looks up providers based on the port binding style, for example, SOAP binding, JMS binding, Java binding, EJB binding, etc. If there is more than one provider supporting a given binding, the WSIFService implementation can choose a provider based on a number of criteria, for example, the preferred provider for a particular binding, the first defined provider, etc.

Port class: WSIFPort implements a factory method for WSIFOperations. A WSIFPort handles the details of creation of an operation based on the port definition.

Operation class: The WSIFOperation is the runtime representation of an operation. It is responsible for invoking a service based on a particular binding. It provides methods to create input, output, context, and fault messages, and to invoke the operation.

ResponseHandler class: The WSIFResponseHandler is an implementation of the Callback object, used for asynchronous operation invocation using the executeAsyncResponse() method on the WSIFOperation class.

Message class: WSIFMessage implements WSDL messages, which are composed of named parts tied to some type system, normally an XML Schema. To invoke such services, this schema type is mapped to possibly more sophisticated type systems, provided by the programming language in use. For instance, the schema type is mapped to certain Java classes by serialization and deserialization for cases where Java is the native type system. The design of WSIFMessage allows you to employ any native type system as a message part. Parts in a message can be typed by employing different type systems. This is needed if parts from multiple separate WSDL messages are associated with different native type systems and have to be combined into a single message.

Provider class: A WSIFProvider is an implementation of a WSDL binding. It can run a WSDL operation over a protocol that depends on a specific binding. WSIF providers implement the bridge between the WSIF API and the actual implementation of a service. WSIF providers are currently available for SOAP over HTTP, SOAP over JMS, Java, EJBs, and native JMS. New providers can easily be added to the WSIF framework.
- The SOAP provider allows WSIF stubs and dynamic clients to invoke SOAP services.
- JMS is a messaging technology. The mapping to a JMS destination is defined during deployment and maintained by the container.
- The WSIF Java provider allows WSIF to invoke Java classes and JavaBeans; local Java code running on a JVM can be incorporated easily.
- The EJB provider allows WSIF clients to invoke Enterprise JavaBeans. The EJB client JAR must be available in the client runtime with the current provider.

Table 1 shows the correspondence between WSDL and WSIF components. Figure 1 illustrates the interaction between the main WSIF components.

There are two ways of using WSIF: as a stub-based model and as a dynamic invocation interface (DII). The stub-based approach allows you to use any JAX-RPC compliant tool (for example WSDL2Java) to generate stub interfaces corresponding to WSDL portTypes. It allows usage of WSIF, pretty much the same as JAX-RPC with multiple provider protocol support. In my evaluation I concentrated on the DII approach to WSIF invocations.

WSIF Programming
I have been testing WSIF with WebSphere Studio Application Developer (WSAD) 5, which allowed me to generate some of the code used and test the code from within WSAD itself. Evaluation involved the following steps:

Creation of the basic service implementation and WSDL, defining the service

Creation of the service client, allowing for the invocation of the service using SOAP/HTTP

Using the same client to use other providers, including:
- An EJB provider
- A native JMS provider (WebSphere MQ as JMS provider) - SOAP over JMS provider (WebSphere MQ as JMS provider)

Using JNDI for storing the service information

Creating custom SOAP headers

Using WSIF to send custom XML files

Asynchronous service invocation using WSIF

Creation of the Basic Service Implementation
I've used the AddressBook EJB provided by the WSIF distribution as a sample of the basic Web service implementation. The code for this bean can be found in the subdirectory samples/ejb/service of the WSIF distribution. Additional classes defining types used are WSIFAddress and WSIFPhone, located in the subdirectory samples/ejb/service/ addressbook/wsiftypes. After compiling and building the code within WSAD, I used WSAD wizards to generate the WSDL files for this service. This is a standard WSDL file, presented in Listing 1 (All of the code for this article can be downloaded from www.sys-con. com/websphere/sourcec.cfm). The most basic WSIF client implementation is presented in Listing 2.

The basic WSIF client is composed of the following steps:
1.   First we need to get a new instance of WSIFServiceFactory.
2.   WSIFServiceFactory is then used to create a WSIFService, which is built based on the WSDL file. The location of the WSDL file can be specified either as a URL location available over HTTP or as a file-based location available through the classLoader. In this simple example I use a URL address. Additional parameters for service creation are service name/namespace and port name/namespace. Because of the simplicity of our WSDL file, containing only a single service with a single port, we will set these values to null. When WSIFService is created, a model of the service (based on the WSDL) is built internally. After the service is created, type maps must be set for it if we want to set message parts using Java objects. Setting type maps creates a correspondence between the Java class types and the namespace/names used in the WSDL for the message definitions.
3.   WSIFService is used for creation of WSIFPort. The port implementation is selected based on the binding type and providers available. A list of the available providers' names is contained in the file org.apache.wsif.spi. WSIFProvider, which is part of the WSIF.jar and is located in the META-INF.services package. When the port is created for the first time this file is loaded into memory and the list of providers is used every time a port is created. Each provider can be queried about the binding and protocol types that it supports. If these two correspond to the binding and protocol types specified in the WSDL for the service/port pair, the provider can be used for the service invocation. There are three situations that can occur when choosing a provider for service invocation:

- A preferred provider can be set for a particular binding type using this command; here we are specifying usage of the AXIS provider for the SOAP binding:

WSIFPluggableProviders.overrideDefaultProvider(
"http://schemas.xmlsoap.org/wsdl/soap/",
new WSIFDynamicProvider_ApacheAxis());

- If there is only one provider available for a particular binding/transport type, this provider is used.
- In the case where multiple providers are available for the required binding/transport type, the providers will alternate in round-robin fashion.
4.   The next step is creation of the WSIFOperation using WSIFPort. An operation is created using a service name or a combination of service name and input and output messages.
5.   WSIFOperation is then used to create input, output, and fault messages.
6.   The input message now has to be populated. Population of the input message is done by setting parts (defined in the WSDL) of the input message. It is possible to set message types using Java classes based on the type map, which is set by the service.
7.   The last step is a service invocation. Invocation returns a Boolean variable that is equal to true if the operation succeeds, or false otherwise. In the case of failure, a fault message can be examined to determine the exact reason for failure. In this case a fault message is populated based on the SOAPBody: Fault element defined in the SOAP specification. In the case of successful service invocation the content of the output message can be extracted into Java classes based on the output message parts (similar to the population of the input messages). Following is the result of execution of the simple WSIF client:

WSIF factory created
WSIF service created
WSIF types map created
WSIF port created
WSIF operation created
WSIF input message created
Successfully added name and address
Successful lookup of name 'Jack' in addressbook
The address found was:
streetNum=1
streetName=The Waterfront
city=Some City
state=NY
zip=47907
phoneNumber=areaCode=765
exchange=494
number=4900

Conclusion
WSIF offers many advantages over other Web services invocation frameworks. In Part 2 I will discuss more advanced topics of WSIF programming, such as JNDI bindings, using different providers, asynchronous service invocation, and messaging.

Related Links

▪ Figure 1

▪ Source Code

▪ Figure 2

About Boris Lublinsky
Boris Lublinsky is an Enterprise Architect at CNA Insurance where he is involved in design and implementation of CNAs integration strategy, building application frameworks and implementing service-oriented architecture for the company Prior to this he was Director of Technology at Inventa Technologies, where he was overseeing and actively participating in engagements in EAI and B2B integration implementations and development of large-scale web applications. While a Technical Architect at Platinum Technology and SSA, Boris was involved in component-based systems development and design and implementation of execution platforms for component-based systems. In all, he has over 25 years experience in software engineering and technical architecture.