Creating Apache Axis2 Web Services on NetBeans IDE

This tutorial shows you how to create and deploy an Apache Axis2 web service from a Java class. You also learn how to set up the Tomcat and GlassFish servers bundled with NetBeans IDE to deploy Axis2 web services. The tutorial also shows how to configure the Axis2 options in the IDE so that the IDE deploys Axis2 web services correctly.

Apache Axis is an implementation of the SOAP (Simple Object-Access Protocol) submission to the W3C. Apache Axis2 is a more efficient, more modular and more XML-oriented version of Axis. Axis2 not only supports SOAP 1.1 and SOAP 1.2, but it also has integrated support for RESTful web services. The same business logic implementation can offer both a WS-* style interface as well as a REST/POX style interface simultaneously. For more information about Axis2, please see the Apache.org website.

Axis2 web services are interoperable with Metro. You can create a JAX-WS client for an Axis2 web service, although some more complicated Axis2 WSDL operations may not be supported.

Contents

• Installing Apache Axis2 and Apache Ant
• Creating and Copying the Axis2 WAR File
• Setting Up Axis2 Options for Tomcat
• Setting Up Axis2 Options for GlassFish
• Creating an Axis2 Web Service
• Deploying and Testing an Axis2 Web Service
• Changing the Web Service's Operations
• More Exercises

To follow this tutorial, you need the following software and resources.

Software or Resource	Version Required
NetBeans IDE	version 6.1
Java Developer Kit (JDK)	version 6 or version 5
Apache Axis 2	version 1.3 or later
Apache Ant, installed and added to your path	latest version
Java EE-compliant web or application server	Tomcat web server 6.0 and/or GlassFish application server v2

Both Tomcat and GlassFish can be installed with the Web and Java EE distribution of NetBeans IDE. Alternatively, you can visit the GlassFish downloads page or the Apache Tomcat downloads page.

This tutorial also requires the Axis2 Support plugin. In the IDE, go to the Plugin Manager, under the Tools menu, and check whether Axis2 Support Plugin is installed, under the Installed tab. If it is not, install it from the Available Plugins tab, as shown below:

Installing Apache Axis2 and Apache Ant

Apache Axis2 and Apache Ant are both downloaded as archive files. Axis2 can be downloaded here and Ant can be downloaded here. To install these programs, unpack the downloaded archives to the locations of your choice. The installation directories will now be referred to as AXIS2_HOME and ANT_HOME respectively. After installing Ant, add the path to the ANT_HOME/bin directory to your classpath.

Creating and Copying the Axis2 WAR File

In order for you to deploy Axis2 web services to an application server, the server needs a copy of an axis2.war (Web ARchive) file. You can create an axis2.war file by running Apache Ant in your Axis2 installation directory. After you create axis2.war, copy it to Tomcat base and GlassFish.

To create and copy the Axis2 WAR file:

1. Navigate to AXIS2_HOME/webapp. Open a command prompt in this directory and run the ant command. Ant creates AXIS2_HOME/dist/axis2.war based on the AXIS2_HOME/webapp/build.xml file. You need to have ANT_HOME/bin on your classpath.
2. Copy AXIS2_HOME/dist/axis2.war to your Tomcat CATALINA_BASE/webapps directory. If you do not know where your CATALINA_BASE is, start the IDE and open the Services tab. Expand the Servers node. Right-click the Tomcat 6.0 node and select Properties from the context menu. The Catalina Base location is visible in the Connection tab.
   
3. Copy AXIS2_HOME/dist/axis2.war to GLASSFISH_HOME/domains/DOMAIN_NAME/autodeploy. To find GLASSFISH_HOME and the name of your domain, start the IDE and open the Services tab. Expand the Servers node. Right-click the GlassFish V2 node and select Properties from the context menu. The Domains folder location and the name of the domain are visible in the Connection tab. For example, from the following image, you know to copy axis2.war to C:\Program Files\glassfish-v2ur1\domains\domain1\autodeploy.
   

Setting Up Axis2 Options for Tomcat

