Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Web Services

# Introduction to WebLogic Web Services

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

- Overview of Web Services
- Why Use Web Services?
- Web Service Standards
- WebLogic Web Service Features
- Unsupported Features
- Examples of Creating and Invoking a Web Service
- Creating WebLogic Web Services: Main Steps
- Roadmap to Common Tasks for Creating Web Services
- Editing XML Files

# Overview of Web Services

Web Services are a special 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 has evolved toward loosely coupled service-oriented applications that interact dynamically 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.

This 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 requires the following standard implementations:

- 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 Java classes; and are packaged as standard J2EE Enterprise Applications.

- A standard for transmitting 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 and JMS as the connection protocol. See SOAP.

- A standard for describing 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 for client applications to invoke a Web Service.

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

- A standard for digitally signing and encrypting the SOAP request and response messages between a client application and the Web Service it is invoking.

WebLogic Web Services implement the following OASIS Standard 1.0 Web Services Security specifications, dated April 6 2004:

- Web Services Security: SOAP Message Security
- Web Services Security: Username Token Profile
- Web Services Security: X.509 Token Profile

For more information, see Web Services Security (WS-Security).

- A standard 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.

## BEA Implementation of Web Service Specifications

Many of the specifications that define Web Service standards have been written in an intentionally vague way to allow for broad use of the specification throughout the industry. Because of this vagueness, BEA's implementation of a particular specification might not cover all possible usage scenarios covered by the specification.

BEA considers interoperability of Web Services platforms to be more important than providing support for all possible edge cases of the Web Services specifications. For this reason, BEA fully supports the Basic Profile 1.0 specification from the Web Services Interoperability Organization and considers it to be the baseline for Web Services interoperability. BEA implements all requirements of the Basic Profile 1.0, although this guide does not necessarily document all of these requirements. This guide does, however, document features that are beyond the requirements of the Basic Profile 1.0."

## SOAP

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 SOAP 1.1, SOAP 1.2, and SOAP With Attachments (SAAJ) 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.

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>

For more information, see SOAP 1.1 and SOAP With Attachments API for Java (SAAJ) 1.1 .

## 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 a client application connects 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>

For more information, see Web Services Description Language (WSDL) 1.1.

## JAX-RPC 1.0

The Java API for XML-based RPC (JAX-RPC) 1.0is a Sun Microsystems specification that defines the Web Services APIs.

WebLogic Server implements all required features of the JAX-RPC Version 1.0 specification. Additionally, WebLogic Server implements optional data type support, as specified in:

- Supported Built-In Data Types
- Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks

WebLogic Server does not implement optional features of the JAX-RPC specification, other than what is described in these sections.

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 invoke a Web Service dynamically.
JAXRPCException | Exception thrown if an error occurs while invoking a Web Service.

For detailed information on JAX-RPC, see 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.

## Web Services Security (WS-Security)

The following description of Web Services Security is taken directly from the OASIS standard 1.0 specification, titled Web Services Security: SOAP Message Security, dated April 6, 2004:

This specification proposes a standard set of SOAP extensions that can be used when building secure Web services to implement integrity and confidentiality. We refer to this set of extensions as the Web Services Security Language or WS-Security.

WS-Security is flexible and is designed to be used as the basis for the construction of a wide variety of security models including PKI, Kerberos, and SSL. Specifically WS-Security provides support for multiple security tokens, multiple trust domains, multiple signature formats, and multiple encryption technologies.

This specification provides three main mechanisms: security token propagation, message integrity, and message confidentiality. These mechanisms by themselves do not provide a complete security solution. Instead, WS-Security is a building block that can be used in conjunction with other Web service extensions and higher-level application-specific protocols to accommodate a wide variety of security models and encryption technologies.

These mechanisms can be used independently (for example, to pass a security token) or in a tightly integrated manner (for example, signing and encrypting a message and providing a security token hierarchy associated with the keys used for signing and encryption).

