incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r827230 - in /websites/staging/sling/trunk/content: ./ documentation/development/embedding-sling.html
Date Fri, 27 Jul 2012 20:02:22 GMT
Author: buildbot
Date: Fri Jul 27 20:02:21 2012
New Revision: 827230

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/development/embedding-sling.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Jul 27 20:02:21 2012
@@ -1 +1 @@
-1366516
+1366518

Modified: websites/staging/sling/trunk/content/documentation/development/embedding-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development/embedding-sling.html (original)
+++ websites/staging/sling/trunk/content/documentation/development/embedding-sling.html Fri
Jul 27 20:02:21 2012
@@ -85,9 +85,12 @@
       <h1>Embedding Sling</h1>
       <p>The Sling Launchpad Launcher can be used to embed the OSGi Framework startup
in your own Java application. This functionality is implemented in the <a href="">Sling
Launchpad Base project</a>. This project has the following features:</p>
 <ul>
-<li>Builds three artifacts:
-<strong> A standalone Java Application with the artifact qualifier <em>app</em>;
e.g. <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-app.jar</code></strong>
A Web Application with the artifact qualifier <em>webapp</em>; e.g <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-wepabb.war</code>
-** The primary artifact without an artifact qualifier; e.g. <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT.jar</code></li>
+<li>Builds three artifacts:<ul>
+<li>A standalone Java Application with the artifact qualifier <em>app</em>;
e.g. <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-app.jar</code></li>
+<li>A Web Application with the artifact qualifier <em>webapp</em>; e.g
<code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-wepabb.war</code></li>
+<li>The primary artifact without an artifact qualifier; e.g. <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT.jar</code></li>
+</ul>
+</li>
 <li>Embeds the OSGi Framework (Apache Felix) in the primary artifact</li>
 <li>Encapsulates the OSGi Framework in its own <code>URLClassLoader</code></li>
 <li>Supports Framework restart</li>
@@ -95,10 +98,12 @@
 </ul>
 <p>This page is about the internal details of the Sling Launchpad Base module. To get
an outside overview of the Sling Launchpad you might want to refer to <a href="/documentation/the-sling-engine/the-sling-launchpad.html">The
Sling Launchpad</a> page.</p>
 <h1 id="structure">Structure</h1>
-<p>The Launcher is based on three parts:
-1. The external part which is for example the standalone Java application's main class or
the servlet deployed into the servlet container
-1. The internal part which is the OSGi framework plus helper classes to control the framework
and run initial installations
-1. The bridging part, which contains API common to the external and internal part.</p>
+<p>The Launcher is based on three parts:</p>
+<ol>
+<li>The external part which is for example the standalone Java application's main class
or the servlet deployed into the servlet container</li>
+<li>The internal part which is the OSGi framework plus helper classes to control the
framework and run initial installations</li>
+<li>The bridging part, which contains API common to the external and internal part.</li>
+</ol>
 <p>The external part uses the bridging part to create the class loader into which the
internal part is loaded. The bidirectional communication between the external and internal
part is implement based on two interfaces:</p>
 <ul>
 <li>The <code>Launcher</code> interface is implemented by a class in the
internal part which is loaded through the bridge class loader. This interface allows setting,
starting and stopping of the framework.</li>
@@ -106,12 +111,36 @@
 </ul>
 <h1 id="the-bridging-part">The Bridging Part</h1>
 <p>The bridging part is provided in the <code>org.apache.sling.launchpad.base.shared</code>
package:</p>
-<p>| Class | Description |
-| Launcher | The interface implemented by the internal class matching the external class
being called to start/stop the framework. |
-| LauncherClassLoader | <code>URLClassLoader</code> implementing the class loader
to load the internal part (along with the OSGi framework). This class loader only delegates
to the parent class loader any packages not contained in the launchpad library (primary artifact
of the Launchpad Base project). |
-| Loader | Helper class to find the launchpad library and to create the <code>LauncherClassLoader</code>
with that library. This class is also used to actually load the <code>Launcher</code>
implementation to be called from the external launcher class. |
-| Notifiable | The interface implemented in the external part and handed over to the internal
part. |
-| SharedConstants | Constants naming various properties and classes. |</p>
+<table>
+<thead>
+<tr>
+<th>Class</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Launcher</td>
+<td>The interface implemented by the internal class matching the external class being
called to start/stop the framework.</td>
+</tr>
+<tr>
+<td>LauncherClassLoader</td>
+<td><code>URLClassLoader</code> implementing the class loader to load the
internal part (along with the OSGi framework). This class loader only delegates to the parent
class loader any packages not contained in the launchpad library (primary artifact of the
Launchpad Base project).</td>
+</tr>
+<tr>
+<td>Loader</td>
+<td>Helper class to find the launchpad library and to create the <code>LauncherClassLoader</code>
with that library. This class is also used to actually load the <code>Launcher</code>
implementation to be called from the external launcher class.</td>
+</tr>
+<tr>
+<td>Notifiable</td>
+<td>The interface implemented in the external part and handed over to the internal
part.</td>
+</tr>
+<tr>
+<td>SharedConstants</td>
+<td>Constants naming various properties and classes.</td>
+</tr>
+</tbody>
+</table>
 <h1 id="the-internal-part">The Internal Part</h1>
 <p>The main class from the internal class directly used is <a href=""><code>Sling</code></a>
which instantiated to start the OSGi Framework. This class is responsible for setting up the
environment to finally start the OSGi Framework:</p>
 <ul>
@@ -124,10 +153,28 @@
 <p>The external part is comprised of a main class started from the environment -- main
class of the Java applicaction or the servlet deployed in the servlet container -- and a corresponding
delegate class located inside of the launchpad base library. This delegate class is instantiated
by the <code>Loader</code> loading from the <code>LauncherClassLoader</code>.</p>
 <h3 id="standalone-java-application">Standalone Java Application</h3>
 <p>The standalone Java Application makes use of three classes:</p>
-<p>| Class | Description |
-| Main | This is the main class whose <code>main</code> method is called by the
Java VM. This class is itself the <code>Notifiable</code> and finds the <code>sling.home</code>
location from the environment (command line parameter, system property, or environment variable).
|
-| MainDelegate | This class is loaded by the <code>Loader</code> from the <code>LauncherClassLoader</code>
to actually complete the initial setup before creating the <code>Sling</code>
class to start the framework. |
-| ControlListener | This class is used by the <code>Main</code> class to open
a server socket to be able to start and stop Sling as a server. This class allows for starting
(opening the server socket), status check (connecting to the socket asking for status), and
shutdown (connecting to the socket asking for shutdown). |</p>
+<table>
+<thead>
+<tr>
+<th>Class</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Main</td>
+<td>This is the main class whose <code>main</code> method is called by
the Java VM. This class is itself the <code>Notifiable</code> and finds the <code>sling.home</code>
location from the environment (command line parameter, system property, or environment variable).</td>
+</tr>
+<tr>
+<td>MainDelegate</td>
+<td>This class is loaded by the <code>Loader</code> from the <code>LauncherClassLoader</code>
to actually complete the initial setup before creating the <code>Sling</code>
class to start the framework.</td>
+</tr>
+<tr>
+<td>ControlListener</td>
+<td>This class is used by the <code>Main</code> class to open a server
socket to be able to start and stop Sling as a server. This class allows for starting (opening
the server socket), status check (connecting to the socket asking for status), and shutdown
(connecting to the socket asking for shutdown).</td>
+</tr>
+</tbody>
+</table>
 <p>At the moment these classes are not directly suitable to be embedded in an existing
application (or custom application launcher framework) unless that embedding prepares command
line arguments in a <code>String[]()</code> and calls the <code>Main.main</code>
method. To allow for custom embeddings or extensions, the work distriubtions between the three
classes should be refactored.</p>
 <h3 id="embedding-the-standalone-java-application">Embedding the Standalone Java Application</h3>
 <p>{info}
@@ -164,9 +211,28 @@ This work is being done as part of <a hr
 <p>By using control actions, the Sling Launcher may open or connect to a control port
to communicate. The <code>doControlAction()</code> method together with the <code>sling.control.action</code>
and <code>sling.control.socket</code> properties is able to setup this communication.</p>
 <p>The <code>sling.control.socket</code> is either a normal port number,
in which case the connection is opened on the <code>localhost</code> interface
(usually 127.0.0.1). Otheriwse, it may also be a value of the form <em>host:port</em>
where <em>host</em> is the name or IP address of the interface to connect to and
port is the port number. For security reasons it is suggested to not use an interface which
is available remotely. So the default of <code>localhost</code> is usually the
best choice.</p>
 <p>The <code>sling.control.action</code> takes either of three values:</p>
