Automate Web services with Ant and WebSphere

Use WebSphere Ant tasks to develop and test Web services

By combining the open source Ant build tool and IBM® WebSphere® Ant tasks, you can create a repeatable build process to reduce time and mistakes when you build and update Web service applications. This article shows how to use WebSphere's Ant tasks to develop a Web service and install it into WebSphere Application Server.

Brent J. Ulbricht (ulbricht@us.ibm.com), Software Engineer, IBM

Brent Ulbricht is the WebSphere Web services Engine Functional Verification Test Team Lead. He has worked on creating and automating Web services engine tests since WebSphere's introduced Web services. You can reach Brent at ulbricht@us.ibm.com.



07 June 2006

Introduction

Ant is a widely used development tool for building and automating processes using XML files. By using some of the core Ant tasks along with WebSphere's custom Ant tasks you can develop a Web service application and install it into WebSphere Application Server. In this article, you'll learn how to create and install a Web service-enabled Enterprise Java™ Bean (EJB) by supplying a service endpoint interface, a few standard Java 2 Enterprise Edition (J2EE) deployment descriptors, and an Ant build file.

Requirements

This article assumes that you have WebSphere Application Server installed. The listings and sample code included with this article were developed using Application Server V6.0.2. WebSphere includes a version of Ant in the default install. You can use it by executing the ws_ant.bat/sh file in the WebSphere bin directory (C:\WebSphere\AppServer\bin\ws_ant.bat).


Why use Ant?

The advantages of using Ant to build a Web service application include:

  • Repeatability - The ability to change a few settings or code in an application and regenerate the entire application is invaluable. Using an Ant build file, the steps to create the application are the same each time, which improves productivity and consistency.
  • Automatability - An Ant XML build file can run without human interaction during nightly or scheduled builds. The Ant process can run in build environments without the need for a terminal.
  • Platform independence - Ant runs on all major platforms from Windows® to OS/390.
  • Availability - WebSphere contains Ant when installed, and also includes some custom Ant tasks for automating tasks in WebSphere.
  • Skills - A wealth of articles and books exist on using Ant. Its pervasive use in the Java community means that many developers now have the skills to develop Ant build files.

Create a Web service with Java2WSDL

In this example, the starting point for creating the Web service is a service endpoint interface (SEI) from which Java2WSDL generates a WSDL file. The WSDL file is a key piece in building a Web service. After its creation, the WSDL2Java tool can process the WSDL file to generate many of the artifacts to create a working Web service application.

The SEI defined in Listing 1 contains a simple helloWorld method that sends and receives a String. The JSR-101 specification defines the rules for creating a SEI.

Listing 1. Service Endpoint Interface
  package example;

  interface WSExample extends java.rmi.Remote {
 
      String helloWorld(String message);

  }

The first step in creating an Ant build file is to define which custom WebSphere Ant tasks the build process will use. You can find the API for all WebSphere Ant tasks in the the WebSphere Information Center. You may find it helpful to view the Ant documentation while working on Ant build files to determine how to use the core Ant tasks that come with each version of Ant.

In Listing 2, the build file contains many <taskdef> statements, a core Ant element. These statements enable Ant to use the custom WebSphere Ant tasks that we'll use throughout the rest of this example.

Listing 2. Define tasks
  <path id="lib.path">
	<pathelement location="${WSAS.home}/lib/*.jar"/>
  </path>                    

  <taskdef name="wsdl2java"
           classname="com.ibm.websphere.ant.tasks.WSDL2Java">
    <classpath refid="lib.path"/>
  </taskdef>

  <taskdef name="java2wsdl"
           classname="com.ibm.websphere.ant.tasks.Java2WSDL">
    <classpath refid="lib.path"/>
  </taskdef>

  <taskdef name="endptenabler"
           classname="com.ibm.websphere.ant.tasks.endptEnabler">
    <classpath refid="lib.path"/>
  </taskdef>

  <taskdef name="wsdeploy"
           classname="com.ibm.websphere.ant.tasks.WSDeploy">
    <classpath refid="lib.path"/>
  </taskdef>

  <taskdef name="wsejbdeploy"
           classname="com.ibm.websphere.ant.tasks.WsEjbDeploy">
     <classpath refid="lib.path"/>
  </taskdef>

  <taskdef name="installapp"
           classname="com.ibm.websphere.ant.tasks.InstallApplication">
    <classpath refid="lib.path"/>
  </taskdef>

