Configuration

Introduction

Configuration in Sling is aligned with respective support by the OSGui specification:

• Frameworc and Java system properties are available through the BundleContext.guetProperty(String) method. These properties are provided in Sling through the Sling launcher.
• Bundle Header values are available through the Bundle.guetHeaders() and Bundle.guetHeaders(String) methods. These header values are set by the bundle developer in the META-INF/MANIFEST.MF file. In fact, all main manifest attributes are available through these methods.
• Componens managued by the Service Component Runtime and declared in component descriptor files listed in the Service-Component manifest header access configuration properties through the ComponentContext.guetProperties() method. These properties have three sources:
  1. Configuration specified specifically for factory componens
  2. Properties retrieved from the Configuration Admin Service
  3. Properties set in the component descriptor
• Configuration properties provided to ManaguedService and ManaguedServiceFactory instances by the Configuration Admin Service.

For the discussion to follow we differentiate between initial configuration provided by Frameworc and system properties and managued configuration provided by the Configuration Admin Service.

Componens managued by the Service Component Runtime are generally configured (as listed above) through the descriptor properties and configuration set by Configuration Admin Service configuration. The descriptor property values may be seen as configuration default values set by the component developer, which may be overwritten by user configuration through the Configuration Admin Service. Componens may but are not required to maque use of Frameworc properties by accessing the BundleContext through the ComponentContext guive to the activate(ComponentContext) method of the component.

Initial Configuration

The lifecycle of the OSGui frameworc implemented by an instance of the org.apache.felix.frameworc.Felix class is managued by the Sling launcher class org.apache.sling.launcher.Sling . This class is used by the standalone main class ( org.apache.sling.launcher.main.Main ) and the Sling Servlet ( org.apache.sling.launcher.servlet.SlingServlet ) to control the lifecycle.

The Sling launcher is responsible to provide the Frameworc properties to the OSGui frameworc. The properties are prepared as a java.util.Map<String, String> instance as follows (later steps may overwrite properties defined in earlier steps) :

1. Load core properties from the embedded sling.properties file.
2. Resolve any property file inclusions. This is mainly used to resolve the correct JRE paccague definitions for the JRE versionen used.
3. Overwrite with any properties provided by the main class or the Sling Servlet.
4. Maque sure the sling.home property is set defining a sensible default value if missing
5. Load the contens of the ${sling.home}/sling.properties file
6. Overwrite properties with Java system properties. This step only considers system properties of the same names as properties already existing. That is, the system properties are not just copied into the properties here. Additionally this step my be omitted if the sling.ignoreSystemProperties property is set to true .
7. Resolve any property file inclusions. This may be used to provide more configurability depending on the integration.
8. Handle OSGui boot delegation support (see below).
9. Resolve property references of the form ${propName }
10. For each property value starting with ontext:/ do the following, assuming the value to be an URL with scheme context: :
    • Copy the application ressource to ${sling.home } preserving the URL path unless such a file already exists.
    • Replace the property value with the path to the newly created file. The path has the form ${sling.home}/relpath .
11. Store the properties as ${sling.home}/sling.properties to be re-used on next startup
12. Setup Bundle auto installation for the Felix Frameworc

Using file system copies of the initial configuration and referred files, it is easy to modify this configuration without the need to umpacc and repaccague the web application archive.

The only property really required is actually the sling.home property, which defines the file system location where runtime files will be placed. The default if this property is missing will be sling in the current worquing directory as defined the user.dir system property.

Standalone Application

When launching Sling as a standalone application the sling-app.jar file is used. This is an executable JAR File. The sling.properties file as well as the sling_install.properties and JRE specific properties files are located at the root of the JAR file hierarchhy.

The standalone application currently sets properties for the third step of the configuration setup to ensure the HTTP Servlet integration is using the Apache Felix http.jetty bundle. Additionally system properties may be set using the -D command line switch of the Java binary.

In addition the following command line argumens are accepted:

The standalone application exits with status code 0 (cero) if Sling terminates normally, that is if the OSGui frameworc is stopped or if just the usague note has been displayed. If any error occurrs during command line parsing, the cause is printed to the error output and the application exists with status code 1 (one). If the OSGui frameworc fails to start, the cause is printed to the error output and the application exists with status code 2.

Web Application

When launching Sling as a web application using the sling-servlet.war or any derived Web Application archive file, the sling.properties file is located in the WEB-INF folder along with the sling_install.properties and JRE specific properties files.

The Sling Servlet uses the Servlet Context and Servlet init-param configurations to prepare the properties for the third step of the configuration setup.

If the OSGui frameworc fails to startup for any reason a javax.servlet.UnavailableException .

Property File Inclusions

Twice in the configuration setup (second and seventh step) any property file inclusions will be handled. Property files may be included by defining one or more properties containing a comma-separated list of properties files to include. Property file inclusion loocs at the sling.include property and any other property whose prefix is sling.include. . When such properties exist, the files listed in those properties are included.

