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
To follow this tutorial, you need the following software and resources.
Both Tomcat and GlassFish can be installed with the Java Web distribution of NetBeans IDE. Alternatively, you can visit the GlassFish downloads page or the Apache Tomcat downloads page.
In this section you learn how to download an Axis2 WAR file, embed it in either an Apache Tomcat or GlassFish server, and configure NetBeans IDE to upload AAR files to the server.
Downloading the Apache Axis2 WAR file
Apache Axis2 can be downloaded here. Download the WAR (Web Archive) distribution, so you do not have to build the WAR file yourself. The download is in the form of an archive file. Later you unpack the archive to your server.
This tutorial requires the Axis2 Support plugin for the NetBeans IDE. 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 installed, check whether an update is available in the Updates tab. If the Axis2 support is not installed, install it from the Available Plugins tab, as shown below.
Setting Up Axis2 Options for Tomcat
Axis services run faster on Tomcat than on GlassFish v1 or v2, 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:
- Unpack the downloaded archive file containing 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.x node and select Properties from the context menu. The Catalina Base location is visible in the Connection tab.
If there is no CATALINA_BASE, you have not run your Tomcat before. Start and stop Tomcat and CATALINA_BASE will be generated.
- Start or restart the Tomcat server. Tomcat unpacks the axis2.war file into an axis2 folder in CATALINA_BASE/webapps.
- From the top menu bar in the IDE, choose Tools > Options. The Options dialog opens.
- Click the Axis2 icon. The Axis2 deployment options page opens.
-
Set the target location for Axis2 AAR files to your CATALINA_BASE (not TOMCAT_HOME)/ webapps/axis2 directory.
- 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.
- 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 and password varies. You can find this information in the Properties page for the Tomcat server 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.)
Setting Up Axis2 Options for GlassFish
You can deploy Axis2 web services to the GlassFish application server. 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:
- Unpack the downloaded archive file containing 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 or V3 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 G:\glassfish-v2ur2\domains\domain1\autodeploy.
- Start the IDE. From the top menu bar, choose Tools -> Options. The Options dialog opens.
- Click the Axis2 icon. The Axis2 deployment options page opens.
- Set the target location for Axis2 AAR files to the axis2.war file you unpacked into the GlassFish autodeploy directory.
By placing axis2.war into autodeploy, you enable GlassFish to automatically redeploy axis2.war every time you alter the file. On GlassFish v3 Prelude, however, you cannot redeploy the WAR file while the server is running.
- 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. The default port number is 8080. In the following image, the correct port number is 8081 (because another server already uses 8080).
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.
In this section, you use NetBeans IDE to create, deploy, test, and modify an Axis2 web service.
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.
You can only create an Axis2 web service from a Java or Java Library project. This is because the axis.aar file (the deployable archive into which web services and Axis configuration files are packed) is neither a WAR nor an EAR and cannot be deployed normally as a web (EAR) application.
To create an Axis2 web service:
- 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.
- 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.
- 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.
- 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.
- 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."
- 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:
- Copying the Axis2 web service to the axis2.war file used by the server. This step can be taken with the server offline.
- 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:
- 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.
- 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.
- 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.
- Your browser opens with a test value of your variables. The test value is appended to the URL.
- 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.
Here are some difficulties you may experience and their solutions:
- The service is not automatically deployed on Tomcat. If autodeploy does not appear to work on Tomcat, open TOMCAT_HOME/conf/server.xml and check that the autoDeploy attribute is set to "true" in the Host element:
- When you change the operations in the service and try to redeploy the service on Tomcat, it fails with the following message in the Tomcat server output window: INFO: validateJarFile(C:\...\apache-tomcat-6.0.16_base\webapps\axis2\WEB-INF\lib\servlet-api-2.3.jar) - jar not loaded. See Servlet Spec 2.3, section 9.7.2. Offending class: javax/servlet/Servlet.class
In this case, stop the server, delete the CATALINA_BASE/webapps/axis2 folder, and restart the server. This regenerates a new axis2 folder.
- Using GlassFish on Windows Vista, you cannot unpack, modify and overwrite the WAR file. You need to either reinstall GlassFish in a different location than C:/Program Files, or disable User Access Control.
- Using GlassFish v3 b20 Prelude, with the server running, you cannot unpack, modify and overwrite the WAR file. You cannot overwrite a JAR file used by a running GlassFish v3 b20 Prelude server. Stop the server and deploy the service, then restart the server.
More Exercises
Here are a few more ideas for you to explore:
See Also
For more information about using NetBeans IDE to create and consume web services, see the following resources:
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.
