You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2012/05/22 10:25:36 UTC
svn commit: r818658 [5/23] - in /websites/staging/sling/trunk/content: ./
tutorials-how-tos/
Modified: websites/staging/sling/trunk/content/configuration.html
==============================================================================
--- websites/staging/sling/trunk/content/configuration.html (original)
+++ websites/staging/sling/trunk/content/configuration.html Tue May 22 08:25:32 2012
@@ -82,331 +82,194 @@
<a href="/">Home</a>
</div>
<h1>Configuration</h1>
- <p><a name="Configuration-ConfigurationSupport"></a></p>
-<h1 id="configuration-support">Configuration Support</h1>
-<p><a name="Configuration-Introduction"></a></p>
+ <h1 id="configuration-support">Configuration Support</h1>
<h2 id="introduction">Introduction</h2>
-<p>Configuration in Sling is aligned with respective support by the OSGi
-specification:</p>
+<p>Configuration in Sling is aligned with respective support by the OSGi specification:</p>
<ul>
-<li>Framework and Java system properties are available through the
-<em>BundleContext.getProperty(String)</em> method. These properties are provided
-in Sling through the Sling launcher.</li>
-<li>Bundle Header values are available through the <em>Bundle.getHeaders()</em>
-and <em>Bundle.getHeaders(String)</em> methods. These header values are set by
-the bundle developer in the <em>META-INF/MANIFEST.MF</em> file. In fact, all
-main manifest attributes are available through these methods.</li>
-<li>Components managed by the Service Component Runtime and declared in
-component descriptor files listed in the <em>Service-Component</em> manifest
-header access configuration properties through the
-<em>ComponentContext.getProperties()</em> method. These properties have three
-sources:
+<li>Framework and Java system properties are available through the <code>BundleContext.getProperty(String)</code> method. These properties are provided in Sling through the Sling launcher.</li>
+<li>Bundle Header values are available through the <code>Bundle.getHeaders()</code> and <code>Bundle.getHeaders(String)</code> methods. These header values are set by the bundle developer in the <code>META-INF/MANIFEST.MF</code> file. In fact, all main manifest attributes are available through these methods.</li>
+<li>Components managed by the Service Component Runtime and declared in component descriptor files listed in the <code>Service-Component</code> manifest header access configuration properties through the <code>ComponentContext.getProperties()</code> method. These properties have three sources:
<em># Configuration specified specifically for factory components
</em># Properties retrieved from the Configuration Admin Service
*# Properties set in the component descriptor</li>
-<li>Configuration properties provided to <em>ManagedService</em> and
-<em>ManagedServiceFactory</em> instances by the Configuration Admin Service.</li>
+<li>Configuration properties provided to <code>ManagedService</code> and <code>ManagedServiceFactory</code> instances by the Configuration Admin Service.</li>
</ul>
-<p>For the discussion to follow we differentiate between intial configuration
-provided by Framework and system properties and managed configuration
-provided by the Configuration Admin Service.</p>
-<p>Components managed 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. Components may but are not
-required to make use of Framework properties by accessing the
-<em>BundleContext</em> through the <em>ComponentContext</em> given to the
-<em>activate(ComponentContext)</em> method of the component.</p>
-<p><a name="Configuration-InitialConfiguration"></a></p>
+<p>For the discussion to follow we differentiate between intial configuration provided by Framework and system properties and managed configuration provided by the Configuration Admin Service.</p>
+<p>Components managed 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. Components may but are not required to make use of Framework properties by accessing the <code>BundleContext</code> through the <code>ComponentContext</code> given to the <code>activate(ComponentContext)</code> method of the component.</p>
<h2 id="initial-configuration">Initial Configuration</h2>
-<p>The lifecycle of the OSGi framework implemented by an instance of the
-<em>org.apache.felix.framework.Felix</em> class is managed by the Sling launcher
-class <em>org.apache.sling.launcher.Sling</em>. This class is used by the
-standalone main class (<em>org.apache.sling.launcher.main.Main</em>) and the
-Sling Servlet (<em>org.apache.sling.launcher.servlet.SlingServlet</em>) to
-control the lifecycle.</p>
-<p>The Sling launcher is responsible to provide the Framework properties to
-the OSGi framework. The properties are prepared as a
-<em>java.util.Map<String, String></em> instance as follows (later steps may
-overwrite properties defined in earlier steps) :</p>
+<p>The lifecycle of the OSGi framework implemented by an instance of the <code>org.apache.felix.framework.Felix</code> class is managed by the Sling launcher class <code>org.apache.sling.launcher.Sling</code>. This class is used by the standalone main class (<code>org.apache.sling.launcher.main.Main</code>) and the Sling Servlet (<code>org.apache.sling.launcher.servlet.SlingServlet</code>) to control the lifecycle.</p>
+<p>The Sling launcher is responsible to provide the Framework properties to the OSGi framework. The properties are prepared as a <code>java.util.Map<String, String></code> instance as follows (later steps may overwrite properties defined in earlier steps) :</p>
<ol>
-<li>Load core properties from the embedded <em>sling.properties</em> file.</li>
-<li>Resolve any property file inclusions. This is mainly used to resolve
-the correct JRE package definitions for the JRE version used.</li>
-<li>Overwrite with any properties provided by the main class or the Sling
-Servlet.</li>
-<li>Make sure the <em>sling.home</em> property is set defining a sensible
-default value if missing</li>
-<li>Load the contents of the <em>${sling.home}/sling.properties</em> file</li>
-<li>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
-<em>sling.ignoreSystemProperties</em> property is set to <em>true</em>.</li>
-<li>Resolve any property file inclusions. This may be used to provide more
-configurability depending on the integration.</li>
+<li>Load core properties from the embedded <code>sling.properties</code> file.</li>
+<li>Resolve any property file inclusions. This is mainly used to resolve the correct JRE package definitions for the JRE version used.</li>
+<li>Overwrite with any properties provided by the main class or the Sling Servlet.</li>
+<li>Make sure the <code>sling.home</code> property is set defining a sensible default value if missing</li>
+<li>Load the contents of the <code>$\{sling.home}/sling.properties</code> file</li>
+<li>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 <code>sling.ignoreSystemProperties</code> property is set to <code>true</code>.</li>
+<li>Resolve any property file inclusions. This may be used to provide more configurability depending on the integration.</li>
<li>Handle OSGi boot delegation support (see below).</li>
-<li>Resolve property references of the form <em>${propName</em>}</li>
-<li>For each property value starting with <em>ontext:/</em> do the following,
-assuming the value to be an URL with scheme <em>context:</em>:</li>
+<li>Resolve property references of the form <code>$\{propName</code>}</li>
+<li>For each property value starting with <code>ontext:/</code> do the following, assuming the value to be an URL with scheme <code>context:</code>:</li>
<li>
<ul>
-<li>Copy the application resource to <em>${sling.home</em>} preserving the
-URL path unless such a file already exists.</li>
+<li>Copy the application resource to <code>$\{sling.home</code>} preserving the URL path unless such a file already exists.</li>
</ul>
</li>
<li>
<ul>
-<li>Replace the property value with the path to the newly created
-file. The path has the form <em>${sling.home}/relpath</em>.</li>
+<li>Replace the property value with the path to the newly created file. The path has the form <code>$\{sling.home}/relpath</code>.</li>
</ul>
</li>
-<li>Store the properties as <em>${sling.home}/sling.properties</em> to be
-re-used on next startup</li>
+<li>Store the properties as <code>$\{sling.home}/sling.properties</code> to be re-used on next startup</li>
<li>Setup Bundle auto installation for the Felix Framework</li>
</ol>
-<p>Using file system copies of the initial configuration and referred files,
-it is easy to modify this configuration without the need to unpack and
-repackage the web application archive.</p>
-<p>The only property really required is actually the <em>sling.home</em> property,
-which defines the file system location where runtime files will be placed.
-The default if this property is missing will be <em>sling</em> in the current
-working directory as defined the <em>user.dir</em> system property.</p>
-<p><a name="Configuration-StandaloneApplication"></a></p>
+<p>Using file system copies of the initial configuration and referred files, it is easy to modify this configuration without the need to unpack and repackage the web application archive.</p>
+<p>The only property really required is actually the <code>sling.home</code> property, which defines the file system location where runtime files will be placed. The default if this property is missing will be <em>sling</em> in the current working directory as defined the <code>user.dir</code> system property.</p>
<h3 id="standalone-application">Standalone Application</h3>
-<p>When launching Sling as a standalone application the <em>sling-app.jar</em> file
-is used. This is an executable JAR File. The <em>sling.properties</em> file as
-well as the <em>sling_install.properties</em> and JRE specific properties files
-are located at the root of the JAR file hierarchy.</p>
-<p>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 <em>http.jetty</em> bundle. Additionally system properties may be set
-using the <em>-D</em> command line switch of the Java binary.</p>
+<p>When launching Sling as a standalone application the <code>sling-app.jar</code> file is used. This is an executable JAR File. The <code>sling.properties</code> file as well as the <code>sling_install.properties</code> and JRE specific properties files are located at the root of the JAR file hierarchy.</p>
+<p>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 <em>http.jetty</em> bundle. Additionally system properties may be set using the <code>-D</code> command line switch of the Java binary.</p>
<p>In addition the following command line arguments are accepted:</p>
<table>
-<tr><th> Argument </th><th> Sling property </th><th> Description </th></tr>
-<tr><td> *-l loglevel* </td><td> *org.apache.sling.osgi.log.level* </td><td> The initial
-loglevel (0..4, FATAL, ERROR, WARN, INFO, DEBUG) </td></tr>
-<tr><td> *-f logfile* </td><td> *org.apache.sling.osgi.log.file* </td><td> The log file, "-"
-for stdout </td></tr>
-<tr><td> *-c slinghome* </td><td> *sling.home* </td><td> the sling context directory </td></tr>
-<tr><td> *-a address* </td><td> -- </td><td> the interfact to bind to (use 0.0.0.0 for any) (not
-supported yet) </td></tr>
-<tr><td> *-p port* </td><td> *org.osgi.service.http.port* </td><td> the port to listen to
-(default 8080) </td></tr>
-<tr><td> *-h* </td><td> -- </td><td> Prints a simple usage message and exits. </td></tr>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Sling property</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>-l loglevel</code></td>
+<td><code>org.apache.sling.osgi.log.level</code></td>
+<td>The initial loglevel (0..4, FATAL, ERROR, WARN, INFO, DEBUG)</td>
+</tr>
+<tr>
+<td><code>-f logfile</code></td>
+<td><code>org.apache.sling.osgi.log.file</code></td>
+<td>The log file, "-" for stdout</td>
+</tr>
+<tr>
+<td><code>-c slinghome</code></td>
+<td><code>sling.home</code></td>
+<td>the sling context directory</td>
+</tr>
+<tr>
+<td><code>-a address</code></td>
+<td>--</td>
+<td>the interfact to bind to (use 0.0.0.0 for any) (not supported yet)</td>
+</tr>
+<tr>
+<td><code>-p port</code></td>
+<td><code>org.osgi.service.http.port</code></td>
+<td>the port to listen to (default 8080)</td>
+</tr>
+<tr>
+<td><code>-h</code></td>
+<td>--</td>
+<td>Prints a simple usage message and exits.</td>
+</tr>
+</tbody>
</table>
-
-<p>The standalone application exits with status code 0 (zero) if Sling
-terminates normally, that is if the OSGi framework is stopped or if just
-the usage 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 OSGi framework fails to start, the
-cause is printed to the error output and the application exists with status
-code 2.</p>
-<p><a name="Configuration-WebApplication"></a></p>
+<p>The standalone application exits with status code 0 (zero) if Sling terminates normally, that is if the OSGi framework is stopped or if just the usage 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 OSGi framework fails to start, the cause is printed to the error output and the application exists with status code 2.</p>
<h3 id="web-application">Web Application</h3>
-<p>When launching Sling as a web application using the <em>sling-servlet.war</em>
-or any derived Web Application archive file, the <em>sling.properties</em> file
-is located in the <em>WEB-INF</em> folder along with the
-<em>sling_install.properties</em> and JRE specific properties files.</p>
-<p>The Sling Servlet uses the Servlet Context and Servlet <em>init-param</em>
-configurations to prepare the properties for the third step of the
-configuration setup.</p>
-<p>If the OSGi framework fails to startup for any reason a
-<em>javax.servlet.UnavailableException</em>.</p>
-<p><a name="Configuration-PropertyFileInclusions"></a></p>
+<p>When launching Sling as a web application using the <code>sling-servlet.war</code> or any derived Web Application archive file, the <code>sling.properties</code> file is located in the <code>WEB-INF</code> folder along with the <code>sling_install.properties</code> and JRE specific properties files.</p>
+<p>The Sling Servlet uses the Servlet Context and Servlet <code>init-param</code> configurations to prepare the properties for the third step of the configuration setup.</p>
+<p>If the OSGi framework fails to startup for any reason a <code>javax.servlet.UnavailableException</code>.</p>
<h3 id="property-file-inclusions">Property File Inclusions</h3>
-<p>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 looks at the <em>sling.include</em>
-property and any other property whose prefix is <em>sling.include.</em>. When
-such properties exist, the files listed in those properties are included.</p>
-<p>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 <em>sling.include.first</em> property will be loaded before
-the files listed in the <em>sling.include.second</em> but after the files listed
-in the <em>sling.include.a</em> property.</p>
+<p>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 looks at the <code>sling.include</code> property and any other property whose prefix is <code>sling.include.</code>. When such properties exist, the files listed in those properties are included.</p>
+<p>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 <code>sling.include.first</code> property will be loaded before the files listed in the <code>sling.include.second</code> but after the files listed in the <code>sling.include.a</code> property.</p>
<p>Any file which does not exist is silently ignored.</p>
<p>The names of the files are resolved as follows:</p>
<ol>
-<li>If a resource exists at the same location as the initial
-<em>sling.properties</em> file packaged with the application, that resource is
-used</li>
-<li>If the name is a relative file name, it is looked for in the
-<em>sling.home</em> directory</li>
+<li>If a resource exists at the same location as the initial <code>sling.properties</code> file packaged with the application, that resource is used</li>
+<li>If the name is a relative file name, it is looked for in the <code>sling.home</code> directory</li>
<li>If the name is an absolute file name, it is used as is</li>
</ol>
<p><em>Example</em></p>
-<p>The packaged <em>sling.properties</em> file contains the following properties
-file inclusion setting:</p>
+<p>The packaged <code>sling.properties</code> file contains the following properties file inclusion setting:</p>
<div class="codehilite"><pre>sling.include.jre = jre-<span class="cp">${</span><span class="n">java</span><span class="o">.</span><span class="n">specification</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span>.properties
</pre></div>
-<p>This is used to include the JRE package list to be made visible inside the
-OSGi framework.</p>
-<p><a name="Configuration-OSGiBootDelegationSupport"></a></p>
+<p>This is used to include the JRE package list to be made visible inside the OSGi framework.</p>
<h3 id="osgi-boot-delegation-support">OSGi Boot Delegation Support</h3>
-<p>Some packages may have to be shared between bundles in an OSGi framework
-and the rest of Java VM in which the framework has been launched. This is
-especially true for OSGi framework 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 packages as well as the JNDI Initial Factory package(s).</p>
-<p>To cope with this sharing issue, the OSGi core specification defines two
-properties, which may list packages to be used from the environment:</p>
+<p>Some packages may have to be shared between bundles in an OSGi framework and the rest of Java VM in which the framework has been launched. This is especially true for OSGi framework 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 packages as well as the JNDI Initial Factory package(s).</p>
+<p>To cope with this sharing issue, the OSGi core specification defines two properties, which may list packages to be used from the environment:</p>
<ul>
-<li><strong>org.osgi.framework.system.packages</strong> - This property lists package
-names which are added to the list of exported packages of the system bundle
-of the OSGi framework. These packages are used in the resolution process
-just as any package listed in an <em>Export-Package</em> bundle manifest header.</li>
-<li><strong>org.osgi.framework.bootdelegation</strong> - This property lists packages,
-which are always used from the environment. As such, these packages will
-never be looked up in package wirings as are packages imported by listing
-them in the <em>Import-Package</em> bundle manifest header.</li>
+<li><em><code>org.osgi.framework.system.packages</code></em> - This property lists package names which are added to the list of exported packages of the system bundle of the OSGi framework. These packages are used in the resolution process just as any package listed in an <code>Export-Package</code> bundle manifest header.</li>
+<li><em><code>org.osgi.framework.bootdelegation</code></em> - This property lists packages, which are always used from the environment. As such, these packages will never be looked up in package wirings as are packages imported by listing them in the <code>Import-Package</code> bundle manifest header.</li>
</ul>
-<p>Sometimes, especially in the Servlet Container case, it is important to use
-the shared classes from the container and not resolve using standard OSGi
-resolution. In such cases, the packages of these shared classes must be
-listed in the <em>org.osgi.framework.bootdelegation</em> property. Sling
-provides a mechanism to extend the default setting of the
-<em>org.osgi.framework.bootdelegation</em> property by adding properties
-prefixed with <em>sling.bootdelegation.</em>. The value of each of these
-prefixed properties is conditionally appended to the
-<em>org.osgi.framework.bootdelegation</em> property. <em>Conditionally</em> means, that
-the property name may contain the fully qualified name of a class, which is
-checked to see whether to add the property value or not.</p>
+<p>Sometimes, especially in the Servlet Container case, it is important to use the shared classes from the container and not resolve using standard OSGi resolution. In such cases, the packages of these shared classes must be listed in the <code>org.osgi.framework.bootdelegation</code> property. Sling provides a mechanism to extend the default setting of the <code>org.osgi.framework.bootdelegation</code> property by adding properties prefixed with <code>sling.bootdelegation.</code>. The value of each of these prefixed properties is conditionally appended to the <code>org.osgi.framework.bootdelegation</code> property. <em>Conditionally</em> means, that the property name may contain the fully qualified name of a class, which is checked to see whether to add the property value or not.</p>
<p><em>Examples</em></p>
-<table>
-<tr><td> *sling.bootdelegation.simple = com.some.package* </td><td> This setting
-unconditionally adds the *com.some.package* package to the
-*org.osgi.framework.bootdelegation* property </th></tr>
-<tr><td> *sling.bootdelegation.class.com.some.other.Main = com.some.other* </td><td>
-This setting checks whether the *com.some.other.Main* class is known. If
-so, the *com.some.other* package is added to the
-*org.osgi.framework.bootdelegation* property. Otherwise the
-*com.some.other* package is not added - and therefore must be exported by
-a bundle if required for use inside the framework. </td></tr>
-</table>
-
-<p><em>Note</em> Even though packages listed in the
-<em>org.osgi.framework.bootdelegation</em> property will always be loaded from
-the environment, any bundles using these packages must still import them
-(through <em>Import-Package</em> or <em>DynamicImport-Package</em>) and the bundles
-must resolve for being usable.</p>
-<p><a name="Configuration-OSGiSystemPackagesSupport"></a></p>
+<p>| <code>sling.bootdelegation.simple = com.some.package</code> | This setting unconditionally adds the <code>com.some.package</code> package to the <code>org.osgi.framework.bootdelegation</code> property |
+|
+| <code>sling.bootdelegation.class.com.some.other.Main = com.some.other</code> | This setting checks whether the <code>com.some.other.Main</code> class is known. If so, the <code>com.some.other</code> package is added to the <code>org.osgi.framework.bootdelegation</code> property. Otherwise the <code>com.some.other</code> package is not added - and therefore must be exported by a bundle if required for use inside the framework. |</p>
+<p><em>Note</em> Even though packages listed in the <code>org.osgi.framework.bootdelegation</code> property will always be loaded from the environment, any bundles using these packages must still import them (through <code>Import-Package</code> or <code>DynamicImport-Package</code>) and the bundles must resolve for being usable.</p>
<h3 id="osgi-system-packages-support">OSGi System Packages Support</h3>
-<p>As listed in the above section on OSGi Boot Delegation Support, the
-<em>org.osgi.framework.system.packages</em> property may be used to extend the
-export list of the system bundle. Similar to the support for extending the
-boot delegation packages list, Sling supports extending the system packages
-list. The mechanism to extend the default setting of the
-<em>org.osgi.framework.system.packages</em> property by adding properties
-prefixed with <em>sling.system.packages.</em>. The value of each of these
-prefixed properties is conditionally appended to the
-<em>org.osgi.framework.system.packages</em> property. <em>Conditionally</em> means,
-that the property name may contain the fully qualified name of a class,
-which is checked to see whether to add the property value or not.</p>
+<p>As listed in the above section on OSGi Boot Delegation Support, the <code>org.osgi.framework.system.packages</code> property may be used to extend the export list of the system bundle. Similar to the support for extending the boot delegation packages list, Sling supports extending the system packages list. The mechanism to extend the default setting of the <code>org.osgi.framework.system.packages</code> property by adding properties prefixed with <code>sling.system.packages.</code>. The value of each of these prefixed properties is conditionally appended to the <code>org.osgi.framework.system.packages</code> property. <em>Conditionally</em> means, that the property name may contain the fully qualified name of a class, which is checked to see whether to add the property value or not.</p>
<p><em>Examples</em></p>
-<table>
-<tr><td> *sling.system.packages.simple = com.some.package* </td><td> This setting
-unconditionally adds the *com.some.package* package to the
-*org.osgi.framework.system.packages* property </th></tr>
-<tr><td> *sling.system.packages.class.com.some.other.Main = com.some.other* </td><td>
-This setting checks whether the *com.some.other.Main* class is known. If
-so, the *com.some.other* package is added to the
-*org.osgi.framework.system.packages* property. Otherwise the
-*com.some.other* package is not added - and therefore must be exported by
-a bundle if required for use inside the framework. </td></tr>
-</table>
-
-<p><em>Note</em> Packages listed in the <em>org.osgi.framework.system.packages</em>
-required by any bundles must be imported by those bundles by listing them
-in the <em>Import-Package</em> or <em>DynamicImport-Package</em> manifest header.</p>
-<p><a name="Configuration-Recommendationsforpropertynames"></a></p>
+<p>| <code>sling.system.packages.simple = com.some.package</code> | This setting unconditionally adds the <code>com.some.package</code> package to the <code>org.osgi.framework.system.packages</code> property |
+|
+| <code>sling.system.packages.class.com.some.other.Main = com.some.other</code> | This setting checks whether the <code>com.some.other.Main</code> class is known. If so, the <code>com.some.other</code> package is added to the <code>org.osgi.framework.system.packages</code> property. Otherwise the <code>com.some.other</code> package is not added - and therefore must be exported by a bundle if required for use inside the framework. |</p>
+<p><em>Note</em> Packages listed in the <code>org.osgi.framework.system.packages</code> required by any bundles must be imported by those bundles by listing them in the <code>Import-Package</code> or <code>DynamicImport-Package</code> manifest header.</p>
<h2 id="recommendations-for-property-names">Recommendations for property names</h2>
<p>The following system property names are reserved:</p>
<ul>
-<li>Names starting with <em>org.osgi.</em> are reserved for OSGi defined
-Framework properties</li>
-<li>Names starting with <em>org.apache.felix.</em> are reserved for the Felix
-Framework</li>
-<li>Names starting with <em>sling.</em> and <em>org.apache.sling.</em> are reserved
-for Sling</li>
+<li>Names starting with <code>org.osgi.</code> are reserved for OSGi defined Framework properties</li>
+<li>Names starting with <code>org.apache.felix.</code> are reserved for the Felix Framework</li>
+<li>Names starting with <code>sling.</code> and <code>org.apache.sling.</code> are reserved for Sling</li>
</ul>
<p>To prevent property name collisions, I suggest the following convention:</p>
<ul>
-<li>Use fully qualified property names for initial configuration through
-Framework properties</li>
-<li>Use unqualified property names for configuration through the
-Configuration Admin Service</li>
+<li>Use fully qualified property names for initial configuration through Framework properties</li>
+<li>Use unqualified property names for configuration through the Configuration Admin Service</li>
</ul>
-<p><a name="Configuration-WellKnownProperties"></a></p>
<h2 id="well-known-properties">Well Known Properties</h2>
-<p>The following table is a collection of well known property names from
-different parts of Project Sling.</p>
+<p>The following table is a collection of well known property names from different parts of Project Sling.</p>
<table>
-<tr><th> Property </th><th> Description </th></tr>
-<tr><td> *sling.home* </td><td> Defines the file system location where Project Sling
-will write copies of the initial configuration. This property should also
-be used to define other local file system locations such as the directory
-to use for the Apache Felix Bundle Cache (*$\{sling.home}/felix* by
-default). If this property is not set it defaults to
-*$\{user.dir}/sling*. </td></tr>
-<tr><td> *sling.home.url* </td><td> Contains the Sling directory set in the
-*sling.home* property as a valid URL. This property may be used in
-situations where the Sling directory is required as an URL. This property
-is automatically set by the Sling application and may not be modified by
-configuration files. </td></tr>
-<tr><td> *sling.ignoreSystemProperties* </td><td> Whether to overwrite any configuration
-properties with Java system properties or not. By default this property is
-set to *true* by the Sling Servlet but not set by the Sling main class.
-The reason to set this by default in the Sling Servlet is to not induce
-values from the environment, which may not be appropriate in the Web
-Application case. </td></tr>
-<tr><td> *obr.repository.url* </td><td> A comma-separated list of OSGi Bundle Repository
-URLs. See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
-. </td></tr>
-<tr><td> *sling.install.bundles* </td><td> A comma-separated list of start level
-numbers. See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
-. </td></tr>
-<tr><td> *sling.install.<n>* </td><td> A comma-separated list of bundle specifications.
-See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
-. </td></tr>
-<tr><td> *org.apache.sling.osgi.log.** </td><td> Properties providing initial
-configuration to the Sling Log Service. See 'Important Properties' on the
-page [Initial Provisioning and Startup](launch-sling.html)
-. </td></tr>
+<thead>
+<tr>
+<th>Property</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sling.home</code></td>
+<td>Defines the file system location where Project Sling will write copies of the initial configuration. This property should also be used to define other local file system locations such as the directory to use for the Apache Felix Bundle Cache (<code>$\{sling.home}/felix</code> by default). If this property is not set it defaults to <code>$\{user.dir}/sling</code>.</td>
+</tr>
+<tr>
+<td><code>sling.home.url</code></td>
+<td>Contains the Sling directory set in the <code>sling.home</code> property as a valid URL. This property may be used in situations where the Sling directory is required as an URL. This property is automatically set by the Sling application and may not be modified by configuration files.</td>
+</tr>
+<tr>
+<td><code>sling.ignoreSystemProperties</code></td>
+<td>Whether to overwrite any configuration properties with Java system properties or not. By default this property is set to <code>true</code> by the Sling Servlet but not set by the Sling main class. The reason to set this by default in the Sling Servlet is to not induce values from the environment, which may not be appropriate in the Web Application case.</td>
+</tr>
+<tr>
+<td><code>obr.repository.url</code></td>
+<td>A comma-separated list of OSGi Bundle Repository URLs. See <em>Important Properties</em> on the page <a href="/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+<tr>
+<td><code>sling.install.bundles</code></td>
+<td>A comma-separated list of start level numbers. See <em>Important Properties</em> on the page <a href="/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+<tr>
+<td><code>sling.install.<n></code></td>
+<td>A comma-separated list of bundle specifications. See <em>Important Properties</em> on the page <a href="/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.osgi.log.*</code></td>
+<td>Properties providing initial configuration to the Sling Log Service. See 'Important Properties' on the page <a href="/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+</tbody>
</table>
-
-<p><a name="Configuration-ConfigurationAdminService"></a></p>
<h2 id="configuration-admin-service">Configuration Admin Service</h2>
-<p>Configuration of the system entities, such as services and components, by
-the system administrator is supported the Configuration Admin Service. The
-Configuration Admin Service acts as the center for the management of the
-configuration data, to which GUI-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 registered
-with the <em>ManagedService</em> or <em>ManagedServiceFactory</em> interfaces are
-updated with the configuration upon updated. The Service Component Runtime
-on the other hand recognizes updated configuration and provides it to the
-managed components as defined in the OSGi Declarative Services
-Specification.</p>
-<p>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 OSGi components declared in the bundles with
-configuration values. The Sling Management Console provides a simple GUI to
-manage these configuration elements on the 'Configuration' page.</p>
-<p>For more information on the Configuration Admin Service refer to the OSGi
-Configuration Admin Service Specification in the OSGi Service Platform
-Service Compendium book.</p>
+<p>Configuration of the system entities, such as services and components, by the system administrator is supported the Configuration Admin Service. The Configuration Admin Service acts as the center for the management of the configuration data, to which GUI-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 registered with the <code>ManagedService</code> or <code>ManagedServiceFactory</code> interfaces are updated with the configuration upon updated. The Service Component Runtime on the other hand recognizes updated configuration and provides it to the managed components as defined in the OSGi Declarative Services Specification.</p>
+<p>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 OSGi components declared in the bundles with configuration values. The Sling Management Console provides a simple GUI to manage these configuration elements on the 'Configuration' page.</p>
+<p>For more information on the Configuration Admin Service refer to the OSGi Configuration Admin Service Specification in the OSGi Service Platform Service Compendium book.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328899 by fmeschbe on Sun, 22 Apr 2012 16:52:13 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Added: websites/staging/sling/trunk/content/content-loading-jcr-contentloader.html
==============================================================================
--- websites/staging/sling/trunk/content/content-loading-jcr-contentloader.html (added)
+++ websites/staging/sling/trunk/content/content-loading-jcr-contentloader.html Tue May 22 08:25:32 2012
@@ -0,0 +1,294 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Sling - Content Loading (jcr.contentloader)</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a>
+ </div>
+ <h1>Content Loading (jcr.contentloader)</h1>
+ <h1 id="content-loading-and-nodetype-support">Content Loading and Nodetype Support</h1>
+<p>Apache Sling provides support for initial content loading into a repository and for registering node types. The <code>sling-jcr-contentloader</code> bundle provides loading of content from a bundle into the repository and the <code>sling-jcr-base</code> bundle provides node type registration.</p>
+<h2 id="initial-content-loading">Initial Content Loading</h2>
+<p>Bundles can provide initial content, which is loaded into the repository when the bundle has entered the <em>started</em> state. Such content is expected to be contained in the bundles accessible through the Bundle entry API methods. Content to be loaded is declared in the <code>Sling-Initial-Content</code> bundle manifest header. This header takes a comma-separated list of bundle entry paths. Each entry and all its child entries are accessed and entered into starting with the child entries of the listed entries.</p>
+<p>Adding this content preserves the paths of the entries as show in this table, which assumes a <code>Sling-Initial-Content</code> header entry of <code>SLING-INF/content</code>:
+| Entry | Repository Path |
+|--|--|
+| <code>SLING-INF/content/home</code> | <code>/home</code> |
+| <code>SLING-INF/content/content/playground/en/home</code> | <code>/content/playground/en/home</code> |
+Bundle entries are installed as follows:
+| Entry Type | Installation method |
+|--|--|
+| Directory | Created as a node of type <code>nt:folder</code> unless a content definition file of the same name exists in the same directory as the directory to be installed. Example: A directory <code>SLING-INF/content/dir</code> is installed as node <code>/dir</code> of type <code>nt:folder</code> unless a <code>SLING-INF/content/dir.xml</code> or <code>SLING-INF/content/dir.json</code> file exists which defines the content for the <code>/dir</code> node. |
+| File | Unless the file is a content definition file (see below) an <code>nt:file</code> node is created for the file and an <code>nt:resource</code> node is created as its <code>jcr:content</code> child node to take the contents of the bundle file. The properties of the <code>nt:resource</code> node are set from file information as available. If the file is a content definition file, the content is created as defined in the file. See below for the content definition file specification. |
+It is possible to modify the intial content loading default behaviour by using certain optional directives. Directives should be specified separated by semicolon. They are defined as follows:
+| Directive | Definition | Default value | Description |
+|--|--|--|--|
+| <code>overwrite</code> | <code>overwrite:=(true\|false)</code> | <code>false</code> | The overwrite directive specifies if content nodes should be overwritten or just initially added. If this is true, existing nodes are deleted and a new node is created in the same place. |
+| <code>overwriteProperties</code> | <code>overwriteProperties:=(true\|false)</code> | <code>false</code> | The overwriteProperties directive specifying if content properties should be overwritten or just initially added. |
+| <code>uninstall</code> | <code>uninstall:=(true\|false)</code> | <code>overwrite</code> | The uninstall directive specifies if content should be uninstalled when bundle is unregistered. This value defaults to the value of the <code>overwrite</code> directive. |
+| <code>path</code> | <code>path:=*/target/location{*</code>} | <code>/</code> | The path directive specifies the target node where initial content will be loaded. If the path does not exist yet in the repository, it is created by the content loader. The intermediate nodes are of type <code>nt:folder</code>. |
+| <code>checkin</code> | <code>checkin:=(true\|false)</code> | <code>false</code> | The checkin directive specifies whether versionable nodes should be checked in. |
+| <code>ignoreImportProviders</code> | <code>ignoreImportProviders:=list of extensions</code> | <code>empty</code> | This directive can be used to not run one of the configured extractors (see below). |
+Examples of these directives uses could be (assumes a Sling-Initial-Content header entry of SLING-INF/content):
+| Entry | Behaviour |
+|--|--|
+| <code>SLING-INF/content/home;overwrite:=true;uninstall:=true</code> | Overwrites already existing content in <em>/home</em> and uninstalls the content when the bundle is unregistered. |
+| <code>SLING-INF/content/home;overwriteProperties:=true</code> | Overwrites properties of existing content in <em>/home</em>. |
+| <code>SLING-INF/content/home;path:=/sites/sling*website</code> | if <em>/sites/sling</em>website<em> exists it loads the content into it. Otherwise, it loads the content into root node </em>/*. |
+| <code>SLING-INF/content/home;checkin:=true</code> | After content loading, versionable nodes are checked in. |</p>
+<h2 id="loading-initial-content-from-bundles">Loading initial content from bundles</h2>
+<p>Repository items to be loaded into the repository, when the bundle is first installed, may be defined in four ways:
+1. Directories
+1. Files
+1. XML descriptor files
+1. JSON descriptor files</p>
+<p>Depending on the bundle entry found in the location indicated by the Sling-Initial-Content bundle manifest header, nodes are created (and/or updated) as follows:</p>
+<h3 id="directories">Directories</h3>
+<p>Unless a node with the name of the directory already exists or has been defined in an XML or JSON descriptor file (see below) a directory is created as a node with the primary node type "nt:folder" in the repository.</p>
+<h3 id="files">Files</h3>
+<p>Unless a node with the name of the file already exists or has been defined in an XML or JSON descriptor file (see below) a file is created as two nodes in the repository. The node bearing the name of the file itself is created with the
+primary node type "nt:file". Underneath this file node, a resource node with the primary node type "nt:resource" is created, which is set to the contents of the file.</p>
+<p>The MIME type is derived from the file name extension by first trying to resolve it from the Bundle entry URL. If this does not resolve to a MIME type, the Sling MIME type resolution service is used to try to find a mime type. If all fals, the MIME type is defaulted to "application/octet-stream". </p>
+<h3 id="xml-descriptor-files">XML Descriptor Files</h3>
+<p>Nodes, Properties and in fact complete subtrees may be described in XML files using either the JCR SystemView format, or the format described below. In either case, the file must have the .xml extension.</p>
+<div class="codehilite"><pre><span class="nt"><node></span>
+ <span class="c"><!--</span>
+<span class="c"> optional on top level, defaults to XML file name without .xml extension</span>
+<span class="c"> required for child nodes</span>
+<span class="c"> --></span>
+ <span class="nt"><name></span>xyz<span class="nt"></name></span>
+
+ <span class="c"><!--</span>
+<span class="c"> optional, defaults to nt:unstructured</span>
+<span class="c"> --></span>
+ <span class="nt"><primaryNodeType></span>nt:file<span class="nt"></primaryNodeType></span>
+
+ <span class="c"><!--</span>
+<span class="c"> optional mixin node type</span>
+<span class="c"> may be repeated for multiple mixin node types</span>
+<span class="c"> --></span>
+ <span class="nt"><mixinNodeType></span>mix:versionable<span class="nt"></mixinNodeType></span>
+ <span class="nt"><mixinNodeType></span>mix:lockable<span class="nt"></mixinNodeType></span>
+
+ <span class="c"><!--</span>
+<span class="c"> Optional properties for the node. Each <property> element defines</span>
+<span class="c"> a single property of the node. The element may be repeated.</span>
+<span class="c"> --></span>
+ <span class="nt"><property></span>
+ <span class="c"><!--</span>
+<span class="c"> required property name</span>
+<span class="c"> --></span>
+ <span class="nt"><name></span>prop<span class="nt"></name></span>
+
+ <span class="c"><!--</span>
+<span class="c"> value of the property.</span>
+<span class="c"> For multi-value properties, the values are defined by multiple</span>
+<span class="c"> <value> elements nested inside a <values> element instead of a</span>
+<span class="c"> single <value> element</span>
+<span class="c"> --></span>
+ <span class="nt"><value></span>property value as string<span class="nt"></value></span>
+
+ <span class="c"><!--</span>
+<span class="c"> Optional type of the property value, defaults to String.</span>
+<span class="c"> This must be one of the property type strings defined in the</span>
+<span class="c"> JCR PropertyType interface.</span>
+<span class="c"> <type>String</type></span>
+<span class="c"> </property></span>
+
+<span class="c"> <!--</span>
+<span class="c"> Additional child nodes. May be further nested.</span>
+<span class="c"> --></span>
+ <span class="nt"><node></span>
+ ....
+ <span class="nt"></node></span>
+ <span class="nt"></node></span>
+</pre></div>
+
+
+<h4 id="using-a-custom-xml-format">Using a custom XML format</h4>
+<p>By writing an XSLT stylesheet file, you can use whatever XML format you prefer. The XML file references an XSLT stylesheet by using the xml-stylesheet processing instruction: </p>
+<div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
+<span class="cp"><?xml-stylesheet href="my-transform.xsl" type="text/xsl"?></span> <span class="c"><!-- The path to my-transform.xsl is relative to this file --></span>
+
+<span class="nt"><your_custom_root_node></span>
+ <span class="nt"><your_custom_element></span>
+ ...
+ <span class="nt"></your_custom_element></span>
+...
+<span class="nt"></your_custom_root_node></span>
+</pre></div>
+
+
+<p>The my-transform.xsl file is then responsible for translating your format into one of the supported XML formats:</p>
+<div class="codehilite"><pre><span class="k"><xsl:stylesheet</span> <span class="na">version=</span><span class="s">"1.0"</span> <span class="na">xmlns:jcr=</span><span class="s">"http://www.jcp.org/jcr/1.0"</span> <span class="na">xmlns:mix=</span><span class="s">"http://www.jcp.org/jcr/mix/1.0"</span>
+ <span class="na">xmlns:sv=</span><span class="s">"http://www.jcp.org/jcr/sv/1.0"</span> <span class="na">xmlns:sling=</span><span class="s">"http://sling.apache.org/jcr/sling/1.0"</span>
+ <span class="na">xmlns:rep=</span><span class="s">"internal"</span> <span class="na">xmlns:nt=</span><span class="s">"http://www.jcp.org/jcr/nt/1.0"</span> <span class="na">xmlns:xsl=</span><span class="s">"http://www.w3.org/1999/XSL/Transform"</span><span class="nt">></span>
+
+ <span class="k"><xsl:template</span> <span class="na">match=</span><span class="s">"your_custom_element"</span><span class="nt">></span>
+ <span class="nt"><node></span>
+ ...
+ <span class="nt"></node></span>
+ <span class="k"></xsl:template></span>
+ ...
+<span class="k"></xsl:stylesheet></span>
+</pre></div>
+
+
+<h3 id="json-descriptor-files">JSON Descriptor Files</h3>
+<p>Nodes, Properties and in fact complete subtrees may be described in JSON files using the following skeleton structure (see <a href="">http://www.json.org</a> or information on the syntax of JSON) :</p>
+<div class="codehilite"><pre><span class="p">{</span>
+ <span class="sr">//</span> <span class="n">optional</span> <span class="n">node</span> <span class="n">name</span> <span class="n">on</span> <span class="n">top</span> <span class="n">level</span><span class="p">,</span> <span class="n">default</span> <span class="n">is</span> <span class="n">file</span> <span class="n">name</span> <span class="n">without</span> <span class="o">.</span><span class="n">json</span> <span class="n">ext</span><span class="o">.</span>
+ <span class="s">"name"</span><span class="p">:</span> <span class="s">"nodename"</span><span class="p">,</span>
+
+ <span class="sr">//</span> <span class="n">optional</span> <span class="n">primary</span> <span class="n">node</span> <span class="n">type</span><span class="p">,</span> <span class="n">default</span> <span class="s">"nt:unstructured"</span>
+ <span class="s">"primaryNodeType"</span><span class="p">:</span> <span class="s">"sling:ScriptedComponent"</span><span class="p">,</span>
+
+ <span class="sr">//</span> <span class="n">optional</span> <span class="n">mixin</span> <span class="n">node</span> <span class="n">types</span> <span class="n">as</span> <span class="n">array</span>
+ <span class="s">"mixinNodeTypes"</span><span class="p">:</span> <span class="p">[</span> <span class="p">],</span>
+
+ <span class="sr">//</span> <span class="n">the</span> <span class="s">"properties"</span> <span class="n">property</span> <span class="n">is</span> <span class="n">an</span> <span class="n">object</span> <span class="n">indexed</span> <span class="n">by</span> <span class="n">property</span> <span class="n">name</span> <span class="n">whose</span>
+ <span class="sr">//</span> <span class="n">value</span> <span class="n">is</span> <span class="n">either</span> <span class="n">the</span> <span class="n">string</span> <span class="n">property</span> <span class="n">value</span><span class="p">,</span> <span class="n">array</span> <span class="k">for</span> <span class="n">multi</span><span class="o">-</span><span class="nb">values</span> <span class="ow">or</span>
+ <span class="sr">//</span> <span class="n">an</span> <span class="n">object</span> <span class="n">whose</span> <span class="n">value</span><span class="p">[</span><span class="n">s</span><span class="p">]</span> <span class="n">property</span> <span class="n">denotes</span> <span class="n">the</span> <span class="n">property</span> <span class="n">value</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="ow">and</span>
+ <span class="sr">//</span> <span class="n">whose</span> <span class="n">type</span> <span class="n">property</span> <span class="n">denotes</span> <span class="n">the</span> <span class="n">property</span> <span class="n">type</span>
+ <span class="s">"properties"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">"sling:contentClass"</span><span class="p">:</span> <span class="s">"com.day.sling.jcr.test.Test"</span><span class="p">,</span>
+ <span class="s">"sampleMulti"</span><span class="p">:</span> <span class="p">[</span> <span class="s">"v1"</span><span class="p">,</span> <span class="s">"v2"</span> <span class="p">],</span>
+ <span class="s">"sampleStruct"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">"value"</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
+ <span class="s">"type"</span><span class="p">:</span> <span class="s">"Long"</span>
+ <span class="p">}</span>
+ <span class="s">"sampleStructMulti"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">"value"</span><span class="p">:</span> <span class="p">[</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span> <span class="p">],</span>
+ <span class="s">"type"</span><span class="p">:</span> <span class="s">"Long"</span>
+ <span class="p">}</span>
+ <span class="p">},</span>
+
+ <span class="sr">//</span> <span class="n">the</span> <span class="s">"nodes"</span> <span class="n">property</span> <span class="n">is</span> <span class="n">an</span> <span class="n">array</span> <span class="n">of</span> <span class="n">objects</span> <span class="n">denoting</span> <span class="n">child</span> <span class="n">nodes</span><span class="o">.</span> <span class="n">Nodes</span>
+ <span class="sr">//</span> <span class="n">may</span> <span class="n">be</span> <span class="n">further</span> <span class="n">nested</span><span class="o">.</span>
+ <span class="s">"nodes"</span><span class="p">:</span> <span class="p">[</span>
+ <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">the</span> <span class="n">name</span> <span class="n">property</span> <span class="n">is</span> <span class="n">required</span> <span class="n">on</span> <span class="p">(</span><span class="n">nested</span><span class="p">)</span> <span class="n">child</span> <span class="n">nodes</span>
+ <span class="s">"name"</span><span class="p">:</span> <span class="s">"sling:scripts"</span><span class="p">,</span>
+
+ <span class="s">"primaryNodeType"</span><span class="p">:</span> <span class="s">"sling:ScriptList"</span><span class="p">,</span>
+
+ <span class="s">"nodes"</span><span class="p">:</span> <span class="p">[</span>
+ <span class="p">{</span>
+ <span class="s">"primaryNodeType"</span><span class="p">:</span> <span class="s">"sling:Script"</span><span class="p">,</span>
+ <span class="s">"properties"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">"sling:name"</span><span class="p">:</span> <span class="s">"/test/content/jsp/start.jsp"</span><span class="p">,</span>
+ <span class="s">"sling:type"</span><span class="p">:</span> <span class="s">"jsp"</span><span class="p">,</span>
+ <span class="s">"sling:glob"</span><span class="p">:</span> <span class="s">"*"</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="p">]</span>
+ <span class="p">}</span>
+ <span class="p">]</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<h3 id="extractors">Extractors</h3>
+<p>By default, the <code>sling-jcr-contentloader</code> bundle tries to extract certain file types during content loading. These include <code>json</code>, <code>xml</code>, <code>zip</code>, and <code>jar</code> files. Therefore all available extractors are used for content processing. However if some files should be put into the repository unextracted, the <code>ignoreImportProviders</code> directive can be used with a comma separated list of extensions that should not be extracted, like <code>ignoreImportProviders:="jar,zip"</code>. Please note that the value needs to be put into quotation marks if more than one value is used like in the example.</p>
+<h3 id="workspace-targetting">Workspace Targetting</h3>
+<p>By default, initial content will be loaded into the default workspace. To override this, add a <code>Sling-Initial-Content-Workspace</code> bundle manifest header to specify the manifest. Note that <em>all</em> content from a bundle will be loaded into the same workspace. </p>
+<h2 id="declared-node-type-registration">Declared Node Type Registration</h2>
+<p>The <code>sling-jcr-base</code> bundle provides low-level repository operations which are at the heart of the functionality of Sling:
+<em> </em>Node Type Definitions* - The class <code>org.apache.sling.content.jcr.base.NodeTypeLoader</code> provides methods to register custom node types with a repository given a repository session and a node type definition file in CND format. This class is also used by this bundle to register node types on behalf of other bundles.</p>
+<p>Bundles may list node type definition files in CND format in the <code>Sling-Nodetypes</code> bundle header. This header is a comma-separated list of resources in the respective bundle. Each resource is taken and fed to the <code>NodeTypeLoader</code> to define the node types.</p>
+<p>After a bundle has entered the <em>resolved</em> state, the node types listed in the <code>Sling-Nodetypes</code> bundle header are registered with the repository.</p>
+<p>Node types installed by this mechanism will never be removed again by the <code>sling-jcr-base</code> bundle. </p>
+<p>Starting with revision 911430, re-registration of existing node types is enabled by default. To disable this, add <code>;rereigster:=false</code> to the resource names for which re-registration should be disabled.</p>
+<p>{warning}
+Support for re-registration of node types is relatively limited. In Jackrabbit, for example, only "trivial" changes are allowed.
+{warning}</p>
+<h3 id="automated-tests">Automated tests</h3>
+<p>The initial content found in the <a href="">sling-test folder of the launchpad initial content</a> is verified by the [InitialContentTest|http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/src/test/java/org/apache/sling/launchpad/webapp/integrationtest/InitialContentTest.java] when running the <em>launchpad/testing</em> integration tests.</p>
+<p>Those tests can be used as verified examples of initial content loading. Contributions are welcome to improve the coverage of those tests.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Modified: websites/staging/sling/trunk/content/contributing.html
==============================================================================
--- websites/staging/sling/trunk/content/contributing.html (original)
+++ websites/staging/sling/trunk/content/contributing.html Tue May 22 08:25:32 2012
@@ -82,40 +82,21 @@
<a href="/">Home</a>
</div>
<h1>Contributing</h1>
- <p><a name="Contributing-Contributing"></a></p>
-<h1 id="contributing">Contributing</h1>
-<p>See <a href="slingxsite:project-information.html">SLINGxSITE:Project Information</a>
- for details about the tools mentioned below.</p>
-<p>Apache Sling is a volunteer effort, so there is always plenty of work that
-needs to be accomplished. If you want to help support Sling, this page is
-intended as a starting point for specific contribution ideas. To further
-understand how the Sling community operates, refer to the Community Roles
-and Processes document and/or join the mailing lists.</p>
-<p>The Sling project organizes its "to do" list using the JIRA issue tracking
-system. Specific items from Sling's JIRA issue tracking system are
-highlighted on this page, but are not limited to it. The purpose of the
-list here is to highlight issues that are either more important or serve as
-good entry points for new contributors.</p>
-<p>It is important to point out that you do not need to be a programmer to
-contribute to Sling. As such, we will break out the list of issues below
-for non-programmers and programmers.</p>
-<p><a name="Contributing-Non-Programmers"></a></p>
+ <h1 id="contributing">Contributing</h1>
+<p>See <a href="">SLINGxSITE:Project Information</a> for details about the tools mentioned below.</p>
+<p>Apache Sling is a volunteer effort, so there is always plenty of work that needs to be accomplished. If you want to help support Sling, this page is intended as a starting point for specific contribution ideas. To further understand how the Sling community operates, refer to the Community Roles and Processes document and/or join the mailing lists.</p>
+<p>The Sling project organizes its "to do" list using the JIRA issue tracking system. Specific items from Sling's JIRA issue tracking system are highlighted on this page, but are not limited to it. The purpose of the list here is to highlight issues that are either more important or serve as good entry points for new contributors.</p>
+<p>It is important to point out that you do not need to be a programmer to contribute to Sling. As such, we will break out the list of issues below for non-programmers and programmers.</p>
<h2 id="non-programmers">Non-Programmers</h2>
-<div class="codehilite"><pre><span class="o">*</span> <span class="n">Improve</span> <span class="n">web</span> <span class="n">site</span> <span class="ow">or</span> <span class="n">documentation</span> <span class="p">(</span><span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span><span class="p">,</span> <span class="n">create</span><span class="o">/</span><span class="n">propose</span> <span class="n">FAQ</span> <span class="n">entries</span><span class="p">)</span><span class="o">.</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="n">Improve</span> <span class="n">web</span> <span class="n">site</span> <span class="ow">or</span> <span class="n">documentation</span> <span class="p">(</span><span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span><span class="p">,</span> <span class="n">create</span><span class="o">/</span><span class="n">propose</span> <span class="n">FAQ</span> <span class="n">entries</span><span class="p">)</span><span class="o">.</span> <span class="n">There</span> <span class="n">is</span> <span class="nb">no</span> <span class="n">specific</span> <span class="n">JIRA</span> <span class="n">issue</span> <span class="k">for</span> <span class="n">this</span> <span class="n">task</span><span class="p">,</span> <span class="n">but</span> <span class="n">any</span> <span class="n">contributions</span> <span class="n">could</span> <span class="n">be</span> <span class="n">posted</sp
an> <span class="n">as</span> <span class="k">new</span> <span class="n">JIRA</span> <span class="n">issues</span> <span class="k">for</span> <span class="n">the</span> <span class="n">Documentation</span> <span class="n">component</span><span class="o">.</span>
</pre></div>
-<p>There is no specific JIRA issue for this task, but any contributions could
-be posted as new JIRA issues for the Documentation component.</p>
-<p><a name="Contributing-Programmers"></a></p>
<h2 id="programmers">Programmers</h2>
-<div class="codehilite"><pre><span class="o">*</span> <span class="n">Implement</span> <span class="n">support</span> <span class="k">for</span> <span class="n">various</span> <span class="n">rendering</span> <span class="n">technologies</span> <span class="n">in</span> <span class="n">Sling</span><span class="o">.</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="n">Implement</span> <span class="n">support</span> <span class="k">for</span> <span class="n">various</span> <span class="n">rendering</span> <span class="n">technologies</span> <span class="n">in</span> <span class="n">Sling</span><span class="o">.</span> <span class="n">Examples</span> <span class="n">coming</span> <span class="n">to</span> <span class="n">mind</span> <span class="n">are</span> <span class="n">JSF</span> <span class="ow">and</span> <span class="n">Wicket</span><span class="o">.</span>
</pre></div>
-
-
-<p>Examples coming to mind are JSF and Wicket.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328899 by fmeschbe on Sun, 22 Apr 2012 16:52:13 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Modified: websites/staging/sling/trunk/content/default-mapping-and-rendering.html
==============================================================================
--- websites/staging/sling/trunk/content/default-mapping-and-rendering.html (original)
+++ websites/staging/sling/trunk/content/default-mapping-and-rendering.html Tue May 22 08:25:32 2012
@@ -82,11 +82,9 @@
<a href="/">Home</a>
</div>
<h1>Default Mapping and Rendering</h1>
- <p>This page contained obsolete content, moved it to
-http://cwiki.apache.org/confluence/display/SLING/Default+Mapping+and+Rendering+%28OBSOLETE%29
-in case it is useful to someone.</p>
+ <p>This page contained obsolete content, moved it to http://cwiki.apache.org/confluence/display/SLING/Default+Mapping+and+Rendering+%28OBSOLETE%29 in case it is useful to someone.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328899 by fmeschbe on Sun, 22 Apr 2012 16:52:13 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Modified: websites/staging/sling/trunk/content/dependency-management.html
==============================================================================
--- websites/staging/sling/trunk/content/dependency-management.html (original)
+++ websites/staging/sling/trunk/content/dependency-management.html Tue May 22 08:25:32 2012
@@ -82,95 +82,105 @@
<a href="/">Home</a>
</div>
<h1>Dependency Management</h1>
- <p><a name="DependencyManagement-DependencyManagement"></a></p>
-<h1 id="dependency-management">Dependency Management</h1>
-<p>{excerpt}This page is about how we do and don't do dependency management in
-the Sling project.{excerpt}</p>
-<p>{toc:minLevel=2}</p>
-<p><a name="DependencyManagement-Introduction"></a></p>
+ <h1 id="dependency-management">Dependency Management</h1>
+<p>This page is about how we do and don't do dependency management in the Sling project.</p>
+<div class="toc">
+<ul>
+<li><a href="#dependency-management">Dependency Management</a><ul>
+<li><a href="#introduction">Introduction</a></li>
+<li><a href="#dependency-management_1">Dependency Management</a></li>
+<li><a href="#references">References</a></li>
+</ul>
+</li>
+</ul>
+</div>
<h2 id="introduction">Introduction</h2>
-<p>Maven provides projects with a nice feature called dependency management.
-In Sling we currently use this feature to declare the non-Sling
-dependencies of modules in the parent POM.</p>
-<p>After working with this some time and trying to upgrade various
-dependencies we came to the conclusion, that using Maven dependency
-management is not going to work out in the Sling scenario.</p>
-<p>Why ? Maven's dependency management is aimed at traditional applicaitons,
-which are glued together statically during the build process. For this
-environment, dependency management is a great thing, since it guarantees a
-consistent application setup.</p>
-<p>In a dynamic application setup as provided by an OSGi framework the static
-dependency management of Maven does not help. Actually it even causes
-problematic results with respect to backwards compatibility when using the
-Maven Bundle plugin.</p>
-<p>Why's that ? The Maven Bundle plugin is constructs the bundle manifest and
-will generally automatically create the Import-Package header. If the
-providing library (from maven's dependency list) has <em>Export-Package</em>
-headers with version numbers, the Maven Bundle plugin will insert the
-respective version numbers for the <em>Import-Package</em> header. This makes
-perfect sense, because it is expected, that the artifact required at least
-the given package version.</p>
-<p>When using Maven dependency management, upgrading any dependencies in the
-parent POM may automatically increse the version numbers in the
-<em>Import-Package</em> headers and hence may cause any such bundle to fail
-resolution if deployed - even though the bundle did not change and does not
-really require a new version of the dependency.</p>
-<p>So, in the case of OSGi deployment, Maven's dependency management actually
-interferes with the OSGi framework dependency management.</p>
-<p>As a consequence, I suggest we drop dependency management in the parent pom
-(almost) completely and state the followin.</p>
-<p><a name="DependencyManagement-DependencyManagement"></a></p>
+<p>Maven provides projects with a nice feature called dependency management. In Sling we currently use this feature to declare the non-Sling dependencies of modules in the parent POM.</p>
+<p>After working with this some time and trying to upgrade various dependencies we came to the conclusion, that using Maven dependency management is not going to work out in the Sling scenario.</p>
+<p>Why ? Maven's dependency management is aimed at traditional applicaitons, which are glued together statically during the build process. For this environment, dependency management is a great thing, since it guarantees a consistent application setup.</p>
+<p>In a dynamic application setup as provided by an OSGi framework the static dependency management of Maven does not help. Actually it even causes problematic results with respect to backwards compatibility when using the Maven Bundle plugin.</p>
+<p>Why's that ? The Maven Bundle plugin is constructs the bundle manifest and will generally automatically create the Import-Package header. If the providing library (from maven's dependency list) has <code>Export-Package</code> headers with version numbers, the Maven Bundle plugin will insert the respective version numbers for the <code>Import-Package</code> header. This makes perfect sense, because it is expected, that the artifact required at least the given package version.</p>
+<p>When using Maven dependency management, upgrading any dependencies in the parent POM may automatically increse the version numbers in the <code>Import-Package</code> headers and hence may cause any such bundle to fail resolution if deployed - even though the bundle did not change and does not really require a new version of the dependency.</p>
+<p>So, in the case of OSGi deployment, Maven's dependency management actually interferes with the OSGi framework dependency management.</p>
+<p>As a consequence, I suggest we drop dependency management in the parent pom (almost) completely and state the followin.</p>
<h2 id="dependency-management_1">Dependency Management</h2>
-<p>The parent pom only does dependency management for build time dependencies
-and a very limited number of API dependencies used Sling wide. These
-dependencies are:</p>
+<p>The parent pom only does dependency management for build time dependencies and a very limited number of API dependencies used Sling wide. These dependencies are:</p>
<ul>
-<li>All plugin dependencies. That is <em>PluginManagement</em> is still used.
-Maven plugins are actualy build time dependencies and therefore have no
-influence on the actual deployment.</li>
-<li>Dependencies on commonly used testing environment helpers. Test helper
-classes are also build time dependencies used to run the unit and
-integration tests. As such, they may well be managed.</li>
-<li>Sling makes a small number of assumptions about the environment, which
-we codify in the dependency management: The minimum version number of the
-OSGi specificaiton used, the servlet API version and the JCR API version.</li>
+<li>All plugin dependencies. That is <code>PluginManagement</code> is still used. Maven plugins are actualy build time dependencies and therefore have no influence on the actual deployment.</li>
+<li>Dependencies on commonly used testing environment helpers. Test helper classes are also build time dependencies used to run the unit and integration tests. As such, they may well be managed.</li>
+<li>Sling makes a small number of assumptions about the environment, which we codify in the dependency management: The minimum version number of the OSGi specificaiton used, the servlet API version and the JCR API version.</li>
</ul>
-<p>The <em><DependencyManagement></em> element currently contains the following
-managed dependencies:</p>
+<p>The <code><DependencyManagement></code> element currently contains the following managed dependencies:</p>
<table>
-<tr><th> Group ID </th><th> Artifact ID </th><th> Version </th><th> Scope </th></tr>
-<tr><td> org.apache.felix </td><td> org.osgi.core </td><td> 1.2.0 </td><td> provided </td></tr>
-<tr><td> org.apache.felix </td><td> org.osgi.compendium </td><td> 1.2.0 </td><td> provided </td></tr>
-<tr><td> javax.servlet </td><td> servlet-api </td><td> 2.4 </td><td> provided </td></tr>
-<tr><td> javax.jcr </td><td> jcr </td><td> 1.0 </td><td> provided </td></tr>
-<tr><td> org.slf4j </td><td> slf4j-api </td><td> 1.5.2 </td><td> provided </td></tr>
-<tr><td> junit </td><td> junit </td><td> 4.3 </td><td> test </td></tr>
-<tr><td> org.jmock </td><td> jmock-junit4 </td><td> 2.2.0 </td><td> test </td></tr>
-<tr><td> org.slf4j </td><td> slf4j-simple </td><td> 1.5.2 </td><td> test </td></tr>
+<thead>
+<tr>
+<th>Group ID</th>
+<th>Artifact ID</th>
+<th>Version</th>
+<th>Scope</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>org.apache.felix</td>
+<td>org.osgi.core</td>
+<td>1.2.0</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>org.apache.felix</td>
+<td>org.osgi.compendium</td>
+<td>1.2.0</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>javax.servlet</td>
+<td>servlet-api</td>
+<td>2.4</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>javax.jcr</td>
+<td>jcr</td>
+<td>1.0</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>org.slf4j</td>
+<td>slf4j-api</td>
+<td>1.5.2</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>junit</td>
+<td>junit</td>
+<td>4.3</td>
+<td>test</td>
+</tr>
+<tr>
+<td>org.jmock</td>
+<td>jmock-junit4</td>
+<td>2.2.0</td>
+<td>test</td>
+</tr>
+<tr>
+<td>org.slf4j</td>
+<td>slf4j-simple</td>
+<td>1.5.2</td>
+<td>test</td>
+</tr>
+</tbody>
</table>
-
-<p>All dependencies per module are fully described in terms of version, scope,
-and classifier by the respective project.</p>
-<p>The version of the module dependency should be selected according to the
-following rule: The lowest version providing the functionality required by
-the module (or bundle). By required functionality we bascially mean
-provided API.</p>
-<p>Generally there is a constant flow of releases of dependent libraries. In
-general this should not cause the dependency version number of a using
-module to be increased. There is one exception though: If the fixed library
-version contains a bug fix, which has an influence on the operation of the
-module, an increase in the version number is indicated and should also be
-applied.</p>
-<p><a name="DependencyManagement-References"></a></p>
+<p>All dependencies per module are fully described in terms of version, scope, and classifier by the respective project.</p>
+<p>The version of the module dependency should be selected according to the following rule: The lowest version providing the functionality required by the module (or bundle). By required functionality we bascially mean provided API.</p>
+<p>Generally there is a constant flow of releases of dependent libraries. In general this should not cause the dependency version number of a using module to be increased. There is one exception though: If the fixed library version contains a bug fix, which has an influence on the operation of the module, an increase in the version number is indicated and should also be applied.</p>
<h2 id="references">References</h2>
<ul>
-<li><a href="http://markmail.org/message/5qpmsukdk4mdacdy">Dependency ManagementLink to this message</a>
- -- Discussion thread about reducing Maven 2 <em>DependencyManagement</em></li>
-<li><a href="https://issues.apache.org/jira/browse/SLING-811">SLING-811</a>
- -- The actual issue governing the changes to the project descriptors</li>
+<li><a href="">Dependency ManagementLink to this message</a> -- Discussion thread about reducing Maven 2 <code>DependencyManagement</code></li>
+<li><a href="">SLING-811</a> -- The actual issue governing the changes to the project descriptors</li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328899 by fmeschbe on Sun, 22 Apr 2012 16:52:13 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project