You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by ju...@apache.org on 2017/10/01 12:33:28 UTC
sling-site git commit: SLING-7095 - restore lost cache documenation
Repository: sling-site
Updated Branches:
refs/heads/master b636fda1e -> fd837603e
SLING-7095 - restore lost cache documenation
Project: http://git-wip-us.apache.org/repos/asf/sling-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/sling-site/commit/fd837603
Tree: http://git-wip-us.apache.org/repos/asf/sling-site/tree/fd837603
Diff: http://git-wip-us.apache.org/repos/asf/sling-site/diff/fd837603
Branch: refs/heads/master
Commit: fd837603ef94ba4d4fc2689049f0516d054b37c6
Parents: b636fda
Author: Justin Edelson <ju...@apache.org>
Authored: Sun Oct 1 08:33:05 2017 -0400
Committer: Justin Edelson <ju...@apache.org>
Committed: Sun Oct 1 08:33:05 2017 -0400
----------------------------------------------------------------------
.../content/documentation/bundles/models.md | 46 ++++++++++++++++++++
1 file changed, 46 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/sling-site/blob/fd837603/src/main/jbake/content/documentation/bundles/models.md
----------------------------------------------------------------------
diff --git a/src/main/jbake/content/documentation/bundles/models.md b/src/main/jbake/content/documentation/bundles/models.md
index efd6efa..35dace2 100644
--- a/src/main/jbake/content/documentation/bundles/models.md
+++ b/src/main/jbake/content/documentation/bundles/models.md
@@ -543,6 +543,52 @@ If you want to generate a bundle header compliant with Sling Models < 1.3.4 (i.e
</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`)