bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Web Services

Overview of WebLogic Web Services

The following sections provide an overview of Web services, and how they are implemented in WebLogic Server:

- What Are Web Services?

- Why Use Web Services?

- Web Service Standards

- WebLogic Web Service Features

- Examples Of Creating and Invoking a Web Service

- Creating WebLogic Web Services: Main Steps

- Differences Between 6.1 and 7.X WebLogic Web Services

- Unsupported Features

- Editing XML Files

What Are Web Services?

Web services are a type of service that can be shared by and used as components of distributed Web-based applications. They commonly interface with existing back-end applications, such as customer relationship management systems, order-processing systems, and so on.

Traditionally, software application architecture tended to fall into two categories: huge monolithic systems running on mainframes or client-server applications running on desktops. Although these architectures work well for the purpose the applications were built to address, they are closed and can not be easily accessed by the diverse users of the Web.

Thus the software industry is evolving toward loosely coupled service-oriented applications that dynamically interact over the Web. The applications break down the larger software system into smaller modular components, or shared services. These services can reside on different computers and can be implemented by vastly different technologies, but they are packaged and transported using standard Web protocols, such as XML and HTTP, thus making them easily accessible by any user on the Web.

The concept of services is not new—RMI, COM, and CORBA are all service-oriented technologies. However, applications based on these technologies require them to be written using that particular technology, often from a particular vendor. This requirement typically hinders widespread acceptance of an application on the Web. To solve this problem, Web services are defined to share the following properties that make them easily accessible from heterogeneous environments:

- Web services are accessed over the Web.

- Web services describe themselves using an XML-based description language.

- Web services communicate with clients (both end-user applications or other Web services) through XML messages that are transmitted by standard Internet protocols, such as HTTP.

Why Use Web Services?

Major benefits of Web services include:

- Interoperability among distributed applications that span diverse hardware and software platforms

- Easy, widespread access to applications through firewalls using Web protocols

- A cross-platform, cross-language data model (XML) that facilitates developing heterogeneous distributed applications

Because you access Web services using standard Web protocols such as XML and HTTP, the diverse and heterogeneous applications on the Web (which typically already understand XML and HTTP) can automatically access Web services, and thus communicate with each other.

These different systems can be Microsoft SOAP ToolKit clients, J2EE applications, legacy applications, and so on. They are written in Java, C++, Perl, and other programming languages. Application interoperability is the goal of Web services and depends upon the service provider's adherence to published industry standards.

Web Service Standards

A Web service consists of the following components:

- An implementation hosted by a server on the Web.

  WebLogic Web services are hosted by WebLogic Server; are implemented using standard J2EE components (such as Enterprise Java Beans and JMS) and Java classes; and are packaged as standard J2EE Enterprise Applications.

- A standardized way to transmit data and Web service invocation calls between the Web service and the user of the Web service.

  WebLogic Web services use Simple Object Access Protocol (SOAP) 1.1 and 1.2 as the message format and HTTP as the connection protocol. See SOAP 1.1 with Attachments.

  Note: WebLogic Web services accept both SOAP 1.1 and 1.2 incoming requests, but produce only SOAP 1.1 outgoing responses.

- A standard way to describe the Web service to clients so they can invoke it.

  WebLogic Web services use Web Services Description Language (WSDL) 1.1, an XML-based specification, to describe themselves. See WSDL 1.1.

- A standard way for client applications to invoke a Web service.

  WebLogic Web services implement the Java API for XML-based RPC (JAX-RPC) as part of a client JAR that client applications can use to invoke WebLogic and non-WebLogic Web services. See JAX-RPC.

- A standard way for client applications to find a registered Web service and to register a Web service.

  WebLogic Web services implement the Universal Description, Discovery, and Integration (UDDI) specification. See UDDI 2.0.

SOAP 1.1 with Attachments

SOAP (Simple Object Access Protocol) is a lightweight XML-based protocol used to exchange information in a decentralized, distributed environment. WebLogic Server includes its own implementation of both the SOAP 1.1 and SOAP With Attachments specifications. The protocol consists of:

- An envelope that describes the SOAP message. The envelope contains the body of the message, identifies who should process it, and describes how to process it.

- A set of encoding rules for expressing instances of application-specific data types.

- A convention for representing remote procedure calls and responses.

This information is embedded in a Multipurpose Internet Mail Extensions (MIME)-encoded package that can be transmitted over HTTP or other Web protocols. MIME is a specification for formatting non-ASCII messages so that they can be sent over the Internet.

Note: WebLogic Web services accept both SOAP 1.1 and 1.2 incoming requests, but produce only SOAP 1.1 outgoing responses.

The following example shows a SOAP request for stock trading information embedded inside an HTTP request:

>     POST /StockQuote HTTP/1.1
>     Host: www.sample.com
>     Content-Type: text/xml; charset="utf-8"
>     Content-Length: nnnn
>     SOAPAction: "Some-URI"

>     <SOAP-ENV:Envelope
>        xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
>              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
>          <SOAP-ENV:Body>
>               <m:GetLastStockQuote xmlns:m="Some-URI">
>                    <symbol>BEAS</symbol>
>               </m:GetLastStockQuote>
>          </SOAP-ENV:Body>
>     </SOAP-ENV:Envelope>

WSDL 1.1

Web Services Description Language (WSDL) is an XML-based specification that describes a Web service. A WSDL document describes Web service operations, input and output parameters, and how to connect to the Web service.

Developers of WebLogic Web services do not need to create the WSDL files; you generate these files automatically as part of the WebLogic Web services development process.

The following example, for informational purposes only, shows a WSDL file that describes the stock trading Web service StockQuoteService that contains the method GetLastStockQuote:

>     <?xml version="1.0"?>
>       <definitions name="StockQuote"
>                    targetNamespace="http://sample.com/stockquote.wsdl"
>                    xmlns:tns="http://sample.com/stockquote.wsdl"
>                    xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
>                    xmlns:xsd1="http://sample.com/stockquote.xsd"
>                    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
>                    xmlns="http://schemas.xmlsoap.org/wsdl/">
>           <message name="GetStockPriceInput">
>               <part name="symbol" element="xsd:string"/>
>           </message>
>           <message name="GetStockPriceOutput">
>               <part name="result" type="xsd:float"/>
>           </message>
>           <portType name="StockQuotePortType">
>               <operation name="GetLastStockQuote">
>                  <input message="tns:GetStockPriceInput"/>
>                  <output message="tns:GetStockPriceOutput"/>
>               </operation>
>           </portType>
>           <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
>               <soap:binding style="rpc"
>                             transport="http://schemas.xmlsoap.org/soap/http"/>
>               <operation name="GetLastStockQuote">
>                  <soap:operation soapAction="http://sample.com/GetLastStockQuote"/>
>                  <input>
>                      <soap:body use="encoded" namespace="http://sample.com/stockquote"
>                                encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
>                  </input>
>                  <output>
>                  <soap:body use="encoded" namespace="http://sample.com/stockquote"
>                                encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
>                  </output>
>               </operation>>
>           </binding>
>           <service name="StockQuoteService">
>               <documentation>My first service</documentation>
>               <port name="StockQuotePort" binding="tns:StockQuoteSoapBinding">
>                  <soap:address location="http://sample.com/stockquote"/>
>               </port>
>           </service>
>       </definitions>

JAX-RPC

The Java API for XML-based RPC (JAX-RPC) is a Sun Microsystems specification that defines the client API for invoking a Web service.

The following table briefly describes the core JAX-RPC interfaces and classes.

Table 1-1 JAX-RPC Interfaces and Classes

javax.xml.rpc Interface or Class | Description
--- | ---
Service | Main client interface. Used for both static and dynamic invocations.
ServiceFactory | Factory class for creating Service instances.
Stub | Represents the client proxy for invoking the operations of a Web service. Typically used for static invocation of a Web service.
Call | Used to dynamically invoke a Web service.
JAXRPCException | Exception thrown if an error occurs while invoking a Web service.

For detailed information on JAX-RPC, see the following Web site: http://java.sun.com/xml/jaxrpc/index.html.

For a tutorial that describes how to use JAX-RPC to invoke Web services, see http://java.sun.com/webservices/docs/ea1/tutorial/doc/JAXRPC.html.

UDDI 2.0

The Universal Description, Discovery and Integration (UDDI) specification defines a standard way to describe a Web service; register a Web service in a well-known registry; and discover other registered Web services.

See http://www.uddi.org.

WebLogic Web Service Features

The WebLogic Web services subsystem has the following features:

- Standard Specifications

  See Web Service Standards.

- Support for Exposing Standard J2EE Components

  WebLogic Web services support exposing standard J2EE components, such as stateless session EJBs and JMS consumers or producers.

- Ant Tasks and Command Line Utilities

  Ant tasks facilitate the implementation and packaging of Web services. See Web Service Ant Tasks and Command-Line Utilities.

- UDDI Registry, Directory Explorer, and Client API

  WebLogic Server includes a UDDI registry, a UDDI Directory Explorer, and an implementation of the UDDI client API. See Publishing and Finding Web Services Using UDDI.

- Support for Both RPC-Oriented and Document-Oriented Operations

  WebLogic Web service operations can be either RPC-oriented (SOAP messages contain parameters and return values) or document-oriented (SOAP messages contain documents.) For details, see RPC-Oriented or Document-Oriented Web Services?.

