Author: buildbot Date: Tue Sep 26 12:21:02 2017 New Revision: 1018730 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 Tue Sep 26 12:21:02 2017 @@ -1 +1 @@ -1809602 +1809734 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 Tue Sep 26 12:21:02 2017 @@ -149,6 +149,7 @@ 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="#caching">Caching</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> @@ -814,6 +815,50 @@ model, exported as a <code>java.lang.Str </pre></div> </td></tr></table> +<h1 id="caching">Caching<a class="headerlink" href="#caching" title="Permanent link">¶</a></h1> +<p>By default, Sling Models do not do any caching of the adaptation result and every request for a model class will +result in a new instance of the model class. However, there are two notable cases when the adaptation result can be cached. The first case is when the adaptable extends the <code>SlingAdaptable</code> base class. Most significantly, this is the case for many <code>Resource</code> adaptables as <code>AbstractResource</code> extends <code>SlingAdaptable</code>. <code>SlingAdaptable</code> implements a caching mechanism such that multiple invocations of <code>adaptTo()</code> will return the same object. For example:</p> +<div class="codehilite"><pre><span class="c1">// assume that resource is an instance of some subclass of AbstractResource</span> +<span class="n">ModelClass</span> <span class="n">object1</span> <span class="o">=</span> <span class="n">resource</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// creates new instance of ModelClass</span> +<span class="n">ModelClass</span> <span class="n">object2</span> <span class="o">=</span> <span class="n">resource</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// SlingAdaptable returns the cached instance</span> +<span class="k">assert</span> <span class="n">object1</span> <span class="o">==</span> <span class="n">object2</span><span class="o">;</span> +</pre></div> + + +<p>While this is true for <code>AbstractResource</code> subclasses, it is notably <strong>not</strong> the case for <code>SlingHttpServletRequest</code> as this class does not extend <code>SlingAdaptable</code>. So:</p> +<div class="codehilite"><pre><span class="c1">// assume that request is some SlingHttpServletRequest object</span> +<span class="n">ModelClass</span> <span class="n">object1</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// creates new instance of ModelClass</span> +<span class="n">ModelClass</span> <span class="n">object2</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// creates another new instance of ModelClass</span> +<span class="k">assert</span> <span class="n">object1</span> <span class="o">!=</span> <span class="n">object2</span><span class="o">;</span> +</pre></div> + + +<p>Since API version 1.3.4, Sling Models <em>can</em> cache an adaptation result, regardless of the adaptable by specifying <code>cache = true</code> on the <code>@Model</code> annotation.</p> +<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptable</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="n">cache</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ModelClass</span> <span class="o">{}</span> + +<span class="o">...</span> + +<span class="c1">// assume that request is some SlingHttpServletRequest object</span> +<span class="n">ModelClass</span> <span class="n">object1</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// creates new instance of ModelClass</span> +<span class="n">ModelClass</span> <span class="n">object2</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// Sling Models returns the cached instance</span> +<span class="k">assert</span> <span class="n">object1</span> <span class="o">==</span> <span class="n">object2</span><span class="o">;</span> +</pre></div> + + +<p>When <code>cache = true</code> is specified, the adaptation result is cached regardless of how the adaptation is done:</p> +<div class="codehilite"><pre><span class="nd">@Model</span><span class="o">(</span><span class="n">adaptable</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="n">cache</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ModelClass</span> <span class="o">{}</span> + +<span class="o">...</span> + +<span class="c1">// assume that request is some SlingHttpServletRequest object</span> +<span class="n">ModelClass</span> <span class="n">object1</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// creates new instance of ModelClass</span> +<span class="n">ModelClass</span> <span class="n">object2</span> <span class="o">=</span> <span class="n">modelFactory</span><span class="o">.</span><span class="na">createModel</span><span class="o">(</span><span class="n">request</span><span class="o">,</span> <span class="n">ModelClass</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> <span class="c1">// Sling Models returns the cached instance</span> +<span class="k">assert</span> <span class="n">object1</span> <span class="o">==</span> <span class="n">object2</span><span class="o">;</span> +</pre></div> + + <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"> @@ -854,7 +899,7 @@ model, exported as a <code>java.lang.Str <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. 1808721 by justin on Mon, 18 Sep 2017 14:15:00 +0000 + Rev. 1809734 by justin on Tue, 26 Sep 2017 12:20:35 +0000 </div> <div class="trademarkFooter"> Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project