Understanding Axis2 Deployment Architecture

Axis 2.0 is the next generation of the Apache Web service stack. Axis2 is built on a new architecture that was designed to be a much more flexible, efficient, and configurable version of Axis. Even though the architecture is new, some of the well-established concepts from Axis 1.x, such as handlers, are preserved in Axis 2.0. Axis 2.0 comes with lots of new features, enhancements, and new industry specification implementations. Among the new features and enhancements are AXIOM, Asynchronous Web service, MTOM, MEP support, and archive-based deployment architecture, which is considerably esteemed.

Axis2 Architecture

The Axis2 architecture has developed keeping a few principles in mind to preserve the uniformity of the architecture. The first one is the architecture that separates the logic and the states; the code that processes the logic is usually stateless. This allows the code to be executed freely by the parallel threads. The second one is that all the information is kept in one Information model; this allows the system to be stored and resumed. And finally, the architecture is modular; the architecture broke Axis2 into the following seven modules (as shown in Figure 1).

1. Information Model
2. XML processing Model
3. SOAP Processing Model
4. Deployment
5. WSDL and Code Generation
6. Client API
7. Transports

Figure 1: Axis2 architecture components

Deployment Architecture

What is the difference between Axis 1.x and Axis2 deployment?

Previous versions of Axis failed to address the user friendliness factor involved in the deployment of a Web service, and it is due to the fact that Axis 1.x was created mainly to prove the Web service concepts. Therefore, in Axis 1.x, the user has to invoke the admin client manually and update the server classpath, and then restart the server to apply the changes. This burdensome deployment model was a definite barrier for beginners. Axis2 is engineered to overcome this drawback and provide a flexible, user-friendly, and easily configurable deployment model.

Axis2 deployment introduced the notion of a J2EE-like deployment mechanism, where the developer can bundle all his/her class files, library files, resources files, and configuration files together as an archive file, and drop it into a specified location in the file system.

The concept of hot deployment and hot update is not new terminology to the technical paradigm, particularly to a Web service platform, but for Apache Axis, it is a new feature. Therefore, Axis2 was developed by keeping room for "hot" deployment features.

Hot deployment: The capability of deploying service while system is up and running. In a real-time system or business environment, availability of the system is very important. If the system is down even for a moment, the loss might be substantial and it may affect the lifetime of the business. However, if it is necessary to add a new service to the system and if this can be done without shutting down the servers, that would be a great achievement. So, Axis2 addresses that and provides a Web service hot deployment ability, where you do not need shut down the system to deploy a new Web service. You merely need to drop the required Web service archive into the services directory in the repository. Then, the deployment model will automatically deploy the service and make it available to you.

Hot update: The capability of making changes to an existing Web service without shutting down the system. This is an important feature and is required in a testing environment. However, it is not advisable to use hot update in a real-time system because a hot update could result in the system leading to an unknown state. Additionally, there is the possibility of losing the existing service data of that service. To prevent this, Axis2 came with the hot update parameter set to FALSE by default.

Axis2 addresses hot deployment and hot update by using a scheduler and a file system listener, where the scheduler is scheduled in the way that will inform the listener to search the repository for updating and, depending on the configuration given by axis2.xml updates (adding new service or changing an existing service), will be made available to the system. The underlying architecture that provides "hot" deployment characteristics is as shown in Figure 2.

Figure 2: Deployment Architecture (Repository based deployment)

• Scheduler: This is scheduled in the way that periodically informs the Listener to search the repository.
• Listener: This searches the repository for updating.
• Descriptor Parser: A component to process the service and module descriptors (totally built on AXIOM).
• Deployment Engine: The centered component of the deployment, which does all the logic processing.
• Axis2 Core: In the Axis2 core system, deployment is totally independent from the core, and the core does not depend on the deployment.
• Repository: A directory in the file system where deployment has been configured to search. Inside the repository there could be two sub directories called "services" and "modules," where services and modules are going to be dropped in respectively. The pictorial representation of the repository looks like Figure3.

Figure 3: Axis2 repository

Axis2 Global Configuration

The flexibility and extensibility of Axis2 is focused mainly on its deployment descriptors. Because all these descriptors are XML-based, the extensibility nature of XML has reflected to Axis2 as well. There are three main deployment descriptors in Axis2, as follows:

• Global descriptor (axis2.xml)
• Service descriptor (services.xml)
• Module descriptor (module.xml)

All the global configurations that are needed to run Axis2 are given by axis2.xml (global parameters, transport information, and so forth). The most interesting thing about this is that someone can configure the deployment behavior by axis2.xml, meaning that one can configure "hotdeployment" and "hotupdate" parameters the way he wants, as shown below.