- Support for User-Defined Data Types

  You can create a WebLogic Web service that uses non-built-in data types as its parameters and returns values. Non-built-in data types are defined as data types other than the supported built-in data types; examples of built-in data types include int and String. WebLogic Server Ant tasks can generate the components needed to use non-built-in data types; this feature is referred to as autotyping. You can also create these components manually. See Web Service Ant Tasks and Command-Line Utilities, and Using Non-Built-In Data Types.

- SOAP Message Handlers to Access SOAP Messages

  A SOAP message handler accesses the SOAP message and its attachment 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. See Creating SOAP Message Handlers to Intercept the SOAP Message.

- Java Client to Invoke a Web Service

  Developers can use an automatically generated thin Java client to create Java client applications that invoke WebLogic and non-WebLogic Web services. See Invoking Web Services.

  Note: For information about BEA's current licensing of client functionality, see the BEA eLicense Web Site.

- The Web Services Home Web Page

  All deployed WebLogic Web services automatically have a Home Web Page that includes links to the WSDL of the Web service, the client JAR file that you can download for invoking the Web service, and a mechanism for testing the Web service to ensure that it is working as expected. See The WebLogic Web Services Home Page and WSDL URLs.

- Point-to-Point Security

  WebLogic Server supports connection oriented point-to-point security for WebLogic Web service operations, as well as authorization and authentication of Web service operations. See Configuring Security.

- Interoperability

  WebLogic Web services interoperate with major Web service platforms such as Microsoft .NET.

- Java 2 Platform Micro Edition (J2ME) Clients

  The WebLogic Server the clientgen Ant task can create a client JAR file that runs on J2ME. See Invoking Web Services.

Examples Of Creating and Invoking a Web Service

WebLogic Server includes the following examples of creating and invoking WebLogic Web services in the WL_HOME\samples\server\src\examples\webservices directory, where WL_HOME refers to the main WebLogic Platform directory:

- basic.statelessSession : Uses a stateless session EJB backend component with built-in data types as its parameters and return value.

- basic.javaclass : Uses a Java class backend component with built-in data types as its parameters and return value.

- complex.statelessSession : Uses a stateless session EJB backend component with non-built-in data types as its parameters and return value.

- handler.log : Uses both a handler chain and a stateless session EJB.

- handler.nocomponent : Uses only a handler chain with no backend component.

- client.static : Shows how to create a static client application that invokes a non-WebLogic Web service.

- client.static_out : Shows how to create a static client application that invokes a non-WebLogic Web service that uses out parameters.

- client.dynamic_wsdl : Shows how to create a dynamic client application that uses WSDL to invoke a non-WebLogic Web service.

- client.dynamic_no_wsdl : Shows how to create a dynamic client application that does not use WSDL to invoke a non-WebLogic Web service.

- message: Shows how to create a JMS-implemented WebLogic Web service.

- multicomponent: Shows how to create a WebLogic Web services implemented with two Java classes.

- r4client: Shows how to run the WebLogic Web service client to exercise the SOAPBuilders Interoperability Lab Round 3 suite of tests.

For detailed instructions on how to build and run the examples, open the following Web page in your browser:

>     WL_HOME\samples\server\src\examples\webservices\package-summary.html

Additional examples of creating and invoking WebLogic Web services are listed on the Web services Web page on the Web Services dev2dev Download Page.

Creating WebLogic Web Services: Main Steps

The following procedure describes the high-level steps to create a WebLogic Web service. Most steps are described in detail in later chapters.

Creating a WebLogic Web Service: A Simple Example, briefly describes an example of creating a Web service.

1. Design the WebLogic Web service.

   Decide on a synchronous or asynchronous Web service; the type of back-end components that implement the service; whether your service uses only built-in data types or custom data types; whether you need to intercept the incoming or outgoing SOAP message; and so on.

   See Designing WebLogic Web Services.

2. Implement the WebLogic Web service.

   Write the Java code of the back-end components that make up the Web service; optionally create SOAP message handlers that intercept the SOAP messages; optionally create your own serialization class to convert data between XML and Java; and so on.

   See Implementing WebLogic Web Services.

3. Assemble and package the WebLogic Web service.

   Gather all the implementation class files into an appropriate directory structure; create the Web service deployment descriptor file; create the supporting parts of the service (such as client JAR file); and package everything into a deployable EAR file.

   If your Web service is fairly simple, use the servicegen Ant task which performs all the assembly steps for you. If your Web service is more complicated, use additional Ant tasks or assemble the Web service manually.

   See Assembling WebLogic Web Services Using Ant Tasks.

