incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling > The Sling Launchpad
Date Fri, 30 Jul 2010 21:44:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=SLING&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/SLING/The+Sling+Launchpad">The
Sling Launchpad</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
        <br/>
                         <h4>Changes (3)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h2. Servlet Parameters <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >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}} <span class="diff-changed-words">fi<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">e</span>le.</span>
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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>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. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >| {{/sling/instance1}} | {{sling/\_sling\_instance1}}
| <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Examples:
Assume the {{sling.home.prefix}} system property is set to {{/var/sling}} <br> <br>||
Servlet Context || Default {{sling.home}} || <br>| _root_ | {{/var/sling/\_}} | <br>|
{{/sling}} | {{/var/sling/\_sling}} | <br>| {{/sling/instance1}} | {{/var/sling/\_sling\_instance1}}
| <br> <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h2. sling.properties <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="TheSlingLaunchpad-TheSlingLaunchpad"></a>The Sling
Launchpad</h1>

<div>
<ul>
    <li><a href='#TheSlingLaunchpad-SlingHome'>Sling Home</a></li>
    <li><a href='#TheSlingLaunchpad-CommandLineOptions'>Command Line Options</a></li>
<ul>
    <li><a href='#TheSlingLaunchpad-SecurityImplication'>Security Implication</a></li>
</ul>
    <li><a href='#TheSlingLaunchpad-ServletParameters'>Servlet Parameters</a></li>
    <li><a href='#TheSlingLaunchpad-sling.properties'>sling.properties</a></li>
    <li><a href='#TheSlingLaunchpad-Components'>Components</a></li>
<ul>
    <li><a href='#TheSlingLaunchpad-LaunchpadBase'>Launchpad Base</a></li>
    <li><a href='#TheSlingLaunchpad-LaunchpadBundles'>Launchpad Bundles</a></li>
    <li><a href='#TheSlingLaunchpad-LaunchpadAppandLaunchpadWebApp'>Launchpad
App and Launchpad WebApp</a></li>
</ul>
</ul></div>

<p>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.</p>


<h2><a name="TheSlingLaunchpad-SlingHome"></a>Sling Home</h2>

<p>Since Sling requires some space on the filesystem to store various files Sling has
to know where this filesystem space is located.</p>

<p>The following is a list of uses for the Sling Home directory:</p>

<ul>
	<li><tt>sling.properties</tt> &#8211; 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 <em>Launcher JAR</em>.
That is, changes to this file require a restart of the <em>Launcher JAR</em>.</li>
	<li><tt>org.apache.sling.launchpad.base.jar</tt> &#8211;  This is the
<em>Launcher JAR</em> 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 <em>Launcher JAR</em>.</li>
	<li><tt>felix</tt> &#8211; 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.</li>
	<li><tt>config</tt> &#8211; 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.</li>
	<li><tt>jackrabbit</tt> &#8211; The directory in which the Apache Jackrabbit
JCR repository is started. Amongst other things this also contains the Jackrabbit configuration
file <tt>repository.xml</tt>. You may modify this file, but don't forget to restart
the Embedded Jackrabbit Repository bundle after doing this.</li>
	<li><tt>logs</tt> &#8211; Contains the log files generated by Sling.
By default this contains the error.log and its rotated generations.</li>
</ul>



<h2><a name="TheSlingLaunchpad-CommandLineOptions"></a>Command Line Options</h2>


