http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/development/sling-mock.html ---------------------------------------------------------------------- diff --git a/documentation/development/sling-mock.html b/documentation/development/sling-mock.html index a2acccb..927cb2e 100644 --- a/documentation/development/sling-mock.html +++ b/documentation/development/sling-mock.html @@ -75,9 +75,8 @@ </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>Mock implementation of selected Sling APIs for easier testing.</p> <p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Maven Dependency</h2> -<pre><code>#!xml -<dependency> +<h2><a href="#maven-dependency" name="maven-dependency">Maven Dependency</a></h2> +<pre><code><!-- TODO syntax marker (#!xml) disabled --><dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.testing.sling-mock</artifactId> </dependency> @@ -88,7 +87,7 @@ <li>sling-mock 1.x: compatible with older Sling versions from 2014 (Sling API 2.4 and above)</li> <li>sling-mock 2.x: compatible with Sling versions from 2016 (Sling API 2.11 and above)</li> </ul> -<h2>Implemented mock features</h2> +<h2><a href="#implemented-mock-features" name="implemented-mock-features">Implemented mock features</a></h2> <p>The mock implementation supports:</p> <ul> <li><code>ResourceResolver</code> implementation for reading and writing resource data using the Sling Resource API @@ -121,7 +120,7 @@ </ul> </li> </ul> -<h3>Additional features</h3> +<h3><a href="#additional-features" name="additional-features">Additional features</a></h3> <p>Additional features provided:</p> <ul> <li><code>SlingContext</code> JUnit Rule for easily setting up a Sling Mock environment in your JUnit test cases</li> @@ -132,12 +131,11 @@ </li> <li><code>ContentBuilder</code> and <code>ResourceBuilder</code> make it easier to create resources and properties as test fixture</li> </ul> -<h2>Usage</h2> -<h3>Sling Context JUnit Rule</h3> +<h2><a href="#usage" name="usage">Usage</a></h2> +<h3><a href="#sling-context-junit-rule" name="sling-context-junit-rule">Sling Context JUnit Rule</a></h3> <p>The Sling mock context can be injected into a JUnit test using a custom JUnit rule named <code>SlingContext</code>. This rules takes care of all initialization and cleanup tasks required to make sure all unit tests can run independently (and in parallel, if required).</p> <p>Example:</p> -<pre><code>#!java -public class ExampleTest { +<pre><code><!-- TODO syntax marker (#!java) disabled -->public class ExampleTest { @Rule public final SlingContext context = new SlingContext(); @@ -166,10 +164,9 @@ public class ExampleTest { <li>Registering adapter factories</li> <li>Accessing ContentLoader, and ContentBuilder and ResourceBuilder</li> </ul> -<h3>Choosing Resource Resolver Mock Type</h3> +<h3><a href="#choosing-resource-resolver-mock-type" name="choosing-resource-resolver-mock-type">Choosing Resource Resolver Mock Type</a></h3> <p>The Sling mock context supports different resource resolver types. Example:</p> -<pre><code>#!java -public class ExampleTest { +<pre><code><!-- TODO syntax marker (#!java) disabled -->public class ExampleTest { @Rule public final SlingContext context = new SlingContext(ResourceResolverType.RESOURCERESOLVER_MOCK); @@ -177,7 +174,7 @@ public class ExampleTest { } </code></pre> <p>Different resource resolver mock types are supported with pros and cons, see next chapter for details.</p> -<h3>Resource Resolver Types</h3> +<h3><a href="#resource-resolver-types" name="resource-resolver-types">Resource Resolver Types</a></h3> <p>The Sling Mocks resource resolver implementation supports different "types" of adapters for the mocks. Depending on the type an underlying JCR repository is used or not, and the data is stored in-memory or in a real repository.</p> <p>Resource resolver types currently supported:</p> <p><strong>RESOURCERESOLVER_MOCK (default)</strong></p> @@ -210,8 +207,7 @@ public class ExampleTest { <li>Lucene indexing is not included, thus fulltext search queries will return no result</li> </ul> <p>To use this type you have to declare an additional dependency in your test project:</p> -<pre><code>#!xml -<dependency> +<pre><code><!-- TODO syntax marker (#!xml) disabled --><dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.testing.sling-mock-oak</artifactId> <scope>test</scope> @@ -227,8 +223,7 @@ public class ExampleTest { <li>Node types defined in OSGi bundle header 'Sling-Nodetypes' found in MANIFEST.MF files in the classpath are registered automatically.</li> </ul> <p>To use this type you have to declare an additional dependency in your test project:</p> -<pre><code>#!xml -<dependency> +<pre><code><!-- TODO syntax marker (#!xml) disabled --><dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.testing.sling-mock-jackrabbit</artifactId> <scope>test</scope> @@ -240,21 +235,19 @@ public class ExampleTest { <li>The repository is not cleared for each unit test, so make sure to use a unique node path for each unit test. You may use the <code>uniquePath()</code> helper object of the SlingContext rule for this.</li> <li>The <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/commons/testing";>sling/commons/testing</a> dependency introduces a lot of further dependencies from jackrabbit and others, be careful that they do not conflict and are imported in the right order in your test project</li> </ul> -<h3>Sling Resource Resolver</h3> +<h3><a href="#sling-resource-resolver" name="sling-resource-resolver">Sling Resource Resolver</a></h3> <p>Example:</p> -<pre><code>#!java -// get a resource resolver +<pre><code><!-- TODO syntax marker (#!java) disabled -->// get a resource resolver ResourceResolver resolver = MockSling.newResourceResolver(); // get a resource resolver backed by a specific repository type ResourceResolver resolver = MockSling.newResourceResolver(ResourceResolverType.JCR_MOCK); </code></pre> <p>If you use the <code>SlingContext</code> JUnit rule you case just use <code>context.resourceResolver()</code>.</p> -<h3>Adapter Factories</h3> +<h3><a href="#adapter-factories" name="adapter-factories">Adapter Factories</a></h3> <p>You can register your own or existing adapter factories to support adaptions e.g. for classes extending <code>SlingAdaptable</code>.</p> <p>Example:</p> -<pre><code>#!java -// register adapter factory +<pre><code><!-- TODO syntax marker (#!java) disabled -->// register adapter factory BundleContext bundleContext = MockOsgi.newBundleContext(); MockSling.setAdapterManagerBundleContext(bundleContext); bundleContext.registerService(myAdapterFactory); @@ -267,10 +260,9 @@ MockSling.clearAdapterManagerBundleContext(); </code></pre> <p>Make sure you clean up the adapter manager bundle association after running the unit test otherwise it can interfere with the following tests. If you use the <code>SlingContext</code> JUnit rule this is done automatically for you.</p> <p>If you use the <code>SlingContext</code> JUnit rule you case just use <code>context.registerService()</code>.</p> -<h3>SlingScriptHelper</h3> +<h3><a href="#slingscripthelper" name="slingscripthelper">SlingScriptHelper</a></h3> <p>Example:</p> -<pre><code>#!java -// get script helper +<pre><code><!-- TODO syntax marker (#!java) disabled -->// get script helper SlingScriptHelper scriptHelper = MockSling.newSlingScriptHelper(); // get request @@ -281,10 +273,9 @@ MyService object = scriptHelper.getService(MyService.class); </code></pre> <p>To support getting OSGi services you have to register them via the <code>BundleContext</code> interface of the <a href="/documentation/development/jcr-mock.html">JCR Mocks</a> before. You can use an alternative factory method for the <code>SlingScriptHelper</code> providing existing instances of request, response and bundle context. </p> <p>If you use the <code>SlingContext</code> JUnit rule you case just use <code>context.slingScriptHelper()</code>.</p> -<h3>SlingHttpServletRequest</h3> +<h3><a href="#slinghttpservletrequest" name="slinghttpservletrequest">SlingHttpServletRequest</a></h3> <p>Example for preparing a sling request with custom request data:</p> -<pre><code>#!java -// prepare sling request +<pre><code><!-- TODO syntax marker (#!java) disabled -->// prepare sling request ResourceResolver resourceResolver = MockSling.newResourceResolver(); MockSlingHttpServletRequest request = new MockSlingHttpServletRequest(resourceResolver); @@ -317,10 +308,9 @@ request.addHeader("header1", "value1"); // set cookies request.addCookie(new Cookie("cookie1", "value1")); </code></pre> -<h3>SlingHttpServletResponse</h3> +<h3><a href="#slinghttpservletresponse" name="slinghttpservletresponse">SlingHttpServletResponse</a></h3> <p>Example for preparing a sling response which can collect the data that was written to it:</p> -<pre><code>#!java -// prepare sling response +<pre><code><!-- TODO syntax marker (#!java) disabled -->// prepare sling response MockSlingHttpServletResponse response = new MockSlingHttpServletResponse(); // execute your unit test code that writes to the response... @@ -343,7 +333,7 @@ assertEquals(TEST_CONTENT, response.getOutputAsString()); // validate response body as binary data assertArrayEquals(TEST_DATA, response.getOutput()); </code></pre> -<h3>Import resource data from JSON file in classpath</h3> +<h3><a href="#import-resource-data-from-json-file-in-classpath" name="import-resource-data-from-json-file-in-classpath">Import resource data from JSON file in classpath</a></h3> <p>With the <code>ContentLoader</code> it is possible to import structured resource and property data from a JSON file stored in the classpath beneath the unit tests. This data can be used as text fixture for unit tests.</p> <p>Example JSON data:</p> <pre><code>#!json @@ -369,18 +359,16 @@ assertArrayEquals(TEST_DATA, response.getOutput()); } </code></pre> <p>Example code to import the JSON data:</p> -<pre><code>#!java -context.load().json("/sample-data.json", "/content/sample/en"); +<pre><code><!-- TODO syntax marker (#!java) disabled -->context.load().json("/sample-data.json", "/content/sample/en"); </code></pre> <p>This codes creates a new resource at <code>/content/sample/en</code> (and - if not existent - the parent resources) and imports the JSON data to this node. It can be accessed using the Sling Resource or JCR API afterwards.</p> -<h3>Import binary data from file in classpath</h3> +<h3><a href="#import-binary-data-from-file-in-classpath" name="import-binary-data-from-file-in-classpath">Import binary data from file in classpath</a></h3> <p>With the <code>ContentLoader</code> it is possible to import a binary file stored in the classpath beneath the unit tests. The data is stored using a nt:file/nt:resource or nt:resource node type. </p> <p>Example code to import a binary file:</p> -<pre><code>#!java -context.load().binaryFile("/sample-file.gif", "/content/binary/sample-file.gif"); +<pre><code><!-- TODO syntax marker (#!java) disabled -->context.load().binaryFile("/sample-file.gif", "/content/binary/sample-file.gif"); </code></pre> <p>This codes creates a new resource at <code>/content/binary/sample-file.gif</code> (and - if not existent - the parent resources) and imports the binary data to a jcr:content subnode.</p> -<h3>Building content</h3> +<h3><a href="#building-content" name="building-content">Building content</a></h3> <p>Sling Mocks provides two alterantives for quickly building test content in the repository with as few code as possible. Sling Mocks provides two alternatives. Both are quite similar in their results, but follow different API concepts. You can choose whatever matches your needs and mix them as well.</p> <ul> <li><code>ContentBuilder</code>: Part of Sling Mocks since its first release. If you need a references to each created resource this is the easiest way.</li> @@ -389,15 +377,13 @@ context.load().binaryFile("/sample-file.gif", "/content/binary/sa <h4>Building content using <code>ContentBuilder</code></h4> <p>The entry point for the <code>ContentBuilder</code> is the <code>create()</code> method on the Sling context.</p> <p>Example:</p> -<pre><code>#!java -context.create().resource("/content/test1", ImmutableMap.<String, Object>builder() +<pre><code><!-- TODO syntax marker (#!java) disabled -->context.create().resource("/content/test1", ImmutableMap.<String, Object>builder() .put("prop1", "value1") .put("prop2", "value2") .build()); </code></pre> <p>Simplified syntax without using a map:</p> -<pre><code>#!java -context.create().resource("/content/test1", +<pre><code><!-- TODO syntax marker (#!java) disabled -->context.create().resource("/content/test1", "prop1", "value1", "prop2", "value2"); </code></pre> @@ -405,21 +391,19 @@ context.create().resource("/content/test1", <h4>Building content using <code>ResourceBuilder</code></h4> <p>The entry point for the <code>ResourceBuilder</code> is the <code>build()</code> method on the Sling context.</p> <p>Example:</p> -<pre><code>#!java -context.build().resource("/content/test1") +<pre><code><!-- TODO syntax marker (#!java) disabled -->context.build().resource("/content/test1") .siblingsMode() .resource("test1.1", "stringParam", "configValue1.1") .resource("test1.2", "stringParam", "configValue1.2") .resource("test1.2", "stringParam", "configValue1.3"); </code></pre> <p>See JavaDocs of the class <code>org.apache.sling.resourcebuilder.api.ResourceBuilder</code> for a detailed documentation.</p> -<h3>Context Plugins</h3> +<h3><a href="#context-plugins" name="context-plugins">Context Plugins</a></h3> <p>Sling Mocks supports "Context Plugins" that hook into the lifecycle of each test run and can prepare test setup before or after the other setUp actions, and execute test tear down code before or after the other tearDown action.</p> <p>To define a plugin implement the <code>org.apache.sling.testing.mock.osgi.context.ContextPlugin<SlingContextImpl></code> interface. For convenience it is recommended to extend the abstract class <code>org.apache.sling.testing.mock.osgi.context.AbstractContextPlugin<SlingContextImpl></code>. These plugins can be used with Sling Mock context, but also with context instances deriving from it like AEM Mocks. In most cases you would just override the <code>afterSetUp</code> method. In this method you can register additional OSGi services or do other preparation work. It is recommended to define a constant pointing to a singleton of a plugin instance for using it.</p> <p>To use a plugin in your unit test class, use the <code>SlingContextBuilder</code> class instead of directly instantiating the <code>SlingContext</code>class. This allows you in a fluent style to configure more options, with the <code>plugin(...)</code> method you can add one or more plugins.</p> <p>Example: </p> -<pre><code>#!java -@Rule +<pre><code><!-- TODO syntax marker (#!java) disabled -->@Rule public SlingContext context = new SlingContextBuilder().plugin(MY_PLUGIN).build(); </code></pre> <p>More examples:</p>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/development/sling-testing-tools.html ---------------------------------------------------------------------- diff --git a/documentation/development/sling-testing-tools.html b/documentation/development/sling-testing-tools.html index 1c02370..0d5deff 100644 --- a/documentation/development/sling-testing-tools.html +++ b/documentation/development/sling-testing-tools.html @@ -87,9 +87,9 @@ in the newer "Junit Server-Side Tests Support" page instead, see link below. <p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests";>testing/samples/integration-tests</a> module demonstrates these tools, and is also meant as a sample project to show how to run integration tests for Sling-based applications.</p> <p>The main Sling integration tests at <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests";>launchpad/integration-tests</a> were created before this testing framework, and do not use it yet (as of March 2011). The new testing tools are simpler to use, but the "old" tests (all 400 of them as I write this) fulfill their validation role for testing Sling itself, there's no real need to modify them to use the new tools.</p> <p>See also <a href="/documentation/tutorials-how-tos/testing-sling-based-applications.html">Testing Sling-based applications</a> which discusses testing in general.</p> -<h2>Required bundles</h2> +<h2><a href="#required-bundles" name="required-bundles">Required bundles</a></h2> <p>These tools require a number of bundles on top of the standard Sling launchpad. See the <a href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests/pom.xml";>sample tests pom.xml</a> for an up-to-date list. Look for <code>sling.additional.bundle.*</code> entries in that pom for the bundle artifact IDs, and see the <code>dependencies</code> section for their version numbers.</p> -<h1>Server-side JUnit tests contributed by bundles</h1> +<h1><a href="#server-side-junit-tests-contributed-by-bundles" name="server-side-junit-tests-contributed-by-bundles">Server-side JUnit tests contributed by bundles</a></h1> <p>The services provided by the <a href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/core";>org.apache.sling.junit.core</a> bundle allow bundles to register JUnit tests, which are executed server-side by the JUnitServlet registered by default at <code>/system/sling/junit</code>. This bundle is not dependent on Sling, it should work in other OSGi environments.</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. @@ -102,9 +102,9 @@ For tighter integration with Sling, the alternate `SlingJUnitServlet` is registe <p>To list the available tests, open http://localhost:8080/system/sling/junit/ . 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 http://localhost:8080/system/sling/junit/org.apache.sling.junit.remote.html - the example integration tests described below use this to selectively execute server-side tests. The JUnitServlet provides various output formats, including in particular JSON, see http://localhost:8080/system/sling/junit/.json for example.</p> <p>To supply tests from your own bundles, simply export the tests classes and add the <code>Sling-Test-Regexp</code> header to the bundle so that the Sling JUnit core services register them as tests.</p> -<h3>Injection of OSGi services</h3> +<h3><a href="#injection-of-osgi-services" name="injection-of-osgi-services">Injection of OSGi services</a></h3> <p>The <code>@TestReference</code> annotation is used to inject OSGi services in tests that are executed server side.The <code>BundleContext</code> can also be injected in this way.</p> -<h2>Curl examples</h2> +<h2><a href="#curl-examples" name="curl-examples">Curl examples</a></h2> <p>Here's an example executing a few tests using curl:</p> <pre><code>$ curl -X POST http://localhost:8080/system/sling/junit/org.apache.sling.testing.samples.sampletests.JUnit.json [{ @@ -122,7 +122,7 @@ For tighter integration with Sling, the alternate `SlingJUnitServlet` is registe <p>And another example with a test that fails:</p> <pre><code>$ curl -X POST http://localhost:8080/system/sling/junit/org.apache.sling.testing.samples.failingtests.JUnit4FailingTest.json </code></pre> -<h1>Scriptable server-side tests</h1> +<h1><a href="#scriptable-server-side-tests" name="scriptable-server-side-tests">Scriptable server-side tests</a></h1> <p>If the <a href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/scriptable";>org.apache.sling.junit.scriptable</a> bundle is active in a Sling system, (in addition to the <code>org.apache.sling.junit.core</code> bundle), scriptable tests can be executed by the <code>JUnitServlet</code> according to the following rules:</p> <ul> <li>A node that has the <code>sling:Test</code> mixin is a scriptable test node.</li> @@ -151,7 +151,7 @@ TEST_PASSED ] </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> -<h1>Integration tests example</h1> +<h1><a href="#integration-tests-example" name="integration-tests-example">Integration tests example</a></h1> <p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests";>testing/samples/integration-tests</a> module runs some simple integration tests against a Sling Launchpad instance that's setup from scratch before running the tests.</p> <p>This module's pom and Java code can be used as examples to setup your own integration testing modules for Sling-based apps - or for any other runnable jar that provides an http service.</p> <p>Besides serving as examples, some of the tests in this module are used to validate the testing tools. They run as part of the full Sling <a href="/project-information.html">continuous integration</a> build, so they're guaranteed to be correct examples if that build is successful.</p> @@ -168,19 +168,19 @@ TEST_PASSED <li>The test results are reported via the usual Maven mechanisms.</li> </ol> <p>If <code>-DkeepJarRunning</code> is used on the Maven command line, the Sling runnable jar does not exit, to allow for running individual tests against this instance, for example when debugging the tests or the server code. See the pom for details.</p> -<h2>Running tests against existing server</h2> +<h2><a href="#running-tests-against-existing-server" name="running-tests-against-existing-server">Running tests against existing server</a></h2> <p>Instead of provisioning a completely new Sling server, the ITs can also be executed on an already existing server instance. For that the <code>test-server-url</code> system property has to point to the existing server url. Additional bundles can still be deployed by using the <code>sling.additional.bundle.<num></code> system property.</p> <p>Optionally, the additional bundles can be undeployed after the execution of the IT by setting <code>additional.bundles.uninstall</code> to <code>true</code>. (since Sling Testing Tools 1.0.12, <a href="https://issues.apache.org/jira/browse/SLING-4819";>SLING-4819</a>)</p> -<h1>Remote test execution</h1> +<h1><a href="#remote-test-execution" name="remote-test-execution">Remote test execution</a></h1> <p>The testing tools support two types of remote test execution.</p> -<h2>SlingRemoteTestRunner</h2> +<h2><a href="#slingremotetestrunner" name="slingremotetestrunner">SlingRemoteTestRunner</a></h2> <p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/testrunner/SlingRemoteTestRunner.java";>SlingRemoteTestRunner</a> is used to run tests using the <code>JUnitServlet</code> described above. In this case, the client-side JUnit test only defines which tests to run and some optional assertions. Checking the number of tests executed, for example, can be useful to make sure all test bundles have been activated as expected, to avoid ignoring missing test bundles.</p> <p>See the <a href="https://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests/src/test/java/org/apache/sling/testing/samples/integrationtests/serverside/ServerSideSampleTest.java";>ServerSideSampleTest</a> class for an example.</p> <p>It's a good idea to check that the JUnit servlet is ready before running those tests, see the <a href="https://svn.apache.org/repos/asf/sling/trunk/testing/samples/integration-tests/src/test/java/org/apache/sling/testing/samples/integrationtests/serverside/sling/SlingServerSideTestsBase.java";>ServerSideTestsBase</a> for an example of how to do that.</p> -<h2>SlingRemoteExecutionRule</h2> +<h2><a href="#slingremoteexecutionrule" name="slingremoteexecutionrule">SlingRemoteExecutionRule</a></h2> <p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/ide/SlingRemoteExecutionRule.java";>SlingRemoteExecutionRule</a> is a JUnit Rule that allows tests to be executed remotely in a Sling instance from an IDE, assuming the test is available on both sides.</p> <p>The <a href="https://svn.apache.org/repos/asf/sling/trunk/testing/junit/remote/src/main/java/org/apache/sling/junit/remote/exported/ExampleRemoteTest.java";>ExampleRemoteTest</a> class demonstrates this. To run it from your IDE, set the <code>sling.remote.test.url</code> in the IDE to the URL of the JUnitServlet, like http://localhost:8080/system/sling/junit for example.</p> -<h1>Debugging ITs</h1> +<h1><a href="#debugging-its" name="debugging-its">Debugging ITs</a></h1> <p>The JVM is usually forked twice during the execution of integration tests. The first time by the <code>maven-surefire-plugin</code> which executes the client-side (i.e. Maven-side) part of the tests. To debug this side the option <code>-Dmaven.surefire.debug</code> can be used which waits for a debugger to be attached on port 5005 before the (client-side) test is executed. More information is available in the <a href="http://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html";>documentation of the maven-surefire-plugin</a>.</p> <p>Then the <code>JarExecutor</code> is forking the VM a second time to start the server (this does not happen if connecting to an already running instance). The system environment variable <code>jar.executor.vm.options</code> can be used to start that VM with debug options. All debug options are described at the <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation";>JPDA documentation</a>. If running </p> <pre><code>mvn test -Djar.executor.vm.options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000" http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/development/slingstart.html ---------------------------------------------------------------------- diff --git a/documentation/development/slingstart.html b/documentation/development/slingstart.html index d1f7f4b..c9c96be 100644 --- a/documentation/development/slingstart.html +++ b/documentation/development/slingstart.html @@ -77,7 +77,7 @@ <p>The Apache Sling provisioning model is a model to describe OSGi based application. It can also be used to define a partial application aka feature (or subsystem in OSGi terms).</p> <p>The model is describing an instance, it is not directly related to any particular tooling or packaging/provisioning vehicle.</p> <p>For Apache Maven users, the <code>slingstart-maven-plugin</code> uses the model to create an executable application and/or a web application based on the model. Sling's Launchpad is defined using the model and built by this Maven plugin. See <a href="http://sling.apache.org/components/slingstart-maven-plugin/";>SlingStart Maven Plugin</a> for a documentation of the supported goals and parameters.</p> -<h2>The Model</h2> +<h2><a href="#the-model" name="the-model">The Model</a></h2> <p>The model is a simple API consisting of data objects:</p> <ul> <li>Model: This is the central object. It consists of features.</li> @@ -89,7 +89,7 @@ <li>Configuration: A OSGi configuration</li> <li>Settings : Framework settings for the OSGi framework</li> </ul> -<h3>Run Modes</h3> +<h3><a href="#run-modes" name="run-modes">Run Modes</a></h3> <p>The default run mode is always active, and all information provided there will be used/started. Custom run modes can be used to configure for different situations. Depending on which run mode is used to start the instance a different set of artifacts or configurations is used. Each run mode is associated with a set of run mode names. Only if all listed run modes are active, the definition is used.</p> <p>The model also supports special run modes, which have special meaning. By default, these pre defined special run modes are available:</p> <ul> @@ -97,9 +97,9 @@ <li>:webapp Artifacts for the webapp only</li> </ul> <p>Other special run modes can be defined by using a single run mode name which starts with a colon, like :test. These run modes can be used by special tooling.</p> -<h3>Start Levels</h3> +<h3><a href="#start-levels" name="start-levels">Start Levels</a></h3> <p>Each run mode has start levels. These start levels correspond to OSGi start levels. The default start level has the level 0 and should be used for all non bundle artifacts. If a non bundle artifact is configured with a start level, it's still provisioned, however the start level information might not have any meaning. As usually the provisioned artifacts are bundles and as start levels are pretty handy, this was conscious design decision in order to keep the model files small.</p> -<h3>Artifacts</h3> +<h3><a href="#artifacts" name="artifacts">Artifacts</a></h3> <p>An artifact is defined by Maven coordinates, that is group id, artifact id and version. Type and classifier can be specified, too. Type defaults to "jar". Although the maven way of referring to an artifact is used, the model is in no way tied to Maven and can be used with any tooling. For a plain jar the text definition for an artifact is:</p> <pre><code> groupId/artifactId/version org.apache.sling/api/2.8.0 @@ -112,14 +112,14 @@ <pre><code> groupId/artifactId/version/type/classifier org.apache.sling/api/2.8.0/jar/test </code></pre> -<h3>Configurations</h3> +<h3><a href="#configurations" name="configurations">Configurations</a></h3> <p>A configuration has a pid, or a factory pid and an alias and of course the properties of the configuration object.</p> <p>Special configurations can be marked with a leading ":" of the pid. Special configurations are not added to the OSGi config admin. There are some predefined special configurations</p> <ul> <li>:web.xml This configuration must be part of the :webapp runmode and contains a complete web.xml for the web application</li> <li>:bootstrap This configuration must be part of either the :boot, :base, :standalone, or :webapp run mode and define the contents for the bootstrap command file executed by Launchpad.</li> </ul> -<h4>Bootstrap Command File</h4> +<h4><a href="#bootstrap-command-file" name="bootstrap-command-file">Bootstrap Command File</a></h4> <p>The bootstrap configuration is a text block consisting of uninstall directives. This block is only executed on the first startup.</p> <pre><code>[feature name=:launchpad] @@ -132,15 +132,15 @@ uninstall org.apache.sling.tests </code></pre> <p>Each uninstall directive starts with the text "uninstall" followed by the bundle symbolic name. A version range can be specified as well. If no version information is specified, the bundle with that symbolic name is uninstalled on startup. If a version is specified, the bundle is only uninstalled if it's installed with the exact same version. If a range is specified, the bundle is only uninstalled, if the version is within that range.</p> -<h3>Settings</h3> +<h3><a href="#settings" name="settings">Settings</a></h3> <p>Settings are key value pairs that are added to the framework properties. For now, only settings for the run modes :boot, :base, :standalone, or :webapp are supported.</p> -<h3>Features</h3> +<h3><a href="#features" name="features">Features</a></h3> <p>Features group run modes and define a special functionality. The model also defines two special features:</p> <ul> <li>:launchpad This feature contains the dependency to Sling's launchpad artifact to be used. This mode is required if Apache Sling Launchpad should be used to start the application.</li> <li>:boot The artifacts that are installed before the framework is started. They're used to bootstrap the system.</li> </ul> -<h2>Model Files</h2> +<h2><a href="#model-files" name="model-files">Model Files</a></h2> <p>The model comes also with a textual description language:</p> <pre><code>[feature name=my-feature] [variables] @@ -174,9 +174,9 @@ useQueue=true ignoreTopics=["myTopic"] </code></pre> -<h3>Comments</h3> +<h3><a href="#comments" name="comments">Comments</a></h3> <p>Each object in the model can be annotated with comments. A comment is a line starting with a '#'. Leading spaces are ignored.</p> -<h3>Configurations in the Model file</h3> +<h3><a href="#configurations-in-the-model-file" name="configurations-in-the-model-file">Configurations in the Model file</a></h3> <p>Configuration names are related to the PID and factory PID. The structure of the name is as follows:</p> <pre><code>name ::= <pid> ( '-' <subname> ) </code></pre> @@ -187,7 +187,7 @@ com.acme.xyz // # Managed Service Factory, creates an instance for com.acme.abc com.acme.abc-default </code></pre> -<h3>Default Configuration Format</h3> +<h3><a href="#default-configuration-format" name="default-configuration-format">Default Configuration Format</a></h3> <p>Configurations use by default the format of the Apache Felix ConfigAdmin implementation. It allows to specify the type and cardinality of a configuration property and is not limited to string values.</p> <p>The first line of such a file might start with a comment line (a line starting with a #). Comments within the file are not allowed.</p> <p>The format is:</p> @@ -216,13 +216,13 @@ stringsimple ::= <quoted string representation of the value> (see below) <li>'B' : Boolean</li> </ul> <p>Apart from the escaping of the usual characters like the quotes, double quotes, backslash etc. the equals sign and spaces need to be escaped as well!</p> -<h3>Configurations Defined through Properties</h3> +<h3><a href="#configurations-defined-through-properties" name="configurations-defined-through-properties">Configurations Defined through Properties</a></h3> <p>While the default configuration form is very powerful, it might also sometimes be a little bit too heavy to specify a configuration. For these usage cases, the configuration can be described as properties:</p> <pre><code>com.acme.xyz [format=properties] ftp.port = 21 </code></pre> <p>Notice that this definition only supports string properties. Therefore the service consuming the configuration needs to be able to adapt a string value to the correct type.</p> -<h2>Slingstart and Slingfeature projects</h2> +<h2><a href="#slingstart-and-slingfeature-projects" name="slingstart-and-slingfeature-projects">Slingstart and Slingfeature projects</a></h2> <p>The <code>slingstart-maven-plugin</code> introduces two new packaging types:</p> <ul> <li><code>slingstart</code> : This type requires a model at src/main/provisioning. It reads all text files in that directory and merges them in alphabetical order. The resulting artifact is a runnable jar. The assembled model is also attached to the project artifacts.</li> @@ -235,12 +235,12 @@ stringsimple ::= <quoted string representation of the value> (see below) </code></pre> <p>The resulting model is a merged model, starting with the dependencies and then merging in the current model.</p> <p>By default the Maven classpath is extended by the dependencies of the merged model. This behaviour can be disabled though via setting the parameter <code>disableExtendingMavenClasspath</code> to <code>true</code> (<a href="https://issues.apache.org/jira/browse/SLING-6541";>SLING-6541</a>).</p> -<h2>Model Merging</h2> +<h2><a href="#model-merging" name="model-merging">Model Merging</a></h2> <p>If two or more models are supplied, they are merged feature by feature, each feature being treated as a separate unit. </p> <p>Within a feature each run mode is treated separately as well. </p> <p>Within a run mode, a model can overwrite definitions from the base model. For example, it can define a different configuration or a different version and/or start level for an artifact.</p> <p>The supplied models are ordered alphanumercally by their filenames for merging.</p> -<h3>Removing and Changing of Artifacts</h3> +<h3><a href="#removing-and-changing-of-artifacts" name="removing-and-changing-of-artifacts">Removing and Changing of Artifacts</a></h3> <p>In addition, it can also remove artifacts and configurations. For this the special runmode :remove needs to be used together with all run modes the artifact or configuration is currently in.</p> <p>Let's look at an example base model</p> <pre><code>[artifacts] @@ -264,7 +264,7 @@ stringsimple ::= <quoted string representation of the value> (see below) another/one/0.0.0 </code></pre> <p>Note that the version for removal does not play a role, it's not compared for an exact match. But please keep in mind that the remove directive needs to be specified in the same feature and run mode as the original.</p> -<h3>Removing and Changing of Configurations</h3> +<h3><a href="#removing-and-changing-of-configurations" name="removing-and-changing-of-configurations">Removing and Changing of Configurations</a></h3> <p>Configurations can be removed in the same way by just specifying their PID in the :remove run mode. This is the base model:</p> <pre><code>[configurations] my.special.configuration.b @@ -288,7 +288,7 @@ stringsimple ::= <quoted string representation of the value> (see below) </code></pre> <p>When the merge directive is used, the configurations are merged and the properties are applied as a delta to the base configuration. Therefore the configuration my.special.configuration.b will have two properties "a" and "foo".</p> <p>If a merged configuration redefines a property that already exists, it overwrites it, so the last configuration supplied in a merge wins.</p> -<h2>Starting a server</h2> +<h2><a href="#starting-a-server" name="starting-a-server">Starting a server</a></h2> <p>Use the goal with name <code>start</code> to start one or multiple servers. The goal is bound by default to the <a href="https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference";><code>pre-integration-test</code> lifecycle phase</a>. The launchpad JAR used to start the server is being looked up from the following locations:</p> <ol> <li>the file path given in the configuration field <code>launchpadJar</code> or parameter <code>launchpad.jar</code></li> @@ -387,12 +387,12 @@ stringsimple ::= <quoted string representation of the value> (see below) </tr> </tbody> </table> -<h3>Debugging</h3> +<h3><a href="#debugging" name="debugging">Debugging</a></h3> <p>Since version 1.2.0 of this plugin it is possible to easily start a Sling server in debug mode (<a href="https://issues.apache.org/jira/browse/SLING-4677";>SLING-4677</a>). For that you either configure the property <code>debug</code> inside you server configuration in the pom.xml accordingly or by using the parameter <code>Dlaunchpad.debug</code>. Both values can either be <code>true</code> (in which case the <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Invocation";>JDWP options</a> <code>-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000</code> are appended to the VM options) or just some arbitrary string defining debugging options. In case both are used the parameter <code>Dlaunchpad.debug</code> takes precedence.</p> -<h2>Stopping a server</h2> +<h2><a href="#stopping-a-server" name="stopping-a-server">Stopping a server</a></h2> <p>Use the goal with name <code>stop</code> to stop one or multiple servers. The goal is bound by default to the <a href="https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference";><code>post-integration-test</code> lifecycle phase</a>.</p> -<h2>Known Issues</h2> -<h3>Support of configuration formats</h3> +<h2><a href="#known-issues" name="known-issues">Known Issues</a></h2> +<h3><a href="#support-of-configuration-formats" name="support-of-configuration-formats">Support of configuration formats</a></h3> <p>The provisioning model supports two formats to define configurations, properties and the format of the Apache Felix ConfigAdmin implementation.</p> <p>Starting with version 1.2.0 of the provisioning model and version 1.2.0 of the slingstart-maven-plugin, the implementation uses the latest format from Apache Felix, version 1.8.6 (or higher) of the ConfigAdmin. This requires you to use version 3.6.6 (or higher) of the OSGi installer core bundle to handle these configurations.</p> <p>If you want to stick with the old format from config admin, you can configure the maven plugin as follows:</p> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/development/version-policy.html ---------------------------------------------------------------------- diff --git a/documentation/development/version-policy.html b/documentation/development/version-policy.html index 71aea86..d402cd9 100644 --- a/documentation/development/version-policy.html +++ b/documentation/development/version-policy.html @@ -78,7 +78,7 @@ Please note that this page is currently in draft stage and still being discussed </div> <p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Introduction</h2> +<h2><a href="#introduction" name="introduction">Introduction</a></h2> <p>In comments to <a href="https://issues.apache.org/jira/browse/SLING-2944";>SLING-1176</a> Ian Boston wrote:</p> <blockquote> <p>The exports in bundle/api/pom.xml look like they might become problematic from a support point of view, although we probably can't avoid this. [...] [The problem is the] manual maintenance of the version numbers. (not a big problem but needs to be done)</p> @@ -91,11 +91,11 @@ Please note that this page is currently in draft stage and still being discussed <li>Sling Bundles</li> <li>Package Exports</li> </ol> -<h3>Big Sling Releases</h3> +<h3><a href="#big-sling-releases" name="big-sling-releases">Big Sling Releases</a></h3> <p>For <em>Big Sling Releases</em> we already have an ample solution in that we just use a single number increased from release to release. Just remember that a <em>Big Sling Release</em> is a convenience release of existing released Sling bundles.</p> -<h3>Sling Bundles</h3> +<h3><a href="#sling-bundles" name="sling-bundles">Sling Bundles</a></h3> <p>For <em>Sling Bundles</em> version numbers are just defined as the <code><version></code> element of the bundle's POM. The only restriction here is, that we decided to use even numbers for releases and odd numbers for SNAPSHOTs. Whether and when which version part is increased is not explicitly defined yet.</p> -<h3>Package Exports</h3> +<h3><a href="#package-exports" name="package-exports">Package Exports</a></h3> <p>For <em>Package Exports</em> the situation is more problematic since there are a number of places to set exported package version number:</p> <ul> <li>In a <code>packageinfo</code> file inside the package (picked up by the Maven Bundle Plugin to set the export version)</li> @@ -117,7 +117,7 @@ Please note that this page is currently in draft stage and still being discussed <p>But this would require defining the class source locations as resource location in the POM (at least for <code>packageinfo</code>) files.</p> <p>I am not sure ....</p> <p>This has not been discussed at large, but I would assume, that the POM is still the correct place to take note of the version of the exported packages.</p> -<h3>Future</h3> +<h3><a href="#future" name="future">Future</a></h3> <p>The newest versions of the bnd library also support an <code>@Export</code> annotation in the <code>package-info.java</code> pseudo class file. This pseudo class is supported starting with Java 5 to take package level annotations (like the <code>@Export</code> annotation) and as a replacement of the <code>package-info.html</code> file.</p> <p>Using this syntax something like the following would be easily possible:</p> <pre><code>/** @@ -128,7 +128,7 @@ package org.apache.sling.api.auth; import aQute.bnd.annotation.Export; </code></pre> <p>See <a href="http://bnd.bndtools.org/chapters/170-versioning.html";>bnd Versioning</a> for details.</p> -<h2>Version Number Syntax</h2> +<h2><a href="#version-number-syntax" name="version-number-syntax">Version Number Syntax</a></h2> <p>As a small reminder, this is how a version number is constructed: In OSGi version numbers are composed of four (4) segments: three integers and one string named <em>major</em>._minor_._micro_._qualifier_.</p> <p>Each segment captures a different intent:</p> <ul> @@ -137,7 +137,7 @@ import aQute.bnd.annotation.Export; <li>the micro segment indicates bug fixes</li> <li>the qualifier segment is not generally used but may be used to convey more information about a particular build, such as a build time or a SVN revision number.</li> </ul> -<h2>Evolution of Exported Package Versions</h2> +<h2><a href="#evolution-of-exported-package-versions" name="evolution-of-exported-package-versions">Evolution of Exported Package Versions</a></h2> <p>Version numbers of exported packages evolve independently from each other. Depending on the changes applied, the micro, minor, or major segement is increased. Whenever the major segment is increased, the minor and micro segments are reset to zero. Whenever the minor segment is increased, the micro segment is reset to zero.</p> <p>Segments are increased according to the above listing.</p> <p>This requires committers to think well about changes they apply to exported packages:</p> @@ -147,7 +147,7 @@ import aQute.bnd.annotation.Export; <li>Fixing a bug in an exported class just requires a minor version increase.</li> </ul> <p>JavaDoc updates generally do not constitute a reason to evolve the version number. The exception is that if the JavaDoc update is caused by a API limitation, it might be conceivable to increase the version number of the exported package. A decision on this will have to be taken on a case-by-case basis.</p> -<h2>Evolution of Bundle Versions</h2> +<h2><a href="#evolution-of-bundle-versions" name="evolution-of-bundle-versions">Evolution of Bundle Versions</a></h2> <p>Version numbers of bundles evolve depending on the evolution of the exported packages but also depending on the evolution of the private code, which is not exported.</p> <p>As a rule of thumb, the following reasons apply for increasing the segments of bundle version numbers:</p> <ul> @@ -156,8 +156,8 @@ import aQute.bnd.annotation.Export; <li>Increasing the micro version number of any of the exported packages or bug fixes.</li> </ul> <p>Note, that this definition does not require the bundle and epxorted package version numbers to be synchronized in any way. While doing so might help in a first or second step, over time it will become close to impossible to keep the versions in sync. So rather than trying to keep the versions in sync, we should make sure, we increase the versions correctly.</p> -<h2>Examples</h2> -<h3>Pure API Bundle</h3> +<h2><a href="#examples" name="examples">Examples</a></h2> +<h3><a href="#pure-api-bundle" name="pure-api-bundle">Pure API Bundle</a></h3> <p>An example of an almost <em>Pure API Bundle</em> is the Sling API bundle. This bundle exports 9 packages. Some are really stable -- e.g. the <code>org.apache.sling.api</code> package or the <code>org.apache.sling.wrappers</code> package -- and some are being worked on at the moment -- e.g. the <code>org.apache.sling.resource</code> package.</p> <p>To not break existing users of the unmodified packages, the exported versions of these packages must not be increased.</p> <p>To signal to users of evolving packages, that there might be new and interesting functionality, the version number must be increased according to above definition. This also conveys to the implementor(s) of the API, that they have to take some action.</p> @@ -204,7 +204,7 @@ import aQute.bnd.annotation.Export; </tr> </tbody> </table> -<h3>Implementation Bundle providing API</h3> +<h3><a href="#implementation-bundle-providing-api" name="implementation-bundle-providing-api">Implementation Bundle providing API</a></h3> <p>An example of such a hybrid bundle is the Sling Engine bundle. This bundle exports two packages themselves defining API and contains a number of internal packages which actually implement parts of the Sling API.</p> <p>A hypothetical evolution of version numbers shown on one exported package and the bundle version might be as follows</p> <table> @@ -253,9 +253,9 @@ import aQute.bnd.annotation.Export; </tr> </tbody> </table> -<h3>Pure Implementation Bundle</h3> +<h3><a href="#pure-implementation-bundle" name="pure-implementation-bundle">Pure Implementation Bundle</a></h3> <p>For Pure Implementation Bundles only the bundle version numbers are maintained because there is no exported package whose version number needs to be managed. This makes the decision process of version number evolution very simple.</p> -<h2>Importing Packages</h2> +<h2><a href="#importing-packages" name="importing-packages">Importing Packages</a></h2> <p>When importing packages a version number will automatically be generated by the Maven Bundle Plugin as follows:</p> <ul> <li>If the providing package exports a package with an explicit version number, that exact version number will be used as the lower bound</li> @@ -270,9 +270,9 @@ import aQute.bnd.annotation.Export; <pre><code>Import-Package: api;version=[1.2.3,1.3.0) </code></pre> <p>This allows for the implementation to work correctly with bug fixed package exports but as soon as there are any <em>externally visible</em> changes, the implementation bundle has to be adapted -- even if this just means increasing the upper version bound in the <code>Import-Package</code> statement thus guaranteeing compliance (again).</p> -<h3>Future</h3> +<h3><a href="#future" name="future">Future</a></h3> <p>Recent versions of the bnd library support automatic differentiation between <em>use</em> and <em>implementation</em> of API and to set the import version ranges accordingly. See <a href="http://bnd.bndtools.org/chapters/170-versioning.html";>bnd Versioning</a> for details.</p> -<h2>References</h2> +<h2><a href="#references" name="references">References</a></h2> <ul> <li><a href="http://markmail.org/thread/zshobgjwtqrncajt";>Version Numbers</a> -- The mail thread discussing version numbering</li> <li><a href="http://blog.meschberger.ch/2009/10/on-version-numbers.html";>On Version Numbers</a> -- Blog about version numbers</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/getting-started.html ---------------------------------------------------------------------- diff --git a/documentation/getting-started.html b/documentation/getting-started.html index f9e74e5..7ad4fd6 100644 --- a/documentation/getting-started.html +++ b/documentation/getting-started.html @@ -76,7 +76,7 @@ <ul> <li><a href="getting-started/discover-sling-in-15-minutes.html">Discover Sling in 15 minutes</a></li> </ul> -<h2>Where to head from here</h2> +<h2><a href="#where-to-head-from-here" name="where-to-head-from-here">Where to head from here</a></h2> <p>We recommend you read through following topics to get as fast as possible into Sling: </p> <ul> <li><a href="/documentation/development/getting-and-building-sling.html">Getting and building Sling</a></li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/getting-started/discover-sling-in-15-minutes.html ---------------------------------------------------------------------- diff --git a/documentation/getting-started/discover-sling-in-15-minutes.html b/documentation/getting-started/discover-sling-in-15-minutes.html index a156cb2..5a6073d 100644 --- a/documentation/getting-started/discover-sling-in-15-minutes.html +++ b/documentation/getting-started/discover-sling-in-15-minutes.html @@ -77,14 +77,14 @@ <p>While simple to run and understand, the Launchpad is a full-featured instance of Sling, an example configuration that we have created with the most common modules and configurations. The full functionality of Sling is available by loading additional Sling (or custom) OSGi bundles as needed, using the Launchpad's web-based OSGi management console.</p> <p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>See Also</h2> +<h2><a href="#see-also" name="see-also">See Also</a></h2> <p>More Sling samples can be found under <a href="http://svn.apache.org/repos/asf/sling/trunk/samples/";>http://svn.apache.org/repos/asf/sling/trunk/samples/</a></p> <p>Once you grok the basic examples of this page, we recommend studying the <em>slingbucks</em> and <em>espblog</em> samples. Both have README files with more info.</p> -<h2>Prerequisites</h2> +<h2><a href="#prerequisites" name="prerequisites">Prerequisites</a></h2> <p>We'll start with the self-runnable jar from the Sling distribution, you only need a Java 7 JDK. Download the latest release from the Sling <a href="/downloads.cgi">Downloads</a> page or by clicking this link: <a href="http://www.apache.org/dyn/closer.lua/sling/org.apache.sling.launchpad-8.jar";>org.apache.sling.launchpad-8.jar</a>. Alternatively you can deploy the <a href="http://www.apache.org/dyn/closer.lua/sling/org.apache.sling.launchpad-8-webapp.war";>Sling Web application</a> into any decent Servlet Container such as Jetty or Tomcat or you can <a href="/documentation/development/getting-and-building-sling.html">build the current source yourself</a>.</p> <p>To show the simplicity of the REST-style approach taken by Sling the examples below will be using <a href="http://curl.haxx.se/";>cURL</a>. Any HTTP client would do, but cURL is the easiest to document in a reproducible way.</p> <p>A WebDAV client makes editing server-side scripts much more convenient, but to make our examples easy to reproduce, we're using cURL below to create and update files in the JCR repository, via the Sling WebDAV server.</p> -<h2>Start the Launchpad</h2> +<h2><a href="#start-the-launchpad" name="start-the-launchpad">Start the Launchpad</a></h2> <p>After downloading the Sling Launchpad self-runnable jar just start it as follows:</p> <pre><code>$ java -jar org.apache.sling.launchpad-8.jar </code></pre> @@ -92,7 +92,7 @@ <p>Once started, look at <a href="http://localhost:8080/system/console/bundles";>http://localhost:8080/system/console/bundles</a> with your browser. Use <em>admin</em> with password <em>admin</em> if Sling asks you for a login. Sling then displays the <em>Felix Web Management Console</em> page.</p> <p>On the bundles page, all bundles should be marked <em>Active</em>. They're all <a href="http://www.osgi.org/";>OSGi</a> bundles powered by <a href="http://felix.apache.org";>Apache Felix</a>, but that doesn't really matter to us right now.</p> <p><em>Log files: If things go wrong, have a look at the <code>sling/logs/error.log</code> log file - that's where Sling writes any error messages.</em></p> -<h2>Create some content</h2> +<h2><a href="#create-some-content" name="create-some-content">Create some content</a></h2> <p>Until we have ready-to-test forms, you can create content with cURL, or you can create an HTML form that posts to the specified URL.</p> <p>To create a content node (nodes are a <a href="http://jackrabbit.apache.org/";>JCR</a> concept, a unit of storage) with cURL, use:</p> <pre><code>curl -u admin:admin -F"sling:resourceType=foo/bar" -F"title=some title" http://localhost:8080/content/mynode @@ -105,7 +105,7 @@ </code></pre> <p>The additional property <code>jcr:primaryType</code> is a special JCR property added by the content repository, indicating the JCR primary node type.</p> <p><em>Monitoring requests: Sling provides a simple tool (an OSGi console plugin) to monitor HTTP requests, which helps understand how things work internally. See the <a href="/documentation/development/monitoring-requests.html">Monitoring Requests</a> page for details.</em></p> -<h2>Render your content using server-side javascript (ESP)</h2> +<h2><a href="#render-your-content-using-server-side-javascript-esp-" name="render-your-content-using-server-side-javascript-esp-">Render your content using server-side javascript (ESP)</a></h2> <p>Sling uses scripts or servlets to render and process content.</p> <p>Several scripting languages are available as additional Sling modules (packaged as OSGi <em>bundles</em> that can be installed via the Sling management console), but the launchpad currently includes the ESP (server-side ECMAscript), JSP (Java Server Pages), and Groovy language modules by default.</p> <p>To select a script, Sling uses the node's <em>sling:resourceType</em> property, if it is set.</p> @@ -132,11 +132,11 @@ curl -X MKCOL -u admin:admin http://localhost:8080/apps/foo/bar <p>The HTML rendering of your node, at <a href="http://localhost:8080/content/mynode.html";>http://localhost:8080/content/mynode.html</a>, is now created by this ESP script. You should see the node's title alone as an <h1> element in that page.</p> <p>A script named <em>POST.esp</em> instead of <em>html.esp</em> would be called for a POST request, <em>DELETE.esp</em> for DELETE, <em>xml.esp</em> for a GET request with a <em>.xml</em> extension, etc. See <a href="/documentation/the-sling-engine/url-to-script-resolution.html">URL to Script Resolution</a> on the Sling wiki for more info.</p> <p>Servlets can also be easily "wired" to handle specific resource types, extensions, etc., in the simplest case by using SCR annotations in the servlet source code. Servlets and scripts are interchangeable when it comes to processing Sling requests.</p> -<h2>What next?</h2> +<h2><a href="#what-next-" name="what-next-">What next?</a></h2> <p>These simple examples show how Sling uses scripts to work with JCR data, based on <em>sling:resourceType</em> or node types.</p> <p>There's much more to Sling of course - you'll find some additional simple examples below, as well as above in the <em>see also</em> section.</p> -<h2>Additional examples</h2> -<h3>Let Sling generate the path of a newly created node.</h3> +<h2><a href="#additional-examples" name="additional-examples">Additional examples</a></h2> +<h3><a href="#let-sling-generate-the-path-of-a-newly-created-node-" name="let-sling-generate-the-path-of-a-newly-created-node-">Let Sling generate the path of a newly created node.</a></h3> <p>To create a node with a unique path at a given location, end the URL of the POST request with <em>/</em>.</p> <p>In this case, the Sling response redirects to the URL of the created node.</p> <p>Start by creating a new <em>/blog</em> folder:</p> @@ -151,7 +151,7 @@ curl -X MKCOL -u admin:admin http://localhost:8080/apps/foo/bar <p>The actual node name might not be <em>adventures_with_slin</em> - depending on existing content in your repository, Sling will find a unique name for this new node, based on several well-know property values like title, description, etc. which are used for this if provided.</p> <p>So, in our case, our new node can be displayed in HTML via the <a href="http://localhost:8080/blog/adventures*with*slin.html";>http://localhost:8080/blog/adventures_with_slin.html</a> URL.</p> <p>Note that we didn't set a <em>sling:resourceType</em> property on our node, so if you want to render that node with a script, you'll have to store the script under <em>/apps/nt/unstructured/html.esp</em>.</p> -<h3>Add a page header with sling.include</h3> +<h3><a href="#add-a-page-header-with-sling-include" name="add-a-page-header-with-sling-include">Add a page header with sling.include</a></h3> <p>The <em>sling.include</em> function can be called from scripts to include the rendered result of another node.</p> <p>In this example, we create a node at <em>/content/header</em>, rendered with a logo using an <em>html.esp</em> script, then use that header at the top of the <em>html.esp</em> script that we created previously for the <em>foo/bar</em> resource type.</p> <p>Start by checking that <a href="http://localhost:8080/content/mynode.html";>http://localhost:8080/content/mynode.html</a> is rendered using the <em>html.esp</em> script created above.</p> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/legacy/logging.html ---------------------------------------------------------------------- diff --git a/documentation/legacy/logging.html b/documentation/legacy/logging.html index 98e32b9..2e9a877 100644 --- a/documentation/legacy/logging.html +++ b/documentation/legacy/logging.html @@ -77,7 +77,7 @@ This document is for 3.x release of Sling Commons Log components. Refer to <a href="http://sling.apache.org/documentation/development/logging.html";>Logging</a> for documentation related to newer version. </div> -<h2>Introduction</h2> +<h2><a href="#introduction" name="introduction">Introduction</a></h2> <p>Logging in Sling is supported by the <code>org.apache.sling.commons.log</code> bundle, which is one of the first bundles installed and started by the Sling Launcher. The <code>org.apache.sling.commons.log</code> bundle has the following tasks:</p> <ul> <li>Implements the OSGi Log Service Specification and registers the <code>LogService</code> and <code>LogReader</code> services</li> @@ -91,7 +91,7 @@ to newer version. </li> <li>Configures logging through our own implementation of the SLF4J backend API</li> </ul> -<h2>Initial Configuration</h2> +<h2><a href="#initial-configuration" name="initial-configuration">Initial Configuration</a></h2> <p>The <code>org.apache.sling.commons.log</code> bundle gets the initial configuration from the following <code>BundleContext</code> properties:</p> <table> <thead> @@ -134,9 +134,9 @@ to newer version. </tr> </tbody> </table> -<h2>User Configuration</h2> +<h2><a href="#user-configuration" name="user-configuration">User Configuration</a></h2> <p>User Configuration after initial configuration is provided by the Configuration Admin Service. To this avail two <code>org.osgi.services.cm.ManagedServiceFactory</code> services are registered under the PIDs <code>org.apache.sling.commons.log.LogManager.factory.writer</code> and <code>org.apache.sling.commons.log.LogManager.factory.config</code> which may receive configuration.</p> -<h3>Logger Configuration</h3> +<h3><a href="#logger-configuration" name="logger-configuration">Logger Configuration</a></h3> <p>Loggers (or Categories) can be configured to log to specific files at specific levels using configurable patterns. To this avail factory configuration instances with factory PID <code>org.apache.sling.commons.log.LogManager.factory.config</code> may be created and configured with the Configuration Admin Service.</p> <p>The following properties may be set:</p> <table> @@ -171,7 +171,7 @@ to newer version. </table> <p>| <code>org.apache.sling.commons.log.names</code> | <code>String\[\]</code> | -- | A list of logger names to which this configuration applies. |</p> <p>Note that multiple Logger Configurations may refer to the same Log Writer Configuration. If no Log Writer Configuration exists whose file name matches the file name set on the Logger Configuration an implicit Log Writer Configuration with default setup (daily log rotation) is internally created. </p> -<h3>Log Writer Configuration</h3> +<h3><a href="#log-writer-configuration" name="log-writer-configuration">Log Writer Configuration</a></h3> <p>Log Writer Configuration is used to setup file output and log file rotation characteristics for log writers used by the Loggers.</p> <p>The following properties may be set:</p> <table> @@ -201,10 +201,10 @@ to newer version. </tbody> </table> <p>See the section <em>Log File Rotation</em> below for full details on the <code>org.apache.sling.commons.log.file.size</code> and <code>org.apache.sling.commons.log.file.number</code> properties.</p> -<h2>Log File Rotation</h2> +<h2><a href="#log-file-rotation" name="log-file-rotation">Log File Rotation</a></h2> <p>Log files can grow rather quickly and fill up available disk space. To cope with this growth log files may be rotated in two ways: At specific times or when the log file reaches a configurable size. The first method is called <em>Scheduled Rotation</em> and is used by specifying a <code>SimpleDateFormat</code> pattern as the log file "size". The second method is called <em>Size Rotation</em> and is used by setting a maximum file size as the log file size.</p> <p>As of version 2.0.6 of the Sling Commons Log bundle, the default value for log file scheduling is <code>'.'yyyy-MM-dd</code> causing daily log rotation. Previously log rotation defaulted to a 10MB file size limit.</p> -<h3>Scheduled Rotation</h3> +<h3><a href="#scheduled-rotation" name="scheduled-rotation">Scheduled Rotation</a></h3> <p>The rolling schedule is specified by setting the <code>org.apache.sling.commons.log.file.size</code> property to a <code>java.text.SimpleDateFormat</code> pattern. Literal text (such as a leading dot) to be included must be <em>enclosed</em> within a pair of single quotes. A formatted version of the date pattern is used as the suffix for the rolled file name.</p> <p>For example, if the log file is configured as <code>/foo/bar.log</code> and the pattern set to <code>'.'yyyy-MM-dd</code>, on 2001-02-16 at midnight, the logging file <code>/foo/bar.log</code> will be renamed to <code>/foo/bar.log.2001-02-16</code> and logging for 2001-02-17 will continue in a new <code>/foo/bar.log</code> file until it rolls over the next day.</p> <p>It is possible to specify monthly, weekly, half-daily, daily, hourly, or minutely rollover schedules.</p> @@ -251,7 +251,7 @@ to newer version. </table> <p>Do not use the colon ":" character in anywhere in the pattern option. The text before the colon is interpeted as the protocol specificaion of a URL which is probably not what you want.</p> <p>Note that Scheduled Rotation ignores the <code>org.apache.sling.commons.log.file.number</code> property since the old log files are not numbered but "dated".</p> -<h3>Size Rotation</h3> +<h3><a href="#size-rotation" name="size-rotation">Size Rotation</a></h3> <p>Log file rotation by size is specified by setting the <code>org.apache.sling.commons.log.file.size</code> property to a plain number or a number plus a size multiplier. The size multiplier may be any of <code>K</code>, <code>KB</code>, <code>M</code>, <code>MB</code>, <code>G</code>, or <code>GB</code> where the case is ignored and the meaning is probably obvious.</p> <p>When using Size Rotation, the <code>org.apache.sling.commons.log.file.number</code> defines the number of old log file generations to keep. For example to keep 5 old log files indexed by 0 through 4, set the <code>org.apache.sling.commons.log.file.number</code> to <code>5</code> (which happens to be the default).</p></section></div></div> <div class="footer"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine.html b/documentation/the-sling-engine.html index 854571b..5794379 100644 --- a/documentation/the-sling-engine.html +++ b/documentation/the-sling-engine.html @@ -72,13 +72,13 @@ </div> <div class="main"> <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » </div> <h1> The Sling Engine - </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2>General</h2> + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2><a href="#general" name="general">General</a></h2> <ul> <li><a href="/documentation/the-sling-engine/architecture.html">Architecture</a></li> <li><a href="/documentation/the-sling-engine/authentication.html">Authentication</a></li> <li><a href="/documentation/the-sling-engine/service-authentication.html">Service Authentication</a></li> </ul> -<h2>Request Handling</h2> +<h2><a href="#request-handling" name="request-handling">Request Handling</a></h2> <ul> <li><a href="/documentation/the-sling-engine/dispatching-requests.html">Dispatching Requests</a></li> <li><a href="/documentation/the-sling-engine/url-decomposition.html">URL decomposition</a></li> @@ -89,14 +89,14 @@ <li><a href="/documentation/the-sling-engine/errorhandling.html">Errorhandling</a></li> <li><a href="/documentation/the-sling-engine/request-parameters.html">Request Parameters</a></li> </ul> -<h2>Resources</h2> +<h2><a href="#resources" name="resources">Resources</a></h2> <ul> <li><a href="/documentation/the-sling-engine/resources.html">Resources</a></li> <li><a href="/documentation/the-sling-engine/sling-api-crud-support.html">Sling API CRUD Support</a></li> <li><a href="/documentation/the-sling-engine/wrap-or-decorate-resources.html">Wrap or Decorate Resources</a></li> <li><a href="/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a></li> </ul> -<h2>Misc</h2> +<h2><a href="#misc" name="misc">Misc</a></h2> <ul> <li><a href="/documentation/the-sling-engine/adapters.html">Adapters</a></li> <li><a href="/documentation/the-sling-engine/featureflags.html">Feature Flags</a></li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/adapters.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/adapters.html b/documentation/the-sling-engine/adapters.html index 6283969..aec3d2a 100644 --- a/documentation/the-sling-engine/adapters.html +++ b/documentation/the-sling-engine/adapters.html @@ -76,7 +76,7 @@ </p> <p>The <code>Resource</code> and <code>ResourceResolver</code> interfaces are defined with a method <code>adaptTo</code>, which adapts the object to other classes. Using this mechanism the JCR session of the resource resolver calling the <code>adaptTo</code> method with the <code>javax.jcr.Session</code> class object. Likewise the JCR node on which a resource is based can be retrieved by calling the <code>Resource.adaptTo</code> method with the <code>javax.jcr.Node</code> class object.</p> <p>To use resources as scripts, the <code>Resource.adaptTo</code> method must support being called with the <code>org.apache.sling.api.script.SlingScript</code> class object. But of course, we do not want to integrate the script manager with the resource resolver. To enable adapting objects to classes which are not foreseen by the original implementation, a factory mechanism is used. This way, the script manager can provide an adapter factory to adapt <code>Resource</code> to <code>SlingScript</code> objects.</p> -<h1>Adaptable</h1> +<h1><a href="#adaptable" name="adaptable">Adaptable</a></h1> <p>The <code>Adaptable</code> interface defines the API to be implemented by a class providing adaptability to another class. The single method defined by this interface is</p> <pre><code>/** * Adapts the adaptable to another type. @@ -100,10 +100,10 @@ <AdapterType> AdapterType adaptTo(Class<AdapterType> type); </code></pre> <p>This method is called to get a view of the same object in terms of another class. Examples of implementations of this method are the Sling <code>ResourceResolver</code> implementation providing adapting to a JCR session and the Sling JCR based <code>Resource</code> implementation providing adapting to a JCR node.</p> -<h1>Listing Adaptation Possibilities</h1> +<h1><a href="#listing-adaptation-possibilities" name="listing-adaptation-possibilities">Listing Adaptation Possibilities</a></h1> <p>The Web Console Plugin at <code>/system/console/adapters</code> and at <code>/system/console/status-adapters</code> can be used to list all existing adaptables in the system with their according adapter classes.</p> <p>The web console plugin evaluates metadata being provided by any <code>AdapterFactory</code> services as well as metadata being provided through the file <code>SLING-INF/adapters.json</code></p> -<h1>Implementing Adaptable</h1> +<h1><a href="#implementing-adaptable" name="implementing-adaptable">Implementing Adaptable</a></h1> <p>Each adaptable should derive from <code>SlingAdaptable</code> to automatically profit from all according <code>AdapterFactories</code> registered in the system. In case the <code>adaptTo(...)</code> method is being overwritten an according <code>SLING-INF/adapters.json</code> should be included in the providing bundle listing all adaptation possibilities. While this file is not strictly necessary for the actual adaptation to work, it provides useful information to the Web Console plugin. Otherwise developers will not know which adaptations are supported. The format of this JSON file looks like this (<a href="https://issues.apache.org/jira/browse/SLING-2295";>SLING-2295</a>):</p> <pre><code>{ <fully qualified class name of adaptable> : { @@ -125,14 +125,14 @@ } </code></pre> <p>Instead of manually creating that JSON file, the annotations from the module <a href="https://svn.apache.org/viewvc/sling/trunk/tooling/maven/adapter-annotations/";>adapter-annotations</a> can be used together with the goal <code>generate-adapter-metadata</code> from the <a href="http://sling.apache.org/components/maven-sling-plugin/generate-adapter-metadata-mojo.html";>Maven Sling Plugin</a> to generate it automatically (<a href="https://issues.apache.org/jira/browse/SLING-2313";>SLING-2313</a>).</p> -<h1>Extending Adapters</h1> +<h1><a href="#extending-adapters" name="extending-adapters">Extending Adapters</a></h1> <p>Sometimes an <code>Adaptable</code> implementation cannot foresee future uses and requirements. To cope with such extensibility requirements two interfaces and an abstract base class are defined:</p> <ul> <li><code>AdapterManager</code></li> <li><code>AdapterFactory</code></li> <li><code>SlingAdaptable</code></li> </ul> -<h2>AdapterFactory</h2> +<h2><a href="#adapterfactory" name="adapterfactory">AdapterFactory</a></h2> <p>The <code>AdapterFactory</code> interface defines the service interface and API for factories supporting extensible adapters for <code>SlingAdaptable</code> objects. The interface has a single method:</p> <pre><code>/** * Adapt the given object to the adaptable type. The adaptable object is @@ -162,7 +162,7 @@ </code></pre> <p>Implementations of this interface are registered as OSGi services providing two lists: The list of classes which may be adapted (property named <code>adaptables</code>) and the list of classes to which the adapted class may be adapted (property named <code>adapters</code>). A good example of an Class implementing <code>AdapterFactory</code> is the <code>SlingScriptAdapterFactory</code>. In addition a property named <code>adapter.condition</code> can be provided which is supposed to contain a string value explaining under which circumstances the adaption will work (if there are any restrictions). This is evaluated by the Web Console Plugin.</p> <p><code>AdapterFactory</code> services are gathered by a <code>AdapterManager</code> implementation for use by consumers. Consumers should not care for <code>AdapterFactory</code> services.</p> -<h2>AdapterManager</h2> +<h2><a href="#adaptermanager" name="adaptermanager">AdapterManager</a></h2> <p>The <code>AdapterManager</code> is defines the service interface for the generalized and extensible use of <code>AdapterFactory</code> services. Thus the adapter manager may be retrieved from the service registry to try to adapt whatever object that needs to be adapted - provided appropriate adapters exist.</p> <p>The <code>AdapterManager</code> interface is defined as follows:</p> <pre><code>/** @@ -184,7 +184,7 @@ Class<AdapterType> type); </code></pre> <p>Any object can theoretically be adapted to any class even if it does not implement the <code>Adaptable</code> interface, if an <code>AdapterFactory</code> service delivers a <code>getAdapter()</code> method which adapts an object to another one. To check if there's any existing <code>AdapterFactory</code> which can adapt a given object to another one the <code>AdapterManager</code> service with its <code>getAdapter()</code> method does the job. So the <code>Adaptable</code> interface merely is an indicator that the object provides built-in support for being adapted.</p> -<h2>SlingAdaptable</h2> +<h2><a href="#slingadaptable" name="slingadaptable">SlingAdaptable</a></h2> <p>The <code>SlingAdaptable</code> class is an implementation of the <code>Adaptable</code> interface which provides built-in support to call the <code>AdapterManager</code> to provide an adapter from the <code>Adaptable</code> object to the requested class.</p> <p>An example of extending the <code>SlingAdaptable</code> class will be the Sling JCR based <code>Resource</code> implementation. This way, such a resource may be adapted to a <code>SlingScript</code> by means of an appropriately programmed <code>AdapterFactory</code> (see below).</p></section></div></div> <div class="footer"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/architecture.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/architecture.html b/documentation/the-sling-engine/architecture.html index 496573f..9db3b37 100644 --- a/documentation/the-sling-engine/architecture.html +++ b/documentation/the-sling-engine/architecture.html @@ -82,16 +82,16 @@ <li><strong><a href="#launchpad">Launchpad</a></strong> — Sling uses a very thin launcher to integrate with an existing servlet container, launching Sling as a Web application or providing a main class to represent a standalone Java application.</li> </ul> <p>The following sections elaborate on each of these highlights.</p> -<h2>OSGi</h2> +<h2><a href="#osgi" name="osgi">OSGi</a></h2> <p><a href="http://www.osgi.org";>OSGi</a> is a consortium that has developed a specification to build modular and extensible applications. This offers <a href="http://www.osgi.org/About/WhyOSGi";>various benefits</a>. We deal mainly with two parts of the specifications: The Core Specification, which defines the OSGi Framework and Core Services, and the Compendium Services Specification, which defines a host of services that extend the functionality of the OSGi Framework.</p> -<h3>OSGi Framework</h3> +<h3><a href="#osgi-framework" name="osgi-framework">OSGi Framework</a></h3> <p>The OSGi Framework is made up of three layers – Module, Lifecycle, and Services – that define how extensible applications are built and deployed. The responsibilities of the layers are:</p> <ul> <li><strong>Module</strong> — Defines how a module, or a <em>Bundle</em> in OSGi-speak, is defined. Basically, a bundle is just a plain old JAR file, whose manifest file has some defined entries. These entries identify the bundle with a symbolic name, a version and more. In addition there are headers which define what a bundle provides <code>Export-Package</code> and what a bundle requires to be operative <code>Import-Package</code> and <code>Require-Bundle</code>.</li> <li><strong>Lifecycle</strong> — The lifecycle layer defines the states a bundle may be in and describes the state changes. By providing a class, which implements the <code>BundleActivator</code> interface and which is named in the <code>Bundle-Activator</code> manifest header, a bundle may hook into the lifecycle process when the bundle is started and stopped.</li> <li><strong>Services</strong> — For the application to be able to interact, the OSGi Core Specification defines the service layer. This describes a registry for services, which may be shared.</li> </ul> -<h3>Compendium Services</h3> +<h3><a href="#compendium-services" name="compendium-services">Compendium Services</a></h3> <p>Based on the OSGi Framework specification, the Compendium Services specification defines a (growing) number of extension services, which may be used by applications for various tasks. Of these Compendium Services, Sling is using just a small number:</p> <ul> <li><strong>Log Service</strong> — Sling comes with its own implementation of the OSGi Log Service specification. The respective bundle not only provides this implementation, it also exports the SLF4J, Log4J and Commons Logging APIs needed for the Sling application to perform logging.</li> @@ -101,24 +101,24 @@ <li><strong>Event Admin Service</strong> — Sling uses the OSGi EventAdmin service to dispatch events when scheduling tasks.</li> <li><strong>Declarative Services</strong> — One of the most important (beside the Log Service) services used by Sling is the Declarative Services Specification. This specification defines how to declaratively create components and services to have the Declarative Services runtime actually manage the lifecycle, configuration and references of components.</li> </ul> -<h2>Sling API</h2> +<h2><a href="#sling-api" name="sling-api">Sling API</a></h2> <p>The Sling API is an extension to the Servlet API which provides more functionality to interact with the Sling framework and also to extend Sling itself and to implement Sling applications.</p> -<h2>Request Processing</h2> +<h2><a href="#request-processing" name="request-processing">Request Processing</a></h2> <p>Traditional Web Application framework emply more or less elaborate methods to select a Servlet or Controller based on the request URL, which in turn tries to load some data (usually from a database) to act upon and finally to render the result somehow.</p> <p>Sling turns this processing around in that it places the data to act upon at the center and consequently uses the request URL to first resolve the data to process. This data is internally represented as an instance of the <code>Resource</code> interface. Based on this resource as well as the request method and more properties of the request URL a script or servlet is then selected to handle the request.</p> <p>See the <a href="/documentation/the-sling-engine/servlets.html">Servlets</a> page for more information.</p> -<h2>Resources</h2> +<h2><a href="#resources" name="resources">Resources</a></h2> <p>The Resource is one of the central parts of Sling. Extending from JCR's <em>Everything is Content</em>, Sling assumes <em>Everthing is a Resource</em>. Thus Sling is maintaining a virtual tree of resources, which is a merger of the actual contents in the JCR Repository and resources provided by so called resource providers.</p> <p>Each resource has a path by which it is addressed in the resource tree, a resource type and some resource metadata (such as file size, last modification time). It is important to understand, that a <code>Resource</code> instance actually is only a handle to the actual data. By virtue of the <code>adaptTo(Class<Type>)</code> method, a resource may be coerced into another data type, which may then be used while processing the request. Examples of data types are <code>javax.jcr.Node</code> and <code>java.io.InputStream</code>.</p> <p>See the <a href="/documentation/the-sling-engine/resources.html">Resources</a> page for more information.</p> -<h2>Servlets and Scripts</h2> +<h2><a href="#servlets-and-scripts" name="servlets-and-scripts">Servlets and Scripts</a></h2> <p>Scripts are usually provided as content in a JCR repository. But since Sling is using a resource tree, a script actually is represented as a Resource and may be provided from within a Bundle (by virtue of the bundle resource provider) or even from the platform file system (by virtue of the file system resource provider).</p> <p>Accessing scripts in the resource tree, allows for a very easy to understand mapping from resource type to some script path.</p> <p>Having found the script resource, we still need access to the appropriate script language implementation to evaluate the script. To this avail, Sling is making use of the <code>Resource.adaptTo(Class<Type>)</code> method: If a script language implementation is available for the extension of the script name an adaptor for the script resource can be found, which handles the evaluation of the script.</p> <p>Besides scripting languages, such as ECMAScript, Groovy, JSP, Sling also supports regular servlets. To be able to use servlets for request processing, such servlets must be registered as OSGi services for the <code>javax.servlet.Servlet</code> interface and provide a number of service registration properties, which are used to use the servlets. In fact servlets thus registered as OSGi services are mapped into the resource tree by means of a servlet resource provider. This resource provider mapps the servlets into the resource tree using the service registration properties to build one or more resource paths for the servlet.</p> <p>As a result of mapping servlets into the resource tree and the possibility to adapt resource to an adaptor data type, scripts and servlets may be handled completely transparently: The servlet resolver just looks for a resource matching the resource type and adapts the resource found to <code>javax.jcr.Servlet</code>. If the resource happens to be provided by a servlet resource provider, the adapter is of course the servlet itself. If the resource happens to be a script, the adapter is a servlet facade which internally calls the script language implementation to evaluate the script.</p> <p>See the <a href="/documentation/the-sling-engine/servlets.html">Servlet Resolution</a> page for more information.</p> -<h2>Launchpad</h2> +<h2><a href="#launchpad" name="launchpad">Launchpad</a></h2> <p>Sling may be launched as a standalone application using the Sling Application or as a Web Application running inside any Servlet API 2.4 or newer Servlet Container.</p> <p>The Sling Application is a standalone Java Application which is really small: Just the main class and some glue classes. The OSGi framework as well as the OSGi API libraries are packaged as a JAR file, which is loaded through a custom classloader. This enables to update the framework and/or OSGi API libraries from within Sling by updating the system bundle.</p> <p>The Sling Servlet is equally small as the Sling Application. It uses the Felix <code>HttpService</code> bridge as the glue between the servlet container and the OSGi framework.</p>
