ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r885755 - in /websites/staging/ace/trunk/content: ./ user-doc/
Date Thu, 07 Nov 2013 15:03:46 GMT
Author: buildbot
Date: Thu Nov  7 15:03:46 2013
New Revision: 885755

Log:
Staging update by buildbot for ace

Added:
    websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts.png   (with props)
    websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts_fail.png   (with props)
    websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts_ok.png   (with props)
    websites/staging/ace/trunk/content/user-doc/ace_dynamic_association.png   (with props)
    websites/staging/ace/trunk/content/user-doc/ace_static_association.png   (with props)
    websites/staging/ace/trunk/content/user-doc/ace_target_tag_editor.png   (with props)
Modified:
    websites/staging/ace/trunk/content/   (props changed)
    websites/staging/ace/trunk/content/user-doc/ace_server_ui.png
    websites/staging/ace/trunk/content/user-doc/user-guide.html

Propchange: websites/staging/ace/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Nov  7 15:03:46 2013
@@ -1 +1 @@
-1537515
+1539673

Added: websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts_fail.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts_fail.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts_ok.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/ace/trunk/content/user-doc/ace_dnd_artifacts_ok.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/ace/trunk/content/user-doc/ace_dynamic_association.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/ace/trunk/content/user-doc/ace_dynamic_association.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Modified: websites/staging/ace/trunk/content/user-doc/ace_server_ui.png
==============================================================================
Binary files - no diff available.

Added: websites/staging/ace/trunk/content/user-doc/ace_static_association.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/ace/trunk/content/user-doc/ace_static_association.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/ace/trunk/content/user-doc/ace_target_tag_editor.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/ace/trunk/content/user-doc/ace_target_tag_editor.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

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 Thu Nov  7 15:03:46 2013
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html lang="en">
   <head>
-    <title>ACE Users guide</title>
+    <title>ACE User guide</title>
     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
     <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
     <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
@@ -160,7 +160,7 @@
     </div>
     <div class="container">
       <p><a href="/"><i class='icon-home'></i> Home</a>&nbsp;&raquo&nbsp;<a
href="/user-doc/">User-doc</a></p>
-      <h1>ACE Users guide</h1>
+      <h1>ACE User guide</h1>
       <div class="clear"></div>
       <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">
@@ -181,8 +181,9 @@
 </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, 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
class="footnote-ref" 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>
+<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
+operate properly. 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 <em>immutable</em> versions of artifacts<sup
id="fnref:1"><a class="footnote-ref" 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, ACE always keeps a full history and audit trail for all changes.</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.</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>
@@ -202,16 +203,24 @@ Even though they are smart guys that kno
 <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" 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>
