in the sling

Inside Sling: How Sling boots

2008-09-22T16:09:00.001+02:00

In this post, I will give an overview on how Sling starts up, how Felix is started as the OSGi framework, how Sling is configured, and how Sling loads other bundles.
For this, we need to have a look at the org.apache.sling.launchpad.base project ( sling/launchpad/base ).

Class overview

Let's start with an overview of the most important classes involved in the startup process:

blue boxes are Sling classes, from package org.apache.sling.launcher.base
green boxes are Felix classes, from package org.apache.felix.framework
the violet box is an OSGi framework interface, the BundleActivator

The ResourceProvider abstract class forms an interface for Sling to be able to locate arbitrary resources. In this case, the only implementation is the ClassLoaderResourceProvider, which will load resources from the class loader passed in the constructor. Note that this is not the org.apache.sling.api.ResourceProvider interface, but an abstract class in the package org.apache.sling.launcher.base.

The Sling class holds a reference to a Felix instance (as it starts the instance), and to a Logger instance (which it also instantiates). At the same time, it implements the BundleActivator interface. This is an OSGi framework interface that needs to be implemented by classes that start and stop a bundle. Felix accepts a list of BundleActivators in it's constructor, and these will serve as the bundles that are initially started, and which are responsible for starting any other bundles required. We'll look at Sling's bundle start and stop methods in a minute.

BootstrapInstaller also implements BundleActivator and is also passed to Felix at startup. The BootstrapInstaller will load all the other bundles that make up Sling. We'll look at that as well.

Sequence overview

Before we go into details, let's look at the startup sequence from a high level:

a logger is instantiated
a ClassLoaderResourceProvider is created, passing the Main class' class loader
a Sling instance is created, passing the previous two objects
install bundles are set
the OSGi execution environment is set
an instance of BootstrapInstaller is created
a Felix instance is created, passing the Logger and a list of BundleActivators, consisting of the sling instance itself and the BootstrapInstaller just created
Felix' start method is called
eventually, as it will start up the bundles passed in the constructor, Felix will call the start() method of the sling instance
Felix will also call the start() method of the BootstrapInstaller
this in turn will call installBundles() and
startBundles(), which I will dicuss a little later

Details

Now that we have seen that objects involved and the high level sequence of things, let's dig down a bit deeper, along the lines of the sequence:

the main method

First, let's have a look at the Main class' main method (see below: org.apache.sling.launcher.app.main.Main)

Line 102 creates a Map, props to store properties that will be passed to Sling when instantiated.
Line 105 creates another Map, commandLine in which command line configuration statements will be collected. This collection is deferred to the parseCommandline method. That method will scan the commandline for switches that affect the port, log file, log level or sling home directory, and collect the configuration into the commandLine Map which it was passed.
Line 110 propagates a setting of sling.home from the commandLine Map to the props Map
Lines 119-126 determine the log level from the command line and sets it in the commandLine Map accordingly. This won't take effect until Sling later calls back to the loadPropertiesOverride() method. For a start, a Logger is instantiated and set to a log level of LOG_ERROR in lines 127 and 131.
Line 138 creates the ClassLoaderResourceProvider
Line 140 instantiates a Sling instance and makes an inline overrive of the loadPropertiesOverride method. This method is an overrideable callback provided for classes extending Sling, and will be called by Sling.loadConfigProperties.
Line 159 establishes a VM shutdown hook which will call Sling.destroy() before the VM shuts down

Sling configuration

Actual Sling startup takes place in the constructor, so let's have a closer look at that (Line numbers refer to org.apache.sling.launcher.app.main.Main). Line 182 delegates configuration setup to loadConfigProperties(), so let's first have a look at how the Sling configuration is calculated.

load the properties file (l.299) and all includes (l.302)
overwrite the loaded properties with properties passed in the constructor (if any duplicates) (l.306)
look for the sling.home property in the system properties, the properties just merged, and set to "sling" if not found (l.310-321)
merge any properties found in ${sling.home}/sling.properties (l.328-330).
overwrite properties with any system properties that have the same name (sling.home is not affected). This step can be prevented by setting sling.ignoreSystemProperties to true. (l.338-346)
load includes that have been added through the last steps (l.349)
call loadPropertiesOverride -- Sling's own implementation does nothing, but subclasses may override this to inject configuration
append to the list of boot delegation and system packages (l.355, 357): given the prefix sling.bootdelegation. and the osgiProp org.osgi.framework.bootdelegation, it will
- look for an entry that starts with sling.bootdelegation. and add the value to the end of the current value of org.osgi.framework.bootdelegation (adding a comma if that value is not empty so far)
- unless the entry starts with sling.bootdelegation.class. &ldash; in that case, it will interpret the rest of the property name as a class name, and add the value only if the class can be loaded.
substitute variables (e.g. ${sling.home}) (l.368-371)
substitute context: values (l.374 - 419) (in short: for any value that starts with context:/, copy the file that is specified by the remainder of the value to sling.home and replace the original value of the property with the absolute path of the copied file)
as a last step, the unsubstituted properties are written back to ${sling.home}/sling.properties.

The remainder of the Sling constructor

So, we have reached line 183 in Sling.java, and are before step (4) in the sequence diagram above. Let's see what happens in the rest of Sling's constructor.

setInstallBundles() is called in line 185. I have not seen any use of this in a sling properties file, but it looks like properties of the pattern sling.install.some.bundle.name.here will result in ,some.bundle.name.here being appended to sling.install.bundles.
setExecutionEnvironment() is called in line 188. This will set the property org.osgi.framework.executionenvironment (see section 3.3 of the OSGi R4 core specification).
A list of BundleActivators is created, including the Sling instance in construction and a new BootstrapInstaller.
In line 199, a new Felix instance is created, passing the list of bundle activators just created, the properties, and the logger
Line 200 starts the Felix environment.

Now we're at step (8) in the sequence diagram. Felix has started up, the Sling constructor returns. And all that was to be seen so far didn't look like very much, so where's all the rest happening? We'll take up the thread by looking at the start() methods of Sling and BootstrapInstaller. These were both registered as startup bundle activators when calling the Felix constructor, so this is how Felix again plays the ball to Sling.

Sling.start() will just do one thing: it will register a ContextProtocolHandler to handle URLs that start with context:. Any such URL will Sling's resourceProvider (so in this case, the ClassLoaderResourceProvider) to resolve these URLs.

BootstrapInstaller.start() does a bit more. For one thing, it should be noted that this method will be run only once: when Sling is started for the first time. This is achieved by persisting the installation state to a data file managed by Felix (l 147-165), and by reading that data back on method start and not running the code if it was run before (l 103-127).

Lines 129-134: the DeploymentPackageInstaller will wait until Framework and Deployment Admin service have started up, and then look for deployment packages in resources/bundles (on the class loader), and install any found (if not already installed). See also section 114 of the OSGi Compendium R4.
Lines 143-145 install any bundles provided as jar files in resources/corebundles or resources/bundles, if not already installed, keeping track of the bundles so installed
Line 168 will call startBundles, which will start all the bundles just installed. It will also try to set the start level of each bundle to 1, if the start level service is available (OSGi Core R4, Section 8).

Code

org.apache.sling.launcher.app.Sling
org.apache.sling.launcher.app.BootstrapInstaller
org.apache.sling.launcher.app.main.Main

`org.apache.sling.launcher.app.Sling`, Revision 657002

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.sling.launcher.app;

import static org.apache.felix.framework.util.FelixConstants.EMBEDDED_EXECUTION_PROP;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Hashtable;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
import java.util.SortedMap;
import java.util.StringTokenizer;
import java.util.TreeMap;
import java.util.TreeSet;
import java.util.Map.Entry;

import org.apache.felix.framework.Felix;
import org.apache.felix.framework.Logger;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.BundleException;
import org.osgi.framework.Constants;
import org.osgi.framework.Version;
import org.osgi.service.url.URLConstants;
import org.osgi.service.url.URLStreamHandlerService;

/**
 * The <code>Sling</code> serves as the starting point for Sling.
 * <ul>
 * <li>The {@link #Sling(Logger, ResourceProvider, Map)} method launches
 * Apache <code>Felix</code> as the OSGi framework implementation we use.
 * </ul>
 * <p>
 * <b>Launch Configuration</b>
 * <p>
 * The Apache <code>Felix</code> framework requires configuration parameters
 * to be specified for startup. This servlet builds the list of parameters from
 * three locations:
 * <ol>
 * <li>The <code>com/day/osgi/servlet/Sling.properties</code> is read from
 * the servlet class path. This properties file contains default settings.</li>
 * <li>Extensions of this servlet may provide additional properties to be
 * loaded overwriting the {@link #loadPropertiesOverride(Map)} method.
 * <li>Finally, web application init parameters are added to the properties and
 * may overwrite existing properties of the same name(s).
 * </ol>
 * <p>
 * After loading all properties, variable substitution takes place on the
 * property values. A variable is indicated as <code>${&lt;prop-name&gt;}</code>
 * where <code>&lt;prop-name&gt;</code> is the name of a system or
 * configuration property (configuration properties override system properties).
 * Variables may be nested and are resolved from inner-most to outer-most. For
 * example, the property value <code>${outer-${inner}}</code> is resolved by
 * first resolving <code>${inner}</code> and then resolving the property whose
 * name is the catenation of <code>outer-</code> and the result of resolving
 * <code>${inner}</code>.
 * <p>
 */
public class Sling implements BundleActivator {

    /** Pseduo class version ID to keep the IDE quite. */
    private static final long serialVersionUID = 1L;

    /**
     * The name of the configuration property defining the Sling home directory
     * (value is "sling.home"). This is a Platform file system directory below
     * which all runtime data, such as the Felix bundle archives, logfiles, CRX
     * repository, etc., is located.
     * <p>
     * The value of this property, if not set as a system property defaults to
     * the <i>sling</i> directory in the current working directory.
     *
     * @see #SLING_HOME_URL
     */
    public static final String SLING_HOME = "sling.home";

    /**
     * The name of the configuration property defining the Sling home directory
     * as an URL (value is "sling.home.url").
     * <p>
     * The value of this property is assigned the value of
     * <code>new File(${sling.home}).toURI().toString()</code> before
     * resolving the property variables.
     *
     * @see #SLING_HOME
     */
    public static final String SLING_HOME_URL = "sling.home.url";

    /**
     * The name of the configuration property defining a properties file
     * defining a list of bundles, which are installed into the framework when
     * it has been launched (value is "org.apache.osgi.bundles").
     * <p>
     * This configuration property is generally set in the web application
     * configuration and may be referenced in all property files (default, user
     * supplied and web application parameters) used to build the framework
     * configuration.
     */
    public static final String OSGI_FRAMEWORK_BUNDLES = "org.apache.osgi.bundles";

    /**
     * The property to be set to ignore the system properties when building the
     * Felix framework properties (value is "sling.ignoreSystemProperties"). If
     * this is property is set to <code>true</code> (case does not matter),
     * the system properties will not be used by
     * {@link #loadConfigProperties(Map)}.
     */
    public static final String SLING_IGNORE_SYSTEM_PROPERTIES = "sling.ignoreSystemProperties";

    /**
     * The name of the default launcher properties file to setup the environment
     * for the <code>Felix</code> framework (value is "sling.properties").
     * <p>
     * Extensions of this class may overwrite some or all properties in this
     * file through Web Application parameters or other properties files.
     */
    public static final String CONFIG_PROPERTIES = "sling.properties";

    public static final String PROP_SYSTEM_PACKAGES = "org.apache.sling.launcher.system.packages";

    /**
     * The simple logger to log messages during startup and shutdown to
     */
    protected final Logger logger;

    private ResourceProvider resourceProvider;

    /**
     * The <code>Felix</code> instance loaded on {@link #init()} and stopped
     * on {@link #destroy()}.
     */
    private Felix felix;

    /**
     * The <code>BundleContext</code> of the OSGi framework system bundle.
     * This is used for service registration and service access to get at the
     * delegatee servlet.
     */
    private BundleContext bundleContext;

    /**
     * Initializes this servlet by loading the framework configuration
     * properties, starting the OSGi framework (Apache Felix) and exposing the
     * system bundle context and the <code>Felix</code> instance as servlet
     * context attributes.
     *
     * @throws BundleException if the framework cannot be initialized.
     */
    public Sling(Logger logger, ResourceProvider resourceProvider,
            Map<String, String> propOverwrite) throws BundleException {

        this.logger = logger;
        this.resourceProvider = resourceProvider;

        this.logger.log(Logger.LOG_INFO, "Starting Sling");

        // read the default parameters
        Map<String, String> props = this.loadConfigProperties(propOverwrite);

        // check for auto-start bundles
        this.setInstallBundles(props);

        // ensure execution environment
        this.setExecutionEnvironment(props);

        // make sure Felix does not exit the VM when terminating ...
        props.put(EMBEDDED_EXECUTION_PROP, "true");

        // the custom activator list just contains this servlet
        List<BundleActivator> activators = new ArrayList<BundleActivator>();
        activators.add(this);
        activators.add(new BootstrapInstaller(logger, resourceProvider));

        // create the framework and start it
        Felix tmpFelix = new Felix(logger, props, activators);
        tmpFelix.start();

        // only assign field if start succeeds
        this.felix = tmpFelix;

        // log sucess message
        this.logger.log(Logger.LOG_INFO, "Sling started");
    }

    /**
     * Destroys this servlet by shutting down the OSGi framework and hence the
     * delegatee servlet if one is set at all.
     */
    public final void destroy() {
        // shutdown the Felix container
        if (felix != null) {
            logger.log(Logger.LOG_INFO, "Shutting down Sling");
            felix.stopAndWait();
            logger.log(Logger.LOG_INFO, "Sling stopped");
            felix = null;
        }
    }

    // ---------- BundleActivator ----------------------------------------------

