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
