[Jackrabbit Wiki] Update of "ApacheSling/SlingInitialStartup" by FelixMeschberger

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jackrabbit Wiki" for change notification.

The following page has been changed by FelixMeschberger:
http://wiki.apache.org/jackrabbit/ApacheSling/SlingInitialStartup

The comment on the change is:
Creation

New page:
= Initial Provisioning and Startup =


== We got a Launch ==

The most complicated tasks getting Sling or any Sling application up and running is launching the framework and providing the initial installation. To simplify these tasks, great efforts have been taken. The result is a Standalone Java Application - the Sling App - and a Web Application - the Sling Servlet - with embedded libraries and a core set of bundles and a mechanism to provide initial configuration and installation. The following description applies to both the standalone application and the web application.

When Sling is first started the following steps are executed:

   * The initial configuration is loaded as described in the [:../SlingConfiguration#Initial_Configuration:here].
   * The list of bundles embedded in the application is set to the {{{felix.autostart.1}}} property. This will automatically install and start these bundles in start level 1. Currently this list is hard coded and consists of the following bundles:
      * {{{org.apache.sling.sling-log}}} - The OSGi Log Service implementation of Project Sling also exporting logging APIs
      * {{{org.apache.sling.sling-assembly}}} - Installation and Update Management support
      * {{{org.apache.felix.bundlerepository}}} - Apache Felix implementation of the OSGi Bundle Repository specification.
   * The Apache Felix framework is launched and an URL handler for the {{{context:}}} scheme is registered to provide access to the contents of the Sling Web Application.
   * As soon as the Framework has been started, the {{{com.day.sling.assembly}}} bundle inspects the Framework properties available through the {{{BundleContext.getProperty(String)}}} method to install bundles from configured OSGi Bundle Repositories.



== Initial Bundle Installation by the sling-assembly Bundle ==

When the ''sling-assembly'' bundle is started it registers a {{{FrameworkEventListener}}} which justs listens for the {{{FRAMEWORK_STARTED}}} event. When this event comes in, the framework is up and running, the ''sling-assembly'' bundle will look at the Framework properties to see, whether any bundles need to be installed. This is done along the lines of the following pseudo code:

{{{String startLevelList = bundleContext.getProperty( "sling.install.bundles" )
for ( each startLevel in startLevelList ) do
    String bundleList = bundleContext.getProperty( "sling.install." + startLevel )
    for ( each bundle in bundleList )  do
        if ( not isInstalled( bundle ) ) then
            install( bundle )
            setStartLevel( bundle, startLevel )
        fi
    done
done

for ( each bundle installed ) do
    start( bundle )
done}}}


=== Example ===

Given the following properties

{{{sling.install.bundles = 1, 10, 20
sling.install.1 = org.apache.sling.assemblies.osgi-compendium-assembly:0.1.0, \
 org.apache.sling.assemblies.sling-console-web-assembly:0.1.0
sling.install.10 = org.apache.sling.assemblies.sling-crx-server-assembly:[1,2)
sling.install.20 = org.apache.sling.assemblies.sling-assembly}}}


These bundles will be installed:

|| '''Bundle''' || '''Version''' || '''Start Level''' ||
|| {{{org.apache.sling.assemblies.osgi-compendium-assembly}}} || >= 0.1.0 || 1 ||
|| {{{org.apache.sling.assemblies.sling-console-web-assembly}}} || >= 0.1.0 || 1 ||
|| {{{org.apache.sling.assemblies.sling-crx-server-assembly}}} || Any Version with Major Version 1 || 10 ||
|| {{{org.apache.sling.assemblies.sling-assembly}}} || Any Version || 20 ||


'''Notes'''

   1. The Sling application takes care of constructing the {{{sling.install.bundles}}} property from the {{{sling.install.<n>}}} properties found from the different property sources loaded before launching the framework. The {{{sling.install.bundles}}} property needs only be manually created in case the Sling Servlet is not used to launch the OSGi framework for Sling.
   1. Any {{{sling.install.<n>}}} property whose start level value {{{<n>}}} is not listed in the {{{sling.install.bundles}}} property is ignored.
   1. The {{{sling.install.<n>}}} properties are comma-separated lists of bundle specifications where each entry is a tuple of a bundle symbolic name and an optional version range specification (see section 3.2.5, Version Ranges, in the OSGi Service Platform Core Specification). If no version range (or single version) is specified for an entry, any version is applicable.
   1. The bundles listed in the {{{sling.install.<n>}}} properties are simple bundles from the point of view of initial installation. If any of the bundles happen to be an Assembly Bundle (see [:../SlingAssembly:Assembly: Bundling Bundles]) the Assembly Manager will take care of that bundle after the bundle has been installed.



== Important Properties ==

To recapitulate here is a list of Framework properties used for initial provisioning:

|| '''Property''' || '''Description''' ||
|| {{{obr.repository.url}}} || A comma-separated list of OSGi Bundle Repository URLs. This property is required to access the OSGi Bundle Repository to install the bundles listed in the {{{sling.install.<n>}}} properties. See the {{{org.apache.felix.bundlerepository}}} Bundle documentation for more information on this property. ||
|| {{{sling.install.bundles}}} || A comma-separated list of start level numbers referring to {{{sling.install.<n>}}} properties listing bundles to install. If this property is empty or  missing, nothing will be installed. ||
|| {{{sling.install.<n>}}} || A comma-separated list of bundle specifications consisting of the (required) bundle symbolic name and an (optional) version range specification separated by colon. Any {{{sling.install.<n>}}} property whose start level value {{{<n>}}} is not listed in the {{{sling.install.bundles}}}, property is ignored. ||



== Using the Sling Standalone Application ==

The Sling Standalone Application is available as an executable JAR file and may be started by just specifying a simple command line:

{{{
java -jar sling-app.jar
}}}

This causes Sling to start up as described above. The configuration built into the Sling Standalone Application causes the Apache Felix ''http.jetty'' bundle to be installed to run an embedded Servlet Container backing the OSGi HTTPService implementation used to provide the Sling Management Console.



== Using the Sling Web Application ==

Launching Sling in a servlet container is equally simple as using the standalone application: Grab the ''sling-servlet'' web application and deploy it into your favourite servlet container.