Author: jawi
Date: Wed Apr 18 08:07:09 2012
New Revision: 1327415
URL: http://svn.apache.org/viewvc?rev=1327415&view=rev
Log:
CMS commit to ace by jawi
Modified:
ace/site/trunk/content/dev-doc/design/ace-deployment-strategies.mdtext
Modified: ace/site/trunk/content/dev-doc/design/ace-deployment-strategies.mdtext
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/design/ace-deployment-strategies.mdtext?rev=1327415&r1=1327414&r2=1327415&view=diff
==============================================================================
--- ace/site/trunk/content/dev-doc/design/ace-deployment-strategies.mdtext
(original)
+++ ace/site/trunk/content/dev-doc/design/ace-deployment-strategies.mdtext Wed
Apr 18 08:07:09 2012
@@ -1,17 +1,17 @@
-# Ace deployment strategies
+# Deployment strategies
_implementing custom update policies_
## Introduction
-This article describes how Ace deploys new deployment packages to targets and
how this strategy can be adapted to support more sophisticated scenario's.
-The remainder of this article assumes the reader has basic knowledge of the
principles behind Ace, and has sufficient programming skills. For this
article, the latest code of Ace (0.8.1-SNAPSHOT, rev.1326140) was used.
+This article describes how ACE deploys new deployment packages to targets and
how this strategy can be adapted to support more sophisticated scenario's.
+The remainder of this article assumes the reader has basic knowledge of the
principles behind ACE, and has sufficient programming skills. For this
article, the latest code of ACE (0.8.1-SNAPSHOT, rev.1326140) was used.
## Provisioning
-Apache Ace is all about provisioning software artifacts to targets. Software
artifacts, or simply, artifacts, can be compiled code, configuration files, or
any other artifact needed for a software system to operate. Provisioned
artifacts are bundled in so-called "deployment packages", that is comprised of
the differences between the target's current artifacts and the to-be-deployed
artifacts. To distinguish between deployment packages, each one is given its
own version. The increment of versions is done automatically by Ace when
changes are committed to its repository.
-When a new deployment package is available, it is not automatically sent to
the target as the communication between target and management server (Ace) is
unidirectional and initiated by the target. A target has to periodically check
whether new deployment packages are available, and if so, do something with it.
+Apache ACE is all about provisioning software artifacts to targets. Software
artifacts, or simply, artifacts, can be compiled code, configuration files, or
any other artifact needed for a software system to operate. Provisioned
artifacts are bundled in so-called "deployment packages", that is comprised of
the differences between the target's current artifacts and the to-be-deployed
artifacts. To distinguish between deployment packages, each one is given its
own version. The increment of versions is done automatically by ACE when
changes are committed to its repository.
+When a new deployment package is available, it is not automatically sent to
the target as the communication between target and management server (ACE) is
unidirectional and initiated by the target. A target has to periodically check
whether new deployment packages are available, and if so, do something with it.
-## Understanding Ace's deployment strategy
+## Understanding ACE's deployment strategy
Upon startup, the management agent, which represents a target, schedules
several tasks that periodically synchronize the local state with that of the
management server. Two of these tasks relate to the handling of deployment
packages: `DeploymentCheckTask` and `DeploymentUpdateTask`. Figure 1 shows the
relationship between the various components.
@@ -23,7 +23,7 @@ The `DeploymentCheckTask` is responsible
Figure 2: deployment strategy sequence diagram.
-Figure 2 shows a more detailed sequence diagram of the deployment update
strategy in Ace. The scheduler in the management agent calls the run()-method
of the DeploymentUpdateTask once every _N_ seconds. This method in its turn
makes several calls to the `DeploymentService`, which acts as a facade for
other services in Ace. The `DeploymentService` is queried for the highest local
and remote versions. If the remote version is newer than the local version, a
deployment package containing the changes between the local and the remote
version is installed. Note that this installation is done in a best
effort strategy: if it fails, all changes are rolled back to what they were.
As a consequence, if the installation fails one time, it probably will fail the
next time as well.Â
+Figure 2 shows a more detailed sequence diagram of the deployment update
strategy in ACE. The scheduler in the management agent calls the run()-method
of the DeploymentUpdateTask once every _N_ seconds. This method in its turn
makes several calls to the `DeploymentService`, which acts as a facade for
other services in ACE. The `DeploymentService` is queried for the highest local
and remote versions. If the remote version is newer than the local version, a
deployment package containing the changes between the local and the remote
version is installed. Note that this installation is done in a best
effort strategy: if it fails, all changes are rolled back to what they were.
As a consequence, if the installation fails one time, it probably will fail the
next time as well.Â
### Tweaking the deployment strategy
@@ -36,7 +36,7 @@ Another thing you can customize is wheth
To implement our own deployment strategy, we need to create a bundle that
provides the management agent with our update task. We will start with an
update task that simply prints something to the console each time it is run and
expand it later on. As can be seen in figure 1, a task is anything that
implements the `Runnable` interface, so our update task needs to do as well.
Furthermore, we will use the DependencyManager component from Felix to provide
us with the right dependent services, the most important one being the
`DeploymentService`.
The (stub) code for our update task looks like:
- #!java
+ #!JavaLexer
package net.luminis.ace.updatetask;
import org.apache.ace.deployment.service.DeploymentService;
@@ -54,7 +54,7 @@ The (stub) code for our update task look
The bundle activator that registers our update task as service:
- #!java
+ #!JavaLexer
package net.luminis.ace.updatetask;
import java.util.Properties;
@@ -92,10 +92,10 @@ The bundle activator that registers our
}
}
-The activator isn't that different from any other one, the only interesting
part is the service properties that we register along with our update task. The
three properties are used by the Ace's scheduler to determine that our service
is actually a scheduled task. With the "recipe" key, the scheduler is told what
interval (in milliseconds) is to be used to execute our task. In our case the
recipe is set to 5000, causing our task to be run once every five seconds.
+The activator isn't that different from any other one, the only interesting
part is the service properties that we register along with our update task. The
three properties are used by the ACE's scheduler to determine that our service
is actually a scheduled task. With the "recipe" key, the scheduler is told what
interval (in milliseconds) is to be used to execute our task. In our case the
recipe is set to 5000, causing our task to be run once every five seconds.
To complete the whole cycle, we need some build scripting. For this, we use
[BndTools](http://bndtools.org):
- #!bnd
+ :::text
Bundle-Name: My Update Task
Bundle-Version: 0.0.1
Bundle-SymbolicName: net.luminis.ace.updatetask
@@ -110,7 +110,7 @@ To complete the whole cycle, we need som
To let the management agent to find and use our custom update task bundle, we
need to add the JAR-file to its class path, and start the management agent with
the following options:
- #!sh
+ :::sh
[localhost:~/]$ java -Dorg.apache.ace.deployment.task=disabled \
 -cp org.apache.ace.launcher-0.8.1-SNAPSHOT.jar:net.luminis.ace.updatetask-1.0.0.jar
\
 org.apache.ace.launcher.Main \
@@ -129,7 +129,7 @@ After startup, our update task should pr
With the boiler plating in place, its time to make our update task a little
more interesting. We change the code of our update task to the following (for
brevity, only the run() method is shown):
- #!java
+ #!JavaLexer
   public void run() {
       try {
           Version local = m_service.getHighestLocalVersion();
@@ -157,19 +157,19 @@ With the boiler plating in place, its ti
This new implementation first asks the `DeploymentService` what the current
local (= version current running on management agent) and remote (= version
available in the management server) versions are. If the remote version is
newer/higher than the local version, than we ask the user for permission to
install the update. When given, the `DeploymentService` is requested to upgrade
from the local version to the remote version.
-If you would run this code, you'll notice that if the user doesn't respond
within the task's interval, a new task is started, causing an ever increasing
number of tasks to be waiting for user input in case an update is available.
Currently, due to the current implementation of Ace's scheduler, there is no
way of disabling this behavior (although it is not really difficult to resolve
this problem locally in your task).
+If you would run this code, you'll notice that if the user doesn't respond
within the task's interval, a new task is started, causing an ever increasing
number of tasks to be waiting for user input in case an update is available.
Currently, due to the current implementation of ACE's scheduler, there is no
way of disabling this behavior (although it is not really difficult to resolve
this problem locally in your task).
## Taking it a step furtherâ¦
-So far, we've reused the `DeploymentService` facade from Ace to tweak the
update process of the management agent a bit. However, there still some magic
going on in the installation of newer versions (all the logic behind
`DeploymentService#installVersion`).Â
+So far, we've reused the `DeploymentService` facade from ACE to tweak the
update process of the management agent a bit. However, there still some magic
going on in the installation of newer versions (all the logic behind
`DeploymentService#installVersion`).Â
Let's explore this method a bit more into detail. The `installVersion` method
roughly (some details are left out for brevity) has the following
implementation:
- #!java
+ #!JavaLexer
   // injected by Felix' dependency manager
   volatile Deployment m_deployer;
   volatile EventAdmin m_eventAdmin;
   volatile Identification m_identification;
- Â Â Â // denotes the host + port where Ace is listening, e.g.
http://192.168.1.1:8080/
+ Â Â Â // denotes the host + port where ACE is listening, e.g.
http://192.168.1.1:8080/
  final String m_host;
   /**
@@ -204,13 +204,12 @@ Let's explore this method a bit more int
           }
       }
-Basically, the method builds up an URL to access the deployment service of
Ace. Through this URL, the deployment-service creates a deployment package
containing the changed artifacts between the given local and remote version.
The `InputStream` containing this deployment package is given to the
`Deployment` service (a facade to the standard DeploymentAdmin service) to be
installed. Note that if the installation of the deployment package fails, an
exception is thrown. As mentioned earlier, the installation of deployment
packages is done in a "all or nothing" strategy, meaning that if it fails, all
changes are reverted. For more details on this, you can read the
DeploymentAdmin specification (see [2], chapter 114).
-Aside the actual installation of the deployment package, an event is also
posted to keep track of this installation. This event is picked up by the
`AuditLog` service of Ace to track all changes made to the management agent
(_one can argue whether this shouldn't be a responsibility of the Deployment
facade_).Â
+Basically, the method builds up an URL to access the deployment service of
ACE. Through this URL, the deployment-service creates a deployment package
containing the changed artifacts between the given local and remote version.
The `InputStream` containing this deployment package is given to the
`Deployment` service (a facade to the standard DeploymentAdmin service) to be
installed. Note that if the installation of the deployment package fails, an
exception is thrown. As mentioned earlier, the installation of deployment
packages is done in a "all or nothing" strategy, meaning that if it fails, all
changes are reverted. For more details on this, you can read the
DeploymentAdmin specification (see [2], chapter 114).
+Aside the actual installation of the deployment package, an event is also
posted to keep track of this installation. This event is picked up by the
`AuditLog` service of ACE to track all changes made to the management agent
(_one can argue whether this shouldn't be a responsibility of the Deployment
facade_).Â
-Now we have seen how the installation of deployment packages is implemented in
Ace, we can even tweak that process a bit. For example, we could first download
the deployment package entirely to a temporary location, and install it from
there. Or, as we have access to the deployment package, we could also provide
the user additional information about its contents, perhaps showing a change
log or a summary of its contents, before installing it.
+Now we have seen how the installation of deployment packages is implemented in
ACE, we can even tweak that process a bit. For example, we could first download
the deployment package entirely to a temporary location, and install it from
there. Or, as we have access to the deployment package, we could also provide
the user additional information about its contents, perhaps showing a change
log or a summary of its contents, before installing it.
## References
-1. Ace subversion, http://svn.apache.org/repos/asf/ace/;
-2. OSGi 4.2 compendium
specification, http://www.osgi.org/Download/Release4V42.
-
+1. [ACE subversion](http://svn.apache.org/repos/asf/ace/);
+2. [OSGi 4.2 compendium
specification](http://www.osgi.org/Download/Release4V42).
