Any program is only as good as it is useful. Linus Torvalds
Web Services are defined by W3C as a software system designed to support interoperable machine-to-machine interaction over a network.
What makes Web Services different from other forms of distributed computing is that information is exchanged using only simple and non-proprietary protocols. This means the services can communicate with each other regardless of location, platform, or programming language. Essentially, the Web Services protocols provide a platform-independent way to perform Remote Procedure Calls (RPCs).
The focus of this chapter will be on JBossWS, a Web Service framework developed as part of the JBoss Application Server, based on JSR 224 (Java API for XML-based web services 2.0).
You will get your hands on the following topics:
- A short introduction to Web Services
- How to create, deploy, and test Web Services using the JBoss WS and Eclipse
- Some advanced concepts about Web Services (Handler Chains, SOAP debugging)
As stated at the beginning of this chapter, Web Services are based on the exchange of messages using non-proprietary protocol messages. The messages themselves are not sufficient to define the Web Service platform. We actually need a list of standard components, including the following:
- A language used to define the interfaces provided by a Web Service, in a manner that is not dependent on the platform on which it is running or the programming language used to implement it
- A common standard format for exchanging messages between Web Service Producers and Web Service Consumers
- A registry within which the service definitions can be placed
The Web Service Description Language , that is, WSDL (http://www.w3.org/TR/wsdl) is the de facto standard for providing a description of the Web Service contract exposed to clients. In particular, a WSDL document describes a Web Service in terms of the operations that it provides and the data types that each operation requires as inputs and can return in the form of results.
The communication between the service provider and service consumer happens by means of XML messages, which rely on the SOAP protocol specification.
A basic SOAP message consists of an Envelope that may contain any number of headers and a body. These parts are delimited by XML elements called Envelope, Header, and Body, which belong to a namespace defined by the SOAP specification.
Once you have determined that your business needs to find a provider for a specific service, how do you find the businesses that offer that service, evaluate their offerings, and, if appropriate, fetch the WSDL definition for the service itself? The answer lies in the XML-based registries that are accessible through the Internet and contain the necessary information that allows businesses to discover and make use of the Web Services.
As we have just learned, the service description is provided by a commonly agreed document interface named the Web Service Description Language that exposes services as a collection of networks, endpoints, and ports, using the XML format.
You may logically be inclined to think that it is necessary to state at the beginning the contract of the service, and then produce the corresponding programming interfaces. Actually, you can follow two approaches for developing your web services:
- Top-down: This development strategy involves creating a Web Service from a WSDL file. The top-down approach is likely to be used when creating Web Services from scratch. It is the preferred choice of "purist" Web Service engineers because it's business-driven, that is, the contract is defined by business people and so the software is designed to fit the Web Service contract.
- Bottom-up: This approach requires generating the WSDL file from the programming interfaces. It is likely to be used when we have existing applications that we want to expose as Web Services. As it doesn't require a deep knowledge of the WSDL syntax, it's the easiest choice if you want to turn your Java classes or EJB into Web Services.
As the audience of this book is composed mainly of Java developers with little or no knowledge at all of WSDL basics, we will focus primarily on the bottom-up approach. However, in the following sections, we will teach the reader how to use JBoss Web Service tools to reverse the process of creation of Web Services, starting from a WSDL contract.
Designing top-down Web Services will require that you integrate the basic Web Services notions provided with this chapter with a comprehensive awareness of the WSDL standard.
If you surf on the JBossWS project page http://www.jboss.org/jbossws/, you will see that three main options are available to deploy Web Services on JBoss.
- JBossWS native
- Glassfish Metro
- Apache CXF
Each of these stacks has its own specific features and you are free to develop on JBoss AS choosing the one that is closest to your needs. In this book we will use JBoss WS Native, which is a Web Service framework developed to be part of JBoss AS' Java EE5 offering. JBoss WS native stack is based on the new Web Service specification called JAX WS, and is a follow-on release of the former JAX-RPC specification delivered by Sun in early 2002.
JAX-WS simplifies the task of developing Web Services by supporting Java JEE annotations for declaring Web Services. This API also addresses some of the issues of JAX-RPC, providing support for multiple protocols such as SOAP 1.1, SOAP 1.2, and XML, and by providing a facility for supporting additional protocols along with HTTP.
In the next section, we will deliver a high-level picture of the JAX WS Runtime architecture from the server point of view, showing the components that are involved for processing Web Services requests and responses.
When a SOAP message sent by the client enters the Web Service runtime environment, it is captured by a component named Server endpoint listener, which in turn uses the Dispatcher module to deliver the SOAP message to that Service.
At this point, the HTTP request is converted internally into a SOAP Message. The message context is extracted from the transport protocol and it is processed through the handler chain configured for the Web Service.
Tip
SOAP message handlers are used to intercept the SOAP messages as they make their way from the client to the endpoint service and vice versa. These handlers intercept the SOAP message for both the request and response of the Web Service. You will find this concept similar to EJB interceptors, which we have discussed in Chapter 4.
The next step is unmarshalling the SOAP message into Java objects. This process is governed by WSDL to Java mapping and XML to Java Mapping. The former is performed by the JAX-WS engine and determines which endpoint to invoke from the SOAP Message. The latter, performed by the JAXB libraries, deserializes the SOAP message so that it is ready to invoke the endpoint method.
Finally, the deserialized SOAP message reaches the actual Web Service implementation and the method is invoked.
Once the call is completed, the process is reversed. The return value from the Web Service method is marshalled into a SOAP response message using JAX-WS WSDL to Java mapping and the JAXB 2.0 XML to Java mapping.
Then the outbound message is processed by handlers before returning it to the Dispatcher and the endpoint listener, which will transmit the message as an HTTP response.
The following diagram describes how data flows from a Web Service client to a Web Service endpoint and back:
