Chapter 15: Developing and Deploying Web Services

In this chapter, we will discuss WebLogic Server s Web Services support and best practices for its use. We begin with a brief review of Web Services technology, then show you how to create simple Web Services using WebLogic Server. We then discuss more advanced Web Services capabilities built into WebLogic Server. Finally, we will use what you have learned to build the Web Services interface to bigrez.com .

Throughout the chapter, we refer to standalone examples that are available on the companion Web site at http://www. wiley .com/compbooks/masteringweblogic. We use code fragments in the text to demonstrate key points, but we encourage you to download and look through the complete examples as well.

Reviewing the Underlying Technology

Before we dive into building Web Services, let s review the underlying technology that makes Web Services work. This section will briefly touch on the core technologies and is not intended to provide a comprehensive introduction to Web Services technology. For a more complete introduction to Web Services, we recommend one of the fine books available on the subject, such as Developing Java Web Services: Architecting and Developing Secure Web Services Using Java by Ramesh Nagappan, Robert Skoczylas, and Rima Patel Sriganesh (John Wiley & Sons, 2003) and Java Web Services by David A. Chappell and Tyler Jewell (O Reilly, 2002), or one of the online resources such as the Java Web Services tutorial at http://java.sun.com/ webservices /docs/1.0/tutorial/ .

SOAP