    /**
     * Called when the OSGi framework is being started. This implementation
     * registers as a service listener for the
     * <code>javax.servlet.Servlet</code> class and calls the
     * {@link #doStartBundle()} method for implementations to execute more
     * startup tasks. Additionally the <code>context</code> URL protocol
     * handler is registered.
     *
     * @param bundleContext The <code>BundleContext</code> of the system
     *            bundle of the OSGi framework.
     * @throws Exception May be thrown if the {@link #doStartBundle()} throws.
     */
    public final void start(BundleContext bundleContext) throws Exception {
        this.bundleContext = bundleContext;

        // register the context URL handler
        Hashtable<String, Object> props = new Hashtable<String, Object>();
        props.put(URLConstants.URL_HANDLER_PROTOCOL, new String[] { "context" });
        ContextProtocolHandler contextHandler = new ContextProtocolHandler(
            this.resourceProvider);
        bundleContext.registerService(URLStreamHandlerService.class.getName(),
            contextHandler, props);

        // execute optional bundle startup tasks of an extension
        this.doStartBundle();
    }

    /**
     * Called when the OSGi framework is being shut down. This implementation
     * first calls the {@link #doStopBundle()} method method before
     * unregistering as a service listener and ungetting an servlet delegatee if
     * one has been acquired.
     *
     * @param bundleContext The <code>BundleContext</code> of the system
     *            bundle of the OSGi framework.
     */
    public final void stop(BundleContext bundleContext) {
        // execute optional bundle stop tasks of an extension
        try {
            this.doStopBundle();
        } catch (Exception e) {
            this.logger.log(Logger.LOG_ERROR, "Unexpected exception caught", e);
        }

        // drop bundle context reference
        this.bundleContext = null;
    }

    // ---------- Configuration Loading ----------------------------------------

    /**
     * Loads the configuration properties in the configuration property file
     * associated with the framework installation; these properties are
     * accessible to the framework and to bundles and are intended for
     * configuration purposes. By default, the configuration property file is
     * located in the <tt>conf/</tt> directory of the Felix installation
     * directory and is called "<tt>config.properties</tt>". The
     * installation directory of Felix is assumed to be the parent directory of
     * the <tt>felix.jar</tt> file as found on the system class path property.
     * The precise file from which to load configuration properties can be set
     * by initializing the "<tt>felix.config.properties</tt>" system
     * property to an arbitrary URL.
     *
     * @return A <tt>Properties</tt> instance or <tt>null</tt> if there was
     *         an error.
     */
    private Map<String, String> loadConfigProperties(
            Map<String, String> propOverwrite) throws BundleException {
        // The config properties file is either specified by a system
        // property or it is in the same directory as the Felix JAR file.
        // Try to load it from one of these places.
        Map<String, String> props = new HashMap<String, String>();

        // Read the properties file.
        this.load(props, CONFIG_PROPERTIES);

        // resolve inclusions (and remove property)
        this.loadIncludes(props, null);

        // overwrite default properties with initial overwrites
        if (propOverwrite != null) {
            props.putAll(propOverwrite);
        }

        // check whether sling.home is overwritten by system property
        String slingHome = System.getProperty(SLING_HOME);
        if (slingHome == null || slingHome.length() == 0) {

            // no system property, ensure default setting
            slingHome = props.get(SLING_HOME);
            if (slingHome == null || slingHome.length() == 0) {
                slingHome = "sling";
                this.logger.log(Logger.LOG_INFO,
                    "sling.home is not defined. Using '" + slingHome + "'");
            }
        }

        // resolve variables and ensure sling.home is an absolute path
        slingHome = substVars(slingHome, SLING_HOME, null, props);
        File slingHomeFile = new File(slingHome).getAbsoluteFile();
        slingHome = slingHomeFile.getAbsolutePath();

        // overlay with ${sling.home}/sling.properties
        this.logger.log(Logger.LOG_INFO, "Starting sling in " + slingHome);
        File propFile = new File(slingHome, CONFIG_PROPERTIES);
        this.load(props, propFile);

        // create a copy of the properties to perform variable substitution
        Map<String, String> origProps = props;
        props = new HashMap<String, String>();
        props.putAll(origProps);

        // check system properties for any overrides (except sling.home !)
        String ignoreSystemProperties = props.get(SLING_IGNORE_SYSTEM_PROPERTIES);
        if (!"true".equalsIgnoreCase(ignoreSystemProperties)) {
            for (String name : props.keySet()) {
                String sysProp = System.getProperty(name);
                if (sysProp != null) {
                    props.put(name, sysProp);
                }
            }
        }

        // resolve inclusions again
        this.loadIncludes(props, slingHome);

        // overwrite properties, this is not persisted as such
        this.loadPropertiesOverride(props);

        // resolve boot delegation and system packages
        this.resolve(props, "org.osgi.framework.bootdelegation",
            "sling.bootdelegation.");
        this.resolve(props, "org.osgi.framework.system.packages",
            "sling.system.packages.");

        // reset back the sling home property
        // might have been overwritten by system properties, included
        // files or the sling.properties file
        origProps.put(SLING_HOME, slingHome);
        props.put(SLING_HOME, slingHome);
        props.put(SLING_HOME_URL, slingHomeFile.toURI().toString());

        // Perform variable substitution for system properties.
        for (Entry<String, String> entry : props.entrySet()) {
            entry.setValue(substVars(entry.getValue(), entry.getKey(), null,
                props));
        }

        // look for context:/ URLs to substitute
        for (Entry<String, String> entry : props.entrySet()) {
            String name = entry.getKey();
            String value = entry.getValue();
            if (value != null && value.startsWith("context:/")) {
                String path = value.substring("context:/".length() - 1);

                InputStream src = this.resourceProvider.getResourceAsStream(path);
                if (src != null) {
                    File target = new File(slingHome, path);
                    OutputStream dest = null;
                    try {
                        // only copy file if not existing
                        if (!target.exists()) {
                            target.getParentFile().mkdirs();
                            dest = new FileOutputStream(target);
                            byte[] buf = new byte[2048];
                            int rd;
                            while ((rd = src.read(buf)) >= 0) {
                                dest.write(buf, 0, rd);
                            }
                        }

                        // after copying replace property and add url property
                        entry.setValue(target.getAbsolutePath());

                        // also set the new property on the unsubstituted props
                        origProps.put(name, "${sling.home}" + path);

                    } catch (IOException ioe) {
                        this.logger.log(Logger.LOG_ERROR, "Cannot copy file "
                            + value + " to " + target, ioe);
                    } finally {
                        if (dest != null) {
                            try {
                                dest.close();
                            } catch (IOException ignore) {
                            }
                        }
                        try {
                            src.close();
                        } catch (IOException ignore) {
                        }
                    }
                }
            }
        }

        // write the unsubstituted properties back to the overlay file
        OutputStream os = null;
        try {
            // ensure parent folder(s)
            propFile.getParentFile().mkdirs();

            os = new FileOutputStream(propFile);

            // copy the values into a temporary properties structure to store
            Properties tmp = new Properties();
            tmp.putAll(origProps);
            tmp.store(os, "Overlay properties for configuration");
        } catch (Exception ex) {
            this.logger.log(Logger.LOG_ERROR,
                "Error loading overlay properties from " + propFile, ex);
        } finally {
            if (os != null) {
                try {
                    os.close();
                } catch (IOException ex2) {
                    // Nothing we can do.
                }
            }
        }

        return props;
    }

    /**
     * Scans the properties for any properties starting with the given
     * <code>prefix</code> (e.g. <code>sling.bootdelegation.</code>).
     * <ol>
     * <li>Each such property is checked, whether it actually starts with
     * <code>prefix<b>class.</b></code>. If so, the rest of the property
     * name is assumed to be a fully qualified class name which is check,
     * whether it is visible. If so, the value of the property is appended to
     * the value of the <code>osgiProp</code>. If the class cannot be loaded,
     * the property is ignored.
     * <li>Otherwise, if the property does not contain a fully qualified class
     * name, the value of the property is simply appended to the
     * <code>osgiProp</code>.
     * </ol>
     *
     * @param props The <code>Properties</code> to be scanned.
     * @param osgiProp The name of the property in <code>props</code> to which
     *            any matching property values are appended.
     * @param prefix The prefix of properties to handle.
     */
    private void resolve(Map<String, String> props, String osgiProp,
            String prefix) {
        final String propVal = props.get(osgiProp);
        StringBuffer prop = new StringBuffer(propVal == null ? "" : propVal);
        boolean mod = false;
        for (Entry<String, String> pEntry : props.entrySet()) {
            String key = pEntry.getKey();
            if (key.startsWith(prefix)) {
                if (key.indexOf("class.") == prefix.length()) {
                    // prefix is followed by checker class name
                    String className = key.substring(prefix.length()
                        + "class.".length());
                    try {
                        Class.forName(className, true,
                            this.getClass().getClassLoader());
                    } catch (Throwable t) {
                        // don't really care, but class checking failed, so we
                        // do not add
                        this.logger.log(Logger.LOG_DEBUG, "Class " + className
                            + " not found. Ignoring '" + pEntry.getValue()
                            + "' for property " + osgiProp);
                        continue;
                    }
                }

                // get here if class is known or no checker class
                this.logger.log(Logger.LOG_DEBUG, "Adding '"
                    + pEntry.getValue() + "' to property " + osgiProp);
                if (prop.length() > 0) {
                    prop.append(',');
                }
                prop.append(pEntry.getValue());
                mod = true;
            }
        }

        // replace the property with the modified property
        if (mod) {
            this.logger.log(Logger.LOG_DEBUG, "Setting property " + osgiProp
                + " to " + prop.toString());
            props.put(osgiProp, prop.toString());
        }
    }

    private void setInstallBundles(Map<String, String> props) {
        String prefix = "sling.install.";
        Set<String> levels = new TreeSet<String>();
        for (String key : props.keySet()) {
            if (key.startsWith(prefix)) {
                levels.add(key.substring(prefix.length()));
            }
        }

        StringBuffer buf = new StringBuffer();
        for (String level : levels) {
            if (buf.length() > 0) {
                buf.append(',');
            }
            buf.append(level);
        }

        props.put(prefix + "bundles", buf.toString());
    }

    /**
     * Ensures sensible Execution Environment setting. If the
     * <code>org.osgi.framework.executionenvironment</code> property is set in
     * the configured properties or the system properties, we ensure that older
     * settings for J2SE-1.2, J2SE-1.3 and J2SE-1.4 are included. If the
     * property is neither set in the configuration properties nor in the system
     * properties, the property is not set.
     *
     * @param props The configuration properties to check and optionally ammend.
     */
    private void setExecutionEnvironment(Map<String, String> props) {
        // get the current Execution Environment setting
        String ee = props.get(Constants.FRAMEWORK_EXECUTIONENVIRONMENT);
        if (ee == null) {
            ee = System.getProperty(Constants.FRAMEWORK_EXECUTIONENVIRONMENT);
        }

        // if there is a setting, ensure J2SE-1.2/3/4/5 is included in the list
        if (ee != null) {
            int javaMinor;
            try {
                String specVString = System.getProperty("java.specification.version");
                javaMinor = Version.parseVersion(specVString).getMinor();
            } catch (IllegalArgumentException iae) {
                // don't care, assume minimal sling version (1.5)
                javaMinor = 5;
            }

            for (int i = 2; i <= javaMinor; i++) {
                String exEnv = "J2SE-1." + i;
                if (ee.indexOf(exEnv) < 0) {
                    ee += "," + exEnv;
                }
            }

            this.logger.log(Logger.LOG_INFO,
                "Using Execution Environment setting: " + ee);
            props.put(Constants.FRAMEWORK_EXECUTIONENVIRONMENT, ee);
        } else {
            this.logger.log(Logger.LOG_INFO,
                "Not using Execution Environment setting");
        }
    }

    // ---------- Extension support --------------------------------------------

    /**
     * Loads additional properties into the <code>properties</code> object.
     * <p>
     * This implementation does nothing and may be overwritten by extensions
     * requiring additional properties to be set.
     * <p>
     * This method is called when the servlet is initialized to prepare the
     * configuration for <code>Felix</code>. Implementations may add
     * properties from implementation specific sources. Properties added here
     * overwrite properties loaded from the default properties file and may be
     * overwritten by parameters set in the web application.
     * <p>
     * The <code>properties</code> object has not undergone variable
     * substition and properties added by this method may also contain values
     * refererring to other properties.
     * <p>
     * The properties added in this method will not be persisted in the
     * <code>sling.properties</code> file in the <code>sling.home</code>
     * directory.
     *
     * @param properties The <code>Properties</code> object to which custom
     *            properties may be added.
     */
    protected void loadPropertiesOverride(Map<String, String> properties) {
    }

    /**
     * Returns the <code>BundleContext</code> of the system bundle of the OSGi
     * framework launched by this servlet. This method only returns a non-<code>null</code>
     * object after the system bundle of the framework has been started and
     * before it is being stopped.
     */
    protected final BundleContext getBundleContext() {
        return this.bundleContext;
    }

    /**
     * Executes additional startup tasks and is called by the
     * {@link #start(BundleContext)} method.
     * <p>
     * This implementation does nothing and may be overwritten by extensions
     * requiring additional startup tasks.
     *
     * @throws Exception May be thrown in case of problems.
     */
    protected void doStartBundle() throws Exception {
    }

    /**
     * Executes additional shutdown tasks and is called by the
     * {@link #stop(BundleContext)} method.
     * <p>
     * This implementation does nothing and may be overwritten by extensions
     * requiring additional shutdown tasks.
     * <p>
     * When overwriting this method, it must be made sure, that no exception may
     * be thrown, otherwise unexpected behaviour may result.
     */
    protected void doStopBundle() {
    }

    // ---------- Property file support ----------------------------------------