+<p>The easiest way to add one or more <em>new</em> artifacts is by simply
dragging and dropping them on the artifact column. <em>Note that a drop is accepted
only when a blue line or border is shown around the artifacts column (see figure 2)</em>.
The artifacts are uploaded automatically in the background, and when they are complete, a
summary of the upload results is shown as notification (see figure 3).</p>
+<p><a href="ace_dnd_artifacts.png" target="_blank"><img src="ace_dnd_artifacts.png"
width="640px" title="Figure 2: Adding new artifacts by dragging them onto the artifacts column.
Note the blue line surrounding the artifacts column denoting the drop can be accepted." /></a><br
/>
+<strong>Figure 2</strong>: Adding new artifacts by dragging them onto the artifacts
column. Note the blue line surrounding the artifacts column denoting the drop can be accepted
(click on image to see full size).</p>
+<p><a href="ace_dnd_artifacts_ok.png" target="_blank"><img src="ace_dnd_artifacts_ok.png"
width="640px" title="Figure 3: A notification is shown when all artifacts are successfully
uploaded." /></a><br />
+<strong>Figure 3</strong>: A notification is shown when all artifacts are successfully
uploaded (click on image to see full size).</p>
+<p>To add artifacts that are already in the <abbr title="OSGi Bundle Repository">OBR</abbr>,
you click the "Add artifact…" button. An "Add artifact" dialog opens, showing the artifacts
currently in the <abbr title="OSGi Bundle Repository">OBR</abbr> (but not yet
in the list of selected artifacts) and a list of to-be-uploaded artifacts. This window also
allows you to upload artifacts, and offers two options to do so:</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 uploading 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 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-custom-artifact-types.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>
+<p>If you try to upload an artifact that is not recognized by ACE, a failure notification
is displayed noting that that particular artifact is not uploaded, see also figure 4. Adding
support for new types of artifacts in ACE is discussed in <a href="/dev-doc/adding-custom-artifact-types.html">this
article</a>.</p>
+<p><img src="ace_dnd_artifacts_fail.png" width="369px" title="Figure 4: A failure
notification is shown when one or more artifacts could not be recognized by ACE." /><br
/>
+<strong>Figure 4</strong>: A failure notification is shown when one or more artifacts
could not be recognized by ACE.</p>
+<p>Once all artifacts are uploaded, they appear as selected rows in the artifacts column.
You can immediately drag them onto the feature column to link them to a particular feature.
By double clicking on an artifact, you can edit some of its properties, for example, its description.<br
/>
+To remove an artifact from the artifacts column, you simply press its trash-can icon. Note
that removing an artifact will only remove it from the artifacts column, <em>not</em>
from the <abbr title="OSGi Bundle Repository">OBR</abbr>.</p>
+<p><strong>NOTE</strong>: All changes made through the Web UI need to be
stored explicitly by pressing the "Store" button or by hitting CTRL+S (or CMD+S if you happen
to use OSX), otherwise they will not be visible to the ACE server. In case you want to revert
all changes, you can use the "Revert" button or CTRL/CMD+U. This will ignore all local changes
but does <em>not</em> retrieve the latest state from the server. To retrieve the
latest state from the server, use the "Retrieve" button or CTRL/CMD+G.</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 the feature or distribution and an optional description.</p>
+<p>Adding features and distributions are very similar. You either click the "Add Feature…"
or "Add Distribution…" buttons (or use the shortcut keys CTRL/CMD+F and CTRL/CMD+D).
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>
@@ -226,52 +235,79 @@ Even though they are smart guys that kno
 </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 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>
+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 "broken chain"
button 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 "broken chain"
button on the distribution. Alternatively, you can select the distribution first and hit the
"broken chain" button on the feature to delete the association.</p>
+<p>There is a subtle, but very important, difference when you associate a bundle-artifact
to a feature by dragging its symbolic name (without a version) onto a feature, or when you
drag a bundle-artifact with a version onto a feature. In the first case, you make a "dynamic"
association (see figure 5), which states that you always want the <em>latest</em>
version of that bundle to be associated to the feature, including any newer version that might
be uploaded in the future. In the latter case, you make a "static" association (see figure
6), which states that you always want that particular version of that bundle to be associated
to the feature.</p>
+<p><img src="ace_dynamic_association.png" width="516px" title="Figure 5: Creating
a dynamic association by dragging the BSN of a bundle onto a feature." /><br />
+<strong>Figure 5</strong>: Creating a dynamic association by dragging the BSN
of a bundle onto a feature.</p>
+<p><img src="ace_static_association.png" width="522px" title="Figure 6: Creating
a static association by dragging a particular version of a bundle onto a feature." /><br
/>
+<strong>Figure 6</strong>: Creating a static association by dragging a particular
version of a bundle onto a feature.</p>
+<p>Creating dynamic associations is currently only supported for bundle artifacts.
For other types of artifacts, such as configuration files, only static associations can be
created<sup id="fnref:2"><a class="footnote-ref" href="#fn:2" rel="footnote">2</a></sup>.
</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 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>
+<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 at least the ACE management
agent. This management agent periodically checks with the ACE server whether or not new software
is available. In case new software is available for a target, it can automatically download
and install it.</p>
+<p>ACE provides a runnable eclipse project, <tt>run-target</tt> that starts
an OSGi runtime, the ACE management agent, and a Gogo shell for easy debugging and demo purposes.
The management agent, or agent for short, itself can be found in the <tt>org.apache.ace.agent</tt>
project. This agent simply does the following:</p>
+<ol>
+<li>it uploads the audit log of the target to the ACE server. The audit log contains
all changes in bundle and framework state, such as the starting and stopping of the framework
and (de)installation of bundles;</li>
+<li>it check whether or not software updates are available. If so, it will download
it and install this update automatically.</li>
+</ol>
+<p>The agent can be configured by supplying it options through the command line (e.g.
<tt>-Dname=value</tt>):</p>
 <dl>
