Author's Note: This article is based on work done by Milan Kuchtiak of Sun Microsystems, who also helped with this article.
What is Axis2?
Axis2 is a clean and extensible Open Source web services platform with a configurable, modular architecture. The same business logic implementation in Axis2 offers both a SOAP endpoint and a REST interface. Otherwise the architecture is similar to Metro JAX-WS: Axis2 utilizes an XML pull parser, supports hot deployment and asynchronous web services, and can be extended to provide security and reliable messaging similar to WSIT.
Axis2 Features in NetBeans IDE 6.1
We've added the ability to create and test Axis2 web services in NetBeans IDE. Specifically, you can now use NetBeans IDE to do the following:
- Create an Axis2 service from an empty Java class
- Create an Axis2 service from a preexisting Java class
- Create an Axis2 service from a WSDL document
- Test individual operations of an Axis2 service
You can consume Axis2 services with a standard JAX-WS client. When you create the client in the IDE, you can either specify the URL of the service's WSDL file or browse for the service in NetBeans IDE projects (illustrated).
Setting Up Axis2
Before you create Axis2 services in NetBeans IDE, you have to deploy the axis2.war file to the application server you are going to use, and you have to give the IDE access to this axis2.war file. This is a one-time-only task, unless you want to change the application server you are using.
On Tomcat and GlassFish v2, you deploy the WAR file simply by copying it to the correct location.
These locations are:
- Tomcat: CATALINA_BASE/webapps
- GlassFish: GLASSFISH_DOMAIN/autodeploy
NetBeans IDE needs to know the location of this WAR file, because it will create an Axis2 AAR file and copy it into the WAR when you want to deploy the Axis2 web service. We've added an Axis2 tab to Tools > Options where you enter the WAR file location and the URL of the application server.
The options you enter depend on your application server:
- Tomcat options: Enter the path to the CATALINA_BASE/webapps/axis2 folder instead of CATALINA_BASE/webapps/axis2.war. Tomcat unpacks the WAR file to the /axis2 folder, and you save processing time if you have the AAR file copied there. Also, enter your Tomcat Manager credentials, so that the IDE will run Tomcat Manager in the background to deploy the modified WAR file. Otherwise you have to deploy the WAR file manually after the IDE modifies it.
- GlassFish options: Enter the path to GLASSFISH_DOMAIN/autodeploy/axis2.war. Note that GlassFish automatically redeploys any altered WAR files in /autodeploy.
For either application server, make certain the port number is correct in the URL.
Creating an Axis2 Web Service in NetBeans IDE
You can create an Axis2 service from either a Java class or a WSDL document. In either case, the first step is to create either a Java Application or a Java Library project. The following examples use a Java Library project because no Main class is needed.
After you have created the Project, open the New File wizard. Go to the Web Services category and you can select either an Axis2 Service from Java or an Axis2 Service from WSDL.
If you choose Axis2 Service from Java, a dialog opens in which you can choose either to create an empty web service or a web service from an existing Java class. If you choose to create an empty web service, you are given the possibility to generate a sample method for that service. This sample method simply returns “Hello, World.” You also have the option of generating a WSDL file at build-time, which will be created in the xml-resources directory and bundled into the AAR file. This feature makes it convenient to customize the WSDL.
If you choose Axis2 Service from WSDL, a dialog opens in which you enter the path to a local WSDL file or the URL of a deployed WSDL. There are a number of options you can set as well. You can set the name of the packages that will contain the Java artifacts created when you generate the service. (By default, the package name is taken from the target namespace in the WSDL.) You can decide whether to create a skeleton class interface. Lastly, you select the WSDLToJava databinding technology you want to use. Your settings are propagated to a command-line command visible in the WSDLToJava field. Beneath this field, there are additional options for advanced users to add to the command line.
Configuring and Deploying the Axis2 Service
After you create an Axis2 service, it appears in your Java Application or Java Library project under the Axis2 Services node. To deploy the service, just right-click the service node and select Deploy to Server.
When you select “Deploy to Server,” the IDE bundles the service into an AAR file and copies the AAR file to the application server's axis2.war file (or for Tomcat, to the folder to which axis2.war was unpacked). If you are using GlassFish, or if you are using Tomcat and gave NetBeans IDE the Tomcat Manager authentication details, the modified WAR file is deployed automatically. Otherwise you have to use application server tools to deploy the WAR manually.
Note that you have to start the server manually. However the Deploy to Server function will still create the AAR and pack it to the WAR file if the server is offline. Instead of deploying the service, you can open it in the editor. This actually opens the Java file encoding the service.
You can also reconfigure the service by selecting Configure.
In the Configuration dialog, you can rename the service and even change its implementation class. In addition, you have the option of generating a WSDL file when you build the project, to bundle into the AAR. This is the same option you have when creating an Axis2 service from Java.
You can edit the WSDL file if the web service was created from WSDL, because the WSDL file is downloaded from the original location to the project's xml-resources directory. To open the WSDL file in the IDE's editor, select Edit WSDL from the web service node context menu. After you save the edited WSDL, select Refresh from the web service node context menu. This action regenerates the Java artifacts so they are synchronized with the modified WSDL file.
You can also edit the WSDL file for a web service generated from a Java class. After you modify and save the Java class, select Generate WSDL from the web service node context menu. This action regenerates a WSDL file synchronized with the Java class. Note that Generate WSDL File must be selected in the service's configuration.
Testing a Deployed Axis2 Web Service
After you've created and deployed an Axis2 web service, you can test it by individual operations. Expand the web service's node and you'll see a list of operations. Right-click an operation node and select Test Operation in Browser. A browser window opens with a test value of the operation's variables. The test value is appended to the URL.
To test a different value of the variable, change the variable in the URL and click Enter.