Title: Subsystems

#OSGi Subsystems

##Introduction

Apache Aries Subsystems is the Reference Implementation of the OSGi Subsystems Specification, chapter 134 of the 
[OSGi Enterprise specifications][1]. The Aries 1.x components implement the 1.0 version of the Subsystem spec. Aries 2.x and newer implement the 1.1 version of OSGi Subsystems.

##Getting started

This section shows the bundles to install to get the Subsystems implementation running in your favourite OSGi Framework.

The Aries Subsystem implementation uses the OSGi Coordination service, the OSGi
Resolver service, the OSGi Repository service and integrates with the OSGi Configuration Admin service. Additional 
dependencies are the Aries Util bundle, the Equinox Region bundle and SLF4J for logging.

The following are downloadable links (from Maven central) that 
provide all the required components to get subsystems up and running with Apache
Felix. Note that the Felix Framework distribution comes with OSGi Repository and Resolver implementations so these 
do not need to be added. (When running Aries Subsystems with another OSGi Framework these
must be provided.)

* [org.apache.aries.subsystem.api][2]
* [org.apache.aries.subsystem.core][3]
* [org.apache.aries.util][4]
* [org.apache.felix.configadmin][5]
* [org.apache.felix.coordinator][6]
* [org.eclipse.equinox.region][7]
* [slf4j-api][8]
* [slf4j-simple][9] (or another slf4j binding)

After installing and starting all these components the Felix runtime looks like this:

    g! lb
    START LEVEL 1
       ID|State      |Level|Name
        0|Active     |    0|System Bundle (5.4.0)|5.4.0
        1|Active     |    1|Apache Felix Bundle Repository (2.0.6)|2.0.6
        2|Active     |    1|Apache Felix Gogo Command (0.16.0)|0.16.0
        3|Active     |    1|Apache Felix Gogo Runtime (0.16.2)|0.16.2
        4|Active     |    1|Apache Felix Gogo Shell (0.10.0)|0.10.0
        5|Active     |    1|Apache Aries Subsystem API (2.0.6)|2.0.6
        6|Active     |    1|Apache Aries Subsystem Core (2.0.6)|2.0.6
        7|Active     |    1|Apache Aries Util (1.1.1)|1.1.1
        8|Active     |    1|Apache Felix Configuration Admin Service (1.8.8)|1.8.8
        9|Active     |    1|Apache Felix Coordinator Service (1.0.0)|1.0.0
       10|Resolved   |    1|Region Digraph (1.2.101.v20150831-1342)|1.2.101.v20150831-1342
       11|Active     |    1|slf4j-api (1.7.12)|1.7.12
       12|Resolved   |    1|slf4j-simple (1.7.12)|1.7.12
       13|Active     |    1|org.osgi.service.subsystem.region.context.0 (1.0.0)|1.0.0

The Region Digraph and slf4j-simple bundles are fragments, so they can not be started.
You can see that the Subsystems implementation is operational as it created a synthesized
bundle (13) to represent the root context. The subsystems implementation sometimes
synthesizes a bundle to represent a subsystem. Whether or not this happens depends on 
the isolation model of a subsystem.

You can also see that the Subsystem service for the root subsystem has been registered
by looking at the services registered by the Subsystem Core bundle (6):

    g! inspect cap service 6
    org.apache.aries.subsystem.core [6] provides:
    ---------------------------------------------
    service; org.osgi.service.subsystem.Subsystem, org.apache.aries.subsystem.AriesSubsystem with properties:
       org.apache.aries.subsystem.service.regions = [org.eclipse.equinox.region.kernel]
       subsystem.id = 0
       subsystem.state = ACTIVE
       subsystem.symbolicName = org.osgi.service.subsystem.root
       subsystem.type = osgi.subsystem.application
       subsystem.version = 1.0.0
       ... other properties and services

Each installed subsystem is represented by a serparate service.

##Tools

The Apache Aries community provides a number of tools that facilitate working with OSGi Subsystems:

* Subsystem Gogo Command - a Gogo command to work with subsystems, for more info see below.
* [esa-ant-task][10] - an Ant task to create .esa archives.
* [eas-maven-plugin][11] - a Maven plugin to create .esa archives.

### Subsystem Gogo Command