-<dt><code>agents</code></dt>
-<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>
-<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>
-<dt><code>bundle</code></dt>
-<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>
+<dt><tt>agent.identification.agentid</tt></dt>
+<dd>defines the name to uniquely identify a target on the ACE server. In case this
option is not supplied, a default value of <code>defaultTargetID</code> is used;</dd>
+<dt><tt>agent.discovery.serverurls</tt></dt>
+<dd>defines the ACE server URLs to connect to. Multiple URLs can be given to get a
form of fail-over: in case a connection to the first URL cannot be established, the second
URL will be used, and so on. If this option is given, at least one URL should be supplied,
and multiple URLs can be supplied by separating them with a comma. If this option is omitted,
a default value of <tt>http://localhost:8080</tt> is used;</dd>
+<dt><tt>agent.logging.level</tt></dt>
+<dd>defines the log level of the agent, and should be one of the following values:
<tt>DEBUG</tt>, <tt>INFO</tt>, <tt>WARNING</tt> or <tt>ERROR</tt>.
The default log level is <tt>INFO</tt>;</dd>
+<dt><tt>agent.controller.syncinterval</tt></dt>
+<dd>defines the interval (in seconds) in which the agent should synchronize with the
ACE server. A default of 60 seconds is used in case this option is not supplied;</dd>
+<dt><tt>agent.controller.syncdelay</tt></dt>
+<dd>defines how long the agent should wait (in seconds) after startup before it will
synchronize with the ACE server for the first time. A default of 5 seconds is used in case
this option is not supplied;</dd>
+<dt><tt>agent.controller.streaming</tt></dt>
+<dd>if given a value of <tt>false</tt>, all software updates will be downloaded
completely first after which it will be installed. Use this value in case you suffer from
unreliable network connections. A value of <tt>true</tt> (the default) causes
the agent to download and install any software update directly.</dd>
+<dt><tt>agent.controller.fixpackages</tt></dt>
+<dd>if given a value of <tt>true</tt> (the default), software updates will
only contain the deltas or changed artifacts. For large deployment packages, this can dramatically
reduce the size of an update. Use a value of <tt>false</tt> to get all artifacts
for each software update;</dd>
+<dt><tt>agent.controller.retries</tt></dt>
+<dd>defines the number of times the agent should retry to install a software update
in case its installation fails. If omitted, an installation is retried 3 times;</dd>
+<dt><tt>agent.connection.authtype</tt></dt>
+<dd>defines how to connections to the server are to be authenticated. Valid values
are <tt>NONE</tt> for no authentication, <tt>BASIC</tt> for using
HTTP-BASIC authentication or <tt>CLIENTCERT</tt> for using client certificates.
In case this option is omitted, a value of <tt>NONE</tt> is assumed and no authentication
is used. In case of the values <tt>BASIC</tt> or <tt>CLIENTCERT</tt>,
additional options should be supplied (see below);</dd>
+<dt><tt>agent.connection.username</tt> and <tt>agent.connection.password</tt></dt>
+<dd>provide the username and password used for HTTP-BASIC authentication;</dd>
+<dt><tt>agent.connection.sslProtocol</tt></dt>
+<dd>defines what SSL protocol is to be used for creating secure connections to the
ACE server, defaults to <tt>TLS</tt>;</dd>
+<dt><tt>agent.connection.keyfile</tt> and <tt>agent.connection.keypass</tt></dt>
+<dd>provide the keystore file and password that contain the certificate information
for establishing a secure conncetion between agent and server;</dd>
+<dt><tt>agent.connection.trustfile</tt> and <tt>agent.connection.trustpass</tt></dt>
+<dd>provide the truststore file and password that contain the trusted (server) certificate(s)
for establishing a secure connection between agent and server.</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
-Adding additional bundle activator: org.apache.ace.managementagent.Activator
-Started management agent.
-  Target ID    : MyTarget
-  Server       : http://192.168.1.1:8080
-  Sync interval: 2000 ms
-  Unaffected bundles will not be stopped during deployment.
-</pre></div>
-
-
-<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 class="footnote-ref" href="#fn:2" rel="footnote">2</a></sup>.
</p>
+<p>When the agent is started, a new target should appear in the ACE server after you
"Retrieve" the latest 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 check the "Registered?" option (and optionally the "Auto approve?" option as well)
and close the dialog by pressing "Ok"<sup id="fnref:3"><a class="footnote-ref" href="#fn:3"
rel="footnote">3</a></sup>. Once a target is registered, it cannot be unregistered
unless it is deleted (using the trash-icon).</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 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 class="footnote-ref" 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">&lt;properties&gt;</span>
-  <span class="nt">&lt;key&gt;</span>ipAddress<span class="nt">&lt;/key&gt;</span>
-  <span class="nt">&lt;value&gt;</span>${context.address}<span class="nt">&lt;/value&gt;</span>
+<p>All configuration files<sup id="fnref:4"><a class="footnote-ref" href="#fn:4"
rel="footnote">4</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.<br />
+In order to let ACE provision your (templated) configuration files to your target, you need
a <strong>resource processor</strong> that is capable of handling the configuration
files. Without such a resource processor, the configuration files cannot be deployed to your
target. See <a href="/dev-doc/adding-custom-artifact-types.html">this article</a>
for more information about writing resource processor for your configuration files, or use
an existing one, such as <a href="http://felix.apache.org/documentation/subprojects/apache-felix-autoconf.html">Felix
Autoconf resource processor</a>. </p>
+<p>Suppose a valid resource processor is available that recognizes <a href="http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html">Java
Properties XML</a>, consider the following configuration file:</p>
+<div class="codehilite"><pre><span class="nt">&lt;properties</span>
<span class="na">version=</span><span class="s">&quot;1.0&quot;</span><span
class="nt">&gt;</span>
+  <span class="nt">&lt;entry</span> <span class="na">key=</span><span
class="s">&quot;ipAddress&quot;</span><span class="nt">&gt;</span>${context.address}<span
class="nt">&lt;/entry&gt;</span>
+  <span class="nt">&lt;entry</span> <span class="na">key=</span><span
class="s">&quot;port&quot;</span><span class="nt">&gt;</span>${context.port}<span
class="nt">&lt;/entry&gt;</span>
+  <span class="nt">&lt;entry</span> <span class="na">key=</span><span
class="s">&quot;logLevel&quot;</span><span class="nt">&gt;</span>INFO<span
class="nt">&lt;/entry&gt;</span>
 <span class="nt">&lt;/properties&gt;</span>
 </pre></div>
 
 