4. Create a client that accesses the Web service to test that your Web service is working as you expect. You can also use the Web Service Home Page to test your Web service.

   See Invoking Web Services.

5. Deploy the WebLogic Web service.

   Make the service available to remote clients. Because WebLogic Web services are packaged as standard J2EE Enterprise applications, deploying a Web service is the same as deploying an Enterprise application.

   See Deployment.

6. Optionally publish your Web service in a UDDI registry. See Publishing and Finding Web Services Using UDDI.

Differences Between 6.1 and 7.X WebLogic Web Services

WebLogic Web services changed between versions 6.1 and 7.X of WebLogic Server:

- Due to changes in the runtime system between the two versions, you must upgrade WebLogic Web services created in version 6.1 of WebLogic Server to run on version 7.x. Do not deploy a 6.1 Web service on a 7.x WebLogic Server instance. See Upgrading 6.1 WebLogic Web Services to 7.0.

- The WebLogic Web services client API included in version 6.1 of WebLogic Server has been deprecated. The 6.1 client API was packaged as weblogic.soap.*. Version 7.x includes a new client API, based on the Java API for XML based RPC (JAX-RPC). For details see Invoking Web Services.

- You can implement 7.x Web services with multiple backend components, such as a stateless session EJB, a Java class, and a JMS listener. In 6.1, however, a single Web service was implemented with just one backend component. For this reason, 7.x does not use the terminology "rpc-style" and "message-style" to refer to an entire Web service.

  Also in 7.x you can choose which methods of an EJB you expose to the public; in 6.1 you were forced to expose all public methods of an EJB.

  See Architectural Overview.

- 7.x Web services support non-built-in data types as parameters and return values, as well as out and in-out parameters. 6.1 WebLogic Web services were limited to a list of built-in data types that could be used as parameters and return values. See Using Non-Built-In Data Types.

- Version 7.x introduces SOAP message handlers and handler chains that can intercept SOAP messages for further processing. 6.1 WebLogic Web services were unable to access the request or response SOAP message. See Creating SOAP Message Handlers to Intercept the SOAP Message.

- In 7.x you can use SOAP message handlers to access the SOAP attachment for further processing; in 6.1 you could not access the attachment. See Creating SOAP Message Handlers to Intercept the SOAP Message.

- 7.x Web services now have their own deployment descriptor file, called web-services.xml. For reference information on the web-services.xml file, see WebLogic Web Service Deployment Descriptor Elements. For examples of the file, see Assembling a WebLogic Web Service Manually.

- WebLogic Server 7.x includes additional Ant task support for quickly implementing, assembling, and packaging WebLogic Web services. See Assembling WebLogic Web Services Using Ant Tasks.

- In 7.x you can specify that a Web service be asynchronous one-way, which means the client application that invokes the Web service never receives a response, including any exceptions. In Version 6.1, all Web services were synchronous request-response, which meant that every time a client application invoked a service the client received a response. See WebLogic Web Service Deployment Descriptor Elements.

- The 7.x WebLogic Server Administration Console has a new Web Services Components deployment node for easy administration of Web services. See Administering WebLogic Web Services.

- Version 7.x of WebLogic Server includes UDDI server-side and client-side features. See Publishing and Finding Web Services Using UDDI.

- The 7.x Web Services Home Page has been enhanced from that of 6.1; the new page includes a facility to test your Web service. See The WebLogic Web Services Home Page and WSDL URLs.

Unsupported Features

WebLogic Server does not support the following WSDL and XML Schema features:

- Overloading operations in WSDL, due to a SOAP limitation

- XML Schema complex data type inheritance by restriction

- XML Schema union simple data types

Editing XML Files

When creating or invoking WebLogic Web services, you might need to edit XML files, such as the web-services.xml Web services deployment descriptor file, the EJB deployment descriptors, the Java Ant build files, and so on. You edit these files with the BEA XML Editor.

Note: This guide describes how to create or update the web-services.xml deployment descriptor manually so that programmers get a better understanding of the file and how the elements describe a Web service. You can also use the BEA XML Editor to update the file.

The BEA XML Editor is a simple, user-friendly Java-based tool for creating and editing XML files. It displays XML file contents both as a hierarchical XML tree structure and as raw XML code. This dual presentation of the document gives you two options for editing the XML document:

- The hierarchical tree view allows structured, constrained editing, with a set of allowable functions at each point in the hierarchical XML tree structure. The allowable functions are syntactically dictated and in accordance with the XML document's DTD or schema, if one is specified.

- The raw XML code view allows free-form editing of the data.

The BEA XML Editor can validate XML code according to a specified DTD or XML schema.

For detailed information about using the BEA XML Editor, see its online help.

You can download the BEA XML Editor from dev2dev Online.