-<p>| <code>start</code> | Starts a server socket as specified by the <code>sling.control.socket</code>
property. If the socket cannot be bound to (because the port is in use) an error message is
printed. Using the <code>start</code> action only makes sense when starting the
application. |
-| <code>stop</code> | The <code>stop</code> action is used to stop
a running application. For that a connection is opened to the server running on the socket
specified by the <code>sling.control.socket</code> property. On this connection
the server is instructed to shut down. After executing the <code>stop</code> action,
the Java application should be terminated. |
-| <code>status</code> | The <code>status</code> action is used to
check the status of a running application. For that a connection is opened to the server running
on the socket specified by the <code>sling.control.socket</code> property. On
this connection the server is queried on its status. After executing the <code>stop</code>
action, the Java application should be terminated. |</p>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>start</code></td>
+<td>Starts a server socket as specified by the <code>sling.control.socket</code>
property. If the socket cannot be bound to (because the port is in use) an error message is
printed. Using the <code>start</code> action only makes sense when starting the
application.</td>
+</tr>
+<tr>
+<td><code>stop</code></td>
+<td>The <code>stop</code> action is used to stop a running application.
For that a connection is opened to the server running on the socket specified by the <code>sling.control.socket</code>
property. On this connection the server is instructed to shut down. After executing the <code>stop</code>
action, the Java application should be terminated.</td>
+</tr>
+<tr>
+<td><code>status</code></td>
+<td>The <code>status</code> action is used to check the status of a running
application. For that a connection is opened to the server running on the socket specified
by the <code>sling.control.socket</code> property. On this connection the server
is queried on its status. After executing the <code>stop</code> action, the Java
application should be terminated.</td>
+</tr>
+</tbody>
+</table>
 <h4 id="conversion-of-commandline-arguments-to-properties">Conversion of Commandline
Arguments to Properties</h4>
 <p>When calling the Main class through the JVM startup the <code>Main.main(String[]()
args)</code> methods is called which reads the command line arguments and converts them
into a <code>Map&lt;String, String&gt;</code> suitable for the constructore
as follows:</p>
 <table>
@@ -221,15 +287,39 @@ This work is being done as part of <a hr
 </table>
 <h3 id="web-application">Web Application</h3>
 <p>The web application makes use of 5 classes:</p>
-<p>| Class | Description |
-| SlingServlet | This is the servlet registered in the <code>web.xml</code> descriptor
and loaded by the servlet container into which Sling is deplyoed. This class locates the <code>sling.home</code>
folder and loads the <code>SlingServletDelagate</code> to actually launch the
framework. |
-| SlingSessionListener | This -- somewhat inappropriately named -- class is registered as
a listener by the Sling <code>web.xml</code> descriptor. It is called by the servlet
container and forwards events to the <code>SlingHttpSessionListenerDelegate</code>
which in turn forwards the events to the respective Servlet API listener services registered
in the OSGi Framework. |
-| SlingBridge | Simple extension of the <code>Sling</code> class which registers
the system bundle's <code>BundleContext</code> as a servlet context attribute
of the Sling web application. This allows Servlet Container bridging to properly work. |
-| SlingHttpSessionListenerDelegate | This class is loaded by the <code>LauncherClassLoader</code>
called from the <code>SlingSessionListener</code>. It is called by the <code>SlingSessionListener</code>
to forward servlet container events to registered Servlet API listener services. |
-| SlingServletDelegate | This class is loaded by the <code>Loader</code> from
the <code>LauncherClassLoader</code> to actually complete the initial setup before
creating the <code>SlingBridge</code> class to start the framework. |</p>
+<table>
+<thead>
+<tr>
+<th>Class</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>SlingServlet</td>
+<td>This is the servlet registered in the <code>web.xml</code> descriptor
and loaded by the servlet container into which Sling is deplyoed. This class locates the <code>sling.home</code>
folder and loads the <code>SlingServletDelagate</code> to actually launch the
framework.</td>
+</tr>
+<tr>
+<td>SlingSessionListener</td>
+<td>This -- somewhat inappropriately named -- class is registered as a listener by
the Sling <code>web.xml</code> descriptor. It is called by the servlet container
and forwards events to the <code>SlingHttpSessionListenerDelegate</code> which
in turn forwards the events to the respective Servlet API listener services registered in
the OSGi Framework.</td>
+</tr>
+<tr>
+<td>SlingBridge</td>
+<td>Simple extension of the <code>Sling</code> class which registers the
system bundle's <code>BundleContext</code> as a servlet context attribute of the
Sling web application. This allows Servlet Container bridging to properly work.</td>
+</tr>
+<tr>
+<td>SlingHttpSessionListenerDelegate</td>
+<td>This class is loaded by the <code>LauncherClassLoader</code> called
from the <code>SlingSessionListener</code>. It is called by the <code>SlingSessionListener</code>
to forward servlet container events to registered Servlet API listener services.</td>
+</tr>
+<tr>
+<td>SlingServletDelegate</td>
+<td>This class is loaded by the <code>Loader</code> from the <code>LauncherClassLoader</code>
to actually complete the initial setup before creating the <code>SlingBridge</code>
class to start the framework.</td>
+</tr>
+</tbody>
+</table>
 <p>At the moment these classes, particularly the <code>SlingServlet</code>
class, are not particularly well suited to be extended by a servlet slightly modifying the
launcher.</p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+        Rev. 1366518 by fmeschbe on Fri, 27 Jul 2012 20:02:17 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project



Mime
View raw message