The Simple Object Access Protocol (SOAP) is the specification that defines the format of XML messages used to exchange information (see http://www.w3.org/TR/SOAP/). SOAP does not specify the underlying wire protocol used to send the message, though many people associate SOAP with its HTTP protocol binding. At the time of writing, various efforts were underway for defining SOAP bindings for other transport-level protocols such as TCP and Blocks Extensible Exchange Protocol (BEEP).

SOAP messages are sent using an XML format known as a SOAP envelope, with the following structure:

 <env:Envelope xmlns:env=http://schemas.xmlsoap.org/soap/envelope/               xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance               xmlns:soapenc=http://schemas.xmlsoap.org/soap/encoding/               xmlns:xsd=http://www.w3.org/2001/XMLSchema>   <env:Header>...</env:Header>   <env:Body>...</env:Body> </env:Envelope> 

The SOAP envelope is made up of two elements: the SOAP header and the SOAP body. While the SOAP header is an optional element, it is often used to transmit extra information about the context of the message. For example, the WS-Security specification (see http://www.oasis- open .org/ committees /wss/) uses entries in the SOAP header to pass security information associated with the SOAP message. The SOAP body element contains the payload of the message.

SOAP defines two styles of operation: document and remote procedure call (RPC). The SOAP RPC style is typically associated with synchronous, request/response operations while SOAP document style is usually associated with asynchronous messaging-style operation. These categorizations are somewhat arbitrary because it is generally possible to build applications using either type of messaging paradigm with either style of operation. SOAP also defines two representations (also known as uses ) that affect the content of the message: encoded use and literal use. The primary difference is that the literal use does not specify anything about the contents of the SOAP body (other than that its content is a valid XML document) while the encoded use defines how the different data types are encoded in the message. Technically this means that there are four distinct combinations of the interaction model and encoding, but SOAP document/literal (also called doc/literal) and SOAP rpc/encoded are the two most common mechanisms in use today ”and they are only two required by the JAX-RPC 1.0 specification. WebLogic Server 8.1 supports SOAP 1.1 and 1.2, and it supports both doc/literal and rpc/encoded messages. For more information on SOAP, we refer you to one of the references listed at the beginning of the chapter.

WSDL

The Web Services Description Language (WSDL) is the specification that defines the XML-based, interface definition language used to describe Web Services (see http://www.w3.org/TR/wsdl). WSDL is intended to describe the Web Services interfaces to tools, rather than humans . One look at the WSDL description of even a simple Web Service and you understand why. Although we will not attempt to dissect the entire WSDL 1.1 language here, we will cover the basic constructs so that you can understand how to read a WSDL document, should that be necessary.

The basic structure of a WSDL 1.1 document is shown below. WSDL documents describe Web services by starting with custom type definitions that are used to communicate information between the service provider and service requestor . Using these types, WSDL uses messages to represent the data passed to, or response returned from, a Web Service. The exchange of messages between the provider and requestor is called an operation . A portType is a collection of operation definitions. Bindings associate a portType with a specific protocol and message format. Ports , also known as service endpoints, associate physical network addresses with bindings. A service is just a collection of ports.

 <definitions>   <import>     Other WSDL files to include   </import>   <documentation>     Documentation about the web services   </documentation>   <types>     Definitions of data types used by the web services   </types>   <message>     Definitions of the messages sent to and/or received from     the web services   </message>   <portType>     Definitions of the operations supported by the web services   </portType>   <binding>     Definitions of the web services message formats and protocols   </binding>   <service>     <port>       Definition of the web service endpoint     </port>   </service> </definition> 

WebLogic Server 8.1 currently supports WSDL 1.1, as required by the JAX-RPC 1.0 specification.

UDDI

The Universal Description, Discovery, and Integration (UDDI) portion of the Web Services specification (see http://www.oasis-open.org/committees/uddi-spec/) defines a directory service for locating Web Services. Through the UDDI Business Registry (UBR), a public registry of Web Services information, businesses can register information about their organization, relationships with other organizations, and services that they provide. Instead of being a single, centralized registry, the UBR architecture is distributed and replicated so that many different registries may participate providing that they follow the rules laid out by the UDDI specification. Organizations can also choose to set up their own private UDDI registries that are not part of the UBR. While much of the initial hype of UDDI was around the idea of the UBR and dynamic discovery of services over the Internet, the dominant use of UDDI today appears to be focused on private registries in a single organization or across a limited set of trading partners .

UDDI also provides a programmer s API and set of associated data structures. These APIs define a set of SOAP services through which programs can query for information or publish information to a UDDI registry. As part of these SOAP services, UDDI defines a fairly complex set of data types that can be tedious to work with. Fortunately, most UDDI implementations provide a Java API for accessing these UDDI services that simplify the interaction with the UDDI registry; WebLogic Server provides such an API (see http://edocs.bea.com/wls/docs81/webserv/uddi.html ). The Java API for XML Registries (JAXR) also defines a Java API for accessing a number of different types of registries, including UDDI (see http://java.sun.com/xml/jaxr/). In addition, many UDDI providers also supply some sort of tool that can be used to view and manage the UDDI registry without writing code; WebLogic Server provides the UDDI Directory Explorer for this purpose.

We will not spend any more time on UDDI because its use is fairly limited at the time of writing. WebLogic Server does provide a fully functional UDDI 2.0 implementation that you can use, as well as a UDDI browser that can be used to browse any UDDI directory.

JAX-RPC

The Java API for XML-Based RPC (JAX-RPC) specification (see http://java.sun.com/xml/ jaxrpc / ) defines a standard way for Java applications to develop Web Services clients and endpoints. Endpoints are just Web Services providers whose functionality is described using WSDL. JAX-RPC supports RPC and document style Web Services, as well as supporting SOAP attachments. It also defines message handlers that can be used to intercept calls on either the client or server side to augment or short-circuit the request or response. Finally, JAX-RPC provides both a strongly typed, static invocation interface and a loosely typed, dynamic invocation interface (DII) for constructing Web Services clients. WebLogic Server has full support for JAX-RPC 1.0, and all of the examples in this chapter will use the JAX-RPC interfaces. For more information on JAX-RPC, please see the online documentation at http://edocs.bea.com/wls/docs81/webserv/.

SAAJ

The SOAP with Attachments API for Java (SAAJ) 1.1 specification (see http://java.sun_.com/xml/saaj/ ) defines a standard set of classes for creating and manipulating SOAP messages. These classes were previously defined by the Java API for XML Messaging (JAXM) specification but have been broken out into their own specification because of their more general applicability. As you might expect from the name , this specification contains the core classes needed for creating, attaching, and reading SOAP attachments from Java. For more information, please refer to the specification or the Javadocs for the javax.xml.soap package. WebLogic Server has full support for SAAJ 1.1, and several of the examples in this chapter will use the SAAJ APIs.