Axis2 deployment – Custom deployers

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Deepal Jayasingha
  • 16 Jun, 2008

Introduction

It is obvious that Web services and related technologies are a hot topic in the industry today. These are applicable not only to the IT field but also for others such as financial, telecommunication, government and etc.. . As a result of the nature of the Web service technology , it seems that everyone is making an attempt to move into Web service arena. However, if you consider financial and government sectors, they already have systems up and running and their need is mostly to make these existing systems Web service enabled. When doing so, the biggest challenge is in the conversion process. In this regard, Enterprise Service Buses (ESBs) play a major role. In addition to that Axis2 has introduced an extremely flexible deployment mechanism with which you can easily convert your existing applications to Web services, and receive all the benefits that applies.

 

History of Axis2 Deployments

Having discussed the challenges for deploying Web services, let us now look at how Axis2 has evolved - mainly the deployment aspects of Axis2. In the first couple of release of Axis2, the only available option for deploying services was to drop a service archive file (.aar) into the repository. This service archive file consisted of Java class files and one of them was the service implementation class. This created some barriers on the flexibility aspects of deploying Axis2. Axis2 architecture is extremely sophisticated in that it allows you to plug in various custom code modules at different places (such as in MessageReceivers, Handlers, Transports, MessageBuilders, MessageFormatters), but the deployment did not help gain full benefits. To gain most benefits of Axis2, I introduce the idea of custom deployers, that I discuss in this article.

 

Applications of Custom Deployers

Introduction of custom deployers helped build a number of useful and interesting applications around Axis2. Among them are a number of WSO2 applications, that include:

  • WSO2 Mashup Server – deploying JavaScripts in Axis2 and making them available as Web services

  • WSO2 Data Services – exposing RDMS, CSV and MS-Excel files as Web services, simply using a configuration file

  • Axis1 deployer – deploying Axis1 services in Axis2 and still get full benefits of Axis2

  • JRuby binding – exposing JRuby scripts as Web services and thereby opening up the Axis2 world for script developers

 

In addition to the above, Axis2 itself contains four core deployers

  • Service deployer– deploying services as service archive files

  • Module deployer – deploying modules as module archive files

  • POJO deployer – deploying POJOs and annotated Jar files as Web services

  • JAXWS deployer – extensions for JAXWS

In addition to Axis2, Apache Synapse also uses custom deployment mechanisms for deploying mediators.

Hence it is obvious that the concept of custom deployers is a handy feature, one that increases the flexibility of Axis2 dramatically. Furthermore, it enables the dynamic nature of Axis2, since the concept of custom depoyer can be used to deploy not just services, but additionally any one of the followings:

  • Modules
  • Parameters
  • Transport senders
  • Transport receivers
  • Message builders
  • Message formatters

However, most applications are written to create or deploy Axis2 compatible Web services.

 

How Custom Deployers Work in Axis2

In Axis2 there is a concept called repository where you drop your services and modules into the repository. By default Axis2 repository consist of two sub-directories called “services” and “modules” , we deploy service archive files into the services directory and deploy module archive files into the modules directory. When you need to register a new deployer what we need to do is to tell Axis2 what the subdirectory inside the repository is and where we are going to drop that particular artifact type with the file extension of the artifact.

Then at the runtime Axis2 keeps searching the repository, continuously, scanning all the subdirectories in the repository. When it finds a subdirectory, it iterates all the files in the subdirectory. Next, it picks the deployer that matches the subdirectory and the file extension. It then gives the file reference to the deployer asking it to process the file. At this point, it is up to the deployer to process the file and make a service or anything out of that.

In this way, it is clear that we can register a deployer in a directory inside the repository and with the file extension it can process. This injects the flexibility inherent in Axis2 deployments.

 

Writing a Deployer

Before writing a custom deployer we need to make sure why we are writing a new deployer. One obvious reason is to make a file extension to a Web service. For example in the case of WSO2 Mashup Sever, the deployer is writte to make a “.js” file a Web service. Adding new deployment support or writing a deployer, is a simply a matter of implementing  the “org.apache.axis2.deployment.Deployer” interface.

