4.8 Web Services Design Patterns

The term Design Patterns is now a buzzword that denotes some reusable framework or objects. Design Patterns show a structure that can be applied if certain conditions are met. They are best practices and are accumulated from past implementation experience.

The early use of the term by the so-called Gang of Four (Gamma, Helm, Johnson, and Vlissides) describes the relationship of objects and components in application design in the categories of creational patterns (for example, factory methods ), structural patterns (for example, facade, proxy) and behavioral patterns (for example, observer, visitor). Here, the Web Services design patterns lean toward structural design pattern, in the context of deploying an end-to-end architecture with Quality of Services.

We have identified a few design patterns:

• Scalability Patterns ” SOAP cache, JMS Bridge, multiple servlet engines, HTTP load balancer

• Reliability Patterns ” State management, SOAP logger

• Manageability Patterns ” Publish/unpublish/discover Web Services, managing different versions of Web Services deployment with Service Registry, registry content management

• Availability Patterns ” High Availability for UDDI

• Security Patterns ” UDDI deployment patterns

The following sections describe some Web Services design patterns associated with designing a high level of Quality of Services. Each design pattern will start by defining the context (background or requirements), problem (problem statement), force (design factors to be considered , or when to use the pattern), solution (proposed solution depicted in Use Cases and sequence diagrams), risks (design or implementation risks, and the risk mitigation), and any relevant examples.

There are also design guidelines and best practices associated with designing and deploying Web Services, which are contributed by many practitioners . They will be recapitulated at the end of this section.

4.8.1 SOAP Cache

Context

In a Service Registry environment, Service Requesters dynamically look up a business service by finding the business organization name and service category (such as NAICS) to locate a service key. With a service key, they can retrieve the service end-points URI and bind the URI to the remote business service using a client SOAP proxy. This dynamic service look-up is beneficial to managing business services within a large user community (such as millions of content providers and mobile phone subscribers), where business services and content are usually added or modified in real- time. It will not be practical to store a predefined URI or network address of the remote business service in the client's front-end, because every change in the business service information or the URI will require a program recompilation at the client front-end.

Although dynamic service look-up allows flexibility in managing changes in service information, it has a system performance overhead. The SOAP client front-end that looks up a Service Registry may take up to a few seconds' overhead (an extreme example is six seconds response time) to invoke a remote Web Service call. This will not be acceptable to many customers.

One solution is to reduce the service look-up overhead by caching frequently accessed Web Services at the SOAP client's side. Another solution is to cache the frequently accessed Web Services at the SOAP server's side. Caching the result from frequently accessed Web Services can improve performance of the services if the result contains static information (such as a code look-up table) that is valid within a given time window.

Problem

Every time a SOAP client looks up the service end-point URL from the Service Registry, there is a performance overhead. Sometimes, the response time may take half a second to two seconds, depending on the infrastructure set-up and application design. Frequently accessed transactions, such as stock quotes or common data look-up, take a considerable amount of CPU cycles and network I/O.

Force

For high transaction volume and high performance applications, there is a strong requirement to process a large quantity of SOAP requests during peak hours. If a normal distribution curve is extracted from the SOAP requests and there is a considerable number of frequently accessed service end-point URLs (that is, these frequently accessed service end-points are in the center of the bell curve), then this SOAP cache pattern will be useful to address the performance overhead of dynamic service look-up.

Client-side SOAP caching is desirable if it can be deployed to the Service Requester's side in a manageable manner. For example, if the Service Requester uses a Java-rich client, then the client-side SOAP cache can be implemented and updated easily with Java Web Start (that comes with JDK 1.4). Server-side SOAP caching is desirable if the Service Requester is using a browser or mobile device and loading cached processing logic in an applet is difficult due to performance constraints.

Solution

Use Case Modeling

Figures 4-6 through 4-8 depict the logical process with Use Cases and sequence diagrams for SOAP Cache. They help elaborate the context, and how the solution can address the dynamic service look-up overhead. In Figure 4-6, a SOAP client intends to initiate an RPC call to a remote business service. Instead of dynamically looking up the service end-point URL from a Service Registry, the SOAP client accesses a SOAP cache first. The SOAP cache can be implemented as a hash table stored in the physical memory of the SOAP client or the SOAP server for fast access. If the service end-point URL is available in the cache and the cached data is not yet expired, then the SOAP client will bind the service end-point URL. If the cached data is already expired (or there is no cached data available), the SOAP client will look up the Service Registry. The new service information (including service end-point URL) will be stored in the SOAP cache for faster retrieval with an expiry time frame. The expiry time frame is arbitrary. For example, a public portal service supporting a non-real -time stock quote or foreign exchange rate inquiry can set the expiry time to be every 15 minutes.

Figure 4-6. SOAP Cache

Figure 4-8. SOAP Cache Sequence Diagram

Figure 4-7 describes four business scenarios, or Use Cases, around managing a SOAP cache. A SOAP client looks up the cached data from a SOAP cache and retrieves business service information (such as service end-point URLs) from the cached data. If the cached data is available, then the SOAP client does not need to look up the Service Registry, which will reduce the dynamic service look-up overhead. It will then bind to the service end-point URL and invoke the remote business service via by the SOAP server. If the cached data is not available (or expired), the SOAP client will perform a dynamic service look-up from the Service Registry. Newly fetched business service information can be added or updated to the SOAP cache, and this will be logged for event tracking.

Figure 4-7. SOAP Cache Use Cases

Figure 4-8 elaborates some details of the Use Cases discussed earlier. The SOAP client needs to look up a service end-point URL to invoke a remote business service. It checks whether the nature of the remote business service supports cached business service information. For instance, an indicative foreign exchange rate inquiry is a good example of using SOAP cache. It will then access the SOAP cache, which may be implemented as a hash table stored in the physical memory of the SOAP client. If the cached data is available and is still timely , the SOAP client will retrieve the business service information from the SOAP cache. The business service information may show the binding information of the service end-point URL. Retrieving cached data (or even cached transaction information such as foreign exchange rates) from the physical memory is speedy and does not require routing the service look-up request to a Service Registry that may reside on another network. This will reduce CPU and network resources considerably.

The SOAP client will then generate a SOAP request in an XML document and send it to the SOAP server (RPC router servlet). The SOAP server will initiate an RPC call to the application providing the business services. Using a synchronous Web Services call, an acknowledgement and the inquiry details (or transaction information) will be returned to the SOAP client. Both the caching event and the business transaction will be logged for tracking and management purposes.

