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 (jcr.jcrinstall and osgi.installer)
Date Fri, 22 Jan 2010 08:33:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;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/~fmeschbe">Felix
Meschberger</a>
    </h4>
     fix description of mapping node name to configuration for factory configurations
          <div id="versionComment" class="noteMacro" style="display:none; padding: 5px;">
     fix description of mapping node name to configuration for factory configurations<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>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="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=7&originalVersion=6">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/JCR+Installer+%28jcr.jcrinstall+and+osgi.installer%29?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message