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 SOAP 1.1 and 1.2 as the message format and HTTP and JMS as the connection protocol.
- A standard for describing the Web Service to clients so they can invoke it.
WebLogic Web Services use WSDL 1.1, an XML-based specification, to describe themselves.
- 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.
- A standard for digitally signing or encrypting the SOAP request and response messages between a client application and the Web Service it is invoking.
WebLogic Web Services implement the Web Services Security Core specification, Working Draft Version 1.0.
- 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 specification.
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.
|
java.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 Working Draft 1.0 specification dated April 5, 2002:
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 Web Services Security Core Specification (Working Draft Version 1.0, dated April 5 2002).
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
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.
- 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. 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 java.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
- 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
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.
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 the 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.
- 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 the 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.
- 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 the own serialization class to convert data between XML and Java; and so on.
- 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 the Web Service is fairly simple, use the servicegen Ant task, which performs all the assembly steps for you. If the Web Service is more complicated, use individual Ant tasks.
- 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.
- Create a client that accesses the Web Service to test that the Web Service is working as you expect. You can also use the Web Service Home Page to test the Web Service.
- Configure additional WebLogic Web Service features, such as security, reliable SOAP messaging, JMS transport, internationalization, and so on. See:
- Test the WebLogic Web Service after you add features.
- Deploy the WebLogic Web Service for production.
- Optionally publish the Web Service in a UDDI registry.
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
.
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.
|
|
|