Axis2 Deployers

Axis2 deployer is an extension point in Apache Axis2 where a user can write a new deployer for deploying artifacts. What a deployer does is that it will look for additions/deletions and modifications of a defined file extension(s) in a specified directory and will execute the logic in the deployer implementation. In the Carbon platform, this extension is being used to deploy different types of artifacts such as WAR files, C-Apps and datasources.

The <PRODUCT_HOME>/repository/deployment/server directory is the default location for artifact deployment in all Carbon products. There are different directories (web apps, axis2services etc.) for different artifact types. If you write a deployer that deploys artifacts to the same directory, you get the advantage of deployment synchronization and tenant awareness by default.

Writing an Axis2 Deployer involves the following:

Implementing the org.apache.axis2.deployment.Deployer interface

This contains the logic for the initialization, deployment and removal of artifacts. Note that when an artifact is modified, both the undeploy() and deploy() methods will be called.

package org.wso2.carbon.extensions.deployer;

import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.deployment.Deployer;
import org.apache.axis2.deployment.DeploymentException;
import org.apache.axis2.deployment.repository.util.DeploymentFileData;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import java.io.File;

public class SampleDeployer implements Deployer {
  private static Log log = LogFactory.getLog(SampleDeployer.class);
  public void init(ConfigurationContext configurationContext) {
      // initialization code goes here
      log.info("initializing the sample deployer");
  }

  public void deploy(DeploymentFileData deploymentFileData) throws DeploymentException {
      // file processing code when deploying goes here
      File file = deploymentFileData.getFile();
      log.info("File being deployed: " + file.getName());
  }

  public void setDirectory(String directory) {
      // this can be used to get the directory against which the deployer is registers
  }

  public void setExtension(String fileExtension) {
      // this can be used to get the file extension against which the deployed is registered
  }

  public void undeploy(String filePath) throws DeploymentException {
      // logic at undeployment goes here.
      // NOTE: since the file is already deleted, we don't have a reference to a file at this point
      log.info("File being undeployed: " + filePath);
  }

  public void cleanup() throws DeploymentException {
      // this method gets called when the deployer is unloaded
      log.info("Cleaning up sample deployment");
  }
}

Writing an OSGi component

Given below is a sample OSGi component.

package org.wso2.carbon.extensions.deployer.internal;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.osgi.service.component.ComponentContext;
/**
* @scr.component name="org.wso2.carbon.extensions.deployer.SampleDeployer"
* immediate="true"
*/
public class SampleDeployerSC {
  private static Log log = LogFactory.getLog(SampleDeployerSC.class);
  protected void activate(ComponentContext componentContext) {
      log.info(this.getClass().getName() + " activated");
  }
  protected void deactivate(ComponentContext componentContext) {
      log.info(this.getClass().getName() + " deactivated");
  }
}

Configuring the deployer

The following are the steps for configuring the new deployer in your product:

The component.xml file in the <PRODUCT_HOME>/resources/META-INF directory should be updated with the following details:
- <directory>: The sub directory (in the <PRODUCT_HOME>/repository/deployment/server directory) that is associated with the deployer.
- <extension>: The file extension associated with the deployer.
- <class>: The class implementation, which is org.apache.axis2.deployment.Deployer.
Note that users can register the same deployer implementation for different file extensions and/or different directories. Given below is a sample component.xml file.
```
<component xmlns="http://products.wso2.org/carbon">
  <deployers>
      <deployer>
          <directory>customArtifacts</directory>
          <extension>xml</extension>
          <class>
              org.wso2.carbon.extensions.deployer.SampleDeployer
          </class>
      </deployer>
  </deployers>
</component> 
```

Add <Axis2Deployer>CustomDeployer</Axis2Deployer> under configuration/instructions in the pom.xml of the maven-bundle-plugin. Shown below is the a sample pom.xml that is updated for the above deployer.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.wso2.carbon.extensions</groupId>
  <artifactId>sample-deployer</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>bundle</packaging>
  <repositories>
      <repository>
          <id>wso2-nexus</id>
          <name>WSO2 internal Repository</name>
          <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
          <releases>
              <enabled>true</enabled>
              <updatePolicy>daily</updatePolicy>
              <checksumPolicy>ignore</checksumPolicy>
          </releases>
      </repository>
  </repositories>
  <dependencies>
      <dependency>
          <groupId>org.apache.axis2.wso2</groupId>
          <artifactId>axis2</artifactId>
          <version>1.6.1.wso2v15</version>
      </dependency>
      <dependency>
          <groupId>org.eclipse.osgi</groupId>
          <artifactId>org.eclipse.osgi.services</artifactId>
          <version>3.3.100.v20130513-1956</version>
      </dependency>
      <dependency>
          <groupId>commons-logging</groupId>
          <artifactId>commons-logging</artifactId>
          <version>1.1.3</version>
      </dependency>
  </dependencies>
  <build>
      <plugins>
          <plugin>
              <groupId>org.apache.felix</groupId>
              <artifactId>maven-scr-plugin</artifactId>
              <version>1.7.2</version>
              <executions>
                  <execution>
                      <id>generate-scr-scrdescriptor</id>
                      <goals>
                          <goal>scr</goal>
                      </goals>
                  </execution>
              </executions>
          </plugin>
          <plugin>
              <groupId>org.apache.felix</groupId>
              <artifactId>maven-bundle-plugin</artifactId>
              <version>2.3.5</version>
              <extensions>true</extensions>
              <configuration>
                  <instructions>
                      <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                      <Import-Package>
                          org.apache.axis2.deployment.*,
                          org.osgi.service.component.*,
                          org.apache.commons.logging.*,
                          org.apache.axis2.context.*
                      </Import-Package>
                      <Axis2Deployer>CustomDeployer</Axis2Deployer>
                  </instructions>
              </configuration>
          </plugin>
      </plugins>
  </build>
</project>

Building the bundle

You can now build the bundle and place it in <PRODUCT_HOME>/repository/components/dropins directory.