[https://svn.apache.org/repos/asf/aries/trunk/subsystem/subsystem-gogo-command][12] contains a simple bundle with Gogo commands
to control subsystems. This bundle can also be downloaded from [Maven Central here][13].

After installing the gogo command bundle you can execute subsystem commands, for example:

    g! subsystem:list
    0	ACTIVE	org.osgi.service.subsystem.root 1.0.0

Use `subsystem:install` to install additional subsystems, for example one that is part of the `subsystem-itests` module:

    g! subsystem:install file:/checkouts/aries/subsystem/subsystem-itests/target/feature1.esa
    ...
    Subsystem successfully installed: org.apache.aries.subsystem.feature1; id: 1

This subsystem embeds another subsystem which automatically gets installed too. When you list all subsystems you can see both:

    g! subsystem:list
    0	ACTIVE	org.osgi.service.subsystem.root 1.0.0
    1	INSTALLED	org.apache.aries.subsystem.feature1 1.0.0
    2	INSTALLED	org.apache.aries.subsystem.feature2 1.0.0

Together, these subsystems contain 3 bundles:

    g! lb
    START LEVEL 1
       ID|State      |Level|Name
        0|Active     |    0|System Bundle (5.0.1)
       ...
       16|Installed  |    1|TB3 (1.0.0)
       17|Installed  |    1|TB1 (1.0.0)
       18|Installed  |    1|TB2 (2.0.0)

Use `subsystem:start` to start a subsystem. This will start all its bundles and all the bundles of dependent subsystems. So the 
following single command, starts 3 bundles:

    g! subsystem:start 1
    g! lb
    START LEVEL 1
       ID|State      |Level|Name
        0|Active     |    0|System Bundle (5.0.1)
        ...
       16|Active     |    1|TB3 (1.0.0)
       17|Active     |    1|TB1 (1.0.0)
       18|Active     |    1|TB2 (2.0.0)

### Subsystem gogo commands
The following commands are available from the subsystem-gogo-command bundle:

* `subsystem:install <url>` - Install and resolve a subsystem.
* `subsystem:list <subsystemId>` - List installed subsystems.
* `subsystem:start <subsystemId>` - Start a subsystem and its dependencies.
* `subsystem:stop <subsystemId>` - Stop a subsystem and its dependencies.
* `subsystem:uninstall <subsystemId>` - Uninstall a subsystem and its dependencies. 

Note that, following the OSGi Subsystem specification, dependent subsystems are only stopped and uninstalled when the last using subsystem
is stopped/uninstalled.

##Development
The Aries Subsystems code base can be found at the following location: [https://svn.apache.org/repos/asf/aries/trunk/subsystem][14]


  [1]: http://www.osgi.org/Specifications/HomePage "OSGi Enterprise specifications"
  [2]: https://repo1.maven.org/maven2/org/apache/aries/subsystem/org.apache.aries.subsystem.api/2.0.6/org.apache.aries.subsystem.api-2.0.6.jar
  [3]: https://repo1.maven.org/maven2/org/apache/aries/subsystem/org.apache.aries.subsystem.core/2.0.6/org.apache.aries.subsystem.core-2.0.6.jar
  [4]: http://repo1.maven.org/maven2/org/apache/aries/org.apache.aries.util/1.1.1/org.apache.aries.util-1.1.1.jar
  [5]: https://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.configadmin/1.8.8/org.apache.felix.configadmin-1.8.8.jar
  [6]: http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.coordinator/1.0.0/org.apache.felix.coordinator-1.0.0.jar
  [7]: http://repo1.maven.org/maven2/org/eclipse/equinox/org.eclipse.equinox.region/1.2.101.v20150831-1342/org.eclipse.equinox.region-1.2.101.v20150831-1342.jar
  [8]: http://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.12/slf4j-api-1.7.12.jar
  [9]: http://repo1.maven.org/maven2/org/slf4j/slf4j-simple/1.7.12/slf4j-simple-1.7.12.jar
  [10]: http://aries.apache.org/modules/esaanttask.html
  [11]: http://aries.apache.org/modules/esamavenpluginproject.html
  [12]: https://svn.apache.org/repos/asf/aries/trunk/subsystem/subsystem-gogo-command
  [13]: https://repo1.maven.org/maven2/org/apache/aries/subsystem/org.apache.aries.subsystem.gogo-command/1.0.0/org.apache.aries.subsystem.gogo-command-1.0.0.jar
  [14]: https://svn.apache.org/repos/asf/aries/trunk/subsystem