Welcome!

Websphere Authors: Liz McMillan, Bob Gourley, Gilad Parann-Nissany, Yeshim Deniz, RealWire News Distribution

Related Topics: Websphere

Websphere: Article

The WebSphere Application Server 5 Web Services Technology Preview

The WebSphere Application Server 5 Web Services Technology Preview

Last month we described two new specifications that define the handling of Web services in J2EE, JSR101/JAX-RPC, and JSR109. Both will be part of the J2EE 1.4 release, which is scheduled to go public by the end of the summer. In this article, we will show an example of an implementation of both new standards, which is provided in the Web Services Tech Preview for WebSphere Application Server 5.

This tech preview comes as a free download from the Web, giving you a head start on the new APIs. We will show you two examples, one that takes you through the creation of a Web service that is offered to external clients, and a second showing how to develop a client to an existing Web service.

We will assume that you are familiar with the basic Web services technologies like SOAP and WSDL. See the Resources section at the end for pointers to more material on those topics. We will also assume that you have read our previous article, "Web Services Standards" (WSDJ, Vol. 2, issue 3), describing the JSR101 and JSR109 specifications, or are otherwise familiar with them.

The WAS 5 Web Services Tech Preview
WebSphere Web Services for J2EE Technology Preview is based on the open-source Apache Axis project as a runtime engine, but also includes some enhancements, such as specialized serializers/deserializers for complex objects to obtain better performance. Axis is SAX-based, which makes it faster than implementations based on DOM parsers. Moreover, the deployment model is different; it follows the JSR109 specification, which Axis does not support.

It is important to note that the preview does not "support Axis"; instead, it supports the new standards and reuses some of the Axis work where it makes sense.

To obtain the tech preview installable package (approx. 10MB), download it from the WebSphere Developer Domain site at www7b.boulder.ibm.com/wsdd/downloads/ web_services.html. Before installing it, you must already have either WebSphere Application Server (WAS) version 5 or WebSphere Application Client version 5 installed. The installation process is pretty straightforward; simply follow the instructions.

For our example, the generated EAR (enterprise application archive) file will be deployed using the usual WAS deployment mechanisms, either through the Admin Console, or via the wsadmin tool. The tech preview installation modifies the WAS administration code so that there are two additional "dialogs" in the WAS Admin Console (and additional prompts using wsadmin). We'll show you what they look like later in the article.

There is not much more to say about the tech preview in particular. It implements both JAX-RPC and JSR109, so all the things we described in our earlier article are supported. Having said that, let's dive into a concrete example.

Creating a New Web Service
There are different approaches to creating a new Web service, depending on your environment and your requirements. If some business function implementation already exists (in the form of a JavaBean or EJB), you would use the so-called bottom-up approach (see Figure 1). The tech preview provides a tool called "Java2WSDL" to generate the WSDL description from existing Java code.

On the other hand, a case may arise in which your Web services interface has already been defined in the form of a WSDL document (for example, if a service interface has been standardized for a particular industry). In this case, you would use the so-called top-down approach (see Figure 2). Again, the tech preview offers a tool to handle automatic generation of code and other artifacts. This tool, called WSDL2Java, not only generates the appropriate deployment descriptors, it can also create the service endpoint interface and an implementation class with stubs for the required methods.

We will take you through an example using the bottom-up approach. We will assume that we have a class called WorkOrderManager that lets you create new WorkOrder objects or retrieve an existing WorkOrder by its number. We will then generate a WSDL file for this Java code using the Java2WSDL tool, followed by the WSDL2Java tool to create the deployment descriptor files. Finally, we will assemble all of these into a Web module and EAR, which we can install into the application server.

The first artifact that we will create is the service endpoint interface (SEI). It represents the Web service's port type to be published and contains all the methods we want to expose (see Listing 1).

Note how the interface extends java.rmi.Remote and how every method throws a java.rmi.Remote Exception. This is mandated by the JAX-RPC specification.

