incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling > FAQ
Date Fri, 26 Nov 2010 10:29:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=SLING&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/SLING/FAQ">FAQ</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Introduce two entries as proposed<br />
    </div>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>If on the other hand you
cannot prevent the installation of such bundles and hence the export of the respective packages,
you might want to set the {{org.osgi.framework.bootdelegation}} property conditionally as
described above in the answer to how this property is supported in Sling. This ensures the
property is only set, if the classes are actually available. This should be used as a fall
back only, if the {{org.osgi.framework.system.packages}} method does not work. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br> <br>h2. Miscellaneous <br> <br>h3. Why can&#39;t I connect
to Sling&#39;s WebDAV using Windows NetworkDriveMapping ? <br> <br>Since Windows
XP SP 2 (thus also affects Windows Vista, Windows 7, etc.) support for HTTP Basic authentication
is by default switched off unless using HTTPS. Support can be switched on again by setting
a Windows registry value. See Microsoft Knowledge Base entry [841215|http://support.microsoft.com/kb/841215]
for full details and warnings regarding modifying registry entries. <br> <br>h3.
Why is my WebDAV connection so slow on Windows ? <br> <br>One reason might be
automatic proxy detection being enabled in the Internet Options. See the [Fix Slow WebDAV
Performance in Windows 7|http://oddballupdate.com/2009/12/18/fix-slow-webdav-performance-in-windows-7/]
for the solution. <br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="FAQ-FrequentlyAskedQuestions"></a>Frequently Asked
Questions</h1>

<p>This page lists a series of common questions and answers. It is of course work in
progress ...</p>

<div>
<ul>
    <li><a href='#FAQ-Administration'>Administration</a></li>
<ul>
    <li><a href='#FAQ-HowdoIchangeJackrabbit%27sadminpassword%3F'>How do I change
Jackrabbit's admin password?</a></li>
</ul>
    <li><a href='#FAQ-RESTfulAPI'>RESTful API</a></li>
<ul>
    <li><a href='#FAQ-HowdoIcreateanodebypostingajsondocumenttoaURL%3F'>How do
I create a node by posting a json document to a URL?</a></li>
    <li><a href='#FAQ-Whatsospecialaboutthe%27content%27%2C%27apps%27and%27%27urls%3F'>What
so special about the 'content','apps' and '*' urls?</a></li>
    <li><a href='#FAQ-Ipostedaresource%2Cwherediditgo%3F'>I posted a resource,
where did it go?</a></li>
</ul>
    <li><a href='#FAQ-ScriptsandServlets'>Scripts and Servlets</a></li>
<ul>
    <li><a href='#FAQ-HowdoIgeneratelinkstopreviousversionsofanode%3F'>How do
I generate links to previous versions of a node?</a></li>
    <li><a href='#FAQ-HowdoIfindoutwhyagivenscriptorservletispreferredtoanotherwhenprocessingarequest%3F'>How
do I find out why a given script or servlet is preferred to another when processing a request?</a></li>
    <li><a href='#FAQ-HowdoIrenderascriptforastar%22%22resource%3F'>How do I render
a script for a star "*" resource?</a></li>
    <li><a href='#FAQ-Howtoreplacethedefaultjsonrenderer%28forexample%29withmyown%3F'>How
to replace the default json renderer (for example) with my own?</a></li>
    <li><a href='#FAQ-Howtoexecutescriptsdirectly%3F'>How to execute scripts directly?</a></li>
    <li><a href='#FAQ-HowdoIcreateanewscriptengine%3F'>How do I create a new script
engine?</a></li>
</ul>
    <li><a href='#FAQ-Workingwithbundles'>Working with bundles</a></li>
<ul>
    <li><a href='#FAQ-Isthereaneasywaytoupdatebundlesinarunninginstallationduringdevelopment%3F'>Is
there an easy way to update bundles in a running installation during development?</a></li>
</ul>
    <li><a href='#FAQ-Classloadingissues'>Classloading issues</a></li>
<ul>
    <li><a href='#FAQ-AccessingClassesfromtheEnvironment'>Accessing Classes from
the Environment</a></li>
    <li><a href='#FAQ-Howarethe%7B%7Bsling.bootdelegation%7D%7Dpropertiesused%3F'>How
are the <tt>sling.bootdelegation</tt> properties used ?</a></li>
    <li><a href='#FAQ-HowdoesSlingsupportthe%7B%7Borg.osgi.framework.system.packages%7D%7DProperty%3F'>How
does Sling support the <tt>org.osgi.framework.system.packages</tt> Property ?</a></li>
    <li><a href='#FAQ-Shouldthe%7B%7Borg.osgi.framework.bootdelegation%7D%7Dorthe%7B%7Borg.osgi.framework.system.packages%7D%7DPropertybeused%3F'>Should
the <tt>org.osgi.framework.bootdelegation</tt> or the <tt>org.osgi.framework.system.packages</tt>
Property be used ?</a></li>
</ul>
    <li><a href='#FAQ-Miscellaneous'>Miscellaneous</a></li>
<ul>
    <li><a href='#FAQ-Whycan%27tIconnecttoSling%27sWebDAVusingWindowsNetworkDriveMapping%3F'>Why
can't I connect to Sling's WebDAV using Windows NetworkDriveMapping ?</a></li>
    <li><a href='#FAQ-WhyismyWebDAVconnectionsoslowonWindows%3F'>Why is my WebDAV
connection so slow on Windows ?</a></li>
</ul>
</ul></div>

<h2><a name="FAQ-Administration"></a>Administration</h2>

<h3><a name="FAQ-HowdoIchangeJackrabbit%27sadminpassword%3F"></a>How do
I change Jackrabbit's admin password?</h3>

<p>Using the userManager:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   curl \ 
    -F<span class="code-quote">"oldPwd=admin"</span> \
    -F<span class="code-quote">"newPwd=Fritz"</span> \   
    -F<span class="code-quote">"newPwdConfirm=Fritz"</span> \
    http:<span class="code-comment">//admin:admin@localhost:8080/system/userManager/user/admin.changePassword.html
    </span>
</pre>
</div></div>

<p>You will also have to set that password in the Felix Web Management Console (/system/console/configMgr)
under "Apache Sling Embedded JCR Repository." This is used by Sling to create an admin JCR
session (using SlingRepository.loginAdministrative()) for components that need to have full
access to the repository.</p>

<p>Note: Only after restarting the framework the old password will become invalid (as
of 09-11-10).</p>

<p>Note: depending on the login module used in Jackrabbit, the password might not be
checked at all (SimpleLoginModule, standard in Jackrabbit &lt;= 1.4). Since Jackrabbit
1.5, the DefaultLoginModule provides full user support.</p>


<h2><a name="FAQ-RESTfulAPI"></a>RESTful API</h2>

<h3><a name="FAQ-HowdoIcreateanodebypostingajsondocumenttoaURL%3F"></a>How
do I create a node by posting a json document to a URL?</h3>

<p>At the moment, you cannot do this. (Soon to change as per <a href="https://issues.apache.org/jira/browse/SLING-1172"
class="external-link" rel="nofollow">SLING-1172</a>&#33;)  Instead, each value
must be a field in the request POST.  For example, suppose you have the json document:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  {
    <span class="code-quote">"greetings"</span>:<span class="code-quote">"Hello,
World!"</span>,
    <span class="code-quote">"multi"</span> : [<span class="code-quote">"first"</span>,<span
class="code-quote">"second"</span>],
    <span class="code-quote">"translations"</span> : { <span class="code-quote">"en"</span>:
<span class="code-quote">"Hello"</span>, <span class="code-quote">"zh"</span>,
<span class="code-quote">"你好"</span> }
  }
</pre>
</div></div>

<p>You would do a post such as:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
curl -F<span class="code-quote">"greetings=Hello, World!"</span> -F<span class="code-quote">"mult=first"</span>
-F<span class="code-quote">"multi=second"</span> -F<span class="code-quote">"translations/en=Hello"</span>
-F<span class="code-quote">"translations/zh=你好"</span> http:<span class="code-comment">//admin:admin@localhost:8080/content/../../..</span>
</pre>
</div></div>

<h3><a name="FAQ-Whatsospecialaboutthe%27content%27%2C%27apps%27and%27%27urls%3F"></a>What
so special about the 'content','apps' and '*' urls?</h3>

<p>'apps' is reserved for matching scripts evaluated by sling.</p>

<p>The "*" url is used for POSTing to a child node.</p>

<p>By default, if a resource cannot be found from the root url, sling will try appending
"content".  For example, if you request the following non-existent resource:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
http:<span class="code-comment">//localhost:8080/blog/first_post</span>
</pre>
</div></div>

<p>Sling will look in:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
http:<span class="code-comment">//localhost:8080/content/blog/first_post</span>
</pre>
</div></div>

<p>Before returning a 404.</p>

<h3><a name="FAQ-Ipostedaresource%2Cwherediditgo%3F"></a>I posted a resource,
where did it go?</h3>

<p>Let's start by creating a resource:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
curl -F<span class="code-quote">"greetings=Hello, World"</span> -F<span class="code-quote">"translations/en=Hello"</span>
-F<span class="code-quote">"translations/es=hola"</span> http:<span class="code-comment">//admin:admin@localhost:8080/content/greet</span>
</pre>
</div></div>

<p>We can now view the resource with:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
curl http:<span class="code-comment">//admin:admin@localhost:8080/content/greet.json
</span>{<span class="code-quote">"greetings"</span>:<span class="code-quote">"Hello,
World"</span>,<span class="code-quote">"jcr:created"</span>:<span class="code-quote">"Fri
Nov 06 2009 16:26:23 GMT-0800"</span>,<span class="code-quote">"jcr:primaryType"</span>:<span
class="code-quote">"sling:Folder"</span>}
</pre>
</div></div>

<p>Notice that the "greet" resource is a sling:Folder.  Also notice that it's a little
hard to read the result.  Let's tidy it up:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
curl http:<span class="code-comment">//admin:admin@localhost:8080/content/greet.tidy.json
</span>{
  <span class="code-quote">"greetings"</span>: <span class="code-quote">"Hello,
World"</span>,
  <span class="code-quote">"jcr:created"</span>: <span class="code-quote">"Fri
Nov 06 2009 16:26:23 GMT-0800"</span>,
  <span class="code-quote">"jcr:primaryType"</span>: <span class="code-quote">"sling:Folder"</span>
}
</pre>
</div></div>

<p>But where did our translations go?  To get them, we have to request 2 nodes down
into the tree:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
curl http:<span class="code-comment">//admin:admin@localhost:8080/content/greet.tidy.2.json
</span>{
  <span class="code-quote">"greetings"</span>: <span class="code-quote">"Hello,
World"</span>,
  <span class="code-quote">"jcr:created"</span>: <span class="code-quote">"Fri
Nov 06 2009 16:26:23 GMT-0800"</span>,
  <span class="code-quote">"jcr:primaryType"</span>: <span class="code-quote">"sling:Folder"</span>,
  <span class="code-quote">"translations"</span>: {
    <span class="code-quote">"en"</span>: <span class="code-quote">"Hello"</span>,
    <span class="code-quote">"jcr:created"</span>: <span class="code-quote">"Fri
Nov 06 2009 16:26:23 GMT-0800"</span>,
    <span class="code-quote">"es"</span>: <span class="code-quote">"hola"</span>,
    <span class="code-quote">"jcr:primaryType"</span>: <span class="code-quote">"sling:Folder"</span>
  }
}
</pre>
</div></div>

<p>However, if we try and get the resource without an extension, we get nothing found.
 This is because we're requesting a folder, so sling tries to find either an index.html or
return a directory list, just like a normal directory on a webserver.</p>

<p>To fix this, we can use a script and a sling resource type.  Let's update our greeting
document:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
curl F<span class="code-quote">"sling:resourceType=greeting"</span> -F<span
class="code-quote">"greetings=Hello, World"</span> -F<span class="code-quote">"translations/en=Hello"</span>
-F<span class="code-quote">"translations/es=hola"</span> http:<span class="code-comment">//admin:admin@localhost:8080/content/greet</span>
</pre>
</div></div>

<p>Then we'll post a simple esp script to apps:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>GET.esp</b></div><div class="codeContent
panelContent">
<pre class="code-java">
&lt;html&gt;
  &lt;head&gt;&lt;title&gt;&lt;/title&gt;&lt;/head&gt;
  &lt;body&gt;
    &lt;h1&gt;&lt;%= currentNode.greetings %&gt;&lt;/h1&gt;
  &lt;/body&gt;
&lt;/html&gt;
</pre>
</div></div>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
curl -X MKCOL http:<span class="code-comment">//admin:admin@gandalf.local:8080/apps/greeting
</span>curl -T GET.esp http:<span class="code-comment">//admin:admin@localhost:8080/apps/greeting/GET.esp</span>
</pre>
</div></div>

<p>Now you should be able to see an HTML version of the resource at <a href="http://localhost.local:8080/content/greet"
class="external-link" rel="nofollow">http://localhost.local:8080/content/greet</a>.
 This script matches the sling:resourceType we set and the HTTP method we used.  Note that
resourceType matches must be exact.</p>

<h2><a name="FAQ-ScriptsandServlets"></a>Scripts and Servlets</h2>

<h3><a name="FAQ-HowdoIgeneratelinkstopreviousversionsofanode%3F"></a>How
do I generate links to previous versions of a node?</h3>

<p>Assuming a versionable node at /content/versioned, with sling:resourceType=foo, here's
the /apps/foo/html.esp script that handles the /content/versioned.html request:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;html&gt;

&lt;%
<span class="code-comment">// assume we have a versionable node
</span><span class="code-keyword">var</span> iter = currentNode.getVersionHistory().getAllVersions();
%&gt;

  &lt;body&gt;
    &lt;h1&gt;Versions of node &lt;%= currentNode.getPath() %&gt;&lt;/h1&gt;
    &lt;%
    	<span class="code-keyword">while</span>(iter.hasNext()) {
    	  <span class="code-keyword">var</span> v = iter.nextVersion();

    	  <span class="code-comment">// use UUID of version node to build a link, and add
a .version
</span>    	  <span class="code-comment">// selector to have another esp script
process that request
</span>    	  <span class="code-keyword">var</span> uuid = v[<span class="code-quote">"jcr:uuid"</span>];
    	  <span class="code-keyword">var</span> vPath = currentNode.getPath() + <span
class="code-quote">".version."</span> + uuid + <span class="code-quote">".html"</span>;

    	  <span class="code-comment">// Use Version creation date as the link text
</span>    	  <span class="code-keyword">var</span> vDate = v.getCreated().getTime();

    	  %&gt;
    	  &lt;a href=<span class="code-quote">"&lt;%= vPath %&gt;"</span>&gt;&lt;%=
vDate %&gt;&lt;/a&gt;&lt;br/&gt;
    	  &lt;%
    	}
    %&gt;
  &lt;/body&gt;
&lt;/html&gt;
</pre>
</div></div>

<p>The links to the individual versions look like: /content/versioned.version.313016e1.html
where the first .version. selector causes a different esp script to be called to display the
version data, and the 313016e1 selector is the UUID of the versioned node (real UUIDs are
longer).</p>

<p>That request is handled by this second script, /apps/foo/version/html.esp (name will
change soon, SLING-387):</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;html&gt;

&lt;%
	<span class="code-comment">// Get version node UUID, which is the second selector
</span>	<span class="code-keyword">var</span> uuid = <span class="code-keyword">null</span>;
	<span class="code-keyword">var</span> sel = request.getRequestPathInfo().getSelectors();
	<span class="code-keyword">if</span>(sel.length &gt;= 2) {
		uuid = sel[1];
	} <span class="code-keyword">else</span> {
		response.sendError(400, <span class="code-quote">"Version node UUID must be given
as second selector"</span>);
	}

	<span class="code-comment">// Get version node
</span>	<span class="code-keyword">var</span> v = currentNode.getSession().getNodeByUUID(uuid);
	<span class="code-keyword">var</span> frozen = v.getNode(<span class="code-quote">"jcr:frozenNode"</span>);
	<span class="code-keyword">var</span> title = frozen.title;		
%&gt;

  &lt;body&gt;
    &lt;h1&gt;Version of node &lt;%= currentNode.getPath() %&gt;&lt;/h1&gt;
    Name: &lt;b&gt;&lt;%= v.getName() %&gt;&lt;/b&gt;&lt;br/&gt;
    UUID: &lt;b&gt;&lt;%= uuid %&gt;&lt;/b&gt;&lt;br/&gt;
    Path: &lt;b&gt;&lt;%= v.getPath() %&gt;&lt;/b&gt;&lt;br/&gt;
    Frozen node path: &lt;b&gt;&lt;%= frozen.getPath() %&gt;&lt;/b&gt;&lt;br/&gt;

    &lt;% <span class="code-keyword">if</span>(title) { %&gt;
	    Frozen node title: &lt;b&gt;&lt;%= frozen.getProperty(<span class="code-quote">"title"</span>)
%&gt;&lt;/b&gt;&lt;br/&gt;
    &lt;% } <span class="code-keyword">else</span> { %&gt;
    	Frozen node does not have a title property
    &lt;% } %&gt;
  &lt;/body&gt;
&lt;/html&gt;
</pre>
</div></div>

<p>Which uses the UUID selector to retrieve the versioned node.</p>

<p>The second trick here is that the versioned data is saved as a "jcr:frozenNode" node
under the Version node. This is explained for example at <a href="http://www.onjava.com/lpt/a/6784"
class="external-link" rel="nofollow">http://www.onjava.com/lpt/a/6784</a> .</p>

<h3><a name="FAQ-HowdoIfindoutwhyagivenscriptorservletispreferredtoanotherwhenprocessingarequest%3F"></a>How
do I find out why a given script or servlet is preferred to another when processing a request?</h3>

<p>See <a href="https://issues.apache.org/jira/browse/SLING-580" class="external-link"
rel="nofollow">SLING-580</a>, the SlingServletResolver class logs detailed information
(at the DEBUG level) to indicate in which order the candidate scripts and servlets are considered
for processing a request.</p>

<h3><a name="FAQ-HowdoIrenderascriptforastar%22%22resource%3F"></a>How do
I render a script for a star "*" resource?</h3>

<p>"*" resources do not have a sling:resourceType which can cause confusion when you're
trying to render a specific script.  Consider:</p>

<p>Suppose we have content such as:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>content
--gradapp
----application
--------app1
--------app2
------------tabs
----------------tab1
----------------tab2

apps
--gradapp
----application
--------edit.esp
--------html.esp
--------list.esp
----tab
--------edit.esp
</pre>
</div></div>

<p>In this case, <a href="http://localhost:8888/gradapp/application/app1.edit.html"
class="external-link" rel="nofollow">http://localhost:8888/gradapp/application/app1.edit.html</a>
will provide an edit page for the app1 resource using the script from apps/gradapp/application/edit.esp.
 However, <a href="http://localhost:8888/gradapp/application/*.edit.html" class="external-link"
rel="nofollow">http://localhost:8888/gradapp/application/*.edit.html</a> will not
use that edit.esp script.</p>

<p>By default the "star resource" does not have a resource type, so you get the default
rendering. To give it a specific resource type based on its path, you can install and start
the samples/path-based-rtp bundle.</p>

<p>Another suggestion is to register a generic node creation form script, e.g. at /apps/sling/servlet/default/create.esp.
You should be able to invoke that script by browsing to /gradapp/application/*.create. If
you want the create.esp script to be able to render different forms<br/>
(e.g. one for applications, one for tabs) you can use different selectors, like *.createTab,
*.createApp, etc.</p>

<p>An older version of this answer suggests using a query parameter, this also works
but we recommend using selectors in Sling, leading to cleaner and cachable URLs.</p>

<p>So this would work:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   /gradapp/application/*.create?typeToCreate=application
</pre>
</div></div>
<p>for creating application nodes and</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   /gradapp/application/*.create?typeToCreate=tab
</pre>
</div></div>
<p>for showing the tab form, but this is the preferred way:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   /gradapp/application/*.createApp
</pre>
</div></div>
<p>for creating application nodes and</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   /gradapp/application/*.createTab
</pre>
</div></div>
<p>for showing the tab form.</p>

<p>See: <a href="http://markmail.org/message/htl6r3uctuzb6l5q" class="external-link"
rel="nofollow">http://markmail.org/message/htl6r3uctuzb6l5q</a>  and <a href="http://mail-archives.apache.org/mod_mbox/sling-users/200911.mbox/%3c8A802DC6-7472-4040-807A-D55524F30D3E@gmail.com%3e"
class="external-link" rel="nofollow">http://mail-archives.apache.org/mod_mbox/sling-users/200911.mbox/%3c8A802DC6-7472-4040-807A-D55524F30D3E@gmail.com%3e</a></p>


<h3><a name="FAQ-Howtoreplacethedefaultjsonrenderer%28forexample%29withmyown%3F"></a>How
to replace the default json renderer (for example) with my own?</h3>

<p>The JSON rendering is done by the DefaultGetServlet, which is hardwired to use the
JsonRendererServlet for .json extensions.</p>

<p>If a servlet or script is registered for the <tt>sling/servlet/default</tt>
resource type, but with a specific <tt>sling.servlet.extensions</tt> property
(set using the <tt>@scr.property</tt> annotation), it will take over and process
GET requests which have a .json extension and no specific servlet or script.</p>

<p>As scripts and servlets are equivalent in Sling, the simplest way to do this to create
a script at <tt>apps/sling/servlet/default/json.esp</tt>, for example.</p>

<p>The same logic applies to other extensions (html, txt, ...) handled by the DefaultGetServlet.</p>

<h3><a name="FAQ-Howtoexecutescriptsdirectly%3F"></a>How to execute scripts
directly?</h3>

<p>The following servlet (inspired from the <a href="http://github.com/ieb/open-experiments/tree/334aacad2832ee2dde03eeff16f1d079314c8750/slingtests/osgikernel/bundles/scriptrunner"
class="external-link" rel="nofollow">Sakai ScriptRunner</a>) executes scripts directly
when called with the script URL and a <em>.runscript</em> selector (for example
<em>/foo/myscript.esp.runscript.html</em>).</p>

<p>Note that this can be <b>insecure</b>: if users are allowed to upload
scripts, they can execute any code supported by Sling, so use that only if you know what you're
doing.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>ScriptRunnerServlet</b></div><div
class="codeContent panelContent">
<pre class="code-java">
/* @scr.component
 *    immediate=<span class="code-quote">"<span class="code-keyword">true</span>"</span>
label=<span class="code-quote">"ScriptRunner"</span>
 *    description=<span class="code-quote">"Runs scripts using the .runscript selector"</span>
 *
 * @scr.service
 *    <span class="code-keyword">interface</span>=<span class="code-quote">"javax.servlet.Servlet"</span>
 * @scr.property
 *    name=<span class="code-quote">"sling.servlet.resourceTypes"</span>
 *    value=<span class="code-quote">"sling/servlet/<span class="code-keyword">default</span>"</span>
 * @scr.property
 *    name=<span class="code-quote">"sling.servlet.selectors"</span>
 *    value=<span class="code-quote">"runscript"</span>
 * @scr.property
 *    name=<span class="code-quote">"sling.servlet.methods"</span>
 *    value=<span class="code-quote">"GET"</span>
 */
<span class="code-keyword">public</span> class ScriptRunnerServlet <span class="code-keyword">extends</span>
SlingAllMethodsServlet {

<span class="code-keyword">protected</span> void doGet(
  SlingHttpServletRequest req,
  SlingHttpServletResponse resp)
  <span class="code-keyword">throws</span> ServletException, IOException {
    Servlet s = req.getResource().adaptTo(Servlet.class);
    <span class="code-keyword">if</span>(s == <span class="code-keyword">null</span>)
{
      <span class="code-keyword">throw</span> <span class="code-keyword">new</span>
        ServletException(<span class="code-quote">"Resource "</span>
        + req.getResource()
        + <span class="code-quote">" does not adapt to a Servlet"</span>);
    }
    s.service(req, resp);
  }
}
</pre>
</div></div>

<h3><a name="FAQ-HowdoIcreateanewscriptengine%3F"></a>How do I create a
new script engine?</h3>

<p>As I write this, we don't have documentation on how to create more script engines,
but that's not too hard to do if you take one of the simple existing engines as an example.</p>

<p>The <a href="http://svn.apache.org/viewvc/sling/trunk/contrib/scripting/ruby/"
class="external-link" rel="nofollow">JRuby engine</a> for example, implemented in
the <em>scripting/ruby</em> module, is built out of two simple classes, one that
inherits from AbstractSlingScriptEngine, and one that inherits from AbstractScriptEngineFactory.
The code is very simple, it's basically only a wrapper around the JRuby engine, that adapts
it for Sling.</p>

<p>If creating a script engine, don't forget the <em>META-INF/services/javax.script.ScriptEngineFactory</em>
file, which lets scripting subsystem know about the factory class, so that the engine is activated
when the bundle that contains it is loaded.</p>

<p>Once the script engine is created, loading its bundle into Sling should be enough
to activate scripts having the extension defined by the engine. If several scripts are found
with the same name but different script extensions, the priority in selecting them is currently
unspecified.</p>

<p>The javascript and freemarker engines source code also shows how to add automated
tests to a script engine, including making a JCR repository available to the tests.</p>

<p>To go further, the javascript and jsp script engines are the most interesting ones
to study.</p>

<p>The javascript engine provides <a href="http://svn.apache.org/viewvc/sling/trunk/bundles/scripting/javascript/src/main/java/org/apache/sling/scripting/javascript/wrapper/"
class="external-link" rel="nofollow">wrappers</a> to make it easier to access JCR
and Sling objects from server-side javascript, and also uses a clever <a href="http://svn.apache.org/viewvc/sling/trunk/bundles/scripting/javascript/src/main/java/org/apache/sling/scripting/javascript/io/EspReader.java?view=markup"
class="external-link" rel="nofollow">EspReader</a> (sorry it's not <em>that</em>
<a href="http://en.wikipedia.org/wiki/Extra-sensory_perception" class="external-link" rel="nofollow">ESP</a>)
to convert <em>.esp</em> scripts to plain javascript code.</p>

<p>The JSP engine is actually a compiler, so it can be an interesting example if your
language needs or can benefit from compiling.</p>

<p><b>Note:</b> If the script engine you add involves compiling the scripts
to Java Class files which are consumed by a classloader, it may be worth it to consider to
properly seriliaze access to scripts which are under compilation to prevent paralell compilation
and consequential class loading issues. Sling's JSP Engine is based on Jasper from Apache
Tomcat and employs such serialization.</p>

<h2><a name="FAQ-Workingwithbundles"></a>Working with bundles</h2>

<h3><a name="FAQ-Isthereaneasywaytoupdatebundlesinarunninginstallationduringdevelopment%3F"></a>Is
there an easy way to update bundles in a running installation during development?</h3>

<p>The Sling Maven Plugin provides an install goal which is able to install or update
a bundle in a running Sling application (if the Sling web console is deployed). If the plugin
properties are configured accordingly you can just <tt>mvn clean package org.apache.sling:maven-sling-plugin:install</tt>
and the bundle is uploaded.</p>

<p>You can use the <tt>settings.xml</tt> to set the url to your Sling application.
See the <a href="/confluence/pages/createpage.action?spaceKey=SLING&amp;title=Plugins&amp;linkCreation=true&amp;fromPageId=73883"
class="createlink">Sling Maven Plugin</a> for more information.</p>

<h2><a name="FAQ-Classloadingissues"></a>Classloading issues</h2>

<h3><a name="FAQ-AccessingClassesfromtheEnvironment"></a>Accessing Classes
from the Environment</h3>

<p>Mostly when using the Sling Web Application, that is running Sling inside a web application
deployed into some servlet container, you might want to share classes between the servlet
container and Sling. Some examples of such sharing are:</p>
<ol>
	<li>Accessing EJB from the Application Server</li>
	<li>Sharing classe with another web application such as a Jackrabbit instance</li>
	<li>Using other container features</li>
</ol>


<p>For such cases the OSGi Core Specification provides a functionality to declare such
class sharing. The functionality is defined in terms of two Framework properties <tt>org.osgi.framework.system.packages</tt>
and <tt>org.osgi.framework.bootdelegation</tt>:</p>
<ol>
	<li><tt><b>org.osgi.framework.bootdelegation</b></tt> &#45;
All classes matching any entry in this list are always loaded from the parent class loader
and not through the OSGi framework infrastructure. This property is a comma separated list
of package names. A package name may be terminated by a wildcard character such that any package
starting with the list entry matches the entry and thus will be used from the parent class
loader.</li>
	<li><tt><b>org.osgi.framework.system.packages</b></tt> &#45;
Additional package declarations for packages to be exported from the system bundle. This property
is a simple package declaration list just like any <tt>Export-Package</tt> manifest
header. In a sense the <tt>org.osgi.framework.system.packages</tt> property may
be seen as the <tt>Export-Package</tt> manifest header of the system bundle. Namely
these entries may not contain wildcards (as is allowed for the <tt>bootdelegation</tt>
property) and may contain directives and attributes such as the <tt>uses</tt>
directive and the <tt>version</tt> attribute. It is recommended to provide this
additional information to help in resolving the bundles. The OSGi Core Specification even
prescribes the use of the <tt>uses</tt> directive.</li>
</ol>


<p>The problem with the <tt>org.osgi.framework.bootdelegation</tt> property
is, that it completely bypasses any bundle import wirings and just asks the parent classloader.
Such situations are not easily recognizable. Therefore the Sling Console will be enhanced
to mark any package import which matchs an entry in the <tt>org.osgi.framework.bootdelegation</tt>
appropriately (<a href="ttps://issues.apache.org/jira/browse/SLING-148" class="external-link"
rel="nofollow">SLING-148</a>).</p>

<p>Also note, that any package listed as an import in a bundle must be resolveable for
the bundle resolve. The import resolution process does not take the <tt>org.osgi.framework.bootdelegation</tt>
configuration into account. This means, that regardless of whether a package is listed in
the <tt>org.osgi.framework.bootdelegation</tt> property or not, if the package
is listed as a required import in the <tt>Import-Package</tt> header, it must
be exported by some other bundle.</p>

<h3><a name="FAQ-Howarethe%7B%7Bsling.bootdelegation%7D%7Dpropertiesused%3F"></a>How
are the <tt>sling.bootdelegation</tt> properties used ?</h3>

<p>Sling uses the <tt>sling.bootdelegation.class</tt> property name prefix
to define lists of classes that must be added to the <tt>org.osgi.framework.bootdelegation</tt>
property. In case you want to have a closer look, this is implemented in the <tt>org.apache.sling.launcher.app.Sling.resolve()</tt>
method.</p>

<p>If a Sling property name starts with the <tt>sling.bootdelegation.class.</tt>
prefix, the list of packages defined as the property value is appended to the <tt>org.osgi.framework.bootdelegation</tt>
property, but only if the fully qualified class taken from the rest of the property name exists
in the parent class loader.</p>

<p>Here's an example, from the jcr-client.properties file:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
sling.bootdelegation.class.javax.jcr.Repository = \
 javax.jcr, \
 javax.jcr.lock, \
 javax.jcr.nodetype, \
 javax.jcr.observation, \
 javax.jcr.query, \
 javax.jcr.util, \
 javax.jcr.version
</pre>
</div></div>

<p>This means that, if the <tt>javax.jcr.Repository</tt> class is available
in the parent class loader, all packages listed will be added to the <tt>org.osgi.framework.bootdelegation</tt>,
making the corresponding classes available to OSGi bundles.</p>

<p>If the property name does not start with this <tt>sling.bootdelegation.class.</tt>
property, the list of packages is just appended to the <tt>org.osgi.framework.bootdelegation</tt>
property.</p>

<h3><a name="FAQ-HowdoesSlingsupportthe%7B%7Borg.osgi.framework.system.packages%7D%7DProperty%3F"></a>How
does Sling support the <tt>org.osgi.framework.system.packages</tt> Property ?</h3>

<p>Currently extending the <tt>org.osgi.framework.system.packages</tt> property
in a Sling configuration file is only possibly by setting the <tt>org.apache.sling.launcher.system.packages</tt>
property. The value of this property, which <em>must</em> start with a comma,
is just appended to the <tt>org.osgi.framewrok.system.packages</tt> property.</p>

<p>A more elaborate support as is supported for the <tt>org.osgi.framework.bootdelegation</tt>
Property has been prepared (<a href="http://issues.apache.org/jira/browse/SLING-147" class="external-link"
rel="nofollow">SLING-147</a>).</p>

<h3><a name="FAQ-Shouldthe%7B%7Borg.osgi.framework.bootdelegation%7D%7Dorthe%7B%7Borg.osgi.framework.system.packages%7D%7DPropertybeused%3F"></a>Should
the <tt>org.osgi.framework.bootdelegation</tt> or the <tt>org.osgi.framework.system.packages</tt>
Property be used ?</h3>

<p>So, what mechanism should be used ? The answer is, that it depends.</p>

<p>Most of the time, you will want to use the <tt>org.osgi.framework.system.packages</tt>
property. Because this property ensures that you will allways benefit from the normal class
resolution mechanism through package imports and exports.</p>

<p>This allows creating the bundles normally by having the package import lists being
built according to the packages used by the bundle classes. For example you may use the Apache
Felix Maven Bundle Plugin to build your OSGi bundles and the imports are automatically calculated
(by default).</p>

<p>The drawback of this method is, that there may be bundles in your system, which export
packages also listed in the <tt>org.osgi.framework.system.packages</tt> property.
Depending on the export version, the wrong package may be bound. So to prevent such collisions
you should not install such bundles.</p>

<p>An example of such a declaration is the Servlet API packages (<tt>javax.servlet</tt>,
<tt>javax.servlet.http</tt> and <tt>javax.servlet.resources</tt>).
These packages are imported into the OSGi framework by the <tt>SlingServlet</tt>
of the <tt>launcher/webapp</tt> project as part of the <tt>org.osgi.framework.system.packages</tt>
property. To have this work correctly, no bundle should export the respective packages. In
the case of Sling, this means, the <tt>org.apache.felix.commons.sling-api</tt>
bundle must not be installed.</p>

<p>If on the other hand you cannot prevent the installation of such bundles and hence
the export of the respective packages, you might want to set the <tt>org.osgi.framework.bootdelegation</tt>
property conditionally as described above in the answer to how this property is supported
in Sling. This ensures the property is only set, if the classes are actually available. This
should be used as a fall back only, if the <tt>org.osgi.framework.system.packages</tt>
method does not work.</p>


<h2><a name="FAQ-Miscellaneous"></a>Miscellaneous</h2>

<h3><a name="FAQ-Whycan%27tIconnecttoSling%27sWebDAVusingWindowsNetworkDriveMapping%3F"></a>Why
can't I connect to Sling's WebDAV using Windows NetworkDriveMapping ?</h3>

<p>Since Windows XP SP 2 (thus also affects Windows Vista, Windows 7, etc.) support
for HTTP Basic authentication is by default switched off unless using HTTPS. Support can be
switched on again by setting a Windows registry value. See Microsoft Knowledge Base entry
<a href="http://support.microsoft.com/kb/841215" class="external-link" rel="nofollow">841215</a>
for full details and warnings regarding modifying registry entries.</p>

<h3><a name="FAQ-WhyismyWebDAVconnectionsoslowonWindows%3F"></a>Why is my
WebDAV connection so slow on Windows ?</h3>

<p>One reason might be automatic proxy detection being enabled in the Internet Options.
See the <a href="http://oddballupdate.com/2009/12/18/fix-slow-webdav-performance-in-windows-7/"
class="external-link" rel="nofollow">Fix Slow WebDAV Performance in Windows 7</a>
for the solution.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/SLING/FAQ">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=73883&revisedVersion=27&originalVersion=26">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/SLING/FAQ?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message