    /**
     * Looks for <code>sling.include</code> and <code>sling.include.*</code>
     * properties in the <code>props</code> and loads properties form the
     * respective locations.
     * <p>
     * Each <code>sling.include</code> (or <code>sling.include.*</code>)
     * property may contain a comma-separated list of resource and/or file names
     * to be loaded from. The includes are loaded in alphabetical order of the
     * property names.
     * <p>
     * Each reasource path is first tried to be loaded through the
     * {@link #resourceProvider}. If that fails, the resource path is tested as
     * a file. If relative <code>slingHome</code> is used as the parent if not
     * <code>null</code>, otherwise the current working directory is used as
     * the parent.
     * <p>
     * Any non-existing resource is silently ignored.
     * <p>
     * When the method returns, the <code>sling.include</code> and
     * <code>sling.include.*</code> properties are not contained in the
     * <code>props</code> any more.
     *
     * @param props The <code>Properties</code> containing the
     *            <code>sling.include</code> and <code>sling.include.*</code>
     *            properties. This is also the destination for the new
     *            properties loaded.
     * @param slingHome The parent directory used to resolve relative path names
     *            if loading from a file. This may be <code>null</code> in
     *            which case the current working directory is used as the
     *            parent.
     */
    private void loadIncludes(Map<String, String> props, String slingHome) {
        // Build the sort map of include properties first
        // and remove include elements from the properties
        SortedMap<String, String> includes = new TreeMap<String, String>();
        for (Iterator<Entry<String, String>> pi = props.entrySet().iterator(); pi.hasNext();) {
            Entry<String, String> entry = pi.next();
            if (entry.getKey().startsWith("sling.include.")
                || entry.getKey().equals("sling.include")) {
                includes.put(entry.getKey(), entry.getValue());
                pi.remove();
            }
        }

        for (Iterator<Entry<String, String>> ii = includes.entrySet().iterator(); ii.hasNext();) {
            Map.Entry<String, String> entry = ii.next();
            String key = entry.getKey();
            String include = entry.getValue();

            // ensure variable resolution on this property
            include = substVars(include, key, null, props);

            StringTokenizer tokener = new StringTokenizer(include, ",");
            while (tokener.hasMoreTokens()) {
                String file = tokener.nextToken().trim();
                InputStream is = this.resourceProvider.getResourceAsStream(file);
                try {
                    if (is == null && slingHome != null) {
                        File resFile = new File(file);
                        if (!resFile.isAbsolute()) {
                            resFile = new File(slingHome, file);
                        }
                        if (resFile.canRead()) {
                            is = new FileInputStream(resFile);
                            file = resFile.getAbsolutePath(); // for logging
                        }
                    }

                    if (is != null) {
                        this.load(props, is);
                    }
                } catch (IOException ioe) {
                    this.logger.log(Logger.LOG_ERROR,
                        "Error loading config properties from " + file, ioe);
                }
            }
        }
    }

    /**
     * Load properties from the given resource file, which is accessed through
     * the {@link #resourceProvider}. If the resource does not exist, nothing
     * is loaded.
     *
     * @param props The <code>Properties</code> into which the loaded
     *            properties are loaded
     * @param resource The resource from which to load the resources
     */
    private void load(Map<String, String> props, String resource) {
        InputStream is = this.resourceProvider.getResourceAsStream(resource);
        if (is != null) {
            try {
                this.load(props, is);
            } catch (IOException ioe) {
                this.logger.log(Logger.LOG_ERROR,
                    "Error loading config properties from " + resource, ioe);
            }
        }
    }

    /**
     * Load properties from the given file. If the resource cannot be read from
     * (e.g. because it does not exist), nothing is loaded.
     *
     * @param props The <code>Properties</code> into which the loaded
     *            properties are loaded
     * @param file The <code>File</code> to load the properties from
     */
    private void load(Map<String, String> props, File file) {
        if (file != null && file.canRead()) {
            try {
                this.load(props, new FileInputStream(file));
            } catch (IOException ioe) {
                this.logger.log(Logger.LOG_ERROR,
                    "Error loading config properties from "
                        + file.getAbsolutePath(), ioe);
            }
        }
    }

    private void load(Map<String, String> props, InputStream ins)
            throws IOException {
        try {
            Properties tmp = new Properties();
            tmp.load(ins);

            for (Map.Entry<Object, Object> entry : tmp.entrySet()) {
                props.put((String) entry.getKey(), (String) entry.getValue());
            }
        } finally {
            try {
                ins.close();
            } catch (IOException ioe2) {
                // ignore
            }
        }
    }

    // ---------- Property file variable substition support --------------------

    /**
     * The starting delimiter of variable names (value is "${").
     */
    private static final String DELIM_START = "${";

    /**
     * The ending delimiter of variable names (value is "}").
     */
    private static final String DELIM_STOP = "}";

    /**
     * This method performs property variable substitution on the specified
     * value. If the specified value contains the syntax
     * <tt>${&lt;prop-name&gt;}</tt>, where <tt>&lt;prop-name&gt;</tt>
     * refers to either a configuration property or a system property, then the
     * corresponding property value is substituted for the variable placeholder.
     * Multiple variable placeholders may exist in the specified value as well
     * as nested variable placeholders, which are substituted from inner most to
     * outer most. Configuration properties override system properties.
     *
     * @param val The string on which to perform property substitution.
     * @param currentKey The key of the property being evaluated used to detect
     *            cycles.
     * @param cycleMap Map of variable references used to detect nested cycles.
     * @param configProps Set of configuration properties.
     * @return The value of the specified string after system property
     *         substitution.
     * @throws IllegalArgumentException If there was a syntax error in the
     *             property placeholder syntax or a recursive variable
     *             reference.
     */
    private static String substVars(String val, String currentKey,
            Map<String, String> cycleMap, Map<String, String> configProps)
            throws IllegalArgumentException {
        // If there is currently no cycle map, then create
        // one for detecting cycles for this invocation.
        if (cycleMap == null) {
            cycleMap = new HashMap<String, String>();
        }

        // Put the current key in the cycle map.
        cycleMap.put(currentKey, currentKey);

        // Assume we have a value that is something like:
        // "leading ${foo.${bar}} middle ${baz} trailing"

        // Find the first ending '}' variable delimiter, which
        // will correspond to the first deepest nested variable
        // placeholder.
        int stopDelim = val.indexOf(DELIM_STOP);

        // Find the matching starting "${" variable delimiter
        // by looping until we find a start delimiter that is
        // greater than the stop delimiter we have found.
        int startDelim = val.indexOf(DELIM_START);
        while (stopDelim >= 0) {
            int idx = val.indexOf(DELIM_START, startDelim
                + DELIM_START.length());
            if ((idx < 0) || (idx > stopDelim)) {
                break;
            } else if (idx < stopDelim) {
                startDelim = idx;
            }
        }

        // If we do not have a start or stop delimiter, then just
        // return the existing value.
        if ((startDelim < 0) && (stopDelim < 0)) {
            return val;
        }
        // At this point, we found a stop delimiter without a start,
        // so throw an exception.
        else if (((startDelim < 0) || (startDelim > stopDelim))
            && (stopDelim >= 0)) {
            throw new IllegalArgumentException(
                "stop delimiter with no start delimiter: " + val);
        }

        // At this point, we have found a variable placeholder so
        // we must perform a variable substitution on it.
        // Using the start and stop delimiter indices, extract
        // the first, deepest nested variable placeholder.
        String variable = val.substring(startDelim + DELIM_START.length(),
            stopDelim);

        // Verify that this is not a recursive variable reference.
        if (cycleMap.get(variable) != null) {
            throw new IllegalArgumentException("recursive variable reference: "
                + variable);
        }

        // Get the value of the deepest nested variable placeholder.
        // Try to configuration properties first.
        String substValue = (configProps != null)
                ? configProps.get(variable)
                : null;
        if (substValue == null) {
            // Ignore unknown property values.
            substValue = System.getProperty(variable, "");
        }

        // Remove the found variable from the cycle map, since
        // it may appear more than once in the value and we don't
        // want such situations to appear as a recursive reference.
        cycleMap.remove(variable);

        // Append the leading characters, the substituted value of
        // the variable, and the trailing characters to get the new
        // value.
        val = val.substring(0, startDelim) + substValue
            + val.substring(stopDelim + DELIM_STOP.length(), val.length());

        // Now perform substitution again, since there could still
        // be substitutions to make.
        val = substVars(val, currentKey, cycleMap, configProps);

        // Return the value.
        return val;
    }
}

`org.apache.sling.launcher.app.BootstrapInstaller`, Revision 688973

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.sling.launcher.app;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.util.HashMap;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;

import org.apache.felix.framework.Logger;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.BundleException;
import org.osgi.framework.Constants;
import org.osgi.framework.ServiceReference;
import org.osgi.service.startlevel.StartLevel;

/**
 * The <code>BootstrapInstaller</code> class is installed into the OSGi
 * framework as an activator to be called when the framework is starting up.
 * Upon startup all bundles from the {@link #PATH_CORE_BUNDLES} and the
 * {@link #PATH_BUNDLES} location are checked whether they are already installed
 * or not. If they are not installed, they are installed, their start level set
 * to 1 and started. Any bundle already installed is not installed again and
 * will also not be started here.
 */
class BootstrapInstaller implements BundleActivator {

    /**
     * The Bundle location scheme (protocol) used for bundles installed by this
     * activator (value is "slinginstall:"). The path part of the Bundle
     * location of Bundles installed by this class is the name (without the
     * path) of the resource from which the Bundle was installed.
     */
    public static final String SCHEME = "slinginstall:";

    /**
     * The location the core Bundles (value is "resources/corebundles"). These
     * bundles are installed first.
     */
    public static final String PATH_CORE_BUNDLES = "resources/corebundles";

    /**
     * The location the additional Bundles (value is "resources/bundles"). These
     * Bundles are installed after the {@link #PATH_CORE_BUNDLES core Bundles}.
     */
    public static final String PATH_BUNDLES = "resources/bundles";

    /**
     * The {@link Logger} use for logging messages during installation and
     * startup.
     */
    private final Logger logger;

    /**
     * The {@link ResourceProvider} used to access the Bundle jar files to
     * install.
     */
    private final ResourceProvider resourceProvider;

    /** The data file which works as a marker to detect the first startup. */
    private static final String DATA_FILE = "bootstrapinstaller.ser";

    BootstrapInstaller(Logger logger, ResourceProvider resourceProvider) {
        this.logger = logger;
        this.resourceProvider = resourceProvider;
    }

    /**
     * Installs any Bundles missing in the current framework instance. The
     * Bundles are verified by the Bundle location string. All missing Bundles
     * are first installed and then started in the order of installation.
     * Also install all deployment packages.
     *
     * This installation stuff is only performed during the first startup!
     */
    public void start(BundleContext context) throws Exception {
        boolean alreadyInstalled = false;
        final File dataFile = context.getDataFile(DATA_FILE);
        if ( dataFile != null && dataFile.exists() ) {
            try {
                final FileInputStream fis = new FileInputStream(dataFile);
                try {
                    final ObjectInputStream ois = new ObjectInputStream(fis);
                    try {
                        alreadyInstalled = ois.readBoolean();
                    } finally {
                        try {
                            ois.close();
                        } catch (IOException ignore) {}
                    }
                } finally {
                    try {
                        fis.close();
                    } catch (IOException ignore) {}
                }
            } catch (IOException ioe) {
                logger.log(Logger.LOG_ERROR, "IOException during reading of installed flag.", ioe);
            }
        }

        if ( !alreadyInstalled ) {
            // register deployment package support
            final DeploymentPackageInstaller dpi =
                new DeploymentPackageInstaller(context, logger, resourceProvider);
            context.addFrameworkListener(dpi);
            context.addServiceListener(dpi, "("
                    + Constants.OBJECTCLASS + "=" + DeploymentPackageInstaller.DEPLOYMENT_ADMIN + ")");

            // list all existing bundles
            Bundle[] bundles = context.getBundles();
            Map<String, Bundle> byLocation = new HashMap<String, Bundle>();
            for (int i = 0; i < bundles.length; i++) {
                byLocation.put(bundles[i].getLocation(), bundles[i]);
            }

            // install bundles
            List<Bundle> installed = new LinkedList<Bundle>();
            installBundles(context, byLocation, PATH_CORE_BUNDLES, installed);
            installBundles(context, byLocation, PATH_BUNDLES, installed);

            try {
                final FileOutputStream fos = new FileOutputStream(dataFile);
                try {
                    final ObjectOutputStream oos = new ObjectOutputStream(fos);
                    try {
                        oos.writeBoolean(true);
                    } finally {
                        try {
                            oos.close();
                        } catch (IOException ignore) {}
                    }
                } finally {
                    try {
                        fos.close();
                    } catch (IOException ignore) {}
                }
            } catch (IOException ioe) {
                logger.log(Logger.LOG_ERROR, "IOException during writing of installed flag.", ioe);
            }

            // set start levels on the bundles and start them
            startBundles(context, installed);
        }
    }

    /** Nothing to be done on stop */
    public void stop(BundleContext context) {
    }

    /**
     * Install the Bundles from JAR files found in the given <code>parent</code>
     * path.
     *
     * @param context The <code>BundleContext</code> used to install the new
     *            Bundles.
     * @param currentBundles The currently installed Bundles indexed by their
     *            Bundle location.
     * @param parent The path to the location in which to look for JAR files to
     *            install. Only resources whose name ends with <em>.jar</em>
     *            are considered for installation.
     * @param installed The list of Bundles installed by this method. Each
     *            Bundle successfully installed is added to this list.
     */
    private void installBundles(BundleContext context,
            Map<String, Bundle> currentBundles, String parent,
            List<Bundle> installed) {

        Iterator<String> res = resourceProvider.getChildren(parent);
        while (res.hasNext()) {

            String path = res.next();

            if (path.endsWith(".jar")) {

                // check for an already installed Bundle with the given location
                String location = SCHEME
                    + path.substring(path.lastIndexOf('/') + 1);
                if (currentBundles.containsKey(location)) {
                    continue;
                }

                // try to access the JAR file, ignore if not possible
                InputStream ins = resourceProvider.getResourceAsStream(path);
                if (ins == null) {
                    continue;
                }

                // install the JAR file as a bundle
                Bundle newBundle;
                try {
                    newBundle = context.installBundle(location, ins);
                    logger.log(Logger.LOG_INFO, "Bundle "
                        + newBundle.getSymbolicName() + " installed from "
                        + location);
                } catch (BundleException be) {
                    logger.log(Logger.LOG_ERROR, "Bundle installation from "
                        + location + " failed", be);
                    continue;
                }

                // finally add the bundle to the list for later start
                installed.add(newBundle);
            }
        }
    }