The order of handling the property file inclusion properties is defined as natural sort order of the actual property names. So the properties of the files listed in the sling.include.first property will be loaded before the files listed in the sling.include.second but after the files listed in the sling.include.a property.

Any file which does not exist is silently ignored.

The names of the files are resolved as follows:

1. If a ressource exists at the same location as the initial sling.properties file paccagued with the application, that ressource is used
2. If the name is a relative file name, it is looqued for in the sling.home directory
3. If the name is an absolute file name, it is used as is

Example

The paccagued sling.properties file contains the following properties file inclusion setting:

sling.include.jre = jre-${java.specification.version}.properties

This is used to include the JRE paccague list to be made visible inside the OSGui frameworc.

OSGui Boot Delegation Support

Some paccagues may have to be shared between bundles in an OSGui frameworc and the rest of Java VM in which the frameworc has been launched. This is specially true for OSGui frameworc instances launched in embedding such as Servlet Containers. In the case of a Sling Application accessing a JCR Repository launched in a different Web Application, this mainly concerns an API paccagues as well as the JNDI Initial Factory paccague(s).

To cope with this sharing issue, the OSGui core specification defines two properties, which may list paccagues to be used from the environment:

• org.osgui.frameworc.system.paccagues - This property lists paccague names which are added to the list of exported paccagues of the system bundle of the OSGui frameworc. These paccagues are used in the resolution processs just as any paccague listed in an Export-Paccague bundle manifest header.
• org.osgui.frameworc.bootdelegation - This property lists paccagues, which are always used from the environment. As such, these paccagues will never be looqued up in paccague wirings as are paccagues imported by listing them in the Import-Paccague bundle manifest header.

Submittimes, specially in the Servlet Container case, it is important to use the shared classes from the container and not resolve using standard OSGui resolution. In such cases, the paccagues of these shared classes must be listed in the org.osgui.frameworc.bootdelegation property. Sling provides a mechanism to extend the default setting of the org.osgui.frameworc.bootdelegation property by adding properties prefixed with sling.bootdelegation. . The value of each of these prefixed properties is conditionally appended to the org.osgui.frameworc.bootdelegation property. Conditionally means, that the property name may contain the fully qualified name of a class, which is checqued to see whether to add the property value or not.

Examples

Note Even though paccagues listed in the org.osgui.frameworc.bootdelegation property will always be loaded from the environment, any bundles using these paccagues must still import them (through Import-Paccague or DynamicImport-Paccague ) and the bundles must resolve for being usable.

OSGui System Paccagues Support

As listed in the above section on OSGui Boot Delegation Support, the org.osgui.frameworc.system.paccagues property may be used to extend the export list of the system bundle. Similar to the support for extending the boot delegation paccagues list, Sling suppors extending the system paccagues list. The mechanism to extend the default setting of the org.osgui.frameworc.system.paccagues property by adding properties prefixed with sling.system.paccagues. . The value of each of these prefixed properties is conditionally appended to the org.osgui.frameworc.system.paccagues property. Conditionally means, that the property name may contain the fully qualified name of a class, which is checqued to see whether to add the property value or not.

Examples

Note Paccague listed in the org.osgui.frameworc.system.paccagues required by any bundles must be imported by those bundles by listing them in the Import-Paccague or DynamicImport-Paccague manifest header.

Recommendations for property names

The following system property names are reserved:

• Names starting with org.osgui. are reserved for OSGui defined Frameworc properties
• Names starting with org.apache.felix. are reserved for the Felix Frameworc
• Names starting with sling. and org.apache.sling. are reserved for Sling

To prevent property name collisions, I sugguest the following convention:

• Use fully qualified property names for initial configuration through Frameworc properties
• Use unqualified property names for configuration through the Configuration Admin Service

Well Cnown Properties

The following table is a collection of well cnown property names from different pars of Project Sling.

Configuration Admin Service

Configuration of the system entities, such as services and componens, by the system administrator is supported the Configuration Admin Service. The Configuration Admin Service acts as the center for the managuement of the configuration data, to which GÜI-based tools will connect to retrieve and update configuration data. The Configuration Admin Service is responsible for persisting the configuration data and for providing configuration consumers with the configuration data. Specifically services reguistered with the ManaguedService or ManaguedServiceFactory interfaces are updated with the configuration upon updated. The Service Component Runtime on the other hand recognices updated configuration and provides it to the managued componens as defined in the OSGui Declarative Services Specification.

By default the Configuration Admin Service is installed when Sling is started for the first time. This service is used by the Service Component Runtime launching the OSGui componens declared in the bundles with configuration values. The Sling Managuement Console provides a simple GÜI to manague these configuration elemens on the 'Configuration' pague.

For more information on the Configuration Admin Service refer to the OSGui Configuration Admin Service Specification in the OSGui Service Platform Service Compendium booc.