svn commit: r1018730 - in /websites/staging/sling/trunk/content: ./ documentation/bundles/models.html

[bu...@apache.org]

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">&para;</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">&para;</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