Programming WebLogic Web Services
The following sections provide an overview of Web Services, and briefly describe how they are implemented in WebLogic Server:
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:
Major benefits of Web Services include:
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.
A Web Service requires the following standard implementations:
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.
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.
WebLogic Web Services use Web Services Description Language (WSDL) 1.1, an XML-based specification, to describe themselves. See WSDL 1.1.
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.
WebLogic Web Services implement the following OASIS Standard 1.0 Web Services Security specifications, dated April 6 2004:
For more information, see Web Services Security (WS-Security).
WebLogic Web Services implement the Universal Description, Discovery, and Integration (UDDI) specification. See UDDI 2.0.
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 (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:
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 .
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.
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:
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.
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.
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.
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.
The WebLogic Web Services subsystem has the following features (new features in Version 8.1 of WebLogic Server are listed first):
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 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.
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.
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.
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.
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.
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.
Ant tasks facilitate the implementation and packaging of Web Services. See Web Service Ant Tasks and Command-Line Utilities.
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.
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.
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.
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.
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.
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.
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.
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.
The following list describes the features that are not supported in this release of WebLogic Web Services:
There cannot be a modelgroup (say sequence) that contains another nested modelgroup (say choice), and a content element (say element). So, if a nested modelgroup is required, make sure that it contains only another model group and no other content element.
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 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
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.
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.
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.
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.
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.
The following table provides a roadmap of common tasks for creating, deploying, and invoking WebLogic Web Services
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 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.