Designing WebLogic Web Services

Download Docs

Site Map

Glossary

e-docs > WebLogic Server > Programming WebLogic Web Services > Designing WebLogic Web Services

Programming WebLogic Web Services

Designing WebLogic Web Services

The following sections discuss design issues you should consider before implementing WebLogic Web Services:

Choosing Between Synchronous or Asynchronous Operations

WebLogic Web Service operations can be either synchronous request-response or asynchronous one-way.

Synchronous request-response (the default behavior) means that every time a client application invokes a Web Service operation, it receives a SOAP response, even if the method that implements the operation returns void. Asynchronous one-way means that the client never receives a SOAP response, even a fault or exception.

You specify this type of behavior with the invocation-style attribute of the <operation> element in the web-services.xml file.

Web Service operations are typically synchronous request-response, mirroring typical RPC-style behavior. Sometimes, however, you might want to implement asynchronous behavior if your client application has no need for a response, even in the case of an error. When designing asynchronous one-way Web Service operations, keep the following issues in mind:

The backend component that implements the operation must explicitly return void.
You cannot specify out or in-out parameters to the operation, you can only specify in parameters.

Choosing the Backend Components of Your Web Service

You implement a WebLogic Web Service operation with one of the following types of backend component:

a method of a stateless session EJB
a method of a Java class
a JMS message consumer or producer. For details, see Creating JMS-Implemented WebLogic Web Services.

EJB Backend Component

Web Service operations implemented with a method of a stateless session EJB are interface driven, which means that the business methods of the underlying stateless session EJB determine how the Web Service operation works. When clients invoke the Web Service operation, they send parameter values to the method, which executes and sends back the return value.

Use a stateless session EJB backend component if your application has the following characteristics:

The behavior of the Web Service can be expressed as an interface.
The Web Service is process-oriented rather than data-oriented.
The Web Service can benefit from the facilities of EJBs, such as persistence, security, transactions, and concurrency .

Examples of this type of Web Service operation implementation include providing the current weather conditions in a particular location; returning the current price for a given stock; or checking the credit rating of a potential trading partner prior to the completion of a business transaction.

Java Class Backend Component

Web Service operations implemented with Java classes are similar to those implemented with an EJB method. Creating a Java class, however, is often simpler and faster than creating an EJB. Use a Java class as a backend component when you do not need overhead of EJB facilities such as persistence, security, transactions, and concurrency.

There are limitations and restrictions to using a Java class as a backend component, however. For details, see Implementing a Web Service By Writing a Java Class.

RPC-Oriented or Document-Oriented Web Services?

The operations of a WebLogic Web Service can be either RPC-oriented or document-oriented. As described in the WSDL 1.1 specification, an RPC-oriented operation is one in which the SOAP messages contain parameters and return values, and a document-oriented operation is one in which the SOAP messages contain XML documents.

The method that implements a document-oriented WebLogic Web Service operation can have only one parameter, of any supported data type. There are no restrictions on the number of parameters of an RPC-oriented operation.

RPC-oriented WebLogic Web Service operations use SOAP encoding. Document-oriented WebLogic Web Service operations use literal encoding.

All operations in a single WebLogic Web Service must be either RPC-oriented or documented-oriented; WebLogic Server does not support mixing the two styles within the same Web Service.

By default, the operations of a WebLogic Web Service are RPC-oriented. If you want to specify that the operations are document-oriented, use the style="document" attribute of the <service> element when assembling a Web Service using the servicegen Ant task. The generated web-services.xml deployment descriptor will contain a corresponding style="document" attribute for the appropriate <web-service> element.

For information on implementing document-oriented WebLogic Web Services, see Implementing a Document-Oriented Web Service. For details on using the servicegen Ant task to assemble a document-oriented Web Service, see Assembling WebLogic Web Services Using the servicegen Ant task and servicegen.

Data Types

WebLogic Web Services support both built-in and non-built-in data types as parameters and return values to Web Services operations. This means that WebLogic Web Services can handle any type of data that can be represented using XML Schema.

Built-in data types are those specified by the JAX-RPC specification. If your Web Service uses only built-in data types, the conversion of the data between its XML and Java representation is handled automatically by WebLogic Server. For the full list of built-in data types, see Using Built-In Data Types.

If, however, your Web Service operation is more complex and uses a non-built-in data type as a parameter or return value, you must:

Create the serialization class that convert the data between its XML and Java representation
Describe the XML representation of the data type (using XML Schema notation) in the web-services.xml file
Create the Java class file of the data type
Describe the data type mapping in the web-services.xml file

WebLogic Server includes Ant tasks that perform these tasks for many common XML and Java data types; this feature is called autotyping. For the list of supported non-built-in data types, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks. For information on running these Ant tasks, see Assembling WebLogic Web Services Using Ant Tasks.

Note: If you are using the autotyping Ant tasks to generate data type information for a Java class, your class must conform to the guidelines described in Implementing Non-Built-In Data Types.

If your data type is not either built-in or one of the supported non-built-in data types, then you must create the serialization class, and so on, manually. For details, see Using Non-Built-In Data Types.

Using SOAP Message Handlers to Intercept the SOAP Message

Some Web Services need access to the SOAP message, for which you can create SOAP message handlers.

A SOAP message handler provides a mechanism for intercepting the SOAP message in both the request and response of the Web Service. You can create handlers in both the Web Service itself and the client applications that invoke the Web Service.

A simple example of using handlers is to encrypt and decrypt secure data in the body of a SOAP message. A client application uses a handler to encrypt the data before it sends the SOAP message request to the Web Service. The Web Service receives the request and uses a handler to decrypt the data before it sends the data to the back-end component that implements the Web Service. The same steps happen in reverse for the response SOAP message.

Another example is accessing information in the header part of the SOAP message. You can use the SOAP header to store Web Service specific information and then use handlers to manipulate it.

You can also use SOAP message handlers to improve the performance of your Web Service. After your Web Service has been deployed for a while, you might discover that many consumers invoke it with the same parameters. You could improve the performance of your Web Service by caching the results of popular invokes of the Web Service (assuming the results are static) and immediately returning these results when appropriate, without ever invoking the back-end components that implement the Web Service. You implement this performance improvement by using handlers to check the request SOAP message to see if it contains the popular parameters.

Stateful WebLogic Web Service

You implement a WebLogic Web Service operation using stateless session EJBs or Java classes, and thus a WebLogic Web Service operation is not stateful, or one that can conduct a back and forth conversation beyond the standard request/response model.

You can, however, mimic a conversational Web Service by using JDBC or entity beans. For example, you could design a Web Service so that client applications that invoke it pass a unique ID to identify themselves to the stateless session EJB entry point. This EJB uses the ID to persist the conversation in some kind of persistent storage, using either entity beans or JDBC. The next time the same client application invokes the Web Service, the stateless session EJB can recover the previous state of the conversation by selecting the persisted data using the unique ID.

For information on programming entity beans, see Programming WebLogic Enterprise JavaBeans. For information on JDBC, see WebLogic jDrivers.