Anatomy of a WebLogic Web Service

To better understand WebLogic Web services, you need to look at the basis of the 7.0 implementation: JAX-RPC 1.0.

The JAX-RPC Model

JAX-RPC (Java APIs for XML-based RPC) is a finalized Java specification from Sun Microsystems for standardized Web service invocation, processing, and deployment. JAX-RPC is actually generalized to handle Remote Procedure Call mechanisms employing any protocol or transport, but in the context of this WebLogic Server discussion, we are binding JAX-RPC to the SOAP protocol and the HTTP transport of Web services. The WebLogic Platform Web services implementation is faithfully based on the JAX-RPC 1.0 specification. Therefore, understanding JAX-RPC is essential for the comprehension and effective use of the WebLogic Server Web services features.

Tip

General knowledge of XML and XML namespaces will aid in understanding portions of the JAX-RPC specifications. Refer to the XML specifications available at http://www.w3.org for more information.

Some of the more important elements specified by JAX-RPC are

• Client invocation styles Specifies standard patterns and APIs for invoking a Web service.

• Supported type system Specifies a minimal set of Java types and XML types to be supported.

• Standard type mappings and extensible type mappings Provides consistent transformation rules between Java and XML, and vice versa, and the ability to extend such rules. In WebLogic parlance, these transformations are implemented via serializers and deserializers, respectively.

• Service endpoint model Specifies a standard programming model for the creation and deployment of the service provider.

• JAX-RPC runtime system Defines a library of services required to support the JAX-RPC execution model.

• Standard service description Adds some standard semantics and conventions to WSDL authoring and consumption.

• Standard message handlers A message handler gains access to a SOAP request or response, either to consume , pre-process, or post-process it. For instance, a handler may actually fulfill the SOAP request or merely condition it for the service provider.

The specification also imposes rules on XML encodings for SOAP messages, protocol bindings, and transport. Note that JAX-RPC does not alter nor enhance the definition and semantics of WSDL or UDDI.

Note

None of the use cases described in this chapter utilize UDDI, implicitly or otherwise . WebLogic Platform 7.0 does offer extensive support and tools for UDDI, and this issue will be discussed in Chapter 31.

WebLogic Server 7.0 offers all these JAX-RPC features and more, and has fully passed the JAX-RPC 1.0 Technology Compatibility Kit (TCK) test suite for both Servlet and J2EE Container requirements. Consequently, any client- or server-side Web services code you develop with WebLogic Server can be deployed and run on any JAX-RPCcompliant Web service container, thereby protecting your investment.

Serializers and Deserializers

When you invoke a Web service using a Java method call, its arguments, which are Java primitives or objects, must be translated into XML constructs for inclusion into a SOAP message. The process of converting a Java object to XML representation is called serialization . Conversely, before a Web service response can be returned to the caller, the SOAP return message containing results in XML format must be translated back to the appropriate Java primitives or objects. This conversion is known as deserialization . These conversions are implemented in the serializer and deserializer Java classes. Figure 29.12 shows where these conversions occur in a Web service use case.

Figure 29.12. The place where Java to XML conversions, and vice versa, occur.

Client proxies provide a higher level abstraction layer that shields the client from underlying tasks such as building the SOAP message, parsing a SOAP response, and performing HTTP protocol activities. We will discuss client proxies in more depth later. As you can see, both the client proxy and the SOAP servlet use serializers and deserializers. The following statements explain Figure 29.12 (the numbers in parentheses correspond to those in the figure):

• The client makes a Java call to the proxy, with Java object parameters. The proxy must then convert this call to XML (SOAP) with the help of serializers (1.1).

• The SOAP servlet receives the call and must first convert the XML parameters into Java objects before calling the back-end service (1.2.1), using deserializers.

• The back-end service results come back in Java and must be converted to XML using serializers (1.2.3) before it can be transported via HTTP.

• The client proxy receives the results in a SOAP response (XML) and must then convert the XML results to Java object results, using deserializers (1.3).

In essence, call data needs to be in XML (SOAP) format before transporting via HTTP (serialize), and call data needs to be in Java format before it can be used by a client or back-end service ( deserialize ).