<p>The Java Standalone Application supports a number of command line options, which
influence the operation of the launch process.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Argument </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>start</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> Open a TCP/IP server socket when starting Sling. Uses option
<tt>-j</tt> to define the local socket address. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>status</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> Check whether a (remote) Sling application is running. Uses
option <tt>-j</tt> to define the address of the Sling instance to check. Note,
that the Sling application terminates after checking for the (remote) Sling status. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>stop</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> Stop a (remote) Sling application is running. Uses option
<tt>-j</tt> to define the address of the Sling instance to stop. Note, that the
Sling application terminates after stopping the (remote) Sling instance. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>-c</tt> </td>
<td class='confluenceTd'> slinghome </td>
<td class='confluenceTd'> The directory in which Sling locates its initial configuration
file <tt>sling.properties</tt> and where files of Sling itself such as the Apache
Felix bundle archive or the JCR repository files are stored. This defaults to the <tt>sling</tt>
folder in the current working directory. This is the value which is commonly refered to as
<tt>${sling.home}.</tt></td>
</tr>
<tr>
<td class='confluenceTd'> <tt>-l</tt> </td>
<td class='confluenceTd'> loglevel </td>
<td class='confluenceTd'> Sets the initial loglevel as an integer in the range 0 to
4 or as one of the well known level strings <tt>ERROR</tt>, <tt>WARN</tt>,
<tt>INFO</tt>, or <tt>DEBUG</tt>. This option overwrites the <tt>org.apache.sling.osg.log.level</tt>
setting the <tt>sling.properties</tt> file. The default is <tt>INFO</tt>.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>-f</tt> </td>
<td class='confluenceTd'> logfile </td>
<td class='confluenceTd'>  The log file to use or <tt>-</tt> to log to standard
out. This option overwrites the <tt>org.apache.sling.osg.log.file</tt> setting
the <tt>sling.properties</tt> file. The default is <tt>${sling.home}/logs/error.log</tt>.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>-a</tt> </td>
<td class='confluenceTd'> address </td>
<td class='confluenceTd'> The interfact to bind to (use 0.0.0.0 for any). This option
is not implemented yet. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>-p</tt> </td>
<td class='confluenceTd'> port </td>
<td class='confluenceTd'>  The port to listen (default 8080) to handle HTTP requests.
This option overwrites the <tt>org.osgi.service.http.port</tt> setting the <tt>sling.properties</tt>
file. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>-j</tt> </td>
<td class='confluenceTd'> [ host ":" ] port </td>
<td class='confluenceTd'>  The socket address to listen on for control connections (<tt>start</tt>
or to use as the remote endpoint for the control connection (<tt>status</tt> and
<tt>stop</tt>. If this parameter has no arguments or is not specified, the address
defaults to port 63000 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. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>-h</tt> </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> Prints a simple usage message listing all available command
line options. </td>
</tr>
</tbody></table>
</div>


<p>The Sling Standalone application looks for a definition of the <tt>sling.home</tt>
setting in the following locations in order of precendence:</p>

<ol>
	<li>The <tt>-c</tt> command line option</li>
	<li>The <tt>sling.home</tt> system property</li>
	<li>The <tt>SLING_HOME</tt> environment variable</li>
	<li>If none of the above resolves to a non-null value, the default value of <tt>sling</tt>
is assumed</li>
</ol>



<h3><a name="TheSlingLaunchpad-SecurityImplication"></a>Security Implication</h3>

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

<ul>
	<li>The server side socket for a running Sling Standalone Application is only created
if the application is started with the <tt>start</tt> command line option. If
this option is omitted &#8211; the default &#8211; the server side socket is not created
and the Sling Standalone Application instance cannot be remotely controlled.</li>
	<li>The default host name for the socket is localhost/127.0.0.1 meaning that the socket
is only accessible from the same system as the Sling Standalone Application is running on.
If the socket is accessible from remote systems additional must be taken to prevent malicious
attackers to stop the system. The server side control connection implementation implements
no security precaution (except from supporting to not create such a connection at all).</li>
</ul>



<h2><a name="TheSlingLaunchpad-ServletParameters"></a>Servlet Parameters</h2>

<p>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 <tt>sling.properties</tt>
file. One exception to this rule is the <tt>sling.home</tt> parameter, which is
used to set the value of the <tt>sling.home</tt> 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.</p>

<p>The <tt>sling.home</tt> folders for Sling Web Applications without the
<tt>sling.home</tt> servlet parameter are all located in the <tt>sling</tt>
folder in the current working directory as reported by the <tt>user.dir</tt> system
property. The name of the actual directory is derived from the Web Application Context Path
by replacing all slash characters <tt>/</tt> by underscore characters <tt>&#95;</tt>.
For the root context a single underscore character <tt>&#95;</tt> is used.</p>

<p>Examples:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Servlet Context </th>
<th class='confluenceTh'> Default <tt>sling.home</tt> </th>
</tr>
<tr>
<td class='confluenceTd'> <em>root</em> </td>
<td class='confluenceTd'> <tt>sling/&#95;</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>/sling</tt> </td>
<td class='confluenceTd'> <tt>sling/&#95;sling</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>/sling/instance1</tt> </td>
<td class='confluenceTd'> <tt>sling/&#95;sling&#95;instance1</tt>
</td>
</tr>
</tbody></table>
</div>


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

<p>Examples: Assume the <tt>sling.home.prefix</tt> system property is set
to <tt>/var/sling</tt></p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Servlet Context </th>
<th class='confluenceTh'> Default <tt>sling.home</tt> </th>
</tr>
<tr>
<td class='confluenceTd'> <em>root</em> </td>
<td class='confluenceTd'> <tt>/var/sling/&#95;</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>/sling</tt> </td>
<td class='confluenceTd'> <tt>/var/sling/&#95;sling</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>/sling/instance1</tt> </td>
<td class='confluenceTd'> <tt>/var/sling/&#95;sling&#95;instance1</tt>
</td>
</tr>
</tbody></table>
</div>



<h2><a name="TheSlingLaunchpad-sling.properties"></a>sling.properties</h2>

<p>The <tt>sling.properties</tt> 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 <tt>sling.properties</tt> file installed
when Sling is first started.</p>

<p>One thing to note is, that the <tt>sling.properties</tt> 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 <tt>${name</tt>} notation.
Such property references may even be cascaded as in</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
java.packages=${jre-${java.specification.version}}
</pre>
</div></div>


<h2><a name="TheSlingLaunchpad-Components"></a>Components</h2>

<p>The Sling Launchapd consists of <em>Launchbad Base</em> project and three
additional projects which ultimately create a Standalone Java Application and a Web Appliction
with standard parts of Sling.</p>


<h3><a name="TheSlingLaunchpad-LaunchpadBase"></a>Launchpad Base</h3>

<p>The <em>Launchpad Base</em> projects creates the following artifacts,
which are required in actual setups to get a Sling application:</p>

<ul>
	<li><b>Launcher JAR</b> &#8211; 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.</li>
</ul>


<ul>
	<li><b>App JAR</b> &#8211; The secondary artifact with classifier <em>app</em>
is a minimal Standalone Java Application which may be started by simply typing</li>
</ul>


<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ java -jar org.apache.sling.launchpad.base-app.jar
</pre>
</div></div>

<ul>
	<li><b>Web App Archive</b> &#8211; The secondary artifact with classifier
<em>webapp</em> is a minimal Web Application, which may simply be deployed into
your favirourite servlet container, provided it supports at least Servlet API 2.4.</li>
</ul>


<ul>
	<li><b>Source JAR</b> &#8211; The secondary artifact with the classifier
<em>sources</em> is simple the source of the <em>Launchpad Base</em>
project.</li>
</ul>


<p>To build a very basic Sling launcher, the <em>Launchpad Base</em> 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 <em>Launchpad Bundles</em>,
<em>Launchpad App</em>, and <em>Launchpad WebApp</em> get to that.</p>


<h3><a name="TheSlingLaunchpad-LaunchpadBundles"></a>Launchpad Bundles</h3>

<p>The second project we want to look at is the <em>Launchpad Bundles</em>
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 <tt>resources/9</tt> where <tt>9</tt>
is a start level which is assigned to the bundles as they are installed. The special start
level <tt>0</tt> instructs the installer to not actually assign a specific start
level to the bundles contained in that folder.</p>

<p>Currently the following start level assignement is used by the <em>Launchpad
Bundles</em> project:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Start Level </th>
<th class='confluenceTh'> Bundle Group </th>
<th class='confluenceTh'> Bundle(s) </th>
</tr>
<tr>
<td class='confluenceTd'> 1 </td>
<td class='confluenceTd'> Basic bundles required for the correct operation of Sling
</td>
<td class='confluenceTd'> org.apache.sling.commons.log</td>
</tr>
<tr>
<td class='confluenceTd'> 5 </td>
<td class='confluenceTd'> Apache Felix Web Console </td>
<td class='confluenceTd'> org.apache.felix.bundlerepository, org.apache.felix.webconsole,
org.apache.sling.extensions.threaddump </td>
</tr>
<tr>
<td class='confluenceTd'> 10 </td>
<td class='confluenceTd'> OSGi Compendium Service Implementations </td>
<td class='confluenceTd'> org.apache.felix.configadmin, org.apache.felix.eventadmin,
org.apache.felix.metatype, org.apache.felix.scr </td>
</tr>
<tr>
<td class='confluenceTd'> 15 </td>
<td class='confluenceTd'> JCR Repository (Jackrabbit) </td>
<td class='confluenceTd'> commons-collections, commons-io-1.4.jar<br/>
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 </td>
</tr>
<tr>
<td class='confluenceTd'> 0 </td>
<td class='confluenceTd'> Actual Sling Application bundles </td>
<td class='confluenceTd'> 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 </td>
</tr>
</tbody></table>
</div>




<h3><a name="TheSlingLaunchpad-LaunchpadAppandLaunchpadWebApp"></a>Launchpad
App and Launchpad WebApp</h3>

<p>The <em>Launchpad App</em> and <em>Launchpad WebApp</em>
bundles are actually projects which just glue together artifacts from the Launchpad projects.
There is nothing special about them. Here's what is done:</p>

<ul>
	<li>Take the appropriate secondary artifact from the <em>Launchpad Base</em>
project: <em>app</em> for the Standalone Java Application or <em>webapp</em>
for the Web Application and unpack</li>
	<li>Take the <em>Launchpad Base</em> primary artifact and place it under
the name <tt>org.apache.sling.launchpad.base.jar</tt> into the <tt>resources</tt>
folder</li>
	<li>Take the <em>Launchpad Bundles</em> artifact and unpack it</li>
	<li>Finally pack all together into a single big JAR or WAR file</li>
</ul>


<p>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.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/SLING/The+Sling+Launchpad">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=107790&revisedVersion=10&originalVersion=9">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/SLING/The+Sling+Launchpad?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message