The Sling Launchpad
This tries to explain how exactly the Sling Launchpad works, what constitutes the Sling Launchpad and how you can use the Sling Launchpad to custom create you Sling launchers.
Sling Home
Since Sling requires some space on the filesystem to store various files Sling has to know where this filesystem space is located.
The following is a list of uses for the Sling Home directory:
sling.properties
– The main configuration file used by Sling to launch the framework. It mainly contains OSGi framework configuration and initial configuration for some bundles. This file is read on each startup of Launcher JAR. That is, changes to this file require a restart of the Launcher JAR.org.apache.sling.launchpad.base.jar
– This is the Launcher JAR file used by the Standalone Application or the Web Application to start the OSGi Framework. This file is initially placed when first starting Sling and may later be updated by updating the system bundle with a new Launcher JAR.felix
– The directory into which the Apache Felix Framework places the bundles, which have been installed into the system. This does generally not need to be touched.config
– The directory into which the Apache Felix Configuration Admin Service stores the configurationes. Do not change any files in this directory, since changes will not generally be picked up.jackrabbit
– The directory in which the Apache Jackrabbit JCR repository is started. Amongst other things this also contains the Jackrabbit configuration filerepository.xml
. You may modify this file, but don't forget to restart the Embedded Jackrabbit Repository bundle after doing this.logs
– Contains the log files generated by Sling. By default this contains the error.log and its rotated generations.
Command Line Options
The Java Standalone Application supports a number of command line options, which influence the operation of the launch process.
Option |
Argument |
Description |
---|---|---|
|
slinghome |
The directory in which Sling locates its initial configuration file |
|
loglevel |
Sets the initial loglevel as an integer in the range 0 to 4 or as one of the well known level strings |
|
logfile |
The log file to use or |
|
address |
The interfact to bind to (use 0.0.0.0 for any). This option is not implemented yet. |
|
port |
The port to listen (default 8080) to handle HTTP requests. This option overwrites the |
|
– |
Prints a simple usage message listing all available command line options. |
The Sling Standalone application looks for a definition of the sling.home
setting in the following locations in order of precendence:
- The
-c
command line option - The
sling.home
system property - The
SLING_HOME
environment variable - If none of the above resolves to a non-null value, the default value of
sling
is assumed
Servlet Parameters
The Web Application does not require specific servlet parameters. Those which are specified are used to overwrite any properties with the same name from the sling.properties
fiele. One exception to this rule is the sling.home
parameter, which is used to set the value of the sling.home
property. If no parameter with this name is defined the Sling home directory is derived from the context path at which the Sling Web Application is registered.
The sling.home
folders for Sling Web Applications without the sling.home
servlet parameter are all located in the sling
folder in the current working directory as reported by the user.dir
system property. The name of the actual directory is derived from the Web Application Context Path by replacing all slash characters /
by underscore characters _
. For the root context a single underscore character _
is used.
Examples:
Servlet Context |
Default |
---|---|
root |
|
|
|
|
|
sling.properties
The sling.properties
file contains the initial setup of the Sling Application and the OSGi framework. Some of the parameters are required and should not be modified without a very good reason. Some parameters may be freely modified to your needs. Please see the inlined comment in the sling.properties
file installed when Sling is first started.
One thing to note is, that the sling.properties
file is a simple Java Properties file with support for property references. That is, the value of properties may refer other property values by means of the well known ${name
} notation. Such property references may even be cascaded as in
java.packages=${jre-${java.specification.version}}
Components
The Sling Launchapd consists of Launchbad Base project and three additional projects which ultimately create a Standalone Java Application and a Web Appliction with standard parts of Sling.
Launchpad Base
The Launchpad Base projects creates the following artifacts, which are required in actual setups to get a Sling application:
- Launcher JAR – The primary artifact of the Base project contains the actual support to launch the Apache Felix OSGi Framework and install bundles, which are packaged with the application. It also contains the Apache Felix Framework together with the OSGi R4.1 Core and Compendium libraries as well as the Equinox HttpService bridge and the Servlet API.
- App JAR – The secondary artifact with classifier app is a minimal Standalone Java Application which may be started by simply typing
$ java -jar org.apache.sling.launchpad.base-app.jar
- Web App Archive – The secondary artifact with classifier webapp is a minimal Web Application, which may simply be deployed into your favirourite servlet container, provided it supports at least Servlet API 2.4.
- Source JAR – The secondary artifact with the classifier sources is simple the source of the Launchpad Base project.
To build a very basic Sling launcher, the Launchpad Base is actually all you need. But to really glue this together and get a usable system, some more work is required. Lets see how the additionaly projects Launchpad Bundles, Launchpad App, and Launchpad WebApp get to that.
Launchpad Bundles
The second project we want to look at is the Launchpad Bundles project. This is a very simple project in that it only collects together a number of OSGi bundles, which will make up the final application. The bundles are stored in a (big) Java Archive in folders whose path is formed with resources/9
where 9
is a start level which is assigned to the bundles as they are installed. The special start level 0
instructs the installer to not actually assign a specific start level to the bundles contained in that folder.
Currently the following start level assignement is used by the Launchpad Bundles project:
Start Level |
Bundle Group |
Bundle(s) |
---|---|---|
1 |
Basic bundles required for the correct operation of Sling |
org.apache.sling.commons.log |
5 |
Apache Felix Web Console |
org.apache.felix.bundlerepository, org.apache.felix.webconsole, org.apache.sling.extensions.threaddump |
10 |
OSGi Compendium Service Implementations |
org.apache.felix.configadmin, org.apache.felix.eventadmin, org.apache.felix.metatype, org.apache.felix.scr |
15 |
JCR Repository (Jackrabbit) |
commons-collections, commons-io-1.4.jar |
0 |
Actual Sling Application bundles |
org.apache.sling.adapter, org.apache.sling.api, org.apache.sling.bundleresource.impl, org.apache.sling.commons.json, org.apache.sling.engine, org.apache.sling.extensions.apt.parser, org.apache.sling.extensions.apt.servlet, org.apache.sling.httpauth, org.apache.sling.jcr.classloader, org.apache.sling.jcr.contentloader, org.apache.sling.jcr.ocm, org.apache.sling.jcr.resource, org.apache.sling.launchpad.content, org.apache.sling.samples.path-based.rtp, org.apache.sling.scripting.api, org.apache.sling.scripting.core, org.apache.sling.scripting.javascript, org.apache.sling.scripting.jsp, org.apache.sling.scripting.jsp.taglib, org.apache.sling.servlets.get, org.apache.sling.servlets.post, org.apache.sling.servlets.resolver |
Launchpad App and Launchpad WebApp
The Launchpad App and Launchpad WebApp bundles are actually projects which just glue together artifacts from the Launchpad projects. There is nothing special about them. Here's what is done:
- Take the appropriate secondary artifact from the Launchpad Base project: app for the Standalone Java Application or webapp for the Web Application and unpack
- Take the Launchpad Base primary artifact and place it under the name
org.apache.sling.launchpad.base.jar
into theresources
folder - Take the Launchpad Bundles artifact and unpack it
- Finally pack all together into a single big JAR or WAR file
That's it. The resulting artifact may be directly used to launch the Standalone Java Application or may directly be deployed into any Servlet API 2.4 (or later) compliant servlet container.