As mentioned earlier, JAX-RPC prescribes rules on Java-to-XML mapping and vice versa, on a definite set of data types, listed in the following section. The WebLogic Server has coded these rules into default serializer and deserializer classes that are automatically and appropriately invoked when any built-in type is used in a Web service method call. However, if your Web service methods use user -defined Java types (UDT or nonbuilt-in types) for parameters and return values, custom serializers and deserializers must be written or generated, and configured via type mappings into your Web service. This effectively extends the WebLogic/JAX-RPC built-in type mapping system. The next chapter explains how to define UDTs and mappings.

Supported or Built-in Types

Table 29.1 lists the Java types that are supported by WebLogic Server and their mappings to XML.

Table 29.1. Java Types Supported by WebLogic Server and Their Mappings to XML

Java Data Type (Lowercase Indicates a Primitive Data Type)	Equivalent XML Data Type
Int	int
short	short
long	long
float	float
double	double
byte	byte
boolean	boolean
char	string (with facet of length=1)
java.lang.Integer	int
java.lang.Short	short
java.lang.Long	long
java.lang.Float	float
java.lang.Double	double
java.lang.Byte	byte
java.lang.Boolean	boolean
java.lang.Character	string (with facet of length=1)
java.lang.String	string
java.math.BigInteger	integer
java.math.BigDecimal	decimal
java.lang.String	string
java.util.Calendar	dateTime
java.util.Date	dateTime
Byte[]	base64Binary
Weblogic.xml.schema.binding.util.Duration	duration
Array of any built-in Java data type	SOAP Array
JavaBean whose properties are any sequence of built-in Java data type	<xsd:sequence>
javax.xml.rpc.namespace.Qname	Qname

Use of any of these types in your Web service methods requires no additional consideration or programming to ensure proper translation, interpretation, and delivery via SOAP and WSDL. They are translated between Java and XML automatically.

SOAP Handlers

Because JAX-RPC and WebLogic Server provide such a convenient abstraction for performing all facets of Web services, you normally do not need to nor get to build the SOAP message yourself. Sometimes this feature could become a limitation. If you must influence the SOAP message in some way, JAX-RPC provides the concept of handlers for intercepting SOAP messages (both requests and responses) before they reach their destination. Handlers are Java classes that can be configured for invocation by the Web service container at appropriate junctures. You can do almost anything inside a handler, maybe even fulfill simple Web service requests without invoking a back-end component. Figure 29.13 clarifies where in a Web service call such handlers come into play.

Figure 29.13. How handlers intercept SOAP messages.

Note

To better illustrate handlers, Figure 29.13 is simplified in that it does not show the client invoking serializers and deserializers.

Have you noticed that handlers always work with the SOAP message, that is, the XML representation of the request or response as opposed to the Java representation? You develop the Handler class code and then configure it as part of defining a Web service. Details are reserved for the next chapter. For now, you can scrutinize the make-up of a WebLogic Web service in the next section.

Inside a Synchronous (RPC) Web Service

Figure 29.14 shows the components that make up an End-to-End synchronous Web service call and fulfillment. Details on how to develop or generate these components will be discussed in the next chapter.

Figure 29.14. The components that make up an End-to-End synchronous Web service call and fulfillment.

Each component plays the following role in the game:

1. The client application makes calls to a smart proxy using a prescribed API, based on its chosen interaction style: static or dynamic. These proxies shield the client from details such as building the SOAP call, processing the SOAP response, converting Java types to XML and vice versa, and reading the WSDL file.

2. The client proxy enlists the services of a JAX-RPC runtime to perform tasks such as fetching WSDL files; invoking SOAP message handlers; activating appropriate serializers/deserializers, both custom and default ones; and sending HTTP commands.

3. The SOAP message is sent via an HTTP (or HTTPS) Post command to an endpoint, where a listener like a servlet would be running.

4. WebLogic Server, which is hosting the servlet as well as the Web service business logic, invokes the appropriate back-end component and returns the result to the client over HTTP.