<parameter name="hotdeployment">true</parameter>
<parameter name="hotupdate">false</parameter>

Likewise, all the global level parameters, modules, transports information, and so on can be included in the configuration file. When the axis2 starts, it search the repository for axis2.xml. If it is found, the system will be configured by using that; otherwise, the default one (which is distributed with the axis2 distribution) will be copied into the repository and the system starts using that. Later, if the user wants, he can change axis2.xml file. One thing to remember here is that, to affect any changes, you need to restart the system. (Explaining everything about axis2.xml is beyond the scope of this article. If you need to know more, click here.)

Axis2 Service

If you are an Axis 1.x user, you are familiar with deploying a service with Axis 1.x. The easiest way to do that is (say you are using Axis 1.x java) through the 'instant' Web service in Axis1.

• Write a Java class that has some methods that you want to publish (say Myservice.java).
• Drop the Java class into the Axis webapp directory.
• Rename the Java class to Myservice.jws (because the name of java class is Myservice.java).
• When you restart Axis, you have the Web service

So, with Axis 1.x deploying a service is nothing?. The answer is yes if you are going to publish a very simple service, but say:

• You have more than one class for the service
• You need to provide service-specific parameters
• You want to have specific library files for this service

This is not impossible with Axis 1.x but average users (particularly beginners) will have to do some hard work to get the job done. In this particular case, the user has to write a special deployment descriptor called the WSDD and feed it to the Axis AdminClient. The admin client does the modifications in the server (again through a Web service), but for the service to work, the server class path needs to be modified, which usually requires a server restart!

Therefore, Axis2 was developed to address the deployment drawbacks in Axis 1.x, and to provide a better deployment mechanism. As a result of that, in Axis2 deploying a service is nothing if you can mange to crate a correct service archive (creating a service archive is not such a difficult task because Axis2 comes with a tool to create archive files). Therefore, in Axis2, deploying a service is just a matter of dropping the archive file into the services sub directory in the Axis2 repository. If you are going to deploy Axis2 in an application server like tomcat, you can use a Web interface to deploy the service.

Here is the Axis2 way to write a Web service by hand (without using tools):

• If you already have the WSDL file for the service that you are going to publish, create a service skeleton using WSDL2Java.
• Then, complete (fill) the service skeleton the way you want.
• If you do not have the service skeleton class, don't worry. Write the service implementation class; it is considered the service skeleton class in this case.

Next, write services.xml, the configuration file of the service as described below. A template of a services.xml file is shown below:

<service >
   <description>
      The description of the service goes here; this can be any
      XML element
   </description>
   <parameter name="ServiceClass" locked="false">
      org.apache.axis2.MyServiceImpl
   </parameter>
   <parameter name="ServicePara" locked="false">
      ServicePara
   </parameter>
   <operation name="myOperation">
      <parameter name="OperationPara" locked="false">
         OperationParaValue
      </parameter>
   </operation>
</service>

Steps to Write services.xml

1. There is a specific parameter called ServiceClass. Set the name of the service implementation class as that. It could be a service skeleton class or aservice impl class.
2. For each method in the skeleton or service impl class, there should be an operation element. As an example, if you have a method called "myOperation" in the service implementation class, you should write an operation element as shown above.
3. There could be a service-specific parameter anywhere in services.xml. At run time, those parameters are available in ServiceDescription or OperationDescription.

Note: The above service configuration is very simple one, and the actual configuration file can be more complex than that.

Note: Axis2 is on the way to introducing the concept of a service group into the Web service platform where the user can deploy more than one services in an archive file and share data across those services. This article only describes how a single service should look and the available ways of deployment.

The next step is to bundle the above files together into a service archive file, which can be done by applying the following procedures. (If you are using your IDE as either IntelJ IDEA or eclipse, you can download the plug-in for those IDEs from the Axis2 site; those will make your job much easier.)

1. Create an empty folder.
2. Create a directory called "META-INF" inside that.
3. Put services.xml into the META-INF directory.
4. If you have the WSDL file corresponding to the Web service, rename it to service.wsdl and put that into the same directory. (It is not necessary to have a wsdl file in Axis2.)
5. If you want any third-party lib files or you own lib files, crate a directory called "lib" in the same level as META-INF, and drop all your lib files into that.
6. Copy the compiled service implementation classes into the directory.
7. Create a zip file from all those files and rename it to *.jar or *.aar.

The directory should look like Figure 4.

Figure 4: Axis2 service sub directory hierarchy