Axis services run faster on Tomcat than on GlassFish, but the setup is slightly more complicated. You can easily deploy the same service to both Tomcat and GlassFish by first deploying to one server, then changing the Axis2 options and finally deploying to the other server.

If you want to deploy to GlassFish instead of Tomcat, go to Setting Up Axis2 Options for GlassFish.

To set up Axis2 options for Tomcat:

1. Start the IDE. From the top menu bar, choose Tools -> Options. The Options dialog opens.
2. Click the Axis2 icon. The Axis2 deployment options page opens.
   

3. Set the target location for Axis2 AAR files to your CATALINA_BASE (not TOMCAT_HOME) webapps/axis directory. You can find the location of CATALINA_BASE from the Tomcat Servers properties as described in Creating and Copying the Axis2 WAR File.

4. Make sure the Axis2 URL field contains the correct port number for your Tomcat server. To check the port number, start Tomcat (from the Services tab or from Tools -> Servers) and see what port Coyote HTTP/1.1 uses.
   
5. For convenience, select Use Tomcat Manager for Deployment. This function means that the IDE will launch Tomcat Manager in the background and run the reload command on axis2.war every time you make a change to axis2.war. If you do not select Use Tomcat Manager for Deployment, you will have to manually run Tomcat Manager or use other Tomcat tools to reload axis2.war every time you make a change to it.

   The default Tomcat Manager username is "tomcat" and the default password is also "tomcat". To double-check that Tomcat Manager is deployed and has the default manager role username and password, open CATALINA_BASE/conf/tomcat-users.xml. The manager role should be defined and it should have a username and password assigned to it, as in the following version of the file. (You can copy and paste this file if necessary.)

   <?xml version='1.0' encoding='utf-8'?>
   <tomcat-users>
     <role rolename="manager"/>
     <role rolename="admin"/>
     <user username="tomcat" password="tomcat" roles="manager,admin"/>
     <user username="ide" password="YENnS8UT" roles="manager,admin"/>
   </tomcat-users>
               

Setting Up Axis2 Options for GlassFish

You can deploy Axis2 web services to the GlassFish application server although Tomcat is significantly faster. You can easily deploy the same service to both Tomcat and GlassFish by first deploying to one server, then changing the Axis2 options and finally deploying to the other server.

If you want to deploy to Tomcat instead of GlassFish, go to Setting Up Axis2 Options for Tomcat.

To set up Axis2 options for Glassfish:

1. Start the IDE. From the top menu bar, choose Tools -> Options. The Options dialog opens.
2. Click the Axis2 icon. The Axis2 deployment options page opens.
   
3. Set the target location for Axis2 AAR files to your GLASSFISH_HOME/domains/DOMAIN_NAME/autodeploy directory. You can find the location of GLASSFISH_HOME and the name of your domain from the GlassFish Servers properties as described in Creating and Copying the Axis2 WAR File.

   Note: By placing axis2.war in the autodeploy directory, you enable GlassFish to automatically redeploy axis2.war every time you alter the file.

4. Make sure the Axis2 URL field contains the correct port number for your GlassFish server. To check the port number, start GlassFish (from the Services tab or from Tools -> Servers) and see what 80xx port HTTP 1.1 uses. In the following image, the correct port number is 8081:
   

Note: If you are using Windows Vista, have GlassFish installed to Program Files, and have User Access Control enabled, you will not be able to make changes to the axis2.war file from the IDE. Either install GlassFish to a different location or disable UAC.

Creating an Axis2 Web Service

With NetBeans IDE, you can create an Axis2 web service from a Java class. You can only do this from a Java application or Java library project. In this tutorial, you create a Java library project (because you do not need a main method), create an Axis2 web service in that project (creating the Java class at the same time) and deploy the Axis2 web service to a server.

To create and deploy an Axis2 web service:

1. Click the New Project icon or File -> New Project. The New Project wizard opens. From the Java category, select a Java class library project. Click Next.
2. Name the project AxisHello. Check that you are using the project folder name and location that you want. It is up to you whether to share the project. Click Finish, and the IDE creates the project.
3. Right-click the project node. The context menu opens. In the context menu, choose New -> Other. The New File wizard opens. From the Web Services category, choose Axis2 Service from Java and click Next.
   
