You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ace.apache.org by ja...@apache.org on 2014/11/24 23:42:03 UTC
svn commit: r1641501 [3/4] - in /ace/site/trunk/content: ./ dev-doc/ docs/
docs/analysis/ docs/analysis/src/ docs/design/ docs/design/src/
docs/use-cases/ user-doc/
Added: ace/site/trunk/content/docs/getting-started-5-mins.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/getting-started-5-mins.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/getting-started-5-mins.mdtext (added)
+++ ace/site/trunk/content/docs/getting-started-5-mins.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,157 @@
+Title: Getting Started in 5 minutes
+
+This guide shows the core functionality of Apache ACE, organising bundles and other
+artifacts into logical features and distributions and associating those with specific
+targets, all done using a convenient web interface.
+
+## Introduction
+
+Apache ACE consists of several parts:
+
+1. one or more **targets**, which essentially is a small OSGi framework containing an ACE
+agent that contacts the ACE server on a regular basis to inquire for new software that
+needs to be deployed;
+2. the **ACE (provisioning) server**, which runs the logic to determine what software
+needs to be provisioned to what target;
+3. a **bundle repository**, that contains the actual artifacts that need to be deployed
+onto the targets;
+4. the **ACE client**, used to define the what software should be provisioned on which
+target. By default, there are three different implementations available:
+ a. a *web-based* client, that provides you a simple drag-and-drop interface to manage
+ your targets;
+ b. a *Gogo-shell based* client, that allows you to control your targets using the
+ Gogo-shell from Apache Felix;
+ b. a *REST-based* client, that can be used, for example, to integrate Apache ACE in any
+ other (scripting) language you want.
+
+All of the various parts can either run on a single machine, for demo/testing purposes, or
+run on various machines, depending on your actual use-case. It is not uncommon that the
+various parts all run on different machines. In fact, it is one of the easiest ways to
+scale an Apache ACE instance.
+
+
+## Download the distribution
+
+In order to get started with Apache ACE, you must first download the latest ACE
+distribution:
+
+1. Download the latest binary distribution called `apache-ace-<version>-bin.zip` from the
+[download](/downloads.html) page;
+2. Unpack the downloaded archive somewhere on your filesystem.
+
+## Start the ACE server
+
+As explained above, Apache ACE consists of several different parts. For convenience, the
+ACE distribution provides an all-in-one variant that allows you to start the ACE
+provisioning server, a bundle repository and the ACE web-based client using a single JAR:
+
+1. Open a terminal and navigate to the root of the distribution;
+2. Navigate to the sub directory `server-allinone`;
+3. Start the server using `java -jar server-allinone.jar`.
+
+In case you are wondering how you can tweak Apache ACE, there are some properties that can
+be overridden directly from the command line (for convenience), but most of the
+configuration options are defined in the configuration files located in the <tt>conf</tt>
+directory inside the <tt>server-allinone</tt> directory. For example, to start the web
+server of Apache ACE on a different port, you can start the server as follows:
+
+ java -Dorg.osgi.service.http.port=9000 \
+ -Dorg.apache.ace.server=localhost:9000 \
+ -Dorg.apache.ace.obr=localhost:9000 \
+ -jar server-allinone.jar
+
+Since you're moving *all* the different parts to a different port, that is, the
+provisioning server and bundle repository, to a different port, you need to redefine a
+couple of properties in order to make this work.
+
+To test your server is up and running, you can go to `http://localhost:8080/ace` (or
+`http://localhost:9000/ace` in case you're using a different port) to be presented with
+the a login dialog. You can login by using the default credentials which is <tt>d</tt> as
+username and <tt>f</tt> as password.
+
+
+## Start an ACE target
+
+Now we have the ACE server up and running, we can start an actual target to deploy software to. To start a single target, you need to:
+
+1. Open a terminal and navigate into the root of the ACE distribution;
+2. Navigate to the sub directory `target`;
+3. Start the target using `java -jar target.jar`.
+
+Similar as with the ACE server, you can tweak the configuration of the target from the
+commandline. For example, if you changed the default port of the ACE server to
+<tt>9000</tt>, you need to run the following command:
+
+ java -Dagent.discovery.serverurls=http://localhost:9000 \
+ -jar target.jar
+
+A more comprehensive list of paramaters you can override is described in the [user
+guide](user-guide.html#running-a-target).
+
+
+## Provisioning software
+
+The basic workflow for defining what software needs to be provisioned to what target is:
+
+1. you start with checking out a workspace, in the web UI, this is done implicitly for you
+once you start to interact with the user interface;
+2. you add the artifacts and define the feature(s) and distribution(s) that need to be
+deployed onto your targets;
+3. once you're satisfied with the results, you can commit the results back to the ACE
+server, at which point they will be applied to your targets.
+
+For this demonstration, you need a couple of bundles that you can deploy onto a target. In
+case you do not have any bundles "lying around", you can take a look at the [sample
+application as provided by the Apache Felix project](http://felix.apache.org/documentation/tutorials-examples-and-presentations/apache-felix-application-demonstration.html).
+Follow its instructions and once you're able to run the application locally, you can use
+the resulting bundles in ACE.
+
+1. Go to the ACE web-based UI, and click `Retrieve` in order to be sure that you have the
+latest version of the repository. If your target is up and running, it should be displayed
+in the "Targets" column with a name of `target-1`;
+2. Add the artifacts you want to deploy. This can be done in two ways: either by
+dragging-and-dropping them directly onto the "Actifacts" column (a blue border or line
+should appear for the artifacts to be accepted). Alternatively, you can use the <tt>+</tt>
+button above the "Artifacts" column and using the "Upload" button in the dialog presented
+for each artifact you want to add;
+3. Create a new feature by clicking on the <tt>+</tt> button above the Features column,
+give it a name and acknowledge the dialog;
+4. Create a distribution by clicking on the <tt>+</tt> button above the "Distributions"
+column, again give it a name and acknowledge the dialog;
+5. Next, you can create associations between your artifacts, features, distributions and
+targets:
+ a. select one or more artifacts and drag them onto the feature you created. This will
+ associate these artifacts to your feature;
+ b. select your feature and drag it onto your distribution, creating an association
+ between your feature and distribution;
+ c. select your distribution and drag it onto your target to associate your distribution
+ to your target.
+6. Verify your associations are correct by clicking your artifacts, features and
+distributions. Doing this should highlight the associations. To persist the changes, you
+can use the `Store` button at the top of the screen;
+7. After a couple of seconds, the software is deployed onto the target. If you used the
+Felix demonstration application, you should be presented with a nice Swing UI.
+
+### It doesn't work!
+
+If the previous steps did not provided you with a Swing UI, you need to find out what went
+wrong. There are several ways to find out why your target is not being provisioned
+correctly:
+
+1. Inspect state and log of the target by double-clicking it in the web UI. It presents
+you a dialog with a couple of tabs. On the `Info` tab, you can find some basic information
+on the actual state of the target, such as which version is deployed, which version should
+be deployed, and so on. Alternatively, the LogViewer provides you a little more
+information on what might be wrong. It is a very basic view on the log entries that the
+target sent back to the server;
+2. Alternatively, you can go to the terminal where your target is running and use the Gogo
+shell to find out what is happening directly onto the target. You can use `log 1` to see
+the latest log entries, or `lb` to list the bundles that are currently running. Most of
+the times, the log gives you some clue what went wrong.
+
+## Next steps
+
+If you want to continue on learning more details on Apache ACE, you can continue to the
+detailed [user guide](user-guide.html). Or you might want to go back to the [main
+documentation](../docs.html) to check out any other topic that might be of interest.
+
Propchange: ace/site/trunk/content/docs/getting-started-5-mins.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/history-and-background.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/history-and-background.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/history-and-background.mdtext (added)
+++ ace/site/trunk/content/docs/history-and-background.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,44 @@
+Title: Introduction
+
+Since its birth in 1999, OSGi has steadily been gaining popularity as the component model
+of choice for Java. Originally designed as a framework for home gateways and other
+embedded systems, it has since moved on to desktop and enterprise systems and embraced by
+major software vendors.
+
+OSGi allows you to build your systems out of well defined, reusable components, which
+brings both exciting new benefits as well as a set of challenges. One of these is the
+actual management of components, deployed on different target systems.
+
+Traditional, monolithic systems usually have fairly straightforward and linear release
+schedules. It is quite common for most target systems to have the same version and
+configuration of such a system.
+
+Component based systems can easily be customized on a per target case, meaning there might
+be many different configurations out there. When components are developed over time, they
+might be released individually and a lot more often than these traditional systems.
+
+Keeping track of what is installed where becomes quite a challenge if the number of
+components and targets grows, and this is where Apache ACE comes in.
+
+Apache ACE is a software distribution framework. It is written as a set of OSGi components
+and consists of three major subsystems:
+
+1. dependency management, which handles the complexity of managing the dependencies
+between component, aggregating them into features and distributions and associating those
+to targets;
+2. deployment management, which ensures that the right components get installed onto the
+right targets in a robust and scalable way;
+3. feedback management, which collects life cycle feedback on the target and aggregates
+that on a central server.
+
+A typical topology consists of:
+
+* a server, holding the components and their metadata;
+* multiple target systems, which all connect to the server;
+* a client, usually a web browser, on which the user interacts with the server.
+
+The Apache ACE software, which consists of a set of OSGi bundles, gets deployed on a
+server. A target can be any OSGi framework (Apache Felix, Equinox or Knopflerfish) with
+the Apache ACE management agent installed. This agent will connect to the server, identify
+itself and poll for updates.
+
Propchange: ace/site/trunk/content/docs/history-and-background.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/relay_functional_overview.png
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/relay_functional_overview.png?rev=1641501&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/docs/relay_functional_overview.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: ace/site/trunk/content/docs/release-guide.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/release-guide.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/release-guide.mdtext (added)
+++ ace/site/trunk/content/docs/release-guide.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,144 @@
+Title: Release Guide
+
+Apache ACE is an open source project, and as such its only official releases are source
+releases. For convenience we also provide binaries. This document describes how to do a
+source release. It is based on the [Release FAQ](http://www.apache.org/dev/release.html).
+
+## Prerequisites
+
+To create a release you *must*:
+
+* Be a committer in the Apache ACE project;
+* Have Ant installed on your system;
+* Have Subversion installed on your system;
+* Have gpg installed on your system;
+* Have a public key added to the [keys file](http://www.apache.org/dist/ace/KEYS).
+
+Before you can start staging a release candidate, you must:
+
+* make sure there are no dependencies on snapshots/unreleased versions;
+* double check that the version you want to create is correctly filled in in <tt>build/build.xml</tt>;
+* create a tagged version of the sources in preparation of the release candidate.
+
+Creating a tagged version of the sources can be done directly through svn:
+
+ :::sh
+ $ svn copy https://svn.apache.org/repos/asf/ace/trunk/ https://svn.apache.org/repos/asf/ace/releases/X.Y.Z -m "Release X.Y.Z"
+
+## Staging a release candidate
+
+Staging a release starts by checking out a tagged version of the sources:
+
+ :::sh
+ $ svn co https://svn.apache.org/repos/asf/ace/releases/X.Y.Z ace-X.Y.Z
+
+The next step is to build the software and create the archives:
+
+ :::sh
+ $ cd ace-X.Y.Z/build
+ $ ant
+ $ ant package
+
+Then you sign archives by invoking the following target:
+
+ :::sh
+ $ ant sign
+
+you can upload the archives and the signatures to our development area, which we use to
+stage this release candidate. This development area can be found at
+<tt>https://dist.apache.org/repos/dist/dev/ace</tt> and adding files to it can be done
+using "svnpubsub" which is taken care of by the following target:
+
+ :::sh
+ $ ant commit-to-staging
+
+## Voting on the release
+
+Start a vote on the dev@ace.apache.org list, for example (be sure to replace
+<tt>X.Y.Z</tt> with the *correct* version!):
+
+ To: "Apache ACE developers list" <de...@ace.apache.org>
+ Subject: [VOTE] Release ACE version X.Y.Z
+
+ The source code of Apache ACE version X.Y.Z is available,
+ along with an archive containing all dependencies and a
+ binary release for convenience. They can all be found in
+ our staging area here:
+ https://dist.apache.org/repos/dist/dev/ace/
+
+ You can use this UNIX script to download the release and
+ verify the checksums and signatures:
+ http://svn.apache.org/repos/asf/ace/trunk/etc/check_staged_ace.sh
+
+ Usage:
+ sh check_staged_ace.sh X.Y.Z
+
+ Please vote to approve this release:
+ [ ] +1 Approve the release
+ [ ] -1 Veto the release (please motivate)
+
+ This vote will be open for at least 72 hours.
+
+The formal requirements on [approving a release](http://www.apache.org/dev/release.html#approving-a-release) are:
+
+> Votes on whether a package is ready to be released use majority approval --
+i.e. at least three PMC members must vote affirmatively for release, and there
+must be more positive than negative votes. Releases may not be vetoed. Before
+voting +1 PMC members are required to download the signed source code package,
+compile it as provided, and test the resulting executable on their own
+platform, along with also verifying that the package contains the required
+contents.
+
+The list of PMC (and project) members can be found [on this
+page](http://ace.apache.org/get-involved/project-team.html).
+
+Wrap up the vote with an e-mail to the <tt>dev@ace.apache.org</tt> list again:
+
+ To: "Apache ACE developers list" <de...@ace.apache.org>
+ Subject: [RESULT] [VOTE] Release ACE version X.Y.Z
+
+ The vote has passed/failed with the following result:
+ +1 (binding): ...
+ +1 (non-binding): ...
+ -1: ...
+
+And, depending on the result, continue with either promoting or cancelling the release
+below.
+
+## Promoting the release
+
+Move the artifacts from the development area to the final release location at
+<tt>https://dist.apache.org/repos/dist/release/ace</tt> by invoking the following target:
+
+ :::sh
+ $ ant promote-to-release
+
+Now wait at least 24 hours to allow the release to be properly mirrored and then update
+the news and download page on the Apache ACE website and announce the release:
+
+ To: "Apache ACE users list" <us...@ace.apache.org>
+ Subject: [ANN] ACE version X.Y.Z released.
+
+ The Apache ACE team is proud to announce the release of ACE version X.Y.Z.
+
+ This release is available from our download page at:
+ http://ace.apache.org/downloads.html
+
+After announcing the release, please update the baseline bundles contained in
+trunk/cnf/releaserepo based on the released artifacts (remove old versions, keep only the
+latest one).
+
+Please also make sure that old releases are removed from
+https://dist.apache.org/repos/dist/release/ace (the ant task does not do that yet). Leave
+the KEYS file in place.
+
+
+## Cancelling the release
+
+Remove the artifacts from the development area:
+
+ :::sh
+ $ ant delete-from-staging
+
+We keep the tag in subversion for reference.
+
Propchange: ace/site/trunk/content/docs/release-guide.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/rest-api.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/rest-api.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/rest-api.mdtext (added)
+++ ace/site/trunk/content/docs/rest-api.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,193 @@
+Title: Client REST API
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Introduction
+====================
+To automate the interaction with ACE, you can use its REST client API. Typical use cases include the tight integration of ACE into your development or automated build process, or the creation of a custom user interface or integration.
+
+This is still a work in progress which you can track in ACE-151.
+
+Overview
+====================
+Before we dive into the various REST endpoints, let's start with an overview of how all of this works. Everything in ACE is an entity. For example, an artifact or a feature is an entity, but also the association between an artifact and a feature is. Entities have properties and tags. Properties are the "fixed" attributes that make up a specific type of entity. For example a feature has a name and a description. If you know the type of entity, its properties are also known. Tags on the other hand are attributes that a user can freely add and refer to.
+
+The following diagram shows the different entities that ACE knows:
+![alt text][1]
+
+
+For each entity we will now list and explain the properties:
+
+Artifact
+====================
+Artifacts contain the metadata for the different types of artifacts that can be provisioned to targets. Artifacts can be bundles, configuration data or any other type you've defined yourself.
+
+* artifactName
+* artifactDescription
+* url
+* mimetype
+* processorPid
+
+Since there are different types of artifacts, some properties depend on the actual type.
+
+For bundles:
+
+* Bundle-Name
+* Bundle-SymbolicName
+* Bundle-Version
+
+For configuration:
+
+* filename
+
+For other types, please consult the documentation about these types (specifically the classes that implement the interfaces in the org.apache.ace.client.repository.helper package).
+
+Artifact2Feature
+====================
+Associates artifacts to features. Associations have a left and right hand side. Both can be expressed as filter conditions, and both have a cardinality.
+
+* leftEndpoint
+* rightEndpoint
+* leftCardinality â defaults to 1
+* rightCardinality â defaults to 1
+
+Feature
+====================
+
+A feature is a grouping mechanism for artifacts. It is commonly used to group together a set of artifacts that together represent some kind of feature to the application.
+
+* name
+* description
+
+Feature2Distribution
+====================
+
+Associates features to distributions. Associations have a left and right hand side. Both can be expressed as filter conditions, and both have a cardinality.
+
+* leftEndpoint
+* rightEndpoint
+* leftCardinality â defaults to 1
+* rightCardinality â defaults to 1
+
+Distribution
+====================
+A feature is a grouping mechanism for features. It is commonly used to group together a set of features that together represent some kind of distribution. Distributions are the things you can associate with targets, so you can look at them as the licensable configurations of your software.
+
+* name
+* description
+
+Distribution2Target
+====================
+
+Associates distributions to targets. Associations have a left and right hand side. Both can be expressed as filter conditions, and both have a cardinality.
+
+* leftEndpoint
+* rightEndpoint
+* leftCardinality â defaults to 1
+* rightCardinality â defaults to 1
+
+Target
+====================
+A target receives the artifacts you provision to it. Most of the time, a target is an OSGi container and provisioning means you'll actually install the artifacts in the container, but there can be other types of targets (non-OSGi containers, or something completely different).
+
+* id
+* autoapprove
+
+A target also has specific state (see below for how that is returned):
+
+* registrationState â Unregistered, Registered
+* provisioningState â Idle, InProgress, OK, Failed
+* storeState â New, Unapproved, Approved
+* currentVersion
+* isRegistered
+* needsApproval
+* autoApprove
+* artifactsFromShop
+* artifactsFromDeployment
+* lastInstallSuccess
+
+Checkout and commit
+====================
+Similar to the web based UI, this API also works with the concept of checking out a copy to a local working area, altering it in that working area and then committing it back to the server.
+
+POST /work
+------------
+Creates a working copy for you, with its own ID, and redirects you to it. (For the contents of this working copy, see below.)
+
+Response:
+
+* 302 /work/ID
+
+DELETE /work/ID
+--------------
+Deletes the working copy. Signals you're done with it, without transferring the data back to the server.
+
+POST /work/ID
+------------
+Sets the working copy to be the current version. We keep track of whether you have based your copy on, and will reject the update if it is no longer the latest.
+
+Response:
+
+* 200
+* 409
+
+Repositories and objects
+==================
+Now you have a working copy, you can start working with it.
+
+GET /work/ID
+-------------
+Gets you a list of all repositories you can use. Should return: ["artifact", "feature", "distribution", "target", "artifact2feature", "feature2distribution", "distribution2target"]
+
+GET /work/ID/feature
+-------------
+Lists all feature IDs in the feature repository.
+
+POST /work/ID/feature
+-----------------
+Creates a new feature. In the post body, you can specify attributes and tags, for example: {attributes: {key: "value"}, tags: {key: "value"}}.
+
+Response:
+
+* 302 /work/ID/feature/FID
+* 400
+
+GET /work/ID/feature/FID
+-----------
+Returns a representation of the object, for example: {attributes: {key: "value"}, tags: {key: "value"}}. If you ask for a target, you will also get its state, so the result will be in the form: {attributes: {key: "value"}, tags: {key: "value"}, state: {key: "value"}}.
+
+PUT /work/ID/feature/FID
+-------------
+Updates the object with the JSON data you supply.
+
+Response:
+
+* 200
+* 400
+* 404
+
+DELETE /work/ID/feature/FID
+-----------
+Deletes the object.
+
+Response:
+
+* 200
+* 404
+
+
+ [1]: https://cwiki.apache.org/confluence/download/attachments/27822075/entities.png?version=1&modificationDate=1311923466000
\ No newline at end of file
Propchange: ace/site/trunk/content/docs/rest-api.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/setup-dev-environment.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/setup-dev-environment.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/setup-dev-environment.mdtext (added)
+++ ace/site/trunk/content/docs/setup-dev-environment.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,276 @@
+Title: Setting up a development environment
+
+Everything you need to know to start developing Apache ACE can be found here.
+
+## Obtaining the sources
+
+There are two ways to obtain a copy of the source code. You can either download one of the
+source releases, or checkout the code from subversion.
+
+### Download the sources
+
+Point your browser to: http://ace.apache.org/download.html
+
+On that page you will find, amongst others, a link to the latest released sources, plus an
+archive containing all binary third-party dependencies. The page will automatically select
+a download mirror close to you. Download both the source and dependencies archive and then
+type:
+
+ :::sh
+ $ unzip apache-ace-1.0.0-src.zip
+ $ unzip apache-ace-1.0.0-deps.zip
+
+Note that when unzipping the second archive, you will get some warnings about overlapping
+files. Those are the required NOTICE and LICENSE files, which are in the same location in
+both archives. Just overwriting them is fine.
+
+### Checkout from subversion
+
+ :::sh
+ $ svn co http://svn.apache.org/repos/asf/ace/trunk apache-ace
+
+In both cases you end up with a copy of the source code.
+
+
+## Building the sources
+
+There are two ways to build the sources. You can either run a command line build or use
+Eclipse with Bndtools to build everything. If you want to actively start developing, we
+strongly recommend you use Eclipse with Bndtools as this is by far the most convenient way
+to build and run Apache ACE within a development environment.
+
+### Eclipse with Bndtools
+
+#### Prerequisites
+
+For developing ACE using Eclipse, you need:
+
+* A recent Java JDK, at least [Java 6](http://www.oracle.com/technetwork/indexes/downloads/index.html);
+* A recent Eclipse, for example, [Eclipse Juno](http://www.eclipse.org/downloads/) with the following plugins:
+* [Subclipse](http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA);
+* [BndTools](http://bndtools.org/installation.html);
+* [TestNG](http://testng.org/doc/download.html).
+
+For building or exporting the compiled artifacts of ACE without Eclipse, you only need
+[Apache ANT](http://ant.apache.org/) version 1.8+ installed.
+
+#### Eclipse set up
+
+When firing up Eclipse, make sure to either create a new workspace and check out the
+sources according to the instructions below, or choose the root folder where you have
+previously checked out or extracted your copy of the sources. This is important, as
+otherwise Bndtools will not function correctly.
+
+##### Checking out the latest sources
+
+If you created a new workspace above, you need to grab the latest sources from ACE's
+subversion repository. To do this, open up the "SVN Repository Exploring" perspective, and
+add the following URL as new SVN repository using the yellow add-icon in the "SVN
+Repositories" view:
+
+ https://svn.apache.org/repos/asf/ace/trunk/
+
+After this, expand the newly created tree node named after the SVN URL, and select all
+**individual** projects underneath. *Note: do **not** (only) select the root node, as
+this won't let you properly import the individual projects.*
+
+Right click on the selected (sub)projects, and choose "Checkoutâ¦" from the context menu.
+Leave all default settings as-is and click "finish". Now relax and wait until the checkout
+is completed, and all projects are imported into your workspace.
+
+Switching back to the "Bndtools" perspective should give you a long list of imported
+projects.
+
+##### Importing existing projects
+
+If you created a workspace in a folder that already contained the sources, you need to
+import these projects into the workspace. From the main menu in Eclipse, choose: "File
+-> Import..." and then select "General -> Existing projects into workspace..." and
+select your workspace folder. A list of projects should show up now. Import them all, wait
+until Eclipse has built the project and you're ready to start.
+
+##### Coding guidelines
+
+If you want to develop for ACE, you might want to import the code templates and formatter
+rules for ACE. The formatter can be found in the `etc` folder in subversion, and you can
+import it into Eclipse as your default formatter for this workspace.
+
+#### Running & debugging
+
+One of the benefits of the migration to BndTools is that we can now directly run ACE from
+Eclipse with almost zero effort. In fact, it is even possible to directly debug or profile
+ACE from Eclipse. By convention, all runnable projects start with "run-" and contain a
+".bndrun" file.
+
+##### ACE server
+
+To run or debug the ACE server, you open up the "<tt>server.bndrun</tt>" file in the
+"run-server" project. This will present you with a view in which you can directly choose
+to run it (use "Run OSGi") or debug it (use "Debug OSGi"). Alternatively, you can right
+click on "server.bndrun" and choose either "Run As -> Bnd OSGi Run Launcher" or "Debug
+As -> Bnd OSGi Run Launcher".
+
+##### ACE obr
+
+To run or debug the ACE obr, you open up the "<tt>obr.bndrun</tt>" file in the "run-obr"
+project. This will present you with a view in which you can directly choose to run it (use
+"Run OSGi") or debug it (use "Debug OSGi"). Alternatively, you can right click on
+"obr.bndrun" and choose either "Run As -> Bnd OSGi Run Launcher" or "Debug As -> Bnd
+OSGi Run Launcher".
+
+##### ACE client
+
+To run or debug the ACE client, you open up the "<tt>client.bndrun</tt>" file in the
+"run-client" project. This will present you with a view in which you can directly choose
+to run it (use "Run OSGi") or debug it (use "Debug OSGi"). Alternatively, you can right
+click on "client.bndrun" and choose either "Run As -> Bnd OSGi Run Launcher" or "Debug
+As -> Bnd OSGi Run Launcher".
+
+##### ACE server-allinone
+
+To run or debug the "all in one" ACE server, you open up the
+"<tt>server-allinone.bndrun</tt>" file in the "run-server-allinone" project. This will
+present you with a view in which you can directly choose to run it (use "Run OSGi") or
+debug it (use "Debug OSGi"). Alternatively, you can right click on
+"server-allinone.bndrun" and choose either "Run As -> Bnd OSGi Run Launcher" or "Debug
+As -> Bnd OSGi Run Launcher".
+
+##### ACE target
+
+You can also directly run a target from Eclipse. Doing this is almost equal as running the
+ones described in the previous sections. The only difference is that for running a target,
+you need to use the "<tt>target.bndrun</tt>" file from the "run-target" project.
+
+##### Unit tests
+
+ACE uses TestNG for its unit tests. To run a single test or a package of tests, use "Run
+As -> TestNG Test" or "Debug As -> TestNG Test".
+
+##### Integration tests
+
+The integration tests of ACE are placed in separate projects that are -by convention-
+named with a '<tt>.itest</tt>' suffix. These integration tests use BndTools to get an OSGi
+framework up and running. To run one or all integration tests, use "Run As -> OSGi
+JUnit Test" or "Debug As -> OSGi JUnit Test".
+
+### Command line build
+
+#### Prerequisites
+
+For developing ACE using Ant, you need:
+
+* A recent Java JDK, at least [Java 6](http://www.oracle.com/technetwork/indexes/downloads/index.html);
+* [Apache ANT](http://ant.apache.org/) version 1.8+.
+
+#### Building
+
+The command line build for Apache ACE is based on Ant, and generated automatically when
+using the Bndtools plugin in Eclipse.
+
+The build is structured as a flat hierarchy of projects, and you can go into any of these
+projects to build just that project and its dependencies. There are two special projects:
+
+1. `cnf` -- Which is collection of repositories that contain all the required dependencies
+for building and running Apache ACE;
+2. `build` -- A project that depends on all other projects and is used to build
+everything.
+
+So, to build Apache ACE, we issue the following commands:
+
+ :::sh
+ $ cd build
+ $ ant
+
+In the end, this leaves us with a set of bundles (in the <tt>generated</tt> folder of each
+project).
+
+The following targets are available:
+
+* <tt>clean</tt> -- Cleans up any files in the current project that were generated during a build;
+* <tt>build</tt> -- Build the current project;
+* <tt>test</tt> -- Run the integration tests in the *current* project;
+* <tt>testng</tt> -- Run the unit tests in the *current* project;
+* <tt>deepclean</tt> -- Cleans up any files in the current project and all its dependencies;
+* <tt>deeptestng</tt> -- Runs the unit tests in the current project and all its dependencies;
+* <tt>deeptest</tt> -- Runs the integration tests in the current project and all its dependencies.
+
+There actually are a few more, but these are the most important ones.
+
+## How to...
+
+### ...use my favorite IDE (not Eclipse)?
+
+Unfortunately, the easy answer is "no". Until somebody ports Bndtools to your favorite
+IDE, you either have to use Eclipse, or a combination of your IDE and manual builds using
+Ant (though not recommended). If you insist, please do make sure you manually generate the
+proper metadata for Eclipse.
+
+### ...build this thing in Eclipse?
+
+Normally, you don't. Seriously. If "Build Automatically" is enabled, as soon as you hit
+save after changing a line of code, BndTools will automatically build your bundle for you.
+In fact, if your server if already running, Bndtools will even redeploy all changed
+bundles to it automatically.
+
+### ...get rid of all those red crosses in Eclipse?
+
+If Eclipse complaints about missing test libraries, you probably forgot to install the
+TestNG plugin. If this plugin is installed, it will automatically cause your projects to
+get the required dependency to the TestNG library. Without this plugin, Eclipse won't have
+the required library and fails to compile the code correctly.
+In case you are importing the projects into Eclipse for the first time, it takes a while
+and a couple of builds to get rid of all build errors. If the problem does *not* go away,
+please drop a line on the [mailing lists](/get-involved/mailing-lists.html) to get
+additional help.
+
+### ...create a distributable archive
+
+The next step is to create an archive for the server, so we end up with something we can
+actually run:
+
+ :::sh
+ $ cd build
+ $ ant package-bin
+
+Now, in the generated folder, an archive will have been created. You can unzip this
+archive, which should expose a couple of subfolders with the same names as the runnable
+projects that you can go into and run. You can start the "all in one" server like this:
+
+ :::sh
+ $ cd apache-ace-1.0.0-bin
+ $ unzip apache-ace-1.0.0-bin/.zip
+ $ cd server-allinone/
+ $ java -jar server-allinone.jar
+
+For other projects, the steps are similar to this: just go into the correct folder and
+launch the jar file.
+
+### ...add an OSGi bundle
+
+The easiest way to add an OSGi bundle, is to drag it onto the "Local Repository" entry in
+the "Repositories" view, or to use the "Add files to repository" toolbar icon. Bndtools
+will analyze the files you try to add and show their metadata if they're indeed valid
+bundles.
+
+The bundles will end up in the local repository inside the <tt>cnf</tt> project.
+
+### ...add a Java library
+
+If you want to add a library that does not contain any OSGi metadata, you can follow the
+steps below to add it to the "Library Repository" so it can be used in all other projects
+within Apache ACE. If your library does have sensible OSGi metadata, please follow the
+"...add an OSGi bundle" instructions above.
+
+1. Copy the library to the right location. The jar file for the library should be copied
+to the following location: <tt>cnf/lib/foo/foo-1.0.0.jar</tt>. Note that the directory
+name should be equal to the basename of the added JAR file, that is, everything *before*
+the version-string of the JAR;
+2. Update the `repository.xml`. After making changes to anything in <tt>cnf/lib/</tt> you
+need to update the index file that describes the contents of the repository. To do this
+enter the following commands:
+
+ :::sh
+ $ cd cnf
+ $ ant build
+ $ java -cp bin org.apache.ace.bnd.LibraryIndexer
+
Propchange: ace/site/trunk/content/docs/setup-dev-environment.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/shell-api.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/shell-api.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/shell-api.mdtext (added)
+++ ace/site/trunk/content/docs/shell-api.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,108 @@
+Title: Client Shell API
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Introduction
+====================
+To script the interaction with ACE, you can use its shell based client API. Typical use cases include the tight integration of ACE into your development or automated build process, the creation of a custom user interface, or interactive use for those who prefer a shell over a GUI.
+
+The shell commands extend the standardized OSGi shell, using the GoGo implementation from Apache Felix. This page does not aim to give an overview of all commands available in that shell, so please consult the documentation of the GoGo shell itself in case you're not familiar with it.
+
+Overview
+====================
+Before we dive into the various shell commands, let's start with an overview of how all of this works. Everything in ACE is an entity. For example, an artifact or a feature is an entity, but also the association between an artifact and a feature is. Entities have properties and tags. Properties are the "fixed" attributes that make up a specific type of entity. For example a feature has a name and a description. If you know the type of entity, its properties are also known. Tags on the other hand are attributes that a user can freely add and refer to.
+
+Sessions and Workspaces
+=======================
+The client, independent of whether you're using the WebUI, REST or shell, always works in the same way. You start out by creating a session or workspace that you can then start editing. Once you're happy with your changes, you commit them back to the server.
+
+Creating a session in the shell is done like this:
+
+ w = (cw)
+
+The "cw" (create workspace) command checks out and returns a new workspace. We assign that result to a variable, because
+all our subsequent commands operate on the workspace. Optionally, when creating the workspace, we can provide several parameters:
+
+ w = (cw [showunregisteredtargets=false])
+ w = (cw european dutch dutch)
+ w = (cw european dutch dutch [showunregisteredtargets=false])
+
+The three names (european dutch dutch) are names of repositories. ACE supports a flexible multi-tenancy mechanism that allows you to specify customer or tenant names for all the different repositories. In this example, we checkout a european store repository, and a dutch target and deployment repository. Most people will probably start out with a single workspace with default repositories.
+
+The map (maps are entered like this: [key1=val1 key2=val2 key3=val3]) contains an optional set of configuration properties for the workspace. At the moment, the only property there is is "showunregisteredtargets" which determines if the workspace will contain targets that have not been registered. It finds those by scanning all audit logs. By default, they are included but in some use cases you might not want them to be visible. In such cases, rather than filtering them out of your results, you can completely remove them, which saves quite a bit of processing time as well.
+
+When you're done with your workspace, you can clean it up like this:
+
+ rw $w
+
+This will remove the workspace from memory. Note that any changes will be lost, unless you commit the workspace first:
+
+ $w commit
+
+This is actually not a shell command we explicitly created. Instead, the shell is smart enough to scan an instance (our workspace $w) for methods and tries to invoke those. It also parses arguments as we will soon see.
+
+Let's start creating some entities:
+
+ $w cf feature-base
+ $w cd dist-core
+ $w cf2d "(name=feature-base)" "(name=dist-core)"
+
+This gives us a feature, a distribution and the association between the two. Associations have a left and right hand side, and both are OSGi filters. This means you can create quite complex associations, but in this case we use a simple condition that matches only a single feature and distribution. If you want to see what you've created, you can list all entities of a certain type like this:
+
+ $w lf
+ $w ld
+ $w lf2d
+
+Lists all features, distributions and feature to distribution associations. These list commands accept a filter condition as well:
+
+ $w lf "(name=feature-*)"
+
+Lists all features whose name start with "feature-". Let's proceed by adding a bundle. Bundles are a specific type of artifact and there are several ways to add them. The easiest one, most of the time, is:
+
+ $w ca file:///path/to/some/bundle.jar true
+
+This will create an artifact, using the URL you specified. Because the second parameter was set to true, it will upload the artifact from that URL to the OBR. It will also extract all necessary metadata from the artifact: it recognizes the type and then uses type specific extraction mechanisms.
+
+If you really want to, you can also create the bundle yourself and specify all the metadata manually:
+
+ $w ca [mimetype=application/vnd.osgi.bundle artifactName=org.foo Bundle-Name=org.foo Bundle-SymbolicName=org.foo Bundle-Version=1.0.0 url=http://localhost:8080/obr/org/foo/org.foo-1.0.0.jar processorPid=]
+ $w ca2f "(Bundle-SymbolicName=org.foo)" "(name=feature-base)"
+
+This creates the bundle. The "url" is an important attribute as it tells ACE where to get the bundle from. In this example we assume it can already be found in the OBR at that location. We also create an association. On the bundle side, we use a filter that only specifies the symbolic name of the bundle. So what happens if there is more than one version of such a bundle available? To understand that, we need to explain a few more things about associations.
+
+First of all, assocations have a cardinality for both sides. If you don't specify the cardinality, it defaults to "1:1". So what happens if you specify a filter that returns more than one entity? Two things. First of all, the list of entities is sorted in an order that is specific to the type of entity. Bundles are sorted by version, highest first. Finally, the cardinality is used to determine how many entities from the list to return. So in this case, from all the bundles with the same symbolic name, the bundle with the highest version is selected.
+
+You can use this to create features that automatically update to the highest version of a bundle, or if you're more specific, are fixed to a version or version range. Combined with semantic versioning this gives you a powerful way to for example create a feature where bugfixes or backward compatible changes will automatically be upgraded, but major changes require human intervention.
+
+Let's proceed to create a target:
+
+ $w ct target-1
+ $w cd2t "(name=dist-core)" "(id=target-1)"
+
+This creates the target and associates it with the "dist-core" distribution.
+
+Deleting entities is also quite easy. You first need to get hold of the entity you want to delete though, which can be done like this:
+
+ targetlist = ($w lt "(id=target-1)")
+
+This gives you a list of targets, but since the filter is very specific, the list will only contain one entity. The shell now has a helper command to fetch the first item from the list:
+
+ t1 = (first $targetlist)
+ $w dt $t1
+
+Fetches the first and only target in the list and assigns it to a variable called "t1". Subsequently deletes the target from the workspace. Deleting other entities is done in a similar way.
+
Propchange: ace/site/trunk/content/docs/shell-api.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/simple-workflow.png
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/simple-workflow.png?rev=1641501&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/docs/simple-workflow.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: ace/site/trunk/content/docs/test-script.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/test-script.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/test-script.mdtext (added)
+++ ace/site/trunk/content/docs/test-script.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,31 @@
+Title: Test Script
+
+Besides all our automated tests, sometimes it is useful to run some tests by hand to get a feel for the performance of Apache ACE and tweak it for specific scenarios. To aid in setting up and running such tests, an Ant script was made that allows you to:
+
+1. Configure it to create a runnable server, a collection of targets or both.
+2. Run every configured node.
+3. Cleanup afterwards.
+
+Typical use cases include running a set of targets and a server on the same box, or having two or more boxes and distributing server and (groups of) targets over both. The script, which is located in the `ace-test` project folder, assumes you have a full checkout of ACE and that you have actually already built the code (`mvn -DskipTests=true clean install` or something similar). It also assumes you have a recent version of Ant on your machine.
+
+Before using the script, there are several variables that you can configure that influence its behaviour:
+
+* with-server - when defined, will run an ACE server;
+* with-targets - when defined, will run a number of targets;
+* targets - a comma separated list of target names ("target-" will be used as prefix for all of them);
+* server-host - the discovery URL for the server to use with the targets
+* version - the ACE version to use (should match whatever version of the code you checked out).
+
+To run:
+
+1. `ant unzip` will unzip all required code into folders under the current directory;
+2. `ant run` will run all nodes (and at least on Linux and Mac OS X stop them again when you hit Ctrl-C);
+3. `ant rm` will delete all folders and files created in steps 1 and 2.
+
+For example, to run the ACE management server with 10 targets, we should do the following:
+
+ :::sh
+ [localhost:~/]$ ant -Dtargets=1,2,3,4,5,6,7,8,9,10 unzip run
+ ...(CTRL+C)...
+ [localhost:~/]$ ant -Dtargets=1,2,3,4,5,6,7,8,9,10 rm
+
Propchange: ace/site/trunk/content/docs/test-script.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: ace/site/trunk/content/docs/use-cases/index.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/index.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/index.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/index.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,34 @@
+Title: Use Cases
+
+The view below shows all the major use cases of Apache ACE. If you scroll down
+you will also see a list of use cases, described in more detail when you click on
+a use case.
+
+<object data="usecasesview.svg" type="image/svg+xml" class="span12" height="1898"></object>
+
+List
+----
+
+* [UC-01 Checkout](uc-01.html)
+* [UC-02 Commit](uc-02.html)
+* [UC-03 Resolve merge conflict](uc-03.html)
+* [UC-04 Check for update](uc-04.html)
+* [UC-05 Send audit log data](uc-05.html)
+* [UC-06 Synchronize](uc-06.html)
+* [UC-07 Add artifact](uc-07.html)
+* [UC-08 Add artifact from external location](uc-08.html)
+* [UC-09 Add artifact from managed location](uc-09.html)
+* [UC-10 Add artifact from filesystem](uc-10.html)
+* [UC-11 Add artifact from OBR](uc-11.html)
+* [UC-12 Associate](uc-12.html)
+* [UC-13 Associate artifact to distribution](uc-13.html)
+* [UC-14 Associate distribution to target](uc-14.html)
+* [UC-15 Create](uc-15.html)
+* [UC-16 Create distribution](uc-15.html)
+* [UC-17 Create target](uc-15.html)
+* [UC-18 Review audit log](uc-18.html)
+* [UC-19 Approve version](uc-19.html)
+* [UC-20 Manage users](uc-20.html)
+* [UC-21 Manage rights](uc-21.html)
+* [UC-22 Manage certificates](uc-22.html)
+* [UC-23 Manage system topology](uc-23.html)
Added: ace/site/trunk/content/docs/use-cases/uc-01.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-01.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-01.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-01.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,17 @@
+Title: Use Case 01 - Checkout
+
+Check out data from a repository.
+
+## Flow
+
+### Basic Flow
+
+1. Editor asks discovery service for a location of a server for a certain repository.
+2. Editor contacts the repository to ask for a list of versions.
+3. Editor checks out the latest version of the repository.
+
+### Alternative Flows
+
+* Server cannot be found.
+* Repository does not exist.
+* Latest version could not be checked out.
Added: ace/site/trunk/content/docs/use-cases/uc-02.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-02.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-02.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-02.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,21 @@
+Title: Use Case 02 - Commit
+
+Check out data from a repository.
+
+## Flow
+
+### Basic Flow
+
+1. Editor asks discovery service for a location of a server for the repository.
+2. Editor sends the modified repository the server, together with the version number this edit was based on.
+3. Server reports back that the commit was successful.
+
+### Alternative Flows
+
+* Server cannot be found.
+* Repository does not exist.
+* Commit failed because of a merge conflict.
+
+## Details
+
+When a commit fails because of a merge conflict, the client is expected to check out the newly added version and (with or without interaction from a user) merge all changes and then try again. This is explained in [UC-03 Resolve merge conflict](uc-03.html).
Added: ace/site/trunk/content/docs/use-cases/uc-03.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-03.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-03.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-03.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,23 @@
+Title: Use Case 03 - Resolve merge conflict
+
+Resolve merge conflicts and commit an updated version to a repository.
+
+This use case extends [commit](uc-02.html).
+
+## Flow
+
+### Basic Flow
+
+When the UC commit scenario fails because someone else committed a version while you were editing yours, the flow continues like this:
+
+1. Editor fetches the latest version and now has three versions locally: the original version he started with, the working copy he is trying to commit and this latest version.
+2. Editor reviews the three way diff and updates the working copy.
+3. Editor tries to commit the working copy again, now referencing the latest version again. This is the normal commit use case.
+
+### Alternative Flows
+
+* None.
+
+## Details
+
+This use case interacts with the commit use case and the user can go back and forward between the two as long as new merge conflicts pop up.
Added: ace/site/trunk/content/docs/use-cases/uc-04.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-04.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-04.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-04.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,24 @@
+Title: Use Case 04 - Check for update
+
+Check for an updated set of artifacts for a gateway.
+
+## Flow
+
+### Pre-conditions
+
+A target with an OSGi framework and our management agent.
+
+### Basic flow
+
+1. Target retrieves its own identity.
+2. Target asks the discovery service for the location of a server.
+3. Target polls the server for a list of versions.
+4. If there is a version that is newer than the currently installed version, poll for this update.
+5. Install the update.
+6. Report back to the server.
+
+### Alternative flows
+
+* If no server can be found, do nothing.
+* If there is no newer version, do nothing.
+* If the update cannot be installed, roll back to the previous version.
Added: ace/site/trunk/content/docs/use-cases/uc-05.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-05.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-05.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-05.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,16 @@
+Title: Use Case 05 - Send audit log data
+
+Sends new audit log data to a server.
+
+## Flow
+
+### Basic flow
+
+1. The target asks the discovery protocol for the location of the server.
+2. The target queries the server for the audit log entries it already has.
+3. The target sends any new entries to the server.
+
+### Alternative flows
+
+* If the server cannot be found, nothing happens.
+* If the server already has all the entries, nothing happens.
Added: ace/site/trunk/content/docs/use-cases/uc-06.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-06.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-06.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-06.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,17 @@
+Title: Use Case 06 - Synchronize
+
+Synchronize a local repository with a remote one.
+
+## Flow
+
+### Basic Flow
+
+1. Relay server asks discovery service for a location of a server for a certain repository.
+2. Relay server contacts the repository to ask for a list of versions.
+3. Relay server downloads missing versions of the repository.
+
+### Alternative Flows
+
+* Server cannot be found.
+* Repository does not exist.
+* Version could not be downloaded.
Added: ace/site/trunk/content/docs/use-cases/uc-07.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-07.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-07.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-07.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,16 @@
+Title: Use Case 07 - Add artifact
+
+Add a new artifact to the system.
+
+## Flow
+### Basic flow
+
+1. The user selects an artifact to add to the system.
+2. The system checks if the artifact is of a type it understands.
+3. The system checks if the artifact already exists or not.
+4. The system adds the artifact.
+
+### Alternative flows
+
+* If the artifact is of an unknown type, it is refused.
+* If the artifact already exists, the system notifies the user and denies the artifact.
Added: ace/site/trunk/content/docs/use-cases/uc-08.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-08.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-08.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-08.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,18 @@
+Title: Use Case 08 - Add artifact from external location
+
+Adds a new artifact from an external location. An external location is a location you cannot or should not link to (because it is volatile).
+
+This use case extends [Add artifact](uc-07.html).
+
+## Flow
+### Basic flow
+
+The basic flow is the same as for Add artifact, but at the end, some additional steps are necessary:
+
+1. The system adds the artifact itself to a repository that matches the artifact type.
+2. A reference from that repository to the newly stored artifact is generated.
+
+### Alternative flows
+
+* If there is no repository that matches the artifact type, it cannot be added.
+* If the user has no permission to add artifacts to that repository, the artifact cannot be added.
Added: ace/site/trunk/content/docs/use-cases/uc-09.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-09.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-09.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-09.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,18 @@
+Title: Use Case 09 - Add artifact from managed location
+
+Adds an artifact from a managed location. A managed location is a location that can be referenced with a URL.
+
+This use case extends [Add artifact](uc-07.html).
+
+## Flow
+
+### Basic flow
+
+The basic flow is similar as for Add artifact, but:
+
+* At the start, the user selects an existing artifact from a list of artifacts in a repository.
+* At the end, a reference from that repository to the artifact is generated.
+
+### Alternative flows
+
+* None.
\ No newline at end of file
Added: ace/site/trunk/content/docs/use-cases/uc-10.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-10.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-10.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-10.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,15 @@
+Title: Use Case 10 - Add artifact from filesystem
+
+Adds a new artifact from the local filesystem.
+
+This use case extends [Add artifact from external location](uc-08.html).
+
+## Flow
+
+### Basic flow
+
+The basic flow is the same as for Add artifact from external location, but more specifically, the artifact is retrieved from the local filesystem.
+
+### Alternative flows
+
+* If the artifact cannot be loaded, it cannot be added.
Added: ace/site/trunk/content/docs/use-cases/uc-11.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-11.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-11.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-11.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,15 @@
+Title: Use Case 11 - Add artifact from OBR
+
+Adds a new bundle from an OSGi Bundle Repository.
+
+This use case extends [Add artifact from managed location](uc-09.html).
+
+## Flow
+
+### Basic flow
+
+The basic flow is the same as for UC Add artifact from managed location, but more specifically we select a bundle from an OBR.
+
+### Alternative flows
+
+* None.
Added: ace/site/trunk/content/docs/use-cases/uc-12.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-12.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-12.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-12.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,15 @@
+Title: Use Case 12 - Associate
+
+Creates a new association.
+
+## Flow
+
+### Basic flow
+
+1. User selects two entities.
+2. User creates an association between the two.
+3. User enters additional data for the association.
+
+### Alternative flows
+
+* None.
Added: ace/site/trunk/content/docs/use-cases/uc-13.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-13.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-13.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-13.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,19 @@
+Title: Use Case 13 - Associate artifact to distribution
+
+Associates an artifact to a distribution.
+
+This use case extends [Associate](uc-12.html).
+
+## Flow
+
+### Basic flow
+
+The actor in this case is the release manager. The basic flow remains the same except for the fact that the association is always made between an artifact and a distribution and there is no additional data.
+
+### Alternative flows
+
+* None.
+
+## Details
+
+Our current implementation has artifacts, features and licenses. The theory remains the same.
Added: ace/site/trunk/content/docs/use-cases/uc-14.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-14.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-14.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-14.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,15 @@
+Title: Use Case 14 - Associate distribution to target
+
+Associates a distribution to a target.
+
+This use case extends [Associate](uc-12.html).
+
+## Flow
+
+### Basic flow
+
+The actor in this case is the license manager. The basic flow remains the same except for the fact that the association is always made between a distribution and a target and there is no additional data.
+
+### Alternative flows
+
+* None.
Added: ace/site/trunk/content/docs/use-cases/uc-15.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-15.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-15.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-15.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,15 @@
+Title: Use Case 15 - Create
+
+Creates a new object.
+
+## Flow
+
+### Basic flow
+
+1. User creates the object and names it.
+2. User enters additional data for the object.
+
+### Alternative flows
+
+* Creation fails if name is not unique.
+
Added: ace/site/trunk/content/docs/use-cases/uc-16.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-16.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-16.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-16.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,15 @@
+Title: Use Case 16 - Create distribution
+
+Creates a new distribution.
+
+## Flow
+
+### Basic flow
+
+Same as Create, but with specific attributes for a distribution.
+
+### Alternative flows
+
+* None.
+
+
Added: ace/site/trunk/content/docs/use-cases/uc-17.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-17.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-17.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-17.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,15 @@
+Title: Use Case 17 - Create target
+
+Creates a new target.
+
+## Flow
+
+### Basic flow
+
+Same as Create, but with specific attributes for a target.
+
+### Alternative flows
+
+* None.
+
+
Added: ace/site/trunk/content/docs/use-cases/uc-18.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-18.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-18.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-18.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,14 @@
+Title: Use Case 18 - Review audit log
+
+Review the audit log of a target.
+
+## Flow
+
+### Basic flow
+
+1. User selects two target and opens the audit log.
+2. User reviews the data in the log.
+
+### Alternative flows
+
+* None.
Added: ace/site/trunk/content/docs/use-cases/uc-19.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-19.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-19.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-19.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,29 @@
+Title: Use Case 19 - Approve version
+
+Approve a new versioned set of artifacts for a target.
+
+## Flow
+
+### Pre-conditions
+
+The target must be in the "new" state, meaning there are updates for it.
+
+### Basic flow
+
+1. The target operator reviews the details of the updates.
+2. When he is satisfied, he approves those changes.
+3. A new version of the software for that target is generated.
+4. The target is put in "approved" state.
+
+### Post-conditions
+
+The target is in the "approved" state.
+
+### Alternative flows
+
+* After reviewing the changes, the target operator decides not to approve them. The target then remains in the "new" state.
+
+## Details
+
+* When a target is configured to "auto-approve" updates, this whole use case takes place without human interaction from the target operator.
+* The use case purposely does not describe how a new version number for the target is generated, because that is a configurable aspect (which might or might not include user interaction).
Added: ace/site/trunk/content/docs/use-cases/uc-20.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-20.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-20.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-20.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,3 @@
+Title: Use Case 20 - Manage users
+
+Manages user accounts and their roles.
Added: ace/site/trunk/content/docs/use-cases/uc-21.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-21.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-21.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-21.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,3 @@
+Title: Use Case 21 - Manage rights
+
+Manages the rights associated with the different roles in the system.
Added: ace/site/trunk/content/docs/use-cases/uc-22.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-22.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-22.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-22.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,4 @@
+Title: Use Case 22 - Manage certificates
+
+Manages certificates for the system, acting as a certificate authority for the whole eco-system.
+
Added: ace/site/trunk/content/docs/use-cases/uc-23.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/uc-23.mdtext?rev=1641501&view=auto
==============================================================================
--- ace/site/trunk/content/docs/use-cases/uc-23.mdtext (added)
+++ ace/site/trunk/content/docs/use-cases/uc-23.mdtext Mon Nov 24 22:42:00 2014
@@ -0,0 +1,3 @@
+Title: Use Case 23 - Manage system topology
+
+Manage the topology of the provisioning system. Apache ACE supports many different topologies with servers, relay servers, repositories, clients and targets.
Added: ace/site/trunk/content/docs/use-cases/usecasesview.svg
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/docs/use-cases/usecasesview.svg?rev=1641501&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/docs/use-cases/usecasesview.svg
------------------------------------------------------------------------------
svn:mime-type = image/svg+xml