To see what transpires in the WebLogic Web service container, you can expand the server components as shown in Figure 29.15.

Figure 29.15. A look inside the Web service container.

Each of the numbered steps in Figure 29.15 is explained here:

1. The client makes a Web service call.

2. The Web service reads the SOAP message request and identifies the operation that it needs to run. The operation in this case corresponds to an invocation of a SOAP message handler chain followed by an invocation of a method in a stateless session EJB or a Java class. In the absence of the optional Handler class, the flow would go from step 2 to step 4.

3. The Web service invokes the appropriate handler chain. The handler chain accesses the contents of the SOAP message request, possibly changing it in some way.

4. The Web service converts the operation's parameters in the (possibly modified) SOAP message from their XML representation to their Java representation using the appropriate deserializer class. The deserializer class is either one provided by WebLogic Server for built-in data types or a user-created one for nonbuilt-in data types.

5. The Web service invokes the appropriate back-end component method, passing it the Java parameters. A Java result is returned.

6. The Web service converts the method's return value from Java to XML using the appropriate serializer class and packages it into a SOAP message response.

7. The Web service invokes the appropriate SOAP message handler chain. The handler chain accesses the contents of the SOAP message response, possibly changing it in some way. In the absence of this optional return value handler chain, the flow would go from step 6 to step 8.

8. The Web service sends the (possibly modified) SOAP message response back to the client application that invoked the Web service.

WebLogic Web services even support building a Web service provider that is solely composed of handlers and no back-end component (class or EJB). In this case, the handler alone fulfills the service request. A more realistic scenario is for a handler to cache results of certain popular service requests, with a TTL (Time to Live) on the cache. If the cache is up to date, the handler can just return its contents without invoking the back-end component. When the cache expires or is empty, the back-end component is invoked first, and the results are cached and then returned. This could significantly increase performance and scalability of a Web service.

The client internals are similar to what was described previously for the server. Handlers can be installed on outgoing SOAP requests as well as incoming SOAP results. Client-side handlers can also perform caching, which also will save network overhead.

Inside an Asynchronous Web Service

As you recall from Figure 29.11, an asynchronous service utilizes JMS destinations and message-driven beans to deliver complex business logic to service clients . Such a service provides at least two operations:

• A submitData operation that the client calls to submit input or data for processing

• A requestData operation that the client calls later to see whether results are available

Figure 29.16 depicts the component architecture for such a service.

Figure 29.16. The component architecture for an asynchronous Web service.

Processing steps for an asynchronous Web service are as follows :

1. The client invokes the one-way operation named submitData .

2. The submitData operation puts the client data into JMS Destination 1. Because the back-end MDB is subscribed to JMS Destination 1, it is invoked with the client data.

3. The MDB processes the data, taking an unspecified amount of time to do so.

4. When processing is complete, the MDB places the result in JMS Destination 2.

5. The client invokes the RPC ( request-response ) operation named requestData , whose sole task is to check with JMS Destination 2 to see whether the result is available.

6. If available, the result is returned to the client. Otherwise, the client must try again later.

In practice, for reliability and for avoiding timing issues, another listener needs to be added, and JMS Destination 2 must subscribe to it. The new listener's sole function is to cache or persist the result. The requestData service can then check this persistent store for results.

You might ask if the JMS destinations should be queues or topics. The rule of thumb is to use a JMS queue if there is only one kind of MDB that can process the request data because the WebLogic EJB container can instantiate as many MDB instances as necessary to handle the load. However, if there are multiple kinds of MDBs, a JMS topic would allow them all to subscribe to it and process data concurrently.

You also might observe that this implementation, as is, does not scale to multiple users. Because the Web service may serve many clients, how does the requestData operation ensure that one client's result will not inadvertently be delivered to another client? One simple solution is to include with each submitData request some unique client ID, which is also to be included with each requestData call.

A more elegant design would allow this asynchronous Web service to alert the client immediately when his result becomes available, thereby obviating the need for any polling. The WebLogic Workshop Web service IDE can do just that, and is discussed in Chapter 32. For this discussion, it behooves you to contemplate how the client might implement a callback mechanism.