ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

BEA Implements New Web Services Standard

by Robert Baccus

With its new product, WebLogic Workshop, BEA Systems is aiming at bringing more developers -- especially Microsoft Visual Basic developers -- into the Java Web services fold. WebLogic Workshop builds on a new file format standard, Java Web Services (JWS). JWS is intended to allow developers to focus on application logic, rather than tedious J2EE and Web services plumbing. This article introduces the JWS file format and the standard initiatives around it.

The JWS Standard

The JWS file format standards initiative is captured in JSR 181, "Web Services Metadata for the Java Platform," currently undergoing work in the Java Community Process. This standard builds upon JSR 175, "A Metadata Facility for the Java Programming Language," which is working to provide a general purpose mechanism for adding metadata to Java code. This standard provides the guidelines for developing a meta language that will annotate Java classes, interfaces, fields, and methods with attributes that can be used by development tools to indicate they should be processed in a special way. WebLogic Workshop is one application that implements the Java Language Metadata standard in the specific format of a JWS tag in the JWS file format.

The goal of the JWS standard is to provide an easy-to-learn and easy-to- use programming interface through the use of simple Java Language Metadata tags that will provide the commonly-needed functionality required to build robust, maintainable, and interoperable Web services.

JWS tags describe those tasks that are common to Web service developers by implementing standard J2EE components. It also handles the necessary tasks to deploy Web services, so developers are free from learning the complexities of deployment descriptors or APIs. For example, if you want to write a Web service that accesses a database without using the JWS file format and tags, you would have to do all of the work of getting the JDBC connection, handling the transactions and exceptions, and submitting a SQL statement. Then, to deploy, you would have to provide the necessary deployment descriptors in the XML configuration file for your Web service server. Using the JWS tags provided by WebLogic Workshop, you create an interface file ("controls" in WebLogic Workshop's terminology) that contains the annotations for the SQL statement before the method declaration.

 * @jws:sql  statement="INSERT INTO PLAYERS (NAME, NUMBER) VALUES ({playerName},{number})"
 * @throws java.sql.SQLException
void insertPlayer(String playerName, int number) throws SQLException;

Then, to use this control in your JWS file, you just have to access it like any other object, so:

 * @jws:operation
public void start()
      luckyNumberDBControl.insertPlayer("Fred", 5);
  catch (SQLException ex)
      System.out.println("LuckyNumberDB.start: " + ex.getMessage());

To deploy a JWS file in WebLogic Workshop, you just run the Web service, which automatically compiles and deploys the source JWS file. This "write and run" model is similiar to JSP pages, where the container does the work to automatically compile and deploy the Web service. The tool provides the database connection and EJB-related code, configures the deployment descriptors, and provides the support to use the SOAP 1.1 protocol to communicate with clients. If someone wants to call your Web service as a client, the tool also automatically provides a WSDL-1.1-formatted file, or a Java file with the proxy source code for your Web service.

A Look at the Tags

Once JSR 181 becomes an official standard, this powerful, easy-to-use technology will enable developers using different platforms and tools to create standards-based Web services. The main purpose of the JWS specification is to leverage the core Web services standards (SOAP, WSDL, and UDDI) to provide an easy-to-use development environment. There is no intent to extend or change any of these other standards. The innovations that the JWS standard is providing are the specific JWS annotations and file formats based on these other standards.

O'Reilly Emerging Technologies Conference

The 2002 O'Reilly Emerging Technologies Conference explored how P2P and Web services are coming together in a new Internet operating system.

Let's look at some examples of JWS annotations, or tags, as they are commonly called. In BEA's implementation, tags must be in a JavaDoc comment block, though the order of the JWS tags does not matter. As a side note, the WebLogic Workshop IDE provides a graphical design view that automatically adds the JWS tags when you insert, or set properties on, a control in your JWS file, and when you add methods or edit those methods through the design view. It also removes the related tags when you remove controls or methods from your Web service.

Let's look at two of the most common basic JWS tags. The @jws:operation tag describes an external service method that other Web services can call. When you have a method that you want to expose as a Web service, just put the @jws:operation tag in the JavaDoc comments right before the method declaration, and the tool handles the rest. The @jws:control tag defines any external service to the JWS file you are currently writing. It can be anything from a database to a custom EJB, or just another JWS file that you have in your arsenal.

Now that we have a basic control and we can provide our own Web service methods to others, we need to look at some issues raised when communicating over the Internet. The first issue is that of interoperability across platforms. We have already shown that using the SOAP and WSDL standards will solve the problem by sharing information across businesses and platforms. The second issue is that of loosely-coupled integration, which allows you to develop applications over time without "breaking" your clients when you change implementations or, in some cases, interfaces. The third issue that is important for businesses is reliability. The JWS standard gives implementers of the specification the flexibility to address these issues. WebLogic Workshop provides a good demonstration of how this standard can be used to solve the issues of loosely-coupled integration and reliability.

Web Service Interface

One way to provide loosely-coupled integration is to provide an interface or public contract that other developers will use to implement your Web service. This contract will stipulate what data objects, in the form of XML messages, your Web service expects. Using just the WSDL will not provide the total loosely-coupled integration in full, because this WSDL could be automatically created by your tool and can change over time. What is needed is a map between the XML public contract, or WSDL, and how it relates to the Java code and objects of your Web service. WebLogic Workshop uses XML Maps to accomplish this loose-coupling integration between public contracts or the implemented interface and code. Below is an example of an XML Map.

 public static class ReportResult implements java.io.Serializable
        public String bank;
        public String tax;

 * @jws:parameter-xml
 *      xml-map::
 *      <creditReport>
 *              <bankReport>{resultMsg.bank}<bankReport>
 *              <taxReport>{resultMsg.tax}<taxReport>
 *      <creditReport>
void onReportDone(ReportResult resultMsg);

In this example, you describe what you want the incoming XML document to look like, and then map the data portion of the XML document to your object. The object needs to be defined or accessible to your Web service, and in this case the ReportResult class is defined as an inner class with only the member variables bank and tax as public strings. Using this method, you can extend your method to use any incoming or outgoing XML message that is independent of your Java code and any future changes. As long as your clients and you adhere to this XML contract, you are both free to make changes at any time to your implementation.

Other than loosely-coupled development, other issues are reliability and the more common (but related) problem of unpredictable latency among different applications or systems. For example, say that you are writing a Web service to access patient records and report any drug allergies they may have. Your Web service makes a call to the Web service that exposes the hospital records system requesting drug allergies for the given patient's ID. What you may not know, though, is that their records are all paper and require that someone receive your request and process it manually; this could take days. So what happens to your Web service during this time? At this point, the Web service would wait for days, wasting valuable CPU time and resources.

WebLogic Workshop allows developers to communicate asynchronously with other Web services using buffered messages using JMS queues. Using a message buffer tag -- @jws:message-buffer enable="true" -- on a service method converts it from a synchronous method to an asynchronous method. This replaces the need to create "listeners" for asynchronous messages. Message buffers store incoming messages from a client Web service on the local server machine, and then return a void result to them immediately, freeing them from waiting on your Web service to process the message. When using the message buffer on a callback, or outgoing message, your local service then is free to return, so it does not have to wait for the client to process your message.


BEA Systems, Inc.

Java Community Process(SM) Program

"Web Services Metadata for the Java Platform", JSR 181

"Java Langauage Metadata", JSR 175

One issue message buffers do not handle, though, is the more complex task of managing multiple messages between two related Web services. Conversations can be used as a metaphor to describe a series of message exchanges between two parties in both directions that are related or share the same topic or context. WebLogic Workshop uses this model of a "Web service conversation" to better describe and handle multiple messages between Web services that share the same context. The JWS standard provides the flexibility to implement this complex metaphor with some very easy tags.

To start a conversation with your Web service, you add the @jws:conversation phase="start" tag to a method that will start the conversation. To continue conversations, just change the phase to continue; to finish the conversation set the phase to finish. Each method that handles these three phases can now use member variables and access the state of the JWS objects. Callbacks are used to provide the bidirectional behavior of the conversation. Callbacks are interfaces that your Web service provides and the client implements. When your service wants to asynchronously return information to the client, a callback provides that functionality. Callbacks are defaulted to use the continue phase and are allowed to use the finish phase, but are never allowed to have a start phase in a conversation. We can see that using conversations with callbacks provide a very reliable framework for communicating between Web services that may or may not be reliable in and of themselves.


In a nutshell, the JWS standard provides a quick and simple framework using existing standards and technologies to empower developers of all levels -- from beginning application developers to J2EE experts. BEA has started the process and is leading the effort, since they have the first implementation of the standard. But with help from other companies and J2EE experts, others will likely implement this standard in the future. This is good news to all those corporate developers out there looking to use and build Web services across platforms. JSW's ease of use will help even the most seasoned J2EE developer to write quicker and more reliable Web services for use across the enterprise.

Robert Baccus is an expert developer and engineer with BEA Systems, Inc.

Return to ONJava.com.