4. The Service Type Selection page of the New File wizard is now open. You do not have any Java classes in the project, so select "Create an Empty Web Service." If you had already coded a Java class, you would have selected Create a Web Service from an Existing Java Class. If you wanted to edit the WSDL of the web service, for example to add or change namespaces, you would select Generate a WSDL from Java Source Code. Editing WSDL is outside the scope of this tutorial, so leave this unselected. The wizard should look like the following image:
   
5. Click Next. The Name and Location page opens. Name the Java class HelloAxisWorld. Name the package axishello. Leave Generate Sample Method selected. This generates a method in the Java class that returns "Hello, World."
6. Click Finish. The IDE generates a HelloAxisWorld.java class in the axishello source package and a HelloAxisWorld Axis2 web service that mirrors this Java class. You can see that both the Java class and the Axis2 web service have a hello:String operation, shown in the Navigator tab and as a node of the Axis2 web service, respectively.
   

Deploying and Testing an Axis2 Web Service

Once you have created an Axis2 web service, you need to deploy it to a server. Actually, deployment to a server involves two steps:

1. Copying the Axis2 web service to the axis2.war file used by the server. This step can be taken with the server offline.
2. Redeploying the updated axis2.war file to the server.

If you are deploying to Tomcat with the Use Tomcat Manager for Deployment option enabled (see Setting Up Axis2 Options for Tomcat), or you are deploying to GlassFish and axis2.war is in the GLASSFISH_DOMAIN/autodeploy folder (see Setting Up Axis2 Options for GlassFish), the updated axis2.war is automatically redeployed to the server. Otherwise, you have to redeploy axis2.war manually, using application server tools. In this tutorial we assume you have set up the Axis2 options so redeployment is automatic.

To deploy an Axis2 web service to the server:

1. Right-click the web service's node. The context menu opens. Select Deploy to Server. The IDE compiles an Axis2 AAR file and copies it to the axis2.war file used by the application server.
2. If you have enabled automatic deployment, the web service is deployed to the server. If the server is not running, start it and the web service is automatically deployed.
3. To test the service, expand the web service node to reveal the operations. Right-click the hello:String node and select Test Operation in Browser.
   
4. Your browser opens with a test value of your variables. The test value is appended to the URL.
   
5. Change the variable value in the URL and press Enter. The test result changes as well.
   

Changing the Web Service's Operations

To change the web service operations, edit the Java file in the project. The operations in the web service change simultaneously. Add a simple add method to HelloAxisWorld.java, as below:

public class HelloAxisWorld {

    /** Sample method
    */
    public String hello(String name) {
        return "Hello "+name;
    }
    public int add(int x, int y) {
            return x+y;
    }
        }

Save the Java file, and the operation appears as a subnode of the web service.

Redeploy the web service and test it as described in Deploying and Testing an Axis2 Web Service.

More Exercises

Here are a few more ideas for you to explore:

• Create a JAX-WS client for the Axis2 web service. You need the web service's WSDL URL. To get the WSDL URL, right-click the web service node and select Properties. The WSDL file URL is on the Properties page. See Getting Started with JAX-WS Web Services and Developing JAX-WS Web Service Clients for more information about JAX-WS web services.
• Try deploying the web service to the other application server. You have to change the Axis2 options--see Setting Up Axis2 Options for Tomcat or Setting Up Axis2 Options for GlassFish.
• Expose an existing Java class as an Axis2 web service. The Java class has to be in a Java Application or Java Class Library project.

See Also

For more information about using NetBeans IDE to create and consume web services, see the following resources:

• Developing JAX-WS Web Service Clients
• Getting Started with JAX-WS Web Services
• Consuming StrikeIron Web Services in Web Applications
• EJB & Web Service Applications Learning Trail

To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE Java EE development features, join  the nbj2ee@netbeans.org mailing list.