You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bd...@apache.org on 2017/06/21 07:22:23 UTC
[17/25] sling-site git commit: Testing with /ng/ context path for
temporary https://sling.apache.org/ng/ setup
http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/models.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/models.html b/documentation/bundles/models.html
index 9245ecd..f2cbf08 100644
--- a/documentation/bundles/models.html
+++ b/documentation/bundles/models.html
@@ -2,22 +2,22 @@
<head>
<meta charset="utf-8"/>
<title>Apache Sling on JBake</title>
- <link rel="stylesheet" href="/res/css/site.css"/>
- <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <link rel="stylesheet" href="/ng/res/css/site.css"/>
+ <link rel="icon" href="/ng/res/favicon.ico"/>
<div class="title">
<div class="logo">
<a href="http://sling.apache.org">
- <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/>
</a>
</div><div class="header">
<a href="http://www.apache.org">
- <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/>
</a>
</div>
</div>
</head><body>
<div class="menu">
- <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/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://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p
><strong>Project info</strong><br/><a href="/ng/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/ng/contributing.html">Contributing</a><br/><a href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a href="/ng/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.
org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong>
</div> <div class="main">
<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Sling Models</h1></header><p>[TOC]</p>
<p>Many Sling projects want to be able to create model objects - POJOs which are automatically mapped from Sling objects, typically resources, but also request objects. Sometimes these POJOs need OSGi services as well.</p>
@@ -34,103 +34,259 @@
</ul>
<h1>Basic Usage</h1>
<p>In the simplest case, the class is annotated with <code>@Model</code> and the adaptable class. Fields which need to be injected are annotated with <code>@Inject</code>:</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject private String propertyName; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject
+ private String propertyName;
+}
+</code></pre>
<p>In this case, a property named "propertyName" will be looked up from the Resource (after first adapting it to a <code>ValueMap</code>) and it is injected.</p>
<p>For an interface, it is similar:</p>
-<p>::java @Model(adaptables=Resource.class) public interface MyModel {</p>
-<p>@Inject String getPropertyName(); }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public interface MyModel {
+
+ @Inject
+ String getPropertyName();
+}
+</code></pre>
<p>Constructor injection is also supported (as of Sling Models 1.1.0):</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel { @Inject public MyModel(@Named("propertyName") String propertyName) { // constructor code } }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+ @Inject
+ public MyModel(@Named("propertyName") String propertyName) {
+ // constructor code
+ }
+}
+</code></pre>
<p>Because the name of a constructor argument parameter cannot be detected via the Java Reflection API a <code>@Named</code> annotation is mandatory for injectors that require a name for resolving the injection.</p>
<p>In order for these classes to be picked up, there is a header which must be added to the bundle's manifest:</p>
-<p><Sling-Model-Packages> org.apache.sling.models.it.models </Sling-Model-Packages></p>
+<pre><code><Sling-Model-Packages>
+ org.apache.sling.models.it.models
+</Sling-Model-Packages>
+</code></pre>
<p>This header must contain all packages which contain model classes or interfaces. However, subpackages need not be listed individually, e.g. the header above will also pick up model classes in <code>org.apache.sling.models.it.models.sub</code>. Multiple packages can be listed in a comma-separated list (any whitespace will be removed):</p>
-<p><Sling-Model-Packages> org.apache.sling.models.it.models, org.apache.sling.other.models </Sling-Model-Packages></p>
+<pre><code><Sling-Model-Packages>
+ org.apache.sling.models.it.models,
+ org.apache.sling.other.models
+</Sling-Model-Packages>
+</code></pre>
<p>Alternatively it is possible to list all classes individually that are Sling Models classes via the <code>Sling-Model-Classes</code> header.</p>
<p>If you use the Sling Models bnd plugin all required bundle headers are generated automatically at build time (see chapter 'Registration of Sling Models classes via bnd plugin' below).</p>
<h1>Client Code</h1>
<h2>adaptTo()</h2>
<p>Client code doesn't need to be aware that Sling Models is being used. It just uses the Sling Adapter framework:</p>
-<p>::java MyModel model = resource.adaptTo(MyModel.class)</p>
+<pre><code>::java
+MyModel model = resource.adaptTo(MyModel.class)
+</code></pre>
<p>Or</p>
-<p>::jsp <sling:adaptTo adaptable="${resource}" adaptTo="org.apache.sling.models.it.models.MyModel" var="model"/></p>
+<pre><code>::jsp
+<sling:adaptTo adaptable="${resource}" adaptTo="org.apache.sling.models.it.models.MyModel" var="model"/>
+</code></pre>
<p>Or</p>
-<p>::jsp ${sling:adaptTo(resource, 'org.apache.sling.models.it.models.MyModel')}</p>
+<pre><code>::jsp
+${sling:adaptTo(resource, 'org.apache.sling.models.it.models.MyModel')}
+</code></pre>
<p>As with other AdapterFactories, if the adaptation can't be made for any reason, <code>adaptTo()</code> returns null.</p>
<h2>ModelFactory (since 1.2.0)</h2>
<p><em>See also <a href="https://issues.apache.org/jira/browse/SLING-3709">SLING-3709</a></em></p>
<p>Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi service <code>ModelFactory</code> provides a method for instantiating a model that throws exceptions. This is not allowed by the Javadoc contract of the adaptTo method. That way <code>null</code> checks are not necessary and it is easier to see why instantiation of the model failed.</p>
-<p>::java try { MyModel model = modelFactory.createModel(object, MyModel.class); } catch (Exception e) { // give out error message that the model could not be instantiated. // The exception contains further information. // See the javadoc of the ModelFactory for which Exception can be expected here }</p>
+<pre><code>::java
+try {
+ MyModel model = modelFactory.createModel(object, MyModel.class);
+} catch (Exception e) {
+ // give out error message that the model could not be instantiated.
+ // The exception contains further information.
+ // See the javadoc of the ModelFactory for which Exception can be expected here
+}
+</code></pre>
<p>In addition <code>ModelFactory</code> provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.</p>
<h1>Other Options</h1>
<h2>Names</h2>
<p>If the field or method name doesn't exactly match the property name, <code>@Named</code> can be used:</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject @Named("secondPropertyName") private String otherName; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject @Named("secondPropertyName")
+ private String otherName;
+}
+</code></pre>
<h2>Optional and Required</h2>
<p><code>@Inject</code>ed fields/methods are assumed to be required. To mark them as optional, use <code>@Optional</code>:</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject @Optional private String otherName; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject @Optional
+ private String otherName;
+}
+</code></pre>
<p>If a majority of <code>@Inject</code>ed fields/methods are optional, it is possible (since Sling Models API 1.0.2/Impl 1.0.6) to change the default injection strategy by using adding <code>defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL</code> to the <code>@Model</code> annotation:</p>
-<p>::java @Model(adaptables=Resource.class, defaultInjectionStrategy=DefaultInjectionStrategy.OPTIONAL) public class MyModel {</p>
-<p>@Inject private String otherName; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class, defaultInjectionStrategy=DefaultInjectionStrategy.OPTIONAL)
+public class MyModel {
+
+ @Inject
+ private String otherName;
+}
+</code></pre>
<p>To still mark some fields/methods as being mandatory while relying on <code>defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL</code> for all other fields, the annotation <code>@Required</code> can be used.</p>
<p><code>@Optional</code> annotations are only evaluated when using the <code>defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED</code> (which is the default), <code>@Required</code> annotations only if using <code>defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL</code>.</p>
<h2>Defaults</h2>
<p>A default value can be provided (for Strings & primitives):</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject @Default(values="defaultValue") private String name; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject @Default(values="defaultValue")
+ private String name;
+}
+</code></pre>
<p>Defaults can also be arrays:</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject @Default(intValues={1,2,3,4}) private int[] integers; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject @Default(intValues={1,2,3,4})
+ private int[] integers;
+}
+</code></pre>
<p>OSGi services can be injected:</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject private ResourceResolverFactory resourceResolverFactory; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject
+ private ResourceResolverFactory resourceResolverFactory;
+}
+</code></pre>
<p>In this case, the name is not used -- only the class name.</p>
<h2>Collections</h2>
<p>Lists and arrays are supported by some injectors. For the details look at the table given in <a href="#available-injectors">Available Injectors</a>:</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject private List<Servlet> servlets; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject
+ private List<Servlet> servlets;
+}
+</code></pre>
<p>List injection for <em>child resources</em> works by injecting grand child resources (since Sling Models Impl 1.0.6). For example, the class</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>@Inject private List<Resource> addresses; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ @Inject
+ private List<Resource> addresses;
+}
+</code></pre>
<p>Is suitable for a resource structure such as:</p>
-<p>+- resource (being adapted) | +- addresses | +- address1 | +- address2</p>
+<pre><code>+- resource (being adapted)
+ |
+ +- addresses
+ |
+ +- address1
+ |
+ +- address2
+</code></pre>
<p>In this case, the <code>addresses</code> <code>List</code> will contain <code>address1</code> and <code>address2</code>.</p>
<h2>OSGi Service Filters</h2>
<p>OSGi injection can be filtered:</p>
-<p>::java @Model(adaptables=SlingHttpServletRequest.class) public class MyModel {</p>
-<p>@Inject private PrintWriter out;</p>
-<p>@Inject @Named("log") private Logger logger;</p>
-<p>@Inject @Filter("(paths=/bin/something)") private List<Servlet> servlets; }</p>
+<pre><code>::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public class MyModel {
+
+ @Inject
+ private PrintWriter out;
+
+ @Inject
+ @Named("log")
+ private Logger logger;
+
+ @Inject
+ @Filter("(paths=/bin/something)")
+ private List<Servlet> servlets;
+}
+</code></pre>
<h2>PostConstruct Methods</h2>
<p>The <code>@PostConstruct</code> annotation can be used to add methods which are invoked upon completion of all injections:</p>
-<p>::java @Model(adaptables=SlingHttpServletRequest.class) public class MyModel {</p>
-<p>@Inject private PrintWriter out;</p>
-<p>@Inject @Named("log") private Logger logger;</p>
-<p>@PostConstruct protected void sayHello() { logger.info("hello"); } }</p>
+<pre><code>::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public class MyModel {
+
+ @Inject
+ private PrintWriter out;
+
+ @Inject
+ @Named("log")
+ private Logger logger;
+
+ @PostConstruct
+ protected void sayHello() {
+ logger.info("hello");
+ }
+}
+</code></pre>
<p><code>@PostConstruct</code> methods in a super class will be invoked first.</p>
<h2>Via</h2>
<p>If the injection should be based on a JavaBean property of the adaptable, you can indicate this using the <code>@Via</code> annotation:</p>
-<p>::java @Model(adaptables=SlingHttpServletRequest.class) public interface MyModel {</p>
-<p>// will return request.getResource().adaptTo(ValueMap.class).get("propertyName", String.class) @Inject @Via("resource") String getPropertyName(); }</p>
+<pre><code>::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public interface MyModel {
+
+ // will return request.getResource().adaptTo(ValueMap.class).get("propertyName", String.class)
+ @Inject @Via("resource")
+ String getPropertyName();
+}
+</code></pre>
<h2>Source</h2>
<p>If there is ambiguity where a given injection could be handled by more than one injector, the <code>@Source</code> annotation can be used to define which injector is responsible:</p>
-<p>::java @Model(adaptables=SlingHttpServletRequest.class) public interface MyModel {</p>
-<p>// Ensure that "resource" is retrived from the bindings, not a request attribute @Inject @Source("script-bindings") Resource getResource(); }</p>
+<pre><code>::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public interface MyModel {
+
+ // Ensure that "resource" is retrived from the bindings, not a request attribute
+ @Inject @Source("script-bindings")
+ Resource getResource();
+}
+</code></pre>
<h2>Adaptations</h2>
<p>If the injected object does not match the desired type and the object implements the <code>Adaptable</code> interface, Sling Models will try to adapt it. This provides the ability to create rich object graphs. For example:</p>
-<p>::java @Model(adaptables=Resource.class) public interface MyModel {</p>
-<p>@Inject ImageModel getImage(); }</p>
-<p>@Model(adaptables=Resource.class) public interface ImageModel {</p>
-<p>@Inject String getPath(); }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public interface MyModel {
+
+ @Inject
+ ImageModel getImage();
+}
+
+@Model(adaptables=Resource.class)
+public interface ImageModel {
+
+ @Inject
+ String getPath();
+}
+</code></pre>
<p>When a resource is adapted to <code>MyModel</code>, a child resource named <code>image</code> is automatically adapted to an instance of <code>ImageModel</code>.</p>
<p>Constructor injection is supported for the adaptable itself. For example:</p>
-<p>::java @Model(adaptables=Resource.class) public class MyModel {</p>
-<p>public MyModel(Resource resource) { this.resource = resource; }</p>
-<p>private final Resource resource;</p>
-<p>@Inject private String propertyName; }</p>
+<pre><code>::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+ public MyModel(Resource resource) {
+ this.resource = resource;
+ }
+
+ private final Resource resource;
+
+ @Inject
+ private String propertyName;
+}
+</code></pre>
<h2>Sling Validation (since 1.2.0)</h2>
<a name="validation">*See also [SLING-4161](https://issues.apache.org/jira/browse/SLING-4161)*</a>
<p>You can use the attribute <code>validation</code> on the Model annotation to call a validation service on the resource being used by the Sling model. That attribute supports three different values:</p>
@@ -369,7 +525,12 @@
<p>By default, each model class is registered using its own implementation class as adapter. If the class has additional interfaces this is not relevant.</p>
<p>The <code>@Model</code> annotations provides an optional <code>adapters</code> attribute which allows specifying under which type(s) the model implementation should be registered in the Models Adapter Factory. Prior to <em>Sling Models Impl 1.3.10</em> only the given class names are used as adapter classes, since 1.3.10 the implementation class is always being registered implicitly as adapter as well (see <a href="https://issues.apache.org/jira/browse/SLING-6658">SLING-6658</a>). With this attribute it is possible to register the model to one (or multiple) interfaces, or a superclass. This allows separating the model interface from the implementation, which makes it easier to provide mock implementations for unit tests as well.</p>
<p>Example:</p>
-<p>::java @Model(adaptables = Resource.class, adapters = MyService.class) public class MyModel implements MyService { // injects fields and implements the MyService methods }</p>
+<pre><code>::java
+@Model(adaptables = Resource.class, adapters = MyService.class)
+public class MyModel implements MyService {
+ // injects fields and implements the MyService methods
+}
+</code></pre>
<p>In this example a <code>Resource</code> can be adapted to a <code>MyService</code> interface, and the Sling Models implementation instantiates a <code>MyModel</code> class for this.</p>
<p>It is possible to have multiple models implementing the same interface. By default Sling Models will just take the first one ordered alphabetically by the class name. Applications can provide an OSGi service implementing the <code>ImplementationPicker</code> SPI interface which could use context to determine which implementation can be chosen, e.g. depending an a tenant or content path context. If multiple implementations of the <code>ImplementationPicker</code> interface are present, they are queried one after another in order of their service ranking property, the first one that picks an implementation wins.</p>
<h1>Associating a Model Class with a Resource Type (since 1.3.0)</h1>
@@ -387,17 +548,42 @@
</ul>
<p>The exact semantics of the exporting will be determined by an implementation of the <code>ModelExporter</code> service interface. Sling Models currently includes a single exporter, using the Jackson framework, which is capable of serializing models as JSON or transforming them to <code>java.util.Map</code> objects.</p>
<p>In addition, model objects can have servlets automatically registered for their resource type (if it is set) using the <code>@Exporter</code> annotation. For example, a model class with the annotation</p>
-<p>::java @Model(adaptable = Resource.class, resourceType = "myco/components/foo") @Exporter(name = "jackson", extensions = "json")</p>
+<pre><code>::java
+@Model(adaptable = Resource.class, resourceType = "myco/components/foo")
+@Exporter(name = "jackson", extensions = "json")
+</code></pre>
<p>results in the registration of a servlet with the resource type and extension specified and a selector of 'model' (overridable through the <code>@Exporter</code> annotation's <code>selector</code> attribute). When this servlet is invoked, the <code>Resource</code> will be adapted to the model, exported as a <code>java.lang.String</code> (via the named Exporter) and then returned to the client.</p>
<h1>Registration of Sling Models classes via bnd plugin</h1>
<p>With the Sling Models bnd plugin it is possible to automatically generated the necessary bundle header to register the Sling Models classes contained in the Maven bundle project - either with maven-bundle-plugin or with bnd-maven-plugin. By default the plugin generates a <code>Sling-Model-Classes</code> header (only compatible with Sling Models Impl since version 1.3.4, see <a href="https://issues.apache.org/jira/browse/SLING-6308">SLING-6308</a>).</p>
<p>Example configuration:</p>
-<h1>!xml</h1>
-<p><plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <extensions>true</extensions> <configuration> <instructions> <_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin</_plugin> </instructions> </configuration> <dependencies> <dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.bnd.models</artifactId> <version>1.0.0</version> </dependency> </dependencies> </plugin></p>
+<pre><code>#!xml
+<plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin</_plugin>
+ </instructions>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>org.apache.sling.bnd.models</artifactId>
+ <version>1.0.0</version>
+ </dependency>
+ </dependencies>
+</plugin>
+</code></pre>
<p>If a <code>Sling-Model-Packages</code> or <code>Sling-Model-Classes</code> was already manually defined for the bundle the bnd plugin does nothing. So if you want to migrate an existing project to use this plugin remove the existing header definitions.</p>
<p>If you want to generate a bundle header compliant with Sling Models < 1.3.4 (i.e. <code>Sling-Model-Packages</code>) you need to specify the attribute <code>generatePackagesHeader=true</code>. An example configuration looks like this</p>
-<h1>!xml</h1>
-<p><configuration> <instructions> <_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin;generatePackagesHeader=true</_plugin> </instructions> </configuration></p></section></div></div>
+<pre><code>#!xml
+<configuration>
+ <instructions>
+ <_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin;generatePackagesHeader=true</_plugin>
+ </instructions>
+</configuration>
+</code></pre></section></div></div>
<div class="footer">
<div class="timestamp">
TODO display revision number here
http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/nosql-resource-providers.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/nosql-resource-providers.html b/documentation/bundles/nosql-resource-providers.html
index 7b151c2..8b47c25 100644
--- a/documentation/bundles/nosql-resource-providers.html
+++ b/documentation/bundles/nosql-resource-providers.html
@@ -2,22 +2,22 @@
<head>
<meta charset="utf-8"/>
<title>Apache Sling on JBake</title>
- <link rel="stylesheet" href="/res/css/site.css"/>
- <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <link rel="stylesheet" href="/ng/res/css/site.css"/>
+ <link rel="icon" href="/ng/res/favicon.ico"/>
<div class="title">
<div class="logo">
<a href="http://sling.apache.org">
- <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/>
</a>
</div><div class="header">
<a href="http://www.apache.org">
- <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/>
</a>
</div>
</div>
</head><body>
<div class="menu">
- <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/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://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p
><strong>Project info</strong><br/><a href="/ng/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/ng/contributing.html">Contributing</a><br/><a href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a href="/ng/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.
org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong>
</div> <div class="main">
<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>NoSQL Resource Providers (org.apache.sling.nosql)</h1></header><p>[TOC]</p>
<h2>Introduction</h2>
@@ -37,7 +37,12 @@
<p>Resource provider for <a href="https://www.mongodb.org/">MongoDB</a> NoSQL database.</p>
<p>Tested with MongoDB Server 3.0.6 and MongoDB Java Driver 3.1.1.</p>
<p>Configuration example:</p>
-<p>org.apache.sling.nosql.mongodb.resourceprovider.MongoDBNoSqlResourceProviderFactory.factory.config-default provider.roots=["/"] connectionString="localhost:27017" database="sling" collection="resources"</p>
+<pre><code>org.apache.sling.nosql.mongodb.resourceprovider.MongoDBNoSqlResourceProviderFactory.factory.config-default
+ provider.roots=["/"]
+ connectionString="localhost:27017"
+ database="sling"
+ collection="resources"
+</code></pre>
<p>See Apache Felix OSGi console for detailed documentation of the parameters. All resource data is stored in one Collection of one MongoDB database. Each resource is stored as a document with the path stored in an "_id" property.</p>
<p>Source code: <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/mongodb-resourceprovider">Apache Sling NoSQL MongoDB Resource Provider</a></p>
<p>Please note: there is an <a href="https://github.com/apache/sling/tree/trunk/contrib/extensions/mongodb">alternative MongoDB resource provider implementation</a> from 2012 which has less features, a slightly different concept for storing resource data (in multiple collections), and it does not use the "Generic Resource Provider".</p>
@@ -45,8 +50,15 @@
<p>Resource provider for <a href="http://www.couchbase.com/">Couchbase</a> NoSQL database.</p>
<p>Tested with Couchbase Server 4.0.0 and Couchbase Java SDK 2.2.4. Please note: Couchbase 4 or higher is mandatory because N1QL support is required.</p>
<p>Configuration example:</p>
-<p>org.apache.sling.nosql.couchbase.resourceprovider.CouchbaseNoSqlResourceProviderFactory.factory.config-default provider.roots=["/"]</p>
-<p>org.apache.sling.nosql.couchbase.client.CouchbaseClient.factory.config-default clientId="sling-resourceprovider-couchbase" couchbaseHosts="localhost:8091" bucketName="sling" enabled=B"true"</p>
+<pre><code>org.apache.sling.nosql.couchbase.resourceprovider.CouchbaseNoSqlResourceProviderFactory.factory.config-default
+ provider.roots=["/"]
+
+org.apache.sling.nosql.couchbase.client.CouchbaseClient.factory.config-default
+ clientId="sling-resourceprovider-couchbase"
+ couchbaseHosts="localhost:8091"
+ bucketName="sling"
+ enabled=B"true"
+</code></pre>
<p>See Apache Felix OSGi console for detailed documentation of the parameters. All resource data is stored in one Couchbase bucket. Each resource is stored as a document with the path as key.</p>
<p>Source code: <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/couchbase-resourceprovider">Apache Sling NoSQL Couchbase Resource Provider</a></p>
<p>The resource provider requires and additional bundle <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/couchbase-client">Apache Sling NoSQL Couchbase Client</a> which wraps the Couchbase Java SDK (which itself is not an OSGi bundle), and ensures that the Couchbase Environment instance is used as a singleton in the VM.</p>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/org-apache-sling-junit-bundles.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/org-apache-sling-junit-bundles.html b/documentation/bundles/org-apache-sling-junit-bundles.html
index fd937ad..dd67d6e 100644
--- a/documentation/bundles/org-apache-sling-junit-bundles.html
+++ b/documentation/bundles/org-apache-sling-junit-bundles.html
@@ -2,27 +2,27 @@
<head>
<meta charset="utf-8"/>
<title>Apache Sling on JBake</title>
- <link rel="stylesheet" href="/res/css/site.css"/>
- <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <link rel="stylesheet" href="/ng/res/css/site.css"/>
+ <link rel="icon" href="/ng/res/favicon.ico"/>
<div class="title">
<div class="logo">
<a href="http://sling.apache.org">
- <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/>
</a>
</div><div class="header">
<a href="http://www.apache.org">
- <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/>
</a>
</div>
</div>
</head><body>
<div class="menu">
- <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/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://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p
><strong>Project info</strong><br/><a href="/ng/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/ng/contributing.html">Contributing</a><br/><a href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a href="/ng/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.
org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong>
</div> <div class="main">
-<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>JUnit server-side testing support bundles</h1></header><p>This is an overview of the Sling bundles that provide support for server-side JUnit tests.</p>
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>JUnit server-side testing support bundles</h1></header><p>This is an overview of the Sling bundles that provide support for server-side JUnit tests. </p>
<p>The Maven modules below <a href="https://svn.apache.org/repos/asf/sling/trunk/testing/samples"><code>testing/samples</code></a> provide different examples including HTTP-based and server-side teleported tests in a bundle module, running against a full Sling instance setup in the same Maven module.</p>
<h2>org.apache.sling.junit.core: server-side JUnit tests support</h2>
-<p>This bundle provides a <code>JUnitServlet</code> that runs JUnit tests found in bundles.</p>
+<p>This bundle provides a <code>JUnitServlet</code> that runs JUnit tests found in bundles. </p>
<div class="warning">
Note that the JUnitServlet does not require authentication, so it would allow any client to run tests. The servlet can be disabled by configuration if needed, but in general the `/system` path should not be accessible to website visitors anyway.
</div>
@@ -30,9 +30,10 @@ Note that the JUnitServlet does not require authentication, so it would allow an
For tighter integration with Sling, the alternate `SlingJUnitServlet` is registered with the `sling/junit/testing` resource type and `.junit` selector, if the bundle is running in a Sling system. Using this servlet instead of the plain JUnitServlet also allows Sling authentication to be used for running the tests, and the standard Sling request processing is used, including servlet filters for example.
</div>
<p>To make tests available to that servlet, the bundle that contains them must point to them with a <code>Sling-Test-Regexp</code> bundle header that defines a regular expression that matches the test class names, like for example:</p>
-<p>Sling-Test-Regexp=com.example.*ServerSideTest</p>
+<pre><code>Sling-Test-Regexp=com.example.*ServerSideTest
+</code></pre>
<h3>The TeleporterRule</h3>
-<p>The <code>TeleporterRule</code> supplied by this bundle (since V1.0.12) makes it easy to write such tests, as it takes care of all the mechanics of</p>
+<p>The <code>TeleporterRule</code> supplied by this bundle (since V1.0.12) makes it easy to write such tests, as it takes care of all the mechanics of </p>
<ol>
<li>creating the test bundle including all necessary classes for execution</li>
<li>adding the <code>Sling-Test-Regexp</code> header to the bundles manifest</li>
@@ -41,38 +42,57 @@ For tighter integration with Sling, the alternate `SlingJUnitServlet` is registe
<li>uninstalling the test bundle</li>
</ol>
<p>Most of these steps are done on the client-side by the org.apache.sling.junit.teleporter module (see below).</p>
-<p>Using this rule the server-side tests can be mixed with other tests in the source code if that's convenient, it just requires the <code>junit.core</code> and <code>junit.teleporter</code> modules described on this page to create such tests.</p>
+<p>Using this rule the server-side tests can be mixed with other tests in the source code if that's convenient, it just requires the <code>junit.core</code> and <code>junit.teleporter</code> modules described on this page to create such tests. </p>
<p>Here's a basic example of a server-side test that accesses OSGi services:</p>
-<p>public class BasicTeleporterTest {</p>
-<p>@Rule public final TeleporterRule teleporter = TeleporterRule.forClass(getClass(), "Launchpad");</p>
-<p>@Test public void testConfigAdmin() throws IOException { final String pid = "TEST_" + getClass().getName() + UUID.randomUUID();</p>
-<p>final ConfigurationAdmin ca = teleporter.getService(ConfigurationAdmin.class); assertNotNull("Teleporter should provide a ConfigurationAdmin", ca);</p>
-<p>final Configuration cfg = ca.getConfiguration(pid); assertNotNull("Expecting to get a Configuration", cfg); assertEquals("Expecting the correct pid", pid, cfg.getPid()); } }</p>
-<p>That's all there is to it, the <code>TeleporterRule</code> takes care of the rest.</p>
+<pre><code>public class BasicTeleporterTest {
+
+ @Rule
+ public final TeleporterRule teleporter = TeleporterRule.forClass(getClass(), "Launchpad");
+
+ @Test
+ public void testConfigAdmin() throws IOException {
+ final String pid = "TEST_" + getClass().getName() + UUID.randomUUID();
+
+ final ConfigurationAdmin ca = teleporter.getService(ConfigurationAdmin.class);
+ assertNotNull("Teleporter should provide a ConfigurationAdmin", ca);
+
+ final Configuration cfg = ca.getConfiguration(pid);
+ assertNotNull("Expecting to get a Configuration", cfg);
+ assertEquals("Expecting the correct pid", pid, cfg.getPid());
+ }
+}
+</code></pre>
+<p>That's all there is to it, the <code>TeleporterRule</code> takes care of the rest. </p>
<p>The test bundle being build and deployed through this rule usually happens quickly as the temporary bundle is very small. Both the client-side and server-side parts of the test can be debugged easily with the appropriate IDE settings.</p>
<p>The <code>Teleporter.getService</code> method takes an optional OSGi LDAP filter for service selection, like for example:</p>
-<p>final StringTransformer t = teleporter.getService(StringTransformer.class, "(mode=uppercase)");</p>
+<pre><code>final StringTransformer t = teleporter.getService(StringTransformer.class, "(mode=uppercase)");
+</code></pre>
<p>The method waits for the service to be available or until the timeout elapsed (<a href="https://issues.apache.org/jira/browse/SLING-6031">SLING-6031</a>).</p>
<p>And starting with version 1.0.4 of the <code>org.apache.sling.junit.teleporter</code> bundle, you can specify resources to embed in the test bundle, as in this example:</p>
-<p>@Rule public final TeleporterRule teleporter = TeleporterRule.forClass(getClass(), "Launchpad") .withResources("/foo/", "/some/other/resource.txt");</p>
+<pre><code>@Rule
+public final TeleporterRule teleporter =
+ TeleporterRule.forClass(getClass(), "Launchpad")
+ .withResources("/foo/", "/some/other/resource.txt");
+</code></pre>
<p>which will embed all resources found under <code>/foo</code> as well as the <code>resource.txt</code> in the test bundle, making them available to the server-side tests.</p>
-<p>This teleporter mechanism is used in our integration tests, search for <code>TeleporterRule</code> in there for examples or look at the <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/teleporter"><code>integrationtest.teleporter</code></a> package.</p>
+<p>This teleporter mechanism is used in our integration tests, search for <code>TeleporterRule</code> in there for examples or look at the <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/teleporter"><code>integrationtest.teleporter</code></a> package. </p>
<p>As I write this the teleporter mechanism is quite new, I suspect there might be some weird interactions between things like <code>@AfterClass</code>, custom test runners and this mechanism but it works well to a growing number of tests in our <code>launchpad/integration-tests</code> module. Moving to JUnit <code>Rules</code> as much as possible, and combining them using JUnit's <code>RuleChain</code>, should help work around such limitations if they arise.</p>
<h3>More details on the JUnitServlet</h3>
<p>To try the JUnitServlet interactively, you can install a bundle that contains tests and a <code>Sling-Test-Regexp</code> bundle header that points to them, as described above. Or use the <code>TeleporterRule</code> and set a breakpoint in the tests execution, when the test bundle in installed and listed by the test servlet.</p>
<p>To list the available tests, open <code>/system/sling/junit/</code> in your browser. The servlet shows available tests and allows you to execute them via a POST request.</p>
<p>Adding a path allows you to select a specific subset of tests, as in <code>/system/sling/junit/org.apache.sling.junit.remote.html</code></p>
-<p>The JUnitServlet provides various output formats, including in particular JSON, see <code>/system/sling/junit/.json</code> for example.</p>
+<p>The JUnitServlet provides various output formats, including in particular JSON, see <code>/system/sling/junit/.json</code> for example.</p>
<h2>org.apache.sling.junit.teleporter: client-side TeleporterRule support</h2>
<p>This module provides the <code>ClientSideTeleporter</code> which the <code>TeleporterRule</code> uses to package the server-side tests in bundles that's installed temporarily on the test server. Almost all steps described above in <a href="#the-teleporterrule">The TeleporterRule</a> are being performed by this module.</p>
<p>This module is not a bundle, as it's used on the client only, as a dependency when running the tests.</p>
<h3>TeleporterRule.Customizer</h3>
<p>A <code>TeleporterRule.Customizer</code> is used to setup the <code>ClientSideTeleporter</code>. That customizer is instantiated dynamically based on a String passed to the <code>TeleporterRule.forClass</code> method as 2nd parameter. As an example from our <code>launchpad/integration-tests</code> module, this call</p>
-<p>TeleporterRule.forClass(getClass(), "Launchpad:author");</p>
+<pre><code>TeleporterRule.forClass(getClass(), "Launchpad:author");
+</code></pre>
<p>causes the <code>TeleporterRule</code> to use the <code>org.apache.sling.junit.teleporter.customizers.LaunchpadCustomizer</code> class to setup the <code>ClientSideTeleporter</code>, and passes the "author" string to it as an option. Although our current <code>LaunchpadCustomizer</code> does not use this options string, it is meant to select a specific server (of family of servers) to run the tests on.</p>
<p>The options string can also use a full class name instead of the <code>Launchpad</code> short form used here, if needed. The part of that string that follows the first colon is passed to the customizer as is.</p>
-<p>Using Strings for customization reduces the coupling with the <code>junit.core</code> bundle, as it does not need to know those classes which are used only on the client side when running tests.</p>
-<p>If <code>TeleporterRule.forClass(getClass())</code> is used (the method without an additional 2nd parameter) the default customizer is used (<a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a>, since version 1.0.8).</p>
+<p>Using Strings for customization reduces the coupling with the <code>junit.core</code> bundle, as it does not need to know those classes which are used only on the client side when running tests. </p>
+<p>If <code>TeleporterRule.forClass(getClass())</code> is used (the method without an additional 2nd parameter) the default customizer is used (<a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a>, since version 1.0.8). </p>
<p>The following customizers are currently used in Sling</p>
<h3>Default Customizer</h3>
<p><em><a href="https://svn.apache.org/repos/asf/sling/trunk/testing/junit/teleporter/src/main/java/org/apache/sling/testing/teleporter/client/DefaultPropertyBasedCustomizer.java">DefaultPropertyBasedCustomizer.java</a></em> is used by default when no other customizer is referenced in <code>TeleporterRule.forClass(getClass())</code>. It relies on the following system properties:</p>
@@ -87,8 +107,105 @@ For tighter integration with Sling, the alternate `SlingJUnitServlet` is registe
<th>Related JIRA </th>
</tr>
</thead>
+ <tbody>
+ <tr>
+ <td><code>ClientSideTeleporter.baseUrl</code> </td>
+ <td>base url of the Sling Server to which to deploy. </td>
+ <td>yes </td>
+ <td>(-) </td>
+ <td>1.0.8 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.includeDependencyPrefixes</code> </td>
+ <td>comma-separated list of package prefixes for classes referenced from the IT. Only the classes having one of the given package prefix are included in the bundle being deployed to the given Sling instance together with the IT class itself. They are only included though in case they are referenced! If this is not set, no referenced classes will be included. </td>
+ <td>no </td>
+ <td>(-) </td>
+ <td>1.0.8 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.excludeDependencyPrefixes</code> </td>
+ <td>comma-separated list of package prefixes for classes referenced from the IT. Classes having one of the given package prefix will not be included in the bundle being deployed to the given Sling instance together with the IT class itself. This takes precedence over the <code>ClientSideTeleporter.includeDependencyPrefixes</code>. </td>
+ <td>no </td>
+ <td>(-) </td>
+ <td>1.0.8 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.embedClasses</code> </td>
+ <td>comma-separated list of fully qualified class names which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle </td>
+ <td>no </td>
+ <td>(-) </td>
+ <td>1.0.8 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.embedClassesDirectories</code> </td>
+ <td>comma-separated list directories containing class files which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle </td>
+ <td>no </td>
+ <td>(-) </td>
+ <td>1.0.12 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-6551">SLING-6551</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.additionalBundleHeaders</code> </td>
+ <td>comma-separated list of entries in the format <code><name>:<value></code> which should be added to the test bundle as additional headers </td>
+ <td>no </td>
+ <td>(-) </td>
+ <td>1.0.12 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-6558">SLING-6558</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.testReadyTimeoutSeconds</code> </td>
+ <td>how long to wait for our test to be ready on the server-side in seconds, after installing the test bundle. </td>
+ <td>no </td>
+ <td><code>12</code> </td>
+ <td>1.0.8 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.serverUsername</code> </td>
+ <td>the username with which to send requests to the Sling server. </td>
+ <td>no </td>
+ <td><code>admin</code> </td>
+ <td>1.0.8 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.serverPassword</code> </td>
+ <td>the password with which to send requests to the Sling server. </td>
+ <td>no </td>
+ <td><code>admin</code> </td>
+ <td>1.0.8 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.enableLogging</code> </td>
+ <td>set to <code>true</code> to log the tasks being performed by the teleporter. Useful for debugging. </td>
+ <td>no </td>
+ <td><code>false</code> </td>
+ <td>1.0.12 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.preventToUninstallBundle</code> </td>
+ <td>set to <code>true</code> to not automatically uninstall the test bundle after test execution. Useful for debugging. </td>
+ <td>no </td>
+ <td><code>false</code> </td>
+ <td>1.0.12 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td>
+ </tr>
+ <tr>
+ <td><code>ClientSideTeleporter.testBundleDirectory</code> </td>
+ <td>if set the test bundles are being persisted (before being installed) within the given directory name. If the directory does not exist, it will be automatically created. Useful for debugging. Recommended value <code>${project.build.directory}/test-bundles</code>. </td>
+ <td>no </td>
+ <td>(-) </td>
+ <td>1.0.12 </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td>
+ </tr>
+ </tbody>
</table>
-<p>| <code>ClientSideTeleporter.baseUrl</code> | base url of the Sling Server to which to deploy. | yes | - | 1.0.8 | <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> | | <code>ClientSideTeleporter.includeDependencyPrefixes</code> | comma-separated list of package prefixes for classes referenced from the IT. Only the classes having one of the given package prefix are included in the bundle being deployed to the given Sling instance together with the IT class itself. They are only included though in case they are referenced! If this is not set, no referenced classes will be included. | no | - | 1.0.8 | <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> | | <code>ClientSideTeleporter.excludeDependencyPrefixes</code> | comma-separated list of package prefixes for classes referenced from the IT. Classes having one of the given package prefix will not be included in the bundle being deployed to the given Sling instance together with the IT
class itself. This takes precedence over the <code>ClientSideTeleporter.includeDependencyPrefixes</code>. | no | - | 1.0.8 | <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> | | <code>ClientSideTeleporter.embedClasses</code> | comma-separated list of fully qualified class names which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle | no | - | 1.0.8 | <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> | | <code>ClientSideTeleporter.embedClassesDirectories</code> | comma-separated list directories containing class files which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle | no | - | 1.0.12 | <a href="https://issues.apache.org/jira/browse/SLING-6551">SLING-6551</a> | | <cod
e>ClientSideTeleporter.additionalBundleHeaders</code> | comma-separated list of entries in the format <code><name>:<value></code> which should be added to the test bundle as additional headers | no | - | 1.0.12 | <a href="https://issues.apache.org/jira/browse/SLING-6558">SLING-6558</a> | | <code>ClientSideTeleporter.testReadyTimeoutSeconds</code> | how long to wait for our test to be ready on the server-side in seconds, after installing the test bundle. | no | <code>12</code> | 1.0.8 | <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> | | <code>ClientSideTeleporter.serverUsername</code> | the username with which to send requests to the Sling server. | no | <code>admin</code> | 1.0.8 | <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> | | <code>ClientSideTeleporter.serverPassword</code> | the password with which to send requests to the Sling server. | no | <code>admin</code> | 1.0.8 | <a href="https://issues.apache.org/jira/
browse/SLING-5677">SLING-5677</a> | | <code>ClientSideTeleporter.enableLogging</code> | set to <code>true</code> to log the tasks being performed by the teleporter. Useful for debugging. | no | <code>false</code> | 1.0.12 | <a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> | | <code>ClientSideTeleporter.preventToUninstallBundle</code> | set to <code>true</code> to not automatically uninstall the test bundle after test execution. Useful for debugging. | no | <code>false</code> | 1.0.12 | <a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> | | <code>ClientSideTeleporter.testBundleDirectory</code> | if set the test bundles are being persisted (before being installed) within the given directory name. If the directory does not exist, it will be automatically created. Useful for debugging. Recommended value <code>${project.build.directory}/test-bundles</code>. | no | - | 1.0.12 | <a href="https://issues.apache.org/jira/browse/SLING-6546">SLING
-6546</a> |</p>
<p>The provisioning of an appropriate instance can be done with the <a href="/documentation/development/slingstart.html">slingstart-maven-plugin</a>. An example for that is given at <a href="https://svn.apache.org/viewvc/sling/trunk/testing/samples/module-with-it"><code>testing/samples/module-with-it</code></a>. Since <code>slingstart-maven-plugin</code> 1.5.0 it is possible to bootstrap a Sling Server from a <code>model.txt</code> below <code>src/test/provisioning</code> independent of the packaging (see <a href="https://issues.apache.org/jira/browse/SLING-6068">SLING-6068</a>).</p>
<h4>LaunchpadCustomizer</h4>
<p>The <em><a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/junit/teleporter/customizers/LaunchpadCustomizer.java"><code>LaunchpadCustomizer.java</code></a></em> only verifies that a Sling instance is ready at a given port and configures the <code>ClientSideTeleporter</code> to deploy to <code>http://localhost:8888</code> with the credentials <code>admin</code>:<code>admin</code>. <code>LaunchpadCustomizer</code> uses the <code>HttpTestBase</code> therefore some parameters are customizable through system properties. There is no bootstrapping of an instance done here, so this must be done separately!</p>
@@ -97,7 +214,7 @@ For tighter integration with Sling, the alternate `SlingJUnitServlet` is registe
<p>Those should give you an overview on what can be done with a customizer and decide whether you need to write your own one or using the default customizer is just enough.</p>
<h2>org.apache.sling.junit.healthcheck: run JUnit tests as Sling Health Checks</h2>
<p>This bundle allows JUnit tests to run as <a href="/documentation/bundles/sling-health-check-tool.html">Sling Health Checks</a>, which can be useful when defining smoke tests for example, allowing them to be used both at build time and run time.</p>
-<p>See the <code>JUnitHealthCheck</code> class for details.</p>
+<p>See the <code>JUnitHealthCheck</code> class for details. </p>
<h2>org.apache.sling.junit.scriptable: scriptable server-side tests</h2>
<p>This bundle allows Sling scripts to be executed from the <code>JUnitServlet</code> as JUnit tests, as follows:</p>
<ul>
@@ -106,14 +223,28 @@ For tighter integration with Sling, the alternate `SlingJUnitServlet` is registe
<li>To execute a test, the scriptable tests provider makes an HTTP request to the test node's path, with a <code>.test.txt</code> selector and extension, and expects the output to contain only the string <code>TEST_PASSED</code>. Empty lines and comment lines starting with a hash sign (#) are ignored in the output, and other lines are reported as failures.</li>
</ul>
<p>Here's a minimal example that sets up and executes a scriptable test:</p>
-<p>$ curl -u admin:admin -Fjcr:primaryNodeType=sling:Folder -Fsling:resourceType=foo -Fjcr:mixinTypes=sling:Test http://localhost:8080/apps/foo ... $ echo TEST_PASSED > /tmp/test.txt.esp ; curl -u admin:admin -T/tmp/test.txt.esp http://localhost:8080/apps/foo/test.txt.esp</p>
+<pre><code>$ curl -u admin:admin -Fjcr:primaryNodeType=sling:Folder -Fsling:resourceType=foo -Fjcr:mixinTypes=sling:Test http://localhost:8080/apps/foo
+...
+$ echo TEST_PASSED > /tmp/test.txt.esp ; curl -u admin:admin -T/tmp/test.txt.esp http://localhost:8080/apps/foo/test.txt.esp
+</code></pre>
<p>At this point, foo.test.txt is what the scriptable test framework will request, and that outputs just TEST_PASSED:</p>
-<p>$ curl -u admin:admin http://localhost:8080/apps/foo.test.txt TEST_PASSED</p>
+<pre><code>$ curl -u admin:admin http://localhost:8080/apps/foo.test.txt
+TEST_PASSED
+</code></pre>
<p>And a POST to the JUnit servlet returns information on the test's execution:</p>
-<p>curl -u admin:admin -XPOST http://localhost:8080/system/sling/junit/org.apache.sling.junit.scriptable.ScriptableTestsProvider.json [{ "INFO_TYPE": "test", "description": "verifyContent<a href="org.apache.sling.junit.scriptable.TestAllPaths">0</a>", "test_metadata": { "test_execution_time_msec": 2 } } ]</p>
-<p>Test failures would be included in this JSON representation - you can test that by modifying the script to fail and making the same request again.</p>
+<pre><code>curl -u admin:admin -XPOST http://localhost:8080/system/sling/junit/org.apache.sling.junit.scriptable.ScriptableTestsProvider.json
+[{
+ "INFO_TYPE": "test",
+ "description": "verifyContent[0](org.apache.sling.junit.scriptable.TestAllPaths)",
+ "test_metadata": {
+ "test_execution_time_msec": 2
+ }
+ }
+]
+</code></pre>
+<p>Test failures would be included in this JSON representation - you can test that by modifying the script to fail and making the same request again. </p>
<h2>org.apache.sling.junit.remote: obsolete</h2>
-<p>The <code>org.apache.sling.junit.remote</code> bundle provides utilities to run server-side JUnit tests, but using the newer <code>TeleporterRule</code> described above is much simpler. As a result, this bundle should only be needed for existing tests that were written using its mechanisms.</p></section></div></div>
+<p>The <code>org.apache.sling.junit.remote</code> bundle provides utilities to run server-side JUnit tests, but using the newer <code>TeleporterRule</code> described above is much simpler. As a result, this bundle should only be needed for existing tests that were written using its mechanisms. </p></section></div></div>
<div class="footer">
<div class="timestamp">
TODO display revision number here
http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/osgi-installer.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/osgi-installer.html b/documentation/bundles/osgi-installer.html
index cffd0da..21a2fd6 100644
--- a/documentation/bundles/osgi-installer.html
+++ b/documentation/bundles/osgi-installer.html
@@ -2,22 +2,22 @@
<head>
<meta charset="utf-8"/>
<title>Apache Sling on JBake</title>
- <link rel="stylesheet" href="/res/css/site.css"/>
- <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <link rel="stylesheet" href="/ng/res/css/site.css"/>
+ <link rel="icon" href="/ng/res/favicon.ico"/>
<div class="title">
<div class="logo">
<a href="http://sling.apache.org">
- <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/>
</a>
</div><div class="header">
<a href="http://www.apache.org">
- <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/>
</a>
</div>
</div>
</head><body>
<div class="menu">
- <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/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://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p
><strong>Project info</strong><br/><a href="/ng/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/ng/contributing.html">Contributing</a><br/><a href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a href="/ng/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.
org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong>
</div> <div class="main">
<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>OSGi Installer</h1></header><h1>Overview</h1>
<p>The OSGi installer is a central service for handling installs, updates and uninstall of "artifacts". By default, the installer supports bundles and has an extension for handling configurations for the OSGi configuration admin.</p>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html b/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
index 169db1f..763afa5 100644
--- a/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
+++ b/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
@@ -2,22 +2,22 @@
<head>
<meta charset="utf-8"/>
<title>Apache Sling on JBake</title>
- <link rel="stylesheet" href="/res/css/site.css"/>
- <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <link rel="stylesheet" href="/ng/res/css/site.css"/>
+ <link rel="icon" href="/ng/res/favicon.ico"/>
<div class="title">
<div class="logo">
<a href="http://sling.apache.org">
- <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/>
</a>
</div><div class="header">
<a href="http://www.apache.org">
- <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/>
</a>
</div>
</div>
</head><body>
<div class="menu">
- <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/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://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p
><strong>Project info</strong><br/><a href="/ng/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/ng/contributing.html">Contributing</a><br/><a href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a href="/ng/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</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="https://donate.apache.
org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong>
</div> <div class="main">
<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Output Rewriting Pipelines (org.apache.sling.rewriter)</h1></header><p>The Apache Sling Rewriter is a module for rewriting the output generated by a usual Sling rendering process. Some possible use cases include rewriting or checking all links in an HTML page, manipulating the HTML page, or using the generated output as the base for further transformation. An example of further transformation is to use XSLT to transform rendered XML to some output format like HTML or XSL:FO for generating PDF.</p>
<p>For supporting these use cases, the rewriter uses the concept for a processor. The processor is a component that is injected through a servlet filter into the response. By implementing the <em>Processor</em> interface one is able to rewrite the whole response in one go. A more convenient way of processing the output is by using a so called pipeline; the Apache Sling rewriter basically uses the same concept as the famous Apache Cocoon: an XML based pipeline for further post processing of the output. The pipeline is based on SAX events.</p>
@@ -26,7 +26,7 @@
<p>As the pipeline is based on SAX events, there needs to be a component that generates these events and sends them through the pipeline. By default the Sling rendering scripts write to an output stream, so there is a need to parse this output and generate the SAX events.</p>
<p>The first component in the pipeline generating the initial SAX events is called a generator. The generator gets the output from Sling, generates SAX events (XML), and streams these events into the pipeline. The counterpart of the generator is the serializer which builds the end of the pipeline. The serializer collects all incomming SAX events, transforms them into the required response by writing into output stream of the response.</p>
<p>Between the generator and the serializer so called transformers can be placed in a chain. A transformer receives SAX events from the previous component in the pipeline and sends SAX events to the next component in the pipeline. A transformer can remove events, change events, add events or just pass on the events.</p>
-<p>Sling contains a default pipeline which is executed for all HTML responses: it starts with an HTML generator, parsing the HTML output and sending events into the pipeline. An HTML serializer collects all events and serializes the output.</p>
+<p>Sling contains a default pipeline which is executed for all HTML responses: it starts with an HTML generator, parsing the HTML output and sending events into the pipeline. An HTML serializer collects all events and serializes the output. </p>
<p>The pipelines can be configured in the repository as a child node of <em>/apps/APPNAME/config/rewriter</em> (or <em>/libs/APPNAME/config/rewriter</em>). (In fact the configured search paths of the resource resolver are observed.) Each node can have the following properties:</p>
<ul>
<li>generatorType - the type of the generator (required)</li>
@@ -47,19 +47,32 @@
<p>The default pipeline is configured for the <em>text/html</em> mime type and the <em>html</em> extensions and consists of the <em>html-generator</em> as the generator, and the <em>html-serializer</em> for generating the final response. As the HTML generated by Sling is not required to be valid XHTML, the HTML parser is using an HTML parser to create valid SAX events. In order to perform this, the generator needs to buffer the whole response first.</p>
<h2>Implementing Pipeline Components</h2>
<p>Each pipeline component type has a corresponding Java interface (Generator, Transformer, and Serializer) together with a factory interface (GeneratorFactory, TransformerFactory, and SerializerFactory). When implementing such a component, both interfaces need to be implemented. The factory has only one method which creates a new instance of that type for the current request. The factory has to be registered as a service. For example if you're using the Maven SCR plugin, it looks like this:</p>
-<p>::java @scr.component metatype="no" @scr.service interface="TransformerFactory" @scr.property value="pipeline.type" value="validator"</p>
+<pre><code>::java
+@scr.component metatype="no"
+@scr.service interface="TransformerFactory"
+@scr.property value="pipeline.type" value="validator"
+</code></pre>
<p>The factory needs to implement the according interface and should be registered as a service for this factory interface (this is a plain service and not a factory service in the OSGi sense). Each factory gets a unique name through the <em>pipeline.type</em> property. The pipeline configuration in the repository just references this unique name (like validator).</p>
<h2>Extending the Pipeline</h2>
<p>With the possibilities from above, it is possible to define new pipelines and add custom components to the pipeline. However, in some cases it is required to just add a custom transformer to the existing pipeline. Therefore the rewriting can be configured with pre and post transformers that are simply added to each configured pipeline. This allows a more flexible way of customizing the pipeline without changing/adding a configuration in the repository.</p>
<p>The approach here is nearly the same. A transformer factory needs to be implemented, but instead of giving this factory a unique name, this factory is marked as a global factory:</p>
-<p>::java @scr.component metatype="no" @scr.service interface="TransformerFactory" @scr.property name="pipeline.mode" value="global" @scr.property name="service.ranking" value="RANKING" type="Integer"</p>
+<pre><code>::java
+@scr.component metatype="no"
+@scr.service interface="TransformerFactory"
+@scr.property name="pipeline.mode" value="global"
+@scr.property name="service.ranking" value="RANKING" type="Integer"
+</code></pre>
<p><em>RANKING</em> is an integer value (don't forget the type attribute otherwise the ranking is interpreted as zero!) specifying where to add the transformer in the pipeline. If the value is less than zero the transformer is added at the beginning of the pipeline right after the generator. If the ranking is equal or higher as zero, the transformer is added at the end of the pipeline before the serializer.</p>
<p>The <em>TransformerFactory</em> interface has just one method which returns a new transformer instance. If you plan to use other services in your transformer you might declare the references on the factory and pass in the instances into the newly created transformer.</p>
<p>Since the transformer carries information about the current response it is not advisable to reuse the same transformer instance among multiple calls of <code>TransformerFactory.createTransformer</code>.</p>
<h2>Implementing a Processor</h2>
<p>A processor must conform to the Java interface <em>org.apache.sling.rewriter.Processor</em>. It gets initializd (method <em>init</em>) with the <em>ProcessingContext</em>. This context contains all necessary information for the current request (especially the output writer to write the rewritten content to). The <em>getWriter</em> method should return a writer where the output is written to. When the output is written or an error occured <em>finished</em> is called.</p>
<p>Like the pipeline components a processor is generated by a factory which has to be registered as a service factory, like this:</p>
-<p>::java @scr.component metatype="no" @scr.service interface="ProcessorFactory" @scr.property value="pipeline.type" value="uniqueName"</p>
+<pre><code>::java
+@scr.component metatype="no"
+@scr.service interface="ProcessorFactory"
+@scr.property value="pipeline.type" value="uniqueName"
+</code></pre>
<h2>Configuring a Processor</h2>
<p>The processors can be configured in the repository as a child node of <em>/apps/APPNAME/config/rewriter</em> (or libs or any configured search path). Each node can have the following properties:</p>
<ul>