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