Today's trend is to integrate existing systems in a standard way to make disparate implementations interoperate. Web Services and XML came along with the ability to provide a standard communication interface between these systems, as well as the standard description language - WSDL - the Web Services Description Language that lets those systems define the structure of the services they're providing. Web Services are built using three classic components:
- SOAP - Simple Object Access Protocol - the XML-based communication protocol for sending data using Web Services.
- WSDL - Web Services Description Language - the XML-based language that describes the Web Service that's provided by a particular system and how to access it.
- UDDI - Universal Description Discovery Integration - a directory that helps to identify dynamically where particular Web Services are and how to find them, as well as a means of publishing services for those who want to provide them.
There's also a wide variety of complementary standards that deal with things such as security (WS-Security), policy (WS-Policy), and reliability (WS-Reliability) to provide standard ways of ensuring secure and reliable communications through Web Services. However, these are beyond the scope of this article, which covers the basics of Web Services development using Eclipse Integrated Development Environment (IDE) and the Web Tools Project. Generally, developing Web Services in Java can be either bottom-up or top-down. In the bottom-up development mode, we start with an existing Java application and with either a Java bean or Stateless Session EJB. According to Java Web Services standards (JSR 101/109), only such Java entities can be used as a source of possible Web Services. The IDE helps us generate WSDL from these entities, as well as service wrappers and locators ensuring easy access to them from inside the application code. With the top-down approach, those wrappers and service locators get generated from an existing WSDL file.Software prerequisites before one can start using Web Services with Eclipse include:
- J2SE 5.0 JRE: http://java.sun.com/j2se
- Eclipse 3.1.1: www.eclipse.org
- Eclipse Web Tools Project (WTP) 1.0: (this can also be automatically downloaded and installed into Eclipse using its Help - Software Updates menu). When this article was written, this was the latest WTP release (released on December 23, 2005).
- Tomcat 5.0: http://jakarta.apache.org/tomcat/ (must be already installed and configured in Eclipse - if not, make sure to do this by going to the Eclipse Window menu, selecting Preferences, Server, Installed Runtimes, and then using Add button, select Tomcat 5.0 runtime, where you have to specify the location of the Tomcat server installation on your computer). Please refer to the article on creating Web applications with WTP for more detailed instructions on configuring Tomcat in Eclipse WTP: http://java.sys-con.com/read/152270.htm.
Suppose we want to build a Web Service that will give us the stock price quotes - including the latest price, volume, and trade date/time. For purposes of this demonstration, we'll use a simple application providing this service. Please note that this application adheres to Java Bean standards and implements appropriate getter and setter methods as well as the no-argument constructor.
Our simple application will consist of two classes: StockData and StockService. This application will provide information about stock price, volume, and trade date/time for a single item that we'll call "Our Stock" with the symbol OURS. The StockData class is a simple Java Bean that holds the stock's information. StockService holds the stock name and symbol and the history of its trading (we generate it randomly). These are the public methods that are available in the StockService class:
public double getLatestPrice() - returns the latest price of Our Stock
public long getLatestVolume(); - returns the latest volume number
public java.util.Date getLatestDateTime(); - returns the latest trade date
public String getStockName(); - returns stock name (preset to Our Stock)
public void setStockName(String nm); - sets the stock name to nm
public String getStockSymbol(); - returns stock symbol (preset to OURS)
public void setStockSymbol(String sb); - sets the stock symbol to sb
public void setLatestStockData(double price, long volume);
- sets the latest stock data (adds another stock data object into our history)
public String getStockHistory(); - returns history of stock trading for Our Stock
Only public Java methods can be invoked using Web Services. To avoid platform interoperability issues and to be compliant with the JAX-RPC standard of simple-type encoding, we keep the method return parameters and arguments to simple Java types. The complete code of our StockData and StockService classes will be available with the article's source code (Please see Listing 1).
Let's start building a Web Service from our StockService Java Bean. Please note that a similar procedure can be followed for an EJB Web Service, except in that case we have to build a stateless Session EJB first. Also, in the case of an EJB Web Service, an EJB project would have to be created in Eclipse, rather than the so-called Dynamic Web Project that we're building now.
First, we create a Dynamic Web Project called StockWeb. We'll use the Eclipse Web Tools wizard to create the Dynamic Web Project by selecting File-New-Other from the menu and then expand Web to Dynamic Web Project, which will bring up the screen depicted in Figure 1.
Press Finish to create the StockWeb project. Once created, we'll import our StockData.java and StockService.java files into the JavaSource directory. To import, simply highlight "JavaSource" and select File - Import from the menu and specify "File System" as a type of import. The wizard that appears allows the developer to specify the location of the files to be imported. Once we have these files imported (an appropriate package called "services" will be automatically created), we'll simply highlight StockService class, right-click, and select Web Services - Create Web Service from the context menu.
Figure 2 shows several important notations:
- Web Service Type: Bottom-up and Top-down - we already went through what those mean - since we're creating a Web Service from an existing Java Bean, it's a Bottom-up Web Service, so this selection will be automatically highlighted.
- Start Web Service in Web project makes sure that the Web Service is started when the wizard finishes creating it. Basically this ensures that when the Web Service creation wizard finishes, the Web Service will be automatically started along the Web project that contains it.
- Generate a Proxy: the only proxy type here is Java Proxy. This helps create a static proxy class - a Java bean class that would simplify invoking this Web Service from within the application. It would actually act as a Web Service client.
- Test the Web Service: specifies whether we want to automatically launch the associated Tomcat runtime to launch the Web project along with the Web Service and see if it works.
- Monitor the Web Service: Eclipse Web Tools include a built-in monitor that helps monitor SOAP envelopes -XML-based definitions of communication chunks flowing back and forth between the client and service.
- Overwrite files without warning and Create folders when necessary: they're pretty much self-explanatory.
- Check out files without warning: is for use with source code management (SCM) systems such as PVCS, CVS, or ClearCase - file are checked out (locked for editing by a particular developer) automatically.
The next screen is very important; it configures the service's deployment. Since we've elected to generate a Web Service proxy (a client for our Web Service), a new Web project will be dynamically generated for us that contains all the classes for accessing and invoking our Web Services - our Web Services client (see Figure 4).
On this page, we can also select the J2EE version, Web Services runtime engine, and server where the Web Service will be deployed. We highly recommend selecting J2EE 1.4, and no lower, since with J2EE 1.4, Web Services became a part of the Java 2 Enterprise Edition platform, while previous versions treated them as a specific add-on. The Web Tools Project doesn't fully utilize this feature of J2EE yet; however, relying on it will position you better for future releases. Also, the only engine that the Web Tools Project currently supports is the Apache Axis engine. It's a second attempt by Apache to implement Web Services standards. The first attempt, called Apache SOAP, had some deficiencies, especially, major performance issues. Apache Axis seems to overcome these issues by using SAX parsers more often than the DOM ones. A new Web Project - StockWebClient - will be created for us to host the client Web application for our Web Service.
In Figure 5 we'll have a chance to select which methods in the StockService class should be exposed as Web Services. On this screen we'll also have a chance to select our Encoding scheme: Document/Literal versus RPC/Encoded. Generally speaking, Document/Literal is much more common and provides much greater interoperability between platforms, though RPC might provide somewhat better performance, so it may be considered for homogeneous platforms with no interoperability requirements. We'll select Document/Literal for greater interoperability; in our example we aren't particularly concerned about performance.
Please note that the screen in Figure 5 also designates the service URI and the location where the WSDL file will be generated. Once we click "Next" and pass this screen, the Web Service will be generated and the server will be launched so we can test this Web Service. The screen in Figure 6 specifies the testing facility for our Web Service, which is Web Services Explorer - it allows browsing and testing Web Services, invoking individual methods, and getting results. Click Finish to finish generating our Web Service. Once the service is started, Web Services Explorer is automatically launched, and we can test our Web Service as shown in Figure 7.
Select the WSDL page icon (highlighted in the screen in Figure 7) in the Web Services Explorer then click WSDL Main in the right pane; this gives us the opportunity to invoke the Web Service directly by pointing to its WSDL. When you click "Browse," the screen shown in Figure 8 appears.
On this screen, a developer can select a project from an Eclipse Workspace then select the WSDL URL available in this project, in our case StockService.wsdl. Pressing Go and then Go again brings us back to the WSDL Explorer screen (see Figure 9), where all the methods exposed as part of our Web Service interface are generated:
You can specify the parameters (if any are required) and invoke this method as necessary by clicking on a particular method.
Now let's take a look at the entities that were generated. First of all, it's the WSDL file, StockService.wsdl that gets automatically generated under the Web Content\wsdl directory. Eclipse provides a superior editor for editing WSDL files as shown in Figure 10.
It includes the following four major interrelated entities that describe every Web Service:
- Types: A container for data type definitions using XML schema type system.
- Messages: An abstract typed definition of the data being communicated. A message can have one or more typed parts, for example, the highlighted message getLatestDateTimeResponse has just one part that is its return parameter of xsd:date (XML Schema date type).
- Port types: Abstract sets of one or more operations supported by one or more ports.
- Operations: Abstract description of an action supported by the service that defines the input and output message as well as optional fault message.
- Bindings: Concrete protocol and data format specification for a particular port type. The binding information contains the protocol name, the invocation style, a service ID, and the encoding for each operation.
- Services: A collection of related ports.
- Ports: Single endpoints, which are defined as an aggregation of the binding and network addresses.
- StockServiceServiceLocator: the locator class has information about the Web Service, most importantly the address by which the service can be invoked (the HTTP address). The locator class is populated based on the content of the Web Service's WSDL file.
- StockService: the service endpoint interface that is a local representation of a Web Service. Through this interface, appropriate methods will be invoked.
- StockServiceSoapBindingStub: the stub that implements remote invocation methods defined by StockService interface.
- StockServiceService: the service locator interface that defines methods implemented by service locator class.
Invoking this client can be done simply through the command line or using the Eclipse: right-button menu, Run-As, Java Application. This demonstrates the remote communication that Web Services provide - we invoke a service that could be located on a different machine so long as we know the endpoint address of the service as defined in the StockServiceLocator. Here's the output of this class:
Stock name: Our Stock
Stock price: 30.63180066603478
Stock volume: 42475629656767
Building a Top-Down Web Service
The top-down approach is commonly used when we have a standard service definition and want to implement this definition to provide the requested service. Top-down Web Service design involves the following steps:
- First, we locate the WSDL document (either someone gives it to us, or sends it to us via email, or we locate it in Web Services Inspection Language (WSIL) document. Web Services Inspection Language (WSIL) allows one to describe multiple WSDL documents located within a site. We can also search UDDI registry for our Web Service.
- Next, we generate implementation skeleton (normally, a Java bean skeleton), which contains methods and parameters that we fill to implement our Web Service.
- Finally, using this skeleton, we complete all the methods with the appropriate logic.
It's very similar to the one we initially used in the Bottom-Up development section, when we clicked "Next"; it brings us to the screen where we can specify the location of the WSDL file as shown in Figure 12.
The next screen (see Figure 13) shows the service deployment configuration: which Web project, server, Web Services runtime, and J2EE version to deploy the new Web Service to. Note that we may want to select a different Web project (say StockWebOne) here so as not to overwrite our sample classes from the previous example.
Click Finish to generate a bunch of classes including the service endpoint interface, service locator, but also the most interesting of them, the StockServiceSoapBindingImpl class, where method stubs are provided for you to fill out the particular implementation of this Web Service as shown in Listing 2.
A developer has to fill out these method stubs with the appropriate logic - obviously the system can't do it automatically for him since the WSDL file that the Web Service is generated from in a top-down approach only has information about Web Service's interface, not the actual implementation.
Testing and Debugging Web Services
Testing and debugging Web Services is done using Web Services Explorer. It has three major panes: WSDL, WSIL, and UDDI. Each of these serves the purpose of finding and testing particular Web Services. In the WSDL pane you can do it directly by finding the WSDL document in your project. The WSIL pane makes it easier for a developer to locate and test a particular Web Service on a particular site. With the help of the UDDI interface, one can search private or public UDDI registries (a private registry usually belongs to a particular company and its intranet services, which are usually invoked by internal applications at that company. Public registries are available throughout the Internet and are hosted by companies such as Microsoft [see http://uddi.microsoft.com/] for public use.)
Another way to test Web Services is by generating sample JSP files that create a sample application communicating with the Web Service. This can be easily done by right-clicking on the Java Bean and selecting the Web Services - Generate Sample Pages after Web Service creation is finished.
You can also generate a client from a WSDL file. It will include the service locator, service binding stub, and service endpoint interface: right-click and select Web Services - Generate Client. This will let you construct a simple Java application using the generated classes, just as we did in top-down Web Services generation.
All Eclipse debugging facilities are available when testing Web Services. A developer can start servers in the debugging mode and set breakpoints at any line to do normal code debugging.
Eclipse also includes a TCP/IP monitor to watch the Web Service methods' executions. Figure 14 shows how the TCP/IP monitor lets you debug a Web Service by using a client that consists of generated sample JSP pages. The TCP/IP monitor contains three panes:
- The right-top pane includes a list of the interactions (requests/responses) that have been done in chronological order. When a developer clicks on a particular interaction, the system displays the time of request, how long it took the system to respond (in milliseconds), and the type of protocol that was used (in our case, HTTP).
- The left-bottom pane displays the contents of the SOAP envelope generated by the Web Service's request.
- The right-bottom pane displays the SOAP response envelope. Whenever we invoke a particular Web Service, this pane is populated with the response of the server in the SOAP (XML-based) format.
Conclusion
In this article, we've shown you how to develop bottom-up and top-down sample Web Services using the Eclipse Web Tools Project. Future articles will cover developing database-driven Web Services, security issues, and interoperability between Java and .NET.