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 Website > JCR Installer Provider
Date Tue, 11 Oct 2011 09:24:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=SLINGxSITE&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/SLINGxSITE/JCR+Installer+Provider">JCR
Installer Provider</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~cziegeler@apache.org">Carsten
Ziegeler</a>
    </h4>
        <br/>
                         <h4>Changes (7)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The
JCR installer modules (collectively known as _JCRInstall_) install OSGi bundles and configurations
found in the JCR repository. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
JCR installer provider scans the JCR repository for artifacts and provides them to the [OSGI
installer|SLINGxSITE:OSGi Installer]. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The
goal is to allow Sling applications to be distributed as &quot;content packages&quot;,
which install additional services and configurations when copied to the JCR repository. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2.
Configuration and Scanning <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
JCR installer provider can be configured with weighted paths which are scanned. By default,
the installer scans in */apps* and */libs* where artifacts found in */apps* get a higher priority.
The installer does a deep scan and uses a regular expression to detect folders containing
artifacts to be installed. By default, artifacts from within a folder named _install_ are
provided to the OSGi installer. <br> <br>If such an install folder contains a
binary artifact (e.g. a bundle) this is provided to the OSGi installer. In addition a node
of type _sling:OsgiConfig_ is provided as a configuration to the installer. <br> <br>The
jcr installer provider does not check or scan the artifacts itself, the detection and installation
is deferred to the OSGi installer. <br> <br> <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h1. Example <br>Here&#39;s
a quick walkthrough of the JCR installer functionality. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >Start the Sling [launchpad/app|http://svn.apache.org/repos/asf/sling/trunk/launchpad/app]
and install and start the following additional bundles: <br>* [RunMode service|Run Modes
(org.apache.sling.runmode)] <br></td></tr>
            <tr><td class="diff-changed-lines" >* OSGi installer service <span
class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">([org.apache.sling.osgi.installer|http://svn.apache.org/repos/asf/sling/trunk/installer/osgi/installer])</span>
<span class="diff-added-words"style="background-color: #dfd;">([org.apache.sling.osgi.installer|http://svn.apache.org/repos/asf/sling/trunk/installer/core])</span>
<br></td></tr>
            <tr><td class="diff-changed-lines" >* JCR installer <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">service
([org.apache.sling.jcr.jcrinstall|http://svn.apache.org/repos/asf/sling/trunk/installer/jcr/jcrinstall])</span>
<span class="diff-added-words"style="background-color: #dfd;">provider ([org.apache.sling.jcr.jcrinstall|http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr])</span>
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>To watch the logs produced
by these modules, you can filter {{sling/logs/error.log}} using {{egrep &#39;jcrinstall|osgi.installer&#39;}}.
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>The JCR installer provider scans the JCR repository for artifacts and provides
them to the <a href="/confluence/display/SLINGxSITE/OSGi+Installer" title="OSGi Installer">OSGI
installer</a>.</p>

<h2><a name="JCRInstallerProvider-ConfigurationandScanning"></a>Configuration
and Scanning</h2>

<p>The JCR installer provider can be configured with weighted paths which are scanned.
By default, the installer scans in <b>/apps</b> and <b>/libs</b> where
artifacts found in <b>/apps</b> get a higher priority. The installer does a deep
scan and uses a regular expression to detect folders containing artifacts to be installed.
By default, artifacts from within a folder named <em>install</em> are provided
to the OSGi installer.</p>

<p>If such an install folder contains a binary artifact (e.g. a bundle) this is provided
to the OSGi installer. In addition a node of type <em>sling:OsgiConfig</em> is
provided as a configuration to the installer.</p>

<p>The jcr installer provider does not check or scan the artifacts itself, the detection
and installation is deferred to the OSGi installer.</p>



<h1><a name="JCRInstallerProvider-Example"></a>Example</h1>
<p>Here's a quick walkthrough of the JCR installer functionality.</p>

<h2><a name="JCRInstallerProvider-Installation"></a>Installation</h2>
<p>Start the Sling <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/app"
class="external-link" rel="nofollow">launchpad/app</a> and install and start the
following additional bundles:</p>
<ul>
	<li><a href="/confluence/display/SLINGxSITE/Run+Modes+%28org.apache.sling.runmode%29"
title="Run Modes (org.apache.sling.runmode)">RunMode service</a></li>
	<li>OSGi installer service (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/core"
class="external-link" rel="nofollow">org.apache.sling.osgi.installer</a>)</li>
	<li>JCR installer provider (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr"
class="external-link" rel="nofollow">org.apache.sling.jcr.jcrinstall</a>)</li>
</ul>


<p>To watch the logs produced by these modules, you can filter <tt>sling/logs/error.log</tt>
using <tt>egrep 'jcrinstall|osgi.installer'</tt>.</p>

<h2><a name="JCRInstallerProvider-Installandremoveabundle"></a>Install and
remove a bundle</h2>
<p>We'll use the <a href="http://www.knopflerfish.org/releases/2.0.5/jars/desktop_awt/desktop_awt_all-2.0.0.jar"
class="external-link" rel="nofollow">Knopflerfish Desktop</a> bundle for this example,
it is convenient as it displays a graphical user interface when started.</p>

<p>We use <tt>curl</tt> to create content, to make it easy to reproduce
the example by copying and pasting the <tt>curl</tt> commands. Any other way to
create content in the repository will work, of course.</p>

<p>By default, JCRInstall picks up bundles found in folders named <em>install</em>
under <tt>/libs</tt> and <tt>/apps</tt>, so we start by creating such
a folder:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>curl -X MKCOL  http://admin:admin@localhost:8888/apps/jcrtest
curl -X MKCOL  http://admin:admin@localhost:8888/apps/jcrtest/install
</pre>
</div></div>

<p>And we copy the bundle to install in that folder (a backslash in command lines means
<em>continued on next line</em>):</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>curl -T desktop_awt_all-2.0.0.jar \
  http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
</pre>
</div></div>

<p>That's it. After 2-3 seconds, the bundle should be picked up by JCRInstall, installed
and started. If this works you'll see a small <em>Knopflerfish Desktop</em> window
on your desktop, and Sling's OSGi console can of course be used to check the details.</p>

<p>Removing the bundle from the repository will cause it to be uninstalled, so:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>curl -X DELETE \
  http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
</pre>
</div></div>

<p>Should cause the <em>Knopflerfish Desktop</em> window to disappear as
the bundle is uninstalled.</p>

<p><b>TODO:</b> document folder priorities (/apps over /libs), SNAPSHOT
handling, bundle start retries.</p>

<h2><a name="JCRInstallerProvider-Install%2Cmodifyandremoveaconfiguration"></a>Install,
modify and remove a configuration</h2>
<p>JCRInstall installs OSGi configurations from nodes having the <em>sling:OsgiConfig</em>
node type, found in folders named <em>install</em> under the installation roots
(/apps and /libs).</p>

<p>Let's try this feature by creating a configuration with two properties:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>curl \
  -F "jcr:primaryType=sling:OsgiConfig" \
  -F foo=bar -F works=yes \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
</pre>
</div></div>

<p>And verify the contents of our config node:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>curl \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json
</pre>
</div></div>

<p>Which should display something like</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>{"foo":"bar",
"jcr:created":"Wed Aug 26 2009 17:06:40GMT+0200",
"jcr:primaryType":"sling:OsgiConfig","works":"yes"}
</pre>
</div></div>

<p>At this point, JCRInstall should have picked up our new config and installed it.
The logs would confirm that, but we can also use the OSGi console's config status page (<a
href="http://localhost:8888/system/console/config" class="external-link" rel="nofollow">http://localhost:8888/system/console/config</a>)
to check it. That page should now contain:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>PID=some.config.pid
  BundleLocation=Unbound
  _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid
  foo=bars
  service.pid=some.config.pid
  works=yes
</pre>
</div></div>

<p>Indicating that the configuration has been installed.</p>

<p>Let's try modifying the configuration parameters:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>curl \
  -F works=updated -F even=more \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
</pre>
</div></div>

<p>And check the changes in the console page:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>PID=some.config.pid
  BundleLocation=Unbound
  _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid
  even=more
  foo=bars
  service.pid=some.config.pid
  works=updated
</pre>
</div></div>

<p>We can now delete the configuration node:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>curl -X DELETE \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
</pre>
</div></div>

<p>And verify that the corresponding configuration is gone in the console page (after
1-2 seconds, like for all other JCRInstall operations).</p>

<p><b>TODO:</b> A node named like <tt>o.a.s.foo.bar-a</tt> uses
<em>o.a.s.foo.bar</em> as its factory PID creating a configuration with an automatically
generated PID. The value of <em>a</em> is stored as an alias property in the configuration
to correlate the configuration object with the repository node - demonstrate that.</p>

<h1><a name="JCRInstallerProvider-RunModes"></a>Run Modes</h1>
<p><b>TODO:</b> folder names like <em>install.dev</em> are included
in the repository scanning if the <em>dev</em> run mode is active - describe this
feature.</p>

<h1><a name="JCRInstallerProvider-AutomatedTests"></a>Automated Tests</h1>
<p>The following modules contain lots of automated tests (under <tt>src/test</tt>,
as usual):</p>

<ul>
	<li>OSGi installer integration tests (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/it"
class="external-link" rel="nofollow">org.apache.sling.installer.it</a>)</li>
	<li>JCR installer service (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr"
class="external-link" rel="nofollow">org.apache.sling.installer.providers.jcr</a>)</li>
</ul>


<p>Many of these tests are fairly readable, and can be used to find out in more detail
how these modules work.</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/SLINGxSITE/JCR+Installer+Provider">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=2852417&revisedVersion=9&originalVersion=8">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/JCR+Installer+Provider?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message