On this site, I have covered different topics on Axis2 that go from an introduction to Axis2 to very advanced tasks with Axis2, such as data services with Axis2. In this article, I am not going to discuss how to use Axis2 in simple applications or writing a service using Axis2; for that, I would recommend you to follow a few previous articles. The main goal of this article is to explain how to deploy or integrate Axis2 into an existing application.
There are a number of ways that one can use Axis2, and that can be easily divided in to two main categories. Which is Axis2?
- As a client to invoke other services
- To well deploy Web services
In both of those approaches, developers can use Axis2 as a standalone or integrate it into an existing application. I have already discussed how to use Axis2 as a standalone application, both as a client an as a server, in previous articles. You can find those by using the site’s search engine.
Axis2 as a Standalone Client
In this case, your requirement is to invoke a remote Web service using Axis2. To use Axis2 as a standalone client, the only thing you need to do is add Axis2 and dependent third-party libraries into class path, or set up your favorite IDE with Axis2 and dependent libraries. Simply add Axis2 and depended libraries into the IDE. After doing either of these two, you can use Axis2 to invoke a remote service.
Even if youe are going to integrate Axis2 into an existing application as a client, there would not be much difference. You just need to add Axis2 and depended libraries to the existing application and then call the Axis2 client API for the application.
Axis2 as a Standalone Server
In this case, the meaning of standalone is not as an integrated application. Axis2 comes with a built-in HTTP server as well as an application server-based deployment. In the case of a simple HTTP server, you just need to download the Axis2 binary distribution and run “axis2server.bat” in Windows and “axis2server.sh” in a Linux environment. Then, Axis2 will start a simple HTTP server so you can use that as your Web service server to deploy and access Web services.
In the case of an application server deployment, you need to download the Axis2 .war distribution and copy that into the application server. If you take Tomcat as an example, you need to copy the axis2.war file into the webapps directory. If Tomcat is running, it will deploy Axis2 automatically; otherwise, you need to start Tomcat. In either case, Tomcat will act as the server and, when there is a request, it will dispatch that request to Axis2.
The question is how to deploy services in any of the above cases. Deploying a service in either case is just a matter of copying the service archive file into the repository/services directory. If you take a simple HTTP server as an example, you need to put your services into “repository/services” in the case of Tomcat or, in any other application server, you need to copy the service into the “WEB-INF/services” directory.
Embedding Axis2 into an Existing Application
You’ve now learned how to install Axis2 as a standalone and to deploy the service into Axis2. Now, see how you are going to embed or integrate Axis2 into an existing application. Here, you are going to learn how to embed Axis2 into a J2EE application. As an example application, you are going to deploy on a J2EE application server or another application server, such as Tomcat.
The first part of embedding Axis2 is setting up the transport front; this means to configure the servlet. The Axis2 main servlet is “AxisServlet“. Remember that there is one thing you need to keep in mind when adding the servlet mapping. First, see how you add the servlet in the web.xml; for that, you need to add the following XML tag in the application’s web.xml.
<servlet> <servlet-name>AxisServlet</servlet-name> <display-name>Apache-Axis Servlet</display-name> <servlet-class> org.apache.axis2.transport.http.AxisServlet </servlet-class> <load-on-startup>1</load-on-startup> </servlet>
Then, add the servlet mapping:
<servlet-mapping> <servlet-name>AxisServlet</servlet-name> <url-pattern>/services/*</url-pattern> </servlet-mapping>
If you add the servlet mapping like this (url-pattern with “services”), you do not need to do any other modification. However, if you do not like having the mapping as “services”, you need to do one more step. Say you want to change the servlet mapping to “applications”; your mapping will look like that below:
<servlet-mapping> <servlet-name>AxisServlet</servlet-name> <url-pattern>/applications/*</url-pattern> </servlet-mapping>
Then, as mentioned before, you will need to change axis2.xml as well. There, you need to add the following parameter in to axis2.xml to have the correct servlet mapping.
I will soon discuss the location of axis2.xml, as well how to change its location.
Adding a Service and Modules
Once you do the configuration to web.xml, at the system startup time it will initialize AxisServlet, and then it will try to load the services from the default location. Here, the assumption is that the default repository is the WEB-INF directory. So, Axis2 will try to load the services from “WEB-INF/services” and modules of service extension from “WEB-INF/modules”. In addition to that, the default axis2.xml will load from “WEB-INF/conf/axis2.xml”.
The folder structure of the application should be something like what’s shown in Figure 1.
Figure 1: Application directory structure
All the required Web services for the application need to be in the services directory. In the same way, all Axis2 modules have to be put into the modules directory. The “conf” directory will contain the default axis2.xml. If you want do any modification, you will need to change that.
Where to Add the Resource and Lbraries
Once you follow the steps above, you have completed the process of all the configurations required to embed Axis2 to an existing application. Now,look at how you are going to share the libraries.
If your services and modules need to share any library, you need to put those files into “WEB-INF/lib” or the application’s “lib” directory. All the Axis2 depended .jar files should be in the application library directory or system class path.
Hot Update and Hot Deployment
The next question you may have is about the service hot deployment feature in Axis2. Interestingly, hot deployment and hot update features will continue to work unless you change axis2.xml. In other words, if your application does not have an unwanted problem due to service hot deployment and service hot update, change the following parameters in axis2.xml.
<parameter name="hotdeployment">true</parameter> <parameter name="hotupdate">false</parameter>
Working with a Remote Repository
So far, I discussed how to integrate Axis2 into an application where it uses a repository in the application itself. However, you can configure Axis2 to work with the remote repository; the Axis2 repository could be a URL in this case. You also can have axis2.xml in a remote location as well. For this feature, you need to update the web.xml by adding the init parameters.
<servlet> <servlet-name>AxisServlet</servlet-name> <display-name>Apache-Axis Servlet</display-name> <servlet-class> org.apache.axis2.transport.http.AxisServlet </servlet-class> <!--<init-param>--> <!--<param-name>axis2.xml.url</param-name>--> <!--<param-value> http://localhot/myrepo/axis2.xml </param-value>--> <!--<param-name>axis2.repository.url</param-name>--> <!--<param-value>http://localhot/myrepo</param-value>--> <!--</init-param>--> <load-on-startup>1</load-on-startup> </servlet>
If you want your system to work using a remote axis2.xml, add the following parameter with the value of your axis.xml location.
In the same way, if you want your system to work using a remote repository, add the following parameter with the value you want.
In this article, I discussed how to embed Axis2 into an existing application; there I covered all the necessary configuration and locations needed to add services, modules, and their resources. At the end of the article, I discussed how to embed Axis2 into your application so that it uses a remote repository.
About the Author
Deepal Jayasinghe is a computer science graduate student at Georgia Tech and an Apache Member. Before joining Georgia Tech, he worked at WSO2 for about three years. His interest is mainly in SOA and Distributed computing specially Web services. Deepal was a key member who designed, developed, and implemented the de-facto Java Web service framework, Axis2.
In addition to Axis2, he has contributed to a number of other open source projects, such as Apache Axiom, Apache Synapse, WSO2 Registry, WSO2, and WSAS.