Author: buildbot
Date: Wed Aug 22 14:18:28 2012
New Revision: 829707
Log:
Staging update by buildbot for ace
Modified:
websites/staging/ace/trunk/content/ (props changed)
websites/staging/ace/trunk/content/user-doc/user-guide.html
Propchange: websites/staging/ace/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Aug 22 14:18:28 2012
@@ -1 +1 @@
-1375979
+1376068
Modified: websites/staging/ace/trunk/content/user-doc/user-guide.html
==============================================================================
--- websites/staging/ace/trunk/content/user-doc/user-guide.html (original)
+++ websites/staging/ace/trunk/content/user-doc/user-guide.html Wed Aug 22
14:18:28 2012
@@ -169,13 +169,12 @@
<p><a href="/"><i class='icon-home'></i> Home</a> » <a
href="/user-doc/">User-doc</a></p>
<h1>ACE Users guide</h1>
<div class="clear"></div>
- <div id="content"><p>This article describes how to use ACE and should be
a good starting point for new users of Apache ACE. The remainder of this
article assumes you've read and followed the "<a
href="/user-doc/getting-started.html">Getting Started</a>" guide, meaning that
you have an ACE server successfully up and running.</p>
-<p>Revision 0.8, last updated: August 22nd, 2012.</p>
+ <div id="content"><p>This article describes how to use ACE and is a good
starting point for new users of Apache ACE. The remainder of this article
assumes you've read and followed the "<a
href="/user-doc/getting-started.html">Getting Started</a>" guide, meaning that
you have an ACE server successfully up and running.</p>
<div class="toc">
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#workflow">Workflow</a></li>
-<li><a href="#working-with-ace-server">Working with ACE Server</a><ul>
+<li><a href="#working-with-the-ace-server">Working with the ACE Server</a><ul>
<li><a href="#uploading-artifacts">Uploading artifacts</a></li>
<li><a href="#creating-a-new-feature-distribution-andor-target">Creating a new
feature, distribution and/or target</a></li>
<li><a href="#creating-associations">Creating associations</a></li>
@@ -189,64 +188,70 @@
</div>
<h2 id="introduction">Introduction</h2>
<p>Apache ACE is a framework that enables you to provision OSGi
software(components) in a controlled manner. What this means is that you have a
central server to which clients, or "targets" in ACE terminology, connect and
fetch their software from. This allows one to control which target gets which
software. </p>
-<p>The software that is deployed to a target, is composed of one or more
distributions. A distribution is roughly similar to a piece of self-contained
software. For example, think of a distribution as C/C++ Development Tooling
that you can install on the Eclipse platform. On its own, distributions
consists of one or more features, that provide pieces of functionality to your
software. The difference between a feature and distribution is that the former
is not necessarily fully self-contained: it might need other features in order
to work. Each feature groups one or more artifacts. An artifact is anything
from an OSGi bundle, configuration file or any other kind of artifact that is
needed for the software to work. </p>
-<p>The artifacts themselves reside on an <abbr title="OSGi Bundle
Repository">OBR</abbr>, which can be either the default one supplied by ACE, or
an external one. Think of an <abbr title="OSGi Bundle Repository">OBR</abbr> as
a kind of Maven repository, storing read-only versions of artifacts<sup
id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>. As the <abbr
title="OSGi Bundle Repository">OBR</abbr> is the single source for all
artifacts, and therefore the software that is deployed on a target, ACE is able
to calculate how to upgrade a target from one version to another version. This
is possible because all changes made to (the metadata of) ACE are stored in an
internal versioned database. </p>
+<p>The software that is deployed to a target, is composed of one or more
distributions. A distribution is roughly similar to a piece of self-contained
software. For example, it could be a plugin or even a full application. On
their own, distributions consist of one or more features, that provide pieces
of functionality to your software. The difference between a feature and
distribution is that the former is not necessarily fully self-contained: it
might need other features in order to work. Each feature groups one or more
artifacts. An artifact is anything from an OSGi bundle to a configuration file
or any other kind of artifact that is needed for the software to work.</p>
+<p>The artifacts themselves reside in an <abbr title="OSGi Bundle
Repository">OBR</abbr>, which can be either the default one supplied by ACE, or
an external one. Think of an <abbr title="OSGi Bundle Repository">OBR</abbr> as
a repository, like the Maven repository or a content repository, storing
immutable versions of artifacts<sup id="fnref:1"><a href="#fn:1"
rel="footnote">1</a></sup>. As the <abbr title="OSGi Bundle
Repository">OBR</abbr> is the single source for all artifacts, and therefore
the software that is deployed on a target, ACE is able to calculate how to
upgrade a target from one version to another version. This is possible because
all changes made to (the metadata of) ACE are stored in an internal versioned
database. In other words, we always keep a full history and audit trail.</p>
<h2 id="workflow">Workflow</h2>
-<p>The typical use case for using ACE is where you want to control and manage
which software runs on what target. So, how does one use ACE in practice? To
explain the typical workflow of ACE, let's take the following example.<br />
-Assume you are working on a large OSGi-based system that provides some kind of
service to your customers (the exact details on what it does isn't relevant for
this example). Since you're trying to make real money out of it, and take
development seriously, you want to set up a <abbr title="Development, Testing,
Acceptance and Production">DTAP</abbr> environment. Your developers are working
on their development machines, using the bleeding edge software. They are smart
guys that can set up their own environments, so ACE won't be of much help
here.<br />
-</p>
-<p>There is also have a tester on your team, responsible for testing all the
new features and bug fixes made by your developers. This tester does not want
to have to set up its own environment and fiddle around with configuration
files and such. Instead, he simply wants a working test environment that runs a
recent version of your software. This is were ACE can help you out. All you
need to do is create a testing target, on which a recent software version gets
deployed. That "recent version", can, for example, be a nightly build that
comes out of your <abbr title="Continuous Integration">CI</abbr> server that
automatically gets pushed to ACE after the nightly build is finished.
Alternatively, the tester also can deploy an older version to its testing
target through the ACE server UI, for example, to do some regression
testing.</p>
-<p>Before a new version of your software is put into production, your
customers want to do some acceptance testing to see whether this new version
does not break anything. The acceptance environment should only be updated when
a new version is released and after that remains as-is. In practice, this is
most often not the case, as the acceptance environment is, when not used by any
customer, confiscated by your tester for its daily testing purposes, simply,
because ACE allows him to easily deploy other versions to the acceptance
environment. When a customer asks for an acceptance test, he simply deploys the
latest greatest official release to the acceptance environment, and lets the
customer do its testing. After that, he can repurpose it again.</p>
+<p>The typical use case for using ACE is where you want to control and manage
which software runs on what target. So, how does one use ACE in practice? To
explain the typical workflow of ACE, let's take the following example.</p>
+<p>Assume you are working on a large OSGi-based system that provides some kind
of service to your users (the exact details on what it does isn't relevant for
this example).</p>
+<p>Since you're a professional and take development seriously, you want to set
up a <abbr title="Development, Testing, Acceptance and Production">DTAP</abbr>
environment.
+Your developers are working on their development machines, using the bleeding
edge software.
+Even though they are smart guys that know the software inside out and can set
up their own environments, they still might want to use ACE on their local
machines to validate that changes they make indeed work when deployed. In this
cases it makes sense to use the same deployment method that is used in
production lateron as well.</p>
+<p>There is also a tester on your team, responsible for testing all the new
features and bug fixes made by your developers. This tester does not want to
have to set up his own environment and fiddle around with configuration files
and such. Instead, he simply wants a working test environment that runs a
recent version of your software. This is were ACE can help you out. All you
need to do is create targets for testing, on which a recent software version
gets deployed. That "recent version", can, for example, be a nightly build that
comes out of your <abbr title="Continuous Integration">CI</abbr> server that
automatically gets pushed to ACE after the nightly build is finished.
Alternatively, the tester also can deploy an older version to his testing
target through the ACE server UI, for example, to do some regression testing. A
third scenario might be to duplicate the exact configuration and version that
is currently deployed to a specific user's target.</p>
+<p>Before a new version of your software is put into production, your users
want to do acceptance testing to see whether this new version does not break
anything. The acceptance environment should only be updated when a new version
is released and after that remains as-is. In practice, this is most often not
the case, as the acceptance environment is, when not used by any user,
confiscated by your tester for its daily testing purposes, simply, because ACE
allows him to easily deploy other versions to the acceptance environment. When
a user asks for an acceptance test, he simply deploys the latest greatest
official release to the acceptance environment, and lets the user do its
testing. After that, he can repurpose it again. Another scenario obviously is
that users setup dedicated targets for the purpose of acceptance testing.</p>
<p>When all acceptance tests are successful, the new version of your software
needs to be deployed on several production environments, which is done by you,
the release manager. As most production environments only differ in a few
details, such as IP addresses and database credentials, you use the template
engine of ACE to make specific configuration files for each production target.
This way, you can easily scale up your production environment by defining new
targets and provide them with the necessary configuration values.</p>
-<h2 id="working-with-ace-server">Working with ACE Server</h2>
+<h2 id="working-with-the-ace-server">Working with the ACE Server</h2>
<p>The server UI might look a bit daunting at first, but once you become more
familiar with it, you'll see that it is rather easy to work with.<br />
</p>
<p><a href="ace_server_ui.png" target="_blank"><img src="ace_server_ui.png"
width="640px" title="Figure 1: The server UI of ACE, showing the control area
at the top, and the resource area below that." /></a><br />
<strong>Figure 1</strong>: The server UI of ACE after logging in, showing the
control area at the top, and the resource area below that (click on image to
see full size).</p>
<p>After logging in, the main window consists of two main areas:</p>
<ol>
-<li>The control area at the top of the screen, where you can perform actions
like, retrieving the latest repository changes, revert the changes you've made
locally, add new artifacts, and so on;</li>
-<li>The resource area, consisting of (up to) four columns showing the current
artifacts, features, distributions and targets that are known to ACE.</li>
+<li>The control area at the top of the screen, where you can perform actions
like retrieving the latest repository changes, revert the changes you've made
locally, add new artifacts, and so on;</li>
+<li>The resource area, consisting of (up to) four columns showing the current
artifacts, features, distributions and targets that are known to ACE. When you
select an entity here, the associated entities in other columns will
automatically be highlighted, giving you an instant overview of the links
within the system.</li>
</ol>
<h3 id="uploading-artifacts">Uploading artifacts</h3>
-<p>To upload one or more artifacts, you click on the "Add artifactâ¦" button.
An "Add artifact" dialogs opened, showing both the artifacts currently in the
<abbr title="OSGi Bundle Repository">OBR</abbr> and a list of uploaded
artifacts. There are two possibilities to upload a file:</p>
+<p>To upload one or more artifacts, you click on the "Add artifactâ¦" button.
An "Add artifact" dialog opens, showing both the artifacts currently in the
<abbr title="OSGi Bundle Repository">OBR</abbr> but not in the artifact list
and a list of uploaded artifacts. There are two possibilities to upload a
file:</p>
<ol>
<li>Upload the individual artifacts by pressing the "Upload" button and
selecting the artifact from the file chooser dialog, or;</li>
<li>by using drag-and-drop: select all artifacts in an Explorer or Finder and
drag them onto the "Upload artifact" area. This way, you can upload multiple
artifacts in one go.</li>
</ol>
-<p>Once artifacts are uploaded, they appear in the Artifacts listing. For each
artifact, you can edit its properties by double clicking on it. In addition,
you can unlink an artifact from a feature, which will be discussed later on,
and remove an artifact. <strong>Note</strong>: removing an artifact will only
remove it from the server's metadata, <em>not</em> from the <abbr title="OSGi
Bundle Repository">OBR</abbr>. </p>
-<p>If you try to upload an artifact that is not recognized by ACE, an error is
displayed noting that that particular artifact is not uploaded. Adding support
for particular artifacts in ACE is discussed in <a
href="/dev-doc/adding-artifact-recognizers.html">this article</a>.</p>
+<p>Once artifacts are uploaded, they appear in the Artifacts column. For each
artifact, you can edit its properties by double clicking on it. In addition,
you can unlink an artifact from a feature, which will be discussed later on,
and remove an artifact. <strong>Note</strong>: removing an artifact will only
remove it from the server's metadata, <em>not</em> from the <abbr title="OSGi
Bundle Repository">OBR</abbr>. </p>
+<p>If you try to upload an artifact that is not recognized by ACE, an error is
displayed noting that that particular artifact is not uploaded. Adding support
for new types of artifacts in ACE is discussed in <a
href="/dev-doc/adding-artifact-recognizers.html">this article</a>.</p>
<p><strong>NOTE</strong>: All changes made through the Web UI need to be
stored explicitly by pressing the "Store" button, otherwise they will not be
visible to the ACE server. In case you want to revert all changes, you can use
the "Revert" button. This will ignore all changes and retrieve the latest state
from the server. In case there are no local changes, you can still retrieve the
latest state from the server using the "Retrieve" button.</p>
<h3 id="creating-a-new-feature-distribution-andor-target">Creating a new
feature, distribution and/or target</h3>
-<p>Adding features and distributions are very similar. You either click the
"Add Featureâ¦" or "Add Distributionâ¦" buttons. In both cases, you are
presented with a dialog that allows you to enter the (mandatory) name of
feature (or distribution) and an optional description. <br />
-There are two ways of adding a target to ACE: either you click the "Add
Targetâ¦" button and enter the name of the new target, or let a running target
register itself to ACE. The details on this will be discussed later on.</p>
+<p>Adding features and distributions are very similar. You either click the
"Add Featureâ¦" or "Add Distributionâ¦" buttons. In both cases, you are
presented with a dialog that allows you to enter the (mandatory) name of the
feature or distribution and an optional description.</p>
+<p>There are two ways of adding a target to ACE:</p>
+<ol>
+<li>You can pre-register a target by clicking the "Add Targetâ¦" button and
entering the name of the new target. This allows you to associate software to
this target even before it has ever been started or seen by the server.</li>
+<li>You can register a target that is already running and has already tried to
fetch software from the ACE server. The details on this will be discussed later
on.</li>
+</ol>
<p>After a feature, distribution or target is created, you can edit its
properties by double clicking it. For features and distributions, this means
you can alter their description, while for targets, there are more
possibilities to view and alter:</p>
<ul>
<li>On the Management tab, you can change whether or not the target should be
automatically updated to the latest software. If selected, all updates will
automatically be approved and distributed to that target. If not, any update
must be explicitly approved prior to being distributed to the target;</li>
<li>On the Info tab, you can view the current state of the target, such as the
currently installed version, or the latest available software version;</li>
<li>On the LogViewer tab, you can view the installation log of the target.
This allows you to review the installation of updates on that target;</li>
-<li>The Tag Editor tab allows you to define tags and their replacement values
that will be replaced in any artifacts that contain those tags. This is useful,
for example, to have a single configuration file that can be used for multiple
targets. </li>
+<li>The Tag Editor tab allows you to define tags and their values. Tags can be
used for many things, but one of their more interesting use cases is that they
can be used to replace variables in template artifacts that contain those tags.
This is useful, for example, to have a single configuration file that can be
used for multiple targets, because it is largely the same for all of them.</li>
</ul>
<h3 id="creating-associations">Creating associations</h3>
-<p>To link artifacts to features, you simply select the artifact and drag it
on top of the feature to which it should be associated. The same principle also
apply to associate features to distributions and distributions to targets.<br />
-To delete an association once is created, you can click either the left- or
the right side of the association (viz. either the artifact or the feature),
and click the "-" on the opposite side of the association. For example, to
delete an association between an feature and distribution, you can select the
feature first, and hit the "-" on the distribution. Alternatively, you can
select the distribution first and hit the "-" on the feature to delete the
association.</p>
-<p>Associations can be parameterized, allowing it to be dynamic in what it
matches on left-side and/or right-side of the association. For example, by
default an association between a bundle artifact and a feature will be made to
match the <em>latest</em> version of the bundle. This way, if you upload a new
version of a bundle, the feature will automatically link to that version. While
this is certainly handy in many situations, there are also situations in which
you do not always want to link to the latest greatest version of a bundle. An
example might be the bundles that should run on your production environment,
which should only get an update in controlled upgrades, not when you upload a
new artifact to ACE. To disable the "dynamic" associations between, uncheck the
"Dynamic Links" option in the UI <em>before</em> you create the association.
This will create an association that is explicitly bound to the symbolic name
and version of a bundle.</p>
+<p>To link artifacts to features, you simply select the artifact and drag it
on top of the feature to which it should be associated. The same principle also
applies if you want to associate features to distributions and distributions to
targets.
+To delete an association once is created, you can click either the left- or
the right hand side of the association (viz. either the artifact or the
feature), and click the "-" on the opposite side of the association. For
example, to delete an association between an feature and distribution, you can
select the feature first, and hit the "-" on the distribution. Alternatively,
you can select the distribution first and hit the "-" on the feature to delete
the association.</p>
+<p>Associations can be parameterized, allowing them to be dynamic in what they
match on the left hand side and/or the right hand side of the association. For
example, by default an association between a bundle artifact and a feature will
be made to match the <em>latest</em> version of the bundle. This way, if you
upload a new version of a bundle, the feature will automatically link to that
version. While this is certainly handy in many situations, there are also
situations in which you do not always want to link to the latest greatest
version of a bundle. An example might be the bundles that should run on your
production environment, which should only get an update in controlled upgrades,
not when you upload a new artifact to ACE. To disable the "dynamic"
associations between, uncheck the "Dynamic Links" option in the UI
<em>before</em> you create the association. This will create an association
that is explicitly bound to the symbolic name and version of a bundle.</p>
<h2 id="running-a-target">Running a target</h2>
-<p>As mentioned, a target represents a client on which software can be
deployed by ACE. Actually, a target consists of a small OSGi runtime that runs
an management agent that periodically checks with the ACE server whether or not
it is has new software for it. In case new software is available for a target,
it will automatically download it and install it. </p>
-<p>ACE provides a fully self-contained management agent, that can be run as
plain Java JAR, named <tt>org.apache.ace.launcher.jar</tt>. This management
agent wrapper accepts the following command line arguments:</p>
+<p>As mentioned, a target represents a client on which software can be
deployed by ACE. Actually, a target consists of an OSGi runtime that runs a
management agent that periodically checks with the ACE server whether or not it
has new software for it. In case new software is available for a target, it can
automatically download and install it.</p>
+<p>ACE provides a fully self-contained target that includes a management agent
and can be run as plain Java JAR, named <tt>org.apache.ace.launcher.jar</tt>.
This target accepts the following command line arguments:</p>
<dl>
<dt><code>agents</code></dt>
-<dd>configures the target to act as multiple management agents:
<code>agent-id,identification,discovery[;agent-id,identification,discovery]*</code>;</dd>
+<dd>Configures the target to have multiple management agents:
<code>agent-id,identification,discovery[;agent-id,identification,discovery]*</code>.
If you specify this option, the identification and discovery arguments below
are ignored. Configuring multiple management agents is a very specific use case
that should be avoided unless you know exactly what you're doing. It was added
so a target can fetch different, non-overlapping parts of the software from
different servers. In general though, it is preferable and more convenient to
channel all software updates through a single server.</dd>
<dt><code>auth</code></dt>
<dd>point to the properties file containing the authentication credentials for
a certain subsystem. Can be either a directory, file or URL;</dd>
<dt><code>discovery</code></dt>
-<dd>sets the ACE server to connect to, should be an URL. Defaults to
<code>http://localhost:8080</code>;</dd>
+<dd>Sets the ACE server to connect to, should be an URL. Defaults to
<code>http://localhost:8080</code>.</dd>
<dt><code>id</code> or <code>identification</code></dt>
-<dd>defines the name to identify the target on in the ACE server. Defaults to
<code>defaultTargetID</code>;</dd>
+<dd>Defines the name to identify the target on in the ACE server. Defaults to
<code>defaultTargetID</code>.</dd>
<dt><code>bundle</code></dt>
-<dd>adds an additional bundle to be started with this management agent:
<code>bundle=my.fully.qualified.BundleActivator</code>;</dd>
+<dd>Adds an additional bundle to be started with this management agent. The
bundle itself has to be on the Java classpath.
<code>bundle=my.fully.qualified.BundleActivator</code>;</dd>
<dt><code>fwOption</code></dt>
-<dd>sets framework options for the OSGi framework to be created. This argument
may be repeated. For example:
<code>fwOption=org.osgi.framework.system.packages.extra=sun.misc,com.sun.management</code>.</dd>
+<dd>Sets framework options for the OSGi framework to be created. This argument
may be repeated. For example:
<code>fwOption=org.osgi.framework.system.packages.extra=sun.misc,com.sun.management</code>.</dd>
</dl>
<p>An example on how to run the launcher is:</p>
<div class="codehilite"><pre><span class="nv">$ </span>java -jar
org.apache.ace.launcher.jar <span class="nv">id</span><span
class="o">=</span>MyTarget <span class="nv">discovery</span><span
class="o">=</span>http://192.168.1.1:8080
@@ -261,8 +266,8 @@ Started management agent.
<p>After the management agent is started, a new target should appear in the
ACE server after you "Retrieve" the latest changes or "Revert" the current
changes. If a target is added this way to the ACE server (instead of adding it
through the "Add targetâ¦" button), it initially will be
<em>unregistered</em>. This means that no metadata is present in the ACE server
yet and will not be created. To register a target, you can double click the
target to edit its properties. On the "Management" tab, you can select the
"Registered?" (and optionally the "Auto approve?" option as well) and close the
dialog by pressing "Ok"<sup id="fnref:2"><a href="#fn:2"
rel="footnote">2</a></sup>. </p>
<h3 id="using-the-template-engine-for-targets">Using the template engine for
targets</h3>
-<p>If you want to provision software to multiple targets, those targets
probably need to have their own specific configuration. For example, the IP
address on which it should listen for web requests, or the credentials to
access a database. One could create specific configuration files for each
target, however, this can become quite tedious is you have lots of targets.
Aside that, ACE requires that each artifact has an unique name, so you need to
create unique file names for your configuration files for each change you make.
Fortunately, ACE provides an easier way to solve this problem: an template
engine.</p>
-<p>All configuration files<sup id="fnref:3"><a href="#fn:3"
rel="footnote">3</a></sup> can be regarded as templates, in which variables are
replaced with values supplied by ACE. In fact, the values are definable per
target, distribution, feature or artifact. To define variables and their
replacement values (or "tags") for, for example, a distribution, open up its
properties dialog by double clicking on it, and selecting the "Tag Editor" tab.
Each line in this editor represents a tag. The key of a tag defines that (part
of) the variable name to be replaced in configuration files, and the value of a
tag the actual replacement value. </p>
+<p>If you want to provision software to multiple targets, those targets
probably need to have their own specific configuration. For example, the IP
address on which it should listen for web requests, or the credentials to
access a database. One could create specific configuration files for each
target, however, this can become quite tedious if you have lots of targets.
Besides that, ACE requires that each artifact has a unique name, so you need to
create unique file names for your configuration files for each change you make.
Fortunately, ACE provides an easier way to solve this problem: a template
engine.</p>
+<p>All configuration files<sup id="fnref:3"><a href="#fn:3"
rel="footnote">3</a></sup> can be regarded as templates, in which variables are
replaced with values supplied by ACE. In fact, the values are definable per
target, distribution, feature or artifact and ACE will collect all tags of
entities that are associated with a specific target. To define variables and
their replacement values (or "tags") for, for example, a distribution, open up
its properties dialog by double clicking on it, and selecting the "Tag Editor"
tab. Each line in this editor represents a tag. The key of a tag defines that
(part of) the variable name to be replaced in configuration files, and the
value of a tag the actual replacement value. </p>
<p>For example, consider the following configuration file:</p>
<div class="codehilite"><pre><span class="nt"><properties></span>
<span class="nt"><key></span>ipAddress<span
class="nt"></key></span>
@@ -272,13 +277,14 @@ Started management agent.
<p>The <tt>${context.address}</tt> represent the variable that will be
replaced. The "context." part is mandatory, and everything after that is user
definable. Suppose we want to deploy this configuration file to two targets,
"Target1", which is supposed to listen on address 192.168.2.1 and "Target2",
which is supposed to listen on address 192.168.2.2. To make the configuration
file specific for both targets, we simply need to define a tag on "Target1",
like: <code>address</code> -> <code>192.168.2.1</code>, and a similar tag on
"Target2", like <code>address</code> -> <code>192.168.2.2</code>.</p>
-<p><strong>NOTE</strong>: In case a configuration file consists of a variable
that cannot be resolved, it will simply not be replaced, but left as-is. This
way, you can still include Velocity-like templates in your distribution without
having them garbled by ACE.</p>
+<p>Under the covers, ACE uses Velocity<sup id="fnref:4"><a href="#fn:4"
rel="footnote">4</a></sup> to parse the template. This means that, apart from
variable substitution, you can also use other Velocity macros and create more
complex configurations that might contain conditional sections, loops and other
features Velocity provides.</p>
+<p><strong>NOTE</strong>: In case a configuration file consists of a variable
that cannot be resolved, it will simply not be replaced, but left as-is.</p>
<p>ACE will scan all configuration files and replace all known variables as
soon as a new deployment is created. This means that for our example, both
"Target1" and "Target2" will get their own copy of the configuration file with
their specific content. ACE also automatically versions these generated files,
to aid downgrading software.</p>
<div class="footnote">
<hr />
<ol>
<li id="fn:1">
-<p>Once an artifact is uploaded to the <abbr title="OSGi Bundle
Repository"><abbr title="OSGi Bundle Repository"><abbr title="OSGi Bundle
Repository">OBR</abbr></abbr></abbr>, it cannot be modified anymore. This is
necessary in order to allow both software upgrades as downgrades
possible. <a href="#fnref:1" rev="footnote" title="Jump back to footnote 1
in the text">↩</a></p>
+<p>Once an artifact is uploaded to the <abbr title="OSGi Bundle
Repository"><abbr title="OSGi Bundle Repository"><abbr title="OSGi Bundle
Repository">OBR</abbr></abbr></abbr>, it cannot be modified anymore. This is
necessary in order to allow both software upgrades as downgrades and to ensure
that everything you do is reproducible. One thing to note is that this is not
compatible with the way that Maven handles snapshot versions. A snapshot can
contain anything. In stead we usually use the version qualifier to append a
timestamp in such scenarios. <a href="#fnref:1" rev="footnote" title="Jump
back to footnote 1 in the text">↩</a></p>
</li>
<li id="fn:2">
<p>Do not forget to store your changes! <a href="#fnref:2" rev="footnote"
title="Jump back to footnote 2 in the text">↩</a></p>
@@ -286,6 +292,9 @@ Started management agent.
<li id="fn:3">
<p>In fact any artifact can be considered as an template, but by default ACE
only considers configuration files.  <a href="#fnref:3" rev="footnote"
title="Jump back to footnote 3 in the text">↩</a></p>
</li>
+<li id="fn:4">
+<p>Apache Velocity is an engine that can generate documents by combining a
template with a context that contains variables. To learn more about it, visit
the <a href="http://velocity.apache.org/";>Velocity website</a>. <a
href="#fnref:4" rev="footnote" title="Jump back to footnote 4 in the
text">↩</a></p>
+</li>
</ol>
</div></div>
<hr>
