Programming Web Services for WebLogic Server
|
 |
 |
|
 |
 |
Understanding WebLogic Web Services
The following sections provide an overview of WebLogic Web Services as implemented by WebLogic Server:
- What Are Web Services?
- Why Use Web Services?
- Anatomy of a WebLogic Web Service
- Roadmap of Common Web Service Development Tasks
- Standards Supported by WebLogic Web Services
What Are Web Services?
A Web Service is a set of functions packaged into a single entity that is available to other systems on a network and can be shared by and used as a component of distributed Web-based applications. The network can be a corporate intranet or the Internet. Other systems, such as customer relationship management systems, order-processing systems, and other existing back-end applications, can call these functions to request data or perform an operation. Because Web Services rely on basic, standard technologies which most systems provide, they are an excellent means for connecting distributed systems together.
Traditionally, software application architecture tended to fall into two categories: monolithic systems such as those that ran on mainframes or client-server applications running on desktops. Although these architectures worked well for the purpose the applications were built to address, they were closed and their functionality could not be easily incorporated into new applications.
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 accessible 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 integration of the application's functionality into other services on the network. 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 using widely supported Web protocols such as HTTP.
- Web Services describe themselves using an XML-based description language.
- Web Services communicate with clients (both end-user applications or other Web Services) through simple XML messages that can be produced or parsed by virtually any programming environment or even by a person, if necessary.
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.
Anatomy of a WebLogic Web Service
WebLogic Web Services are implemented according to the Enterprise Web Services 1.1 specification (JSR-921), which defines the standard J2EE runtime architecture for implementing Web Services in Java. The specification also describes a standard J2EE Web Service packaging format, deployment model, and runtime services, all of which are implemented by WebLogic Web Services.
Note: JSR-921 is the 1.1 maintenance release of JSR-109, which was the J2EE 1.3 specification for Web Services. JSR-921 is currently in final release of the JCP (Java Community Process).
The Enterprise Web Services 1.1 specification describes that a J2EE Web Service is implemented by one of the following components:
The code in the Java class or EJB is what implements the business logic of your Web Service. BEA recommends that, instead of coding the raw Java class or EJB directly, you use the JWS annotations programming model instead, which makes programming a WebLogic Web Service much easier.
This programing model takes advantage of the new JDK 5.0 metadata annotations feature in which you create an annotated Java file and then use Ant tasks to compile the file into a Java class and generate all the associated artifacts. The Java Web Service (JWS) annotated file is the core of your Web Service. It contains the Java code that determines how your Web Service behaves. A JWS file is an ordinary Java class file that uses annotations to specify the shape and characteristics of the Web Service. The JWS annotations you can use in a JWS file include the standard ones defined by the Web Services Metadata for the Java Platform specification (JSR-181) as well as a set of WebLogic-specific ones.
For more information on the JWS programming model, see Programming the JWS File,
After you create the JWS file, you use the jwsc WebLogic Web Service Ant task to compile the JWS file into either a Java class or a stateless session EJB, as described by the Enterprise Web Services 1.1 specification. You typically do not need to decide this backend implementation of the Web Service; the jwsc Ant task picks the optimal implementation based on the JWS annotations you have specified in the JWS file. The jwsc Ant task also generates all the supporting artifacts for the Web Service, packages everything into an archive file, and creates an Enterprise Application that you can then deploy to WebLogic Server.
If the jwsc Ant task implements your Web Service with a Java class, then jwsc packages the Web service in a standard Web application WAR file with all the standard WAR artifacts, such as the web.xml and weblogic.xml deployment descriptor files. The WAR file, however, contains additional artifacts to indicate that it is also a Web Service; these additional artifacts include the webservices.xml and weblogic-webservices.xml deployment descriptor files, the JAX-RPC data type mapping file, the WSDL file that describes the public contract of the Web Service, and so on.
Similarly, if the jwsc Ant task implements your Web Service with a stateless session EJB, then jwsc packages the Web Service in a standard EJB JAR file with all the usual artifacts, such as the ejb-jar.xml and weblogic-ejb.jar.xml deployment descriptor files. The EJB JAR file also contains additional Web Service-specific artifacts, as described in the preceding paragraph, to indicate that it is a Web Service.
Note: The jwsc Ant task actually creates a stateless EJB wrapper around the JWS file; your business logic is still in the Java class that contains the JWS annotations. But because of the EJB wrapper, the task must package the service in an EJB JAR file and the Web Service is considered to be EJB-implemented.
If you want your business logic to reside in the actual EJB, then your JWS file must explicitly implement javax.ejb.SessionBean.
In addition to programming the JWS file, you can also configure one or more SOAP message handlers if you need to do additional processing of the request and response SOAP messages used in the invoke of a Web Service operation.
Once you have coded the basic WebLogic Web Service, you can program and configure additional advanced features. These include being able to invoke the Web Service reliably (as specified by the WS-ReliableMessaging specification, dated February 4, 2005) and also specify that the SOAP messages be digitally signed and encrypted (as specified by the WS-Security specification). You configure these more advanced features of WebLogic Web Services using WS-Policy files, which is an XML file that adheres to the WS-Policy specification and contains security- or Web Service reliable messaging-specific XML elements that describe the security and reliable-messaging configuration, respectively.
Roadmap of Common Web Service Development Tasks
The following table provides a roadmap of common tasks for creating, deploying, and invoking WebLogic Web Services.
Standards Supported by WebLogic Web Services
A Web Service requires the following standard specification implementations or conformance:
- A standard programming model used to develop the Web Service.
The WebLogic Web Services programming model uses standard JDK 1.5 metadata annotations, as specified by the Web Services Metadata for the Java Platform specification (JSR-181) See Web Services Metadata for the Java Platform (JSR-181).
- A standard implementation hosted by a server on the Web.
WebLogic Web Services are hosted by WebLogic Server and are implemented using standard J2EE components, as defined by the Implementing Enterprise Web Services 1.1 specification (JSR-921, which is the 1.1 maintenance release of JSR-109). See Enterprise Web Services 1.1.
- 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 as the message format and HTTP as the connection protocol. See SOAP 1.1.
WebLogic Web Services implement the SOAP with Attachments API for Java 1.2 specification to access any attachments to the SOAP message. See SAAJ 1.2.
- 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.
WebLogic Web Services uses WS-Policy to describe additional functionality and requirements not addressed in WSDL 1.1. WebLogic Web Services conform to the WS-Policy and WS-PolicyAttachment specifications when using policies to describe their reliable messaging and security (digital signatures and encryption) functionality. See WS-Policy 1.0 and WS-PolicyAttachment 1.0.
- A standard for client applications to invoke a Web Service.
WebLogic Web Services implement the Java API for XML-based RPC (JAX-RPC) 1.1 as part of a client JAR that client applications can use to invoke WebLogic and non-WebLogic Web Services. See JAX-RPC 1.1.
- 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) 1.0.
- A standard way for two Web Services to communicate asynchronously.
WebLogic Web Services conform to the WS-Addressing 1.0 and WS-ReliableMessaging 1.0 specifications when asynchronous features such as callbacks, addressing, conversations, and Web Service reliable messaging.
- A standard for client applications to find a registered Web Service and to register a Web Service.
BEA Implementation of Web Service Specifications
Many specifications that define Web Service standards are written so as to allow for broad use of the specification throughout the industry. Thus the BEA 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. BEAcomplies with the Basic Profile 1.1 specification from the Web Services Interoperability Organization and considers it to be the baseline for Web Services interoperability. This guide does not necessarily document all of the Basic Profile 1.1 requirements. This guide does, however, document features that are beyond the requirements of the Basic Profile 1.1.
Web Services Metadata for the Java Platform (JSR-181)
Although it is possible to program a WebLogic Web Service manually by coding the standard JSR-921 EJB or Java class from scratch and generating its associated artifacts by hand (deployment descriptor files, WSDL, data binding artifacts for user-defined data types, and so on), the entire process can be difficult and tedious. For this reason, BEA recommends that you take advantage of the new JDK 1.5 metadata annotations feature and use a programming model in which you create an annotated Java file and then use Ant tasks to convert the file into the Java source code of a standard JSR-921 Java class or EJB and automatically generate all the associated artifacts.
The Java Web Service (JWS) annotated file (called a JWS file for simplicity) is the core of your Web Service. It contains the Java code that determines how your Web Service behaves. A JWS file is an ordinary Java class file that uses JDK 1.5 metadata annotations to specify the shape and characteristics of the Web Service. The JWS annotations you can use in a JWS file include the standard ones defined by the Web Services Metadata for the Java Platform specification (JSR-181) as well as a set of WebLogic-specific ones.
Enterprise Web Services 1.1
The Implementing Enterprise Web Services 1.1 specification (JSR-921) defines the programming model and runtime architecture for implementing Web Services in Java that run on a J2EE application server, such as WebLogic Server. In particular, it specifies that programmers implement J2EE Web Services using one of two components:
The specification also describes a standard J2EE Web Service packaging format, deployment model, and runtime services, all of which are implemented by WebLogic Web Services.
Note: JSR-921 is the 1.1 maintenance release of JSR-109, which was the J2EE 1.3 specification for Web Services.
SOAP 1.1
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 the SOAP 1.1 specification. 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:7001
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.
SAAJ 1.2
The SOAP with Attachments API for Java (SAAJ) specification describes how developers can produce and consume messages conforming to the SOAP 1.1 specification and SOAP with Attachments notes.
The single package in the API, javax.xml.soap, provides the primary abstraction for SOAP messages with MIME attachments. Attachments may be entire XML documents, XML fragments, images, text documents, or any other content with a valid MIME type. In addition, the package provides a simple client-side view of a request-response style of interaction with a Web Service.
For more information, see 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>
The WSDL specification includes optional extension elements that specify different types of bindings that can be used when invoking the Web Service. The WebLogic Web Services runtime:
- Fully supports SOAP bindings, which means that if a WSDL file includes a SOAP binding, the WebLogic Web Services will use SOAP as the format and protocol of the messages used to invoke the Web Service.
- Ignores HTTP GET and POST bindings, which means that if a WSDL file includes this extension, the WebLogic Web Services runtime skips over the element when parsing the WSDL.
- Partially supports MIME bindings, which means that if a WSDL file includes this extension, the WebLogic Web Services runtime parses the element, but does not actually create MIME bindings when constructing a message due to a Web Service invoke.
For more information, see Web Services Description Language (WSDL) 1.1.
JAX-RPC 1.1
The Java API for XML-based RPC (JAX-RPC) 1.1 is a Sun Microsystems specification that defines the Java APIs for making XML-based remote procedure calls (RPC). In particular, these APIs are used to invoke and get a response from a Web Service using SOAP 1.1, and XML-based protocol for exchange of information in a decentralized and distributed environment.
WebLogic Server implements all required features of the JAX-RPC Version 1.1 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.
Web Services Security (WS-Security) 1.0
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 March 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).
WebLogic Web Services also implement the following token profiles:
- Web Services Security: Username Token Profile
- Web Services Security: X.509 Certificate Token Profile
- Web Services Security: SAML Token Profile
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.
JAX-R 1.0
The Java API for XML Registries (JAXR) provides a uniform and standard Java API for accessing different kinds of XML Registries. An XML registry is an enabling infrastructure for building, deploying, and discovering Web services.
Currently there are a variety of specifications for XML registries including, most notably, the ebXML Registry and Repository standard, which is being developed by OASIS and U.N./CEFACT, and the UDDI specification, which is being developed by a vendor consortium.
JAXR enables Java software programmers to use a single, easy-to-use abstraction API to access a variety of XML registries. Simplicity and ease of use are facilitated within JAXR by a unified JAXR information model, which describes content and metadata within XML registries.
For more information, see Java API for XML Registries.
WS-Addressing 1.0
The WS-Addressing specification provides transport-neutral mechanisms to address Web services and messages. In particular, the specification defines a number of XML elements used to identify Web service endpoints and to secure end-to-end endpoint identification in messages.
All the asynchronous features of WebLogic Web Services (callbacks, conversations, and Web Service reliable messaging) use addressing in their implementation, but Web Service programmers can also use the APIs that conform to this specification stand-alone if additional addressing functionality is needed.
See Web Services Addressing (WS-Addressing).
WS-Policy 1.0
The Web Services Policy Framework (WS-Policy) specification provides a general purpose model and corresponding syntax to describe and communicate the policies of a Web Service. WS-Policy defines a base set of constructs that can be used and extended by other Web Services specifications to describe a broad range of service requirements, preferences, and capabilities.
See Web Services Policy Framework (WS-Policy).
WS-PolicyAttachment 1.0
The Web Services Policy Framework (WS-Policy) specification defines an abstract model and an XML-based expression grammar for policies. This specification, Web Services Policy Attachment (WS-PolicyAttachment), defines two general-purpose mechanisms for associating such policies with the subjects to which they apply. This specification also defines how these general-purpose mechanisms can be used to associate WS-Policy with WSDL and UDDI descriptions.
See Web Services Policy Attachment (WS-PolicyAttachment).
WS-ReliableMessaging 1.0
The WS-ReliableMessaging specification (February 4, 2005) describes how two Web Services running on different WebLogic Server instances can communicate reliably in the presence of failures in software components, systems, or networks. In particular, the specification provides for an interoperable protocol in which a message sent from a source endpoint to a destination endpoint is guaranteed either to be delivered or to raise an error.
See Web Services Reliable Messaging Protocol (WS-ReliableMessaging).