    /**
     * Starts the Bundles in the <code>bundles</code> list. If the framework
     * provides an active <code>StartLevel</code> service, the start levels of
     * the Bundles is first set to <em>1</em>.
     */
    private void startBundles(BundleContext context, List<Bundle> bundles) {

        // the start level service to set the initial start level
        ServiceReference ref = context.getServiceReference(StartLevel.class.getName());
        StartLevel startLevel = (ref != null)
                ? (StartLevel) context.getService(ref)
                : null;

        // start all bundles
        for (Bundle bundle : bundles) {

            if (startLevel != null) {
                startLevel.setBundleStartLevel(bundle, 1);
            }

            try {
                bundle.start();
            } catch (BundleException be) {
                logger.log(Logger.LOG_ERROR, "Bundle "
                    + bundle.getSymbolicName() + " could not be started", be);
            }
        }

        // release the start level service
        if (ref != null) {
            context.ungetService(ref);
        }
    }

}

`org.apache.sling.launcher.app.main.Main`, Revision 667440

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.sling.launcher.app.main;

import static org.apache.felix.framework.util.FelixConstants.LOG_LEVEL_PROP;

import java.util.HashMap;
import java.util.Map;

import org.apache.felix.framework.Logger;
import org.apache.sling.commons.log.LogManager;
import org.apache.sling.launcher.app.ClassLoaderResourceProvider;
import org.apache.sling.launcher.app.ResourceProvider;
import org.apache.sling.launcher.app.Sling;
import org.osgi.framework.BundleException;
import org.osgi.framework.Constants;

/**
 * The <code>Main</code> class is a simple Java Application which interprests
 * the command line and creates the {@link Sling} launcher class and thus starts
 * the OSGi framework. In addition a shutdown thread is registered to ensure
 * proper shutdown on VM termination.
 * <p>
 * The supported command line options are:
 * <dl>
 * <dt>-l loglevel</dt>
 * <dd>Sets the initial loglevel as an integer in the range 0 to 4 or as one of
 * the well known level strings FATAL, ERROR, WARN, INFO or DEBUG. This option
 * overwrites the <code>org.apache.sling.osg.log.level</code> setting the
 * <code>sling.properties</code> file.</dd>
 * <dt>-f logfile</dt>
 * <dd>The log file, \"-\" for stdout (default logs/error.log). This option
 * overwrites the <code>org.apache.sling.osg.log.file</code> setting the
 * <code>sling.properties</code> file.</dd>
 * <dt>-c slinghome</dt>
 * <dd>The directory in which Sling locates its initial configuration file
 * <code>sling.properties</code> and where files of Sling itself such as the
 * Apache Felix bundle archive or the JCR repository files are stored (default
 * sling).</dd>
 * <dt>-a address</dt>
 * <dd>The interfact to bind to (use 0.0.0.0 for any). This option is not
 * implemented yet.</dd>
 * <dt>-p port</dt>
 * <dd>The port to listen (default 8080) to handle HTTP requests. This option
 * overwrites the <code>org.osgi.service.http.port</code> setting the
 * <code>sling.properties</code> file.</dd>
 * <dt>-h</dt>
 * <dd>Prints a simple usage message listing all available command line
 * options.</dd>
 * </dl>
 */
public class Main {

    /** Mapping between log level numbers and names */
    private static final String[] logLevels = { "FATAL", "ERROR", "WARN",
        "INFO", "DEBUG" };

    /** The Sling configuration property name setting the initial log level */
    private static final String PROP_LOG_LEVEL = LogManager.LOG_LEVEL;

    /** The Sling configuration property name setting the initial log file */
    private static final String PROP_LOG_FILE = LogManager.LOG_FILE;

    /** Default log level setting if no set on command line (value is "INFO"). */
    private static final int DEFAULT_LOG_LEVEL = Logger.LOG_INFO;

    /**
     * The configuration property setting the port on which the HTTP service
     * listens
     */
    private static final String PROP_PORT = "org.osgi.service.http.port";

    /** The default port on which the HTTP service listens. */
    private static final String DEFAULT_PORT = "8080";

    /**
     * The property value to export the Servlet API 2.5 from the system
     * bundle.
     */
    private static final String SERVLET_API_EXPORT =
        "javax.servlet;javax.servlet.http;javax.servlet.resources; version=2.5";

    /** The parsed command line mapping (Sling) option name to option value */
    private static Map<String, String> commandLine;

    public static void main(String[] args) throws Exception {
        // creating the instance launches the framework and we are done here ..
        Map<String, String> props = new HashMap<String, String>();

        // parse the command line (exit in case of failure)
        commandLine = new HashMap<String, String>();
        commandLine.put(PROP_PORT, DEFAULT_PORT);
        parseCommandLine(args, commandLine);

        // if sling.home was set on the command line, set it in the properties
        if (commandLine.containsKey(Sling.SLING_HOME)) {
            props.put(Sling.SLING_HOME, commandLine.get(Sling.SLING_HOME));
        }

        // overwrite the loadPropertiesOverride method to inject the command
        // line arguments unconditionally. These will not be persisted in any
        // properties file, though

        // set up and configure Felix Logger
        int logLevel;
        if (!commandLine.containsKey(PROP_LOG_LEVEL)) {
            logLevel = DEFAULT_LOG_LEVEL;
        } else {
            logLevel = toLogLevelInt(commandLine.get(PROP_LOG_LEVEL),
                DEFAULT_LOG_LEVEL);
            commandLine.put(LOG_LEVEL_PROP, String.valueOf(logLevel));
        }
        Logger logger = new Logger();

        // prevent tons of needless WARN from the framework
        // logger.setLogLevel(logLevel);
        logger.setLogLevel(Logger.LOG_ERROR);

        // prevent tons of needless WARN messages from the framework
        // logger.setLogLevel(logLevel);
        logger.setLogLevel(Logger.LOG_ERROR);

        try {
            ResourceProvider resProvider = new ClassLoaderResourceProvider(
                Main.class.getClassLoader());
            Sling sling = new Sling(logger, resProvider, props) {
                protected void loadPropertiesOverride(
                        Map<String, String> properties) {
                    if (commandLine != null) {
                        properties.putAll(commandLine);
                    }

                    // add Servlet API to the system bundle exports
                    String sysExport = properties.get(Constants.FRAMEWORK_SYSTEMPACKAGES);
                    if (sysExport == null) {
                        sysExport = SERVLET_API_EXPORT;
                    } else {
                        sysExport += "," + SERVLET_API_EXPORT;
                    }
                    properties.put(Constants.FRAMEWORK_SYSTEMPACKAGES,
                        sysExport);
                }
            };

            Runtime.getRuntime().addShutdownHook(new TerminateSling(sling));
        } catch (BundleException be) {
            log("Failed to Start OSGi framework");
            be.printStackTrace(System.err);
            System.exit(2);
        }
    }

    private static class TerminateSling extends Thread {
        private final Sling sling;

        TerminateSling(Sling sling) {
            super("Sling Terminator");
            this.sling = sling;
        }

        public void run() {
            if (this.sling != null) {
                this.sling.destroy();
            }
        }
    }

    /**
     * Parses the command line in <code>args</code> and sets appropriate Sling
     * configuration options in the <code>props</code> map.
     */
    private static void parseCommandLine(String[] args,
            Map<String, String> props) {
        for (int argc = 0; argc < args.length; argc++) {
            String arg = args[argc];
            if (arg.startsWith("-")) {

                // require at least another character naming the option
                if (arg.length() != 2) {
                    usage("Missing option name", 1);
                }

                // option argument is following the current option
                argc++;
                String value = argc < args.length ? args[argc] : null;

                switch (arg.charAt(1)) {
                    case 'l':
                        if (value == null) {
                            usage("Missing log level value", 1);
                            continue;
                        }
                        try {
                            int logLevel = Integer.parseInt(value);
                            value = toLogLevel(logLevel);
                        } catch (NumberFormatException nfe) {
                            // might be a log level string
                            value = checkLogLevel(value);
                        }
                        if (value != null) {
                            props.put(PROP_LOG_LEVEL, value);
                        }
                        break;

                    case 'f':
                        if (value == null) {
                            usage("Missing log file value", 1);
                            continue;
                        } else if ("-".equals(value)) {
                            value = "";
                        }
                        props.put(PROP_LOG_FILE, value);
                        break;

                    case 'c':
                        if (value == null) {
                            usage("Missing directory value", 1);
                            continue;
                        }
                        props.put(Sling.SLING_HOME, value);
                        break;

                    case 'p':
                        if (value == null) {
                            usage("Missing port value", 1);
                            continue;
                        }
                        try {
                            // just to verify it is a number
                            Integer.parseInt(value);
                            props.put(PROP_PORT, value);
                        } catch (RuntimeException e) {
                            usage("Bad port: " + value, 1);
                        }
                        break;

                    case 'a':
                        if (value == null) {
                            usage("Missing address value", 1);
                            continue;
                        }
                        log("Setting the address to bind to is not supported, binding to 0.0.0.0");
                        break;

                    case 'h':
                        usage(null, 0);

                    default:
                        usage("Unrecognized option " + arg, 1);
                        break;
                }
            }
        }
    }

    /** prints a simple usage plus optional error message and exists with code */
    private static void usage(String message, int code) {
        if (message != null) {
            log(message);
            log("");
        }

        log("usage: "
            + Main.class.getName()
            + " [ -l loglevel ] [ -f logfile ] [ -c slinghome ] [ -a address ] [ -p port ] [ -h ]");

        log("    -l loglevel   the initial loglevel (0..4, FATAL, ERROR, WARN, INFO, DEBUG)");
        log("    -f logfile    the log file, \"-\" for stdout (default logs/error.log)");
        log("    -c slinghome  the sling context directory (default sling)");
        log("    -a address    the interfact to bind to (use 0.0.0.0 for any) (not supported yet)");
        log("    -p port       the port to listen to (default 8080)");
        log("    -h            prints this usage message");

        // exiting now
        System.exit(code);
    }

    /** Writes the message to stderr output */
    private static void log(String message) {
        System.err.println(message);
    }

    /** Converts the loglevel code to a loglevel string name */
    private static String toLogLevel(int level) {
        if (level >= 0 && level < logLevels.length) {
            return logLevels[level];
        }

        usage("Bad log level: " + level, 1);
        return null;
    }

    /** Verifies the log level is one of the known values, returns null otherwise */
    private static String checkLogLevel(String level) {
        for (int i = 0; i < logLevels.length; i++) {
            if (logLevels[i].equalsIgnoreCase(level)) {
                return logLevels[i];
            }
        }

        usage("Bad log level: " + level, 1);
        return null;
    }

    /** Return the log level code for the string */
    private static int toLogLevelInt(String level, int defaultLevel) {
        for (int i = 0; i < logLevels.length; i++) {
            if (logLevels[i].equalsIgnoreCase(level)) {
                return i;
            }
        }

        return defaultLevel;
    }
}

Sling OSGi Track pt 7: configuring services at runtime

2008-09-09T10:22:00.001+02:00

This is the continuation of

In this part, I will explain how to use the OSGi configuration management to configure services at runtime.

Suppose I want a service that can do more than just say "hello". I want the phrase the service returns from the sayHello() method to be configurable at runtime. This is easily done through OSGi configuration management.

Aims:

Show how to introduce a configurable property into an OSGi bundle
Show how to change the configuration through the OSGi configuration manager

Ingredients:

Files:

Outline:

Project Structure
Changes to the implementation
The pom
The results
Testing

Execution

Project Structure

From here on, I am no longer bundling the sample client script, as we've done our own client servlet in part 6 of this track. So we're back to just the pom, the interface and the implementation.

.
|-- pom.xml
`-- src
    `-- main
        `-- java
            `-- mh
                `-- osgitest
                    |-- SampleService.java
                    `-- SampleServiceImpl.java

Changes to the implementation

The only semantic change is in lines 18 and 21: a property helloPhrase is introduced and the value that is returned from the "sayHello()" method is read from that property.

Lines 11-14 introduce a constant, PROP_HELLO_PHRASE. The value of that constant will be used as a key to store the actual value. Line 12 points to the DEFAULT_HELLO_PHRASE constant for the default value. The following would have been equivalent, but it's better practice to use constants, so that the default value can be reffered to from Java code.

	/**
	 * @scr.property value="hello"
	 */
	public static final String PROP_HELLO_PHRASE = "mh.osgitest.helloPhrase";

the activate() method is called when the component is activated. At that point, we can obtain configuration values from the properties that are part of the ComponentContext that is passed as the method's argument.

package mh.osgitest;

import org.osgi.service.component.ComponentContext;

/**
 * @scr.component immediate="true"
 * @scr.service interface="SampleService"
 */
public class SampleServiceImpl implements SampleService {

	/**
	 * @scr.property valueRef="DEFAULT_HELLO_PHRASE"
	 */
	public static final String PROP_HELLO_PHRASE = "mh.osgitest.helloPhrase";

	public static final String DEFAULT_HELLO_PHRASE = "hello";

	private String helloPhrase;

	public String sayHello() {
		return helloPhrase;
	}

	protected void activate(ComponentContext context) {
		Object helloPhrase = context.getProperties().get(PROP_HELLO_PHRASE);
		if (helloPhrase != null)
			this.helloPhrase = helloPhrase.toString();
	}
}

The pom

