Title: Dependency Management

Apache Stanbol is a modular software stack. Technically, this modularization
is implemented by the underlying OSGi component infrastructure. Each Apache
Stanbol component is implemented as an OSGi bundle that can be deployed in
an OSGi environment. Apache Stanbol uses the OSGi implementation from
[Apache Felix](http://felix.apache.org/site/index.html) for this.

Apache Stanbol's dependency management is organized at three levels:

  1. [Build Dependency Management](#build-dependency-management)
  2. [Runtime (OSGi) Dependency Management](#runtime-dependency-management)
  3. [Launcher Configuration Management](#launcher-configuration-management)

<a name="build-dependency-management"></a>
### Build Dependency Management

Build dependencies are configured in the Apache Maven pom.xml (POM) files.
We distinguish between internal and external dependencies.

  * Internal dependencies are dependencies to other org.apache.stanbol.*
    components.
  * External dependencies are dependencies to third party components from
    outside the Apache Stanbol project.

Internal dependencies are managed separatly for each component. So each
component defines in its own POM which other Apache Stanbol components in
which versions it requires. This makes it possible that different components
could rely on different versions of another Apache Stanbol component.
This is a requirement to be able to release single Apache Stanbol
components independently.

External dependencies to third party components are managed at a central
place to ensure that all Apache Stanbol components rely on the very same
version of a third party component. The central configuration for this can
be found in the dependency management section of the Apache Stanbol
[parent POM](http://svn.apache.org/repos/asf/stanbol/trunk/parent/pom.xml).
As all Apache Stanbol components define this central POM as their parent,
it is ensured that all components use the same version of an
external dependency. Changing the version of an external dependency in the
parent POM affects all Apache Stanbol components that rely on this
dependency.

In consequence it is not allowed that Apache Stanbol components define their
own version of an external dependency in their POM. External dependencies
are configured in the parent POM only! If there is any Apache Stanbol 
component that does not apply to this rule, it should
be considered as a bug or a good reason for this should be documented.
Relying on the same version of external dependencies is essential to ensure
a working Apache Stanbol stack.

<a name="runtime-dependency-management"></a>
### Runtime (OSGi) Dependency Management

Apache Stanbol components are OSGi bundles. Therefore, the runtime
dependencies between such bundles are managed by the exported and imported
packages of those bundles. What a bundle requires to import and what it
exports is configured by using the Maven Bundle plugin of the Apache Felix
project. Its configuration is done inside the POM. The Maven Bundle plugin
ensures that the OSGi specific meta-information are generated correctly
for the resulting JAR.

Configuring the OSGi imports and exports is in most cases analogue to
configure the build dependencies in the POM. We can not go into the details
of OSGi here and refer to the
[OSGi Alliance](http://www.osgi.org/) and the
[Apache Felix](http://felix.apache.org/site/index.html) project
for further information.

<a name="launcher-configuration-management"></a>
### Launcher Configuration Management

Launchers represent the binary distribution of Apache Stanbol. An Apache
Stanbol launcher is a packaged OSGi runtime environment. It includes a set
of Apache Stanbol components and required third party components to build up
the runtime stack. Additionally, a launcher instantiates an Apache Stanbol
HTTP endpoint to provide the RESTful interface and documentation.

Basically, a launcher packages everything together in a single executable
JAR that is needed to run Apache Stanbol. To configure which bundles are
part of this launcher and to ensure that all required third party components
are in place, the launchers are composed of so called 'partial bundlelists'.

A partial bundlelist is defined by each Apache Stanbol component and it lists
all required internal and external dependencies that have to be included in a
launcher in order to make this component work. The dependencies are
configured in a 'src/main/bundles/list.xml' file of each partial bundlelist
artifact. The dependencies listed in such a file of a partial bundlelist
are more or less the same as the ones defined for the build dependencies in
the POM. But remember that the partial bundlelists define the dependencies
needed at runtime and there may be other/more dependencies needed at runtime
than at build time.

Apache Stanbol pre-configures a set of launchers in the
[/launchers](http://svn.apache.org/repos/asf/stanbol/trunk/launchers/) directory.
The most important one is the 'full' launcher which includes all available
Apache Stanbol components. This launcher is also used when executing the
integration tests. In a launcher's POM you just have to declare dependencies
to all required partial bundlelists that the launcher should include.