This is an old version of the Sling website, see the site conversion page for more info.
Apache
Apache Sling Website > Apache Sling > Documentation > Bundles > JCR Installer (jcr.jcrinstall and osgi.installer)

The JCR installer modules (collectively known as JCRInstall) install OSGi bundles and configurations found in the JCR repository.

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.

Example

Here's a quick walkthrough of the JCR installer functionality.

Installation

Start the Sling launchpad/app and install and start the following additional bundles:

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

Install and remove a bundle

We'll use the Knopflerfish Desktop bundle for this example, it is convenient as it displays a graphical user interface when started.

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

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

curl -X MKCOL  http://admin:admin@localhost:8888/apps/jcrtest
curl -X MKCOL  http://admin:admin@localhost:8888/apps/jcrtest/install

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

curl -T desktop_awt_all-2.0.0.jar \
  http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar

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 Knopflerfish Desktop window on your desktop, and Sling's OSGi console can of course be used to check the details.

Removing the bundle from the repository will cause it to be uninstalled, so:

curl -X DELETE \
  http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar

Should cause the Knopflerfish Desktop window to disappear as the bundle is uninstalled.

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

Install, modify and remove a configuration

JCRInstall installs OSGi configurations from nodes having the sling:OsgiConfig node type, found in folders named install under the installation roots (/apps and /libs).

Let's try this feature by creating a configuration with two properties:

curl \
  -F "jcr:primaryType=sling:OsgiConfig" \
  -F foo=bar -F works=yes \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid

And verify the contents of our config node:

curl \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json

Which should display something like

{"foo":"bar",
"jcr:created":"Wed Aug 26 2009 17:06:40GMT+0200",
"jcr:primaryType":"sling:OsgiConfig","works":"yes"}

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 (http://localhost:8888/system/console/config) to check it. That page should now contain:

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

Indicating that the configuration has been installed.

Let's try modifying the configuration parameters:

curl \
  -F works=updated -F even=more \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid

And check the changes in the console page:

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

We can now delete the configuration node:

curl -X DELETE \
  http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid

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

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

Run Modes

TODO: folder names like install.dev are included in the repository scanning if the dev run mode is active - describe this feature.

Automated Tests

The following modules contain lots of automated tests (under src/test, as usual):

Many of these tests are fairly readable, and can be used to find out in more detail how these modules work.

Last modified by mykee on 2010-10-06 12:38:17.0
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.