Repository: sling-site Updated Branches: refs/heads/asf-site 0998f5f80 -> aa4955c75
SLING-7095 - restore missing sling models cache documentation Project: http://git-wip-us.apache.org/repos/asf/sling-site/repo Commit: http://git-wip-us.apache.org/repos/asf/sling-site/commit/aa4955c7 Tree: http://git-wip-us.apache.org/repos/asf/sling-site/tree/aa4955c7 Diff: http://git-wip-us.apache.org/repos/asf/sling-site/diff/aa4955c7 Branch: refs/heads/asf-site Commit: aa4955c75415ae56472704d7e475779d3e807735 Parents: 0998f5f Author: Justin Edelson <[email protected]> Authored: Sun Oct 1 08:36:49 2017 -0400 Committer: Justin Edelson <[email protected]> Committed: Sun Oct 1 08:36:49 2017 -0400 ---------------------------------------------------------------------- documentation/bundles/models.html | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/sling-site/blob/aa4955c7/documentation/bundles/models.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/models.html b/documentation/bundles/models.html index b823bbc..bd16738 100644 --- a/documentation/bundles/models.html +++ b/documentation/bundles/models.html @@ -626,6 +626,41 @@ public class MyModel implements MyService { </instructions> </configuration> </code></pre> +<h1><a href="#caching" name="caching">Caching</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> +<pre><code><!-- TODO syntax marker (::java) disabled -->// assume that resource is an instance of some subclass of AbstractResource +ModelClass object1 = resource.adaptTo(ModelClass.class); // creates new instance of ModelClass +ModelClass object2 = resource.adaptTo(ModelClass.class); // SlingAdaptable returns the cached instance +assert object1 == object2; +</code></pre> +<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> +<pre><code><!-- TODO syntax marker (::java) disabled -->// assume that request is some SlingHttpServletRequest object +ModelClass object1 = request.adaptTo(ModelClass.class); // creates new instance of ModelClass +ModelClass object2 = request.adaptTo(ModelClass.class); // creates another new instance of ModelClass +assert object1 != object2; +</code></pre> +<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> +<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptable = SlingHttpServletRequest.class, cache = true) +public class ModelClass {} + +... + +// assume that request is some SlingHttpServletRequest object +ModelClass object1 = request.adaptTo(ModelClass.class); // creates new instance of ModelClass +ModelClass object2 = request.adaptTo(ModelClass.class); // Sling Models returns the cached instance +assert object1 == object2; +</code></pre> +<p>When <code>cache = true</code> is specified, the adaptation result is cached regardless of how the adaptation is done:</p> +<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptable = SlingHttpServletRequest.class, cache = true) +public class ModelClass {} + +... + +// assume that request is some SlingHttpServletRequest object +ModelClass object1 = request.adaptTo(ModelClass.class); // creates new instance of ModelClass +ModelClass object2 = modelFactory.createModel(request, ModelClass.class); // Sling Models returns the cached instance +assert object1 == object2; +</code></pre> <h1><a href="#via-types-since-api-1-3-4-implementation-1-4-0-" name="via-types-since-api-1-3-4-implementation-1-4-0-">Via Types (Since API 1.3.4/Implementation 1.4.0)</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>