-<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> -&gt; <code>192.168.2.1</code>,
and a similar tag on "Target2", like <code>address</code> -&gt; <code>192.168.2.2</code>.</p>
-<p>Under the covers, ACE uses Velocity<sup id="fnref:4"><a class="footnote-ref"
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>
+<p>The <tt>${context.address}</tt> and <tt>${context.port}</tt>
represent variables that can be replaced. The <tt>context.</tt> (including the
dot) prefix is mandatory, and everything after this prefix is user-definable and considered
as variable name. In this example, two variables are expected: <tt>address</tt>
and <tt>port</tt>. The values for these variables can be added to entities by
using the "Tag Editor", available when you double click on an artifact, feature, distribution
or target in the web UI<sup id="fnref:5"><a class="footnote-ref" href="#fn:5" rel="footnote">5</a></sup>.
It does not really matter on what entity the variables are actually defined, but in most cases
they are either defined on a distribution and/or target.</p>
+<p>Suppose we want to deploy the aforementioned configuration file to two targets,
"target-1", which is supposed to listen on <tt>192.168.2.1:80</tt> and "target-2",
which is supposed to listen on <tt>192.168.2.2:8080</tt>. To make the configuration
file specific for both targets, we simply need to define two tags on "target-1", like (see
also figure 7):</p>
+<ul>
+<li><tt>address</tt> -&gt; <tt>192.168.2.1</tt>;</li>
+<li><tt>port</tt> -&gt; <tt>80</tt>.</li>
+</ul>
+<p>And similar tags on "target-2": </p>
+<ul>
+<li><tt>address</tt> -&gt; <tt>192.168.2.2</tt>;</li>
+<li><tt>port</tt> -&gt; <tt>8080</tt>.</li>
+</ul>
+<p><img src="ace_target_tag_editor.png" width="600px" title="Figure 7: Using the
Tag Editor of a target to supply configuration variables." /><br />
+<strong>Figure 7</strong>: Using the Tag Editor of a target to supply configuration
variables.</p>
+<p>Under the covers, ACE uses Velocity<sup id="fnref:6"><a class="footnote-ref"
href="#fn:6" rel="footnote">6</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. See the Velocity documentation for more information on how to use this functionality.</p>
+<p>In case a variable cannot be resolved, it will simply not be replaced, but left
as-is. This could lead to invalid or unparsable artifacts (configuration files) on your target!</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 "target-1" and "target-2"
will get a processed version of the configuration file, each with its own specific content.
ACE also automatically versions these generated files, to aid downgrading software.</p>
 <div class="footnote">
 <hr />
 <ol>
