http://git-wip-us.apache.org/repos/asf/sling-site/blob/f47e8676/documentation/bundles/sling-query/operators.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/sling-query/operators.html b/documentation/bundles/sling-query/operators.html new file mode 100644 index 0000000..07e0aed --- /dev/null +++ b/documentation/bundles/sling-query/operators.html @@ -0,0 +1,115 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";><html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> + <title>Apache Sling :: Operators</title> + <link rel="icon" href="/ng/res/favicon.ico"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"/> + <script src='https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js'></script><script> + hljs.initHighlightingOnLoad(); + </script> + + </head> <body> +<div class="title"> + <div class="logo"> + <a href="http://sling.apache.org";> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> + </a> + </div><div class="header"> + <a href="http://www.apache.org";> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> + </a> + </div> + </div><h1 class="draft">DRAFT 2017 WEBSITE - SLING-6955</h1><div class="menu"> + <p> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/> + <a href="/ng/documentation/getting-started.html">Getting Started</a><br/> + <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/> + <a href="/ng/documentation/development.html">Development</a><br/> + <a href="/ng/documentation/bundles.html">Bundles</a><br/> + <a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/> + <a href="/ng/documentation/configuration.html">Configuration</a> + </p><p> + <a href="http://s.apache.org/sling.wiki";>Wiki</a><br/> + <a href="http://s.apache.org/sling.faq";>FAQ</a><br/> + + </p><p> + <strong>API Docs</strong><br/> + <a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/> + <a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/> + <a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/> + <a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/> + <a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/> + <a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/> + + </p><p> + <strong>Project info</strong><br/> + <a href="/ng/downloads.cgi">Downloads</a><br/> + <a href="http://www.apache.org/licenses/";>License</a><br/> + <a href="/ng/contributing.html">Contributing</a><br/> + <a href="/ng/news.html">News</a><br/> + <a href="/ng/links.html">Links</a><br/> + <a href="/ng/project-information.html">Project Information</a><br/> + <a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/> + <a href="/ng/project-information/security.html">Security</a><br/> + + </p><p> + <strong>Source</strong><br/> + <a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/> + <a href="git://git.apache.org/sling.git">Git</a><br/> + <a href="https://github.com/apache/sling";>Github Mirror</a><br/> + + </p><p> + <strong>Sponsorship</strong><br/> + <a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/> + <a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/> + <a href="https://donate.apache.org/";>Donate!</a><br/> + <a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/> + + </p><p> + <strong><a href="/ng/sitemap.html">Site Map</a></strong> + </p> + </div> <div class="main"> +<div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » <a href="/ng/documentation/bundles/sling-query.html">Sling Query</a> » </div> <h1> + Operators + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h3>Contains <code>[name*=value]</code></h3> +<p>Select resources that have property <code>name</code> containing <code>value</code>:</p> +<pre><code>// select children pages titled 'foo', 'foo bar', 'bar foo bar', 'foofoofoo', etc. +$(resources).children("cq:Page[jcr:content/jcr:title*=foo]") +</code></pre> +<h3>Contains a word <code>[name~=value]</code></h3> +<p>Select resources that have property <code>name</code> containing word <code>value</code> delimited with spaces:</p> +<pre><code>// select children pages titled 'foo', 'foo bar', 'bar foo bar', but not 'foofoofoo' +$(resources).children("cq:Page[jcr:content/jcr:title~=foo]") +</code></pre> +<h3>Ends with <code>[name$=value]</code></h3> +<p>Select resources that have property <code>name</code> ending with <code>value</code>:</p> +<pre><code>// select children pages titled 'foo', 'bar foo', etc. +$(resources).children("cq:Page[jcr:content/jcr:title$=foo]") +</code></pre> +<h3>Equals <code>[name=value]</code></h3> +<p>Select resources that have property <code>name</code> that equals to <code>value</code>:</p> +<pre><code>$(resources).children("cq:Page[jcr:content/jcr:title=foo]") +</code></pre> +<h3>Not equal <code>[name!=value]</code></h3> +<p>Select resources that have property <code>name</code> that not equals to <code>value</code>:</p> +<pre><code>$(resources).children("cq:Page[jcr:content/jcr:title!=foo]") +</code></pre> +<h3>Starts with <code>[name^=value]</code></h3> +<p>Select resources that have property <code>name</code> starting with <code>value</code>:</p> +<pre><code>// select children pages titled 'foo', 'foo bar', etc. +$(resources).children("cq:Page[jcr:content/jcr:title^=foo]") +</code></pre> +<h3>Has attribute <code>[name]</code></h3> +<p>Select resources that have property <code>name</code>:</p> +<pre><code>$(resources).find("[markerProperty]") +</code></pre></section></div></div> +<div class="footer"> + <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/f47e8676/documentation/bundles/sling-query/selectors.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/sling-query/selectors.html b/documentation/bundles/sling-query/selectors.html new file mode 100644 index 0000000..0516f0a --- /dev/null +++ b/documentation/bundles/sling-query/selectors.html @@ -0,0 +1,126 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";><html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> + <title>Apache Sling :: Selectors</title> + <link rel="icon" href="/ng/res/favicon.ico"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"/> + <script src='https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js'></script><script> + hljs.initHighlightingOnLoad(); + </script> + + </head> <body> +<div class="title"> + <div class="logo"> + <a href="http://sling.apache.org";> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> + </a> + </div><div class="header"> + <a href="http://www.apache.org";> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> + </a> + </div> + </div><h1 class="draft">DRAFT 2017 WEBSITE - SLING-6955</h1><div class="menu"> + <p> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/> + <a href="/ng/documentation/getting-started.html">Getting Started</a><br/> + <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/> + <a href="/ng/documentation/development.html">Development</a><br/> + <a href="/ng/documentation/bundles.html">Bundles</a><br/> + <a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/> + <a href="/ng/documentation/configuration.html">Configuration</a> + </p><p> + <a href="http://s.apache.org/sling.wiki";>Wiki</a><br/> + <a href="http://s.apache.org/sling.faq";>FAQ</a><br/> + + </p><p> + <strong>API Docs</strong><br/> + <a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/> + <a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/> + <a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/> + <a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/> + <a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/> + <a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/> + + </p><p> + <strong>Project info</strong><br/> + <a href="/ng/downloads.cgi">Downloads</a><br/> + <a href="http://www.apache.org/licenses/";>License</a><br/> + <a href="/ng/contributing.html">Contributing</a><br/> + <a href="/ng/news.html">News</a><br/> + <a href="/ng/links.html">Links</a><br/> + <a href="/ng/project-information.html">Project Information</a><br/> + <a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/> + <a href="/ng/project-information/security.html">Security</a><br/> + + </p><p> + <strong>Source</strong><br/> + <a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/> + <a href="git://git.apache.org/sling.git">Git</a><br/> + <a href="https://github.com/apache/sling";>Github Mirror</a><br/> + + </p><p> + <strong>Sponsorship</strong><br/> + <a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/> + <a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/> + <a href="https://donate.apache.org/";>Donate!</a><br/> + <a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/> + + </p><p> + <strong><a href="/ng/sitemap.html">Site Map</a></strong> + </p> + </div> <div class="main"> +<div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » <a href="/ng/documentation/bundles/sling-query.html">Sling Query</a> » </div> <h1> + Selectors + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>Selector string are something between filters and content descriptors. Selector can filter resources by their <a href="#resource-type">type</a>, <a href="#resource-name">name</a>, <a href="#attributes">attributes</a> and <a href="#modifiers">additional modifiers</a>. They can be also <a href="#joining-selectors">chained together</a> to describe more sophisticated hierarchy structure or <a href="#combining-selectors">combined with comma</a>.</p> +<h2><a href="#syntax" name="syntax">Syntax</a></h2> +<p>Selector consists of four parts:</p> +<h3><a href="#resource-type" name="resource-type">Resource type</a></h3> +<p>Resource type, which could be a <code>sling:resourceType</code>, like <code>foundation/components/richtext</code> or the underlying JCR node type, like <code>cq:Page</code> or <code>nt:unstructured</code>. In the latter case, SlingQuery takes types hierarchy into consideration (eg. <code>nt:base</code> matches everything). JCR mixin types could be used as well.</p> +<h3><a href="#resource-name" name="resource-name">Resource name</a></h3> +<p>Resource name can be defined with a hash <code>#</code> character, after the resource type (or instead of it):</p> +<pre><code>$(resource).children("cq:Page#some-name") +</code></pre> +<p>If the desired resource name contains colon (<code>:</code>) character, the whole string should be escaped with apostrophes:</p> +<pre><code>$(resource).children("#'jcr:content'[jcr:title=My title]") +</code></pre> +<h3><a href="#attributes" name="attributes">Attributes</a></h3> +<p>After the resource type and resource name one could pass a number of filtering attributes. Each attribute has following form: <code>[property=value]</code>. Passing multiple attributes will match only those resources that have all of them set. Property name could contain <code>/</code>. In this case property will be taken from the child resource, eg.:</p> +<pre><code>$(resource).children("cq:Page[jcr:content/jcr:title=My title]") +</code></pre> +<p>will return only children of type <code>cq:Page</code> that have sub-resource called <code>jcr:content</code> with property <code>jcr:title</code> set to <code>My title</code>. Besides the <code>=</code> you may use other operators like <code>*=</code>, which means <em>contains</em>:</p> +<pre><code>$(resource).children("cq:Page[jcr:content/jcr:title*=title]") +</code></pre> +<p>See the <a href="operators.html">fulll list of operators</a>.</p> +<h3><a href="#modifiers" name="modifiers">Modifiers</a></h3> +<p>At the end of the selector one could define any number of modifiers that will be used to filter out the resources matched by the resource type and attributes. Each modifier starts with colon, some of them accepts a parameter set in parentheses. Example:</p> +<pre><code>$(resource).children("cq:Page:first"); +$(resource).children("cq:Page:eq(0)"); // the same +$(resource).children(":first"); // modifier can be used alone +</code></pre> +<p>It is important that modifier filters out sub-collection created for each node, before it is merged. Eg.:, there is a difference between:</p> +<pre><code>$(resource1, resource2).children().first(); +</code></pre> +<p>and</p> +<pre><code>$(resource1, resource2).children(":first"); +</code></pre> +<p>In the first case we create a new collection consisting of children of the <code>resource1</code> and <code>resource2</code> and then we get the first element of the merged collection. On the other hand, the second example takes <em>first child</em> of each resource and creates a collection from them.</p> +<p>See the <a href="modifiers.html">full list of modifiers</a>.</p> +<h2><a href="#joining-selectors" name="joining-selectors">Joining selectors</a></h2> +<p>Selectors can be joined together using <a href="hierarchy-operators.html">hierarchy operators</a>. This feature enables the developer to create sophisticated filters describing desired resource structure, eg.:</p> +<pre><code>$(resource).children("cq:Page foundation/components/parsys > foundation/components/richtext") +</code></pre> +<p>will all <code>cq:Page</code>s containing paragraph systems with a richtext inside.</p> +<h2><a href="#combining-selectors" name="combining-selectors">Combining selectors</a></h2> +<p>You may specify any number of selectors to combine into a single result. Use comma to join a few conditions. Comma is treated as <code>OR</code> statement:</p> +<pre><code>$(resource).children("#en, #de, #fr"); // return all direct children named `en` or `de` or `fr`. +</code></pre></section></div></div> +<div class="footer"> + <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/f47e8676/documentation/bundles/sling-query/vs-jcr.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/sling-query/vs-jcr.html b/documentation/bundles/sling-query/vs-jcr.html new file mode 100644 index 0000000..b142210 --- /dev/null +++ b/documentation/bundles/sling-query/vs-jcr.html @@ -0,0 +1,123 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";><html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> + <title>Apache Sling :: Sling Query vs JCR</title> + <link rel="icon" href="/ng/res/favicon.ico"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"/> + <script src='https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js'></script><script> + hljs.initHighlightingOnLoad(); + </script> + + </head> <body> +<div class="title"> + <div class="logo"> + <a href="http://sling.apache.org";> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> + </a> + </div><div class="header"> + <a href="http://www.apache.org";> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> + </a> + </div> + </div><h1 class="draft">DRAFT 2017 WEBSITE - SLING-6955</h1><div class="menu"> + <p> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/> + <a href="/ng/documentation/getting-started.html">Getting Started</a><br/> + <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/> + <a href="/ng/documentation/development.html">Development</a><br/> + <a href="/ng/documentation/bundles.html">Bundles</a><br/> + <a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/> + <a href="/ng/documentation/configuration.html">Configuration</a> + </p><p> + <a href="http://s.apache.org/sling.wiki";>Wiki</a><br/> + <a href="http://s.apache.org/sling.faq";>FAQ</a><br/> + + </p><p> + <strong>API Docs</strong><br/> + <a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/> + <a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/> + <a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/> + <a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/> + <a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/> + <a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/> + + </p><p> + <strong>Project info</strong><br/> + <a href="/ng/downloads.cgi">Downloads</a><br/> + <a href="http://www.apache.org/licenses/";>License</a><br/> + <a href="/ng/contributing.html">Contributing</a><br/> + <a href="/ng/news.html">News</a><br/> + <a href="/ng/links.html">Links</a><br/> + <a href="/ng/project-information.html">Project Information</a><br/> + <a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/> + <a href="/ng/project-information/security.html">Security</a><br/> + + </p><p> + <strong>Source</strong><br/> + <a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/> + <a href="git://git.apache.org/sling.git">Git</a><br/> + <a href="https://github.com/apache/sling";>Github Mirror</a><br/> + + </p><p> + <strong>Sponsorship</strong><br/> + <a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/> + <a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/> + <a href="https://donate.apache.org/";>Donate!</a><br/> + <a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/> + + </p><p> + <strong><a href="/ng/sitemap.html">Site Map</a></strong> + </p> + </div> <div class="main"> +<div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » <a href="/ng/documentation/bundles/sling-query.html">Sling Query</a> » </div> <h1> + Sling Query vs JCR + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>Sling Query is not meant to replace JCR queries (XPath, JCR-SQL, JCR-SQL2). It doesn't use indexes and generally in queries traversing large subtrees (like <code>/</code> or <code>/content</code> or <code>/content/mysite/en</code>) it'll be much slower than well written JCR query.</p> +<p>Purpose of the SlingQuery is to provide a convenient way to traverse resource tree. All SlingQuery operations are eventually transformed into a series of <code>listChildren()</code> and <code>getParent()</code> operations [1].</p> +<p>As a rule of thumb - if you have a complex Java loop reading resource children or parents and processing them somehow, rewritting it to SlingQuery will be a good choice. If you have a recursive method trying to get some resource ancestor, using SlingQuery will be a good choice. On the other hand, if you have a large resource subtree and want to find all <code>cq:Page</code>s, using SlingQuery is a bad choice.</p> +<table> + <thead> + <tr> + <th>Description </th> + <th>JCR query </th> + <th>SlingQuery </th> + </tr> + </thead> + <tbody> + <tr> + <td>You have a complex logic using Sling Resource API </td> + <td>(-) </td> + <td>Yes! </td> + </tr> + <tr> + <td>You want to find resource ancestor </td> + <td>(-) </td> + <td>Yes! </td> + </tr> + <tr> + <td>You want to find all descendants with given attribute </td> + <td>Yes! </td> + <td>(-) </td> + </tr> + <tr> + <td>You want to find all descendants of given type </td> + <td>Yes! </td> + <td>(-) </td> + </tr> + <tr> + <td>You'd like to get ordered results </td> + <td>Yes! </td> + <td>(-) </td> + </tr> + </tbody> +</table> +<p>[1] - Actually, the <code>find()</code> operation uses QUERY strategy by default, which means that the selector string is transformed to a SQL2 query. However, the transformation process is very naïve and simply skips all conditions that can't be easily transformed to SQL2 (eg. selector <code>[jcr:content/jcr:title=some title]</code> won't be transformed as it contains some subresource reference). The result of this query is then filtere manually. See <a href="methods.html#searchstrategystrategy">searchStrategy</a> for more details.</p></section></div></div> +<div class="footer"> + <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/f47e8676/documentation/development/jsr-305.html ---------------------------------------------------------------------- diff --git a/documentation/development/jsr-305.html b/documentation/development/jsr-305.html index cd0bef5..3c40446 100644 --- a/documentation/development/jsr-305.html +++ b/documentation/development/jsr-305.html @@ -80,10 +80,11 @@ <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> + <li><code>javax.annotation.CheckForNull</code> (only on return values which may be <code>null</code>)</li> + <li><code>javax.annotation.Nonnull</code> (on return values and arguments which are never supposed to be <code>null</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>In case no annotations have been set on method arguments those accept <code>null</code> as a value. Return values should always be explicitly annotated, as from both cases checks can be derived.</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><a href="#use-with-eclipse" name="use-with-eclipse">Use With Eclipse</a></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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f47e8676/documentation/development/release-management.html ---------------------------------------------------------------------- diff --git a/documentation/development/release-management.html b/documentation/development/release-management.html index 348853c..40f7b96 100644 --- a/documentation/development/release-management.html +++ b/documentation/development/release-management.html @@ -124,6 +124,7 @@ </code></pre> <ul> <li>If you experience an error during deployment like a HTTP 401 check your settings for the required server entries as outlined in the <em>Prerequisites</em></li> + <li>Depending on the OS & the gpg version you have, you might hit https://issues.apache.org/jira/browse/MGPG-59, in which case you need, before maven command, to run <code>gpg --use-agent --armor --detach-sign --output $(mktemp) pom.xml</code></li> <li>Make sure the generated artifacts respect the Apache release <a href="http://www.apache.org/dev/release.html";>rules</a>: NOTICE and LICENSE files should be present in the META-INF directory within the jar. For -sources artifacts, be sure that your POM does not use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4</li> <li>You should verify the deployment under the <a href="https://repository.apache.org/content/groups/snapshots/org/apache/sling";>snapshot</a> repository on Apache</li> </ul> @@ -236,6 +237,7 @@ promote the artifacts to the central Maven repository. <li>Commit the released artifacts to <a href="https://dist.apache.org/repos/dist/release/sling/";>https://dist.apache.org/repos/dist/release/sling/</a> which is replicated to <a href="http://www.apache.org/dist/sling/";>http://www.apache.org/dist/sling/</a> quickly via svnpubsub. Hint: use svn import to avoid having to checkout the whole folder first. The easiest to do this is to get the released artifact using the check script (check_staged_release.sh) and then simply copy the artifacts from the downloaded folder to your local checkout folder. Make sure to not add the checksum files for the signature file *.asc.*). <ul> <li>Make sure to <em>not</em> change the end-of-line encoding of the .pom when uploaded via svn import! Eg when a windows style eol encoded file is uploaded with the setting '*.pom = svn:eol-style=native' this would later fail the signature checks!</li> + <li>Following the SVN commit you will receive an email from the 'Apache Reporter Service'. Follow the link and add the release data, as it used by the PMC chair to prepare board reports.</li> </ul> </li> <li>Delete the old release artifacts from that same dist.apache.org svn folder (the dist directory is archived)</li> @@ -256,6 +258,8 @@ promote the artifacts to the central Maven repository. <p>Also create a new version X.Y.Z+2, if that hasn't already been done.</p> <p>And keep the versions sorted, so when adding a new version moved it down to just above the previous versions.</p> <p>Close all issues associated with the released version.</p> +<h2><a href="#update-the-sling-launchpad" name="update-the-sling-launchpad">Update the Sling Launchpad</a></h2> +<p>If the bundle was already included in the Sling Launchpad or if it a new release that should be included add it with the release version in the provisioning model under <code>launchpad/builder/src/main/provisioning</code>.</p> <h2><a href="#create-an-announcement" name="create-an-announcement">Create an Announcement</a></h2> <p>We usually do such announcements only for "important" releases, as opposed to small individual module releases which are just announced on our <a href="/news.html">news</a> page.</p> <pre><code>To: "Sling Developers List" <d...@sling.apache.org>, "Apache Announcements" <annou...@apache.org> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f47e8676/documentation/the-sling-engine/architecture.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/architecture.html b/documentation/the-sling-engine/architecture.html index 9db3b37..7a0175a 100644 --- a/documentation/the-sling-engine/architecture.html +++ b/documentation/the-sling-engine/architecture.html @@ -83,7 +83,7 @@ </ul> <p>The following sections elaborate on each of these highlights.</p> <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> +<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="https://www.osgi.org/developer/benefits-of-using-osgi/";>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><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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f47e8676/documentation/the-sling-engine/service-authentication.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/service-authentication.html b/documentation/the-sling-engine/service-authentication.html index 81ba6ef..0de3fb2 100644 --- a/documentation/the-sling-engine/service-authentication.html +++ b/documentation/the-sling-engine/service-authentication.html @@ -116,9 +116,10 @@ service-id = service-name [ ":" subservice-name ] . <p>The implementation uses two fallbacks in case no mapping can be found for the given subServiceName</p> <ol> <li>Use user mapping for the serviceName only (not considering subServiceName)</li> - <li>Use default user (if one is configured).</li> + <li>Use default user (if one is configured in the OSGi configuration for PID <code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl</code>).</li> + <li>Use default mapping (if it is enabled in the OSGi configuration for PID <code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl</code>) which looks up a user with id <code>serviceuser--<bundleId>[--<subservice-name>]</code> (since Service User Mapper 1.3.0, <a href="https://issues.apache.org/jira/browse/SLING-6772";>SLING-6227</a>).</li> </ol> -<p>In addition a service named <code>ServiceUserMapped</code> is registered for each bundle and subservice name for which a service user mapping is configured (<a href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>). By explicitly defining a (static) reference towards <code>ServiceUserMapped</code> one can defer starting the service until that service user mapping is available.</p> +<p>In addition a service named <code>ServiceUserMapped</code> is registered for each bundle and subservice name for which a service user mapping is explicitly configured (<a href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>). By explicitly defining a (static) reference towards <code>ServiceUserMapped</code> one can defer starting the service until that service user mapping is available. Please note, that the two last default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work.</p> <h3><a href="#resourceresolverfactory" name="resourceresolverfactory">ResourceResolverFactory</a></h3> <p>The second part is support for service access to the Resource Tree. To this avail, the <code>ResourceResolverFactory</code> service is enhanced with a new factory method</p> <pre><code><!-- TODO syntax marker (#!java) disabled -->ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) @@ -135,10 +136,10 @@ service-id = service-name [ ":" subservice-name ] . <p>This method allows for access to the JCR Repository for services where the service bundle is the bundle actually using the <code>SlingRepository</code> service. The additional Subservice Name may be provided with the <code>subServiceName</code> parameter.</p> <h2><a href="#configuration" name="configuration">Configuration</a></h2> <h3><a href="#service-user-mappings" name="service-user-mappings">Service User Mappings</a></h3> -<p>For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user. This is configured through an OSGi configuration for the factory configuration with PID <code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended</code> <a href="https://issues.apache.org/jira/browse/SLING-3578";>SLING-3578</a>. There you can set one configuration property named <code>user.mapping</code> getting a String array as value where each entry must stick to the following format:</p> -<pre><code><service-name>[:<subservice-name>]=<authorizable id of a JCR system user>] +<p>For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user. This is configured through an OSGi configuration for the factory configuration with PID <code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended</code> (added in <a href="https://issues.apache.org/jira/browse/SLING-3578";>SLING-3578</a>). There you can set one configuration property named <code>user.mapping</code> getting a String array as value where each entry must stick to the following format:</p> +<pre><code><service-name>[:<subservice-name>]=<authorizable id of a JCR system user> </code></pre> -<p>The according user must exist at the point in time where <code>ResourceResolverFactory.getServiceResourceResolver(...)</code> or <code>SlingRepository.loginService(...)</code> is called. If you rely on one of those methods in your <code>activate</code> method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service <code>ServiceUserMapped</code> (<a href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>), optionally with a target filter on property <code>subServiceName</code> (in case such a subservice name is used). The service <code>ServiceUserMapped</code> does not expose any methods but is only a marker interface exclusively used to defer starting of other OSGi components. However this waits only for the mapping configuration to be available, it does not wait for the service user itself to be available.</p> +<p>The according user must exist at the point in time where <code>ResourceResolverFactory.getServiceResourceResolver(...)</code> or <code>SlingRepository.loginService(...)</code> is called. If you rely on one of those methods in your <code>activate</code> method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service <code>ServiceUserMapped</code> (see Section <code>ServiceUserMapper</code> above), optionally with a target filter on property <code>subServiceName</code> (in case such a subservice name is used). The service <code>ServiceUserMapped</code> does not expose any methods but is only a marker interface exclusively used to defer starting of other OSGi components. However this waits only for the mapping configuration to be available, it does not wait for the service user itself to be available.</p> <p>Example OSGi DS Component</p> <pre><code>:<!-- TODO syntax marker (::java) disabled -->@Component( reference = { @@ -151,7 +152,6 @@ service-id = service-name [ ":" subservice-name ] . class MyComponent { } </code></pre> -<p>There is a default mapping applied if no OSGi configuration is available for the mapping. The default is: "serviceuser--" + bundleId [ + "--" + subservice-name]. Please note, that these default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work.</p> <h2><a href="#deprecation-of-administrative-authentication" name="deprecation-of-administrative-authentication">Deprecation of administrative authentication</a></h2> <p>Originally the <code>ResourceResolverFactory.getAdministrativeResourceResolver</code> and <code>SlingRepository.loginAdministrative</code> methods have been defined to provide access to the resource tree and JCR Repository. These methods proved to be inappropriate because they allow for much too broad access.</p> <p>Consequently these methods are being deprecated and will be removed in future releases of the service implementations.</p> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f47e8676/documentation/tutorials-how-tos/46-line-blog.html ---------------------------------------------------------------------- diff --git a/documentation/tutorials-how-tos/46-line-blog.html b/documentation/tutorials-how-tos/46-line-blog.html index 0d2c9b9..f95c89c 100644 --- a/documentation/tutorials-how-tos/46-line-blog.html +++ b/documentation/tutorials-how-tos/46-line-blog.html @@ -78,9 +78,9 @@ <h2><a href="#audience" name="audience">Audience</a></h2> <p>Although this is a simple sample, it requires some custom settings to work. If you're just starting with Sling, <a href="/documentation/getting-started/discover-sling-in-15-minutes.html">Discover Sling in 15 minutes</a> might be a better choice.</p> <h2><a href="#step-0-start-configure-and-login-to-sling" name="step-0-start-configure-and-login-to-sling">Step 0: Start, configure and login to Sling</a></h2> -<p>See <a href="/documentation/development/getting-and-building-sling.html">Getting and Building Sling</a> for how to start Sling. Start it on port 8888 for the below links to work.</p> -<p>For this sample we need the optional <em>org.apache.sling.samples.path-based.rtp</em> bundle, if it's not present in the <a href="http://localhost:8888/system/console/bundles";>OSGi console</a>, install and start it. That bundle is not released yet so you might need to build it yourself, from its <a href="http://svn.apache.org/repos/asf/sling/trunk/samples/path-based-rtp";>source</a>. The bundle must then appear in the <a href="http://localhost:8888/system/console/bundles";>OSGI console's list of bundles</a>, with name = <em>org.apache.sling.samples.path-based.rtp</em> and status = <em>Active</em>.</p> -<p>Then, login using <a href="http://localhost:8888/?sling:authRequestLogin=1";>http://localhost:8888/?sling:authRequestLogin=1</a> which should prompt you for a username and password, use <em>admin</em> and <em>admin</em>. Once that's done, <a href="http://localhost:8888/index.html";>http://localhost:8888/index.html</a> should say <em>You are currently logged in as user <em>admin</em> to workspace <em>default</em></em>.</p> +<p>See <a href="/documentation/development/getting-and-building-sling.html">Getting and Building Sling</a> for how to start Sling. Start it on port 8080 for the below links to work.</p> +<p>For this sample we need the optional <em>org.apache.sling.samples.path-based.rtp</em> bundle, if it's not present in the <a href="http://localhost:8080/system/console/bundles";>OSGi console</a>, install and start it. That bundle is not released yet so you might need to build it yourself, from its <a href="http://svn.apache.org/repos/asf/sling/trunk/samples/path-based-rtp";>source</a>. The bundle must then appear in the <a href="http://localhost:8080/system/console/bundles";>OSGI console's list of bundles</a>, with name = <em>org.apache.sling.samples.path-based.rtp</em> and status = <em>Active</em>.</p> +<p>Then, login using <a href="http://localhost:8080/?sling:authRequestLogin=1";>http://localhost:8080/?sling:authRequestLogin=1</a> which should prompt you for a username and password, use <em>admin</em> and <em>admin</em>. Once that's done, <a href="http://localhost:8080/index.html";>http://localhost:8080/index.html</a> should say <em>You are currently logged in as user <em>admin</em> to workspace <em>default</em></em>.</p> <h2><a href="#step-1-creating-content" name="step-1-creating-content">Step 1: Creating content</a></h2> <p>The easiest way to create content in Sling is to use an HTTP POST request, let's use a simple HTML form:</p> <pre><code><html> @@ -109,15 +109,15 @@ </html> </code></pre> <p>That's two input fields, a submit button and a hidden field that tells Sling what to do after the POST (in this case: redirect to the html view of the node that was just created).</p> -<p>To test the form, start Sling and save the above script as {{/apps/blog/blog.esp}} [^esp] in the Sling repository - a WebDAV mount is the easiest way to do that. Browsing to <a href="http://localhost:8888/content/blog/*.html";>http://localhost:8888/content/blog/*.html</a> [^port] should display the above form.</p> -<p>[^esp]: ESP is Sling's server-side javascript language [^port]: This assumes your instance of Sling is running on port 8888. If that's not the case, adjust the example URLs accordingly.</p> +<p>To test the form, start Sling and save the above script as {{/apps/blog/blog.esp}} [^esp] in the Sling repository - a WebDAV mount is the easiest way to do that. Browsing to <a href="http://localhost:8080/content/blog/*.html";>http://localhost:8080/content/blog/*.html</a> [^port] should display the above form.</p> +<p>[^esp]: ESP is Sling's server-side javascript language [^port]: This assumes your instance of Sling is running on port 8080. If that's not the case, adjust the example URLs accordingly.</p> <p>Input some data (using "foo" for the title, for the sake of our examples below), save the form, and Sling should display the form again, using the URL of the node that was just created.</p> <div class="note"> If you get an error saying _javax.jcr.AccessDeniedException: ...not allowed to add or modify item_ it means that you are not logged in as user _admin_. See instructions above for logging in. </div> <p>At this point you're probably looking at an empty form with an URL ending in <em>foo</em>, if you used that for the title. Or <em>foo_0</em> or <em>foo_1</em> if other _foo_s already existed. Don't worry about not seeing your content, we'll fix that right away.</p> <h2><a href="#step-2-where-s-my-content-" name="step-2-where-s-my-content-">Step 2: Where's my content?</a></h2> -<p>To verify that our content has been created, we can have a look at the JSON data at <a href="http://localhost:8888/content/blog/foo.tidy.json";>http://localhost:8888/content/blog/foo.tidy.json</a>, which should display our new node's values:</p> +<p>To verify that our content has been created, we can have a look at the JSON data at <a href="http://localhost:8080/content/blog/foo.tidy.json";>http://localhost:8080/content/blog/foo.tidy.json</a>, which should display our new node's values:</p> <pre><code>{ "jcr:primaryType": "nt:unstructured", "text": "This is the foo text", @@ -134,7 +134,7 @@ If you get an error saying _javax.jcr.AccessDeniedException: ...not allowed to a <pre><code><!-- code of step 2 comes here --> <script>Sling.wizard();</script> </code></pre> -<p>Reloading the form at <code>http://localhost:8888/content/blog/*.html</code> and creating a new post should now redirect to an editable version of the post, with the form fields correctly initialized.</p> +<p>Reloading the form at <code>http://localhost:8080/content/blog/*.html</code> and creating a new post should now redirect to an editable version of the post, with the form fields correctly initialized.</p> <p>We can now create and edit posts; let's add some navigation, using more of the <em>sling.js</em> functionality. </p> <h2><a href="#step-3-navigation" name="step-3-navigation">Step 3: Navigation</a></h2> <p>The <em>sling.js</em> library provides utilities to access and manipulate content. For our blog, we'll use the <code>getContent(path)</code> method to list the siblings of the current node.</p>
