Programming WebLogic Web Services
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.
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.
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.
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.
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.
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 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.
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.
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="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="documentwrapped" attribute for the appropriate
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.
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.
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.
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.
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.
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.