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/19 12:41:48 UTC
[42/53] sling-site git commit: asf-site branch created for published
content
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/development/issue-tracker.html
----------------------------------------------------------------------
diff --git a/documentation/development/issue-tracker.html b/documentation/development/issue-tracker.html
new file mode 100644
index 0000000..ace0e04
--- /dev/null
+++ b/documentation/development/issue-tracker.html
@@ -0,0 +1,155 @@
+<!DOCTYPE html><html lang="en">
+ <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"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/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"/>
+ </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>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Issue Tracker</h1></header><p>Apache Sling uses Jira for tracking bug reports and requests for improvements, new features, and other changes.</p>
+<p>The issue tracker is available at <a href="https://issues.apache.org/jira/browse/SLING">https://issues.apache.org/jira/browse/SLING</a> and is readable by everyone. A Jira account is needed to create new issues and to comment on existing issues. Use the <a href="https://issues.apache.org/jira/secure/Signup!default.jspa">registration form</a> to request an account if you do not already have one.</p>
+<p>See below for guidelines on creating and managing issues.</p>
+<h2>Issue type</h2>
+<p>When creating a new issue, select the issue type based as follows:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Issue type </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><em>Bug</em> </td>
+ <td>Bug reports are used for cases where Sling fails not function as it should (as defined by some documentation). If you are not certain whether the issue you've found is actually a bug, please ask the <a href="/project-information.html#mailing-lists">Sling mailing lists</a> first for help. </td>
+ </tr>
+ <tr>
+ <td><em>New Feature</em> </td>
+ <td>Use a feature request when Sling does not have some functionality you need. </td>
+ </tr>
+ <tr>
+ <td><em>Improvement</em> </td>
+ <td>Use an improvement request to suggest improvements to existing features. Typical improvement requests are about updating documentation, increasing stability and performance, simplifying the implementation, or other such changes that make Sling better without introducing new features or fixing existing bugs. </td>
+ </tr>
+ <tr>
+ <td><em>Test</em> </td>
+ <td>Use this type when contributing test cases for existing features. Normally test cases should be contributed as a part of the original feature request or as regression tests associated with bug reports, but sometimes you just want to extend test coverage by introducing new test cases. This issue type is for such cases. </td>
+ </tr>
+ <tr>
+ <td><em>Task</em> </td>
+ <td>Used only for issues related to project infrastructure. </td>
+ </tr>
+ </tbody>
+</table>
+<h2>Summary</h2>
+<p>The issue summary should be a short and clear statement that indicates the scope of the issue. You are probably being too verbose if you exceed the length of the text field. Use the Environment and Description fields to provide more detailed information.</p>
+<h2>Issue priority</h2>
+<p>Issue priority should be set according to the following:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Issue priority </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><em>Blocker</em> </td>
+ <td>Legal or other fundamental issue that makes it impossible to release Jackrabbit code </td>
+ </tr>
+ <tr>
+ <td><em>Critical</em> </td>
+ <td>Major loss of functionality that affects many Slingusers </td>
+ </tr>
+ <tr>
+ <td><em>Major</em> </td>
+ <td>Important issue that should be resolved soon </td>
+ </tr>
+ <tr>
+ <td><em>Minor</em> </td>
+ <td>Nice to have issues </td>
+ </tr>
+ <tr>
+ <td><em>Trivial</em> </td>
+ <td>Trivial changes that can be applied whenever someone has extra time </td>
+ </tr>
+ </tbody>
+</table>
+<h2>Issue States</h2>
+<p>Sling issues can transition through a number of states while being processed:</p>
+<table>
+ <thead>
+ <tr>
+ <th>State </th>
+ <th>Description </th>
+ <th>Next States in Workflow </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><em>Open</em> </td>
+ <td>The issue has just been created </td>
+ <td><em>In Pogress</em> </td>
+ </tr>
+ <tr>
+ <td><em>In Progress</em> </td>
+ <td>Work has started on the issue </td>
+ <td><em>Documentation Required</em>, <em>Testcase Required</em>, <em>Documentation/Testcase required</em>, <em>Resolved</em>, <em>Open</em> </td>
+ </tr>
+ <tr>
+ <td><em>Documentation Required</em> </td>
+ <td>Implementation work has finished for this issue. To complete it documentation must be created and/or updated. </td>
+ <td><em>Resolved</em> </td>
+ </tr>
+ <tr>
+ <td><em>Testcase Required</em> </td>
+ <td>Implementation work has finished for this issue. To complete it test cases must be created and/or updated. </td>
+ <td><em>Resolved</em> </td>
+ </tr>
+ <tr>
+ <td><em>Documentation/Testcase Required</em> </td>
+ <td>Implementation work has finished for this issue. To complete it documentation and test cases must be created and/or updated. </td>
+ <td><em>Resolved</em>, <em>Documentation Required</em>, <em>Testcase Required</em> </td>
+ </tr>
+ <tr>
+ <td><em>Resolved</em> </td>
+ <td>The issue has been resolved from the developers point of view. Documentation and Testcases have been created and updated as required. Issue is ready for release. </td>
+ <td><em>Reopened</em>, <em>Closed</em> </td>
+ </tr>
+ <tr>
+ <td><em>Reopened</em> </td>
+ <td>A resolved issue has been recognized to contain bugs or to be incomplete and thus has been reopened. </td>
+ <td><em>In Progress</em>, <em>Resolved</em> </td>
+ </tr>
+ </tbody>
+</table>
+<p>| <em>Closed</em> | Work on this issue has finished and it is included in the release. | -- |</p>
+<p>Users generally create issues and provide feedback while work on the issue is in progress. When the developer thinks the issue has been resolved, he resolves the issue. At this point, the user may test the resolution and reopen the issue if it has not really be solved. Otherwise the user may just acknowledge the fix.</p>
+<p>Developers transition the issue through the workflow while working on it. When done with the issue, they mark the issue resolved with the appropriate resolution and ask the reporting user to confirm.</p>
+<p>Issues are closed once the project against which it has been reported has been released. Issues once closed cannot be opened again. Rather new issues should be created against the new release to have broken implementations fixed or extended.</p>
+<h2>Patches</h2>
+<p>When reporting a bug, requesting a feature or propose an improvement, it is a good thing to attach a patch to the issue. This may speed up issue processing and helps you being recognized as a good community member leading to closer involvement with Sling.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/development/jcr-mock.html
----------------------------------------------------------------------
diff --git a/documentation/development/jcr-mock.html b/documentation/development/jcr-mock.html
new file mode 100644
index 0000000..6bc7b9f
--- /dev/null
+++ b/documentation/development/jcr-mock.html
@@ -0,0 +1,72 @@
+<!DOCTYPE html><html lang="en">
+ <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"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/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"/>
+ </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>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>JCR Mocks</h1></header><p>Mock implementation of selected JCR APIs for easier testing. It stores all data in-memory in a HashMap to ensure instantly creating and destroying of the JCR repository.</p>
+<p>[TOC]</p>
+<h2>Maven Dependency</h2>
+<h1>!xml</h1>
+<p><dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.testing.jcr-mock</artifactId> </dependency></p>
+<p>See latest version on the <a href="/downloads.cgi">downloads page</a>.</p>
+<h2>Implemented mock features</h2>
+<p>The mock implementation supports:</p>
+<ul>
+ <li>Reading and writing all data (primitive values, arrays, binary data) via the JCR API</li>
+ <li>Creating any number of nodes and properties (stored in-memory in a hash map)</li>
+ <li>Register namespaces</li>
+ <li>Queries are supported by setting expected results for a given query</li>
+</ul>
+<p>The following features are <em>not supported</em>:</p>
+<ul>
+ <li>Node types are supported in the API, but their definitions and constraints are not applied</li>
+ <li>Versioning not supported</li>
+ <li>Transactions not supported</li>
+ <li>Observation events can be registered but are ignored</li>
+ <li>Access control always grants access</li>
+ <li>Exporting/Importing data via document and system views not supported</li>
+ <li>Workspace management methods not supported</li>
+</ul>
+<h2>Usage</h2>
+<h3>Getting JCR mock objects</h3>
+<p>The factory class <code>MockJcr</code> allows to instantiate the different mock implementations.</p>
+<p>Example:</p>
+<h1>!java</h1>
+<p>// get session Session session = MockJcr.newSession();</p>
+<p>// get repository Repository repository = MockJcr.newRepository();</p>
+<p>The repository is empty and contains only the root node. You can use the JCR API to read or write content.</p>
+<h3>Mocking queries</h3>
+<p>If you want to test code that contains a JCR query you can simulate a query execution and set the result to return during setting up your unit test.</p>
+<p>Example:</p>
+<h1>!java</h1>
+<p>// prepare mocked search result List<Node> resultNodes = ImmutableList.of(node1, node2, node3);</p>
+<p>// return this result for all queries MockJcr.setQueryResult(session, resultNodes);</p>
+<p>// return this result for a specific query MockJcr.setQueryResult(session, "your query statement", Query.JCR_SQL2, resultNodes);</p>
+<p>Alternatively you can use the <code>MockJcr.addQueryResultHandler</code> method to pass a callback object that allows you to return a query result after inspecting the given query object.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/development/jspc.html
----------------------------------------------------------------------
diff --git a/documentation/development/jspc.html b/documentation/development/jspc.html
new file mode 100644
index 0000000..b4754d8
--- /dev/null
+++ b/documentation/development/jspc.html
@@ -0,0 +1,33 @@
+<!DOCTYPE html><html lang="en">
+ <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"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/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"/>
+ </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>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>HTL Maven Plugin</h1></header><p>See <a href="http://sling.apache.org/components/jspc-maven-plugin/">Apache Sling JspC Maven Plugin documentation</a>.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/development/jsr-305.html
----------------------------------------------------------------------
diff --git a/documentation/development/jsr-305.html b/documentation/development/jsr-305.html
new file mode 100644
index 0000000..18e5c38
--- /dev/null
+++ b/documentation/development/jsr-305.html
@@ -0,0 +1,75 @@
+<!DOCTYPE html><html lang="en">
+ <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"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/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"/>
+ </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>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Leveraging JSR-305 null annotations to prevent NullPointerExceptions</h1></header><p>[TOC]</p>
+<h1>Introduction</h1>
+<p>The Sling API forces developers to sometimes check for <code>null</code> return values. Most prominently this is the case for <a href="https://sling.apache.org/apidocs/sling8/org/apache/sling/api/adapter/Adaptable.html#adaptTo-java.lang.Class-"><code>Adaptable.adaptTo</code></a> and <a href="https://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceResolver.html#getResource-java.lang.String-"><code>ResourceResolver.getResource</code></a>. This is often forgotten, which may lead to <code>NullPointerException</code>s. Sling API 2.9.0 introduced the JSR-305 annotations (<a href="https://issues.apache.org/jira/browse/SLING-4377">SLING-4377</a>) which allow tools to check automatically for missing null checks in the code.</p>
+<h1>Annotations</h1>
+<p>The annotations used within Sling are based on the <a href="https://jcp.org/en/jsr/detail?id=305">JSR-305</a> which is dormant since 2012. Nevertheless those annotations are understood by most of the tools and used by other Apache Projects like Apache Oak <a href="https://issues.apache.org/jira/browse/OAK-37">OAK-37</a>.</p>
+<p>Due to the fact that Eclipse and FindBugs are interpreting annotations differently (<a href="https://sourceforge.net/p/findbugs/bugs/1355/">Findbugs-1355</a>). Sling only uses the following two different annotations which are supported by both tools:</p>
+<ol>
+ <li><code>javax.annotation.CheckForNull</code></li>
+ <li><code>javax.annotation.Nonnull</code></li>
+</ol>
+<p>Annotations which support setting the default null semantics of return values and or parameters on a package level cannot be leveraged for that reason.</p>
+<p>The annotations have a retention policy of <code>runtime</code>, therefore bundles using these automatically have a <code>Import-Package</code> header listing <code>javax.annotation</code>. That package is by default exported by the system bundle (as this package is also part of the <a href="https://docs.oracle.com/javase/7/docs/api/javax/annotation/package-summary.html">JRE</a>). To be able to resolve the bundle through this exported package from the system bundle you should use the <code>com.google.code.findbugs:jsr305</code> artifact in version 3.0.0 as that exports the package <code>javax.annotation</code> in no specific version. Newer versions use version directives which automatically restrict the version range for the generated <code>Import-Package</code> header to <code>[3,4)</code> <a href="https://github.com/amaembo/jsr-305/issues/31">which usually cannot be resolved at run time</a>.</p>
+<h1>Use With Eclipse</h1>
+<p>Eclipse since Juno supports <a href="http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fpreferences%2Fjava%2Fcompiler%2Fref-preferences-errors-warnings.htm&anchor=null_analysis">null analysis based on any annotations</a>. Those need to be enabled in <em>Preferences->Java->Compiler->Errors/Warnings</em> via <strong>Enable annoation-based null analysis</strong>. Also the annotations need to be configured. For Sling/JSR 305 those are</p>
+<ul>
+ <li><code>javax.annotation.CheckForNull</code> as <strong>'Nullable' annotation</strong> (primary annotation)</li>
+ <li><code>javax.annotation.Nonnull</code> as <strong>'NonNull' annotation</strong> (primary annotation)</li>
+</ul>
+<p><img src="eclipse-settings-null-analysis.png" alt="Eclipse Settings for Null analysis" /></p>
+<p>Unfortunately Eclipse cannot infer information about fields which are for sure either null or not null (reasoning is available in <a href="https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields">https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields</a> and <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=247564">Eclipse Bug 247564</a>). This also affecs constants (static final fields) or enums which are known to be non null, but still Eclipse will emit a warning like <em>The expression of type 'String' needs unchecked conversion to conform to '@Nonnull String'</em>. The only known workaround is to disable the <strong>"Unchecked conversion from non-annotated type to @NonNull type"</strong> or to annotate also the field with <code>@Nonnull</code>.</p>
+<p>More information are available at <a href="https://wiki.eclipse.org/JDT_Core/Null_Analysis">https://wiki.eclipse.org/JDT_Core/Null_Analysis</a>.</p>
+<p>Since Eclipse 4.5 (Mars) <strong>external annotations</strong> are supported as well (i.e. annotations maintained outside of the source code of the libraries, e.g. for the JRE, Apache Commons Lang). There are some external annotations being mainted at <a href="http://www.lastnpe.org/">lastnpe.org</a> and <a href="https://github.com/tracecompass/tracecompass/tree/master/common/org.eclipse.tracecompass.common.core/annotations">TraceCompass</a>. There is no official repository yet though (<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=449653">Eclipse Bug 449653</a>). <a href="http://www.lastnpe.org/">Lastnpe.org</a> provides also an m2e extension to ease setting up the classpaths with external annotations from within your pom.xml.</p>
+<h1>Use With Maven</h1>
+<h2>Leveraging Eclipse JDT Compiler (recommended)</h2>
+<p>You can use Eclipse JDT also in Maven (with null analysis enabled) for the regular compilation. That way it will give out the same warnings/errors as Eclipse and will also consider external annotations. JDT in its most recent version is provided by the <code>tycho-compiler-plugin</code> which can be hooked up with the <code>maven-compiler-plugin</code>. The full list of options for JDT is described in <a href="http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-using_batch_compiler.htm">here</a>. This method was presented by Michael Vorburger in his presentation <a href="https://www.slideshare.net/mikervorburger/the-end-of-the-world-as-we-know-it-aka-your-last-nullpointerexception-1b-bugs/14">The end of the world as we know it</a>.</p>
+<p>::xml <plugin> <artifactId>maven-compiler-plugin</artifactId> <version>3.5.1</version> <configuration> <source>1.8</source> <target>1.8</target> <showWarnings>true</showWarnings> <compilerId>jdt</compilerId> <compilerArguments> <!-- just take the full Maven classpath as external annotations --> <annotationpath>CLASSPATH</annotationpath> </compilerArguments> <!-- maintain the org.eclipse.jdt.core.prefs properties to options listed on
+http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm --> <compilerArgument>-err:nullAnnot,null,-missingNullDefault</compilerArgument> </configuration> <dependencies> <dependency> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-compiler-jdt</artifactId> <version>1.0.0</version> </dependency> </dependencies> </plugin></p>
+<h2>Leveraging FindBugs</h2>
+<p>You can also let Maven automatically run FindBugs to execute those checks via the <strong>findbugs-maven-plugin</strong>. For that just add the following plugin to your <code>pom.xml</code></p>
+<p>::xml <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>findbugs-maven-plugin</artifactId> <version>3.0.0</version> <configuration> <visitors>InconsistentAnnotations,NoteUnconditionalParamDerefs,FindNullDeref,FindNullDerefsInvolvingNonShortCircuitEvaluation</visitors> </configuration> <executions> <execution> <id>run-findbugs-fornullchecks</id> <goals> <goal>check</goal> </goals> </execution> </executions> </plugin></p>
+<p>The results are often very imprecise (<a href="http://jira.codehaus.org/browse/MFINDBUGS-208">MFINDBUGS-208</a>), especially when it comes to line numbers, therefore it is best to start the Findbugs GUI in case of errors found by this plugin via <code>mvn findbugs:gui</code>.</p>
+<h1>Use With FindBugs</h1>
+<p>FindBugs evaluates the JSR-305 annotations by default. You can restrict the rules to only the ones which check for those annotations, which are</p>
+<ul>
+ <li>InconsistentAnnotations</li>
+ <li>NoteUnconditionalParamDerefs</li>
+ <li>FindNullDeref</li>
+ <li>FindNullDerefsInvolvingNonShortCircuitEvaluation</li>
+</ul>
+<p>A complete list of visitors class names in Findbugs can be found in the <a href="https://code.google.com/p/findbugs/source/browse/#git%2Ffindbugs%2Fsrc%2Fjava%2Fedu%2Fumd%2Fcs%2Ffindbugs%2Fdetect%253Fstate%253Dclosed">sourcecode</a>. The according <a href="http://findbugs.sourceforge.net/bugDescriptions.html">bug patterns</a> have an identifier (in parenthesis) for which you can search in the according Java classes, in case you want to extend the checks.</p>
+<p>Findbugs is also integrated in <a href="http://docs.sonarqube.org/display/SONAR/Findbugs+Plugin">SonarQube</a> but for SonarQube you should now rather use the native Java plugin (look at <a href="#use-with-sonarqube">Use with SonarQube</a>).</p>
+<h1>Use with SonarQube</h1>
+<p>At least rule <a href="https://sonarqube.com/coding_rules#rule_key=squid%3AS2259">squid:S2259</a> in SonarQube supports JSR-305 annotations as well for null checks.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/development/logging.html
----------------------------------------------------------------------
diff --git a/documentation/development/logging.html b/documentation/development/logging.html
new file mode 100644
index 0000000..6b87cbf
--- /dev/null
+++ b/documentation/development/logging.html
@@ -0,0 +1,392 @@
+<!DOCTYPE html><html lang="en">
+ <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"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/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"/>
+ </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>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Logging</h1></header><div class="note">
+This document is for the new (November 2013) 4.x release of the Sling Commons Log components. Refer to
+<a href="http://sling.apache.org/documentation/legacy/logging.html">Logging 3.x</a> for older versions.
+</div>
+<p>[TOC]</p>
+<h2>Introduction</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. This bundle along with other bundles manages the Sling Logging and provides the following features:</p>
+<ul>
+ <li>Implements the OSGi Log Service Specification and registers the <code>LogService</code> and <code>LogReader</code> services</li>
+ <li>Exports three commonly used logging APIs:</li>
+ <li><a href="http://www.slf4j.org">Simple Logging Facade for Java (SLF4J)</a></li>
+ <li><a href="http://jakarta.apache.org/commons/logging">Apache Commons Logging</a></li>
+ <li><a href="http://logging.apache.org/log4j/index.html">log4j</a></li>
+ <li><a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html">java.util.logging</a></li>
+ <li>Configures logging through Logback which is integrated with the OSGi environment</li>
+ <li>Allows logging to be configured both via editing Logback xml or via OSGi Configurations</li>
+</ul>
+<h3>v5.0.0 release</h3>
+<p>With Sling Log 5.0.0. release the webconsole support has been moved to a different bundle named Sling Commons Log WebConsole (org.apache.sling.commons.log.webconsole:1.0.0)</p>
+<p>Also with this release Logback 1.1.7 version is embedded and thus it requires slf4j-api:1.7.15. See <a href="https://issues.apache.org/jira/browse/SLING-6144">SLING-6144</a> for details</p>
+<h2>WebConsole Plugin</h2>
+<p>The Web Console Plugin supports the following features:</p>
+<ul>
+ <li>Display the list of loggers which have levels or appenders configured.</li>
+ <li>List the file appenders with the location of current active log files.</li>
+ <li>Show the contents of LogBack config files.</li>
+ <li>Show the contents of various Logback config fragments.</li>
+ <li>Show Logback Status logs.</li>
+ <li>Inline edit the Logger setting</li>
+ <li>Configure Logger with content assist for logger names</li>
+ <li>Provides links to log file content allows log file content to be viewed from Web UI</li>
+</ul>
+<img src="sling-log-support.png" />
+<h2>WebTail</h2>
+<p>The Web Console Plugin also supports tailing of the current active log files. It generates link to all active log files which can be used to see there content from within the browser. The url used is like</p>
+<p><code>
+http://localhost:8080/system/console/slinglog/tailer.txt?tail=1000&grep=lucene&name=%2Flogs%2Ferror.log
+</code></p>
+<p>It supports following parameters</p>
+<ul>
+ <li><code>name</code> - Appender name like <em>/logs/error.log</em></li>
+ <li><code>tail</code> - Number of lines to include in dump. -1 to include whole file</li>
+ <li><code>grep</code> - Filter the log lines based on <code>grep</code> value which can be</li>
+ <li>Simple string phrase - In this case search is done in case insensitive way via String.contains</li>
+ <li>regex - In this case the search would be done via regex pattern matching</li>
+</ul>
+<h2>Initial Configuration</h2>
+<p>The <code>org.apache.sling.commons.log</code> bundle gets its initial configuration from the following <code>BundleContext</code> properties:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Property </th>
+ <th>Default </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>org.apache.sling.commons.log.level</code> </td>
+ <td><code>INFO</code> </td>
+ <td>Sets the initial logging level of the root logger. This may be any of the defined logging levels <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, <code>ERROR</code> and <code>FATAL</code>. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.file</code> </td>
+ <td>undefined </td>
+ <td>Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to <code>System.out</code>. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.file.number</code> </td>
+ <td>5 </td>
+ <td>The number of rotated files to keep. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.file.size</code> </td>
+ <td>'.'yyyy-MM-dd </td>
+ <td>Defines how the log file is rotated (by schedule or by size) and when to rotate. See the section <em>Log File Rotation</em> below for full details on log file rotation. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.pattern</code> </td>
+ <td>{0,date,dd.MM.yyyy HH:mm:ss.SSS} <em>{4}</em> [{2}]({{ refs.-2.path }}) {3} {5} </td>
+ <td>The <code>MessageFormat</code> pattern to use for formatting log messages with the root logger. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.julenabled</code> </td>
+ <td>n/a </td>
+ <td>Enables the <code>java.util.logging</code> support. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.configurationFile</code> </td>
+ <td>n/a </td>
+ <td>Path for the Logback config file which would be used to configure logging. If the path is not absolute then it would be resolved against Sling Home </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.packagingDataEnabled</code> </td>
+ <td>true </td>
+ <td>Boolean property to control packaging data support of Logback. See <a href="http://www.slf4j.org/manual.html#mdc">Packaging Data</a> section of Logback for more details </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.numOfLines</code> </td>
+ <td>1000 </td>
+ <td>Number of lines from each log files to include while generating the dump in 'txt' mode. If set to -1 then whole file would be included </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.maxOldFileCountInDump</code> </td>
+ <td>3 </td>
+ <td>Maximum number of old rolled over files for each active file to be included while generating the dump as part of Status zip support </td>
+ </tr>
+ <tr>
+ <td><code>sling.log.root</code> </td>
+ <td>Sling Home </td>
+ <td>The directory, which is used to resolve relative path names against. If not specified it would map to sling.home. Since <a href="https://issues.apache.org/jira/browse/SLING-4225">4.0.2</a></td>
+ </tr>
+ </tbody>
+</table>
+<h2>User Configuration - OSGi Based</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> to receive configurations.</p>
+<h3>Logger Configuration</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>
+ <thead>
+ <tr>
+ <th>Property </th>
+ <th>Type </th>
+ <th>Default </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>org.apache.sling.commons.log.level</code> </td>
+ <td><code>String</code> </td>
+ <td><code>INFO</code> </td>
+ <td>Sets the logging level of the loggers. This may be any of the defined logging levels <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, <code>ERROR</code> and <code>FATAL</code>. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.file</code> </td>
+ <td><code>String</code> </td>
+ <td>undefined </td>
+ <td>Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to <code>System.out</code>. This property should refer to the file name of a configured Log Writer (see below). If no Log Writer is configured with the same file name an implicit Log Writer configuration with default configuration is created. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.pattern</code> </td>
+ <td><code>String</code> </td>
+ <td>{0,date,dd.MM.yyyy HH:mm:ss.SSS} <em>{4}</em> [{2}]({{ refs.-2.path }}) {3} {5} </td>
+ <td>The <code>java.util.MessageFormat</code> pattern to use for formatting log messages with the root logger. This is a <code>java.util.MessageFormat</code> pattern supporting up to six arguments: {0} The timestamp of type <code>java.util.Date</code>, {1} the log marker, {2} the name of the current thread, {3} the name of the logger, {4} the log level and {5} the actual log message. If the log call includes a Throwable, the stacktrace is just appended to the message regardless of the pattern. </td>
+ </tr>
+ </tbody>
+</table>
+<p>| <code>org.apache.sling.commons.log.names</code> | <code>String[]</code> | -- | A list of logger names to which this configuration applies. | | <code>org.apache.sling.commons.log.additiv</code> | <code>Boolean</code> | false | If set to false then logs from these loggers would not be sent to any appender attached higher in the hierarchy |</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. While the log level configuration is case insensitive, it is suggested to always use upper case letters.</p>
+<h3>Log Writer Configuration</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>
+ <thead>
+ <tr>
+ <th>Property </th>
+ <th>Default </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>org.apache.sling.commons.log.file</code> </td>
+ <td>undefined </td>
+ <td>Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to <code>System.out</code>. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.file.number</code> </td>
+ <td>5 </td>
+ <td>The number of rotated files to keep. </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.sling.commons.log.file.size</code> </td>
+ <td>'.'yyyy-MM-dd </td>
+ <td>Defines how the log file is rotated (by schedule or by size) and when to rotate. See the section <em>Log File Rotation</em> below for full details on log file rotation. </td>
+ </tr>
+ </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>
+<h4>Log File Rotation</h4>
+<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. In previous version, log rotation defaults to a 10MB file size limit.</p>
+<h5>Scheduled Rotation</h5>
+<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. Internally the Log bundle configures a <code>TimeBasedRollingPolicy</code> for the appender. Refer to <a href="http://logback.qos.ch/manual/appenders.html#TimeBasedRollingPolicy">TimeBasedRollingPolicy</a> for more details around the pattern format</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>
+<table>
+ <thead>
+ <tr>
+ <th>DatePattern </th>
+ <th>Rollover schedule </th>
+ <th>Example </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>'.'yyyy-MM</code> </td>
+ <td>Rollover at the beginning of each month </td>
+ <td>At midnight of May 31st, 2002 <code>/foo/bar.log</code> will be copied to <code>/foo/bar.log.2002-05</code>. Logging for the month of June will be output to <code>/foo/bar.log</code> until it is also rolled over the next month. </td>
+ </tr>
+ <tr>
+ <td><code>'.'yyyy-ww</code> </td>
+ <td>Rollover at the first day of each week. The first day of the week depends on the locale. </td>
+ <td>Assuming the first day of the week is Sunday, on Saturday midnight, June 9th 2002, the file <code>/foo/bar.log</code> will be copied to <code>/foo/bar.log.2002-23</code>. Logging for the 24th week of 2002 will be output to <code>/foo/bar.log</code> until it is rolled over the next week. </td>
+ </tr>
+ <tr>
+ <td><code>'.'yyyy-MM-dd</code> </td>
+ <td>Rollover at midnight each day.</td>
+ <td>At midnight, on March 8th, 2002, <code>/foo/bar.log</code> will be copied to <code>/foo/bar.log.2002-03-08</code>. Logging for the 9th day of March will be output to <code>/foo/bar.log</code> until it is rolled over the next day.</td>
+ </tr>
+ <tr>
+ <td><code>'.'yyyy-MM-dd-a</code> </td>
+ <td>Rollover at midnight and midday of each day.</td>
+ <td>at noon, on March 9th, 2002, <code>/foo/bar.log</code> will be copied to <code>/foo/bar.log.2002-03-09-AM</code>. Logging for the afternoon of the 9th will be output to <code>/foo/bar.log</code> until it is rolled over at midnight.</td>
+ </tr>
+ <tr>
+ <td><code>'.'yyyy-MM-dd-HH</code> </td>
+ <td>Rollover at the top of every hour.</td>
+ <td>At approximately 11:00.000 o'clock on March 9th, 2002, <code>/foo/bar.log</code> will be copied to <code>/foo/bar.log.2002-03-09-10</code>. Logging for the 11th hour of the 9th of March will be output to <code>/foo/bar.log</code> until it is rolled over at the beginning of the next hour.</td>
+ </tr>
+ <tr>
+ <td><code>'.'yyyy-MM-dd-HH-mm</code> </td>
+ <td>Rollover at the beginning of every minute.</td>
+ <td>At approximately 11:23,000, on March 9th, 2001, <code>/foo/bar.log</code> will be copied to <code>/foo/bar.log.2001-03-09-10-22</code>. Logging for the minute of 11:23 (9th of March) will be output to <code>/foo/bar.log</code> until it is rolled over the next minute.</td>
+ </tr>
+ </tbody>
+</table>
+<p>Do not use the colon ":" character in anywhere in the pattern option. The text before the colon is interpreted as the protocol specification 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>
+<h5>Size Rotation</h5>
+<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>
+<h2>Logback Integration</h2>
+<p>Logback integration provides following features</p>
+<ul>
+ <li>LogBack configuration can be provided via Logback config xml</li>
+ <li>Supports Appenders registered as OSGi Services</li>
+ <li>Supports Filters and TurboFilters registered as OSGi Services</li>
+ <li>Support providing Logback configuration as fragments through OSGi Service Registry</li>
+ <li>Support for referring to Appenders registered as OSGi services from with Logback config</li>
+ <li>Exposes Logback runtime state through the Felix WebConsole Plugin</li>
+</ul>
+<p>The following sections provide more details.</p>
+<h3>TurboFilters as OSGi Services</h3>
+<p><a href="http://logback.qos.ch/manual/filters.html#TurboFilter">Logback TurboFilters</a> operate globally and are invoked for every Logback call. To register an OSGi <code>TurboFilter</code>, just to register an service that implements the <code>ch.qos.logback.classic.turbo.TurboFilter</code> interface.</p>
+<p>:::java import import ch.qos.logback.classic.turbo.MatchingFilter;</p>
+<p>SimpleTurboFilter stf = new SimpleTurboFilter(); ServiceRegistration sr = bundleContext.registerService(TurboFilter.class.getName(), stf, null);</p>
+<p>private static class SimpleTurboFilter extends MatchingFilter { @Override public FilterReply decide(Marker marker, Logger logger, Level level, String format, Object[] params, Throwable t) { if(logger.getName().equals("turbofilter.foo.bar")){ return FilterReply.DENY; } return FilterReply.NEUTRAL; } }</p>
+<p>As these filters are invoked for every call they must execute quickly.</p>
+<h3>Filters as OSGi services</h3>
+<p><a href="http://logback.qos.ch/manual/filters.html">Logback Filters</a> are attached to appenders and are used to determine if any LoggingEvent needs to be passed to the appender. When registering a filter the bundle needs to configure a service property <code>appenders</code> which refers to list of appender names to which the Filter must be attached</p>
+<p>:::java import ch.qos.logback.core.filter.Filter;</p>
+<p>SimpleFilter stf = new SimpleFilter(); Dictionary<String, Object> props = new Hashtable<String, Object>(); props.put("appenders", "TestAppender"); ServiceRegistration sr = bundleContext.registerService(Filter.class.getName(), stf, props);</p>
+<p>private static class SimpleFilter extends Filter<ILoggingEvent> {</p>
+<p>@Override public FilterReply decide(ILoggingEvent event) { if(event.getLoggerName().equals("filter.foo.bar")){ return FilterReply.DENY; } return FilterReply.NEUTRAL; } }</p>
+<p>If the <code>appenders</code> value is set to <code>*</code> then the filter would be registered with all the appenders (<code>Since 4.0.4</code>)</p>
+<h3>Appenders as OSGi services</h3>
+<p><a href="http://logback.qos.ch/manual/appenders.html">Logback Appenders</a> handle the logging events produced by Logback. To register an OSGi <code>Appender</code>, just register a service that implements the <code>ch.qos.logback.core.Appender</code> interface. Such a service must have a <code>loggers</code> service property, which refers to list of logger names to which the Appender must be attached.</p>
+<p>:::java Dictionary<String,Object> props = new Hashtable<String, Object>();</p>
+<p>String[] loggers = { "foo.bar:DEBUG", "foo.bar.zoo:INFO", };</p>
+<p>props.put("loggers",loggers); sr = bundleContext.registerService(Appender.class.getName(),this,props);</p>
+<h3>Logback Config Fragment Support</h3>
+<p>Logback supports including parts of a configuration file from another file (See <a href="http://logback.qos.ch/manual/configuration.html#fileInclusion">File Inclusion</a>). This module extends that support by allowing other bundles to provide config fragments. There are two ways to achieve that, described below.</p>
+<h4>Logback config fragments as String objects</h4>
+<p>If you have the config as string then you can register that String instance as a service with property <code>logbackConfig</code> set to true. The Sling Logback Extension monitors such objects and passes them to logback.</p>
+<p>:::java Properties props = new Properties(); props.setProperty("logbackConfig","true");</p>
+<p>String config = "<included>n" + " <appender name="FOOFILE" class="ch.qos.logback.core.FileAppender">n" + " <file>${sling.home}/logs/foo.log</file>n" + " <encoder>n" + " <pattern>%d %-5level %logger{35} - %msg %n</pattern>n" + " </encoder>n" + " </appender>n" + "n" + " <logger name="foo.bar.include" level="INFO">n" + " <appender-ref ref="FOOFILE" />n" + " </logger>n" + "n" + "</included>";</p>
+<p>registration = context.registerService(String.class.getName(),config,props);</p>
+<p>If the config needs to be updated just re-register the service so that changes are picked up.</p>
+<h4>Logback config fragments as ConfigProvider instances</h4>
+<p>Another way to provide config fragments is with services that implement the <code>org.apache.sling.commons.log.logback.ConfigProvider</code> interface.</p>
+<p>:::java @Component @Service public class ConfigProviderExample implements ConfigProvider { public InputSource getConfigSource() { return new InputSource(getClass().getClassLoader().getResourceAsStream("foo-config.xml")); } }</p>
+<p>If the config changes then sending an OSGi event with the <code>org/apache/sling/commons/log/RESET</code> topic resets the Logback runtime.</p>
+<p>:::java eventAdmin.sendEvent(new Event("org/apache/sling/commons/log/RESET",new Properties()));</p>
+<h3>External Config File</h3>
+<p>Logback can be configured with an external file. The file name can be specified through</p>
+<ol>
+ <li>OSGi config - Look for a config with name <code>Apache Sling Logging Configuration</code> and specify the config file path.</li>
+ <li>OSGi Framework Properties - Logback support also looks for a file named according to the OSGi framwork <code>org.apache.sling.commons.log.configurationFile</code> property.</li>
+</ol>
+<p>If you are providing an external config file then to support OSGi integration you need to add following action entry:</p>
+<p>:::xml <newRule pattern="*/configuration/osgi"
+actionClass="org.apache.sling.commons.log.logback.OsgiAction"/> <newRule pattern="*/configuration/appender-ref-osgi"
+actionClass="org.apache.sling.commons.log.logback.OsgiAppenderRefAction"/> <osgi/></p>
+<p>The <code>osgi</code> element enables the OSGi integration support</p>
+<h3>Java Util Logging (JUL) Integration</h3>
+<p>The bundle also support <a href="http://www.slf4j.org/api/org/slf4j/bridge/SLF4JBridgeHandler.html">SLF4JBridgeHandler</a>. The two steps listed below enable the JUL integration. This allows for routing logging messages from JUL to the Logbback appenders.</p>
+<ol>
+ <li>Set the <code>org.apache.sling.commons.log.julenabled</code> framework property to true.</li>
+</ol>
+<p>If <code>org.apache.sling.commons.log.julenabled</code> is found to be true then <a href="http://logback.qos.ch/manual/configuration.html#LevelChangePropagator">LevelChangePropagator</a> would be registered automatically with Logback</p>
+<h3><a name="config-override"></a>Configuring OSGi appenders in the Logback Config</h3>
+<p>So far Sling used to configure the appenders based on OSGi config. This provides a very limited set of configuration options. To make use of other Logback features you can override the OSGi config from within the Logback config file. OSGi config based appenders are named based on the file name.</p>
+<p>For example, for the following OSGi config</p>
+<p>org.apache.sling.commons.log.file="logs/error.log" org.apache.sling.commons.log.level="INFO" org.apache.sling.commons.log.file.size="'.'yyyy-MM-dd" org.apache.sling.commons.log.file.number=I"7" org.apache.sling.commons.log.pattern="{0,date,dd.MM.yyyy HH:mm:ss.SSS} <em>{4}</em> [{2}] {3} {5}"</p>
+<p>The Logback appender would be named <code>logs/error.log</code>. To extend/override the config in a Logback config create an appender with the name <code>logs/error.log</code>:</p>
+<p>:::xml <appender name="/logs/error.log" class="ch.qos.logback.core.FileAppender"> <file>${sling.home}/logs/error.log</file> <encoder> <pattern>%d %-5level %X{sling.userId:-NA} [%thread] %logger{30} %marker- %msg %n</pattern> <immediateFlush>true</immediateFlush> </encoder> </appender></p>
+<p>In this case the logging module creates an appender based on the Logback config instead of the OSGi config. This can be used to move the application from OSGi based configs to Logback based configs.</p>
+<h2>Using Slf4j API 1.7</h2>
+<p>With Slf4j API 1.7 onwards its possible to use logger methods with varargs i.e. log n arguments without constructing an object array e.g. <code>log.info("This is a test {} , {}, {}, {}",1,2,3,4)</code>. Without var args you need to construct an object array <code>log.info("This is a test {} , {}, {}, {}",new Object[] {1,2,3,4})</code>. To make use of this API and still be able to use your bundle on Sling systems which package older version of the API jar, follow the below steps. (See <a href="https://issues.apache.org/jira/browse/SLING-3243">SLING-3243</a>) for more details.</p>
+<ol>
+ <li>Update the api version in the pom:</li>
+</ol>
+<p>:::xml <dependencies> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>1.7.5</version> <scope>provided</scope> </dependency> ... </dependency></p>
+<ol>
+ <li>Add an <code>Import-Package</code> instruction with a custom version range:</li>
+</ol>
+<p>:::xml <build> <plugins> <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <extensions>true</extensions> <configuration> <instructions> ... <Import-Package> org.slf4j;version="[1.5,2)", * </Import-Package> </instructions> </configuration> </plugin> ... </plugins> </build></p>
+<p>The Slf4j API bundle 1.7.x is binary compatible with 1.6.x.</p>
+<p>This setup allows your bundles to make use of the var args feature while making logging calls, but the bundles can still be deployed on older systems which provide only the 1.6.4 version of the slf4j api.</p>
+<h2>Log Tracer</h2>
+<p>Log Tracer provides support for enabling the logs for specific category at specific level and only for specific request. It provides a very fine level of control via config provided as part of HTTP request around how the logging should be performed for given category.</p>
+<p>Refer to <a href="/documentation/bundles/log-tracers.html">Log Tracer Doc</a> for more details</p>
+<h2>Slf4j MDC</h2>
+<p>Sling MDC Inserting Filter exposes various request details as part of <a href="http://www.slf4j.org/manual.html#mdc">MDC</a>.</p>
+<p>Currently it exposes following variables:</p>
+<ol>
+ <li><code>req.remoteHost</code> - Request remote host</li>
+ <li><code>req.userAgent</code> - User Agent Header</li>
+ <li><code>req.requestURI</code> - Request URI</li>
+ <li><code>req.queryString</code> - Query String from request</li>
+ <li><code>req.requestURL</code> -</li>
+ <li><code>req.xForwardedFor</code> -</li>
+ <li><code>sling.userId</code> - UserID associated with the request. Obtained from ResourceResolver</li>
+ <li><code>jcr.sessionId</code> - Session ID of the JCR Session associated with current request.</li>
+</ol>
+<p>The filter also allow configuration to extract data from request cookie, header and parameters. Look for configuration with name 'Apache Sling Logging MDC Inserting Filter' for details on specifying header, cookie, param names.</p>
+<p><img src="/documentation/bundles/mdc-filter-config.png" alt="MDC Filter Config" /></p>
+<a name="mdc-pattern">
+<h3>Including MDC in Log Message</h3>
+<p>To include the MDC value in log message you MUST use the <a href="http://logback.qos.ch/manual/layouts.html#conversionWord">Logback pattern</a> based on Logback and not the old MessageFormat based pattern.</p>
+<p>%d{dd.MM.yyyy HH:mm:ss.SSS} <em>%p</em> [%X{req.remoteHost}] [%t] %c %msg%n</p>
+<h3>Installation</h3>
+<p>Download the bundle from <a href="http://sling.apache.org/downloads.cgi">here</a> or use following Maven dependency</p>
+<p>::xml <dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.extensions.slf4j.mdc</artifactId> <version>1.0.0</version> </dependency></p>
+<h2>Logback Groovy Fragment</h2>
+<p>This fragment is required to make use of Groovy based event evaluation support provided by Logback. This enables programatic filtering of the log messages and is useful to get desired logs without flooding the system. For example Oak logs the JCR operations being performed via a particular session. if this lo is enabled it would flood the log with messages from all the active session. However if you need logging only from session created in a particular thread then that can be done in following way</p>
+<p>::xml <?xml version="1.0" encoding="UTF-8"?> <configuration scan="true" scanPeriod="1 second"> <jmxConfigurator/> <newRule pattern="*/configuration/osgi" actionClass="org.apache.sling.commons.log.logback.OsgiAction"/> <newRule pattern="*/configuration/appender-ref-osgi" actionClass="org.apache.sling.commons.log.logback.OsgiAppenderRefAction"/> <osgi/></p>
+<p><appender name="OAK" class="ch.qos.logback.core.FileAppender"> <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> <evaluator class="ch.qos.logback.classic.boolex.GEventEvaluator"> <expression><![CDATA[ return e.getThreadName().contains("JobHandler"); ]]></expression> </evaluator> <OnMismatch>DENY</OnMismatch> <OnMatch>ACCEPT</OnMatch> </filter> <file>${sling.home}/logs/oak.log</file> <encoder> <pattern>%d %-5level [%thread] %marker- %msg %n</pattern> <immediateFlush>true</immediateFlush> </encoder> </appender></p>
+<p><logger name="org.apache.jackrabbit.oak.jcr.operations" level="DEBUG" additivity="false"> <appender-ref ref="OAK"/> </logger> </configuration></p>
+<p>Logback exposes a variable <code>e</code> which is of type <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/spi/ILoggingEvent.html">ILoggingEvent</a>. It provides access to current logging event. Above logback config would route all log messages from <code>org.apache.jackrabbit.oak.jcr.operations</code> category to <code>${sling.home}/logs/oak.log</code>. Further only those log messages would be logged where the <code>threadName</code> contains <code>JobHandler</code>. Depending on the requirement the expression can be customised.</p>
+<h3>Installation</h3>
+<p>Currently the bundle is not released and has to be build from <a href="http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/logback-groovy-fragment/">here</a></p>
+<p>::xml <dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.extensions.logback-groovy-fragment</artifactId> <version>1.0.0-SNAPSHOT</version> </dependency></p>
+<h2>FAQ</h2>
+<h5>Q. Can Sling Commons Log bundle be used in non Sling environments</h5>
+<p>This bundle does not depend on any other Sling bundle and can be easily used in any OSGi framework. To get complete log support working you need to deploy following bundles</p>
+<ul>
+ <li>Slf4j-Api - org.slf4j:slf4j-api</li>
+ <li>Jcl over Slf4j - org.slf4j:jcl-over-slf4j</li>
+ <li>Log4j over Slf4j - org.slf4j:log4j-over-slf4j</li>
+ <li>Sling Log Service - org.apache.sling:org.apache.sling.commons.logservice:1.0.2</li>
+ <li>Sling Commons Log - org.apache.sling:org.apache.sling.commons.log:4.0.0 or above</li>
+ <li>Sling Log WebConsole - org.apache.sling.commons.log.webconsole:1.0.0 or above</li>
+</ul>
+<h5>Q. How to start Sling with an external logback.xml file</h5>
+<p>You need to specify the location of logback.xml via <code>org.apache.sling.commons.log.configurationFile</code></p>
+<p>java -jar org.apache.sling.launchpad-XXX-standalone.jar -Dorg.apache.sling.commons.log.configurationFile=/path/to/logback</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/development/maven-archetypes.html
----------------------------------------------------------------------
diff --git a/documentation/development/maven-archetypes.html b/documentation/development/maven-archetypes.html
new file mode 100644
index 0000000..c647576
--- /dev/null
+++ b/documentation/development/maven-archetypes.html
@@ -0,0 +1,46 @@
+<!DOCTYPE html><html lang="en">
+ <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"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/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"/>
+ </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>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Maven Archetypes</h1></header><p>translation_pending: true</p>
+<p>Sling includes four Maven archetypes to quick start development. See <a href="http://maven.apache.org/archetype/maven-archetype-plugin/">http://maven.apache.org/archetype/maven-archetype-plugin/</a> for general information on using Maven archetypes. The Maven groupId for all Sling archetypes is <code>org.apache.sling</code>.</p>
+<h3>sling-launchpad-standalone-archetype</h3>
+<p>This archetype generates a Maven project which will build a standalone Launchpad JAR file using the default bundle set. For demonstration purposes, the generated project includes an extra bundle list file (<code>src/main/bundles/list</code>) which includes Apache Felix FileInstall as well as a test configuration file (<code>src/test/config/sling.properties</code>).</p>
+<h3>sling-launchpad-webapp-archetype</h3>
+<p>This archetype generates a Maven project which will build a Launchpad WAR file using the default bundle set. For demonstration purposes, the generated project includes an extra bundle list file (<code>src/main/bundles/list</code>) which includes Apache Felix FileInstall as well as a test configuration file (<code>src/test/config/sling.properties</code>).</p>
+<h3>sling-intitial-content-archetype</h3>
+<p>This archetype generates a Maven project which will build an OSGi bundle that supports JCR NodeType registration (in <code>SLING-INF/nodetypes/nodetypes.cnd</code>) and initial content loading (in <code>SLING-INF/scripts</code> and <code>SLING-INF/content</code>).</p>
+<h3>sling-servlet-archetype</h3>
+<p>This archetype generates a Maven project which will build an OSGi bundle containing two Servlets registered with Sling, one registered by path and one registered by resource type.</p>
+<h3>sling-bundle-archetype</h3>
+<p>This archetype generates a Maven project which will build a basic OSGi bundle including support for the Felix SCR Annotations. It is pre-configured to install using the Felix Web Console when the profile <code>autoInstallBundle</code> is activated.</p>
+<h3>sling-jcrinstall-bundle-archetype</h3>
+<p>This archetype generates a Maven project which will build a basic OSGi bundle including support for the Felix SCR Annotations. It is pre-configured to install using a WebDAV PUT into the JCR when the profile <code>autoInstallBundle</code> is activated.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/development/maven-launchpad-plugin.html
----------------------------------------------------------------------
diff --git a/documentation/development/maven-launchpad-plugin.html b/documentation/development/maven-launchpad-plugin.html
new file mode 100644
index 0000000..af6a239
--- /dev/null
+++ b/documentation/development/maven-launchpad-plugin.html
@@ -0,0 +1,133 @@
+<!DOCTYPE html><html lang="en">
+ <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"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/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"/>
+ </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>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Maven Launchpad Plugin</h1></header><p>translation_pending: true</p>
+<div class="note">
+This page is out of sync with the latest maven-launchpad-plugin features and settings. For now,
+refer to the source code and the launchpad/builder and launchpad/testing modules for more information.
+</div>
+<p>The Maven Launchpad Plugin provides goals which facilitate the creation of OSGi applications. It supports the following runtime scenarios:</p>
+<ul>
+ <li>A WAR file suitable for running in a JavaEE servlet container.</li>
+ <li>A standalone Java application, with HTTP support from the Felix HttpService implementation</li>
+ <li>Inside Apache Karaf</li>
+</ul>
+<p>In addition, the Maven Launchpad Plugin supports the publishing of an application descriptor, in the form of a <em>bundle list</em>, as a Maven artifact. This descriptor can then be used by downstream application builders as the basis for other applications. In Sling, this is embodied by two Maven projects:</p>
+<ul>
+ <li><a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/builder">org.apache.sling.launchpad</a> - produces an application descriptor.</li>
+ <li><a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/">org.apache.sling.launchpad.testing</a> - uses the application descriptor from <code>org.apache.sling.launchpad</code> and adds two bundles.</li>
+</ul>
+<p>Maven Launchpad Plugin provides the following goals:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Goals </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>launchpad:prepare-package </td>
+ <td>Create the file system structure required by Sling's Launchpad framework. </td>
+ </tr>
+ <tr>
+ <td>launchpad:attach-bundle-list </td>
+ <td>Attach the bundle list descriptor to the current project as a Maven artifact. </td>
+ </tr>
+ <tr>
+ <td>launchpad:create-karaf-descriptor </td>
+ <td>Create an Apache Karaf Feature descriptor. </td>
+ </tr>
+ <tr>
+ <td>launchpad:create-bundle-jar </td>
+ <td>Create a JAR file containing the bundles in a Launchpad-structured JAR file. </td>
+ </tr>
+ <tr>
+ <td>launchpad:check-bundle-list-for-snapshots </td>
+ <td>Validate that the bundle list does not contain any SNAPSHOT versions. </td>
+ </tr>
+ <tr>
+ <td>launchpad:run </td>
+ <td>Run a Launchpad application. </td>
+ </tr>
+ <tr>
+ <td>launchpad:start </td>
+ <td>Start a Launchpad application. </td>
+ </tr>
+ <tr>
+ <td>launchpad:stop </td>
+ <td>Stop a Launchpad application. </td>
+ </tr>
+ <tr>
+ <td>launchpad:output-bundle-list </td>
+ <td>Output the bundle list to the console as XML. (added in version 2.0.8) </td>
+ </tr>
+ </tbody>
+</table>
+<h3>General Configuration</h3>
+<p>In general, the bulk of the configuration of the Maven Launchpad Plugin is concerned with setting up the bundle list which all of the goals will use. This bundle list is created using the following steps:</p>
+<ol>
+ <li>If <code>includeDefaultBundles</code> is <code>true</code> (the default), the default bundle list is loaded. By default, this is <code>org.apache.sling.launchpad:org.apache.sling.launchpad:RELEASE:xml:bundlelist</code>, but can be overridden by setting the <code>defaultBundleList</code> plugin parameter.</li>
+ <li>If <code>includeDefaultBundles</code> is <code>false</code>, an empty list is created.</li>
+ <li>If the bundle list file exists (by default, at <code>src/main/bundles/list.xml</code>), the bundles defined in it are added to the bundle list.</li>
+ <li>If the <code>additionalBundles</code> plugin parameter is defined, those bundles are added to the bundle list.</li>
+ <li>If the <code>bundleExclusions</code> plugin parameter is defined, those bundles are removed from the bundle list.</li>
+</ol>
+<p>When a bundle is added to the bundle list, if a bundle with the same groupId, artifactId, type, and classifier is already in the bundle list, the version of the existing bundle is modified. However, the start level of a bundle is never changed once that bundle is added to the bundle list.</p>
+<p>The plugin may also contribute bundles to (or remove bundles from) the bundle list as it sees fit.</p>
+<h3>Framework Configuration</h3>
+<p>For the <code>run</code> and <code>start</code> goals, the plugin will look for a file named <code>src/test/config/sling.properties</code>. If this file is present, it will be filtered using standard Maven filtering and used to populate the OSGi framework properties. This can be used, for example, to specify a <code>repository.xml</code> file to be used during development:</p>
+<p>sling.repository.config.file.url=${basedir}/src/test/config/repository.xml</p>
+<h2>Bundle List Files</h2>
+<p>The bundle list file uses a simple XML syntax representing a list of bundles organized into start levels:</p>
+<p><?xml version="1.0"?> <bundles> <startLevel level="0"> <bundle> <groupId>commons-io</groupId> <artifactId>commons-io</artifactId> <version>1.4</version> </bundle> <bundle> <groupId>commons-collections</groupId> <artifactId>commons-collections</artifactId> <version>3.2.1</version> </bundle> </startLevel></p>
+<p><startLevel level="10"> <bundle> <groupId>org.apache.felix</groupId> <artifactId>org.apache.felix.eventadmin</artifactId> <version>1.0.0</version> </bundle> </startLevel></p>
+<p><startLevel level="15"> <bundle> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.jcr.api</artifactId> <version>2.0.2-incubator</version> </bundle> </startLevel> </bundles></p>
+<p>Within each <code>bundle</code> element, <code>type</code> and <code>classifier</code> are also supported.</p>
+<p>The Http Service support can not be configured using the bundle list, but only using the <code>jarWebSupport</code> parameter, since it is specific to whether the Sling Launchpad is built as a java application (in which case the Jetty-based Http Service is used) or a web application (in which case the Http Service bridge is used).</p>
+<h2>Artifact Definition</h2>
+<p>The <code>defaultBundleList</code>, <code>jarWebSupport</code>, <code>additionalBundles</code>, and <code>bundleExclusions</code> parameters are configured with artifact definitions. This is done using a syntax similar to Maven dependency elements:</p>
+<p><configuration> ... <jarWebSupport> <groupId>GROUP_ID</groupId> <artifactId>ARTIFACT_ID</artifactId> <version>VERSION</version> <!-- type and classifier can also be specified if needed --> </jarWebSupport> ... </configuration></p>
+<p>For example, to use Pax Web instead of Felix HttpService as the HttpService provider, use the following:</p>
+<p><configuration> ... <jarWebSupport> <groupId>org.ops4j.pax.web</groupId> <artifactId>pax-web-service</artifactId> <version>RELEASE</version> <!-- type and classifier can also be specified if needed --> </jarWebSupport> ... </configuration></p>
+<p>In the case of <code>additionalBundles</code> and <code>bundleExclusions</code>, these are arrays of definitions, so an intermediate <code>bundle</code> element is necessary:</p>
+<p><configuration> ... <additionalBundles> <bundle> <groupId>GROUP_ID</groupId> <artifactId>ARTIFACT_ID</artifactId> <version>VERSION</version> <!-- type and classifier can also be specified if needed --> </bundle> </additionalBundles> ... </configuration></p>
+<p>By default, bundles are added to start level 0. To change, this use the <code>startLevel</code> element within each additional bundle definition.</p>
+<h2>Integration Testing</h2>
+<p>For integration testing examples, see <code>/samples/inplace-integration-test</code> and <code>launchpad/testing</code> in the Sling source tree.</p>
+<h2>Bundle List Rewriting</h2>
+<p>The Maven Launchpad Plugin supports the use of rules to rewrite the bundle list. These rules are executed by the <a href="http://www.jboss.org/drools">Drools</a> rule engine. Typically, this is used along with Maven profiles. For example, Sling's testing project includes a profile called <code>test-reactor-sling-bundles</code>. When activated, this profile runs a Drools rule file which scans the project list from the Maven reactor and modifies the version number for bundles which were contained within the reactor.</p>
+<p>In order for rules to interact with the Maven build, the following global variables are made available:</p>
+<ul>
+ <li><code>mavenSession</code> - an instance of <code>org.apache.maven.execution.MavenSession</code>.</li>
+ <li><code>mavenProject</code> - an instance of <code>org.apache.maven.project.MavenProject</code>.</li>
+</ul></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </div><div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+
+ </div>
+ </body>
+</html>