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 2017/09/18 14:08:41 UTC
svn commit: r1018320 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/models.html
Author: buildbot
Date: Mon Sep 18 14:08:40 2017
New Revision: 1018320
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 Mon Sep 18 14:08:40 2017
@@ -1 +1 @@
-1808652
+1808719
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 Mon Sep 18 14:08:40 2017
@@ -149,6 +149,10 @@ h2:hover > .headerlink, h3:hover > .head
<li><a href="#associating-a-model-class-with-a-resource-type-since-130">Associating a Model Class with a Resource Type (since 1.3.0)</a></li>
<li><a href="#exporter-framework-since-130">Exporter Framework (since 1.3.0)</a></li>
<li><a href="#registration-of-sling-models-classes-via-bnd-plugin">Registration of Sling Models classes via bnd plugin</a></li>
+<li><a href="#via-types-since-api-134implementation-140">Via Types (Since API 1.3.4/Implementation 1.4.0)</a><ul>
+<li><a href="#custom-via-type">Custom Via Type</a></li>
+</ul>
+</li>
</ul>
</div>
<p>Many Sling projects want to be able to create model objects - POJOs which are automatically mapped from Sling objects, typically resources, but also request objects. Sometimes these POJOs need OSGi services as well.</p>
@@ -389,18 +393,34 @@ strategy by using adding <code>defaultIn
<p><code>@PostConstruct</code> methods in a super class will be invoked first.</p>
+<p>Since Sling Models Implementation 1.4.6, <code>@PostConstruct</code> methods may return a <code>false</code> boolean value in which case the model creation will fail without logging any exception
+(a message will be logged at the <code>DEBUG</code> level).</p>
<h2 id="via">Via<a class="headerlink" href="#via" title="Permanent link">¶</a></h2>
-<p>If the injection should be based on a JavaBean property of the adaptable, you can indicate this using the <code>@Via</code> annotation:</p>
+<p>In some cases, a different object should be used as the adaptable instead of the original adaptable. This can be done
+using the <code>@Via</code> annotation. By default, this can be done using a JavaBean property of the adaptable:</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>
- <span class="c1">// will return request.getResource().adaptTo(ValueMap.class).get("propertyName", String.class)</span>
+ <span class="c1">// will return request.getResource().getValueMap().get("propertyName", String.class)</span>
<span class="nd">@Inject</span> <span class="nd">@Via</span><span class="o">(</span><span class="s">"resource"</span><span class="o">)</span>
<span class="n">String</span> <span class="nf">getPropertyName</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
+<p>A different strategy can be used to define the adaptable by specifying a <code>type</code> attribute:</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>
+
+ <span class="c1">// will return resource.getChild("jcr:content").getValueMap().get("propertyName", String.class)</span>
+ <span class="nd">@Inject</span> <span class="nd">@Via</span><span class="o">(</span><span class="n">value</span> <span class="o">=</span> <span class="s">"jcr:content"</span><span class="o">,</span> <span class="n">type</span> <span class="o">=</span> <span class="n">ChildResource</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+ <span class="n">String</span> <span class="nf">getPropertyName</span><span class="o">();</span>
+
+<span class="o">}</span>
+</pre></div>
+
+
+<p>See the <a href="#via-types">Via Types</a> section below for details on the included types for <code>@Via</code>.</p>
<h2 id="source">Source<a class="headerlink" href="#source" title="Permanent link">¶</a></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>
@@ -507,7 +527,7 @@ strategy by using adding <code>defaultIn
<dt><code>@PostConstruct</code></dt>
<dd>methods to call upon model option creation (only for model classes)</dd>
<dt><code>@Via</code></dt>
-<dd>use a JavaBean property of the adaptable as the source of the injection</dd>
+<dd>change the adaptable as the source of the injection</dd>
<dt><code>@Default</code></dt>
<dd>set default values for a field or method</dd>
<dt><code>@Path</code></dt>
@@ -793,8 +813,49 @@ model, exported as a <code>java.lang.Str
<span class="nt"></configuration></span>
</pre></div>
</td></tr></table>
+
+<h1 id="via-types-since-api-134implementation-140">Via Types (Since API 1.3.4/Implementation 1.4.0)<a class="headerlink" href="#via-types-since-api-134implementation-140" title="Permanent link">¶</a></h1>
+<p>As discussed in the <a href="#via">Via</a> section above, it is possible to select a different adaptable than the original value using the <code>@Via</code> annotation. The following standard types are provided (all types are in the package <code>org.apache.sling.models.annotations.via</code>)</p>
+<table class="table">
+<thead>
+<tr>
+<th><code>@Via</code> type value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>BeanProperty</code> (default)</td>
+<td>Uses a JavaBean property from the adaptable.</td>
+</tr>
+<tr>
+<td><code>ChildResource</code></td>
+<td>Uses a child resource from the adaptable, assuming the adaptable is a <code>Resource</code>.</td>
+</tr>
+<tr>
+<td><code>ForcedResourceType</code></td>
+<td>Creates a wrapped resource with the provided resource type. If the adaptable is a <code>SlingHttpServletRequest</code>, a wrapped request is created as well to contain the wrapped resource.</td>
+</tr>
+<tr>
+<td><code>ResourceSuperType</code></td>
+<td>Creates a wrapped resource with the resource type set to the adaptable's resource super type. If the adaptable is a <code>SlingHttpServletRequest</code>, a wrapped request is created as well to contain the wrapped resource.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="custom-via-type">Custom Via Type<a class="headerlink" href="#custom-via-type" title="Permanent link">¶</a></h2>
+<p>Defining your own type for the <code>@Via</code> annotation is a two step process. The first step is to create a marker class implementing the <code>@ViaProviderType</code> annotation. This class can be entirely empty, e.g.</p>
+<div class="codehilite"><pre><span class="p">:</span><span class="n">java</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">MyCustomProviderType</span> <span class="n">implements</span> <span class="n">ViaProviderType</span> <span class="p">{}</span>
+</pre></div>
+
+
+<p>The second step is to create an OSGi service implementing the <code>ViaProvider</code> interface. This interface defines two methods:</p>
+<ul>
+<li><code>getType()</code> should return the marker class. </li>
+<li><code>getAdaptable()</code> should return the new adaptable or <code>ViaProvider.ORIGINAL</code> to indicate that the original adaptable should be used.</li>
+</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1788420 by kwin on Fri, 24 Mar 2017 12:05:59 +0000
+ Rev. 1808719 by justin on Mon, 18 Sep 2017 14:08:16 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project