| 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 |