You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bd...@apache.org on 2017/06/19 12:41:41 UTC
[35/53] sling-site git commit: asf-site branch created for published
content
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/the-sling-launchpad.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/the-sling-launchpad.html b/documentation/the-sling-engine/the-sling-launchpad.html
new file mode 100644
index 0000000..c8c916b
--- /dev/null
+++ b/documentation/the-sling-engine/the-sling-launchpad.html
@@ -0,0 +1,179 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>The Sling Launchpad</h1></header><p>[TOC]</p>
+<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. For a view behind the scenes of the Sling Launchpad Base module (the actual launcher) you might want to refer to the <a href="/documentation/development/embedding-sling.html">Embedding Sling</a> page.</p>
+<h2>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><code>sling.properties</code> -- 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><code>org.apache.sling.launchpad.base.jar</code> -- 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><code>felix</code> -- 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><code>config</code> -- 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><code>jackrabbit</code> -- The directory in which the Apache Jackrabbit JCR repository is started ( only applicable when using Apache Jackrabbit 2.x ). This is only available for Sling Launchpad 7 or older. Amongst other things this also contains the Jackrabbit configuration file <code>repository.xml</code>. You may modify this file, but don't forget to restart the Embedded Jackrabbit Repository bundle after doing this.</li>
+ <li><code>oak</code> - The directory in which the Apache Jackrabbit Oak JCR Repository is started ( only applicable when using Apache Jackrabbit Oak with the SegmentNodeStoreBackend ). This is only available for Sling Launchpad 8 or newer.</li>
+ <li><code>logs</code> -- Contains the log files generated by Sling. By default this contains the error.log and its rotated generations.</li>
+</ul>
+<h2>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>
+<table>
+ <thead>
+ <tr>
+ <th>Option </th>
+ <th>Argument </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+</table>
+<p>| <code>start</code> | -- | Open a TCP/IP server socket when starting Sling. Uses option <code>-j</code> to define the local socket address. | | <code>status</code> | -- | Check whether a (remote) Sling application is running. Uses option <code>-j</code> to define the address of the Sling instance to check. Note, that the Sling application terminates after checking for the (remote) Sling status. | | <code>stop</code> | -- | Stop a (remote) Sling application is running. Uses option <code>-j</code> to define the address of the Sling instance to stop. Note, that the Sling application tesrminates after stopping the (remote) Sling instance. | | <code>-j</code> | [ host ":" ] port | The socket address to listen on for control connections (<code>start</code> or to use as the remote endpoint for the control connection (<code>status</code> and <code>stop</code>. 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 th
e port is specified localhost/127.0.0.1 is used as the host part of the address. | | <code>-c</code> | slinghome | The directory in which Sling locates its initial configuration file <code>sling.properties</code> and where files of Sling itself such as the Apache Felix bundle archive or the JCR repository files are stored. This defaults to the <code>sling</code> folder in the current working directory. This is the value which is commonly refered to as <code>${sling.home}.</code> | <code>-i</code> | launchpadhome | The launchpad directory. If not set, this is the same as <code>${sling.home}.</code> (since Sling Launchpad 2.4.0) | | <code>-l</code> | loglevel | Sets the initial loglevel as an integer in the range 0 to 4 or as one of the well known level strings <code>ERROR</code>, <code>WARN</code>, <code>INFO</code>, or <code>DEBUG</code>. This option overwrites the <code>org.apache.sling.osg.log.level</code> setting the <code>sling.properties</code> file. The default is <code>INFO</
code>. | | <code>-f</code> | logfile | The log file to use or <code>-</code> to log to standard out. This option overwrites the <code>org.apache.sling.osg.log.file</code> setting in the <code>sling.properties</code> file. The default is <code>${sling.home}/logs/error.log</code>. | | <code>-a</code> | address | The interfact to bind to (use 0.0.0.0 for any). This option overwrites the <code>org.apache.felix.http.host</code> setting in the <code>sling.properties</code> file and requires the embedded Http Service implementation to honor this property. (supported since Sling Launchpad 2.4.0) | | <code>-p</code> | port | The port to listen (default 8080) to handle HTTP requests. This option overwrites the <code>org.osgi.service.http.port</code> setting in the <code>sling.properties</code> file. | | <code>-r</code> | path | The root servlet context path for the Http Service (default is /). This option overwrites the <code>org.apache.felix.http.context_path</code> setting in the <code>slin
g.properties</code> file and requires the embedded Http Service implementation to honor this property. (since Sling Launchpad 2.4.0) | | <code>-D</code> | n=v | Sets the property <code>n</code> to the value <code>v</code>. This option can be added repeatedly setting additional properties. Any property set in this manner overwrites same named properties in the <code>sling.properties</code> file. (since Sling Launchpad 2.4.0) | | <code>-n</code> | -- | Don't install the shutdown hook. See <a href="#shutdown-hook">Shutdown Hook</a> below. (since Sling Launchpad 2.5.2) | | <code>-h</code> | -- | Prints a simple usage message listing all available command line options. |</p>
+<p>The Sling Standalone application looks for a definition of the <code>sling.home</code> setting in the following locations in order of precendence:</p>
+<ol>
+ <li>The <code>-c</code> command line option</li>
+ <li>The <code>sling.home</code> system property</li>
+ <li>The <code>SLING_HOME</code> environment variable</li>
+ <li>If none of the above resolves to a non-null value, the default value of <code>sling</code> is assumed</li>
+</ol>
+<h3>Control Port</h3>
+<p>When starting the Sling Standalone Application with the <code>start</code> command line option, a TCP control port is opened to receive simple commands which allow for stopping an instance and getting thread dumps.</p>
+<p>Currently supported commands are</p>
+<ul>
+ <li><code>stop</code> to stop the Sling instance</li>
+ <li><code>status</code> to get the instance status (OK or STOPPING)</li>
+ <li><code>threads</code> to get a thread dump</li>
+</ul>
+<p>For the Whole Truth about this functionality see the <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/base/src/main/java/org/apache/sling/launchpad/app/ControlListener.java">ControlListener class source code</a>.</p>
+<p>The interface and port is configurable with the <code>-j</code> command line option. The actual address and port used are written to the <code>${sling.home}/conf/controlport</code> file. So technically the <code>-j</code> option is not required for the <code>status</code> and <code>stop</code> operations because the port information can be read from that file.</p>
+<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 not created by default, but only if the application is started with the <code>start</code> command line option.</li>
+ <li>The default control port configuration is <code>localhost/127.0.0.1</code> meaning that the socket is only accessible from the same system as the Sling Standalone Application is running on.</li>
+ <li>A nonce, followed by a space character, must be used as a prefix for every command sent to the control port. This nonce is generated by Sling at startup and also written to the <code>controlport</code> file mentioned above.</li>
+</ul>
+<p>For additional security, do not allow the control port to be opened on an externally visible network interface and strictly restrict access to the Sling installation folder (<code>${sling.home}</code>).</p>
+<p>Here's an example session where a Sling Standalone Application is started with the control port active:</p>
+<p>$ java -jar target/org.apache.sling.launchpad-9-SNAPSHOT.jar start 05.04.2016 11:50:45.003 *INFO * [main] Setting sling.home=sling (default) 05.04.2016 11:50:45.006 *INFO * [main] Starting Apache Sling in /foo/sling/launchpad/builder/sling ... 05.04.2016 11:50:45.012 *INFO * [Apache Sling Control Listener@/127.0.0.1:59239] Apache Sling Control Listener started ...</p>
+<p>And stopped using its control port, from another terminal:</p>
+<p>$ cat sling/conf/controlport 127.0.0.1:59239 mdsryh1k5fpcgvm7suqnckxkr7fvluzv</p>
+<p>$ telnet 127.0.0.1 59239 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'.</p>
+<p>mdsryh1k5fpcgvm7suqnckxkr7fvluzv stop</p>
+<p>OK Connection closed by foreign host.</p>
+<h3>Shutdown Hook</h3>
+<p>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 <code>-n</code> to prevent the installation of a shutdown hook.</p>
+<p>Apart from the command line option, the <code>sling.shutdown.hook</code> system property is also supported: If this property is set to <code>true</code> or is not set at all the shutdown hook is installed as expected. If the property is set to anything other than <code>true</code>, e.g. <code>false</code>, the shutdown hook is not installed.</p>
+<p>If you are embedding the Sling Launchpad application's <code>Main</code> class, the <code>sling.shutdown.hook</code> property can also be set as a member of the <code>props</code> map handed to the <code>Main</code> constructor.</p>
+<h2>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 <code>sling.properties</code> file. One exception to this rule is the <code>sling.home</code> parameter, which is used to set the value of the <code>sling.home</code> 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 <code>sling.home</code> folders for Sling Web Applications without the <code>sling.home</code> servlet parameter are all located in the <code>sling</code> folder in the current working directory as reported by the <code>user.dir</code> system property. The name of the actual directory is derived from the Web Application Context Path by replacing all slash characters <code>/</code> by underscore characters <code>_</code>. For the root context a single underscore character <code>_</code> is used.</p>
+<p>Examples:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Servlet Context </th>
+ <th>Default <code>sling.home</code> </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><em>root</em> </td>
+ <td><code>sling/_</code> </td>
+ </tr>
+ <tr>
+ <td><code>/sling</code> </td>
+ <td><code>sling/_sling</code> </td>
+ </tr>
+ <tr>
+ <td><code>/sling/instance1</code> </td>
+ <td><code>sling/_sling/instance1</code> </td>
+ </tr>
+ </tbody>
+</table>
+<p>Starting with Launchpad Base 2.2.2 the fixed prefix <code>sling</code> is configurable with the <code>sling.home.prefix</code> system property. If this property is set the value used as the prefix.</p>
+<p>Examples: Assume the <code>sling.home.prefix</code> system property is set to <code>/var/sling</code></p>
+<table>
+ <thead>
+ <tr>
+ <th>Servlet Context </th>
+ <th>Default <code>sling.home</code> </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><em>root</em> </td>
+ <td><code>/var/sling/_</code> </td>
+ </tr>
+ <tr>
+ <td><code>/sling</code> </td>
+ <td><code>/var/sling/_sling</code> </td>
+ </tr>
+ <tr>
+ <td><code>/sling/instance1</code> </td>
+ <td><code>/var/sling/_sling/instance1</code> </td>
+ </tr>
+ </tbody>
+</table>
+<h2>sling.properties</h2>
+<p>The <code>sling.properties</code> 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 <code>sling.properties</code> file installed when Sling is first started.</p>
+<p>One thing to note is, that the <code>sling.properties</code> 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 <code>${name}</code> notation. Such property references may even be nested as in</p>
+<p>java.packages=${jre-${java.specification.version}}</p>
+<h2>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>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>
+ <p><em>Launcher JAR</em> -- 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.</p></li>
+ <li>
+ <p><em>App JAR</em> -- The secondary artifact with classifier <em>app</em> is a minimal Standalone Java Application which may be started by simply typing</p></li>
+</ul>
+<p>$ java -jar org.apache.sling.launchpad.base-app.jar</p>
+<ul>
+ <li>
+ <p><em>Web App Archive</em> -- 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.</p></li>
+ <li>
+ <p><em>Source JAR</em> -- The secondary artifact with the classifier <em>sources</em> is simple the source of the <em>Launchpad Base</em> project.</p></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>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 <code>org.apache.sling.launchpad.base.jar</code> into the <code>resources</code> folder</li>
+ <li>Copies the list of artifacts defined in the <a href="/documentation/development/slingstart.html">Provisioning model</a></li>
+ <li>Finally pack all together into a single big JAR or WAR file</li>
+</ul>
+<p>The artifacts can be configured to use different JCR repository implementations, based on the value of the <code>-Dsling.run.modes</code> property. The following run modes are available for the 8 version of the Sling Launchpad:</p>
+<ul>
+ <li><code>oak</code>: configures and starts up an Apache Jackrabbit Oak repository implementation with a SegmentNodeStore ( TarMK ) implementation</li>
+ <li><code>oak,oak_mongo</code>: configures and starts up an Apache Jackrabbit Oak repository implementation with a DocumentNodeStore implementation connected to a MongoDB database. The default configuration points to a MongoDB instance at mongodb://localhost:27017 and a database named sling.</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 3.0 (or later) compliant servlet container.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/url-decomposition.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/url-decomposition.html b/documentation/the-sling-engine/url-decomposition.html
new file mode 100644
index 0000000..9534fc6
--- /dev/null
+++ b/documentation/the-sling-engine/url-decomposition.html
@@ -0,0 +1,178 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>URL decomposition</h1></header><p>[TOC]</p>
+<h1>Overview</h1>
+<p>During the <em>Resource Resolution</em> step, the client request URI (as being returned by [HttpServletRequest.getRequestURI()](http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRequestURI())) is decomposed into the following parts (in exactly this order):</p>
+<ol>
+ <li><strong>Resource Path</strong> - For existing resources the resource path is the longest match (also considering its <a href="/documentation/the-sling-engine/mappings-for-resource-resolution.html">mappings</a>) pointing to a resource where the next character is either a dot (<code>.</code>) or it is the full request URI. Otherwise (for a path not matching any existing resource) the resource path ends at the <em>first dot (<code>.</code>)</em> in the request url. The exact logic for retrieving the resource path is implemented at <a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#resolve-javax.servlet.http.HttpServletRequest-java.lang.String-">ResourceResolver.resolve(HttpServletRequest,String)</a>. <em>It is impossible to tell from just looking at the request URI where the resource path part ends. You have to know the underlying resource structure to know how a URL is decomposed. You cannot safely assume that the resource path w
ill always end at the first dot!</em>.</li>
+ <li><strong>Selectors</strong> - If the first character in the request URL after the resource path is a dot (<code>.</code>), the string after the dot up to but not including the last dot before the next slash character or the end of the request URL comprises the selectors. If the resource path spans the complete request URL no selectors exist. If only one dot follows the resource path before the end of the request URL or the next slash, also no selectors exist.</li>
+ <li><strong>Extension</strong> - The string after the last dot after the resource path in the request URL but before the end of the request URL or the next slash after the resource path in the request URL is the extension.</li>
+ <li><strong>Suffix</strong> - If the request URL contains a slash character after the resource path and optional selectors and extension, the path starting with the slash up to the end of the request URL is the suffix path. Otherwise, the suffix path is empty. Note, that after the resource path at least a dot must be in the URL to let Sling detect the suffix.</li>
+</ol>
+<p>Those decomposed parts can be accessed through the <code>RequestPathInfo</code> object, which is retrieved via <a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/SlingHttpServletRequest.html#getRequestPathInfo--">SlingHttpServletRequest.getPathInfo()</a>.</p>
+<p>There's a cheat sheet in Adobe's AEM documentation at <a href="https://docs.adobe.com/docs/en/aem/6-2/develop/platform/sling-cheatsheet.html">https://docs.adobe.com/docs/en/aem/6-2/develop/platform/sling-cheatsheet.html</a> available to get you familiar with the URL decomposition of Sling.</p>
+<h1>Examples</h1>
+<p>Assume there is a Resource at <code>/a/b</code>, which has no children.</p>
+<table>
+ <thead>
+ <tr>
+ <th>URI </th>
+ <th>Resource Path </th>
+ <th>Selectors </th>
+ <th>Extension </th>
+ <th>Suffix </th>
+ <th>Resource Found </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>/a/b </td>
+ <td>/a/b </td>
+ <td>null </td>
+ <td>null </td>
+ <td>null </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.html </td>
+ <td>/a/b </td>
+ <td>null </td>
+ <td>html </td>
+ <td>null </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.s1.html </td>
+ <td>/a/b </td>
+ <td>s1 </td>
+ <td>html </td>
+ <td>null </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.s1.s2.html </td>
+ <td>/a/b </td>
+ <td>s1.s2 </td>
+ <td>html </td>
+ <td>null </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b/c/d </td>
+ <td>/a/b/c/d </td>
+ <td>null </td>
+ <td>null </td>
+ <td>null </td>
+ <td>no! </td>
+ </tr>
+ <tr>
+ <td>/a/c.html/s.txt </td>
+ <td>/a/c </td>
+ <td>null </td>
+ <td>html </td>
+ <td>/s.txt </td>
+ <td>no! </td>
+ </tr>
+ <tr>
+ <td>/a/b./c/d </td>
+ <td>/a/b </td>
+ <td>null </td>
+ <td>null </td>
+ <td>/c/d </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.html/c/d </td>
+ <td>/a/b </td>
+ <td>null </td>
+ <td>html </td>
+ <td>/c/d </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.s1.html/c/d </td>
+ <td>/a/b </td>
+ <td>s1 </td>
+ <td>html </td>
+ <td>/c/d </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.s1.s2.html/c/d </td>
+ <td>/a/b </td>
+ <td>s1.s2 </td>
+ <td>html </td>
+ <td>/c/d </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b/c/d.s.txt </td>
+ <td>/a/b/c/d </td>
+ <td>s </td>
+ <td>txt </td>
+ <td>null </td>
+ <td>no! </td>
+ </tr>
+ <tr>
+ <td>/a/b.html/c/d.s.txt </td>
+ <td>/a/b </td>
+ <td>null </td>
+ <td>html </td>
+ <td>/c/d.s.txt </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.s1.html/c/d.s.txt </td>
+ <td>/a/b </td>
+ <td>s1 </td>
+ <td>html </td>
+ <td>/c/d.s.txt </td>
+ <td>yes </td>
+ </tr>
+ <tr>
+ <td>/a/b.s1.s2.html/c/d.s.txt </td>
+ <td>/a/b </td>
+ <td>s1.s2 </td>
+ <td>html </td>
+ <td>/c/d.s.txt </td>
+ <td>yes </td>
+ </tr>
+ </tbody>
+</table>
+<h1>Automated Tests</h1>
+<p>The tests at</p>
+<ul>
+ <li><a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/resourceresolver/src/test/java/org/apache/sling/resourceresolver/impl/ResourceResolverImplTest.java">ResourceResolverImplTest</a> shows the split between resource path and the rest. Mostly in the method <code>testBasicAPIAssumptions</code>.</li>
+ <li><a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/engine/src/test/java/org/apache/sling/engine/impl/request/SlingRequestPathInfoTest.java">SlingRequestPathInfoTest</a> demonstrates the decomposition after the resource path part.</li>
+</ul>
+<p>Feel free to suggest additional tests that help clarify how this works!</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/url-to-script-resolution.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/url-to-script-resolution.html b/documentation/the-sling-engine/url-to-script-resolution.html
new file mode 100644
index 0000000..e29f836
--- /dev/null
+++ b/documentation/the-sling-engine/url-to-script-resolution.html
@@ -0,0 +1,89 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>URL to Script Resolution</h1></header><p>[TOC]</p>
+<p>This page explains how Sling maps URLs to a script or and servlet.</p>
+<p>See also <a href="/documentation/the-sling-engine/servlets.html">Servlets and Scripts</a> which provides detailed info about how to register servlets.</p>
+<p>First of all Sling looks up the resource identified by the URL - typically a path inside the JCR repository, which is annotated by the <code>sling:resourceType</code> property which defines the resource type of that resource. Using this resource type (which is kind of a relative path, eg. "myblog/comment"), scripts or servlets are looked up. For more details about how the initial resource is identified for a specific request URL look at <a href="/documentation/the-sling-engine/url-decomposition.html">URL decomposition</a>.</p>
+<p>Scripts and servlets are itself resources in Sling and thus have a resource path: this is either the location in the JCR repository, the resource type in a servlet component configuration or the "virtual" bundle resource path (if a script is provided inside a bundle without being installed into the JCR repository).</p>
+<p>For the whole Truth about script resolution, see the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/servlets/resolver/src/test/java/org/apache/sling/servlets/resolver/internal/helper/ScriptSelectionTest.java">ScriptSelectionTest</a> class. If you see interesting cases that are not covered there, please let us know via the Sling users mailing list.</p>
+<p>TODO: explain super types, servlet path mappings, node type resource types (<code>my:type -> my/type</code>)</p>
+<h2>Fundamental: Scripts and Servlets are equal</h2>
+<p>In the following discussion, I will write about scripts. This will always include servlets as well. In fact, internally, Sling only handles with Servlets, whereas scripts are packed inside a Servlet wrapping and representing the script.</p>
+<h2>Base: Resource Type Inheritance</h2>
+<p>While not exactly part of our discussion, resource type inheritance as implemented for <a href="https://issues.apache.org/jira/browse/SLING-278">SLING-278</a> plays a vital role in script resolution.</p>
+<p>Each resource type may have a resource super type, which may be defined in various ways. One example is having a <code>sling:resourceSuperType</code> property in the node addressed by the resource type. See <a href="http://www.mail-archive.com/sling-dev@incubator.apache.org/msg02365.html">http://www.mail-archive.com/sling-dev@incubator.apache.org/msg02365.html</a> and <a href="http://issues.apache.org/jira/browse/SLING-278">SLING-278</a> for more details.</p>
+<p>If a resource type has no explicit resource super type, the resource super type is assumed to be "sling/servlet/default". That is the resource type used for default script selection is also acting as a basic resource type much like java.lang.Object does for other types in the Java language.</p>
+<h2>Script Locations</h2>
+<p>Scripts are looked up in a series of locations defined by the ResourceResolver.getSearchPath() and the resource type (and resource super types) of the requested resource:</p>
+<p>{scriptPathPrefix}/{resourceTypePath}</p>
+<p>The pseudo code for iterating the locations would be something like:</p>
+<p>var type = resource.getResourceType(); while (type != null) { for (String root: resourceResolver.getSearchPath()) { String path = root + type.toPath(); findScriptsIn(path); }</p>
+<p>if (type == defaultServlet) { type = null; } else { type = getResourceSuperType(type); if (type == null) { type = defaultServlet; } } }</p>
+<h2>All requests are NOT equal</h2>
+<p>GET and HEAD request methods are treated differently than the other request methods. Only for GET and HEAD requests will the request selectors and extension be considered for script selection. For other requests the servlet or script name (without the script extension) must exactly match the request method.</p>
+<p>That is for a PUT request, the script must be PUT.esp or PUT.jsp. For a GET request with a request extension of html, the script name may be html.esp or GET.esp.</p>
+<h2>Scripts for GET requests</h2>
+<p>Apart for supporting scripts named after the request method, scripts handling GET and HEAD requests may be named differently for Sling to support a more elaborate processing order.</p>
+<p>Depending on whether request selectors are considered, a script may have two forms:</p>
+<ul>
+ <li>a. Ignoring request selectors (e.g. there are none in the request URI) <code>{resourceTypeLabel}.{requestExtension}.{scriptExtension}</code></li>
+ <li>b. Handling request selectors <code>{selectorStringPath}.{requestExtension}.{scriptExtension}</code></li>
+</ul>
+<p>The constituents of these script names are as follows:</p>
+<ul>
+ <li><code>{resourceTypeLabel}</code> - The last path segment of the path created from the resource type. This part is optional if the <code>{requestExtension}</code> is used in the script name. The resource type might either be set via the <code>sling:resourceType</code> property on the accessed node or if that property is not there its primary node type (property <code>jcr:primaryType</code>) is taken as fallback.</li>
+ <li><code>{requestExtension}</code> - The request extension. This part may be ommitted if the request extension is "html", otherwise this part is required. If this part is ommitted, the <code>{resourceTypeLabel}</code> is required in the case of ignoring the selectors.</li>
+ <li><code>{scriptExtension}</code> - The extension, e.g. "esp" or "jsp", identifying the scripting langauage used.</li>
+ <li><code>{selectorStringPath}</code> - The selector string converted to a path, along the lines of <code>selectorString.replace('.', '/')</code>. If less selectors are specified in the script name than given in the request, the script will only be taken into consideration if the given selectors are the <strong>first</strong> selectors in the request. This means <em>sel1/sel2.html.jsp</em> will be a candidate for the request url <em>/content/test.sel1.sel2.sel3.html</em> but not for <em>/content/test.sel3.sel1.sel2.html</em>. So the order of selectors is relevant!</li>
+</ul>
+<h2>Priority</h2>
+<p>The rules for script path priorization is defined as follows:</p>
+<ul>
+ <li>The more request selectors are matched, the better</li>
+ <li>A script including the request extension matches better than one without a request extension (for html only)</li>
+ <li>A script found earlier matches better than a script found later in the processing order. This means, that script closer to the original resource type in the resource type hierarchy is considered earlier.</li>
+</ul>
+<h2>Examples</h2>
+<p>Let's consider the following script paths for a request of a resource whose resource type is <code>slingsample</code> and the request selectors are <em>print.a4</em> and the request extension is <em>html</em>:</p>
+<ul>
+ <li>(0) GET.esp</li>
+ <li>(1) sample.esp</li>
+ <li>(2) html.esp</li>
+ <li>(3) print.esp</li>
+ <li>(4) print/a4.esp</li>
+ <li>(5) print.html.esp</li>
+ <li>(6) print/a4.html.esp</li>
+ <li>(7) a4.html.esp</li>
+ <li>(8) a4/print.html.esp</li>
+</ul>
+<p>The priority of script selection would be (starting with the best one): (6) - (4) - (5) - (3) - (2) - (1) - (0). Note that (4) is a better match than (5) because it matches more selectors even though (5) has an extension match where (4) does not. (7) is not a candidate because it does not include the first selector (print) and (8) is not a candidate because it has the wrong order of selectors.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/wrap-or-decorate-resources.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/wrap-or-decorate-resources.html b/documentation/the-sling-engine/wrap-or-decorate-resources.html
new file mode 100644
index 0000000..d0729a9
--- /dev/null
+++ b/documentation/the-sling-engine/wrap-or-decorate-resources.html
@@ -0,0 +1,42 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Wrap or Decorate Resources</h1></header><h2>Introduction</h2>
+<p>The Sling API provides an easy way to wrap or decorate a resource before returning. Use cases for this could for example be * overwrite resource type/resource super type (for example based on the resource path) * add metadata</p>
+<p>##</p>
+<p>To add a resource decorator just register one or more services which implement the interface <code>ResourceDecorator</code></p>
+<p>:::java interface ResourceDecorator { /** Optionally decorate the supplied Resource */ Resource decorate(Resource)</p>
+<p>/** Only called if using older versions of Sling, see below */ @Deprecated Resource decorate(Resource, HttpServletRequest) }</p>
+<p>The registered decorators will be called from the resource resolver for each resource returned. If the service decorates the resource it should return the new resource (often using a <code>ResourceWrapper</code> to wrap the original Resource). If the service does not want to decorate the resource, it should return the original resource or null.</p>
+<p>Starting with version 2.1.0 of the JCR Resource bundle, the two-argument <code>decorate</code> method is not called anymore. Implementors of this interface targeting both newer and older versions of this bundle are advised to implement this method as:</p>
+<p>:::java public Resource decorate(Resource resource, HttpServletRequest request) { return this.decorate(resource); }</p>
+<p>And use some other mechanism (e.g. a <code>ThreadLocal</code>) to obtain the current request if necessary.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/tutorials-how-tos.html
----------------------------------------------------------------------
diff --git a/documentation/tutorials-how-tos.html b/documentation/tutorials-how-tos.html
new file mode 100644
index 0000000..e05f226
--- /dev/null
+++ b/documentation/tutorials-how-tos.html
@@ -0,0 +1,33 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Tutorials & How-Tos</h1></header><p>{% for label, page in children %}* [{{ page.headers.title }}]({{ page.path }}) {% endfor %}</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/tutorials-how-tos/46-line-blog.html
----------------------------------------------------------------------
diff --git a/documentation/tutorials-how-tos/46-line-blog.html b/documentation/tutorials-how-tos/46-line-blog.html
new file mode 100644
index 0000000..009ebdb
--- /dev/null
+++ b/documentation/tutorials-how-tos/46-line-blog.html
@@ -0,0 +1,120 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>46 Line Blog</h1></header><p>This tutorial is based on the first <em>Sling Gems</em> on dev.day.com: The <a href="http://dev.day.com/microsling/content/blogs/main/sling-46-lines-blog.html">Sling gems: a blog in 46 lines of code</a>. It has slightly been adapted to fit here.</p>
+<p>In this tutorial, the SlingPostServlet and the sling.js library are brought together using 46 (no kidding: <em>fourty-six</em>) lines of code to create a simple blog (or let's say <em>bloggish</em>) application.</p>
+<p>I used this example in my <a href="http://www.slideshare.net/bdelacretaz/rapid-jcr-applications-development-with-sling-1196003">Rapid JCR application development with Apache Sling</a> presentation at ApacheCon US 09 in Oakland (slides will be available soon), and I think it's a good testimony to the power and simplicity of Sling.</p>
+<h2>Audience</h2>
+<p>Although this is a simple sample, it requires some custom settings to work. If you're just starting with Sling, <a href="/documentation/getting-started/discover-sling-in-15-minutes.html">Discover Sling in 15 minutes</a> might be a better choice.</p>
+<h2>Step 0: Start, configure and login to Sling</h2>
+<p>See <a href="/documentation/development/getting-and-building-sling.html">Getting and Building Sling</a> for how to start Sling. Start it on port 8888 for the below links to work.</p>
+<p>For this sample we need the optional <em>org.apache.sling.samples.path-based.rtp</em> bundle, if it's not present in the <a href="http://localhost:8888/system/console/bundles">OSGi console</a>, install and start it. That bundle is not released yet so you might need to build it yourself, from its <a href="http://svn.apache.org/repos/asf/sling/trunk/samples/path-based-rtp">source</a>. The bundle must then appear in the <a href="http://localhost:8888/system/console/bundles">OSGI console's list of bundles</a>, with name = <em>org.apache.sling.samples.path-based.rtp</em> and status = <em>Active</em>.</p>
+<p>Then, login using <a href="http://localhost:8888/?sling:authRequestLogin=1">http://localhost:8888/?sling:authRequestLogin=1</a> which should prompt you for a username and password, use <em>admin</em> and <em>admin</em>. Once that's done, <a href="http://localhost:8888/index.html">http://localhost:8888/index.html</a> should say <em>You are currently logged in as user <em>admin</em> to workspace <em>default</em></em>.</p>
+<h2>Step 1: Creating content</h2>
+<p>The easiest way to create content in Sling is to use an HTTP POST request, let's use a simple HTML form:</p>
+<html>
+<body>
+<h1>Sling microblog</h1>
+
+<div>
+<form method="POST">
+<input type="text" name="title" style="width:100%"/>
+
+<br/>Text:<br/>
+<textarea style="width:100%" name="text"></textarea>
+
+<br/>
+<input type="submit" value="save"/>
+<input type="hidden" name=":redirect" value="*.html"/>
+
+<!-- used by Sling when decoding request parameters -->
+<input type="hidden" name="_charset_" value="UTF-8"/>
+</form>
+</div>
+
+<!-- code of step 2 comes here -->
+</body>
+</html>
+<p>That's two input fields, a submit button and a hidden field that tells Sling what to do after the POST (in this case: redirect to the html view of the node that was just created).</p>
+<p>To test the form, start Sling and save the above script as {{/apps/blog/blog.esp}} [^esp] in the Sling repository - a WebDAV mount is the easiest way to do that. Browsing to <a href="http://localhost:8888/content/blog/*.html">http://localhost:8888/content/blog/*.html</a> [^port] should display the above form.</p>
+<p>[^esp]: ESP is Sling's server-side javascript language [^port]: This assumes your instance of Sling is running on port 8888. If that's not the case, adjust the example URLs accordingly.</p>
+<p>Input some data (using "foo" for the title, for the sake of our examples below), save the form, and Sling should display the form again, using the URL of the node that was just created.</p>
+<div class="note">
+If you get an error saying _javax.jcr.AccessDeniedException: ...not allowed to add or modify item_ it means that you are not logged in as user _admin_. See instructions above for logging in.
+</div>
+<p>At this point you're probably looking at an empty form with an URL ending in <em>foo</em>, if you used that for the title. Or <em>foo_0</em> or <em>foo_1</em> if other _foo_s already existed. Don't worry about not seeing your content, we'll fix that right away.</p>
+<h2>Step 2: Where's my content?</h2>
+<p>To verify that our content has been created, we can have a look at the JSON data at <a href="http://localhost:8888/content/blog/foo.tidy.json">http://localhost:8888/content/blog/foo.tidy.json</a>, which should display our new node's values:</p>
+<p>{ "jcr:primaryType": "nt:unstructured", "text": "This is the foo text", "title": "foo" }</p>
+<p>That's reassuring, but what we really want is for these values to be displayed on the editing form for our post.</p>
+<p>Thanks to the <em>sling.js</em> client library, we just need to add a <code>Sling.wizard()</code> call to our form to display those values. Let's first add a <code><head></code> element to our form to load the <em>sling.js</em> library, before the existing <code><body></code> of course:</p>
+<head>
+<script src="/system/sling.js"></script>
+</head>
+<p>And add the <code>Sling.wizard()</code> after the form, where we had the <em>code of step 2 comes here</em> comment:</p>
+<!-- code of step 2 comes here -->
+<script>Sling.wizard();</script>
+<p>Reloading the form at <code>http://localhost:8888/content/blog/*.html</code> and creating a new post should now redirect to an editable version of the post, with the form fields correctly initialized.</p>
+<p>We can now create and edit posts; let's add some navigation, using more of the <em>sling.js</em> functionality.</p>
+<h2>Step 3: Navigation</h2>
+<p>The <em>sling.js</em> library provides utilities to access and manipulate content. For our blog, we'll use the <code>getContent(path)</code> method to list the siblings of the current node.</p>
+<p>Add the following code to your script, after the <code>Sling.wizard()</code> call that was added in step 2:</p>
+<h3>Navigation</h3>
+<ul>
+<li><em><a href="/content/blog/*.html">[Create new post]</a></em></li>
+<script>
+var posts = Sling.getContent("/content/blog", 2);
+for(var i in posts) {
+document.write("<li>"
++ "<a href='/content/blog/" + i + ".html'>"
++ posts[i].title
++ "</a></li>");
+}
+</script>
+</ul>
+<p>The first link to <code>/content/blog/*</code> brings us back to our content creating form, which is nothing else than the editing form reading empty values and posting to the "magic star" URL.</p>
+<p>The rest of the javascript runs client-side, as it is not embedded in <code><% %></code> code markers, calls the <code>sling.getContent</code> method to get two levels of node data below <code>/content/blog</code>, and displays links to nodes that it finds.</p>
+<p>That's a basic navigation, of course, in a real blog we'd need some paging and contextualization to cope with large numbers of posts.</p>
+<p>Nevertheless, with this addition our ESP script allows us to create, edit and navigate blog posts - not bad for 46 lines of code, including comments, whitespace and output formatting.</p>
+<h2>Step 4: Data first, structure later</h2>
+<p>You might have heard this mantra, which we apply in many areas of Sling.</p>
+<p>In this case, adding a new field to our blog posts could not be easier: just add an input field to the form, and Sling will do the rest.</p>
+<p>Adding this inside our script's <code><form></code> element, for example:</p>
+<p><br/>Author:<br/> <input type="author" name="author" style="width:100%"/></p>
+<p>Allows us to add an author name to our blog posts. No need to define anything at the repository level, as Sling is using it in unstructured mode in this case, and no need to migrate existing data, the author field of existing posts will simply be empty.</p>
+<h2>I want my ESP!</h2>
+<p>Now wait...we said we were going to create an ESP script, but our "application" is just static HTML and some client javascript at this point.</p>
+<p>That's correct - as we are using only Sling client-facing features at this point (HTTP POST and <code>sling.js</code>), we do not necessarily need to use ESP code.</p>
+<p>To keep things simple, we'll refrain from adding ESP-based features at this point, but you can of course use any ESP code in the <em>blog.esp</em> "script".</p>
+<h2>That's the power of Sling</h2>
+<p>The 46-line blog is a good example of the power of Sling. It leverages the <a href="/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">SlingPostServlet</a>, which handles POST requests in a form-friendly way, and the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/servlets/post/src/main/resources/system/sling.js"><code>sling.js</code></a> client library, which provides high-level functionality on the client side.</p>
+<p>///Footnotes Go Here///</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html
----------------------------------------------------------------------
diff --git a/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html b/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html
new file mode 100644
index 0000000..308f8c9
--- /dev/null
+++ b/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html
@@ -0,0 +1,67 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Getting Resources and Properties in Sling</h1></header><p>The Resource is one of the central parts of Sling. Extending from JCR's Everything is Content, Sling assumes Everthing is a Resource. Thus Sling is maintaining a virtual tree of resources, which is a merger of the actual contents in the JCR Repository and resources provided by so called resource providers. By doing this Sling fits very well in the paradigm of the REST architecture.</p>
+<p>In this article we will explore a few ways to programmatically map a resource path (String) to a resource object (Resource) and its properties in Sling, from within an OSGI service, a servlet and a JSP.</p>
+<p>The whole game consists in first getting a <code>ResourceResolver</code> and then getting the <code>Resource</code> itself.</p>
+<h2>Within an OSGI Service/Compoment</h2>
+<p>You can access a resource through the <code>ResourceResolverFactory</code> service:</p>
+<h1>!java</h1>
+<p>@Reference private ResourceResolverFactory resolverFactory;</p>
+<p>public void myMethod() { try { String resourcePath = "path/to/resource"; ResourceResolver resourceResolver = resolverFactory.getAdministrativeResourceResolver(null); Resource res = resourceResolver.getResource(resourcePath); // do something with the resource // when done, close the ResourceResolver resourceResolver.close(); } catch (LoginException e) { // log the error } }</p>
+<h2>Within a Servlet</h2>
+<p>You can access the resource defined by the request URL through the <code>SlingHttpServletRequest</code>:</p>
+<h1>!java</h1>
+<p>// req is the SlingHttpServletRequest Resource res = req.getResource();</p>
+<p>You can access any resource by first accessing the <code>ResourceResolver</code>:</p>
+<h1>!java</h1>
+<p>String resourcePath = "path/to/resource"; // req is the SlingHttpServletRequest ResourceResolver resourceResolver = req.getResourceResolver(); Resource res = resourceResolver.getResource(resourcePath);</p>
+<h2>Within a JSP file</h2>
+<p>When you use the <code><sling:defineObjects></code> tag in a JSP file, you have access to a few handy objects, one of them is <code>resource</code>, the resource that is resolved from the URL. Another one is <code>resourceResolver</code>, the <code>ResourceResolver</code> defined through the <code>SlingHttpServletRequest</code>.</p>
+<p>To access a resource:</p>
+<h1>!jsp</h1>
+<p><sling:defineObjects> <% String resourcePath = "path/to/resource"; Resource res = resourceResolver.getResource(resourcePath); %></p>
+<p>If needed you can adapt a Sling Resource to a JCR Node:</p>
+<h1>!java</h1>
+<p>Node node = resource.adaptTo(Node.class);</p>
+<p>Note: <code>resource.adaptTo(Node.class)</code> may return null if the resource is not backed by a JCR node. This is particularly the case for <code>NonExistingResource</code> resources or resource provided by a non-JCR resource provider.</p>
+<h2>Accessing a Property</h2>
+<p>The <code>ValueMap</code> is an easy way to access properties of a resource. With most resources you can use <code>Adaptable.adaptTo(Class)</code> to adapt the resource to a value map:</p>
+<h1>!java</h1>
+<p>// res is the Resource ValueMap properties = res.adaptTo(ValueMap.class);</p>
+<p>You can also access the properties through the <code>ResourceUtil</code> utility class:</p>
+<h1>!java</h1>
+<p>// res is the Resource ValueMap properties = ResourceUtil.getValueMap(res);</p>
+<p>Then, to access a specific String property called <code>propName</code>:</p>
+<h1>!java</h1>
+<p>String rule = properties.get(propName, (String) null);</p>
+<p>For more details about resources and how to access them in Sling, you can refer to the <a href="/documentation/the-sling-engine/resources.html">Sling documentation about Resources</a>.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html
----------------------------------------------------------------------
diff --git a/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html b/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html
new file mode 100644
index 0000000..e55ee4e
--- /dev/null
+++ b/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html
@@ -0,0 +1,115 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>How to Manage Job in Sling</h1></header><p>Apache Sling supports the execution of jobs with the guarantee of processing the job at least once. This can be seen as an extensions of the OSGi event admin, although jobs are not started or processed by OSGi events leveraging the OSGi event admin.</p>
+<p>For more details please refer to the following resources:</p>
+<ul>
+ <li>[Eventing, Jobs and Scheduling section]({{ refs.eventing-and-jobs.path }}) to get detailed information on the eventing mechanisms in Sling.</li>
+ <li>Package <a href="http://www.osgi.org/javadoc/r4v42/org/osgi/service/event/package-summary.html">org.osgi.service.event</a> of the OSGI API.</li>
+ <li>Package <a href="/apidocs/sling6/org/apache/sling/event/package-summary.html">org.apache.sling.event</a> of the Sling API.</li>
+</ul>
+<p>This page drives you through the implementation of two services that rely on the Sling job mechanism. The services implement the following use case: whenever a file is uploaded to a temporary location in your web application, the file is moved to a specific location according to its MIME type.</p>
+<h2>Introduction</h2>
+<p>You will now implement the logic to listen to files posted to <em>/tmp/dropbox</em> and to move them to the appropriate locations depending on the MIME type:</p>
+<ul>
+ <li>images (.png) are moved to <strong>/dropbox/images/</strong></li>
+ <li>music (.mp3) are moved to <strong>/dropbox/music/</strong></li>
+ <li>movies (.avi) are moved to <strong>/dropbox/movies/</strong></li>
+ <li>otherwise the files are moved to <strong>/dropbox/other/</strong></li>
+</ul>
+<p>To do that, you will implement two services. The first one, called <strong>DropBoxService</strong>:</p>
+<ul>
+ <li>Listens to specific OSGi events (Sling resource added events)</li>
+ <li>Starting a job event if a resource has been added to <strong>/tmp/dropbox</strong>.</li>
+</ul>
+<p>The second one, called <strong>DropBoxEventHandler</strong>:</p>
+<ul>
+ <li>Processes the former jobs</li>
+ <li>Moves the file according to its extension.</li>
+</ul>
+<h2>Listening to OSGI Events</h2>
+<p>To listen to OSGi events in Sling you just need to register an <strong>org.osgi.service.event.EventHandler</strong> service with an <strong>event.topics</strong> property that describes which event topics the handler is interested in.</p>
+<p>To listen to a Sling <strong>resource added</strong> events, for example, you'll set the <em>event.topics</em> property to <strong>org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED</strong> in the class annotations:</p>
+<p>:::java @Property(name=org.osgi.service.event.EventConstants.EVENT_TOPIC, value=org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED)</p>
+<p>The javadocs of the TOPIC_ constants in the <a href="/apidocs/sling6/org/apache/sling/api/SlingConstants.html">org.apache.sling.api.SlingConstants</a> class lists and explains the available event topics available in Sling.</p>
+<h2>Starting a job</h2>
+<p>To start a job, the <em>JobManager</em> service can be used. It needs a job topic and a payload. In our case we define our dropbox job topic and give the resource path as the payload:</p>
+<p>:::java final String resourcePath = ...; // path to the resource to handle final Map<String, Object> payload = new HashMap<String, Object>(); payload.put("resourcePath", resourcePath); // start job this.jobManager.addJob(JOB_TOPIC, payload);</p>
+<p>To receive the resource event, the service needs to implement the <strong>org.osgi.service.event.EventHandler</strong> interface and register it as an EventHandler service:</p>
+<p>:::java @Component(immediate=true) // immediate should only be used in rare cases (see below) @Service(value=EventHandler.class) public class DropBoxService implements EventHandler { ... }</p>
+<p>Usually a service should be lazy and therefore not declare itself to be immediate (in the Component annotation). However as this service is an event handler and might receive a lot of events even concurrently, it is advised to set the immediate flag to true on the component. Otherwise our event handler would be created and destroyed with every event coming in.</p>
+<p>To start the job we need a reference to the JobManager:</p>
+<p>:::java @Reference private JobManager jobManager;</p>
+<p>The job topic for dropbox job events needs to be defined:</p>
+<p>:::java /** The job topic for dropbox job events. */ public static final String JOB_TOPIC = "com/sling/eventing/dropbox/job";</p>
+<p>The <strong>org.osgi.service.event.EventHandler#handleEvent(Event event)</strong> method needs to be implemented:</p>
+<p>Its logic is as follows:</p>
+<ul>
+ <li>The OSGI event is analyzed.</li>
+ <li>If the event is a file that has been added to <em>/tmp/dropbox</em>:</li>
+ <li>An job is created with 1 property:</li>
+ <li>A property for the file path.</li>
+ <li>The job is started</li>
+</ul>
+<p>For example:</p>
+<p>:::java public void handleEvent(final Event event) { // get the resource event information final String propPath = (String) event.getProperty(SlingConstants.PROPERTY_PATH); final String propResType = (String) event.getProperty(SlingConstants.PROPERTY_RESOURCE_TYPE);</p>
+<p>// a job is started if a file is added to /tmp/dropbox if ( propPath.startsWith("/tmp/dropbox") && "nt:file".equals(propResType) ) { // create payload final Map<String, Object> payload = new HashMap<String, Object>(); payload.put("resourcePath", propPath); // start job this.jobManager.addJob(JOB_TOPIC, payload); logger.info("the dropbox job has been started for: {}", propPath); } }</p>
+<p>The complete code for the <strong>DropBoxService</strong> service is available <a href="DropBoxService.java">here</a>.</p>
+<h2>Consuming Job Events</h2>
+<p>Now that you have implemented a service that starts a job when a file is uploaded to <strong>/tmp/dropbox</strong>, you will implement the service <strong>DropBoxEventHandler</strong> that processes those jobs and moves the files to a location according to their MIME types.</p>
+<p>To process to the job that have been defined before the property <strong>job.topics</strong> needs to be set to <strong>DropBoxService.JOB_TOPIC</strong> in the class annotations:</p>
+<p>:::java @Property(name="job.topics", value=DropBoxService.JOB_TOPIC)</p>
+<p>In addition the service needs to implement the <strong>org.apache.sling.event.jobs.consumer.JobConsumer</strong> interface:</p>
+<p>:::java public class DropBoxEventHandler implements JobConsumer {</p>
+<p>Some class fields need to be defined:</p>
+<ul>
+ <li>The default logger.</li>
+ <li>The references to the ResourceResolverFactory services, which are used in the implementation.</li>
+ <li>The destination paths of the files.</li>
+</ul>
+<p>For example:</p>
+<p>:::java /** Default log. */ protected final Logger logger = LoggerFactory.getLogger(this.getClass());</p>
+<p>@Reference private ResourceResolverFactory resolverFactory;</p>
+<p>private final static String IMAGES_PATH = "/dropbox/images/"; private final static String MUSIC_PATH = "/dropbox/music/"; private final static String MOVIES_PATH = "/dropbox/movies/"; private final static String OTHER_PATH = "/dropbox/other/";</p>
+<p>The <strong>org.apache.sling.event.jobs.consumer.JobConsume#process(Job job)</strong> method needs to be implemented:</p>
+<p>Its logic is as follows:</p>
+<ul>
+ <li>The resource path is extracted from the job.</li>
+ <li>The resource is obtained from the resource path.</li>
+ <li>If the resource is a file, the destination path is defined based on the file MIME type.</li>
+ <li>The file is moved to the new location by using a JCR session (as the Sling Resource API doesn't support move atm)</li>
+</ul>
+<p>or in Java Code:</p>
+<p>:::java public JobResult process(final Job job) { ResourceResolver adminResolver = null; try { adminResolver = resolverFactory.getAdministrativeResourceResolver(null);</p>
+<p>final String resourcePath = (String) job.getProperty("resourcePath"); final String resourceName = resourcePath.substring(resourcePath.lastIndexOf("/") + 1);</p>
+<p>final Resource res = adminResolver.getResource(resourcePath); if ( res.isResourceType("nt:file") ) { final String mimeType = res.getResourceMetadata().getContentType(); String destDir; if (mimeType.equals("image/png")) { destDir = IMAGES_PATH; } else if (mimeType.equals("audio/mpeg")) { destDir = MUSIC_PATH; } else if (mimeType.equals("video/x-msvideo")) { destDir = MOVIES_PATH; } else { destDir = OTHER_PATH; } final Session adminSession = adminResolver.adaptTo(Session.class); adminSession.move(resourcePath, destDir + resourceName); adminSession.save(); logger.info("The file {} has been moved to {}", resourceName, destDir); } return JobResult.OK; } catch (final Exception e) { logger.error("Exception: " + e, e); return JobResult.FAILED; } finally { if (adminResolver != null) { adminResolver.close(); } } }</p>
+<p>The complete code for the <strong>DropBoxEventHandler</strong> service is available <a href="DropBoxEventHandler.java">here</a>.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ 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.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>