ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject svn commit: r1327415 - /ace/site/trunk/content/dev-doc/design/ace-deployment-strategies.mdtext
Date Wed, 18 Apr 2012 08:07:10 GMT
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: sequence diagram](deployment_strategy_update_seq.svg "Figure 2: sequence diagram")
 
 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).



Mime
View raw message