Next is the source code for the WorkOrder class (see Listing 2). What you should note here is that the class implements java.io.Serializable. This is a requirement for a nonbasic Java type that appears on the interface of a Web service (similar to parameters on an EJB's remote interface).

The WorkOrder class will be mapped to an XML Schema by the Java2WSDL tool. This schema then becomes part of the WSDL definition for our Web service.

Finally, Listing 3 shows the code for the WorkOrderManagerImpl class, which implements the service. We kept the code very simple, because we want to focus on the creation of the Web service artifacts here. A real business application would certainly look different.

After you have compiled these three classes (WorkOrder, WorkOrderManager, and WorkOrderManagerImpl), you are ready to generate the WSDL document.

The Java2WSDL Tool
The first of the tech preview tools that we will use is the Java2WSDL tool, which generates the WSDL file from the SEI class. It is located in the <was_install_root>\bin directory.

We assume here that the code exists in the c:\was5tp\tech\preview directory, and that you have added c:\was5tp to your classpath. Make c:\was5tp your current directory and enter this command:

java2wsdl tech.preview.WorkOrderManager

This will create a WSDL file called WorkOrderManager. wsdl. You will receive a message indicating that "the -location was not set,...". The location point of the Web service will be specified when you install the application in WAS, so you can ignore this message for now.

We have now created the contract that our Web service exposes and can use as the input for creating all other artifacts needed to deploy the service.

The WSDL2Java Tool
We will now use the WSDL2Java tool with the generated WorkOrderManager.wsdl file as input to generate the Web service deployment descriptor templates:

wsdl2java -verbose -META-INF-Only
-server-side Bean -output . WorkOrderManager.wsdl

This will create two directories, META-INF and WEB-INF, with the following Web service deployment descriptor files:

  • META-INF:
    -webservicesclient.xml: This file is the deployment descriptor for any client that uses the Web service and runs in a J2EE client container.
    -WorkOrderManager_mapping.xml: This file contains the mapping between a namespace that is used in the WSDL document and the Java package that is used in the Java code.
    -ibm-webservicesclient-bnd.xml: This file is used to create definitions for securely accessing the Web service.
  • WEB-INF:
    -webservices.xml: This is the Web service deployment descriptor that defines the new Web service to the application server.
    -WorkOrderManager_mapping.xml: This file is an exact copy of the one created in the META-INF directory.
    -ibm-webservices-bnd.xml: Again, this file is used if you want to secure your Web service.

    Generally, the files in the META-INF directory are used for a client to the Web service, whereas the files in the WEB-INF directory are used for server-side deployment. The only files defined in the standard are the webservices. xml and webservicesclient.xml deployment descriptors; the other files are specific to WebSphere.

    The only modification you need to make is in the webservices.xml file. Make this change :

    <servlet-link>WorkOrderManager</servlet-link>

    This binds the Web service to a particular implementation, the WorkOrderManager class. We will reuse this value later when we assemble the application (i.e., it will go into the web.xml deployment descriptor for the Web application).

    Creating the EAR File
    Now we can go ahead and assemble the generated files into an archive file that we can install into the application server. Do this using the Application Assembly Tool (AAT) that comes with WAS. You can start it by entering "assembly" on the command line.

    Choose to create a new Web module. Since this is all standard AAT business, we won't describe it in detail here and will simply refer to the AAT documentation for more info. Name the new Web module "WorkOrderManager Web.war".

    Add all of the class files to the new Web module. They go into the \WEB-INF\classes\tech\preview directory. Moreover, you need to add a new Web component, a servlet. Its name is WorkOrderManager (this is referenced from within the webservices.xml file) and its class is tech.preview.WorkOrderManagerImpl. Note that even though this class is not really a servlet, it is defined as one in the Web module deployment descriptor. During deployment the application server will make this class accessible as a Web service (by effectively wrapping it into a servlet that receives the SOAP request and invokes the appropriate method on the bean). Save the new Web module and exit the AAT.

    Now move the WorkOrderManager.wsdl file into the c:\was5tp\WEB-INF directory. On the command line, type the following command to add the remaining files to the module:

    jar -uvf WorkOrderManagerWeb.war WEB-INF/*

    Using the AAT again, create the EAR application (WorkOrderManager.ear) and import the Web module WorkOrderManagerWeb.war. Make its context root "/workorder". This is all business as usual and does not require any special steps for the Web service.

    Installing the Application
    Now you are ready to deploy and install the enterprise application into WebSphere Application Server. As we already mentioned, the installation process is similar to that of any other enterprise application. After installing the technical preview, there are two additional steps. First, the system asks for the location to place the WSDL files. Enter "c:\was5tp" into that field. This will export the resulting WSDL file to the c:\was5tp\WorkOrderManager.ear\WorkOrderManagerWeb.war\ WorkOrderManagerService directory. We will need it later when we create the client.

    The second new step requires information about the protocol, hostname, and port on which the Web service will run. You can leave all the defaults. The WSDL file in the Web module is updated with the new endpoint, and a copy is exported to the defined directory.

    After installing the enterprise application, save the configuration, start the WorkOrderManager.ear application, and your Web service is ready to go!

    Accessing an Existing Web Service
    Now that you have a Web service ready and waiting to be called, we want to create a client to use this service. We will access the service that we just created; however, this could also be any other Web service described by a WSDL document.

    The client interface we will use is based on the JAX-RPC standard, as described earlier. A JAX-RPC-compliant Web service client can run stand-alone or in a J2EE client container. We will keep things simple here by running the client from the command line.

    The only input we will need is the exported WSDL file from the installation of the enterprise archive with the Web service. Feel free to delete the files generated before; they are all safely installed in the application server and we don't need them here anymore. Copy the WorkOrderManager.wsdl file to the c:\was5tp directory. Now use the WSDL2Java tool again to create the client-side bindings for the service: wsdl2java WorkOrderManager.wsdl

    This will create the classes we need on the client side. All of the generated Java files go into the tech\preview directory:

  • WorkOrder.java: This class is generated from the XML Schema for WorkOrder in the XML Schema.
  • WorkOrder_Deser.java.,WorkOrder_Ser.java, WorkOrder_Helper.java: These classes serve as helpers to convert an XML document into a WorkOrder object and vice versa.
  • WorkOrderManager.java: This is the interface of the Web service. (Yes, we had these classes before, but remember that we generate all of this only from the WSDL file.)
  • WorkOrderManagerService.java: This interface extends the javax.xml.rpc.Service interface and provides some convenient methods to obtain proxies to the Web service dynamically.
  • WorkOrderManagerServiceLocator.java: This class is an implementation of the foregoing interface.
  • WorkOrderManagerSoapBindingStub.java: This class represents the actual proxy, but you will never use it directly in your client program.

    The WSDL2Java tool created a number of deployment descriptor files in the META-INF directory. These files would be needed if we were to access the Web service from within a J2EE client container. We already described them earlier when creating the server-side deployment descriptions. We won't need them here, because we will run the client from the command line. (In Java standards lingo, we are using a "J2SE client.")

    Go ahead and compile all of the generated Java files. To do so, you need the following set of JAR files in your classpath. They can be found in the <was_install_root> \lib directory: axis.jar, qname.jar, jaxrpc.jar, j2ee.jar, commons-logging-api.jar, commons-discovery.jar, and saaj.jar.

    And finally, Listing 4 is a small test application that uses the Web service, which creates two new WorkOrder objects and then retrieves one of them.

    Conclusion
    The new standards for providing and consuming Web services will help developers create portable and interoperable Web services applications across a variety of application servers. While this is coming later this year in the J2EE 1.4 specification, IBM provides you with an early implementation of the new standards on top of WebSphere Application Server 5, allowing you to get a head start on becoming familiar with the new APIs. Also later this year, complete tooling will follow as part of WebSphere Studio Application Developer.

    Resources

  • JAX-RPC: http://java.sun.com/xml/jaxrpc
  • JSR109: http://jcp.org/en/jsr/detail?id=109
  • The WAS 5 Web Services Tech Preview: www7b.boulder.ibm.com/wsdd/downloads/ web_services.html
  • WebSphere Version 5 Web Services Handbook: http://publib-b.boulder.ibm.com/Redbooks.nsf/ RedpieceAbstracts/sg246891.html?Open
  • High, R.; Herness, E.; Rochat, K.; Francis, T.; Vignola, C.; and Knutson, J. (2003). Professional IBM WebSphere 5.0 Application Server. Wrox.
  • The IBM developerWorks Web services zone: www.ibm.com/developerworks/webservices
  • More Stories By Andre Tost

    André Tost is a Senior Technical Staff Member in the WebSphere Business Development group where he helps IBM?s Strategic Alliance partners integrate their applications with WebSphere. His special focus is on Web services technology throughout the WebSphere product family. Before his current assignment, he spent ten years in various development and architecture roles in IBM software development, most recently for the WebSphere Business Components product. Originally from Germany, he now lives and works in Rochester, Minnesota.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.