<html>
<head>
<base href="http://cwiki.apache.org/confluence">
<link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLINGxSITE&forWysiwyg=true"
type="text/css">
</head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/JCR+Installer+%28jcr.jcrinstall+and+osgi.installer%29">JCR
Installer (jcr.jcrinstall and osgi.installer)</a></h2>
<h4>Page <b>edited</b> by <a href="http://cwiki.apache.org/confluence/display/~bdelacretaz">Bertrand
Delacretaz</a>
</h4>
Link to restored run modes page
<div id="versionComment" class="noteMacro" style="display:none; padding: 5px;">
Link to restored run modes page<br />
</div>
<br/>
<div class="notificationGreySide">
<p>The JCR installer modules (collectively known as <em>JCRInstall</em>)
install OSGi bundles and configurations found in the JCR repository.</p>
<p>The goal is to allow Sling applications to be distributed as "content packages",
which install additional services and configurations when copied to the JCR repository.</p>
<h1><a name="JCRInstaller%28jcr.jcrinstallandosgi.installer%29-Example"></a>Example</h1>
<p>Here's a quick walkthrough of the JCR installer functionality.</p>
<h2><a name="JCRInstaller%28jcr.jcrinstallandosgi.installer%29-Installation"></a>Installation</h2>
<p>Start the Sling <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/app"
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/osgi/installer"
rel="nofollow">org.apache.sling.osgi.installer</a>)</li>
<li>JCR installer service (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/jcr/jcrinstall"
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="JCRInstaller%28jcr.jcrinstallandosgi.installer%29-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"
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="JCRInstaller%28jcr.jcrinstallandosgi.installer%29-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" 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>a</em> as its factory PID, and <em>o.a.s.foo.bar</em> as its configuration
PID - demonstrate that.</p>
<h1><a name="JCRInstaller%28jcr.jcrinstallandosgi.installer%29-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="JCRInstaller%28jcr.jcrinstallandosgi.installer%29-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 service (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/osgi/installer"
rel="nofollow">org.apache.sling.osgi.installer</a>)</li>
<li>OSGi installer integration tests (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/osgi/it"
rel="nofollow">org.apache.sling.osgi.installer</a>)</li>
<li>JCR installer service (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/jcr/jcrinstall"
rel="nofollow">org.apache.sling.jcr.jcrinstall</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="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
</div>
<a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/JCR+Installer+%28jcr.jcrinstall+and+osgi.installer%29">View
Online</a>
|
<a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=2852417&revisedVersion=6&originalVersion=5">View
Change</a>
|
<a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/JCR+Installer+%28jcr.jcrinstall+and+osgi.installer%29?showComments=true&showCommentArea=true#addcomment">Add
Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>
|