Apache
Home » Documentation » The Sling Engine

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. For a view behind the scenes of the Sling Launchpad Base module (the actual launcher) you might want to refer to the Embedding Sling page.

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:

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
start -- Open a TCP/IP server socket when starting Sling. Uses option -j to define the local socket address.
status -- Check whether a (remote) Sling application is running. Uses option -j to define the address of the Sling instance to check. Note, that the Sling application terminates after checking for the (remote) Sling status.
stop -- Stop a (remote) Sling application is running. Uses option -j to define the address of the Sling instance to stop. Note, that the Sling application tesrminates after stopping the (remote) Sling instance.
-j [ host ":" ] port The socket address to listen on for control connections (start or to use as the remote endpoint for the control connection (status and stop. If this parameter has no arguments or is not specified, the address defaults to any free port on localhost/127.0.0.1. If only the port is specified localhost/127.0.0.1 is used as the host part of the address.
-c slinghome The directory in which Sling locates its initial configuration file sling.properties and where files of Sling itself such as the Apache Felix bundle archive or the JCR repository files are stored. This defaults to the sling folder in the current working directory. This is the value which is commonly refered to as $\{sling.home}.
-i launchpadhome The launchpad directory. If not set, this is the same as $\{sling.home}. (since Sling Launchpad 2.4.0)
-l loglevel Sets the initial loglevel as an integer in the range 0 to 4 or as one of the well known level strings ERROR, WARN, INFO, or DEBUG. This option overwrites the org.apache.sling.osg.log.level setting the sling.properties file. The default is INFO.
-f logfile The log file to use or - to log to standard out. This option overwrites the org.apache.sling.osg.log.file setting in the sling.properties file. The default is $\{sling.home}/logs/error.log.
-a address The interfact to bind to (use 0.0.0.0 for any). This option overwrites the org.apache.felix.http.host setting in the sling.properties file and requires the embedded Http Service implementation to honor this property. (supported since Sling Launchpad 2.4.0)
-p port The port to listen (default 8080) to handle HTTP requests. This option overwrites the org.osgi.service.http.port setting in the sling.properties file.
-r path The root servlet context path for the Http Service (default is /). This option overwrites the org.apache.felix.http.context_path setting in the sling.properties file and requires the embedded Http Service implementation to honor this property. (since Sling Launchpad 2.4.0)
-D n=v Sets the property n to the value v. This option can be added repeatedly setting additional properties. Any property set in this manner overwrites same named properties in the sling.properties file. (since Sling Launchpad 2.4.0)
-n -- Don't install the shutdown hook. See Shutdown Hook below. (since Sling Launchpad 2.5.2)
-h -- 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:

  1. The -c command line option
  2. The sling.home system property
  3. The SLING_HOME environment variable
  4. If none of the above resolves to a non-null value, the default value of sling is assumed

Control Port

When starting the Sling Standalone Application with the start command line option, a TCP port is opened. The interface and port is configurable with the -j command line option. The address of the interface and the actual port used are written to the $\{sling.home}/conf/controlport file. So technically the -j option is not required for the status and stop operations because the port information is just read from this file.

Note that using a control connection for the Sling Standalone Application presents a potential security issue. For this reason the following defaults apply:

Suggestions: Do not allow the control port to be opened on an externally visible interface. Using the localhost/127.0.0.1 is just sufficient. Make sure only legitimate users have access to the installation folder of Sling (${sling.home}).

Shutdown Hook

By default the Sling Launchpad standalone application installs a Shutdown Hook with the Java Runtime to make sure the framework is properly terminated in case of a Java termination. In some situations or setups you want to control shutdown of Sling yourselves, so Sling supports a command line option -n to prevent the installation of a shutdown hook.

Apart from the command line option, the sling.shutdown.hook system property is also supported: If this property is set to true or is not set at all the shutdown hook is installed as expected. If the property is set to anything other than true, e.g. false, the shutdown hook is not installed.

If you are embedding the Sling Launchpad application's Main class, the sling.shutdown.hook property can also be set as a member of the props map handed to the Main constructor.

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 file. 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 sling.home
root sling/_
/sling sling/_sling
/sling/instance1 sling/_sling/instance1

Starting with Launchpad Base 2.2.2 the fixed prefix sling is configurable with the sling.home.prefix system property. If this property is set the value used as the prefix.

Examples: Assume the sling.home.prefix system property is set to /var/sling

Servlet Context Default sling.home
root /var/sling/_
/sling /var/sling/_sling
/sling/instance1 /var/sling/_sling/instance1

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

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, commons-lang, jackrabbit-api, jackrabbit-jcr-commons, org.apache.sling.commons.mime, org.apache.sling.commons.osgi, org.apache.sling.jcr.api, org.apache.sling.jcr.base, org.apache.sling.jcr.jackrabbit.server, org.apache.sling.jcr.webdav
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:

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.

Rev. 1456864 by fmeschbe on Fri, 15 Mar 2013 10:27:37 +0000
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.