For more information, see the OASIS Web Service Security Web page.

## UDDI 2.0

The Universal Description, Discovery and Integration (UDDI) specification defines a standard for describing a Web Service; registering a Web Service in a well-known registry; and discovering other registered Web Services.

For more information, see http://www.uddi.org.

## Additional Specifications Supported by WebLogic Web Services

- XML Schema Part 1: Structures
- XML Schema Part 2: Data Types
- JSSE (part of JDK 1.4)

# WebLogic Web Service Features

The WebLogic Web Services subsystem has the following features (new features in Version 8.1 of WebLogic Server are listed first):

- Digital Signatures and Encryption - New 8.1 Feature

New elements in the `web-services.xml` deployment descriptor enable you to configure message-level security for Web Services and Web Service clients. See Configuring Message-Level Security: Main Steps.

- Reliable SOAP Messaging - New 8.1 Feature

Reliable SOAP messaging is a framework whereby an application running in one WebLogic Server instance can asynchronously and reliably invoke a Web Service running on another WebLogic Server instance. See Using Reliable SOAP Messaging.

- Asynchronous Client Invocation of WebLogic Web Services - New 8.1 Feature

The `clientgen` Ant task can now generate stubs for invoking a Web Service operation asynchronously. The stub contains two methods: the first invokes the operation with the required parameters but does not wait for the result to return; later, the second method returns the actual results. You use this asynchronous client when using reliable SOAP messaging. See Writing an Asynchronous Client Application.

- JMS Transport Protocol - New 8.1 Feature

You can configure a Web Service to use JMS as the transport protocol (as opposed to HTTP/S, the default protocol) when a client accesses the service. See Using JMS Transport to Invoke a WebLogic Web Service.

- Portable Stubs - New 8.1 Feature

You can now use portable stubs (versioned client JAR files used to invoke WebLogic Web Services) to avoid class clashes when invoking a Web Service from within WebLogic Server. See Creating and Using Portable Stubs.

- Implementation of the SOAP with Attachments API For Java (SAAJ) 1.1 - New 8.1 Feature

SAAJ enables developers to produce and consume messages conforming to the SOAP 1.1 specification and SOAP with Attachments note. This specification is derived from the `javax.xml.soap` package originally defined in the JAXM 1.0 specification.

See Directly Manipulating the SOAP Request and Response Message Using SAAJ for information about using SAAJ in a SOAP message handler to view and manipulate a SOAP attachment.

- SOAP 1.2 Support - New 8.1 Feature

WebLogic Server provides support for using SOAP 1.2 as the message format when a client invokes a Web Service operation. See Using SOAP 1.2.

- 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.

- 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 Choosing 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 from Client Applications and WebLogic Server.

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 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 Transport-Level Security (SSL): Main Steps.

- 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 from Client Applications and WebLogic Server.

# Unsupported Features

The following list describes the features that are not supported in this release of WebLogic Web Services:

- WebLogic Server does not support the XMLBeans data type as an input parameter or return value of a Web Service operation.
- WebLogic Server does not support the following XML Schema features:

- Complex data type inheritance by restriction
- Union simple data types
- References to named model groups
- Nested content models in a single complex type
- Redefinition of declarations
- Identity constraints (key, keyref, unique)
- Wildcards
- Substitution groups

Note: If you use the `autotype`, `servicegen`, or `clientgen` Ant tasks to generate the serialization components for any non-built-in XML Schema data type that uses one of the preceding constructs (either directly or by containing a type that uses them), the Ant tasks map that data type to `javax.xml.soap.SOAPElement`. This gives you access to the full XML via a DOM-like API.

Additionally, the `autotype` Ant task does not comply with the JAX-RPC specification if the XML Schema data type (for which it is generating the Java representation) has certain characteristics; see Data Type Non-Compliance with JAX-RPC for details.

- WebLogic Server does not support the following WSDL features:

- Overloading operations in WSDL, due to a SOAP limitation
- HTTP GET and POST bindings
- Faults with complex types
- RPC literal style
- Document encoded style
- `solicit-response` and `notification` transmission primitives

# 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/examples/src/examples/webservices` directory, where `WL_HOME` refers to the main WebLogic Platform directory:

- `basic.statelessSession`: Uses a stateless session EJB back-end component with built-in data types as its parameters and return value.
- `basic.javaclass`: Uses a Java class back-end component with built-in data types as its parameters and return value.
- `complex.statelessSession`: Uses a stateless session EJB back-end 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 back-end component.
- `client.static_no_out`: Shows how to create a static client application that invokes a non-WebLogic Web Service.
- `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.

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

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

# 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 an RPC- or document-oriented Web Service; 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 basic WebLogic Web Service.

Write and compile 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 unit (either an EAR file or in exploded directory format).

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 individual Ant tasks.

See Assembling WebLogic Web Services Using Ant Tasks.

4. Deploy the basic WebLogic Web Service for testing purposes.

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 Deploying WebLogic Server Applications.

5. 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 from Client Applications and WebLogic Server.

6. Configure additional WebLogic Web Service features, such as security, reliable SOAP messaging, JMS transport, internationalization, and so on. See:

- Configuring Security
- Using Reliable SOAP Messaging
- Using JMS Transport to Invoke a WebLogic Web Service
- Internationalization

7. Test the WebLogic Web Service after you add features.

See Deploying and Testing WebLogic Web Services.

8. Deploy the WebLogic Web Service for production.

See Deploying WebLogic Server Applications.

9. Optionally publish your Web Service in a UDDI registry. See Publishing and Finding Web Services Using UDDI.

# Roadmap to Common Tasks for Creating Web Services

The following table provides a roadmap of common tasks for creating, deploying, and invoking WebLogic Web Services

.

Table 1-2 Web Services Tasks

Major Task | Subtasks and Additional Information
--- | ---
Create (implement) the Web Service back-end components. | Overview of Implementing a WebLogic Web Service
Writing the Java Code for the Components
Generating a Partial Implementation From a WSDL File
Creating SOAP Message Handlers to Intercept the SOAP Message
Using SOAP Attachments
Using Built-In and Non-Built-In Data Types
Implementing Non-Built-In Data Types
Supported Built-In Data Types
Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks
Throwing SOAP Fault Exceptions
Using the WebLogic Web Services APIs
Assemble the Web Service into a deployable unit. | Overview of Assembling WebLogic Web Services Using Ant Tasks
Assembling WebLogic Web Services Using the servicegen Ant Task
Assembling WebLogic Web Services Using Individual Ant Tasks
Assembling a Web Service Starting with Java
Assembling a Web Service Starting with an XML Schema
Deploy and test the Web Service. | Deploying and Testing WebLogic Web Services
WebLogic Web Services Home Page and WSDL URLs
Invoke the Web Service. | Overview of Invoking Web Services
Creating Java Client Applications to Invoke Web Services: Main Steps
Writing an Asynchronous Client Application
Invoking Web Services from WebLogic Server
Secure the Web Service. | Overview of Web Services Security
Configuring Message-Level Security: Main Steps
Configuring Transport-Level Security (SSL): Main Steps
Configuring Access Control Security: Main Steps
Add advanced features. | Using Reliable SOAP Messaging
Internationalization
Upgrade a 6.1 or 7.0 WebLogic Web Service. | Upgrading a 7.0 WebLogic Web Service to 8.1
Upgrading a 6.1 WebLogic Web Service to 8.1
Troubleshoot problems. | Using the Web Service Home Page to Test Your Web Service
Viewing SOAP Messages
Posting the HTTP SOAP Message
Debugging Problems with WSDL
Verifying a WSDL File
Verifying an XML Schema
Debugging Data Type Generation (Autotyping) Problems

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