modules/ROOT/pages/documentation/integrators-guide.mdtext

Title: Integrators Guide
# Integrators guide
This page describes things that should be considered when integrating the
Apache Aries project into a runtime.

<a name="IntegratorsGuide-InstallingApplications"></a>
## Installing Applications

An application is installed using the AriesApplicationManager service. A
client looks up the AriesApplicationManager and calls one of the
createApplication methods. There are two createApplication methods. The
first takes a URL that identifies the application. When this is called the
application is archive is downloaded from the specified URL and stored in a
temporary location. The second takes an IDirectory. The application utils
project contains two implementations of IDirectory, one that maps onto
directories and the other maps onto a zip. This method creates applications
with no downloads. The createApplication method will attempt to convert non
bundle content into bundles and will resolve the application in order to
find all the dependencies. This does not affect the original application.
To get a converted, resolved application the returned AriesApplication can
be stored elsewhere. Storing the AriesApplication will store an application
archive.

Once the AriesApplication has been created it can be installed into a
framework using the install method of the AriesApplicationManager. The
install method returns an ApplicationContext which represents the runtime
state of the application.

<a name="IntegratorsGuide-StartingandStoppinganApplication"></a>
## Starting and Stopping an Application

The application can be started and stopped by calling the start and stop
methods on the ApplicationContext.

<a name="IntegratorsGuide-UninstallinganApplication"></a>
## Uninstalling an Application

The application can be uninstalled by passing the ApplicationContext to the
uninstall method on the AriesApplicationManager.

<a name="IntegratorsGuide-FelixFileInstall"></a>
## Felix FileInstall

The aries application project contains an example application installer
that hooks into the felix file install project. It automatically installs
and uninstalls .eba archives found by FileInstall.

<a name="IntegratorsGuide-BundleConverters"></a>
## BundleConverters

A BundleConverter is a service that can convert an artefact into an OSGi
Bundle. The interface is provided an IFile indicating the artefact in the
application and an IDirectory for the root of the aries application. If the
artefact can be converted then an InputStream is returned that contains the
bytes for the bundle.

The Aries application project contains a converter for turning war files
into web application bundles.

<a name="IntegratorsGuide-AriesApplicationResolvers"></a>
## AriesApplicationResolvers

The Application-Content header in the application does not denote the full
content of the application. When the application is created the runtime
will use an AriesApplicationResolver service to work out what extra bundles
are needed to run the application.

The aries project contains two resolvers:

1. The NoOpResolver. This resolver assumes that all the required bundles are
contained by value in the application and simply returns the information
about the bundles in the application.
1. The OBRAriesResolver. This resolver makes use of OBR to resolve the
applications

The AriesApplicationManager service picks up any resolver in the service
registry, so alternatives can be provided if the default resolvers do not
provide the desired behaviour.

<a name="IntegratorsGuide-ApplicationContextManagers"></a>
## ApplicationContextManagers

The AriesApplicationManager does not itself know how to put an application
into an OSGi framework. To do this it calls out to an
ApplicationContextManager. 

The aries project contains a single simple application context manager
which installs the application into a flat framework. This does not provide
the isolation expected for the application content and is provided as a
simple sample.