Detailed Design

Transaction Cache Creation. Predefined transaction types can cache transaction contents and results. Cached data can be stored in serialized data objects, databases, XML cache (edge products), and LDAP with time stamp, version, and transaction type/id. Cache data (read-only) can be represented in XML structure and can be parsed/retrieved via DOM, SAX, JDOM, or Xpath.

There is a time-to-live time window. New and updated versions of cache data can be indicated by version and time stamp, whereas outdated /obsolete data can be decommissioned upon creation. If cached data is unavailable (for example, if it is corrupted, or being updated or removed), transaction contents need to be refetched and recached.

Retrieval of Cached Data. The SOAP Cache can be configured to intercept a normal SOAP request, check whether the transaction has been cached, before retrieving the cached data or passing through to applications or the SOAP server. A hash key can be generated to determine whether the transaction cache data is available. Data synchronization is critical, otherwise obsolete data is retrieved.

Implementation. SOAP Cache can be home-grown (such as Leavson's Professional Java SOAP), or off-the-shelf using an XML database (such as Progress eXcelon's XIS). Leavson's book provides some sample code ( http://www.wrox.com/dynamic/books/download.aspx?isbn=1861006101#downloads ) to implement a SOAP Cache, and it is a good reference point. The logical steps are outlined as follows :

   Read  in  XML-RPC  request
   Check  if  cache  is  available  against  the  cache  hash  table
   Locate  the  relevant  cached  data  (XML  file)
   If  available,  read  cached  data,  identify  the  cached  result  by  key
           Present  result
Else
           format  XML-RPC  request
           send  to  SOAP  server
End-if

Benefits

Some frequently accessed real-time (within a time window) or off-line applications can cache their transactions to boost performance and to reduce network traffic. Cached transaction results can be placed in memory and/or in edge products, instead of fetching the same requests from the application servers or from the database.

Risk

• Transaction Integrity and Data Synchronization. If the application contents are updated or changed, then how does this impact the cached data (for example, automatic/timed data synchronization)?

• Design Complexity. Intercepting transactions and applications requests by SOAP Cache requires additional application design and is often complex to implement.

• Recovery of Cached Data. If cached data is corrupted or being replaced , how should the application handle the recovery (for example, high availability of the cached data, refetch and cache the transactions)?

Example