@@ -279,13 +315,19 @@ Started management agent.
 <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.&#160;<a
class="footnote-backref" href="#fnref:1" rev="footnote" title="Jump back to footnote 1 in
the text">&#8617;</a></p>
 </li>
 <li id="fn:2">
-<p>Do not forget to store your changes!&#160;<a class="footnote-backref" href="#fnref:2"
rev="footnote" title="Jump back to footnote 2 in the text">&#8617;</a></p>
+<p>This is a limitation of the current web UI. It is possible to create more sophisticated
associations by using the REST API or the Gogo shell commands.&#160;<a class="footnote-backref"
href="#fnref:2" rev="footnote" title="Jump back to footnote 2 in the text">&#8617;</a></p>
 </li>
 <li id="fn:3">
-<p>In fact any artifact can be considered as an template, but by default ACE only considers
configuration files. &#160;<a class="footnote-backref" href="#fnref:3" rev="footnote"
title="Jump back to footnote 3 in the text">&#8617;</a></p>
+<p>Do not forget to store your changes!&#160;<a class="footnote-backref" href="#fnref:3"
rev="footnote" title="Jump back to footnote 3 in the text">&#8617;</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>.&#160;<a class="footnote-backref" href="#fnref:4" rev="footnote"
title="Jump back to footnote 4 in the text">&#8617;</a></p>
+<p>In fact any artifact can be considered as an template, but by default ACE only considers
configuration files. &#160;<a class="footnote-backref" href="#fnref:4" rev="footnote"
title="Jump back to footnote 4 in the text">&#8617;</a></p>
+</li>
+<li id="fn:5">
+<p>In other UIs, such as the Gogo shell, you need to supply these tags manually.&#160;<a
class="footnote-backref" href="#fnref:5" rev="footnote" title="Jump back to footnote 5 in
the text">&#8617;</a></p>
+</li>
+<li id="fn:6">
+<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>.&#160;<a class="footnote-backref" href="#fnref:6" rev="footnote"
title="Jump back to footnote 6 in the text">&#8617;</a></p>
 </li>
 </ol>
 </div></div>



Mime
View raw message