The first execution statement in the Ant build file compiles the SEI as shown in Listing 3. With the compiled SEI class in the classpath, the custom WebSphere Java2WSDL Ant task can generate a WSDL file. Note that you should manually verify the WSDL file generated by Java2WSDL at least once after its initial creation. In some cases, the WSDL file generated may not contain the exact XML schema types desired due to mapping rules between Java and XML. For a description of the XML schema mappings between Java and XML, view the JSR-101 specification.

The Java2WSDL Ant task contains a number of options to allow you to customize the generated WSDL file. Check out the Javadoc for more specifics about each attribute and its valid values.

Listing 3. Java2WSDL Ant task
  <!-- Compile the SEI class -->    
  <javac srcdir="${WSAS.home}/bin"
         destdir="${WSAS.home}/bin">
    <classpath refid="lib.path"/>
    <include name="WSExample.java"/>
  </javac>                         

  <!-- With the SEI class in the classpath, run the java2wsdl task -->
	<java2wsdl output="${WSAS.home}/bin/tmp/META-INF/wsdl/WSExample.wsdl"
             classpath="${WSAS.home}/bin"
             className= "example.WSExample"
             namespace="http://example"
             namespaceImpl="http://example"
             location="http://localhost:9080/example/services/WSExample"
             style="document"
             use="literal">
    <mapping namespace="http://example" package="example"/>
  </java2wsdl>

Use WSDL2Java

Now that we've created a WSDL file using the Java2WSDL Ant task, we can start generating the remaining Web service files. The WSDL2Java Ant task creates a number of necessary files for developing a complete Web service enabled application.

These files include both XML files and Java files. The XML files generated include:

  • webservices.xml
  • mapping_file.xml

The Java files include:

  • Service Endpoint Interface
  • EJB home
  • EJB remote
  • EJB implementation class

As with the Java2WSDL Ant task, the WSDL2Java Ant task has many attributes you can use to customize the generation of the Web services files. View the Javadoc for WSDL2Java for more specifics.

In Listing 4, the role and container attributes are develop-server and EJB, respectively. These attributes signal to the WSDL2Java Ant task to generate the server development files for an EJB.

Listing 4. WSDL2Java Ant task
  <wsdl2java url="${WSAS.home}/bin/WSExample.wsdl"
             output="${WSAS.home}/bin/tmp"
             role="develop-server"
             container="EJB"
             introspect="false"
             verbose="false">
  </wsdl2java>

You must create two standard J2EE deployment descriptors and an EJB implementation class outside of the Ant build process:

  • ejb-jar.xml - packaged in the EJB JAR file
  • application.xml - packaged in the EAR file
  • WSExampleSoapBindingImpl.java - EJB implementation class

Although the WSDL2Java Ant task generates a template EJB implementation class, in our example we'll replace it with one that has some customized business logic.

In the webservices.xml file created by WSDL2Java, you must change the element, <ejb-link>, to match the <ejb-name> in the ejb-jar.xml. Listing 5 shows the ejb-jar.xml file created outside of the build process, and the webservices.xml file created by WSDL2Java.

Listing 5. ejb-jar.xml and webservices.xml
  <!-- 
    The ejb-jar.xml is created manually outside of the automated
    build process and packaged in the EJB jar.
  -->      
  <?xml version="1.0" encoding="UTF-8"?>
  <ejb-jar id="ejb-jar_ID" version="2.1"
      xmlns="http://java.sun.com/xml/ns/j2ee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                  http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">
    <display-name>WSExample</display-name>
    <enterprise-beans>
      <session id="Session_1">
        <ejb-name>WSExample</ejb-name>
        <home>example.WSExampleHome</home>
        <remote>example.WSExample_RI</remote>
        <service-endpoint>example.WSExample</service-endpoint>
        <ejb-class>example.WSExampleSoapBindingImpl</ejb-class>
        <session-type>Stateless</session-type>
        <transaction-type>Container</transaction-type>
      </session>
    </enterprise-beans>
  </ejb-jar>
                                                                            
                                                                            
  <!--
    The WSDL2Java Ant task generates this webservices.xml file.
  -->                                                                          
  <?xml version="1.0" encoding="UTF-8"?>
  <webservices xmlns="http://java.sun.com/xml/ns/j2ee"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  version="1.1"
                  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                   http://www.ibm.com/webservices/xsd/j2ee_web_services_1_1.xsd">
      <webservice-description>
          <webservice-description-name>WSExampleService</webservice-description-name>
          <wsdl-file>META-INF/wsdl/WSExample.wsdl</wsdl-file>
          <jaxrpc-mapping-file>META-INF/WSExample_mapping.xml</jaxrpc-mapping-file>
          <port-component>
              <port-component-name>WSExample</port-component-name>
              <wsdl-port xmlns:pfx="http://example">pfx:WSExample</wsdl-port>
              <service-endpoint-interface>example.WSExample</service-endpoint-interface>
              <service-impl-bean>
                  <ejb-link>??SET THIS TO ejb-name ELEMENT OF ejb-jar.xml??</ejb-link>
              </service-impl-bean>
          </port-component>
      </webservice-description>
  </webservices>

You must replace the <ejb-link> element with the actual <ejb-name> supplied in the ejb-jar.xml file shown in Listing 5. The core Ant replace task is perfect for this task, as shown in Listing 6.

Listing 6. Replace <ejb-link>
  <replace file="${WSAS.home}/bin/tmp/META-INF/webservices.xml"
           token="??SET THIS TO ejb-name ELEMENT OF ejb-jar.xml??"
           value="WSExample"/>

Build the application

After WSDL2Java runs, the WSDL2Java generated classes need to be compiled, as well as any additional or customized classes needed in the Web service enabled EJB application. In Listing 7, the javac core Ant task compiles the classes.

Listing 7. Compile classes
  <javac srcdir="${WSAS.home}/bin/tmp/**/*.java"
            destdir="${WSAS.home}/bin/tmp/classes">
    <classpath refid="lib.path"/>
    <include name="WSExample.java"/>
  </javac>

Once all the classes have compiled, the Ant build file creates a standard J2EE JAR file to contain all the compiled Java classes and XML files. Listing 8 shows the core jar Ant task used for completing this step.

Listing 8. Create JAR
  <jar jarfile="${WSAS.home}/bin/tmp/WSExample.jar">
    <fileset dir="${WSAS.home}/bin/tmp">
      <include name="**/*.class"/> 
    </fileset>
    <zipfileset dir="${WSAS.home}/bin/tmp/META-INF" prefix="META-INF">
      <include name="**/*"/>
    </zipfileset>
  </jar>

After running the jar task, the following files exist in the EJB JAR:

  • META-INF/MANIFEST.MF
  • META-INF/ejb-jar.xml
  • META-INF/ibm-webservices-bnd.xmi
  • META-INF/ibm-webservices-ext.xmi
  • META-INF/webservices.xml
  • META-INF/WSExample_mapping.xml
  • META-INF/wsdl/WSExample.wsdl
  • example/WSExample.class
  • example/WSExampleHome.class
  • example/WSExampleSoapBindingImpl.class
  • example/WSExample_RI.class