The pom is very straight forward. Nothing special here.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>mh.studies</groupId>
	<artifactId>mh.studies.sling.osgitest</artifactId>
	<name>OSGI Test Bundle</name>
	<version>0.0.7</version>
	<packaging>bundle</packaging>
	<description />
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>1.5</source>
					<target>1.5</target>
				</configuration>
			</plugin>
			<plugin>
				<groupId>org.apache.sling</groupId>
				<artifactId>maven-sling-plugin</artifactId>
				<version>2.0.2-incubator</version>
				<executions>
					<execution>
						<id>install-bundle</id>
						<goals>
							<goal>install</goal>
						</goals>
						<configuration>
							<slingUrl> http://localhost:7402/system/console/install</slingUrl>
							<user>admin</user>
							<password>admin</password>
						</configuration>
					</execution>
				</executions>
			</plugin>
			<plugin>
			    <groupId>org.apache.felix</groupId>
			    <artifactId>maven-scr-plugin</artifactId>
			    <version>1.0.7</version>
			    <executions>
			        <execution>
			            <id>generate-scr-scrdescriptor</id>
			            <goals>
			                <goal>scr</goal>
			            </goals>
			        </execution>
			    </executions>
			</plugin>			
			<plugin>
				<groupId>org.apache.felix</groupId>
				<artifactId>maven-bundle-plugin</artifactId>
				<version>1.4.3</version>
				<extensions>true</extensions>
				<configuration>
					<instructions>
						<Export-Package>mh.osgitest</Export-Package>
						<Import-Package>
                            org.osgi.framework;version="1.3.0",
                            org.osgi.service.component
                        </Import-Package>
						<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
						<Bundle-Name>${pom.name}</Bundle-Name>
						<Bundle-Vendor>Moritz Havelock</Bundle-Vendor>
					</instructions>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<repositories>
		<repository>
			<id>apache.incubating</id>
			<name>Apache Incubating Repository</name>
			<url>http://people.apache.org/repo/m2-incubating-repository</url>
		</repository>
	</repositories>
	<pluginRepositories>
		<pluginRepository>
			<id>apache.incubating.plugins</id>
			<name>Apache Incubating Plugin Repository</name>
			<url>http://people.apache.org/repo/m2-incubating-repository
			</url>
		</pluginRepository>
	</pluginRepositories>
	<dependencies>
		<dependency>
			<groupId>org.apache.felix</groupId>
			<artifactId>org.osgi.core</artifactId>
			<version>1.0.1</version>
		</dependency>
            <dependency>
            <groupId>org.apache.felix</groupId>
            <artifactId>org.osgi.compendium</artifactId>
            <version>1.0.1</version>
        </dependency>
	</dependencies>
</project>

The results

After deploying the Bundle, I do a quick test and call http://localhost:7402/system/osgitest/info. That requires that the Servlet from the last part is still installed. If you have not followed along, grab it from here: http://in-the-sling.blogspot.com/2008/09/sling-osgi-track-pt-6-sling-servlets-i.html.

As expected, I get the result "hello".

Now, I hit the OSGi configuration management console at http://localhost:7402/system/console/configMgr and select my bundle from the drop down:

Don't be confused by the naming of the entries. They can easily be replaced, but I will keep focused on the important stuff for a while and leave these out of consideration.

I get the following screen, which allows me to configure the component's properties. In our case, that is the "helloPhrase" property, which I can change by entering a new value into the text box and hitting "save".

Testing

The final test is to again hit http://localhost:7402/system/osgitest/info, which should now return the new value of the "helloPhrase" property.

Technorati Tags: CRX,Sling,OSGi

Sling OSGI Track pt 6: Sling Servlets I

2008-09-03T23:44:00.001+02:00

This is the continuation of

In this part, I will show how to create your own Sling Servlet and deploy it as an OSGi Bundle.

