Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Web Services

# Designing WebLogic Web Services

The following sections discuss design considerations for implementing WebLogic Web Services:

- Choosing the Back-end Components of Your Web Service
- Choosing Between Synchronous or Asynchronous Operations
- Choosing RPC-Oriented or Document-Oriented Web Services
- Using Built-In and Non-Built-In Data Types
- Using SOAP Message Handlers to Intercept the SOAP Message
- Mimicking a Conversational (Stateful) WebLogic Web Service

# Choosing the Back-end Components of Your Web Service

You implement a WebLogic Web Service operation with one of the following types of back-end component:

- A method of a stateless session EJB
- A method of a Java class
- A JMS message consumer or producer.

Note: BEA recommends that you implement your Web Service operation with only a stateless session EJB or a Java class, and not with a JMS consumer or producer. In most of the book, it is assumed that your Web Service is implemented with either an EJB or a Java class. All JMS-specific information is in its own chapter: Creating JMS-Implemented WebLogic Web Services.

## EJB Back-end 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 back-end component if your Web Service will have 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 EJB facilities, such as persistence, security, transactions, and concurrency.

Examples of this 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 Back-end 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 back-end component when you do not need the overhead of EJB facilities such as persistence, security, transactions, and concurrency.

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

# 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 back-end 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 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.

WebLogic Server supports two types of document-oriented Web Service operations: standard document and document-wrapped.

Standard document-oriented Web Service operations take only one parameter, typically an XML document. This means that the methods that implement the operations must also have only one parameter. Document-wrapped Web Service operations, however, can take any number of parameters, although the parameter values will be wrapped into one complex data type in the SOAP messages. If two or more methods of your stateless session EJB or Java class that implement the Web Service have the same number and data type of parameters, and you want the operations to be document-oriented, you must specify that they be document-wrapped.

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"` or `style="documentwrapped"` 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"` or `style="documentwrapped"` 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.

# Using Built-In and Non-Built-In 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 Supported 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:

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

WebLogic Server includes Ant tasks that you use to 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.

# Mimicking a Conversational (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 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.