svn commit: r1809734 - /sling/site/trunk/content/documentation/bundles/models.mdtext

[ju...@apache.org]

Author: justin
Date: Tue Sep 26 12:20:35 2017
New Revision: 1809734

URL: http://svn.apache.org/viewvc?rev=1809734&view=rev
Log:
SLING-7095 - Document Sling Models cache feature

Modified:
    sling/site/trunk/content/documentation/bundles/models.mdtext

Modified: sling/site/trunk/content/documentation/bundles/models.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/models.mdtext?rev=1809734&r1=1809733&r2=1809734&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/models.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/models.mdtext Tue Sep 26 12:20:35 2017
@@ -537,6 +537,52 @@ If you want to generate a bundle header
         </instructions>
     </configuration>
 
+# Caching
+
+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 `SlingAdaptable` base class. Most significantly, this is the case for many `Resource` adaptables as `AbstractResource` extends `SlingAdaptable`.  `SlingAdaptable` implements a caching mechanism such that multiple invocations of `adaptTo()` will return the same object. For example:
+
+    ::java
+    // 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;
+
+While this is true for `AbstractResource` subclasses, it is notably **not** the case for `SlingHttpServletRequest` as this class does not extend `SlingAdaptable`. So:
+
+    ::java
+    // 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;
+
+Since API version 1.3.4, Sling Models *can* cache an adaptation result, regardless of the adaptable by specifying `cache = true` on the `@Model` annotation.
+
+
+    ::java
+    @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;
+
+When `cache = true` is specified, the adaptation result is cached regardless of how the adaptation is done:
+
+    ::java
+    @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;
+
 # Via Types (Since API 1.3.4/Implementation 1.4.0)
 
 As discussed in the [Via](#via) section above, it is possible to select a different adaptable than the original value using the `@Via` annotation. The following standard types are provided (all types are in the package `org.apache.sling.models.annotations.via`)