Note: If you are using Axis2 version above 0.91, you do not need to create an archive file. You can just drop your service folder into the service sub directory in the Axis2 repository.

Note: As mentioned earlier, in Axis2 it is not required to have a wsdl file to publish a service, but if you have a wsdl file, it provides more functionality or rather configurations. If the archive file contains a wsdl file, a WSDL Object Model (WOM) will be created using that particular wsdl by deployment and then fill rest of the data by using services.xml. If you do not have a wsdl with you, an empty WOM model will be crated and rest will be filled using services.xml.

Axis2 Service Extension (Modules)

The concept of service extension is a totally new concept in the Apache Axis paradigm, but the developers have achieved the functionally of service extension or the module by doing a very hard job in Axis 1.x. A module is something that can plug into a running system; then, it will do some extra job. In one respect, a module can be considered a set of handlers bundled together to provide some specific case—most of the time, it implements a WS spec.

The idea is very simple. Say you need to support WS-Addressing; what you have to do is download the module and drop that into the modules directory in the Axis2 repository. If you want to enable that globally, put the following entry into axis2.xml; otherwise, if you want to enable that into specific service, put the same entry into the services.xml of that particular service.

<module ref="ModuleName"/>

In this case ModuleName = addressing.

Note: In Axis2, you get WS-Addressing by default, so you do not need to do anything. In fact, addressing is globally enabled, so each and every service will have addressing functionally by default.

The same scenario is applicable for WS-Security, WS-RM, and so forth.

Creating a module archive file is almost the same as that of a service archive file; the only difference is that the module contains module.xml as its configuration file. In addition to that, the module may or may not contain a module implementation class, but as a module it should at least contain a single handler. (It won't be checked by deployment, but if a module does not have a single handler, it is useless.) A template of module.xml is shown below:

<module name="ModuleName" class="org.apache.module.Module1Impl">
   <inflow>
      <handler name="h1" class="org.apache.axis2.registry.Handler3">
         <order phase="userphase1"/>
      </handler>
      <handler name="h2" class="org.apache.axis2.registry.Handler3">
         <order phase="userphase1"/>
      </handler>
   </inflow>
   <outflow>
      Out Flow handlers go here
   </outflow>
   <Outfaultflow>
      Out fault flow handler go here
   </Outfaultflow>
   <INfaultflow>
      In fault flow handlers go here
   </INfaultflow>
<parameter name="ModulePara" locked="true">
   ModuleParaValue
</parameter>
</module>

Note: If you have a module implementation class, set the value of the class attribute as a fully qualified name of the implementation class. If module.xml contains a module implementation class, its init method will be called by deployment at deployment time.

As you can see, there are some elements called ** flow. In module.xml, those are basically to configure Axis2 messaging paths. To write a correct module, you need to have a better understanding about all the possible and valid elements in module configuration, but explaining them here is beyond the scope of this article. Resources are available on the Axis2 site; you should read them before writing any modules.

Although a service can deploy without creating a service archive, it is not applicable here. To be a valid module in Axis2, (1) it should be an archive file (either *.mar or *.jar), (2) it should take the directory hierarchy as shown in Figure 5.

Figure 5: Axis2 module sub directories hierarchy

Note: It is not a requirement that you should drop the module archive file into the module's sub directory, but if you have the module archive in your class path and you ask to engage that particular module by putting <module ref="foo"/> in anywhere (may be axis2.xml or services.xml), the deployment engine will read the module from the class path and copy that into the modules directory.

Available Ways to Deploy a Service in Axis2

In Axis2 there are two ways to deploy a service. One is to drop the service archive file into the services sub directory in the Axis2 repository; the other is to deploy the service programmatically. The basis of repository-based deployment has mentioned above, and is the most common way of deploying a service.

Deploying a service programmatically is not really a user requirement, but it is kind of module author requirement, where some module requires you to deploy a Web service to provide the full functionality of the module. To create a service programmatically, you need to have servicesxml, a class loader with your class files (or CCL) and ServiceDescription, the static representation of a service in Axis2. The following code fragment will help you to get a basic understanding about programmatically service deployment.

DeploymentEngine de = new DeploymentEngine();
ServiceDescription service = new ServiceDescription();
ClassLoader cls = Thread.currentThread().getContextClassLoader();
InputStream in = new FileInputStream("location of servie.xml");
de.buildService(service,in,cls);

Conclusion

Axis2 is not there to prove Web services concepts, but to provide a better SOAP processing model, with considerable performance increase in both speed and memory with respect to Axis 1.x and other existing web service engines. In addition to that, it provides a user convenient deployment mechanism. Now, it's time to play with Axis2.