Progress eXcelon's XIS ( http://www.exln.com/products/ ) is an example of using an XML database to implement SOAP Cache, but it needs to be customized. Spiritsoft 's jcache ( http://www.spiritsoft.com/products/jms_jcache/overview.html ) provides similar capability.

4.8.2 JMS Bridge

Context

Java Message Service (JMS) is part of the J2EE technology to provide reliable messaging for business transactions. It provides a set of high-level abstraction APIs to abstract connectivity and message delivery and is implemented using a middleware product or by reusing a J2EE application server infrastructure. It also allows richer and more flexible mechanisms (such as using Java Connector Architecture together) to integrate with other system components.

However, one trading partner (such as an investment manager) cannot send business transactions using a specific JMS vendor product to another trading partner (such as a sales trader or broker) who uses another JMS vendor product. This is because the underlying data transport implementation for the two JMS vendor products is different. A messaging bridge capability (such as JMS bridge using SOAP messaging) will be required to exchange business transactions and documents in a common format that can be understood by different JMS vendor implementations .

Reliable messaging using Web Services technology is critical to delivering financial messages or high-value transactions. An example is the case of an investment manager placing a trade order with a brokerage firm (see Figure 4-9). Both trading partners have JMS implementations in their back-office infrastructure. If the investment manager is placing a trade order of 10,000 lots of high-value technology stocks with the brokerage firm and his portfolio management system uses JMS to exchange trade orders, then the two different JMS vendor implementations cannot exchange messages directly. This is because they have different underlying data transport. The trading partners may want to utilize the benefits of SOAP messaging as a standards-based integration and interoperability technology, which is very useful for cross-institution interoperability or B2B integration. One solution approach is to use a JMS bridge for SOAP messaging, so that the trading partners can benefit from easier integration and interoperability using Web Services technology and JMS. This design pattern describes what a JMS bridge is, and how it can be implemented.

Figure 4-9. JMS Bridge

Problem

JMS is an integration technology that provides good Quality of Service and reliability for business transactions. However, different JMS vendor implementations are not interoperable, as the underlying transport and application protocols are different.

Force

JMS provides reliable message delivery within one application infrastructure. To interoperate with another infrastructure or other institutions, it is essential to build a JMS bridge between two different JMS vendor products. SOAP messaging is a flexible and standards-based interoperability technology and can be bound to JMS in the data transport layer to offer reliable message delivery. This design pattern is useful to business scenarios where there is a need to interoperate between two different JMS vendor products or two different middleware products.

Solution

Use Case Modeling

Figures 4-10 and 4-11 depict the logical process with Use Cases and sequence diagrams for a JMS bridge. Figure 4-10 describes five business scenarios or business cases. A trading partner (say, an investment manager, who is also a JMS publisher) wants to send business transactions to another trading partner (say, a sales trader, who is also a JMS subscriber). The JMS publisher publishes the business transaction information to a predefined JMS topic using the same JMS vendor implementation (say, JMS product 1). The JMS bridge picks up the business transaction information from the JMS queue, routes it, and resends it to the JMS subscriber under another specific JMS topic using a common JMS vendor implementation (say, JMS product 2).

Figure 4-10. JMS Bridge Use Cases

Figure 4-11. JMS Bridge Sequence Diagram

Basically, the JMS bridge has two components, one of which (JMS bridge component 1) works with JMS product 1 and another (JMS bridge component 2) which works with JMS product 2. The two components exchange the business transaction information via SOAP messaging. Upon successful message delivery to the JMS subscriber, the JMS bridge returns an acknowledgement to the JMS publisher. It also logs transaction and exception events for monitoring and audit trail purposes.

Figure 4-11 elaborates some details of the Use Cases discussed earlier. The JMS publisher publishes business transaction information to a predefined JMS topic, where JMS bridge component 1 can pick up. The JMS publisher and JMS bridge component 1 are sharing the same JMS vendor implementation. The JMS bridge component 1 then serializes the content into a SOAP message and sends it to JMS bridge component 2. There is a built-in control mechanism to ensure the SOAP messages will be resent if JMS bridge component 2 has not received the content under the same JMS bridge. For instance, the business transaction information can be persisted in an XML cache, where JMS bridge component 1 can resend it later, even if JMS bridge component 2 is unavailable temporarily.

The JMS bridge component 2 deserializes the SOAP message and publishes to another JMS topic, where the JMS subscriber subscribes to using the same JMS vendor implementation. Upon successful delivery of the message to the JMS subscriber, the JMS subscriber will return an acknowledgement receipt to the JMS bridge. The JMS bridge will then acknowledge receipt with the JMS publisher. It will also log the messaging events for tracking purposes. This completes the entire life cycle of interoperating with two different JMS implementations.

In case any component is unavailable, the business transaction information is encapsulated in SOAP messages and is persisted in an XML cache (or a relational database). If the JMS subscriber is not available online, the JMS publisher can persist the message on the queue and republish the SOAP messages when the JMS subscriber resumes online.

Detailed Design

Creating a JMS Bridge. The topics/queue names of the target JMS need to be registered in the JMS bridge. A JMS bridge client listens to the target topics/queue names , unmarshals the data objects or messages from the original JMS, serializes them into a SOAP message, and then posts it to the recipient JMS bridge client. Data is also stored in XML cache for audit logging and for message recovery. If there is no message acknowledgement, then it recovers the message from the XML cache and resend.

Receiving Messages. The JMS bridge recipient listens to any SOAP messages (synchronous or asynchronous); it acknowledges receipt of messages. Received messages will be also stored in XML cache for audit logging and message recovery. Based on the previous SOAP message routing information, the JMS bridge recipient will act as a JMS publisher to publish the message content to the target JMS. The JMS bridge recipient (JMS publisher) will republish from the XML cache if necessary to provide guaranteed message delivery.

Benefits

There is no need to develop or implement a vendor-specific adapter to bridge two underlying middleware vendors . Caching XML data between two JMSs can provide availability and interoperability. There are existing edge products (such as XML database) to cache XML data from one JMS that can be passed to another JMS (that is, JMS bridge or JMS-SOAP bindings). A JMS bridge is vendor/JMS-independent. Guaranteed messaging between two JMSs.

Risk

• Real-time Support. A small lead time is required to bridge two JMSs using asynchronous messaging. System overhead is incurred to provide guaranteed messaging. Application security of XML cache is vendor-dependent .

Example

There are many vendors providing JMS Bridges to bind SOAP messages to JMS for reliable messaging. Two examples are Progress eXcelon ( http://www.exln.com/using XIS ), and Spiritsoft ( http://www.spiritsoft.com/products/jms_jcache/overview.html ).

4.8.3 Multiple Servlet Engines

Context

A SOAP server handles incoming service requests from SOAP clients . If there are an increasing number of SOAP service requests, a single SOAP server may become a bottleneck. If a SOAP server cannot handle the large influx of incoming service requests, the Service Requester may experience events such as a browser hanging up while waiting for an HTTP connection, HTTP connection drops , and SOAP messaging results. These exception events are examples of a poor service level, even though the service availability of the SOAP server still appears to be high.

A SOAP server is primarily a set of servlets running on top of a Web container (servlet engine). By scaling the SOAP servers vertically on the infrastructure level, architects are able to improve the Quality of Services easily without changing the application.

Problem

A large influx of incoming SOAP service requests during peak hours may deteriorate the performance of SOAP servers. Adding more machines configured as SOAP servers (horizontal scaling) to meet a high volume of SOAP service requests is usually expensive due to additional hardware and maintenance cost. Besides, a single SOAP server on a single Unix machine may underutilize the capacity of the CPU and memory of the operating platform.

Force

Vertically scaling the SOAP server platform is desirable if there is excessive processing capability in the same machine hosting the SOAP server. This is usually implemented by using additional physical memory, disk space, and network adapter cards.

Solution

To horizontally scale up a servlet engine (Web container), multiple instances can be added to the same Unix (or Windows) machine. For an entry-level Unix machine, it is feasible to configure two or more servlet engines (such as Apache HTTP server). This is usually done by installing multiple instances of the servlet engine under different directories. Administrators also need to modify the configuration parameters (such as defining separate IP ports for each servlet engine instance and adding different environment variables or paths). A SOAP server is a set of servlets running on top of the servlet engine. Each SOAP server uses a separate IP port number. This is usually well documented in the servlet engine administration guide (for instance, http://httpd.apache.org/docs-2.0/vhosts/ ) and the SOAP server installation guide.

Figure 4-12 depicts a scenario with four instances of SOAP servers, each of which uses a separate IP port number (ports 8060, 8070, 8080, 8090 respectively). As there are four instances running on the same Unix machines, there are a few hardware requirements, including sufficient physical memory allocated to each virtual host, an individual network adaptor for each virtual host, and more CPUs. A separate hardware capacity sizing plan exercise is essential.

Figure 4-12. Multiple Servlet Engines

Detailed Design

Administering Multiple Servlet Engines. Install multiple servlet engines; installation and configuration varies by vendor implementation. For example, Tomcat 4.x requires creating the variables CATALINA_HOME, CATALINA_BASE, and CATALINA_OPTS to reference to the base instance. Different ports need to be defined in the server.xml of the $CATALINA_HOME/conf directory.

Configuring Servlet Engines. You can assign different priorities and resources to different servlet engines on Unix, just like any Unix processes. You can have different configurations for different servlet engines in the server.xml file, or equivalent ”for example, different services and resources mapping.

Application Partitioning. Different instances of servlet engines can be dedicated to support specific applications.

Benefits

Vertical scaling optimizes existing computing capacity by running multiple instances of the SOAP servlet engines. Multiple servlet engines can support application partitioning for better performance and scalability.

Risk

There are initial administrative overheads for application partitioning; this is not ideal for frequently changed partitioning criteria (for example, servlet A handles cities A to K this month, but handles cities A to P next month). Multiple SOAP servlet engines on the same machine are competing for network I/O or memory, though there are ways to compensate them (such as adding additional network adapter cards for each port to compensate for network I/O competition).

Example

Multiple SOAP engines (which are physically servlets) can be created and run on the same machine. For example, a Windows PC can run two instances of Tomcat servers, and each instance can run a separate SOAP engine.

4.8.4 HTTP Load Balancer (SOAP Server Farm)

Context

A SOAP server handles incoming service requests from SOAP clients. Vertically scaling up SOAP servers with multiple instances on the same Unix machine allows handling a large number of incoming service requests from SOAP clients simultaneously . However, vertical scaling can easily come to a saturation point, where a single machine becomes a bottleneck, perhaps a single point of failure.

Horizontal scaling of SOAP servers is usually implemented by connecting multiple SOAP servlets with a number of HTTP load balancers. The HTTP load balancers allow any incoming SOAP service request to be allocated to an available SOAP server instantly. To increase the processing power of SOAP service requests during peak hours, an additional SOAP server machine can be added and attached to the subnet connecting to the HTTP load balancers. This does not impact the existing SOAP messaging or HTTP requests routing operations. Besides, there is no need to cluster the SOAP servers, because if one SOAP server dies, the HTTP load balancers will allocate workload to another SOAP server automatically.

A SOAP server is primarily a set of servlets running on top of a Web container (servlet engine). By scaling the SOAP servers horizontally on the infrastructure level, architects are able to improve the Quality of Services easily without changing the application.

Problem

Massive volumes of SOAP service requests are not easily handled and processed by a single SOAP server machine, even if it is configured with multiple instances. A single SOAP server machine is exposed to the risk of single point of failure. In case one single instance of a SOAP server causes any system failure, the entire machine may need to be rebooted. This will be disruptive to the service operation, impacting the service level.

Force

Horizontal scaling of SOAP servers is considered appropriate for a large user community with numerous SOAP service requests simultaneously. The traffic volume requirement is multiple times greater than the case in a single SOAP server machine with vertical scaling.

The implementation consideration for horizontal scaling is the server consolidation strategy. Although horizontal scaling can be implemented with low-cost machines (such as blade servers and Linux machines) and load-balancing switches, maintaining a SOAP server farm denotes considerable administrative and maintenance cost.

Solution

Figure 4-13 depicts a scenario using three SOAP server machines connected to a HTTP load balancer. One of the SOAP server machines has two instances of SOAP servers. Load balancers and switches can be used to balance the HTTP load for SOAP requests and responses. This is useful in building a SOAP server farm (with HTTP Load Balancer), when the Web Services network traffic increases .

Figure 4-13. HTTP Load Balancer

SOAP RPC router (aka SOAP server) is primarily a servlet running on a Web container (for example, Apache Tomcat, Sun ONE Web Server, or WebSphere Application Server). Architects and developers can run multiple instances of SOAP RPC routers on a physical machine (for example, a multiple-domain machine such as Sun Fire 6800) for vertical scaling or run multiple instances on separate machines as a SOAP server farm for horizontal scaling. There is no fixed rule about whether architects and developers should start with vertical or horizontal scaling first. As in the HTTP load balancing design, HTTP traffic and SOAP RPC routing are better managed by horizontal scaling because each instance of the server farm has a separate network adapter and if one is unavailable, the other instance can take over the processing.

Architecturally, the SOAP RPC router can be installed on a Sun ONE Web Server (Web Container) and a J2EE Application Server (Web container and EJB container) in the same operating environment. It is always a good architecture design practice to decouple the Web Tier from the Application Tier for security and scalability reasons. It is recommended that it be installed on the Web Tier (that is, Sun ONE Web Server) because of the following considerations:

Security Considerations

There is no business logic in the Web Tier. SOAP RPC router is acting as the SOAP message router behind the DMZ (Demilitarized Zone) firewall. If there is any security attack such as Denial of Service, this will not affect the business logic.

Better Scalability

With the use of load balancers, architects and developers can scale up better with horizontal scaling of the SOAP RPC routers (aka SOAP server farm) if the SOAP RPC routers reside on the same machine as the HTTP Server. If SOAP RPC routers reside on the same machine with the application server, this will allow only vertical scaling by creating multiple instances within a Unix machine (for example, multidomain Solaris OE).

Benefits

SOAP requests can be evenly spread out to different SOAP servers during the peak hours. No additional programming is required in the application or server side.

Risk

Load balancers usually do not support session management; thus if a HTTP session dies, the SOAP request will be lost.

Example

SOAP server farm can be implemented by combining SOAP servers with the Web servers and HTTP load balancers as Web Services appliances (or edge devices).

4.8.5 State Management

Context

A complex business transaction may consist of a chain of remote business services, where each RPC-based Web Services call is dependent on one another. Architects are often tempted to persist the state of each RPC call, so that they can roll back to the previous state in case there is any exception in the midst of the chained RPC calls. If architects keep track of numerous chained Web Services calls, they will create heavy resource overheads, especially when the Web Services call invokes an EJB via RMI/IIOP. Besides, the business rules for any potential rollback are very complicated.

Keeping the session information is different from maintaining the state of each Web Services call. Session information (such as whether a JAX-RPC Web Service is successfully returned with a result) needs to be captured for tracking high-level Web Services calls, for security monitoring, and also for Single Sign-on. In case the JAX-RPC call fails, the client can resend the request based on the session information.

This design pattern suggests a scenario of how states are handled using RPC-based Web Services calls (see Figure 4-14). In this sample scenario, an investment manager wants to place a trader order of 10,000 stocks with the sales trader. The investment manager's SOAP client initiates a trade order Web Service that triggers a chain of Web Services calls. This includes authenticating the user credential for Single Sign-on, checking the access rights to place a trade order, checking the account balance for risk exposure, and placing the trade order. Most of the business functionality resides on the legacy mainframe system. Each Web Services call is dependent on the others.

Figure 4-14. State Management

In a stateless RPC-based Web Services call scenario, the session management module creates a login session, and authenticates the user credential. Upon successful log in, the system redirects the user to the order booking page. By filling in the trade order details, the SOAP client is able to invoke the high-level trade order Web Services call. A session facade is used to perform three things: check the access rights, check the account balance, and place the trade order. Each RPC call is dependent on another. In this normal scenario, the investment manager is a valid user with access rights to place a trade order. Each RPC-based Web Services call is successful, and the session facade confirms that the trade order is placed successfully. During the RPC-based Web Services calls to the mainframe system, no state information is captured. Only the return code of each call is logged and tracked.

If this is a stateful RPC-based Web Service, each of the Web Services calls will capture the state information. There will be code customized to handle every possible exception. In this sample scenario, if the Web Services call to place a trade order fails, the system will roll back to the previous Web Services call (check balance). Practically, the process "check balance" does not process any business transaction and is simply an inquiry. Capturing the business logic to handle roll back and exceptions will be redundant and resource- intensive . The design can be simpler to reinitiate the trade order Web Services, if there is any exception during the chain of Web Services calls.

Problem

Some architects maintain states for remote transactions because they can reinitiate the remote transactions if there are any exceptions. However, maintaining states incurs system overhead and heavy resources. Should state or session be maintained for RPC-based Web Services? Can a Web Service be recovered if there is a failure in the midst of the remote XML-RPC call?

Force

RPC-based Web Services calls can be stateful or stateless. Stateful RPC-based Web Services calls denote persisting the states of every remote call, but this is very resource expensive. Sometimes, a stateful EJB can be created to initiate a chain of Web Services calls. This is also called EJB Web Services, and developers need to design what state information is captured and how to use it. Stateless RPC-based Web Services calls are simply remote procedure calls implemented in a Java program or a servlet. They do not capture any state, and therefore there is no mechanism to roll back any transaction. In both cases, the return code of the Web Services calls can be captured and logged. The choice of stateful or stateless Web Services is dependent on business requirements and operating environment constraints. Typically, if the remote business services are provided by legacy mainframe applications via RPC-based Web Services calls, it would be difficult to capture the states without changing the back-end mainframe applications.

The session information (for example, the user, date, and time) tracked during a session is useful for logging and exception handling. Architects should consider what session information is necessary to support security session control or event tracking. This should be separate from maintaining states.

Solution

Use Case Modeling

Figures 4-15 and 4-16 depict the logical process with Use Cases and sequence diagrams for state management. Figure 4-15 describes six business scenarios or Use Cases. A SOAP client initiates a chain of RPC-based Web Services calls. The SOAP server creates a session to track the Web Services calls. The Web Services calls invoke the remote business applications via XML-RPC. The remote business applications process requests from each RPC call. Upon completion of the current RPC call, the RPC call will return to the SOAP server (or the parent Web Services call), which will initiate the next Web Services call. After all RPC calls are completed, the application will commit transactions. The session will be killed . The SOAP server can also reinvoke the RPC call if any exception is encountered .

Figure 4-15. State Management Use Cases

Figure 4-16. State Management Sequence Diagram

Figure 4-16 elaborates the details of the previous Use Cases. The SOAP client initiates a stateless RPC-based Web Services call by passing an XML-RPC request to the SOAP server. The SOAP server uses a session facade, creates a sign-on session, and builds up a chain of RPC-based Web Services calls. For each RPC call, the session facade tracks the session information for the calls, and invokes the back-end mainframe applications. The back-end business application acknowledges the RPC call and processes the service request. If the service request is successful, then the application will return the requested business information. If there is any exception, the application will handle error recovery or roll back. The session facade will then reinvoke the RPC call.

Upon successful completion of all RPC calls, the session facade will kill the session and log the transaction events to the logger.

Detailed Design

SOAP Client. XML-RPC from a SOAP client can create a session variable, but cannot track states remotely for several reasons. For example:

• State cannot be updated and tracked remotely.

• Multiple phase commit will create many wait states and is overly complex and therefore problematic .

• Remote RPC is usually functionally like a black box and may not support state management.

Remote Applications. They are likely to be black box processes, which may or may not support state management or transaction roll-back/roll-forward. Upon completion of the Web Services call and success return code, the SOAP client can kill the session; otherwise, the SOAP client should assume the RPC call fails and needs reinvocation.

In case of exception in the midst of the XML-RPC call, the SOAP client may not like to reinvoke automatically for various reasons; therefore, do not make design assumptions to reinvoke automatically.

Benefits

Session control is in place for XML-RPC Web Services, where remote transactions can be reinvoked if the session dies or fails over. There is also a clear demarcation of recovery. Remote applications should be responsible for transaction roll-back or roll-forward for recovery, while Web Services should handle invocation only, not provide recovery. Architects can reuse the session facade pattern (use of session bean to encapsulate the complexity of interactions between the business subjects participating in a workflow) in designing state management. This pattern (refer to Alur, Crupi, and Malks, Core J2EE Patterns , 2001, pp. 291 “309 for more details) provides a uniform coarse-grained service access layer to clients without overloading the system performance by storing states for each tier.

Risk

We cannot know whether a session dies, fails over, or recovers if there is no session or state management at all. Many remote applications may not support states or session recovery.

Example

The session facade pattern (refer to Alur, Crupi, and Malks, Core J2EE Patterns ) has provided good guidelines in state management and are applicable to developing Web Services applications.

4.8.6 SOAP Logger

Context

Transaction logging is essential for troubleshooting, audit trail, and billing. Service providers often need transaction logging information for metering service levels or billing, if they provide a variety of Web Services calls to Service Requesters.

High-level Web Services call information can be easily captured in the SOAP server level, using the logging infrastructure provided by the Web container (for example, Java logging API from J2SE version 1.3.x/1.4). This will considerably reduce application developers' efforts to capture Web Services calls.

Problem

SOAP request “reply does not support logging. Apache SOAP server does not provide sufficient logging capability for audit trail or for billing purposes. Developers need to add customized Web Services call transaction logging functionality or to rely on the application server platform that runs J2SE version 1.3.x/1.4 to provide logging.

Force

JAX-RPC-based Web Services may not support transaction logging if the remote business services cannot generate logging events. Thus, the support of transaction logging depends on two factors: the logging infrastructure (as provided by the Web container or customized logging facilities) and the capability of remote business services to generate logging events.

Solution

Use Case Modeling

Figures 4-17 through 4-19 depict the logical process with Use Cases and sequence diagrams for a SOAP logger. Figure 4-17 presents a scenario where the SOAP server (SOAP reply) generates a logging event before it initiates a SOAP-RPC call or a document-based Web Services call. This is based on the logging provider class provided by J2SE 1.4 or the logging facility in Apache AXIS.

Figure 4-17. SOAP Logger

Figure 4-19. SOAP Logger Sequence Diagram

Figure 4-18 depicts four business scenarios, or Use Cases, about transaction logging. A SOAP client initiates a document-based or an RPC-based Web Services call by sending an XML document to the SOAP server. The SOAP server, using the logging provider class, logs the transaction events, and binds the service end-point URL to the remote business applications.

Figure 4-18. SOAP Logger Use Cases

Figure 4-19 elaborates the Use Cases with more details using sequence diagrams. Once the SOAP client initiates a SOAP service request, the SOAP server will unmarshal the sender information from the SOAP envelope and the session information. It logs the sender and session information in the logger using the Java API for logging. The SOAP server will then invoke RPC calls with the remote business applications. The date/time and usage will be logged in the logger as well. Upon successful invocation of the remote business services, the SOAP server will acknowledge with a return code or an exception. The information captured in the logger should be sufficient for basic usage analysis and per-call-based billing.

Detailed Design

Logger Design. J2SE 1.3.x or 1.4 has a logger API that can be used for logger design. Unmarshal the SOAP envelope to acquire the sender information and time stamp for logging.

Time Services. If time services are required for remote RPC calls, the start time and the end time for the RPC call invocation need to be tracked for logging purpose.

Persistence and Storage. The choice of persistence and storage (for example, LDAP, RDBMS, XML Cache, or flat file) will determine the quality of data security of the logging information. Though the logging information may not contain sensitive financial information, it is useful for audit tracking and perhaps for billing. Therefore, the logger needs to be protected in the server for access control (for example, file access restricted to server administrators only).

There needs to be a proper archive strategy, and backup/restore procedure for the logger (such as daily backup or archive every 30 days).

Benefits

Logs of SOAP replies (requester, request time stamp, or service request) can be captured for audit trail or for billing purpose. The built-in features of Java logging can be leveraged.

Risk

Requester information is not reliable or easily authenticated; the SOAP envelope is the only source. The service time is not usually available from the RPC call, if time-based billing is required.

Example

Apache Axis has a logging feature based on log4j (also incorporated in J2SE 1.4) using the log handler. Every time a business service is invoked (for example, via JAX-RPC), the log handler will track the usage for application monitoring and troubleshooting. The following deployment description shows an example of how the log handler is specified (see Figure 4-20). In this example, the transaction events are logged by the log handler LogTestService in a file MyService.log whenever the samples.userguide.example4.Service is invoked.

Figure 4-20 Deployment Descriptor for Log Handler (aka SOAP Logger)

 <deployment xmlns="http://xml.apache.org/axis/wsdd/"             xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">  <! define the logging handler configuration -->  <handler name="track" type="java:samples.userguide.example4.LogHandler">   <parameter name="filename" value=  "MyService.log"  />  </handler>  <! define the service, using the log handler we just defined -->  <service name=  "LogTestService"  provider="java:RPC">   <requestFlow>    <handler type="track"/>   </requestFlow>   <parameter name="className" value="samples.userguide.example4.Service"/>   <parameter name="allowedMethods" value="*"/>  </service> </deployment> 

4.8.7 High Availability of Service Registry

Context

Service Requesters that use dynamic service look-up for Web Services are heavily dependent on the availability of the Service Registry. High availability of the Service Registry denotes the Service Registry is always available, even though one of the instances may fail or be hacked.

Problem

Dynamic service look-up requires the Service Registry to always be available. If there is any downtime, no SOAP client (Service Requester) can access remote business services. Although the Service Registry functionality is based on the UDDI or ebXML standard, each vendor implementation varies, and there is no standard mechanism to support high availability. How do we make the Service Registry highly available?

Force

The provision of a high availability Service Registry requires a resource cost (for example, redundant hardware platform or redundant network switch).

Solution

The Service Registry can be made resilient by clustering the hardware platform that runs the Service Registry. Figure 4-21 depicts a scenario of clustering the hardware platform of multiple Service Registries, and the contents of these Service Registries are also synchronized using the underlying database replication or proprietary Service Registry replication utilities (such as Systinet's UDDI registry).

Figure 4-21. High Availability Service Registry

Detailed Design

General. Follow the rule of three. This means that architects should have at least three instances of the Service Registry running in production. These instances can be clustered to provide a better level of service availability. Always have three. If one is down, then you have two clustered as backup.

Hardware Level. Hardware level clustering of all UDDI servers is useful to provide machine-level availability. Hardware-level failover may have a short lead time to switch from one UDDI server to another (for example, 10 minutes); thus, this must go hand in hand with the software level.

Network Level. Network-level resilience is important when UDDI service look-up becomes critical. Dual network link or cross-network switch is fairly standard.

Software Level. Software-level availability of UDDI servers depends on the physical implementation such as ”RDBMS, LDAP, or proprietary. RDBMS can have a parallel database server (data synchronization); yet the I/O overhead to synchronize data in real time is fairly high; thus the machine resources and costs are higher.

Another RDBMS variation is to have standby database mode, where the secondary database is replicated. LDAP can be set up as master-slave replication; thus when one fails, the slave (secondary LDAP) will take over. Proprietary implementation may make use of mirrored disks and manual switch over; but the service level is unpredictable.

Benefits

7 x 24 x 365 high availability enables service lookup running nonstop (not disruptable).

Risk

The quality of high availability of the UDDI Service Registry depends highly on the UDDI implementation (for example, RDBMS or LDAP). Hardware-level-only clustering of the UDDI server has a short recovery time (for example, 10 minutes). Parallel database server implementation of UDDI has expensive I/O overhead to synchronize the databases.

Example

The Service Registry can be clustered on a redundant hardware platform such as Sun Fire mid-frame series ( http://www.sun.com/servers/ midrange /sunfire/ ), which has redundant power supply, redundant system boards , and network adapters. This will enable better availability.

4.8.8 UDDI Deployment

Context

The Service Registry is a key piece of architecture that enables service look-up and accessing remote business services. External or internal security attacks may intrude into the Service Registry and cause denial of service. The Service Registry (either UDDI or ebXML Service Registry) should be deployed with appropriate firewall protection. It is important to understand the appropriate deployment strategy on which the UDDI Service Registry should be placed.

Problem

In which tier (outer tier, DMZ, or inner tier) should the UDDI Service Registry be placed? Public and private Service Registries have different security requirements, and they do not necessarily have the same deployment and security protection strategy.

Force

Potential security attacks on the Service Registry will be a major threat to the discovery and invocation of Web Services. They will impact the service availability.

Solution

Figure 4-22 depicts the deployment scenarios for both a public UDDI Service Registry and a private UDDI Service Registry. Public UDDI Service Registries are usually vulnerable to outside security attack. The security attack usually takes the form of a penetrating agent (aka Trojan horse) and intrudes into internal resources once access to the internal network is gained . Thus, it is better to place the UDDI Service Registry in front of the Demilitarized one next to the Web server with a standby instance. This is similar to placing the DNS server in front of the DMZ.

Figure 4-22. UDDI Deployment

Private UDDI Service Registries are primarily intended for internal use. They have different security risks when compared to public UDDI Service Registries. It is recommended that private UDDI Service Registries be placed behind the DMZ. An optional standby instance may be installed. However, private UDDI Service Registries are open to insider security attacks.

Detailed Design

Deployment Architecture. There are many types of UDDI Service Registries, but there is no need for an individual deployment architecture for each type. The UDDI deployment architecture usually varies for public UDDI and private UDDI.

Benefits

Reduction of security risk for the UDDI Service Registry if it is placed in the appropriate tier.

Risk

Firewall port administration ”the UDDI port (port 8080) needs to be defined and opened in the firewall policy.

Example

A Public Service Registry is always deployed in the demilitarized zone behind the outer firewall. A private Service Registry is usually deployed behind the DMZ.

4.8.9 Publish, Unpublish, and Discover Web Services

Context

The Service Provider (developers and architects) needs to register, publish, and unpublish a business service to a Service Registry for consumers (endusers and trading partners) to utilize. Each Service Registry vendor product usually has its own set of APIs and utilities to manage publishing and unpublishing business services and service information, though all of these products support a Service Registry standard. Thus, there is a design and management issue for architects and developers who must determine the best strategy for managing different vendor product implementations.

Problem

Different Service Registry vendor products have different APIs to publish and unpublish. Thus, if architects and developers have multiple Service Registry vendor products, they may need to maintain different sets of programs to register and publish Web Services.

Force

Different vendor implementations of Service Registries have their own set of APIs to publish or unpublish business service information. This has a major impact to developers if they decide to migrate from one vendor product to another. Developers may consider standardizing APIs (such as using JAXR, or creating an abstract layer on top of the vendor-specific Service Registry APIs) to publish and unpublish Web Services to the Service Registries for easy maintenance and high usability.

Solution

The recommendation is to use JAXR (JAX Pack from http://java.sun.com ) to access UDDI. This enables developers to switch to other UDDI vendor products seamlessly without rewriting their code. They simply need to replace the query.url and publish.url entries in the registry.properties file (see Figure 4-23) to denote the specific UDDI vendor product APIs (refer to the following excerpts). There is no need to recompile or rewrite the code if a new Service Registry product is used.

Figure 4-23 Sample registry.properties File Used by JAXR Client

  query.url  =http://uddi.ibm.com/ubr/inquiryapi  publish.url  =https://uddi.ibm.com/ubr/protect/publishapi 

Figure 4-24 Sample JAXR Program Excerpt

 /*          * Define connection configuration properties.          * To publish, you need both the query URL and          * the publish URL.          */  Properties props = new Properties();   props.setProperty("javax.xml.registry.queryManagerURL",   queryUrl);   props.setProperty("javax.xml.registry.lifeCycleManagerURL",   publishUrl);  ... 

The Java Web Services Developer Pack 1.01 Tutorial ( http://java.sun.com/ webservices /downloads/webservicestutorial.html ) contains a sample JAXR publisher (see Figure 4-24) that can be reused as a standard template. Developers can use a registry.properties file to specify the query.url and publish.url for the specific Service Registry. The same JAXR publisher and registry.properties can be customized as standard Web Services utilities that can be reused for implementation in a different country. Architects and developers can customize their JAXR Publisher utility in the Proof of Concept stage or future phases.

Risk

There are implementation and migration risks when migrating from one Service Registry to another because they use different publish and unpublish APIs. Switching from one Service Registry vendor to another often incurs intensive testing and regression testing. To mitigate the risk, architects and developers can adopt the JAXR standard using the registry.properties file to work with any Service Registry vendor product. This approach does not require retesting as JAXR can work with both UDDI and ebXML Service Registry vendor products without rewriting the APIs.

Example

Some of the common and infrastructural services, even including authentication and authorization services, can be published in the Service Registry. JAXR provides a common and standardized mechanism to browse and invoke these services. If architects and developers determine to transition to a new Service Registry vendor product or to split the services to multiple Service Registries, this JAXR approach will not require developers to migrate or redo any integration testing.

Alternatively, architects and developers may provide a standard set of B2B Web Services APIs using JAXR to their trading partners. With these standards-based APIs, trading partners do not need to worry about the client platform or back-end integration with the invocation APIs, as the same invocation APIs (URIs) using JAXR will work with any platform.

4.8.10 Managing Different Versions of Web Services Deployment With Service Registry

Context

Many Service Providers (such as retail banks) have deployed legacy customer front-ends and systems around the world. Once they adopt Web Services for customer integration, it is necessary to integrate with these legacy customer front-ends and systems. However, these systems provide the same business service functionality, but they likely run on different platforms with multiple versions. It is rather challenging to standardize the software versions simultaneously in terms of management and upgrade cost.

These Service Providers need to deploy and manage different versions of Web Services in a structured and manageable manner. The Service Registry can be used as an administration tool to centralize managing different versions of Web Services deployment.

Problem

There are different versions of business services available to support different platforms, different customers (customized for specific customers), and different countries . There is a need to easily manage different versions when publishing (and even discovering) business services from the Service Registry.

Force

Different variants of clients or software versions of the interfaces are deployed in parallel. Administering and managing different versions for the same client or trading partners is complex.

Solution

Different versions of business services can be registered in the Service Registry under the same Service Provider as different service bindings (that is, URLs) and service binding descriptions. This enables running variants of the business services globally in parallel. Figure 4-25 depicts how different versions of the same business service can be defined in a UDDI Service Registry.

Figure 4-25. Different Web Services Versioning Can Be Managed as Different Service Bindings

Publishing different versions of business services requires planning ahead of the versions (for example, creating a product version roadmap). The Service Registry can act as a tool to track all versions and can be supplemented by Web Services network Service Providers such as Flamenco Network and Talking Block. These vendors provide services that can route the client request to different versions of the remote Web Services based on their profile.

There should be a synergy between the service versioning development best practice (for example, specifying the service version in the SOAP message header attribute) and this best practice. Practically, the service version should tie to (or equate to) the "Service Bindings" and their associated service end-points (or service bindings access URI). They collaborate to provide manageability of deployed Web Services. Refer to Figure 4-25 for an example.

Risk

Using URLs in the service bindings to manage versions is currently a manual process, prone to careless human errors (for example, during staff changeover). Web Services network tools that provide an administrative tool to track versions and to deploy URLs can supplement it. Alternatively, architects and developers can develop some utilities to publish different versions of business services.

Example

Historically, customers may have many commercial off-the-shelf applications deployed in local countries. Some of them have similar functionalities, and some have many software versions deployed in parallel.

4.8.11 Registry Content Management

Context

Service Providers (developers) need to manage the contents of Web Services globally to provide timely access and update of the service end-point URLs. Being able to create, publish, and access timely information for a large user community is crucial. The timeliness of service information affects the quality of Web Services.

A large user community may generate a large volume of service information. As the number of content providers or Service Providers increases, the process of updating the content of the Service Registry becomes more complicated to manage. There needs to be a well-defined Service Registry content management process to manage the timeliness of the service information. If there are multiple Service Registries deployed, there needs to be a deployment strategy to synchronize them.

Problem

The nature of the Service Registry is to allow dynamic updates of the business services and related service information. As the service information size is small and the update is instantaneous, developers may assume that a Web Services client performing a dynamic service look-up is able to discover that the service has just been removed or upgraded. However, there is always the risk of synchronization issues, as in the case of DNS management.

Forces

There are two major factors affecting the content management strategy for Service Registries: the business rules and the data volume. Local business rules of updating and replicating the business service information (for example, service end-point URLs) need to be established.

The data volume (size of the business service information) and the number of Service Registry instances need to be updated and managed.

Solution

Immediate Recommendation

It is not recommended to dynamically update the Service Registry on the production platform. Doing so exposes the risk of synchronization problems when any Web Services client is looking up the service end-point. Besides, there is no fallback if the production master Service Registry is updated directly. There should be operational processes defined and reinforced to ensure updates are accurate and timely. This can be addressed in future phases.

Short-Term Recommendation

A staging Service Registry is highly recommended, where administrators can perform updates. There should be scheduled replications (for example, every hour ) to synchronize the master Service Registry with the staging Service Registry. Administrators can also push replication in real-time, if necessary. The replication implementation should be synchronizing the "delta." The replication schedule is dependent on the number and volume of the changes. It can be increased as the volume goes up. There should be also scheduled replications (such as every 8 hours or every 24 hours) to synchronize the master Service Registry with the slave Service Registries. Refer to Figure 4-26 for an example.

Figure 4-26. Staging Service Registry

For emergency (ad hoc with high priority) updates, it is recommended that administrators push the update to the master Service Registry (that is, nonscheduled), which will also push the updates to the next tier of the slave Service Registries in realtime.

Removing a business service entails removing the entry instantaneously from the Service Registry. Typically, the deprecated or decommissioned business service will be made unavailable before the update of the Service Registry. During service discovery, Web Services clients should be able to get a return code from the Service Registry indicating that the service is unavailable, and the client's exception handling routine should be able to display an error message.

Risk

Upgrading a business service entails removing the entry and adding a new entry in the Service Registry. However, customers may need to run multiple versions in parallel, without decommissioning older versions immediately. As service discovery is designed to bind the business service at runtime, the chance of binding to the old business service during the update is slim because the update is instantaneous. It may be helpful to check the version from the SOAP message header. If a different version is found, then the Web Services client can reinvoke the business service again for the upgraded business service.

Example

Many financial institutions have decentralized applications and services running in different regions . These business services can be registered in the centralized Service Registry, while copies (slave Service Registries) can be replicated for better performance and availability.

4.8.12 Design Consideration

JNDI Look-up versus UDDI. JNDI look-up can be performed in place of UDDI look-up. The benefits of doing this include:

• There is no dependency on an additional UDDI server.

• Established Java programs already use JNDI.

• It alleviates the complexity involved implementing and tuning UDDI servers.

• JNDI provides a better paradigm of dynamic discovery (Jini!).

Web Services Troubleshooting Approach. SOAP calls debugging tools are available to trace each step invoked (for example, XMLSpy). SOAP load testing tools are emerging. The general troubleshooting approach is to identify the first-tier bottleneck (for example, memory, I/O, or network), and perform load testing with different transaction volumes and at different times see whether the problem is related to load or time.

Performance Tuning. Performance tuning of SOAP calls is like tuning and scaling up a servlet (SOAP is a servlet). Tuning an XML-RPC call is difficult, as there may be multiple processes beneath and very often the remote applications are wrapped as a SOAP-based Web Service (black box processes).

Trace the SOAP calls to narrow down the potential problem areas and isolate the problem by trial-and-error testing (for example, repeat the first-tier bottleneck testing or load testing).

4.8.13 Other Design Guidelines for Web Services

Coarse Grained. There is a general understanding among Web Services architects that Web Services calls need to be coarse grained, while leaving EJBs or Java beans fine grained. In other words, a customer may start with one single coarse-grained Web Service, where different services can be invoked by passing parameters in the Web Service call (either an XML-RPC or an XML message). Architects can also expose the business service using a coarse-grained uniform access point such as a business delegate or a session facade (refer to Alur, Deepak, and Crupi, Core J2EE Patterns for details).

Performance. Raghu Varadan, in his presentation "Patterns for eBusiness ”Design Guidelines for Web Services," has pointed out that the notion of Web Services being slow because of transmitting or XML parsing is unfounded ”a myth. He quotes a GeSC test, which shows that the response time for a simple transaction on an IBM F40 machine with no load yields 8 ms. The same transaction on an IBM F80 machine can yield over 300 transactions per seconds. XML parsing can be addressed by using XML parsing library calls. The live implementation of Hewitt Associates' managed HR services using Web Services, according to Hilgenberg and Hansen, yields similar results. Hewitt Associates' Web Services implementation can support up to 4 million transactions per day.

Distributed Events. Geysermans and Miller have identified design patterns for managing distributed events using a Distributed Event-based Architecture (DEBA). DEBA patterns make use of state machine concepts and callback design patterns (visitor and observer). This allows an easy implementation of a dynamic workflow model. Currently, DEBA patterns include multiple observables (aka providers) and observers (aka requesters) as well as distributed state machine, router, workflow, and composite patterns.