As you may have seen from the sling documentation, there is a pretty straightforward way to create scripts on the search paths (/apps, /libs) that will be executed depending on properties of the requested resource (most notably sling:resourceType.

You can do the same using servlets, if you prefer.
Using servlets, you can also do a lot more than with scripts, and we'll have a first look at what can be done right now.
As a first easy example, I will show how to create a servlet that uses the service created in the previous parts and makes the output available at /system/osgitest/info .

Aims:

Show how to create a Sling Servlet and register it to respond to a preset path.

Ingredients:

Files:

Outline:

Project structure
The servlet implementation
The pom: nothing special
Maven dependencies: oops
Build, Deploy, Test

Execution:

Project structure

The project structure is simpler than anything we had so far. We actually need no more than the servlet implementation and the pom. Let's have a look:

.
|-- pom.xml
`-- src
    `-- main
        `-- java
            `-- mh
                `-- osgitest
                    `-- client
                        `-- OsgiTestClientServlet.java

The servlet implementation

Let's have a look at the servlet implementation:

The servlet extends SlingSafeMethodsServlet (l. 25).
This is a sling-provided class that can be extended to implement servlets that do not have side-effects, i.e. do not modify data. See http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/servlets/SlingSafeMethodsServlet.java?view=markup for the details.
The servlet overrides the doGet method (l. 31ff).
In this method, it checks whether it's "service" variable is set (which is of the type 'SampleService' from our previous parts of this track), and if so calls sayHello() on the object to write the result to the output stream.
OK, so how can the service variable ever be anything but null? That happens through the src.reference directive in line 27. This will create an OSGi service descriptor, and the OSGi container will inject the reference to a SampleService instance, if available.
In line 22, the sling.servlet.paths property is set to /system/osgitest/info. This creates the mapping to the URL /system/osgitest/info, which the servlet will respond to.
There are many other options of creating mappings depending on the resource that is being accessed, depending on method, etc. Part of this is explained in http://incubator.apache.org/sling/site/servlet-resolution.html, but that description is outdated. I'll look into the other options in further posts.

package mh.osgitest.client;

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletResponse;

import mh.osgitest.SampleService;

import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.SlingHttpServletResponse;
import org.apache.sling.api.servlets.SlingSafeMethodsServlet;

/**
 * A Servlet that uses the service provided in the mh.osgitest to retrieve the
 * phrase "hello".
 * 
 * @scr.component immediate="true" metatype="no"
 * @scr.service interface="javax.servlet.Servlet"
 * @scr.property name="service.description" value="Sample OSGi Client Servlet"
 * @scr.property name="service.vendor" value="Moritz Havelock"
 * @scr.property name="sling.servlet.paths" value="/system/osgitest/info"
 */
@SuppressWarnings("serial")
public class OsgiTestClientServlet extends SlingSafeMethodsServlet {
	
	/** @scr.reference */
	private final SampleService service = null;

	@Override
	protected void doGet(SlingHttpServletRequest request,
			SlingHttpServletResponse response) throws ServletException,
			IOException {
		if (service == null) {
			response.sendError(HttpServletResponse.SC_SERVICE_UNAVAILABLE,
					"no reference to service available");
		} else {
			response.setContentType("text/plain");
			response.getOutputStream().print(service.sayHello());
		}
	}
}

The pom: nothing special

The pom looks quite familiar. What's different this time?
On lines 93-97, we have a dependency on the org.apache.sling.api artifact. That is because we are using sling specific types in the servlet implementation. I have here used the version 2.0.0.incubator-SNAPSHOT, which is what comes with CRX Cup edition.
On lines 98-102, we depend on the mh.studies.sling.osgitest artifact. This should be in your m2 repository from the previous tracks.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>mh.studies</groupId>
   <artifactId>mh.studies.sling.osgitest.client</artifactId>
   <packaging>bundle</packaging>
   <name>A Servlet Client for the OSGi Test Bundle</name>
   <version>0.0.1</version>
   <description />
   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
               <source>1.5</source>
               <target>1.5</target>
            </configuration>
         </plugin>
         <plugin>
            <groupId>org.apache.sling</groupId>
            <artifactId>maven-sling-plugin</artifactId>
            <version>2.0.2-incubator</version>
            <executions>
               <execution>
                  <id>install-bundle</id>
                  <goals>
                     <goal>install</goal>
                  </goals>
                  <configuration>
                     <slingUrl>http://localhost:7402/system/console/install</slingUrl>
                     <user>admin</user>
                     <password>admin</password>
                  </configuration>
               </execution>
            </executions>
         </plugin>
         <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-scr-plugin</artifactId>
            <version>1.0.7</version>
            <executions>
               <execution>
                  <id>generate-scr-scrdescriptor</id>
                  <goals>
                     <goal>scr</goal>
                  </goals>
               </execution>
            </executions>
         </plugin>
         <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-bundle-plugin</artifactId>
            <version>1.4.3</version>
            <extensions>true</extensions>
            <configuration>
               <instructions>
                  <Export-Package></Export-Package>
                  <Private-Package>mh.osgitest.client</Private-Package>
                  <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
                  <Bundle-Name>${pom.name}</Bundle-Name>
               </instructions>
            </configuration>
         </plugin>
      </plugins>
   </build>
   <repositories>
      <repository>
         <id>apache.incubating</id>
         <name>Apache Incubating Repository</name>
         <url>http://people.apache.org/repo/m2-incubating-repository</url>
      </repository>
   </repositories>
   <pluginRepositories>
      <pluginRepository>
         <id>apache.incubating.plugins</id>
         <name>Apache Incubating Plugin Repository</name>
         <url>http://people.apache.org/repo/m2-incubating-repository 
         </url>
      </pluginRepository>
   </pluginRepositories>
   <dependencies>
      <dependency>
         <groupId>javax.servlet</groupId>
         <artifactId>servlet-api</artifactId>
         <version>2.4</version>
      </dependency>
      <dependency>
         <groupId>org.apache.felix</groupId>
         <artifactId>org.osgi.core</artifactId>
         <version>1.0.0</version>
      </dependency>
      <dependency>
         <groupId>org.apache.sling</groupId>
         <artifactId>org.apache.sling.api</artifactId>
         <version>2.0.0.incubator-SNAPSHOT</version>
      </dependency>
      <dependency>
         <groupId>mh.studies</groupId>
         <artifactId>mh.studies.sling.osgitest</artifactId>
         <version>0.0.5</version>
      </dependency>
   </dependencies>
</project>

Maven dependencies: oops

Everything looks easy so far, but there's one catch: no public m2 repository can satisfy the dependency on org.apache.sling.api-2.0.0.incubator-SNAPSHOT, so that when you now run mvn package, you will end up with the following:

D:\projekte\workspace-sling\mh.studies.sling.osgitest.client>mvn package
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building A Servlet Client for the OSGi Test Bundle
[INFO]    task-segment: [package]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] snapshot org.apache.sling:org.apache.sling.api:2.0.0.incubator-SNAPSHOT: checking for updates from apache.incubating
Downloading: http://people.apache.org/repo/m2-incubating-repository/org/apache/sling/org.apache.sling.api/2.0.0.incubator-SNAPSHOT/org.apache.sling.api-2.0.0.incubator-SNAPSHOT.pom

Downloading: http://people.apache.org/repo/m2-incubating-repository/org/apache/sling/org.apache.sling.api/2.0.0.incubator-SNAPSHOT/org.apache.sling.api-2.0.0.incubator-SNAPSHOT.jar

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Failed to resolve artifact.

Missing:
----------
1) org.apache.sling:org.apache.sling.api:jar:2.0.0.incubator-SNAPSHOT

  Try downloading the file manually from the project website.

  Then, install it using the command:
      mvn install:install-file -DgroupId=org.apache.sling -DartifactId=org.apache.sling.api -Dversion=2.0.0.incubator-SNAPSHOT -Dpackaging=jar -Dfile=/path/to/file

  Alternatively, if you host your own repository you can deploy the file there:
      mvn deploy:deploy-file -DgroupId=org.apache.sling -DartifactId=org.apache.sling.api -Dversion=2.0.0.incubator-SNAPSHOT -Dpackaging=jar -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]

  Path to dependency:
        1) mh.studies:mh.studies.sling.osgitest.client:bundle:0.0.1
        2) org.apache.sling:org.apache.sling.api:jar:2.0.0.incubator-SNAPSHOT

----------
1 required artifact is missing.

for artifact:
  mh.studies:mh.studies.sling.osgitest.client:bundle:0.0.1

from the specified remote repositories:
  central (http://repo1.maven.org/maven2),
  apache.incubating (http://people.apache.org/repo/m2-incubating-repository)


[INFO] ------------------------------------------------------------------------
[INFO] For more information, run Maven with the -e switch
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3 seconds
[INFO] Finished at: Wed Sep 03 16:56:39 CEST 2008
[INFO] Final Memory: 5M/9M
[INFO] ------------------------------------------------------------------------

Don't let it bring you down -- the problem is easily solved, even if it takes a few steps. Note the lines 21 - 26 above. They already show that there is a solution at hand. Now all we need is the jar file. Don't look on the sling website, it's already on your machine. Go to the place you started CRX Quickstart from, and you'll find it here: ./crx-quickstart/server/runtime/0/_/WEB-INF/resources/bundles/org.apache.sling.api-2.0.0-incubator-SNAPSHOT.jar. Now, you only need to execute the following:

mvn install:install-file -DgroupId=org.apache.sling -DartifactId=org.apache.sling.api -Dversion=2.0.0.incubator-SNAPSHOT -Dpackaging=jar \
  -Dfile=<crx quickstart dir>/crx-quickstart/server/runtime/0/_/WEB-INF/resources/bundles/org.apache.sling.api-2.0.0-incubator-SNAPSHOT.jar

Build, Deploy, Test

All that remains is mvn clean install, and go to http://localhost:7402/system/osgitest/info

HOW-TO use the JSON Query Servlet

2008-09-02T22:24:00.001+02:00

Sling provides a standard JSON Query Servlet in the package org.apache.sling.servlets.get that allows you to perform a search on the contents of the underlying repository.

The source of the servlet is available here:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/get/src/main/java/org/apache/sling/servlets/get/RedirectServlet.java?view=markup

I am here discussing revision 660460. The source of that revision is at the very bottom of this post.

The servlet registers with the selector "query" and the extension "json" in lines 59 and 58.
That means that we can trigger it by accessing any node in the repository and append ".query" to it's name and ".json" as the extension.
The node we call is irrelevant. The servlet will always query the whole repository. The only thing we need is a resource that does exist, or the star resource.
So let's start off with a simple example that will work on any sling installation, whatever has been done to it, and return each and every node as a search result:

http://localhost:8080/content.query.json?queryType=xpath&statement=//*

This reveals the two required parameters for the servlet: queryType and statement.

queryType can be "xpath" or "sql"
statement is the search statement in the language specified through the queryType parameter.

The more intuitive language (at least to me and when dealing with structured content) is xpath, so let's see another example. This one will return all nodes of the primary type "nt:unstructured".
http://localhost:8080/content.query.json?queryType=xpath&statement=//*[@jcr:primaryType='nt:unstructured']

The same result will be returned with the following SQL query:
http://localhost:8080/content.query.json?queryType=sql&statement=select * from nt:base where jcr:primaryType='nt:unstructured'

This will (on my instance) give the following result. As you can see, for each result we get

the name of the node
the path
the score of the result entry
the primaryType

 [
    {
       "name":"org.apache.sling.launchpad.content",
       "jcr:path":"/var/sling/bundle-content/org.apache.sling.launchpad.content",
       "jcr:score":"1000",
       "jcr:primaryType":"nt:unstructured"
    },
    {
       "name":"mh.studies.sling.osgitest",
       "jcr:path":"/var/sling/bundle-content/mh.studies.sling.osgitest",
       "jcr:score":"1000",
       "jcr:primaryType":"nt:unstructured"
    },
    {
       "name":"test",
       "jcr:path":"/content/osgitest/test",
       "jcr:score":"1000",
       "jcr:primaryType":"nt:unstructured"
    }
 ]

But you can also use the full power of the jcr-specific xpath functions, e.g.
http://localhost:8080/content.query.json?queryType=xpath&statement=//*[jcr:contains(.,'sling')]

This searches for all nodes that contain the word "sling".

The offset parameter will skip as many rows in the result as given (lines 110-116).

The rows parameter states the maximum number of rows that will be returned.

The property parameter can be used to extract additional properties from the node.
It can be used multiple times.
http://localhost:8080/content.query.json?statement=//*[@jcr:primaryType='nt:file']&property=jcr:content/jcr:mimeType

will return:

  1: [
  2:    {
  3:       "name":"index.html",
  4:       "jcr:path":"/index.html",
  5:       "jcr:score":"1000",
  6:       "jcr:primaryType":"nt:file",
  7:       "jcr:content/jcr:mimeType":"text/html"
  8:    },
  9:    {
 10:       "name":"sling-logo.png",
 11:       "jcr:path":"/sling-logo.png",
 12:       "jcr:score":"1000",
 13:       "jcr:primaryType":"nt:file",
 14:       "jcr:content/jcr:mimeType":"image/png"
 15:    },
 16:    {
 17:       "name":"assert.js",
 18:       "jcr:path":"/sling-test/sling/assert.js",
 19:       "jcr:score":"1000",
 20:       "jcr:primaryType":"nt:file",
 21:       "jcr:content/jcr:mimeType":"application/x-javascript"
 22:    },
 23:    {
 24:       "name":"sling-test.html",
 25:       "jcr:path":"/sling-test/sling/sling-test.html",
 26:       "jcr:score":"1000",
 27:       "jcr:primaryType":"nt:file",
 28:       "jcr:content/jcr:mimeType":"text/html"
 29:    },
 30:    {
 31:       "name":"sling.css",
 32:       "jcr:path":"/sling.css",
 33:       "jcr:score":"1000",
 34:       "jcr:primaryType":"nt:file",
 35:       "jcr:content/jcr:mimeType":"text/css"
 36:    },
 37:    {
 38:       "name":"GET.esp",
 39:       "jcr:path":"/apps/samples/osgitest/GET.esp",
 40:       "jcr:score":"1000",
 41:       "jcr:primaryType":"nt:file",
 42:       "jcr:content/jcr:mimeType":"text/plain"
 43:    }
 44: ]

The excerptPath parameter specifies the argument to the rep:excerpt() function.
You might want to have a look here: http://wiki.apache.org/jackrabbit/ExcerptProvider

So what is the rep:excerpt() function? The rep:excerpt() function returns an excerpt of the node that was found and highlights search terms. The excerpt is an XML fragment, and is included in the JSON code as a "rep:excerpt" key in the returned array.

Let's have an example:

http://localhost:8080/content.query.json?queryType=xpath&statement=//*[jcr:contains(.,'sling')]/(rep:excerpt(.))

This will return the following JSON that includes

the name
the path
the excerpt
the score

for each entry (note it no longer returns the primaryType).

  1: [
  2:    {
  3:       "name":"",
  4:       "jcr:path":"/",
  5:       "rep:excerpt()":"<div><span><strong>sling<\/strong>:redirect /index.html<\/span><\/div>",
  6:       "jcr:score":"1000"
  7:    },
  8:    {
  9:       "name":"jcr:content",
 10:       "jcr:path":"/index.html/jcr:content",
 11:       "rep:excerpt()":"<div><span> Welcome to the <strong>Sling<\/strong> Launchpad Welcome to the <strong>Sling<\/strong> Launchpad Apache <strong>Sling<\/strong> currently in incubation is a web framework that uses a Java Content<\/span><span>... content bundles can be loaded unloaded and reconfigured at runtime The <strong>Sling<\/strong> Launchpad is a ready to run <strong>Sling<\/strong> configuration providing an embedded JCR content repository and web server<\/span><span>... root URL as the WebDAV server URL Use our mailing lists to contact the <strong>Sling<\/strong> developers team The <strong>Sling<\/strong> OSGi management console is available at system console The Sling client ...<\/span><\/div>",
 12:       "jcr:score":"500"
 13:    },
 14:    {
 15:       "name":"jcr:content",
 16:       "jcr:path":"/sling-test/sling/sling-test.html/jcr:content",
 17:       "rep:excerpt()":"<div><span>... px background color red color white padding em font weight bold Automated <strong>Sling<\/strong> client library tests TODO for now running these tests requires setting<\/span><span>... undefined typeof data dummy function testGetSessionInfo var session <strong>Sling<\/strong> getSessionInfo assertNotNull <strong>Sling<\/strong> getSessionInfo session assertEquals session userID is a string string<\/span><span>... indexOf default function testRemoveContent var deletePath baseTestPath <strong>sling<\/strong> test testhtml nodes delete now var c slingPost deletePath title hello ...<\/span><\/div>",
 18:       "jcr:score":"313"
 19:    }
 20: ]

This is quite unsatisfactory. What we really want is not the jcr:content nodes, right? We want their parent nodes, but still have the excerpt from the content.

So, let's refine in a first step and get the parents as the search result:
http://localhost:8080/content.query.json?queryType=xpath&statement=//*[jcr:contains(jcr:content,'sling')]/(rep:excerpt(.))

This gives us the following. This is OK in terms of nodes returned -- it gives us the nodes of which the content contains "sling".
But now the excerpts are ruined, as the node itself does not contain the word "sling", but the excerpt is drawn from the node.

  1: [
  2:    {
  3:       "name":"index.html",
  4:       "jcr:path":"/index.html",
  5:       "rep:excerpt()":"<excerpt><fragment><\/fragment><\/excerpt>",
  6:       "jcr:score":"1000"
  7:    },
  8:    {
  9:       "name":"sling-test.html",
 10:       "jcr:path":"/sling-test/sling/sling-test.html",
 11:       "rep:excerpt()":"<excerpt><fragment><\/fragment><\/excerpt>",
 12:       "jcr:score":"903"
 13:    }
 14: ]

*STOPPER*
After struggling through JPDA sessions for a whole while, I must confess that I am a bit lost about excerptPath.
Looking at lines 155ff, it would seem that it is impossible for a result row to contain REP_EXCERPT = "rep:excerpt()" and "rep:excerpt(" + exerptPath + ")" at the same time, if exerptPath is anything else but "".

But this may be because I am not too well acquainted with the jcr functions of xpath.
If ever I get a handle on this, I will update this post. Or maybe someone can provide a meaningful example?

My idea was that I can modify above query to the following, so that the parent node of the respective node is returned, and the excerpt of the jcr:content path.
http://localhost:8080/content.query.json?queryType=xpath&statement=//*[jcr:contains(jcr:content,'sling')]/(rep:excerpt(jcr:content))&excerptPath=jcr:content

Source:

  1: /*
  2:  * Licensed to the Apache Software Foundation (ASF) under one
  3:  * or more contributor license agreements.  See the NOTICE file
  4:  * distributed with this work for additional information
  5:  * regarding copyright ownership.  The ASF licenses this file
  6:  * to you under the Apache License, Version 2.0 (the
  7:  * "License"); you may not use this file except in compliance
  8:  * with the License.  You may obtain a copy of the License at
  9:  *
 10:  *   http://www.apache.org/licenses/LICENSE-2.0
 11:  *
 12:  * Unless required by applicable law or agreed to in writing,
 13:  * software distributed under the License is distributed on an
 14:  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 15:  * KIND, either express or implied.  See the License for the
 16:  * specific language governing permissions and limitations
 17:  * under the License.
 18:  */
 19: package org.apache.sling.servlets.get;
 20: 
 21: import java.io.IOException;
 22: import java.io.InputStream;
 23: import java.util.ArrayList;
 24: import java.util.Iterator;
 25: import java.util.List;
 26: import java.util.Map;
 27: 
 28: import javax.jcr.RepositoryException;
 29: import javax.jcr.Value;
 30: import javax.jcr.query.Query;
 31: 
 32: import org.apache.sling.api.SlingException;
 33: import org.apache.sling.api.SlingHttpServletRequest;
 34: import org.apache.sling.api.SlingHttpServletResponse;
 35: import org.apache.sling.api.resource.Resource;
 36: import org.apache.sling.api.resource.ResourceResolver;
 37: import org.apache.sling.api.resource.ResourceUtil;
 38: import org.apache.sling.api.servlets.SlingSafeMethodsServlet;
 39: import org.apache.sling.commons.json.JSONException;
 40: import org.apache.sling.commons.json.io.JSONWriter;
 41: import org.apache.sling.jcr.resource.JcrResourceUtil;
 42: import org.apache.sling.servlets.get.helpers.JsonRendererServlet;
 43: import org.slf4j.Logger;
 44: import org.slf4j.LoggerFactory;
 45: 
 46: /**
 47:  * A SlingSafeMethodsServlet that renders the search results as JSON data
 48:  *
 49:  * @scr.component immediate="true" metatype="no"
 50:  * @scr.service interface="javax.servlet.Servlet"
 51:  * 
 52:  * @scr.property name="service.description" value="Default Query Servlet"
 53:  * @scr.property name="service.vendor" value="The Apache Software Foundation"
 54:  * 
 55:  * Use this as the default query servlet for json get requests for Sling
 56:  * @scr.property name="sling.servlet.resourceTypes"
 57:  *               value="sling/servlet/default"
 58:  * @scr.property name="sling.servlet.extensions" value="json"
 59:  * @scr.property name="sling.servlet.selectors" value="query"
 60:  */
 61: public class JsonQueryServlet extends SlingSafeMethodsServlet {
 62:     private final Logger log = LoggerFactory.getLogger(JsonQueryServlet.class);
 63: 
 64:     /** Search clause */
 65:     public static final String STATEMENT = "statement";
 66: 
 67:     /** Query type */
 68:     public static final String QUERY_TYPE = "queryType";
 69: 
 70:     /** Result set offset */
 71:     public static final String OFFSET = "offset";
 72: 
 73:     /** Number of rows requested */
 74:     public static final String ROWS = "rows";
 75: 
 76:     /** property to append to the result */
 77:     public static final String PROPERTY = "property";
 78: 
 79:     /** exerpt lookup path */
 80:     public static final String EXCERPT_PATH = "excerptPath";
 81: 
 82:     /** rep:exerpt */
 83:     private static final String REP_EXCERPT = "rep:excerpt()";
 84: 
 85:     @Override
 86:     protected void doGet(SlingHttpServletRequest req,
 87:             SlingHttpServletResponse resp) throws IOException {
 88:         dumpResult(req, resp);
 89:     }
 90: 
 91:     /**
 92:      * Dumps the result as JSON object.
 93:      *
 94:      * @param req request
 95:      * @param resp response
 96:      * @throws IOException in case the search will unexpectedly fail
 97:      */
 98:     private void dumpResult(SlingHttpServletRequest req,
 99:             SlingHttpServletResponse resp) throws IOException {
100:         try {
101:             ResourceResolver resolver = req.getResourceResolver();
102: 
103:             String statement = req.getParameter(STATEMENT);
104:             String queryType = (req.getParameter(QUERY_TYPE) != null && req.getParameter(
105:                 QUERY_TYPE).equals(Query.SQL)) ? Query.SQL : Query.XPATH;
106: 
107:             Iterator<Map<String, Object>> result = resolver.queryResources(
108:                 statement, queryType);
109: 
110:             if (req.getParameter(OFFSET) != null) {
111:                 long skip = Long.parseLong(req.getParameter(OFFSET));
112:                 while (skip > 0 && result.hasNext()) {
113:                     result.next();
114:                     skip--;
115:                 }
116:             }
117: 
118:             resp.setContentType(JsonRendererServlet.responseContentType);
119:             resp.setCharacterEncoding("UTF-8");
120: 
121:             final JSONWriter w = new JSONWriter(resp.getWriter());
122:             w.array();
123: 
124:             long count = -1;
125:             if (req.getParameter(ROWS) != null) {
126:                 count = Long.parseLong(req.getParameter(ROWS));
127:             }
128: 
129:             List<String> properties = new ArrayList<String>();
130:             if (req.getParameterValues(PROPERTY) != null) {
131:                 for (String property : req.getParameterValues(PROPERTY)) {
132:                     properties.add(property);
133:                 }
134:             }
135: 
136:             String exerptPath = "";
137:             if (req.getParameter(EXCERPT_PATH) != null) {
138:                 exerptPath = req.getParameter(EXCERPT_PATH);
139:             }
140: 
141:             // iterate through the result set and build the "json result"
142:             while (result.hasNext() && count != 0) {
143:                 Map<String, Object> row = result.next();
144: 
145:                 w.object();
146:                 String path = row.get("jcr:path").toString();
147: 
148:                 w.key("name");
149:                 w.value(ResourceUtil.getName(path));
150: 
151:                 // dump columns
152:                 for (String colName : row.keySet()) {
153:                     w.key(colName);
154:                     String strValue = "";
155:                     if (colName.equals(REP_EXCERPT)) {
156:                         Object ev = row.get("rep:excerpt(" + exerptPath + ")");
157:                         strValue = (ev == null) ? "" : ev.toString();
158:                     } else {
159:                         strValue = formatValue(row.get(colName));
160:                     }
161:                     w.value(strValue);
162:                 }
163: 
164:                 // load properties and add it to the result set
165:                 if (!properties.isEmpty()) {
166:                     Resource nodeRes = resolver.getResource(path);
167:                     dumpProperties(w, nodeRes, properties);
168:                 }
169: 
170:                 w.endObject();
171:                 count--;
172:             }
173:             w.endArray();
174:         } catch (JSONException je) {
175:             throw wrapException(je);
176:         }
177:     }
178: 
179:     private void dumpProperties(JSONWriter w, Resource nodeRes,
180:             List<String> properties) throws JSONException {
181: 
182:         // nothing to do if there is no resource
183:         if (nodeRes == null) {
184:             return;
185:         }
186: 
187: 
188:         ResourceResolver resolver = nodeRes.getResourceResolver();
189:         for (String property : properties) {
190:             Resource prop = resolver.getResource(nodeRes, property);
191:             if (prop != null) {
192:                 String strValue;
193:                 Value value = prop.adaptTo(Value.class);
194:                 if (value != null) {
195:                     strValue = formatValue(value);
196:                 } else {
197:                     strValue = prop.adaptTo(String.class);
198:                     if (strValue == null) {
199:                         strValue = "";
200:                     }
201:                 }
202:                 w.key(property);
203:                 w.value(strValue);
204:             }
205:         }
206: 
207:     }
208: 
209:     private String formatValue(Value value) {
210:         try {
211:             return formatValue(JcrResourceUtil.toJavaObject(value));
212:         } catch (RepositoryException re) {
213:             // might log
214:         }
215:         return "";
216:     }
217: 
218:     private String formatValue(Object value) {
219:         String strValue;
220:         if (value instanceof InputStream) {
221:             // binary value comes as a LazyInputStream
222:             strValue = "[binary]";
223: 
224:             // just to be clean, close the stream
225:             try {
226:                 ((InputStream) value).close();
227:             } catch (IOException ignore) {
228:             }
229:         } else if (value != null) {
230:             strValue = value.toString();
231:         } else {
232:             strValue = "";
233:         }
234: 
235:         return strValue;
236:     }
237: 
238:     /**
239:      * @param e
240:      * @throws org.apache.sling.api.SlingException wrapping the given exception
241:      */
242:     private SlingException wrapException(Exception e) {
243:         log.warn("Error in QueryServlet: " + e.toString(), e);
244:         return new SlingException(e.toString(), e);
245:     }
246: }
247:

Sling OSGi Track pt 5: Bundling initial content

2008-09-02T13:54:00.001+02:00

This is the continuation of

In this part, I will show how to bundle initial content.

I will put the test node and the test script that I used previously into the bundle, so they don't need to be created separately.

Sling provides several different ways to load content provided by an OSGi bundle. These are provided in the org.apache.sling.jcr.contentloader package, and can be used to

create initial content from a filesystem structure contained in a ZIP or JAR file
This content reader will create nt:folder and nt:file resources. It basically does the same as if you created the same items through WebDAV.
It also has the same limitations: you cannot set different Nodetypes, and you cannot edit properties explicitly.
create initial content from an XML definition
This allows you to provide an XML file, in which the content structure is defined. You can define nodetypes and mixins, but you cannot influence any other properties.
As opposed to the ZIP reader, it does not provide a way to include binary data.
create initial content from a JSON definition
This is the most powerful reader, as you can set arbitrary properties (but again, no binary content can be included).

Aims:

Show how to bundle initial sling content into the OSGi bundle

Ingredients:

Files:

Outline:

Project structure
Create initial content structure
Update the pom accordingly
Build and Install
Test

Execution:

Project structure

.
|-- pom.xml
`-- src
    `-- main
        |-- java
        |   `-- mh
        |       `-- osgitest
        |           |-- SampleService.java
        |           `-- SampleServiceImpl.java
        `-- resources
            |-- META-INF
            `-- SLING-INF
                `-- initial-content
                    |-- apps
                    |   `-- samples
                    |       `-- osgitest
                    |           `-- GET.esp
                    `-- content.json

Create initial content structure

We'll be using the JAR content loader to create the structure apps/samples/osgitest and the file GET.esp beneath it.
For that, we create a directory src/main/resources/SLING-INF/initial-content. In that directory, we'll create the directory apps/samples/osgitest.
Into that directory, we place the file GET.esp with the following contents:

  1: <%
  2: var service =
  3:  sling.getService(Packages.mh.osgitest.SampleService);
  4: %><%= service.sayHello() %>

That was easy so far: all we wanted to do was create resources of type nt:folder and nt:file.
(Note that the changes to the pom are needed before sling takes notice, so don't try right now).

For creating the structure in the content tree, it's not that easy. If you peek back at the first part, we need to create a resource of type "nt:unstructured" and assign it a property of "sling:resourceType" with a value of "samples:osgitest", so that the GET.esp script at apps/samples/osgitest is picked up.

Also, I now want to create the script at /content/osgitest/test, instead of /content/test, so this does not clutter up the content tree at root level.

This can only be achieved through the JSON reader, which expects a JSON definition of the nodes to be created. It's actually very intuitive and need little explanation.
In the initial-content/ directory, I place a file named "content.json" with the following content:

  1: {
  2:     "jcr:primaryType" : "nt:unstructured",
  3:     "osgitest" : {
  4:         "jcr:primaryType" : "nt:unstructured",
  5:         "test" : {
  6:             "jcr:primaryType" : "nt:unstructured",
  7:             "sling:resourceType" : "samples:osgitest"
  8:         }
  9:     }
 10: }

This will create the following structure in the content repository

Update the pom accordingly

The contentloader service inspects the Manifest for the "Sling-Initial-Content" header.
To create this header, we add line 13 below to the pom.

The header can contain multiple entries, separated by commas, and can contain directives whether content should be overwritten, whether it should be deleted when the bundle is uninstalled, and what path other then the root node the content should go to. All this is described at http://incubator.apache.org/sling/site/content-loading.html, and in even more detail at
http://svn.apache.org/viewvc/incubator/sling/trunk/jcr/contentloader/src/main/java/org/apache/sling/jcr/contentloader/internal/PathEntry.java?view=markup and
http://svn.apache.org/viewvc/incubator/sling/trunk/jcr/contentloader/src/main/java/org/apache/sling/jcr/contentloader/internal/Loader.java?view=markup.

The "overwrite" part is dangerous: it will first delete the whole path and then add your contents, so in our case above, the folders "content" and "apps" would be empty except for the content we just filled in. Ouch.
This can be avoided by simultaneously restricting the deployment to a path. But note that this does not work in CRX (not the cup edition, at least).

But take care you understand that by default, existing content is NOT overwritten, so if you re-deploy your package and want to see the effect of your changes, you'll need to delete everything that must be replaced before deployment -- it won't be overwritten.

  1: <plugin>
  2: 	<groupId>org.apache.felix</groupId>
  3: 	<artifactId>maven-bundle-plugin</artifactId>
  4: 	<version>1.4.3</version>
  5: 	<extensions>true</extensions>
  6: 	<configuration>
  7: 		<instructions>
  8: 			<Export-Package>mh.osgitest</Export-Package>
  9: 			<Import-Package>org.osgi.framework;version="1.3.0"</Import-Package>
 10: 			<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
 11: 			<Bundle-Name>${pom.name}</Bundle-Name>
 12: 			<Bundle-Vendor>Moritz Havelock</Bundle-Vendor>
 13: 			<Sling-Initial-Content>SLING-INF/initial-content</Sling-Initial-Content>
 14: 		</instructions>
 15: 	</configuration>
 16: </plugin>

Build and Install

Before we build and install, remove the old test artifacts from the repository (the apps/samples/osgitest folder and the /content/test script).

Then, as before, just do "mvn clean install".

Test

We've moved the test script a bit, so now go to http://localhost:7402/osgitest/test to see our service say "hello".

Properly done

Above I mentioned that a combination of path specifications, overwrite and uninstall values is possible to enable the behaviour that is probably what someone would intuitively expect as the default behaviour.
So, I want to

deploy content from the package
if resources are already existing where I want to deploy a resource, overwrite it
leave other resources alone

For that, I need to attach content-definitions to specific paths. For that, I need to re-structure my initial-content directory a bit:

src/main/resources/SLING-INF/
`-- initial-content
    |-- apps
    |   `-- samples
    |       `-- osgitest
    |           `-- GET.esp
    `-- content
        `-- osgitest
            `-- test.json

Then, I change my Sling-Initial-Content tag in the pom to look like this:

  1: <Sling-Initial-Content>						
  2:   SLING-INF/initial-content/content/osgitest;path:=/content/osgitest;overwrite:=true;uninstall:=false,
  3:   SLING-INF/initial-content/apps/samples/osgitest;path:=/apps/samples/osgitest;overwrite:=true;uninstall:=true
  4: </Sling-Initial-Content>

And the file test.json looks like this:

  1: {
  2:     "jcr:primaryType" : "nt:unstructured",
  3:     "sling:resourceType" : "samples:osgitest"
  4: }

What does all that do?

In the first line in the Sling-Initial-Content tag in the pom, I state that I want to have content created at /content/osgitest. This restricts the whole operation to that path and makes sure that no other resources are touched (i.e. deleted in the overwrite). But that also means that my content definition in the JSON file must no longer contain the parent nodes of the "test" node. That is why the file now has a new name and contains only the properties of the single node it defines.
By saying that uninstall is false, I make sure that when the package is uninstalled, the content still remains. You might want this for your package or no.
Do note that even in this scenario, the whole subtree of /content/osgitest will be deleted before the content is re-deployed. It's just everything outside of that path that is unaffected.
The second line does basically the same, but points deeper into the path through the path directive. Contents will be uninstalled when the bundle is uninstalled.
I could have omitted the uninstall directive here, as it defaults to the value of the overwrite directive.

Sling OSGi Track pt 4: installing to Sling using Maven

2008-08-29T15:17:00.001+02:00

This is the continuation of

In this part, I will show how to install a maven-built bundle to sling directly from maven

Aims:

Show how to install a maven-built bundle to sling

Ingredients:

Files:

Outline:

Add the sling plugin to the pom
Add the ASF incubating repository
Build and Install
Test

Execution:

Add the sling plugin to the pom

Add the following snippet to the build plugins.

(8-10) bind the execution of the plugin's install-bundle goal to install phase goal
(11-15) configure the sling URL to use, the username and the password.

  1: <plugin>
  2: 	<groupId>org.apache.sling</groupId>
  3: 	<artifactId>maven-sling-plugin</artifactId>
  4: 	<version>2.0.2-incubator</version>
  5: 	<executions>
  6: 		<execution>
  7: 			<id>install-bundle</id>
  8: 			<goals>
  9: 				<goal>install</goal>
 10: 			</goals>
 11: 			<configuration>
 12: 				<slingUrl>http://localhost:7402/system/console/install</slingUrl>
 13: 				<user>admin</user>
 14: 				<password>admin</password>
 15: 			</configuration>
 16: 		</execution>
 17: 	</executions>
 18: </plugin>

Add the ASF incubating repository

The sling plugin (to date) lives in the Apache Software Foundation's incubating repository (as sling is still in the incubator).
So for maven to be able to resolve the plugin, we must add the repository to the pom.
While we're at it, we will also add it both as a plugin and as a regular artifact repository, as we'll be using other parts of sling later on.

Add the following right before the <dependencies> section:

  1: <repositories>
  2: 	<repository>
  3: 		<id>apache.incubating</id>
  4: 		<name>Apache Incubating Repository</name>
  5: 		<url>http://people.apache.org/repo/m2-incubating-repository</url>
  6: 	</repository>
  7: </repositories>
  8: <pluginRepositories>
  9: 	<pluginRepository>
 10: 		<id>apache.incubating.plugins</id>
 11: 		<name>Apache Incubating Plugin Repository</name>
 12: 		<url>http://people.apache.org/repo/m2-incubating-repository
 13: 		</url>
 14: 	</pluginRepository>
 15: </pluginRepositories>

Build and Install

Now, execute maven so:

mvn clean install

To verify that the new package is deployed, go to the sling console at http://localhost:7402/system/console/list and click on the "OSGI Test Bundle" to see the details
(this only works in Firefox, not on IE, about others I do not know).

I bumped the version by 0.0.1 for each part of this series, so we're now at 0.0.4.
The version is taken from the pom's <version> element.

Test

As usual, go to http://localhost:7402/test to see the service say "hello"

Sling OSGi Track pt 3: replacing the Activator with DS

2008-08-29T12:25:00.003+02:00

This is the continuation of

In this part, I will show how to declare the SampleService instead of registering it explicitly by an activator

Aims:

Show how to declare a service component

Ingredients:

Files:

Outline:

Add the scr plugin to the pom
Remove the activator
Add scr tags
Build, Install, Test

Execution:

Add the scr plugin to the pom

Add the following snippet to the build plugins:

  1:  <plugin>
  2:      <groupId>org.apache.felix</groupId>
  3:      <artifactId>maven-scr-plugin</artifactId>
  4:      <version>1.0.7</version>
  5:      <executions>
  6:          <execution>
  7:              <id>generate-scr-scrdescriptor</id>
  8:              <goals>
  9:                  <goal>scr</goal>
 10:              </goals>
 11:          </execution>
 12:      </executions>
 13:  </plugin>

Remove the activator

As we no longer will use explicit activation, we remove the Activator from the sources and remove the following line from the pom:

<Bundle-Activator>mh.osgitest.Activator</Bundle-Activator>

Add scr tags

Now, we add the scr tags to the implementing class.

Line (4) declares the class as a component. This will provide a wrapped ManagedService Component in the OSGi container (I'll come to ManageServices later)

Line (5) declares the service we are offering. Actually, the interface attribute is superflous, as by default, all implemented Interfaces are used.

  1: package mh.osgitest;
  2:
  3: /**
  4:  * @scr.component
  5:  * @scr.service interface="SampleService"
  6:  */
  7: public class SampleServiceImpl implements SampleService {
  8:  public String sayHello() {
  9:   return "hello";
 10:  }
 11: }

Build, Install, Test

First, mvn clean package

To install the bundle, go to the system console at http://localhost:7402/system/console/list.

Then, call the URL http://localhost:7402/test .

For the detail of these two steps, have a look at the first post in this series: /2008/08/basic-osgi-service-for-sling.html

Sling OSGi Track pt 2: using Felix' bundle plugin for manifest entries

2008-08-28T21:44:00.001+02:00

This is the continuation of Sling OSGi Track pt 1: hand-rolled service bundle.

In this part, I will remove the manually created MANIFEST.MF, and have it created by the Maven2 felix-bundle-plugin.

Aims:

define OSGi-specific manifest entries in pom.xml and let Maven create the manifest

Ingredients:

Files:

Outline:

enable and configure the plugin in pom.xml
change the packaging style in pom.xml
stop merging our own manifest into the created jar and remove manifest file

Execution:

enable and configure the plugin in pom.xml

The plugin configuration is done in lines 20-35.
(27): Export-Package creates and Export-Package manifest entry with the same content
(28): same for Import-Package
(29): the symbolic name is taken from the pom's articactId
(30): the bundle name is taken from the pom's project name
(32): Bundle-Activator -- the main class

change the packaging style in pom.xml

We need to change the packaging style to "bundle" (defaults to "jar") for the plugin to do its work.
This is done in line 8.

  1: <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  2: 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  3: 	<modelVersion>4.0.0</modelVersion>
  4: 	<groupId>mh.studies</groupId>
  5: 	<artifactId>mh.studies.sling.osgitest</artifactId>
  6: 	<name>OSGI Test Bundle</name>
  7: 	<version>0.0.2</version>
  8: 	<packaging>bundle</packaging>
  9: 	<description />
 10: 	<build>
 11: 		<plugins>
 12: 			<plugin>
 13: 				<groupId>org.apache.maven.plugins</groupId>
 14: 				<artifactId>maven-compiler-plugin</artifactId>
 15: 				<configuration>
 16: 					<source>1.5</source>
 17: 					<target>1.5</target>
 18: 				</configuration>
 19: 			</plugin>
 20: 			<plugin>
 21: 				<groupId>org.apache.felix</groupId>
 22: 				<artifactId>maven-bundle-plugin</artifactId>
 23: 				<version>1.4.3</version>
 24: 				<extensions>true</extensions>
 25: 				<configuration>
 26: 					<instructions>
 27: 						<Export-Package>mh.osgitest</Export-Package>
 28: 						<Import-Package>org.osgi.framework;version="1.3.0"</Import-Package>
 29: 						<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
 30: 						<Bundle-Name>${pom.name}</Bundle-Name>
 31: 						<Bundle-Vendor>Moritz Havelock</Bundle-Vendor>
 32: 						<Bundle-Activator>mh.osgitest.Activator</Bundle-Activator>
 33: 						<Built-By>Moritz Havelock</Built-By>
 34: 					</instructions>
 35: 				</configuration>
 36: 			</plugin>
 37: 		</plugins>
 38: 	</build>
 39: 	<dependencies>
 40: 		<dependency>
 41: 			<groupId>org.apache.felix</groupId>
 42: 			<artifactId>org.osgi.core</artifactId>
 43: 			<version>1.0.1</version>
 44: 		</dependency>
 45: 	</dependencies>
 46: </project>

stop merging our own manifest into the created jar and remove manifest file

We can now remove the file src/main/resources/META-INF/MANIFEST.MF, as this will be auto-generated.
Also, we can remove the following section from the pom.

			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-jar-plugin</artifactId>
				<version>2.2</version>
				<configuration>
					<archive>
						<manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
					</archive>
				</configuration>
			</plugin>

Build

Do an "mvn clean package".

Now, open the created jar file ( target/mh.studies.sling.osgitest-0.0.2.jar ), and have a look at the created META-INF/MANIFEST.MF:
as you can see, all the lines we previously created manually are there, looking much the same.
There are slight differences in (7) -- the used packages are declared, and (3), (2), (11) and (15) are new.

  1: Manifest-Version: 1.0
  2: Built-By: Moritz Havelock
  3: Created-By: Apache Maven Bundle Plugin
  4: Bundle-Activator: mh.osgitest.Activator
  5: Import-Package: org.osgi.framework;version="1.3.0"
  6: Bnd-LastModified: 1219937878156
  7: Export-Package: mh.osgitest;uses:="org.osgi.framework"
  8: Bundle-Version: 0.0.2
  9: Bundle-Name: OSGI Test Bundle
 10: Bundle-ClassPath: .
 11: Build-Jdk: 1.5.0_16
 12: Bundle-ManifestVersion: 2
 13: Bundle-Vendor: Moritz Havelock
 14: Bundle-SymbolicName: mh.studies.sling.osgitest
 15: Tool: Bnd-0.0.255

Install / Test Client

To install the bundle, go to the system console at http://localhost:7402/system/console/list.

Then, call the URL http://localhost:7402/test .

For the detail of these two steps, have a look at the previous post: /2008/08/basic-osgi-service-for-sling.html

Sling OSGi Track pt 1: hand-rolled service bundle

2008-08-28T11:49:00.001+02:00

Technorati Tags: sling,osgi,crx

This is the first in a series that tries to show how to create OSGi bundles for sling.

I'll create a very simple service that answers with "hello" when asked to say hello.
This is little functionality, but demonstrates how to get the tools ready for creating CRX bundles.

Aims:

create a service that returns the String "hello" when called with sayHello()
use maven for building

Ingredients:

CRX-quickstart

Files:

https://mhavelock-blog.s3.amazonaws.com/mh.studies.sling.osgitest-0-0-1-src.zip (sources used)
https://mhavelock-blog.s3.amazonaws.com/mh.studies.sling.osgitest-0.0.1.jar (completed OSGi bundle)

Outline:

Project structure
Define the service interface
Create an implementation of that interface
Create an Activator that registers the service
Create the Manifest
Create the Maven pom
Build
Install
Create a test client

Execution:

Project structure

.
|-- pom.xml
`-- src
    `-- main
        |-- java
        |   `-- mh
        |       `-- osgitest
        |           |-- Activator.java
        |           |-- SampleService.java
        |           `-- SampleServiceImpl.java
        `-- resources
            `-- META-INF
                `-- MANIFEST.MF

Define the service interface

The service interface is straightforward: it contains a single public method.

  1: package mh.osgitest;
  2: 
  3: public interface SampleService {
  4: 	public String sayHello();
  5: }

Create an implementation of that interface

This is just as easy and pojo:

  1: package mh.osgitest;
  2: 
  3: public class SampleServiceImpl implements SampleService {
  4: 	public String sayHello() {
  5: 		return "hello";
  6: 	}
  7: }
  8:

Create an activator that registers the service

Every OSGi bundle must have an activator that implements the BundleActivator interface.
(simplification. declarative services do not need an activator).

The BundleActivator gives us start and stop methods that will be called when the bundles is started / stopped by the container.
In the start method, the service instance is created (11), and then registered. The registerService method of the BundleContext receives the class name under which the service is registered and by which it can be located (14), the service instance (15) and an empty configuration table.

  1: package mh.osgitest;
  2: 
  3: import java.util.Hashtable;
  4: import org.osgi.framework.BundleActivator;
  5: import org.osgi.framework.BundleContext;
  6: 
  7: public class Activator implements BundleActivator {
  8: 
  9: 	public void start(BundleContext context) throws Exception {
 10: 
 11: 		SampleService sample = new SampleServiceImpl();
 12: 
 13: 		context.registerService(
 14: 				SampleService.class.getName(), 
 15: 				sample,
 16: 				new Hashtable<Object, Object>());
 17: 
 18: 		System.err.println("SampleService Started");
 19: 	}
 20: 
 21: 	public void stop(BundleContext context) throws Exception {
 22: 		System.err.println("SampleService Stopped");
 23: 	}
 24: }

Create the Manifest

The manifest file needs some OSGi specific entries:

  1: Manifest-Version: 1.0
  2: Bundle-ManifestVersion: 2
  3: Bundle-Name: Simple OSGITest
  4: Bundle-SymbolicName: mh.osgitest
  5: Bundle-Version: 1.0.0
  6: Bundle-Activator: mh.osgitest.Activator
  7: Bundle-Vendor: Moritz Havelock
  8: Import-Package: org.osgi.framework;version="1.3.0"
  9: Export-Package: mh.osgitest;version=0.0.1
 10: Bundle-ClassPath: .

(3) Name of the Bundle. Choose freely
(4) The symbolic name by which the bundle is referred to.
(6) the activator is the name of the class that implements BundleActivator
(8) Import-Package declares the packages that this bundle expects to be provided by other packages.
(9) Export-Package declares the package that is exposed and available to other bundles.

Create the Maven pom

The only things needed (except for dependencies) are

configuring our own manifest file to be blended in when bundling the jar file and
setting source style to Java 5

  1: <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  2: 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  3: 	<modelVersion>4.0.0</modelVersion>
  4: 	<groupId>mh.studies</groupId>
  5: 	<artifactId>mh.studies.sling.osgitest</artifactId>
  6: 	<name>OSGI Test Bundle</name>
  7: 	<version>0.0.1</version>
  8: 	<description />
  9: 	<build>
 10: 		<plugins>
 11: 			<plugin>
 12: 				<groupId>org.apache.maven.plugins</groupId>
 13: 				<artifactId>maven-jar-plugin</artifactId>
 14: 				<version>2.2</version>
 15: 				<configuration>
 16: 					<archive>
 17: 						<manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
 18: 					</archive>
 19: 				</configuration>
 20: 			</plugin>
 21: 			<plugin>
 22: 				<groupId>org.apache.maven.plugins</groupId>
 23: 				<artifactId>maven-compiler-plugin</artifactId>
 24: 				<configuration>
 25: 					<source>1.5</source>
 26: 					<target>1.5</target>
 27: 				</configuration>
 28: 			</plugin>
 29: 		</plugins>
 30: 	</build>
 31: 	<dependencies>
 32: 		<dependency>
 33: 			<groupId>org.apache.felix</groupId>
 34: 			<artifactId>org.osgi.core</artifactId>
 35: 			<version>1.0.1</version>
 36: 		</dependency>
 37: 	</dependencies>
 38: </project>

Build

mvn clean package

Install

To install the bundle, go to the system console at http://localhost:7402/system/console/list.
(note that the system console does not fully work in Internet Explorer)

Hit the "Browse" button and select the jar file from the target/ directory created by maven.

Check the "Start" box, level the level at 20 and hit "Install or Update".

Then, hit "Refresh Package". You will then see an entry "Simple OSGITest" in the list of bundles. Click it to see an expanded view.
You will see the Bundle properties, plus the registered service of type mh.osgitest.SampleService.

Create a test client

In the CRX browser, create a node /content/test of type nt:unstructured, and give it a property "sling:resourceType" with a value of "samples:osgitest".
Create the structure /apps/samples/osgitest, and there create the file GET.esp with the following contents.

In line 3, the service is obtained from the sling helper object.

  1: <%
  2: var service =
  3:   sling.getService(Packages.mh.osgitest.SampleService);
  4:   
  5: %><%= service.sayHello() %>

Now, you can use a browser or curl to call that URL with an impressing result ;-)

D:\projekte\workspace-sling\mh.studies.sling.osgitest>curl http://localhost:7402/test
hello

in the sling

Inside Sling: How Sling boots

Class overview

Sequence overview

Details

the main method

Sling configuration

The remainder of the Sling constructor

Code

org.apache.sling.launcher.app.Sling, Revision 657002

org.apache.sling.launcher.app.BootstrapInstaller, Revision 688973

org.apache.sling.launcher.app.main.Main, Revision 667440

Sling OSGi Track pt 7: configuring services at runtime

Aims:

Ingredients:

Files:

Outline:

Execution

Project Structure

Changes to the implementation

The pom

The results

Testing

Sling OSGI Track pt 6: Sling Servlets I

Aims:

Ingredients:

Files:

Outline:

Execution:

Project structure

The servlet implementation

The pom: nothing special

Maven dependencies: oops

Build, Deploy, Test

HOW-TO use the JSON Query Servlet

Sling OSGi Track pt 5: Bundling initial content

Aims:

Ingredients:

Files:

Outline:

Execution:

Project structure

Create initial content structure

Update the pom accordingly

Build and Install

Test

Sling OSGi Track pt 4: installing to Sling using Maven

Aims:

Ingredients:

Files:

Outline:

Execution:

Add the sling plugin to the pom

Add the ASF incubating repository

Test

Sling OSGi Track pt 3: replacing the Activator with DS

Aims:

Ingredients:

Files:

Outline:

Execution:

Add the scr plugin to the pom

Remove the activator

Add scr tags

Build, Install, Test

Sling OSGi Track pt 2: using Felix' bundle plugin for manifest entries

Aims:

Ingredients:

Files:

Outline:

Execution:

enable and configure the plugin in pom.xml

change the packaging style in pom.xml

Build

Install / Test Client

Sling OSGi Track pt 1: hand-rolled service bundle

Aims:

Ingredients:

Files:

Outline:

`org.apache.sling.launcher.app.Sling`, Revision 657002

`org.apache.sling.launcher.app.BootstrapInstaller`, Revision 688973

`org.apache.sling.launcher.app.main.Main`, Revision 667440