http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/context-aware-configuration/context-aware-configuration.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/context-aware-configuration/context-aware-configuration.html b/documentation/bundles/context-aware-configuration/context-aware-configuration.html index c47bee4..6567033 100644 --- a/documentation/bundles/context-aware-configuration/context-aware-configuration.html +++ b/documentation/bundles/context-aware-configuration/context-aware-configuration.html @@ -74,13 +74,13 @@ Apache Sling Context-Aware Configuration </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h1>About</h1> +<h1><a href="#about" name="about">About</a></h1> <p>These bundles provide a service API that can be used to get context-aware configurations. Context-aware configurations are configurations that are related to a content resource or a resource tree, e.g. a web site or a tenant site.</p> <p>Here is an example how your content structure may look like:</p> <p><img src="context-aware-config-example.png" alt="Configuration example" /></p> <p>The application needs different configuration for different sites, regions and tenants = different contexts. Some parameters may be shared, so inheritance for nested contexts and from global fallback values is supported as well. You have full control which content subtrees are the contexts in your application, the structure above is only an example.</p> <p>Using the Context-Aware Configuration Java API you can get the matching configuration for each content resource without caring where it is stored or how the inheritance works.</p> -<h1>Java API</h1> +<h1><a href="#java-api" name="java-api">Java API</a></h1> <p>To get and use configurations, the Java API must be used. Any using code must not make any assumptions on how the context-aware configurations are searched or stored!</p> <p>The Java API consists of two parts:</p> <ul> @@ -88,53 +88,55 @@ <li>Context-Aware Configurations: 'High-level' API for accessing configuration data (key/value pairs)</li> </ul> <p>In most cases you will use only the 'High-level' API for getting context-aware configurations.</p> -<h2>Context-Aware Resources</h2> +<h2><a href="#context-aware-resources" name="context-aware-resources">Context-Aware Resources</a></h2> <p>The base concept are context-aware resources: for a given content resource, a named configuration resource can be get. The service for getting the configuration resources is called the ConfigurationResourceResolver. This service has two methods:</p> <ul> <li>getting a named configuration resource</li> <li>getting all child resources of a named configuration resource.</li> </ul> <p>For example to get a configuration resource for a content resource at /content/mysite/page1, you would get a reference to the OSGi service <code>org.apache.sling.caconfig.resource.ConfigurationResourceResolver</code> and write:</p> -<pre><code>#!java -Resource contentResource = resourceResolver.getResource("/content/mysite/page1"); +<pre><code><!-- TODO syntax marker (#!java) disabled -->Resource contentResource = resourceResolver.getResource("/content/mysite/page1"); Resource configResource = configurationResourceResolver.getResource(contentResource, "my-bucket", "my-config"); </code></pre> <p>Or if you have several configuration resources of the same type and you need all of them:</p> -<pre><code>#!java -Collection<Resource> configResources = configurationResourceResolver.getResourceCollection(contentResource, "my-bucket", "my-config"); +<pre><code><!-- TODO syntax marker (#!java) disabled -->Collection<Resource> configResources = configurationResourceResolver.getResourceCollection(contentResource, "my-bucket", "my-config"); </code></pre> <p>The ConfigurationResourceResolver has a concept of "buckets" (2nd parameter in the method signatures) that allows to separate different types of configuration resources into different resource hierarchies, so you have a separate "namespaces" for the named configuration resources. For example one bucket for workflow definitions, one bucket for template definitions, one for key/value-pairs.</p> <p>The configuration name (3rd parameter) defines which configuration you are interested in. The name can be a relative path as well (e.g. <code>"sub1/my-config"</code>).</p> -<h2>Context-Aware Configurations</h2> +<h2><a href="#context-aware-configurations" name="context-aware-configurations">Context-Aware Configurations</a></h2> <p>While context-aware resources give you pure resources and your application code can decide what to do with it, the most common use case is some configuration. A configuration is usually described by an annotation class (like Declarative Services does for component configurations). These are typed configuration objects and the context-aware configuration support automatically converts resources into the wanted configuration type.</p> <p>Context-aware configurations are built on top of context-aware resources. The same concept is used: configurations are named and the service to get them is the ConfigurationResolver. You can get a reference to the OSGi service <code>org.apache.sling.caconfig.ConfigurationResolver</code> - it has a single method to get a ConfigurationBuilder. Alternatively you can directly adapt your content resource directly to the ConfigurationBuilder interface and get the configuration:</p> -<pre><code>#!java -Resource contentResource = resourceResolver.getResource("/content/mysite/page1"); +<pre><code><!-- TODO syntax marker (#!java) disabled -->Resource contentResource = resourceResolver.getResource("/content/mysite/page1"); MyConfig config = contentResource.adaptTo(ConfigurationBuilder.class).as(MyConfig.class); </code></pre> <p>Or if you want to get a list of configurations:</p> -<pre><code>#!java -Collection<MyConfig> configs = contentResource.adaptTo(ConfigurationBuilder.class).asCollection(MyConfig.class); +<pre><code><!-- TODO syntax marker (#!java) disabled -->Collection<MyConfig> configs = contentResource.adaptTo(ConfigurationBuilder.class).asCollection(MyConfig.class); </code></pre> <p>The ConfigurationBuilder also supports getting the configurations as ValueMap or by adapting the configuration resources e.g. to a Sling Model. In this case you have to specify a configuration name which is otherwise derived automatically from the annotation class.</p> <p>Internally the ConfigurationResolver used the ConfigurationResourceResolver to get the configuration resources. It uses always the bucket name <code>sling:configs</code>.</p> -<h1>Contexts and configuration references</h1> +<h1><a href="#contexts-and-configuration-references" name="contexts-and-configuration-references">Contexts and configuration references</a></h1> <p>When you use the <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html";>Default Implementation</a> contexts in the content resource hierarchy is defined by setting <code>sling:configRef</code> properties. Each resource that has a <code>sling:configRef</code> property set defines the root resource of a context, the whole subtree is the context. Within the subtree further nested contexts can be defined. The property contains a resource path pointing to a resource below <code>/conf</code>. This is the configuration reference.</p> <p>Example:</p> <p><img src="context-and-config-reference.png" alt="Context and config reference" /></p> <p>If you define nested contexts or use a deeper hierarchy of resourced in <code>/conf</code> the inheritance rules are applied. Additionally it is possible to define default values as fallback if no configuration resource exists yet in <code>/conf</code>. See <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html";>Default Implementation</a> for details.</p> -<h1>Describe configurations via annotation classes</h1> +<h1><a href="#describe-configurations-via-annotation-classes" name="describe-configurations-via-annotation-classes">Describe configurations via annotation classes</a></h1> <p>You need an annotation class for each configuration you want to read via the ConfigurationBuilder. The annotation classes may be provided by the applications/libraries you use, or you can define your own annotation classes for your application.</p> <p>The annotation class may look like this:</p> -<pre><code>#!java +<pre><code><!-- TODO syntax marker (#!java) disabled -->@Configuration(label="My Configuration", description="Describe me") +public @interface MyConfig { + + @Property(label="Parameter #1", description="Describe me") + String param1(); + + @Property(label="Parameter with Default value", description="Describe me") + String paramWithDefault() default "defValue"; + + @Property(label="Integer parameter", description="Describe me") + int intParam(); +} </code></pre> -<p> @Configuration(label="My Configuration", description="Describe me") public @interface MyConfig {</p> -<p> @Property(label="Parameter #1", description="Describe me") String param1();</p> -<p> @Property(label="Parameter with Default value", description="Describe me") String paramWithDefault() default "defValue";</p> -<p> @Property(label="Integer parameter", description="Describe me") int intParam();</p> -<p> }</p> <p>The <code>@Configuration</code> annotation is mandatory. All properties on the <code>@Configuration</code> annotation and the <code>@Property</code> annotations are optional - they provide additional metadata for tooling e.g. configuration editors. </p> <p>By default the annotation class name is used as configuration name, which is also the recommended option. If you want to use an arbitrary configuration name you can specify it via a <code>name</code> property on the <code>@Configuration</code> annotation.</p> <p>You may specify custom properties (via <code>property</code> string array) for the configuration class or each properties. They are not used by the Sling Context-Aware configuration implementation, but may be used by additional tooling to manage the configurations.</p> @@ -142,21 +144,26 @@ Collection<MyConfig> configs = contentResource.adaptTo(ConfigurationBuilde <pre><code>Sling-ContextAware-Configuration-Classes: x.y.z.MyConfig, x.y.z.MyConfig2 </code></pre> <p>To automate this you can use the Context-Aware Configuration bnd plugin (see next chapter). </p> -<h1>Accessing configuration from HTL/Sightly templates</h1> +<h1><a href="#accessing-configuration-from-htl-sightly-templates" name="accessing-configuration-from-htl-sightly-templates">Accessing configuration from HTL/Sightly templates</a></h1> <p>Context-Aware configuration contains a Scripting Binding Values provider with automatically registeres a <code>caconfig</code> variable in your HTL/Sightly scripts to directly access context-aware configurations. It supports both singleton configurations and configuration lists. Please note that configuration lists are only supported when configuration metadata is present (e.g. via an annotation class).</p> <p>Example for accessing a property of a singleton configuration (with a config name <code>x.y.z.ConfigSample</code>):</p> -<p> #!html <dl> <dt>stringParam:</dt> <dd>${caconfig['x.y.z.ConfigSample'].stringParam}</dd> </dl></p> +<pre><code><!-- TODO syntax marker (#!html) disabled --><dl> + <dt>stringParam:</dt> + <dd>${caconfig['x.y.z.ConfigSample'].stringParam}</dd> +</dl> +</code></pre> <p>Example for accessing a property of a configuration list (with a config name <code>x.y.z.ConfigSampleList</code>):</p> -<p> #!html <ul data-sly-list.item="${caconfig['x.y.z.ConfigSampleList']}"> <li>stringParam: ${item.stringParam}</li> </ul></p> +<pre><code><!-- TODO syntax marker (#!html) disabled --><ul data-sly-list.item="${caconfig['x.y.z.ConfigSampleList']}"> + <li>stringParam: ${item.stringParam}</li> +</ul> +</code></pre> <p>If you want to access nested configurations you have to use a slash "/" as separator in the property name. Example:</p> -<pre><code>#!html -${caconfig['x.y.z.ConfigSample']['nestedConfig/stringParam']} +<pre><code><!-- TODO syntax marker (#!html) disabled -->${caconfig['x.y.z.ConfigSample']['nestedConfig/stringParam']} </code></pre> -<h1>Context-Aware Configuration bnd plugin</h1> +<h1><a href="#context-aware-configuration-bnd-plugin" name="context-aware-configuration-bnd-plugin">Context-Aware Configuration bnd plugin</a></h1> <p>A <a href="http://bnd.bndtools.org/";>bnd</a> plugin is provided that scans the classpath of a bundle Maven project at build time and automatically generates a <code>Sling-ContextAware-Configuration-Classes</code> bundle header for all annotation classes annotated with <code>@Configuration</code>. It can be used by both <a href="http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html";>maven-bundle-plugin</a> and <a href="https://github.com/bndtools/bnd/tree/master/maven";>bnd-maven-plugin</a>, as both use the bnd library internally.</p> <p>Example configuration:</p> -<pre><code>#!xml -<plugin> +<pre><code><!-- TODO syntax marker (#!xml) disabled --><plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <extensions>true</extensions> @@ -175,11 +182,10 @@ ${caconfig['x.y.z.ConfigSample']['nestedConfig/stringParam']} </dependencies> </plugin> </code></pre> -<h1>Unit Tests with Context-Aware Configuration</h1> +<h1><a href="#unit-tests-with-context-aware-configuration" name="unit-tests-with-context-aware-configuration">Unit Tests with Context-Aware Configuration</a></h1> <p>When your code depends on Sling Context-Aware Configuration and you want to write Sling Mocks-based unit tests running against the Context-Aware configuration implementation you have to register the proper OSGi services to use them. To make this easier, a "Apache Sling Context-Aware Configuration Mock Plugin" is provided which does this job for you.</p> <p>Example for setting up the unit test context rule:</p> -<pre><code>#!java -import static org.apache.sling.testing.mock.caconfig.ContextPlugins.CACONFIG; +<pre><code><!-- TODO syntax marker (#!java) disabled -->import static org.apache.sling.testing.mock.caconfig.ContextPlugins.CACONFIG; public class MyTest { @@ -196,22 +202,22 @@ public class MyTest { <p>In you project define a test dependency (additionally the sling-mock dependency is required):</p> <p> #!xml <dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.testing.caconfig-mock-plugin</artifactId> <scope>test</scope> </dependency></p> <p>Full example: <a href="https://github.com/apache/sling/blob/trunk/testing/mocks/caconfig-mock-plugin/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java";>Apache Sling Context-Aware Configuration Mock Plugin Test</a></p> -<h1>Customizing the configuration lookup</h1> +<h1><a href="#customizing-the-configuration-lookup" name="customizing-the-configuration-lookup">Customizing the configuration lookup</a></h1> <p>The Context-Aware Configuration implementation provides a set of Service Provider Interfaces (SPI) that allows you to overlay, enhance or replace the default implementation and adapt it to your needs.</p> <p>See <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html";>SPI</a> for details.</p> <p>You can also override specific context-aware configuration within an instance - see <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html";>Override</a> for details.</p> -<h1>Web Console plugins</h1> +<h1><a href="#web-console-plugins" name="web-console-plugins">Web Console plugins</a></h1> <p>The Context-Aware Configuration implementation provides two extension to the Felix Web Console:</p> <ul> <li>A plugin "Sling / Context-Aware Configuration" that allows to test configuration resolution and prints outs all metadata. This is helpful debugging the resolution and collection and property inheritance. For each resource and property value the the real source resource path is listed.</li> <li>A inventory printer "Sling Context-Aware Configuration" which lists all SPI implementations that are deployed, and additionally prints out all configuration metadata and override strings</li> </ul> <p>To use the web console plugin you need to configure a "Service User" mapping for the bundle <code>org.apache.sling.caconfig.impl</code> to a system user which has read access to all context and configuration resources. By default this should be <code>/content</code>, <code>/conf</code>, <code>/apps/conf</code> and <code>/libs/conf</code>.</p> -<h1>Management API</h1> +<h1><a href="#management-api" name="management-api">Management API</a></h1> <p>The Context-Aware Configuration Implementation Bundle provides a Management API which allows to read and write configuration data. It supports only Context-Aware configurations, not context-aware resources. It should not be used directly in applications, but is intended to provide an API for editor GUIs and other tools which allow to manage configurations.</p> <p>The main entry point is the OSGi service <code>org.apache.sling.caconfig.management.ConfigurationManager</code>. It allows to get, write or delete singleton configurations and configuration lists. Configuration data is returned using <code>ConfigurationData</code> and <code>ConfigurationCollectionData</code> objects which also provide access to additional metadata about the resolving process and inheritance/override status of each property. Internally the configuration manager uses the <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html";>SPI</a> implementation to resolve and write the configuration data.</p> <p>Whenever configuration data is read or written from the configuration resources a filtering of property names is applied to make sure "system properties" like <code>jcr:primaryType</code> or <code>jcr:created</code> are not returned as part of the configuration data. A list of regular expressions for this filtering can be configured via the "Apache Sling Context-Aware Configuration Management Settings" OSGi configuration. The configuration is accessible to custom persistence implementations via the <code>org.apache.sling.caconfig.management.ConfigurationManagementSettings</code> OSGi service. By default all properties in the <code>jcr:</code> namespace are filtered out.</p> -<h1>References</h1> +<h1><a href="#references" name="references">References</a></h1> <ul> <li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html";>Context-Aware Configuration - Default Implementation</a></li> <li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html";>Context-Aware Configuration - SPI</a></li>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/datasource-providers.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/datasource-providers.html b/documentation/bundles/datasource-providers.html index 9f520f6..a85a831 100644 --- a/documentation/bundles/datasource-providers.html +++ b/documentation/bundles/datasource-providers.html @@ -75,7 +75,7 @@ </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>DataSource provider bundle supports creation of <code>DataSource</code> instance and registering them with the OSGi service registry. Application using the DataSource just obtains it from OSGi while an administrator can configure the DataSource via Felix WebConsole configuration UI.</p> <p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Pooled Connection DataSource Provider</h2> +<h2><a href="#pooled-connection-datasource-provider" name="pooled-connection-datasource-provider">Pooled Connection DataSource Provider</a></h2> <p>This bundle enables creating and configuring JDBC DataSource in OSGi environment based on OSGi configuration. It uses <a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html";>Tomcat JDBC Pool</a> as the JDBC Connection Pool provider.</p> <ol> <li>Supports configuring the DataSource based on OSGi config with rich metatype</li> @@ -83,13 +83,13 @@ <li>Exposes the DataSource stats as JMX MBean</li> <li>Supports updating of DataSource connection pool properties at runtime without restart</li> </ol> -<h3>Driver Loading</h3> +<h3><a href="#driver-loading" name="driver-loading">Driver Loading</a></h3> <p>Loading of JDBC driver is tricky on OSGi env. Mostly one has to attach the Driver bundle as a fragment bundle to the code which creates the JDBC Connection.</p> <p>With JDBC 4 onwards the Driver class can be loaded via Java SE Service Provider mechanism (SPM) JDBC 4.0 drivers must include the file META-INF/services/java.sql.Driver. This file contains the name of the JDBC driver's implementation of java.sql.Driver. For example, to load the JDBC driver to connect to a Apache Derby database, the META-INF/services/java.sql.Driver file would contain the following entry:</p> <pre><code>org.apache.derby.jdbc.EmbeddedDriver </code></pre> <p>Sling DataSource Provider bundles maintains a <code>DriverRegistry</code> which contains mapping of Driver bundle to Driver class supported by it. With this feature there is no need to wrap the Driver bundle as fragment to DataSource provider bundle</p> -<h3>Configuration</h3> +<h3><a href="#configuration" name="configuration">Configuration</a></h3> <ol> <li>Install the current bundle</li> <li>Install the JDBC Driver bundle</li> @@ -98,7 +98,7 @@ <p>If Felix WebConsole is used then you can configure it via Configuration UI at http://localhost:8080/system/console/configMgr/org.apache.sling.datasource.DataSourceFactory</p> <p><img src="/documentation/development/sling-datasource-config.png" alt="Web Console Config" /></p> <p>Using the config ui above one can directly configure most of the properties as explained in <a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html";>Tomcat Docs</a></p> -<h3>Convert Driver jars to Bundle</h3> +<h3><a href="#convert-driver-jars-to-bundle" name="convert-driver-jars-to-bundle">Convert Driver jars to Bundle</a></h3> <p>Most of the JDBC driver jars have the required OSGi headers and can be directly deployed to OSGi container as bundles. However some of the drivers e.g. Postgres are not having such headers and hence need to be converted to OSGi bundles. For them we can use the <a href="http://bnd.bndtools.org/chapters/390-wrapping.html";>Bnd Wrap</a> command.</p> <p>For example to convert the Postgres driver jar follow the steps below</p> <pre><code>$ wget https://github.com/bndtools/bnd/releases/download/2.3.0.REL/biz.aQute.bnd-2.3.0.jar -O bnd.jar @@ -118,7 +118,7 @@ $ java -jar bnd.jar bnd.bnd <li>Execute the bnd command</li> <li>Resulting bundle is present in <code>org.postgresql-9.3.1101.jar</code></li> </ol> -<h2>JNDI DataSource</h2> +<h2><a href="#jndi-datasource" name="jndi-datasource">JNDI DataSource</a></h2> <p>While running in Application Server the DataSource instance might be managed by app server and registered with JNDI. To enable lookup of DataSource instance from JNDI you can configure <code>JNDIDataSourceFactory</code></p> <ol> <li>Configure the DataSource from OSGi config for PID <code>org.apache.sling.datasource.JNDIDataSourceFactory</code></li> @@ -126,11 +126,10 @@ $ java -jar bnd.jar bnd.bnd </ol> <p>If Felix WebConsole is used then you can configure it via Configuration UI at http://localhost:8080/system/console/configMgr/org.apache.sling.datasource.JNDIDataSourceFactory</p> <p>Once configured <code>JNDIDataSourceFactory</code> would lookup the DataSource instance and register it with OSGi ServiceRegistry</p> -<h2>Usage</h2> +<h2><a href="#usage" name="usage">Usage</a></h2> <p>Once the required configuration is done the <code>DataSource</code> would be registered as part of the OSGi Service Registry The service is registered with service property <code>datasource.name</code> whose value is the name of datasource provided in OSGi config.</p> <p>Following snippet demonstrates accessing the DataSource named <code>foo</code> via DS annotation</p> -<pre><code>::java -import javax.sql.DataSource; +<pre><code><!-- TODO syntax marker (::java) disabled -->import javax.sql.DataSource; import org.apache.felix.scr.annotations.Reference; public class DSExample { @@ -139,10 +138,9 @@ public class DSExample { private DataSource dataSource; } </code></pre> -<h2>Installation</h2> +<h2><a href="#installation" name="installation">Installation</a></h2> <p>Download the bundle from <a href="http://sling.apache.org/downloads.cgi";>here</a> or use following Maven dependency</p> -<pre><code>::xml -<dependency> +<pre><code><!-- TODO syntax marker (::xml) disabled --><dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.datasource</artifactId> <version>1.0.0</version> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/discovery-api-and-impl.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/discovery-api-and-impl.html b/documentation/bundles/discovery-api-and-impl.html index 714f3e3..84324f6 100644 --- a/documentation/bundles/discovery-api-and-impl.html +++ b/documentation/bundles/discovery-api-and-impl.html @@ -76,9 +76,9 @@ <p>The <code>discovery-api</code> bundle introduces an abstraction for such scenarios called <code>topology</code>. It provides access to the current topology, allows to be informed of any changes in the topology (such as joining or leaving instances) and contains a simple property exchange mechanism, e.g. to allow building communication services on top of it.</p> <p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Discovery Entities</h2> +<h2><a href="#discovery-entities" name="discovery-entities">Discovery Entities</a></h2> <p>The Discovery API defines the following entities</p> -<h3>Instance, InstanceDescription</h3> +<h3><a href="#instance-instancedescription" name="instance-instancedescription">Instance, InstanceDescription</a></h3> <p>A Sling instance running in one VM is represented in the discovery API by an <code>InstanceDescription</code>:</p> <ul> <li>it represents one Sling instance</li> @@ -86,7 +86,7 @@ <li>it has a flag that marks if it is leader in a cluster (more details below)</li> <li>plus it has properties (which can be provided via <code>PropertyProviders</code>)</li> </ul> -<h3>Cluster, ClusterView</h3> +<h3><a href="#cluster-clusterview" name="cluster-clusterview">Cluster, ClusterView</a></h3> <p>Multiple instances that are connected to the same underlying repository are commonly referred to as a 'Cluster'. The reasoning behind this terminology being that they access the same data and can thus deliver or modify the same data.</p> <p>In the discovery API this cluster concept is represented via a <code>ClusterView</code> object. A 'view' because it is a momentary snapshot of the cluster and only contains instances that are currently alive. It's features are:</p> <ul> @@ -94,17 +94,17 @@ <li>it has an ordered, stable list of instances that are part of it, thus currently alive. the relative order of instances in this list is stable, meaning that it only stays or moves up one position if an instance listed 'above' crashes - a newly started instance will always be added at the end of this list.</li> <li>plus it has a unique id that is persistent across restarts</li> </ul> -<h3>Topology, TopologyView</h3> +<h3><a href="#topology-topologyview" name="topology-topologyview">Topology, TopologyView</a></h3> <p>The topology - or more precisely the <code>TopologyView</code> - represents a snapshot (<code>view</code>) of a number of loosely coupled Sling instances (<code>InstanceDescription</code>) and clusters (<code>ClusterView</code>) of a particular deployment. A cluster can consist of one or more instances. Each instance is always part of a cluster (even if the cluster consists of only one instance). The features are:</p> <ul> <li>only one: it has a list of clusters</li> </ul> <p>There are no further assumption made on the structure of a topology.</p> <p>If different clusters in the topology should represent different 'types of clusters' (eg a publish or an author cluster), then that is not explicitly handled by the discovery API. Instead, applications can define properties on each instance that model such cluster types or other aspects.</p> -<h2>Cluster Leader and Instance Ordering</h2> +<h2><a href="#cluster-leader-and-instance-ordering" name="cluster-leader-and-instance-ordering">Cluster Leader and Instance Ordering</a></h2> <p>As mentioned the discovery API introduces support for a <code>cluster leader</code>: within each cluster, the API guarantees that one and only one instance is leader at any time. That leader is guaranteed to be <code>stable</code>, ie as long as it stays alive and is visible by other instances of the same cluster, it will stay leader. As soon as it leaves the cluster (or the corresponding implementation bundle is deactivated), another instance in that cluster is elected leader. The leader can be used to deal with work that must be guaranteed to only execute on one (but any) instance in the cluster.</p> <p>Additionally each cluster (<code>ClusterView</code>) orders its instances in a stable list: each newly joined instances is added at the end of the list and retains its order in the list as long as it doesn't leave the cluster. This can be used to distribute "singleton" work amongst the cluster to more than just the leader. </p> -<h2>Topology Changes</h2> +<h2><a href="#topology-changes" name="topology-changes">Topology Changes</a></h2> <p>The <code>DiscoveryService</code> provides access to the currently valid <code>TopologyView</code>. Additionally, applications can register a <code>TopologyEventListener</code> and thus be informed about any changes in the topology. Whenever the discovery service detects that an instance is no longer responding or has newly joined, or a new leader has been elected, it sends a <code>TOPOLOGY_CHANGING</code> event, starts settling the change within the topology (i.e. making sure everybody else in the topology agrees with the change) and finally sends a <code>TOPOLOGY_CHANGED</code> event with the new topology.</p> <p>Additionally, when "only" properties have changed, a <code>PROPERTIES_CHANGED</code> event is sent.</p> <p>Note that the detection of topology (or properties) changes will incur a delay which is implementation dependent.</p> @@ -124,7 +124,7 @@ public class MyTopologyEventListener implements TopologyEventListener { } </code></pre> -<h2>Properties</h2> +<h2><a href="#properties" name="properties">Properties</a></h2> <p>The discovery API not only lists all clusters and instances that are part of a topology but also provides a simple mechanism for announcing properties of each instance to the topology, via the <code>PropertyProvider</code> service interface.</p> <p>Typical use cases for this are announcements of endpoint URLs or ports such that applications can communicate to other instances in the topology.</p> <p>Note that the properties mechanism is not meant be used as a messaging tool: both from an API point of view and the implementation of it are not optimized for frequent changes and its use for messaging is discouraged. It is only meant to be used to announce configuration information for accessing proper messaging services.</p> @@ -150,17 +150,17 @@ public class SamplePropertyProvider implements PropertyProvider { } } </code></pre> -<h2>Deployment and configuration</h2> +<h2><a href="#deployment-and-configuration" name="deployment-and-configuration">Deployment and configuration</a></h2> <p>The discovery API makes no assumptions as to how the instances and clusters discover each other. This is entirely up to the implementations. Some might choose automatic discovery within a LAN using IP multicast, others might choose explicit configuration via a central service etc.</p> -<h2>discovery.impl: Resource-based, OOTB Implementation</h2> +<h2><a href="#discovery-impl-resource-based-ootb-implementation" name="discovery-impl-resource-based-ootb-implementation">discovery.impl: Resource-based, OOTB Implementation</a></h2> <p>The <code>discovery.impl</code> bundle is a resource-based, out of the box implementation of the <code>discovery.api</code> using standard Sling. </p> <p>The discovery within a cluster is done by writing heartbeat information into the (common) repository (there's no other form of communication within a cluster). The establishment of a clusterview is done by analyzing these heartbeats, initiating a voting within the cluster (such that each instance can agree that it sees the same number of instances) and by concluding the voting by promoting it as the new "established" view.</p> <p>The discovery of instances and clusters outside the local cluster requires explicit configuration of what is termed 'topology connectors', which are HTTP PUTs (see below).</p> -<h3>Location in Repository</h3> +<h3><a href="#location-in-repository" name="location-in-repository">Location in Repository</a></h3> <p>Administrative note: All the information about the topology is stored at the following location in the repository:</p> <pre><code>/var/discovery/impl </code></pre> -<h4>/var/discovery/impl/clusterInstances/<slingId></h4> +<h4><a href="#var-discovery-impl-clusterinstances-lt-slingid-gt-" name="var-discovery-impl-clusterinstances-lt-slingid-gt-">/var/discovery/impl/clusterInstances/<slingId></a></h4> <p>Each instance has its own node under <code>clusterInstances/</code> where it stores:</p> <ul> <li><code>lastHeartbeat</code>: property, which marks the instance as alive for another <code>heartbeatTimeout</code></li> @@ -173,19 +173,19 @@ public class SamplePropertyProvider implements PropertyProvider { <li><code>announcements</code>: this contains announcements of topology connector peers (also see below). An announcement is a json-encoded representation of the sub-tree that the connector peer is aware of and is thereby announcing to this instance. Announcements are sent in both directions of a topology connector. Discovery.impl takes care of filtering out duplicate instances should the structure of topology connectors, and thus these announcements overlap (which is legal)</li> <li><code>properties</code>: contains all properties as specified by registered <code>PropertyProvider</code></li> </ul> -<h4>/var/discovery/impl/establishedView</h4> +<h4><a href="#var-discovery-impl-establishedview" name="var-discovery-impl-establishedview">/var/discovery/impl/establishedView</a></h4> <p>This contains the currently valid, agreed/voted upon cluster view that lists all alive instances:</p> <ul> <li>the name of the node directly under <code>establishedView</code> is a unique id of the current incarnation of the cluster view - thus changes whenever an instance joins or leaves or there is a new voting for another reason. ** <code>clusterId</code> : name of the persistent identifier of this cluster. As this is propagated from cluster view to cluster view it stays unchanged forever. ** <code>leaderElectionId</code>: the leaderElectionId that was winning, ie that was lowest ** <code>leaderId</code>: the slingId of the instance that is leader of this cluster view</li> <li><code>members</code>: just an intermediate node containing all alive instances as child nodes</li> <li>child node of <code>members</code>: each child represents a particular alive node (with the name being the slingId) and contains the following properties: ** <code>leaderElectionId</code>: the id that will be used to determine the leader - this value is copied from the corresponding <code>/var/discovery/impl/clusterInstances/<slingId></code> ** <code>initiator</code>: this marks the instance that originally created this voting ** <code>vote</code>: represents this instance's vote, which is true for a voting that got promoted to established view</li> </ul> -<h4>/var/discovery/impl/ongoingVotings</h4> +<h4><a href="#var-discovery-impl-ongoingvotings" name="var-discovery-impl-ongoingvotings">/var/discovery/impl/ongoingVotings</a></h4> <p>This area is used for voting. Each instance can initiate a voting when it realizes that the live instances - denominated by those instances that have a not-yet-timed-out heartbeat property - does not match with the <code>establishedView</code>.</p> <p>Once a voting gets a yes vote by all instances it is promoted (moved) under <code>establishedView</code> by the initiating instance. Each establishedView was once a voting, thus the structure is the same as described above.</p> -<h4>/var/discovery/impl/previousView</h4> +<h4><a href="#var-discovery-impl-previousview" name="var-discovery-impl-previousview">/var/discovery/impl/previousView</a></h4> <p>The instance that promotes its winning voting to <code>establishedView</code> first moves what was there before under <code>previousView</code>. This is purely for debugging and not used anywhere, it just represents a persistet history of previous views of length 1.</p> -<h3>Heartbeats, Voting and Intra-Cluster Discovery</h3> +<h3><a href="#heartbeats-voting-and-intra-cluster-discovery" name="heartbeats-voting-and-intra-cluster-discovery">Heartbeats, Voting and Intra-Cluster Discovery</a></h3> <p><code>discovery.impl</code> uses the fact that all instance of a cluster are connected to the same repository as the basis for discovering those instances. It does so by using a heartbeat and voting mechanism:</p> <ul> <li>each instance periodically stores a 'heartbeat' into the repository in a well-known location. This is done by setting a corresponding <code>lastHeartbeat</code> property to the current timestamp</li> @@ -200,7 +200,7 @@ public class SamplePropertyProvider implements PropertyProvider { <li>when a voting receives a 'yes' from all instances that it enlists it is considered as 'winning' and is promoted to be the new, valid view from now on.</li> <li>a promoted view is stored in <code>/var/discovery/impl/establishedView</code> and any change therein is passed on in a TopologyEvent to all registered listeners.</li> </ul> -<h3>pseudo-network partitioning aka split-brain</h3> +<h3><a href="#pseudo-network-partitioning-aka-split-brain" name="pseudo-network-partitioning-aka-split-brain">pseudo-network partitioning aka split-brain</a></h3> <p><code>discovery.impl</code> requires the, eventually consistent, underlying repository to propagate changes within reasonable time: in less than the configured heartbeat timeout. If heartbeats for some reason are not becoming visible by peers in the cluster within that time, <code>discovery.impl</code> will consider that peer instance as dead. At which point it will first send a TOPOLOGY_CHANGING event to all listeners to make them aware that something is changing in the topology, and then start a new voting. Once the voting concludes a TOPOLOGY_CHANGED event will follow.</p> <p>Given the voting is happening through the repository as well, one could imagine a situation where the repository delays can cause a topology to be "pseudo partitioned" into two or more parts, each one agreeing on a set of instances in that sub-cluster (one requirement for such a scenario being that the delays must be asymmetric, ie changes from a subset of instances propagate slow, while the remaining changes propagate fast - ie. two different sets of delays in the cluster). Such a situation would only last as long as the repository delays are large (larger than the heartbeat timeouts). Exact cases where the repository experiences large delays depend of course on the repository configuration and deployment details, known cases include for example long running queries, large set of changes, large set of commits and long-running session.saves.</p> <p>The following is an illustration of the impact of large cluster delays:</p> @@ -213,14 +213,14 @@ public class SamplePropertyProvider implements PropertyProvider { </ul> <p>All of the above greatly reduce the likelyhood of pseudo-network partitioning with <code>discovery.impl</code>, however, as also described in SLING-4640, there is still a small time-window in which it cannot be ruled out entirely. The successor of discovery.impl, the <code>discovery.oak</code> bundle, addresses these concerns to avoid pseudo-network partitioning alltogether.</p> <p>In the context of <code>discovery.impl</code> it is therefore paramount that the underlying repository is monitored and optimized such that the delays are well under control and do not exceed the configured heartbeat timeout.</p> -<h3>Topology Connectors for Cross-Cluster Discovery</h3> +<h3><a href="#topology-connectors-for-cross-cluster-discovery" name="topology-connectors-for-cross-cluster-discovery">Topology Connectors for Cross-Cluster Discovery</a></h3> <p>From a discovery API's point of view a cluster consists of all instances that are connected to the same repository. The above described built-in mechanism of storing a lastHeartbeat property into the (shared) repository, of voting on changes and creating an explicit establishedView results in automatic discovery within a cluster. There is therefore no further configuration needed for discovering instances in the same cluster.</p> <p>However, for discovering multiple clusters such an automatic discovery is not possible and the clusters need to be explicitly configured using (cross-cluster) topology connectors:</p> <p>A topology connector is a periodically issued HTTP PUT that announces the part of the topology known to the sending instance to the receiving instance and vica-verca the receiving instance announces its part of the topology to the sender in the response of the very same HTTP PUT. This way whatever other clusters are connected to sender or receiver will be made known to each other. Such a 'topology announcement' will be valid either until the same sender sends the announcement again (which it does periodically) - or until it times out (configurable). A topology connector is by definition always between clusters, never within the same cluster. Topology connectors can be structured in an arbitrary way (chain, star, tree, etc) with the only important point to note here that since changes in the topology propagate through these topology connectors they have a certain delay (namely the configured heartbeatInterval per hop).</p> <p>Topology connectors are configured at <a href="http://localhost:8888/system/console/configMgr/org.apache.sling.discovery.impl.Config";>/system/console/configMgr/org.apache.sling.discovery.impl.Config</a>. They use the same interval and timeout as the repository heartbeats (heartbeatInterval and heartbeatTimeout).</p> -<h3>WebConsole</h3> +<h3><a href="#webconsole" name="webconsole">WebConsole</a></h3> <p>A Felix WebConsole plugin at <a href="http://localhost:8888/system/console/topology";>/system/console/topology</a> provides a (read-only) overview of the topology.</p> -<h3>Configuration</h3> +<h3><a href="#configuration" name="configuration">Configuration</a></h3> <p>The following properties can be configured (at <a href="http://localhost:8888/system/console/configMgr/org.apache.sling.discovery.impl.Config";>/system/console/configMgr/org.apache.sling.discovery.impl.Config</a>):</p> <ul> <li> @@ -244,12 +244,12 @@ public class SamplePropertyProvider implements PropertyProvider { <li> <p>hmacSharedKeyTTL: The key used for the signatures is derived from the shared key. Each derived key has a lifetime before the next key is generated. This parameter sets the lifetime of each key in ms. The default is 4h. Messages sent using old keys will remain valid for 2x the TTL, after which time the message will be ignored.</p></li> </ul> -<h2>discovery.oak: Oak-based, OOTB-implementation</h2> +<h2><a href="#discovery-oak-oak-based-ootb-implementation" name="discovery-oak-oak-based-ootb-implementation">discovery.oak: Oak-based, OOTB-implementation</a></h2> <p>When running discovery.impl ontop of an eventually consistent repository (such as documentMK of oak), the heartbeat mechanism becomes unreliable. The eventual-ness of the repository has an inherent problem in that it doesn't guarantee by when a change initiated from instance A is visible by instance B. And when there are no hard guarantees, it becomes impossible to choose a <code>heartbeatTimeout</code> that works for all eventualities.</p> <p>Therefore it becomes necessary to be able to store heartbeats in a (low-level) location that provides higher consistency (than eventualness). Such a 'low-level location' is the DocumentStore of oak (which is an internal API of the DocumentNodeStore). Turns out that the DocumentNodeStore already has a heartbeat-like concept called leases. Those can be re-used for discovery to fulfill the same aspect as heartbeats do: indicate alive instances. This can further be combined with an explicit materialization of a "cluster view" in the DocumentStore so that all instances agree and refer to the same view without the actual need for voting (this is possible since the DocumentStore allows to do conditional updates).</p> -<h3>Jackrabbit Oak's discovery-lite</h3> +<h3><a href="#jackrabbit-oak-s-discovery-lite" name="jackrabbit-oak-s-discovery-lite">Jackrabbit Oak's discovery-lite</a></h3> <p>All of the above mentioned features have been implemented in so-called 'discovery-lite': Discovery-lite is a simplified version of discovery on the oak level. Other than the discovery API it only provides one thing, and that's the clusterview-json:</p> -<h4>'oak.discoverylite.clusterview'</h4> +<h4><a href="#oak-discoverylite-clusterview-" name="oak-discoverylite-clusterview-">'oak.discoverylite.clusterview'</a></h4> <p>The discovery-lite descriptor <code>oak.discoverylite.clusterview</code> is a shrink-wrapped json-formatted object representing the current state of the cluster. It contains the following:</p> <ul> <li><code>active</code>: a list of active nodes in the documentNodeStore cluster</li> @@ -260,20 +260,20 @@ public class SamplePropertyProvider implements PropertyProvider { <li><code>seq</code>: a sequence number that is incremented upon each change in this descriptor (to be able to identify a change even if the other values are unchanged) and shared amongst all instances in the cluster, ie all instances see the same sequence number. This number can thus be used by upper layers to identify this particular incarnation of clusterview.</li> <li><code>final</code>: when this flag is <code>false</code> it indicates that the sequence number has changed (as well as eg <code>active</code> and <code>inactive</code>), but that the local instance has not yet fully processed this changed on a low-level. I.e. it marks that the local instance has not yet read the entire back-log of another, deactivating instance. Thus when <code>final==false</code>, the upper layers should wait until <code>final==true</code>, at which point they know oak has finished processing an instance crashing/shutting down.</li> </ul> -<h4>Accessing discovery-lite</h4> +<h4><a href="#accessing-discovery-lite" name="accessing-discovery-lite">Accessing discovery-lite</a></h4> <p>The <code>oak.discoverylite.clusterview</code> descriptor is exposed as a JCR repository descriptor and can be accessed like so:</p> <pre><code>getRepository().getDescriptor("oak.discoverylite.clusterview") </code></pre> <p>which will return the json-formatted clusterview as described above.</p> <p>Note however, that this API is not meant to be a public, stable API and changes will be done without prior notice. It is merely an internal information exposed by oak and not standardized nor guaranteed to remain supported or unchanged!</p> -<h3>Sling's discovery.oak</h3> +<h3><a href="#sling-s-discovery-oak" name="sling-s-discovery-oak">Sling's discovery.oak</a></h3> <p>discovery.oak is a implementation of the discovery API that now makes use of this new discovery-lite descriptor in oak. It basically delegates the detection of the instances in the local cluster to discovery-lite. To do so, it periodically reads this descriptor (which is designed to be read at a high-frequency without problems) and triggers <code>TopologyEvents</code> when this descriptor changes.</p> <p>The advantage of using discovery-lite (which uses oak leases) instead of writing heartbeats into the repository is that discovery.oak thus becomes independent of the speed/latency that the repository can produce under high load. The discovery-lite should be entirley resilient to high load, thus is discovery.oak.</p> <p>Additionally, it reuses functionality from discovery.impl, such as the way properties (from <code>PropertyProviders</code>) or cross-cluster topology announcements (via topology connectors) are handled.</p> <p>In order to do this, the discovery.impl bundle has been refactored as follows:</p> -<h4>discovery.commons</h4> +<h4><a href="#discovery-commons" name="discovery-commons">discovery.commons</a></h4> <p>This is a bundle usable by any implementation of discovery and contains very basic, implementation-independent functionality</p> -<h4>discovery.base</h4> +<h4><a href="#discovery-base" name="discovery-base">discovery.base</a></h4> <p>This is the base bundle solely used by discovery.impl and discovery.oak and contains exactly the mentioned properties and announcement handling.</p></section></div></div> <div class="footer"> <div class="trademarkFooter"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/dynamic-includes.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/dynamic-includes.html b/documentation/bundles/dynamic-includes.html index df3dd10..06486f4 100644 --- a/documentation/bundles/dynamic-includes.html +++ b/documentation/bundles/dynamic-includes.html @@ -73,7 +73,7 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » </div> <h1> Apache Sling Dynamic Include </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>Notice: 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.</p> -<h1>Sling Dynamic Include (org.apache.sling.dynamic-include)</h1> +<h1><a href="#sling-dynamic-include-org-apache-sling-dynamic-include-" name="sling-dynamic-include-org-apache-sling-dynamic-include-">Sling Dynamic Include (org.apache.sling.dynamic-include)</a></h1> <p>For now the Sling Dynamic Include documentation can be found <a href="https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/sling-dynamic-include/README.md";>in the Sling codebase</a> or <a href="https://github.com/apache/sling/tree/trunk/contrib/extensions/sling-dynamic-include";>on our GitHub mirror</a> if that's in sync.</p></section></div></div> <div class="footer"> <div class="trademarkFooter"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/file-installer-provider.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/file-installer-provider.html b/documentation/bundles/file-installer-provider.html index b0714b9..0766c45 100644 --- a/documentation/bundles/file-installer-provider.html +++ b/documentation/bundles/file-installer-provider.html @@ -73,7 +73,7 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » </div> <h1> File Installer Provider </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>The file installer provider scans configured directories and provides the found artifacts (files) to the <a href="/documentation/bundles/osgi-installer.html">OSGI installer</a>. The functionality is very similar to Apache Felix FileInstall, with the major difference that this service implements just the task of scanning a file directory. All the management logic is implemented in the OSGi installer and support of various artifact types like bundles, configurations or custom formats is implemented by plugins for the OSGi installer.</p> -<h2>Setup</h2> +<h2><a href="#setup" name="setup">Setup</a></h2> <p>The file installer can be configured with these framework (system) properties:</p> <table> <thead> @@ -101,17 +101,17 @@ </tr> </tbody> </table> -<h2>Bundles</h2> +<h2><a href="#bundles" name="bundles">Bundles</a></h2> <p>Bundles are supported by the OSGi installer. If a bundle jar is added to a scanned directory, this bundle is installed. If the file is updated/changed, the bundle is updated. If the file is removed, the bundle gets removed. Of course, these are the simple rules. The actual action depends by the overall state of the system and is controlled by the OSGi installer. For example if already the same bundle with a higher version is installed, when a bundle is dropped into the install folder, the OSGi installer will perform no operation.</p> <p>Start levels are supported as well by creating a directory with the name of the start level within the scan directory and putting the bundles within this directory. For example, if the <code>install</code> folder is scanned, the bundle <code>install/3/mybundle.jar</code> will be installed with start level 3. Without such a directory the default start level is used.</p> -<h2>Configurations</h2> +<h2><a href="#configurations" name="configurations">Configurations</a></h2> <p>Configurations are handled by the <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>. The different formats are described there.</p> -<h2>Custom Artifacts</h2> +<h2><a href="#custom-artifacts" name="custom-artifacts">Custom Artifacts</a></h2> <p>Custom artifacts are handled by the OSGi installer depending on the installed plugins. Have a look at the OSGi installer and its plugins for more information.</p> -<h2>Runmode Support</h2> +<h2><a href="#runmode-support" name="runmode-support">Runmode Support</a></h2> <p>The file installer supports run modes for installing artifacts (added with <a href="https://issues.apache.org/jira/browse/SLING-4478";>SLING-4478</a>). Within the scanned directory, a folder prefixed with "install." and followed by one or more run modes (separated by ".") will only be considered if all the respective run modes are active. For example artifacts below a folder named <code>install.a1.dev</code> are only taken into account if the run modes <code>a1</code> and <code>dev</code> are both active. </p> <p>You can even combine start level and run mode support. Just pay attention that the run mode foldername must be set on a direct child folder of <code>sling.fileinstall.dir</code> while the start level must be set directly on the parent folder of the artifact you want to install. E.g. <code><sling.fileinstall.dir>/install.a1.dev/3/mybundle.jar</code> will only be considered if both run modes <code>a1</code> and <code>dev</code> are set. If this is the case then the according artifact will be installed in start level 3.</p> -<h1>Project Info</h1> +<h1><a href="#project-info" name="project-info">Project Info</a></h1> <ul> <li>File installer provider (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/providers/file";>org.apache.sling.installer.provider.file</a>)</li> </ul></section></div></div> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/internationalization-support-i18n.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/internationalization-support-i18n.html b/documentation/bundles/internationalization-support-i18n.html index ff616f6..5db2336 100644 --- a/documentation/bundles/internationalization-support-i18n.html +++ b/documentation/bundles/internationalization-support-i18n.html @@ -108,7 +108,7 @@ <li><code>sling:message</code> -- The <code>sling:message</code> property represents the resource for the key.</li> </ul> <p>It is only required that the message nodes are located below <code>mix:language</code> nodes. Such structures may also be scattered in the repository to allow storing message resources next to where they are most likely used, such as request scripts.</p> -<h5>Sample Resources</h5> +<h5><a href="#sample-resources" name="sample-resources">Sample Resources</a></h5> <p>Content for dictionaries in this format might look like this:</p> <pre><code> /libs/languages +-- English (nt:folder, mix:language) @@ -141,9 +141,9 @@ +-- sling:message = "Ein Anwendungstext" </code></pre> <p>This content defines two languages <em>en</em> and <em>de</em> with three messages <em>msg001</em>, <em>msg002</em> and <em>msgXXX</em> each. The names of the respective resources have no significance (in case the <code>sling:key</code> is set).</p> -<h4>JSON-file based</h4> +<h4><a href="#json-file-based" name="json-file-based">JSON-file based</a></h4> <p>Since Version 2.4.2 the i18n bundle supports dictionaries in JSON-format (<a href="https://issues.apache.org/jira/browse/SLING-4543";>SLING-4543</a>). Since loading such dictionaries is much faster than loading the ones based on <code>sling:MessageEntry</code>s this format should be used preferably. This format is assumed if the <code>mix:language</code> resource name is ending with the extension <code>.json</code>. The parser will take any "key":"value" pair in the JSON file, including those in nested objects or arrays. Normally, a dictionary will be just a single json object = hash map though.</p> -<h5>Sample Resources</h5> +<h5><a href="#sample-resources" name="sample-resources">Sample Resources</a></h5> <p>Content for this format might look like this:</p> <pre><code> /libs/languages +-- english.json (nt:file, mix:language) http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/jcr-installer-provider.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/jcr-installer-provider.html b/documentation/bundles/jcr-installer-provider.html index 1583c3c..db21762 100644 --- a/documentation/bundles/jcr-installer-provider.html +++ b/documentation/bundles/jcr-installer-provider.html @@ -73,22 +73,22 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » </div> <h1> JCR Installer Provider </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>The JCR installer provider scans the JCR repository for artifacts and provides them to the <a href="/documentation/bundles/osgi-installer.html">OSGI installer</a>.</p> -<h2>Configuration and Scanning</h2> +<h2><a href="#configuration-and-scanning" name="configuration-and-scanning">Configuration and Scanning</a></h2> <p>The JCR installer provider can be configured with weighted paths which are scanned. By default, the installer scans in <em>/apps</em> and <em>/libs</em> where artifacts found in <em>/apps</em> get a higher priority. The installer does a deep scan and uses a regular expression to detect folders containing artifacts to be installed. By default, artifacts from within a folder named <em>install</em> are provided to the OSGi installer.</p> <p>If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>) this is provided to the OSGi installer. </p> <p>In addition every node of type <em>sling:OsgiConfig</em> is provided as a configuration to the installer. This has the advantage of leveraging the JCR structure better than binary files, but has the known limitations outlined in <a href="https://issues.apache.org/jira/browse/SLING-4183";>SLING-4183</a> and <a href="https://issues.apache.org/jira/browse/SLING-2477";>SLING-2477</a>, therefore it is recommended to stick to one of the binary formats described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>.</p> <p>The JCR installer provider does not check or scan the artifacts itself, the detection and installation is deferred to the OSGi installer.</p> -<h3>Runmode Support</h3> +<h3><a href="#runmode-support" name="runmode-support">Runmode Support</a></h3> <p>The JCR installer supports run modes for installing artifacts. By default folders named <em>install</em> are checked for artifacts. If Apache Sling is started with one (or more run modes), all folders named <em>install.[RUNMODE]</em> are scanned as well. To be precise, the folder name can be followed by any number of run modes separated by comma. For example, if started with run modes <em>dev</em>, <em>a1</em>, and <em>public</em>, folders like <em>install.dev</em>, <em>install.a1</em>, <em>install.public</em> are searched as well as <em>install.dev.a1</em>, or <em>install.a1.dev</em>.</p> <p>Artifacts from folders with a run mode get a higher priority. For example by default, an <em>install</em> folder underneath <em>/libs</em> gets the priority <em>50</em>. For each run mode in the folder name, this priority is increased by <em>1</em>, so <em>install.dev</em> has <em>51</em> and <em>install.a1.dev</em> is <em>52</em>.</p> -<h2>Write Back Support</h2> +<h2><a href="#write-back-support" name="write-back-support">Write Back Support</a></h2> <p>The JCR installer supports writing back of configurations which are changed by some other ways, e.g by using the Apache Felix web console. If this is a new configuration which was not originally stored in the repository, a new configuration is stored under <em>/apps/sling/install</em>. The highest search path is used together with a configurable folder (*sling/install* in this case). If a configuration is changed which already exists in the repository, then it depends where the original configuration is stored. If its under <em>/libs</em> a new configuration at the same path under <em>/apps</em> is created. Otherwise the configuration is directly modified. As JCR properties do not support all Java primitive types like Integer, the write back does not generate a node of type <em>sling:OsgiConfig</em> in the repository but a properties file as described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>.</p> <p>Write back can be turned off by configuration.</p> -<h3>Start Level Support</h3> +<h3><a href="#start-level-support" name="start-level-support">Start Level Support</a></h3> <p>If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with <a href="https://issues.apache.org/jira/browse/SLING-2011";>SLING-2011</a>). So e.g. a bundle in the path <code>/libs/sling/install/15/somebundle.jar</code> is having the start level <strong>15</strong>. </p> -<h1>Example</h1> +<h1><a href="#example" name="example">Example</a></h1> <p>Here's a quick walkthrough of the JCR installer functionality.</p> -<h2>Installation</h2> +<h2><a href="#installation" name="installation">Installation</a></h2> <p>Start the Sling <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/app";>launchpad/app</a> and make sure that the following bundles are present and started:</p> <ul> <li><a href="sling-settings-org-apache-sling-settings.html">Sling Settings</a></li> @@ -96,7 +96,7 @@ <li>JCR installer provider (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr";>org.apache.sling.installer.provider.jcr</a>)</li> </ul> <p>To watch the logs produced by these modules, you can filter <code>sling/logs/error.log</code> using <code>egrep 'jcrinstall|osgi.installer'</code>.</p> -<h2>Install and remove a bundle</h2> +<h2><a href="#install-and-remove-a-bundle" name="install-and-remove-a-bundle">Install and remove a bundle</a></h2> <p>We'll use the <a href="http://www.knopflerfish.org/releases/2.0.5/jars/desktop_awt/desktop_awt_all-2.0.0.jar";>Knopflerfish Desktop</a> bundle for this example, it is convenient as it displays a graphical user interface when started.</p> <p>We use <code>curl</code> to create content, to make it easy to reproduce the example by copying and pasting the <code>curl</code> commands. Any other way to create content in the repository will work, of course.</p> <p>By default, JCRInstall picks up bundles found in folders named <em>install</em> under <code>/libs</code> and <code>/apps</code>, so we start by creating such a folder:</p> @@ -113,7 +113,7 @@ curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar </code></pre> <p>Should cause the <em>Knopflerfish Desktop</em> window to disappear as the bundle is uninstalled.</p> -<h2>Install, modify and remove a configuration</h2> +<h2><a href="#install-modify-and-remove-a-configuration" name="install-modify-and-remove-a-configuration">Install, modify and remove a configuration</a></h2> <p>JCRInstall installs OSGi configurations from nodes having the <em>sling:OsgiConfig</em> node type, found in folders named <em>install</em> under the installation roots (/apps and /libs).</p> <p>Let's try this feature by creating a configuration with two properties:</p> <pre><code>curl \ @@ -159,14 +159,14 @@ curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install </code></pre> <p>And verify that the corresponding configuration is gone in the console page (after 1-2 seconds, like for all other JCRInstall operations).</p> <p>A node named like <code>o.a.s.foo.bar-a</code> uses <em>o.a.s.foo.bar</em> as its factory PID creating a configuration with an automatically generated PID. The value of <em>a</em> is stored as an alias in the OSGi installer to correlate the configuration object with the repository node.</p> -<h1>Automated Tests</h1> +<h1><a href="#automated-tests" name="automated-tests">Automated Tests</a></h1> <p>The following modules contain lots of automated tests (under <code>src/test</code>, as usual):</p> <ul> <li>OSGi installer integration tests (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/it";>org.apache.sling.installer.it</a>)</li> <li>JCR installer service (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr";>org.apache.sling.installer.providers.jcr</a>)</li> </ul> <p>Many of these tests are fairly readable, and can be used to find out in more detail how these modules work.</p> -<h1>Project Info</h1> +<h1><a href="#project-info" name="project-info">Project Info</a></h1> <ul> <li>JCR installer provider (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr";>org.apache.sling.installer.provider.jcr</a>)</li> </ul></section></div></div> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/log-tracers.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/log-tracers.html b/documentation/bundles/log-tracers.html index 1db43ad..69722f2 100644 --- a/documentation/bundles/log-tracers.html +++ b/documentation/bundles/log-tracers.html @@ -83,11 +83,11 @@ -d "tracers=oak-writes" \ http://localhost:4502/content/dam/ </code></pre> -<h2>Configuration</h2> +<h2><a href="#configuration" name="configuration">Configuration</a></h2> <p><img src="/documentation/bundles/tracer-config.png" alt="Tracer Config" /></p> <p><strong>Note that by default Tracer would not be enabled and you would need to save the OSGi config to get it activated</strong></p> <p>Tracer support two ways to enable logging.</p> -<h3>Tracer Sets</h3> +<h3><a href="#tracer-sets" name="tracer-sets">Tracer Sets</a></h3> <p>Tracer sets are collection of predefined logging categories matching specific area of an application. These can for now be configured as part of OSGi config</p> <pre><code>oak-query : org.apache.jackrabbit.oak.query.QueryEngineImpl;level=debug auth : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security @@ -111,12 +111,12 @@ attributes := attributeName '=' attributeValue </li> <li><code>caller-exclude-filter</code> - (optional) - '|' separated package prefixes which should not be included in the output. e.g. <em>org.apache.jackrabbit.oak.query.QueryImpl;caller=28;caller-exclude-filter="org.eclipse|org.felix"</em> this would exclude eclipse and felix packages from the resulting stack</li> </ul> -<h3>Performance Impact</h3> +<h3><a href="#performance-impact" name="performance-impact">Performance Impact</a></h3> <p>Tracer makes use of <a href="http://logback.qos.ch/manual/filters.html#TurboFilter";>Logback TuboFilter</a> to intercept the logging calls and only enable them for those which are enabled via tracer config for the request. The filter is only registered for the duration of that request hence would avoid adding the cost for normal run.</p> <p>You can also disable the Tracer completely via OSGi config.</p> -<h2>Where do logs go</h2> +<h2><a href="#where-do-logs-go" name="where-do-logs-go">Where do logs go</a></h2> <p>The logs captured are logged at two places</p> -<h3>RequestProgressTracker</h3> +<h3><a href="#requestprogresstracker" name="requestprogresstracker">RequestProgressTracker</a></h3> <p>Sling provides support for recording recent requests which can be accessed via <a href="https://sling.apache.org/documentation/development/monitoring-requests.html";>Recent Requests Plugin</a>. It would list down the list of recent request and then on clicking them you can see the logs showed on the UI.</p> <p>The logging there is done via <a href="https://sling.apache.org/apidocs/sling5/org/apache/sling/api/request/RequestProgressTracker.html";>RequestProgressTracker</a> (<a href="http://dev.day.com/content/ddc/blog/2008/06/requestprogresstracker.html";>intro</a>). By default recent request plugin gets overflown as it captures request even for css, js files. To avoid that you can modify the config as part of <em>Sling Main Servlet</em> config</p> <p><img src="/documentation/bundles/sling-main-servlet-config.png" alt="Sling Main Servlet Config" /></p> @@ -128,15 +128,15 @@ attributes := attributeName '=' attributeValue 1316 (2015-05-11 17:39:56) LOG JCR Query Count 3 1320 (2015-05-11 17:39:56) TIMER_END{1320,Request Processing} Request Processing </code></pre> -<h3>Server Logs</h3> +<h3><a href="#server-logs" name="server-logs">Server Logs</a></h3> <p>Further the logs also go to normal server side logs. By default they would go to the error.log. If you have routed the logs of specific categories to different files then normal Logback logging rules would apply</p> -<h2>Usage</h2> +<h2><a href="#usage" name="usage">Usage</a></h2> <p>Tracing can be done in various ways for a given HTTP request. Tracer looks for following hints as part of request</p> <ul> <li>Tracer set names - Comma separated list of tracer set names which need to be enabled. e.g. <code>oak-query, oak-writes</code> etc</li> <li>tracerConfig - Raw tracing config only used for that specific request</li> </ul> -<h3>Request Parameters</h3> +<h3><a href="#request-parameters" name="request-parameters">Request Parameters</a></h3> <p>Param names</p> <ul> <li><code>tracers</code> - Tracer set names</li> @@ -163,7 +163,7 @@ attributes := attributeName '=' attributeValue 2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType 2015-05-11 17:30:42,856 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] save </code></pre> -<h3>Request Headers</h3> +<h3><a href="#request-headers" name="request-headers">Request Headers</a></h3> <p>Some request like initial authentication processing does not involve Sling MainServlet and hence for those request logging cannot be done to RequestProgressTracker. Instead we can just get logs enabled and route them to normal logging on server side. For that you need to use HTTP header</p> <ul> <li><code>Sling-Tracers</code> - Set of tracer set names</li> @@ -184,7 +184,7 @@ attributes := attributeName '=' attributeValue 2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding Credentials to shared state. 2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding login name to shared state. </code></pre> -<h2>Tracer Recording</h2> +<h2><a href="#tracer-recording" name="tracer-recording">Tracer Recording</a></h2> <p><em>Since 1.0.0 <a href="https://issues.apache.org/jira/browse/SLING-5459";>SLING-5459</a></em></p> <p>Apart from routing the logs to the server logs they can also be stored in memory and accessed in json form from Felix Web Console. By default support for recording is disabled and it needs to be explicitly enabled via OSGi config</p> <p>Recording features works as explained below</p> @@ -220,8 +220,7 @@ Transfer-Encoding: chunked -u admin:admin http://localhost:4512/assets.html/content/dam -o /dev/null </code></pre> <p>Below is a json output for GET request</p> - <pre><code>:::javascript -{ + <pre><code>:<!-- TODO syntax marker (::javascript) disabled -->{ "method": "GET", "time": 15140, "timestamp": 1461574009024, @@ -262,10 +261,9 @@ Transfer-Encoding: chunked <li><code>logs</code> - List of log entries captured (as enabled by tracer config) for current request</li> </ol> <p>The recordings are held in memory for 15 mins (per default setting) and can be seen listed at http://localhost:8080/system/console/tracer. Look into the OSGi config for more config options around this.</p> -<h2>Installation</h2> +<h2><a href="#installation" name="installation">Installation</a></h2> <p>Download the bundle from <a href="http://sling.apache.org/downloads.cgi";>here</a> or use following Maven dependency</p> -<pre><code>::xml -<dependency> +<pre><code><!-- TODO syntax marker (::xml) disabled --><dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.tracer</artifactId> <version>1.0.0</version> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html b/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html index 91bf2e5..9b2cf7c 100644 --- a/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html +++ b/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html @@ -74,7 +74,7 @@ Managing permissions (jackrabbit.accessmanager) </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>The <code>jackrabbit-accessmanager</code> bundle delivers a REST interface to manipulate users permissions in the JCR. After installing the <code>jackrabbit-accessmanager</code> bundle the REST services are exposed under the path of the node where you will manipulate the permissions for a user with a specific selector like <code>modifyAce</code>, <code>acl</code> and <code>deleteAce</code>. <!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Privileges</h2> +<h2><a href="#privileges" name="privileges">Privileges</a></h2> <table> <thead> <tr> @@ -141,7 +141,7 @@ </tr> </tbody> </table> -<h2>Add or modify permissions</h2> +<h2><a href="#add-or-modify-permissions" name="add-or-modify-permissions">Add or modify permissions</a></h2> <p>To modify the permissions for a node POST a request to <code>/<path-to-the-node>.modifyAce.<html or json></code>. The following parameters are available:</p> <ul> <li><em>numeric</em> - Place the target ACE at the specified numeric index. |</li> @@ -149,18 +149,18 @@ <p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. | Example with curl:</p> <pre><code>curl -FprincipalId=myuser -Fprivilege@jcr:read=granted http://localhost:8080/test/node.modifyAce.html </code></pre> -<h2>Delete permissions</h2> +<h2><a href="#delete-permissions" name="delete-permissions">Delete permissions</a></h2> <p>To delete permissions for a node POST a request to <code>/<path-to-the-node>.deleteAce.<html or json></code>. The following parameters are available:</p> <p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. | Example with curl:</p> <pre><code>curl -F:applyTo=myuser http://localhost:8080/test/node.deleteAce.html </code></pre> -<h2>Get permissions</h2> -<h3>Bound Permissions</h3> +<h2><a href="#get-permissions" name="get-permissions">Get permissions</a></h2> +<h3><a href="#bound-permissions" name="bound-permissions">Bound Permissions</a></h3> <p>To get the permissions bound to a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.acl.json</code>. </p> <p>Example:</p> <pre><code>http://localhost:8080/test/node.acl.json </code></pre> -<h3>Effective Permissions</h3> +<h3><a href="#effective-permissions" name="effective-permissions">Effective Permissions</a></h3> <p>To get the permissions which are effective for a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.eacl.json</code>. </p> <p>Example:</p> <pre><code>http://localhost:8080/test/node.eacl.json @@ -168,7 +168,7 @@ <div class="note"> See section 16.3 of the JCR 2.0 specification for an explanation of the difference between bound and effective policies. </div> -<h2>Sample User Interface Implementation</h2> +<h2><a href="#sample-user-interface-implementation" name="sample-user-interface-implementation">Sample User Interface Implementation</a></h2> <p><em>Since Version 2.1.1</em></p> <p>A sample implementation of ui pages for permissions management is provided @ http://svn.apache.org/viewvc/sling/trunk/samples/accessmanager-ui/</p></section></div></div> <div class="footer">
