You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2014/11/13 17:07:01 UTC
svn commit: r929075 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/models.html
Author: buildbot
Date: Thu Nov 13 16:07:01 2014
New Revision: 929075
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles/models.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Nov 13 16:07:01 2014
@@ -1 +1 @@
-1639357
+1639376
Modified: websites/staging/sling/trunk/content/documentation/bundles/models.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/models.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/models.html Thu Nov 13 16:07:01 2014
@@ -95,7 +95,18 @@
<li><a href="#design-goals">Design Goals</a></li>
<li><a href="#basic-usage">Basic Usage</a></li>
<li><a href="#client-code">Client Code</a></li>
-<li><a href="#other-options">Other Options</a></li>
+<li><a href="#other-options">Other Options</a><ul>
+<li><a href="#names">Names</a></li>
+<li><a href="#optional-and-required">Optional and Required</a></li>
+<li><a href="#defaults">Defaults</a></li>
+<li><a href="#collections">Collections</a></li>
+<li><a href="#osgi-service-filters">OSGi Service Filters</a></li>
+<li><a href="#postconstruct-methods">PostConstruct Methods</a></li>
+<li><a href="#via">Via</a></li>
+<li><a href="#source">Source</a></li>
+<li><a href="#adaptations">Adaptations</a></li>
+</ul>
+</li>
<li><a href="#custom-injectors">Custom Injectors</a></li>
<li><a href="#annotation-reference">Annotation Reference</a></li>
<li><a href="#available-injectors">Available Injectors</a></li>
@@ -188,6 +199,7 @@ can be listed in a comma-separated list
<p>As with other AdapterFactories, if the adaptation can't be made for any reason, <code>adaptTo()</code> returns null.</p>
<h1 id="other-options">Other Options</h1>
+<h2 id="names">Names</h2>
<p>If the field or method name doesn't exactly match the property name, <code>@Named</code> can be used:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">Resource</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -198,6 +210,7 @@ can be listed in a comma-separated list
</pre></div>
+<h2 id="optional-and-required">Optional and Required</h2>
<p><code>@Inject</code>ed fields/methods are assumed to be required. To mark them as optional, use <code>@Optional</code>:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">Resource</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -219,6 +232,10 @@ strategy by using adding <code>defaultIn
</pre></div>
+<p>To still mark some fields/methods as being mandatory while relying on <code>defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL</code> for all other fields, the annotation <code>@Required</code> can be used.</p>
+<p><code>@Optional</code> annotations are only evaluated when using the <code>defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED</code> (which is the default), <code>@Required</code> annotations only if using <code>defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL</code>.</p>
+<p><em>The <code>defaultInjectionStrategy</code> is currently not considered for fields/methods annotated with Injector-specific annotations (see also <a href="https://issues.apache.org/jira/browse/SLING-4155">SLING-4155</a>)</em></p>
+<h2 id="defaults">Defaults</h2>
<p>A default value can be provided (for Strings & primitives):</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">Resource</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -250,6 +267,7 @@ strategy by using adding <code>defaultIn
<p>In this case, the name is not used -- only the class name.</p>
+<h2 id="collections">Collections</h2>
<p>Lists and arrays are supported:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">Resource</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -282,6 +300,7 @@ strategy by using adding <code>defaultIn
<p>In this case, the <code>addresses</code> <code>List</code> will contain <code>address1</code> and <code>address2</code>.</p>
+<h2 id="osgi-service-filters">OSGi Service Filters</h2>
<p>OSGi injection can be filtered:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">SlingHttpServletRequest</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -300,6 +319,7 @@ strategy by using adding <code>defaultIn
</pre></div>
+<h2 id="postconstruct-methods">PostConstruct Methods</h2>
<p>The <code>@PostConstruct</code> annotation can be used to add methods which are invoked upon completion of all injections:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">SlingHttpServletRequest</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -320,6 +340,7 @@ strategy by using adding <code>defaultIn
<p><code>@PostConstruct</code> methods in a super class will be invoked first.</p>
+<h2 id="via">Via</h2>
<p>If the injection should be based on a JavaBean property of the adaptable, you can indicate this using the <code>@Via</code> annotation:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">SlingHttpServletRequest</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -331,6 +352,7 @@ strategy by using adding <code>defaultIn
</pre></div>
+<h2 id="source">Source</h2>
<p>If there is ambiguity where a given injection could be handled by more than one injector, the <code>@Source</code> annotation can be used to define which injector is responsible:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">SlingHttpServletRequest</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -342,6 +364,7 @@ strategy by using adding <code>defaultIn
</pre></div>
+<h2 id="adaptations">Adaptations</h2>
<p>If the injected object does not match the desired type and the object implements the <code>Adaptable</code> interface, Sling Models will try to adapt it. This provides the ability to create rich object graphs. For example:</p>
<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptables</span><span class="o">=</span><span class="n">Resource</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">MyModel</span> <span class="o">{</span>
@@ -569,7 +592,7 @@ the following advantages over using the
</tbody>
</table>
<h2 id="hints">Hints</h2>
-<p>Those annotations replace <code>@Via</code>, <code>@Filter</code>, <code>@Named</code>, <code>@Optional</code>, <code>@Source</code> and <code>@Inject</code>.
+<p>Those annotations replace <code>@Via</code>, <code>@Filter</code>, <code>@Named</code>, <code>@Optional</code>, <code>@Required</code>, <code>@Source</code> and <code>@Inject</code>.
<code>@Default</code> may still be used in addition to the injector-specific annotation to set default values. All elements given above are optional.</p>
<h2 id="custom-annotations">Custom Annotations</h2>
<p>To create a custom annotation, implement the <code>org.apache.sling.models.spi.injectorspecific.InjectAnnotationProcessorFactory</code> interface.
@@ -597,7 +620,7 @@ SPI interface which could use context to
content path context. If multiple implementations of the <code>ImplementationPicker</code> interface are present, they are queried
one after another in order of their service ranking property, the first one that picks an implementation wins.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1623986 by sseifert on Wed, 10 Sep 2014 12:50:19 +0000
+ Rev. 1639376 by kwin on Thu, 13 Nov 2014 16:06:53 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project