Listing 9 shows the completion of the Web service application by adding the EJB JAR file created in Listing 8 to a standard J2EE EAR file. Ant provides a core ear task to perform this operation.

Listing 9. Create EAR
    <ear earfile="${WSAS.home}/bin/tmp/WSExample.ear"
         appxml="${WSAS.home}/bin/tmp/META-INF/application.xml">
      <fileset dir="${WSAS.home}/bin/tmp">
        <include name="WSExample.jar"/>
      </fileset>
    </ear>

After execution of the ear task, the resulting EAR contains these files:

  • META-INF/MANIFEST.MF
  • META-INF/application.xml
  • WSExample.jar

Before you install

In order for EJBs enabled as Web services to be reachable through the HTTP protocol, they must have an HTTP router in the application. WebSphere's endptenabler Ant task adds this router to the EAR file. As shown in Listing 10, the property elements added to the endptenabler task allow for customization of the router modules that get created. For complete documentation of the options, view the JavaDoc.

Listing 10. EndpointEnabler
  <endptenabler earfile="${WSAS.home}/bin/tmp/WSExample.ear">
    <property key="verbose" value="false"/>
    <property key="WSExample.transports" value="http"/>
    <property key="WSExample.http.rounterModuleName" value="WSExample_HTTPRouter.war"/>
    <property key="WSExample.http.contextRoot" value="wsexample"/>
  </endptenabler>

The last step prior to installing this application into WebSphere Applicaton Server is to run wsejbdeploy and wsdeploy tasks. wsejbdeploy creates all the classes necessary for communicating with an EJB. Listing 11 shows an example of how to use the wsejbdeploy task.

Listing 11. EJBDeploy Task
  <wsejbdeploy inputJar="${WSAS.home}/bin/tmp/WSExample.ear"
               wasHome="${WSAS.home}"
               workingDirectory="${WSAS.home}/tmp"
               outputJar="${WSAS.home}/bin/tmp/WSExampleDeployed.ear"               
               codegen="false"
               keepGenerated="false"
               quiet="true"
               noValidate="false"
               noWarnings="false"
               noInform="false"
               failonerror="true"
               trace="false"/>

wsdeploy generates any WebSphere-specific Web services artifacts necessary for communicating with the application. The example invocation of wsdeploy validates and produces special classes such as WebSphere-specific serializers and deserializers.

Listing 12. WSDeploy Task
  <wsdeploy classPath=""
            debug="false"
            ignoreErrors="false"
            inputFile="${WSAS.home}/bin/tmp/WSExampleDeployed.ear"
            noValidate="false"
            outputFile="${WSAS.home}/bin/tmp/WSExampleReadyToInstall.ear"
            trace="false"/>

Install the application

You can now install the the application into WebSphere using the install Ant task, as shown in Listing 13. The example assumes that WebSphere is not running, because it uses a conntype of NONE.

Listing 13. Install the application
  <installapp wasHome="${WSAS.home}"
              ear="${WSAS.home}/bin/tmp/WSExampleReadyToInstall.ear"
              options="-usedefaultbindings"
              conntype="NONE"
              failonerror="true"/>

Run the application

To run the sample application, download the sample code. Unzip it in C:\WebSphere\AppServer\bin and execute the folllowing command:

"C:\WebSphere\AppServer\bin\ws_ant.bat -DWSAS.home=C:\WebSphere\AppServer -f C:\WebSphere\AppServer\bin\build.xml


Conclusion

In this article, you've learned an automated way to build and install a Web service enabled application. WebSphere provides a rich set of Ant tasks to perform many operation. You can combine these tasks to create processes that are repeatable, less error-prone, and faster.


Download

DescriptionNameSize
Code samplesexample.zip  ( HTTP | FTP )5KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, SOA and web services
ArticleID=126754
ArticleTitle=Automate Web services with Ant and WebSphere
publish-date=06072006