Author: marrs
Date: Mon Mar 5 14:46:17 2012
New Revision: 1297077
URL: http://svn.apache.org/viewvc?rev=1297077&view=rev
Log:
First part of the architecture document.
Modified:
ace/site/trunk/content/dev-doc/architecture.mdtext
Modified: ace/site/trunk/content/dev-doc/architecture.mdtext
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/architecture.mdtext?rev=1297077&r1=1297076&r2=1297077&view=diff
==============================================================================
--- ace/site/trunk/content/dev-doc/architecture.mdtext (original)
+++ ace/site/trunk/content/dev-doc/architecture.mdtext Mon Mar 5 14:46:17 2012
@@ -1 +1,125 @@
Title: Architecture
+
+Introduction
+============
+
+Apache ACE is a system that can be used to provision software to OSGi based
and other targets. It manages the life cycle of bundles and provides a
controlled, centralized way to install, update and uninstall software and
related artifacts such as configuration data, native code and device firmware.
+
+### Purpose and scope
+
+The purpose of this document is to provide a comprehensive overview of the
software architecture of the system. It uses a number of different views to
depict the important aspects of the system and captures and conveys the
significant architectural decisions which have been made on the system.
+
+It serves three purposes:
+
+1. *Abstraction of the system.* The architecture provides a relatively small,
intellectually graspable model of how the system is structured and how
components interact.
+2. *Mutual communication.* The model described here forms the common basis for
all of the stakeholders to communicate with each other and form consensus about
the system.
+3. *Major design decisions.* The description of the architecture represents
the earliest set of design decisions that have a significant impact on the
system as a whole. They are relevant to ensure the qualities and features of
the architecture.
+
+### Readers' guide
+
+The document starts with an introduction, outlining the scope and purpose of
this document and defining some acronyms and abbreviations. It then goes on by
first sketching the architectural context, exploring the domain and the
constraints. That is followed by the architectural design, which uses the 4+1
view as a guide to describe the system.
+
+All stakeholders should read the architectural context, as it explains what
the system does and how it interacts with its surroundings.
+
+Software engineers in particular should read the architectural design, which
outlines the foundation and describes the high level design that forms the
basis for further analysis and design.
+
+
+
+### Definitions, acronyms and abbreviations
+
+Definition | Explanation
+------------ | --------------------------------------------------
+OSGi | The OSGi alliance is an independent non-profit organization
that maintains the OSGi standard. OSGi technology provides a service-oriented,
component-based environment for developers and offers standardized ways to
manage the software life cycle. |
+Provisioning | Software provisioning is the process of installing and updating
software.
+Target | A target, or OSGi gateway, is a computer or device that has an
OSGi framework installed.
+REST | Representational State Transfer (REST) is a style of software
architecture for distributed hypermedia systems. The term was introduced in the
doctoral dissertation in 2000 by Roy Fielding, one of the principal authors of
the Hypertext Transfer Protocol (HTTP) specification, and has come into
widespread use in the networking community.
+JMX | Java Management Extensions provides the tools for building
distributed, web-based, modular and dynamic solutions for managing and
monitoring devices, applications and service-driven networks. Since Java 5, it
is part of the Java SE platform.
+SOAP | SOAP is a protocol for exchanging XML-based messages over
computer networks, normally using HTTP/HTTPS. SOAP forms the foundation layer
of the Web services stack, providing a basic messaging framework that more
abstract layers can build on.
+DIY | An acronym for "do it yourself".
+
+Architectural Context
+---------------------
+
+### Domains
+
+The system consists of the following domains, as shown in the picture below.
+
+On the left hand side, the user interface and dependency repository are shown.
The dependency repository, sometimes referred to in an analogy as the "shop",
is mainly concerned with the dependency management domain, effectively linking
artifacts to targets through various mechanisms of grouping and filtering based
on requirements and capabilities of the individual artifacts.
+
+On the right hand side, the deployment aspect deals with the actual
provisioning of versioned sets of artifacts to targets.
+
+Finally, on the target itself, the life cycle is monitored and managed by the
management agent.
+
+The OBR does not need to be a part of our system, but it is used both in the
dependency and deployment domain.
+
+The lower part of the image deals with feedback. Feedback is responsible for
providing historic data of all changes to the actual life cycle of the target,
which is collected in the audit log and synchronized back to the server.
+
+#### Dependency management
+
+Whenever you are dealing with collections of artifacts, you want to start
grouping them to form logical subsystems. Doing this makes the artifacts more
manageable by users that are not intimately familiar with the architecture of
the software components that are being deployed.
+
+As an analogy, we often use the example of IKEA. They create modular
furniture, and sell their modules in configurations that make sense to their
users. You can order a cupboard that consists of planks, screws and doors, and
they give those configurations names. Apache ACE pretty much allows you to do
the same thing, which is why we like the "shop" analogy. In ACE we group our
artifacts into named distributions, and users can install one or more of these
onto a target.
+
+When installing artifacts together, we also need to make sure this collection
actually works together. Each bundle can have dependencies on other bundles,
services, packages or even specific hardware or operating systems. These
dependencies all need to be managed.
+
+Within an OSGi framework, there are two layers that feature dependencies:
+
+1. the module layer, that has package dependencies;
+2. the service layer, that has service dependencies.
+
+Traditionally, in OSGi, a bundle contains enough meta-data to analyze package
dependencies and ensure that these can be resolved. Service dependencies,
however, are a lot harder to analyze because of the extremely dynamic nature of
a service and the fact that there is no meta-data available. Also, modern
dependency management frameworks can express dependencies on more than just
services, allowing users to have configuration dependencies or even custom
dependencies like a dependency on the time of day.
+
+For other dependencies, such as required screen sizes, or the presence of
specific hardware, no meta-data is available in the bundle, so that is one
thing we need to add externally.
+
+Summing it up, it is important to make sure that you first of all have a clear
overview of the artifacts and their different deployable distributions and
secondly that you end up deploying sets of artifacts that work together well in
the environments in which they're deployed.
+
+#### Deployment
+
+In short, deployment is responsible for getting software artifacts onto target
systems. The general strategy is to have a management agent on each OSGi based
target that receives and deploys these artifacts.
+
+An important aspect of deployment is the actual distribution of artifacts. The
provisioning server takes an OBR as its source and artifacts somehow need to
find a way to the targets. In real-life scenarios, there often won't be a
completely open, two way connection between server and target, so catering for
all kinds of scenarios here is important.
+
+#### Life cycle management
+
+Life cycle management deals with managing the life cycle of artifacts within
the OSGi based target.
+
+The management agent is responsible for managing these life cycles, when to
update and even to figure out what update strategy to implement. The management
agent is also responsible for monitoring any changes and reporting those back
via the audit log (see "Feedback" below).
+
+Different types of artifacts might have different life cycles. From a
provisioning point of view, each artifact is either present on a target or it
is not. Bundles have a more extensive life cycle, where the following states
can be identified:
+
+* installed;
+* resolved;
+* starting;
+* active;
+* stopping;
+* uninstalled.
+
+The following state diagram shows these states and their transitions:
+
+TODO
+
+The transitions are explained below:
+
+* *install* - Each bundle starts its life cycle when it is first installed in
the OSGi framework. When a bundle is installed it is stored persistently in the
framework.
+* *start* - As soon as the bundle is started, it will transition through a
couple of states. The first step is the resolving of package dependencies. Here
the bundle is "wired up" and if that succeeds, it ends up in the resolved
state. From there it will go to starting, where the bundle activator gets
instantiated and a bundle can become an active entity (it can start threads,
initialize, etc.). Finally it ends up in the active state.
+* *update* - As soon as a bundle is installed, it can be updated. When a
bundle is updated, if it was active, it will be stopped. Subsequently it will
have to be resolved again, and started.
+* *stop* - When a bundle is active, it can be stopped. It will first go to the
stopping state, where it will have to cleanup (basically undo everything it did
during starting). It will end up as resolved.
+* *uninstall* - When a bundle is no longer needed, it can be uninstalled.
That's a final state, from there it can never be started again.
+
+#### Feedback
+
+Feedback is responsible for collecting log data and synchronizing it back to
the server. By default, all life cycle data is collected in the audit log. This
mechanism is extensible and can support domain specific extensions.
+
+An audit log is a full historic account of all events that are relevant for a
certain target. In this case, it provides historic data of all changes to the
actual life cycle of the target, both triggered by the management agent and by
other mechanisms on the target (for example, it also shows when the framework
itself was started and stopped).
+
+Architectural Design
+--------------------
+
+### Architectural foundation
+
+#### Service oriented, component based architecture
+
+#### Principles
+
+### Use Case View
+