The interface has five methods and are listed below:

  • init(ConfigurationContext configCtx)
    • This method is called at Axis2 startup. If the deployer needs to do any kind of initialization then those can be written in here.
  • deploy(DeploymentFileData deploymentFileData)
  • unDeploy(String fileName)
  • setExtension(String extension)
    • File extensions that the deployer is looking for
  • setDirectory(String directory)
    • Directory where deployment artifacts need to be deployed for this specific deployer

As you can see there are five methods in the interface we need to implement, however, only two of them are critical and therefore are made mandatory. They are the “deploy” method and the “unDeploy” method.

As we discussed in the previous section, when you register a deployer you register it with a file extension and the subdirectory in the repository. Therefore at runtime when Axis2 finds the matching file it calls your deployer. Then it is your responsibility to implement the “deploy” method to do the right thing. Say you are writing a deployer to process or make JavaScript file as web service , then when someone drops a .js file you have to write the code so that , you first process the .js file and make an AxisService from that , and finally you add that to Axis2 system using ConfigurationContext. Likewise depending on the work you are going to do you have to process the file and make Axis2 compatible artifact from that.

One other point to consider is that as a deployer you know the file extension you plan to process, as well as its structure. This also means that you are the only one who knows how to process that particular file type. For an example, if we take a service archive file, then the structure of that can be processed only by the ServiceDeployer of Axis2. Furthermore, note that in the case of a WSO2 Data Service, only the data service deployer will know how to process that particular configuration file.

The other important method is the “unDeploy” method, where, if someone deletes a file from the subdirectory that you are interested in (file extension that the deployer has registered with), then Axis2 calls the unDeploy method with the file name. Remember, at this point, you do not have the file around, as it is already deleted from the file system. Therefore, it is important that you remember the file name and also to remove whatever runtime objects that you created for that specific file.

Sample implementation class for a custom deployer looks like the following:

public class MyDeployer implements Deployer {
public void init(ConfigurationContext configCtx) {
// all the initialization code goes here. One thing you can do here is store a pointer to ConfigurationContext
}
public void deploy(DeploymentFileData deploymentFileData) throws DeploymentException {
File file = deploymentFileData.getFile();
// Then write the processing code need to process the file

}

public void setDirectory(String directory) {
// if you need to know the subdirectory that the deployer has registered
}

public void setExtension(String extension) {
//extension of the file that the deployer has registered

} public void unDeploy(String fileName) throws DeploymentException { // remove all the runtime data you have created for this file } }

Registering a Deployer in Axis2

Registering a deployer requires the following:

  • Need to have the deployer code in the class path
  • Need to add the following element into axis2.xml

<deployer extension=".foo" directory="Foo" class="MyDeployer"/>

So here, we have registered our deployer in the “Foo” directory to process “.foo” files. One thing to note here, is that we can register one deployer to process multiple file extensions, say for example, our deployer can process both “.foo” and “xyz” file extensions then we can register our deployer twice in the axis2.xml. The code is given below:

 

<deployer extension=".foo" directory="Foo" class="MyDeployer"/>

<deployer extension=".xyz" directory="Foo" class="MyDeployer"/>

 

What to Know When Registering Deployer for Service

There is one additinal important thing you need to keep in mind when you write a deployer to deploy services - and that is the WSDL generation for the deployer. You might be aware that at the runtime Axis2 generates a WSDL for any given service, but really, there is no magic behind this. At the time of deployment, it process whatever the file and create a schema for that service and adds that to the service. Then later at runtime, using this schema information, Axis2 generates the WSDL file. So if you are writing a deployer to process services, it is better if you could think how you are going to generate the schema for the service. Unless you generate the schema, Axis2 would not know how to generate the WSDL, which results in no user being able to access the service. This is because  without a WSDL there is no way for the users to find out what your service interface looks like. Again, when writing a service deployer make sure to generate the XML schema for the service.

 

Conclusion

In this article we discussed a very useful feature of Axis2. We learnt the flexibility and power of the concept of custom deployers. We even look at a few available deployers and analysed the power behind. Finally, we discussed how to write a custom deployer and how to register it with the system.

 

Author

Deepal Jayasinghe, Senior Software Engineer, WSO2. deepal AT wso2 DOT com

About Author

  • Deepal Jayasingha
  • WSO2 Inc.