C-App Deployment Process

Introduction

C-App namely Carbon Application is an archive format collection of different artifacts bundled to a single deployable component. C-App files have CAR extensions and can be deployed to different runtimes. Each runtime will only deploy the artifacts which match with the role that the runtime is playing (e.g., ESB runtime will not deploy a data service in the CAR file, unless the default configuration is altered).

C-App structure

The structure of a typical C-App, contains individual directories of the artifacts and a file named artifacts.xml which contains the metadata about the artifact content listed inside the C-App.  The following code illustrates a sample artifacts.xml file which provides in-depth details about the sample C-App and its content. This file contains the name of the C-App (in this case sampleCApp ), its version and the type of the artifact. The relevant deployer for the artifact is identified using the artifact type; for C-Apps this is " carbon/application" . In addition, the artifacts.xml file also contains details about its content artifacts such as its name, version and server role of the artifact. The server role will be considered to recognize whether the given artifact is relevant to that running server. If the serverRole is matched with the WSO2 product that the C-App was deployed for, then those artifacts will be deployed using the CappDeployer ; however, if the serverRole is not matched the artifact will be ignored.

Sample artifacts.xml file

The relevant deployable artifact (e.g., if its an Axis2 service the file extension used is .aar and if it is a webapp the file extension used is .war) and other relevant files needed for that specific artifact are found inside the artifact directory. This also contains a XML file named artifact.xml that contain the meta-data information about that artifact. This contains the artifact name, version, type of the artifact, server role and the name of the artifact file. For example if its an Axis2 service the type will be “service/axis2” and for webapps the type will either be “web/application” or “webapp/jaxws” based on the type of the webapp.

Sample artifact.xml files

Evolution in C-App deployment model

Prior to WSO2 Carbon 4.2.0 Turing platform release, the process of C-App deployment was different from the current approach. In the previous approach during C-App deployment, the CappDeployer initially extracts all the CAR files to the <PRODUCT_HOME>/temp directory. Thereafter, based on the artifact type, the CappDeployer will copy the C-Apps to relevant hot deployment folders in the <PRODUCT_HOME>/repository/deployment/server directory. Due to this approach the C-App deployment prior to the Carbon 4.2.0 era was not synchronous. One major drawback of this approach was during runtime, if an artifact failed during its deployment, there was no direct way to check as to which C-App deployed these faulty artifacts. In many production systems this requirement was crucial, since they tend to deploy dozens of C-Apps at once.

In current approach during C-App deployment, the CappDeployer initially extracts all the CAR files to the <PRODUCT_HOME>/repository/carbonapps/work directory. Thereafter, the CappDeployer copies the the artifacts based on the artifact type, to the <PRODUCT_HOME>/repository/deployment/server/carbonapps hot deployment directory. The DeployerSchedulerTask will run periodically to identify all changes in the hot deployment directories. If there are any changes (such as new C-Apps, edited C-Apps and deleted C-Apps) in the carbonapps hot deployment directory, the DeployerSchedulerTask will deploy the artifacts immediately. Thereby, this process is synchronous and atomic in the new C-App deployment strategy and if the CApp gets successfully deployed, we can guarantee that all the artifacts have been successfully deployed.  

C-App deployment methods

  Any of the following methods can be used to deploy C-Apps:

• Upload the C-App using the Management Console.

• Directly add the artifact file to the < CARBON_HOME>/repository/deployment/server/carbonapps hot deployment directory.

C-App deployment process

The following are the steps that take place during the deployment of a C-App:

1. Artifacts inside C-App get extracted to the temp location inside the <PRODUCT_HOME>/repository/carbonapps/work directory.

2. The CappDeployer then reads the artifacts.xml file to get the list of artifacts contained in the C-App. In this process the C-App deployer builds a map containing all the required dependencies to deploy the artifacts.

3. The C-App deployer iteratively deploys the artifacts and required dependencies. This is done by calling the CAppDeployer, which in-turn programmatically calls the relevant deployer of the artifacts based on the server role and the artifactType and thereafter it deploys the artifacts.

4. When the C-App deployment process is completed all its artifacts relevant to the server role are up and running. However, if any issues are encountered during the deployment it rollbacks to the deployed artifact.  

Sample

The following sample code is based on the new implementation and is for a webapp deployment. The deployment of the other artifacts will be done in a similar manner except for Synapse artifacts.

package org.wso2.carbon.application.deployer.webapp
 
/**
*  Check the artifact type and if it is a WAR, copy it to the WAR deployment hot folder
*/
 
List<Artifact.Dependency> artifacts = carbonApp.getAppConfig().getApplicationArtifact().getDependencies();
 
// loop through all artifacts and deploy them iteratively
	for (Artifact.Dependency dep : artifacts) {
	Deployer deployer;
	Artifact artifact = dep.getArtifact();
	if (artifact == null) {
		continue;
	}
 
/**
* for each service type, select the correct deployer
* for this we need to provide the relevent deployment directory on carbon server and the extension of the artifact
* these details are read from the configurations for the corresponding artifact type
* since webapps may have two artifact types we should get the correct deployer
*/
	if (WAR_TYPE.equals(artifact.getType())) {
		deployer = AppDeployerUtils.getArtifactDeployer(axisConfig, WAR_DIR, "war");
	} else if (JAX_WAR_TYPE.equals(artifact.getType())) {
		deployer = AppDeployerUtils.getArtifactDeployer(axisConfig, JAX_WAR_DIR, "war");
	} else {
		continue;
	}
 
	// once the deployer gets called we execute the webapp deployer to deploy
	if (deployer != null) {
		String fileName = artifact.getFiles().get(0).getName();
		String artifactPath = artifact.getExtractedPath() + File.separator + fileName;  
	// extracted path is our artifact extracted temp location. These details are available is the artifact
	try {
		// deploy the artifact 
		deployer.deploy(new DeploymentFileData(new File(artifactPath), deployer)); 
		// set the deployment state 
		artifact.setDeploymentStatus(AppDeployerConstants.DEPLOYMENT_STATUS_DEPLOYED);   
	} catch (DeploymentException e) {
		artifact.setDeploymentStatus(AppDeployerConstants.DEPLOYMENT_STATUS_FAILED);
	throw e;
	}
}

package org.wso2.carbon.application.deployer
 
/**
* Finds the correct deployer for the given directory and extension
*
* @param axisConfig - AxisConfiguration instance
* @param directory - Directory to retrieve the deployer
* @param extension - Extension of the deployable artifact
* @return Deployer instance
*
*/
public static Deployer getArtifactDeployer(AxisConfiguration axisConfig, String directory, String extension) {
	// access the deployment engine through axis config
	DeploymentEngine deploymentEngine = (DeploymentEngine) axisConfig.getConfigurator();
	// return the corresponding deployer to the required artifact type
	return deploymentEngine.getDeployer(directory, extension); 
}

C-App modifying process

As a best practice we do not recommend users to modify deployed CApps or its artifacts through the Carbon management console . Instead, the Developer Studio can be used to modify a CApp. Thereafter, the CApp needs to be redeployed.