You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by GitBox <gi...@apache.org> on 2022/12/21 08:44:52 UTC

[GitHub] [sling-site] stefanseifert opened a new pull request, #106: SLING-11711 rework of the Sling Model documentation, part 1

stefanseifert opened a new pull request, #106:
URL: https://github.com/apache/sling-site/pull/106

   PR to comment on the changes by @joerghoh 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1059653312


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   Can you suggest an sentence? I feel a bit out of my comfort-zone here, especially when it comes to the ```@via``` annotation and it's replacement in the injector-specific annotations.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1060403681


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   @kwin: I want to give clear guidelines what to use; and recommending to always use SlingHttpServletRequest sounds incorrect, because then you cannot use it outside of a request, limiting the flexibility.
   
   
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1062398340


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -179,92 +150,121 @@ Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi
         // See the javadoc of the ModelFactory for which Exception can be expected here
     }
 
-In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.
+In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable. 
 
 ## Usage in HTL
-[Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1) (internally uses the `ModelFactory` from above).
+Please see [Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1); internally it uses the `ModelFactory` from above.
 
-# Other Options
-## Names
-If the field or method name doesn't exactly match the property name, `@Named` can be used:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Named("secondPropertyName")
-	    private String otherName;
-	} 
- 
+# Available injectors
+
+In the above cases just the `@ValueMapValue` annotation was used, but there other available injectors. For each injector there is a specialized annotation available. For the optional parameters see the next section.
+
+
+Injector Name  | Annotation          | Supported Optional Elements    | Description   | Array Support   | Parametrized Type Support

Review Comment:
   I added more rows to the table and included the name and the column "Applicable to".



##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -660,86 +612,78 @@ 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;
+# Discouraged annotations
 
-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.
+In earlier versions of Sling Models the use of the annotation `@Inject` was suggested and documented; but over time it turned out that it had 2 major issues:
 
+* This injection iterated through all available injectors and injected the first non-null value provided by an injector. This lead to unpredictable behavior, although the order is well-defined. The addition of the `@Source` annotation did not really help.
+* This iteration turned out to the performance bottleneck, especially if (optional) injections were not succesful, and then all other injectors have to be tried.

Review Comment:
   +1



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1062397705


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   I rewrote this part here.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] stefanseifert commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
stefanseifert commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1054120663


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -179,86 +144,141 @@ Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi
         // See the javadoc of the ModelFactory for which Exception can be expected here
     }
 
-In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.
+In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable. 
 
 ## Usage in HTL
-[Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1) (internally uses the `ModelFactory` from above).
+Please see [Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1); internally it uses the `ModelFactory` from above.
 
-# Other Options
-## Names
-If the field or method name doesn't exactly match the property name, `@Named` can be used:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Named("secondPropertyName")
-	    private String otherName;
-	} 
- 
+# Available injectors
+
+In the above cases just the `@ValueMapValue` annotation was used, but there other available injectors. For each injector there is a specialized annotation available. For the optional parameters see the next section.
+
+Injector Name  | Annotation          | Supported Optional Elements    | Description   | Array Support   | Parametrized Type Support
+----- | -----------------   | ------------------------------ |------------------------- | --------------- | ---------------------------
+Scripting Bindings|`@ScriptVariable`   | `injectionStrategy` and `name`          | Injects the script variable defined via [Sling Bindings](https://cwiki.apache.org/confluence/display/SLING/Scripting+variables). If `name` is not set the name is derived from the method/field name.  | no conversion is done |  If a parameterized type is passed, the bindings value must be of a compatible type of the parameterized type.
+ValueMap | `@ValueMapValue`    | `injectionStrategy`, `name` and `via`   | Injects a `ValueMap` value. If `via` is not set, it will automatically take `resource` if the adaptable is the `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name. | Primitive arrays wrapped/unwrapped as necessary. Wrapper object arrays are unwrapped/wrapped as necessary. | Parameterized `List` and `Collection` injection points are injected by getting an array of the component type and creating an unmodifiable `List` from the array.
+Child Resource | `@ChildResource`    | `injectionStrategy`, `name` and `via`   | Injects a child resource by name. If `via` is not set, it will automatically take `resource` if the adaptable is the `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name. | none  | if a parameterized type `List` or `Collection` is passed, a `List<Resource>` is returned (the contents of which may be adapted to the target type) filled with all child resources of the resource looked up by the given name.
+Request Attribute | `@RequestAttribute` | `injectionStrategy`, `name` and `via`   | Injects a request attribute by name. If `name` is not set the name is derived from the method/field name. | no conversion is done | If a parameterized type is passed, the request attribute must be of a compatible type of the parameterized type.
+Resource path | `@ResourcePath`     | `injectionStrategy`, `path`, and `name` |Injects a resource either by path or by reading a property with the given name. | yes | none
+OSGi service | `@OSGiService`      | `injectionStrategy`, `filter`           | Injects an OSGi service by type (and the optional filter) | yes | Parameterized `List` and `Collection` injection points are injected by getting an array of the services and creating an unmodifiable `List` from the array.
+Context-Aware Configuration | `@ContextAwareConfiguration` | `injectionStrategy`, `name`    |  Lookup context-aware configuration. See [Context-Aware Configuration](#context-aware-configuration) below. | yes | If a parameterized type `List` or `Collection` is used, a configuration collection is looked up.
+Self | `@Self`             | `injectionStrategy`                     |  Injects the adaptable itself. If the field type does not match with the adaptable it is tried to adapt the adaptable to the requested type. | none | none
+Sling Object | `@SlingObject`      | `injectionStrategy`                     | Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper | none | none
+
+# Parameters to the Injectors
+
+Injectors can support optional parameters as listed in the above table
+
 ## Optional and Required
-`@Inject`ed fields/methods are assumed to be required. To mark them as optional, use `@Optional`:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Optional
-	    private String otherName;
-	}
+Injected fields/methods are assumed to be required. To mark them as optional, there are 2 options:
 
-If a majority of `@Inject`ed fields/methods are optional, it is possible (since Sling Models API 1.0.2/Impl 1.0.6) to change the default injection
-strategy by using adding `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` to the `@Model` annotation:
+* add the parameter `injectionStrategy=InjectionStrategy.OPTIONAL` to the annotation
+* or wrap the type into an `Optional`
+
+It is recommended to use the approach using the `Optional` type, because then this "optionality" is also expressed in the type system.
+
+    ::java
+    import java.util.Optional;
+
+    @Model(adaptables=Resource.class)
+    public class MyModel {
+
+	    @ValueMapValue(injectionStrategy=InjectionStrategy.OPTIONAL)
+	    private String optionalProperty;
+
+        @ValueMapValue
+        private Optional<String> anotherOptionalProperty;
+    }
+Please note, that also injections marked as optional are always tried. It is just that any failure to inject a value does not lead to the termination of the creation of the SlingModel, but instead it continues, leaving the field value/return value at the default value of the used type.
+
+If a majority of injected fields/methods are optional, it is possible (since Sling Models API 1.0.2/Impl 1.0.6) to change the default injection strategy by using adding `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` to the `@Model` annotation:
 
 	::java
 	@Model(adaptables=Resource.class, defaultInjectionStrategy=DefaultInjectionStrategy.OPTIONAL)
 	public class MyModel {
 
-	    @Inject
-	    private String otherName;
+        @ValueMapValue
+        private String optionalProperty;
 	}
 
-To still mark some fields/methods as being mandatory while relying on `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` for all other fields, the annotation `@Required` can be used.
+To still mark some fields/methods as being mandatory while relying on `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` for all other fields, the parameter `injectionStrategy=InjectionStrategy.REQUIRED` can be used.
 
-`@Optional` annotations are only evaluated when using the `defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED` (which is the default), `@Required` annotations only if using `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL`.
+`defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` parameters are only evaluated when using the `defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED` (which is the default), `injectionStrategy=InjectionStrategy.REQUIRED` parameters only if using `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL`.
 
-## Defaults
-A default value can be provided (for Strings & primitives):
+## Via 
+In some cases, a different object should be used as the adaptable instead of the original adaptable. This can be done
+using the `via` parameter. By default, this can be done using a JavaBean property of the adaptable:
 
 	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
+	@Model(adaptables=SlingHttpServletRequest.class)
+	public interface MyModel {
 	 
-	    @Inject @Default(values="defaultValue")
-	    private String name;
-	}
+	    // will return request.getResource().getValueMap().get("propertyName", String.class)
+	    @ValueMapValue(via="resource")
+	    String getPropertyName();
+	} 
 
-Defaults can also be arrays:
+
+A different strategy can be used to define the adaptable by specifying a `type` attribute:
+
+    ::java
+    @Model(adaptables=Resource.class)
+    public interface MyModel {
+
+		// will return resource.getChild("jcr:content").getValueMap().get("propertyName", String.class)
+        @Inject @Via(value = "jcr:content", type = ChildResource.class)
+        String getPropertyName();
+
+    }
+
+See the [Via Types](#via-types-since-api-134implementation-140) section below for details on the included types for `@Via`.
+
+
+## Names
+If the field or method name doesn't exactly match the property name, the parameter `name` can be used:
 
 	::java
 	@Model(adaptables=Resource.class)
 	public class MyModel {
 	 
-	    @Inject @Default(intValues={1,2,3,4})
-	    private int[] integers;
-	}
+	    @ValueMapValue(name="secondPropertyName")
+	    private String otherName;
+	} 
+
+In this case the value of the property named `secondPropertyName` would be taken from the ValueMap.
+
 
+## Path
+The `@ResourcePath` injector supports the parameter `path` to inject a resource with the given parameter:   
 
-OSGi services can be injected:
+    ::java
+    @Model(adaptables=Resource.class) {
+
+        @ResourcePath(path="/libs")
+        Resource libs;
+    }
+
+## OSGi Service Filters
+OSGi injection can be filtered:
 
 	::java
-	@Model(adaptables=Resource.class)
+	@Model(adaptables=SlingHttpServletRequest.class)
 	public class MyModel {
 	 
-	    @Inject
-	    private ResourceResolverFactory resourceResolverFactory;
-	} 
-
- 
-In this case, the name is not used -- only the class name.
+	    @OSGiInjector

Review Comment:
   correct: @OSGiService



##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -274,7 +294,7 @@ List injection for *child resources* works by injecting grand child resources (s
 	@Model(adaptables=Resource.class)
 	public class MyModel {
 
-	    @Inject
+	    @@ChildResource

Review Comment:
   correct: @ChildResource



##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -179,86 +144,141 @@ Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi
         // See the javadoc of the ModelFactory for which Exception can be expected here
     }
 
-In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.
+In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable. 
 
 ## Usage in HTL
-[Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1) (internally uses the `ModelFactory` from above).
+Please see [Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1); internally it uses the `ModelFactory` from above.
 
-# Other Options
-## Names
-If the field or method name doesn't exactly match the property name, `@Named` can be used:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Named("secondPropertyName")
-	    private String otherName;
-	} 
- 
+# Available injectors
+
+In the above cases just the `@ValueMapValue` annotation was used, but there other available injectors. For each injector there is a specialized annotation available. For the optional parameters see the next section.
+
+Injector Name  | Annotation          | Supported Optional Elements    | Description   | Array Support   | Parametrized Type Support
+----- | -----------------   | ------------------------------ |------------------------- | --------------- | ---------------------------
+Scripting Bindings|`@ScriptVariable`   | `injectionStrategy` and `name`          | Injects the script variable defined via [Sling Bindings](https://cwiki.apache.org/confluence/display/SLING/Scripting+variables). If `name` is not set the name is derived from the method/field name.  | no conversion is done |  If a parameterized type is passed, the bindings value must be of a compatible type of the parameterized type.
+ValueMap | `@ValueMapValue`    | `injectionStrategy`, `name` and `via`   | Injects a `ValueMap` value. If `via` is not set, it will automatically take `resource` if the adaptable is the `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name. | Primitive arrays wrapped/unwrapped as necessary. Wrapper object arrays are unwrapped/wrapped as necessary. | Parameterized `List` and `Collection` injection points are injected by getting an array of the component type and creating an unmodifiable `List` from the array.
+Child Resource | `@ChildResource`    | `injectionStrategy`, `name` and `via`   | Injects a child resource by name. If `via` is not set, it will automatically take `resource` if the adaptable is the `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name. | none  | if a parameterized type `List` or `Collection` is passed, a `List<Resource>` is returned (the contents of which may be adapted to the target type) filled with all child resources of the resource looked up by the given name.
+Request Attribute | `@RequestAttribute` | `injectionStrategy`, `name` and `via`   | Injects a request attribute by name. If `name` is not set the name is derived from the method/field name. | no conversion is done | If a parameterized type is passed, the request attribute must be of a compatible type of the parameterized type.
+Resource path | `@ResourcePath`     | `injectionStrategy`, `path`, and `name` |Injects a resource either by path or by reading a property with the given name. | yes | none
+OSGi service | `@OSGiService`      | `injectionStrategy`, `filter`           | Injects an OSGi service by type (and the optional filter) | yes | Parameterized `List` and `Collection` injection points are injected by getting an array of the services and creating an unmodifiable `List` from the array.
+Context-Aware Configuration | `@ContextAwareConfiguration` | `injectionStrategy`, `name`    |  Lookup context-aware configuration. See [Context-Aware Configuration](#context-aware-configuration) below. | yes | If a parameterized type `List` or `Collection` is used, a configuration collection is looked up.
+Self | `@Self`             | `injectionStrategy`                     |  Injects the adaptable itself. If the field type does not match with the adaptable it is tried to adapt the adaptable to the requested type. | none | none
+Sling Object | `@SlingObject`      | `injectionStrategy`                     | Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper | none | none
+
+# Parameters to the Injectors
+
+Injectors can support optional parameters as listed in the above table
+
 ## Optional and Required
-`@Inject`ed fields/methods are assumed to be required. To mark them as optional, use `@Optional`:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Optional
-	    private String otherName;
-	}
+Injected fields/methods are assumed to be required. To mark them as optional, there are 2 options:
 
-If a majority of `@Inject`ed fields/methods are optional, it is possible (since Sling Models API 1.0.2/Impl 1.0.6) to change the default injection
-strategy by using adding `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` to the `@Model` annotation:
+* add the parameter `injectionStrategy=InjectionStrategy.OPTIONAL` to the annotation
+* or wrap the type into an `Optional`
+
+It is recommended to use the approach using the `Optional` type, because then this "optionality" is also expressed in the type system.
+
+    ::java
+    import java.util.Optional;
+
+    @Model(adaptables=Resource.class)
+    public class MyModel {
+
+	    @ValueMapValue(injectionStrategy=InjectionStrategy.OPTIONAL)
+	    private String optionalProperty;
+
+        @ValueMapValue
+        private Optional<String> anotherOptionalProperty;
+    }
+Please note, that also injections marked as optional are always tried. It is just that any failure to inject a value does not lead to the termination of the creation of the SlingModel, but instead it continues, leaving the field value/return value at the default value of the used type.
+
+If a majority of injected fields/methods are optional, it is possible (since Sling Models API 1.0.2/Impl 1.0.6) to change the default injection strategy by using adding `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` to the `@Model` annotation:
 
 	::java
 	@Model(adaptables=Resource.class, defaultInjectionStrategy=DefaultInjectionStrategy.OPTIONAL)
 	public class MyModel {
 
-	    @Inject
-	    private String otherName;
+        @ValueMapValue
+        private String optionalProperty;
 	}
 
-To still mark some fields/methods as being mandatory while relying on `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` for all other fields, the annotation `@Required` can be used.
+To still mark some fields/methods as being mandatory while relying on `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` for all other fields, the parameter `injectionStrategy=InjectionStrategy.REQUIRED` can be used.
 
-`@Optional` annotations are only evaluated when using the `defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED` (which is the default), `@Required` annotations only if using `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL`.
+`defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` parameters are only evaluated when using the `defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED` (which is the default), `injectionStrategy=InjectionStrategy.REQUIRED` parameters only if using `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL`.
 
-## Defaults
-A default value can be provided (for Strings & primitives):
+## Via 
+In some cases, a different object should be used as the adaptable instead of the original adaptable. This can be done
+using the `via` parameter. By default, this can be done using a JavaBean property of the adaptable:
 
 	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
+	@Model(adaptables=SlingHttpServletRequest.class)
+	public interface MyModel {
 	 
-	    @Inject @Default(values="defaultValue")
-	    private String name;
-	}
+	    // will return request.getResource().getValueMap().get("propertyName", String.class)
+	    @ValueMapValue(via="resource")
+	    String getPropertyName();
+	} 
 
-Defaults can also be arrays:
+
+A different strategy can be used to define the adaptable by specifying a `type` attribute:
+
+    ::java
+    @Model(adaptables=Resource.class)
+    public interface MyModel {
+
+		// will return resource.getChild("jcr:content").getValueMap().get("propertyName", String.class)
+        @Inject @Via(value = "jcr:content", type = ChildResource.class)
+        String getPropertyName();
+
+    }
+
+See the [Via Types](#via-types-since-api-134implementation-140) section below for details on the included types for `@Via`.
+
+
+## Names
+If the field or method name doesn't exactly match the property name, the parameter `name` can be used:
 
 	::java
 	@Model(adaptables=Resource.class)
 	public class MyModel {
 	 
-	    @Inject @Default(intValues={1,2,3,4})
-	    private int[] integers;
-	}
+	    @ValueMapValue(name="secondPropertyName")
+	    private String otherName;
+	} 
+
+In this case the value of the property named `secondPropertyName` would be taken from the ValueMap.
+
 
+## Path
+The `@ResourcePath` injector supports the parameter `path` to inject a resource with the given parameter:   
 
-OSGi services can be injected:
+    ::java
+    @Model(adaptables=Resource.class) {
+
+        @ResourcePath(path="/libs")
+        Resource libs;
+    }
+
+## OSGi Service Filters
+OSGi injection can be filtered:
 
 	::java
-	@Model(adaptables=Resource.class)
+	@Model(adaptables=SlingHttpServletRequest.class)
 	public class MyModel {
 	 
-	    @Inject
-	    private ResourceResolverFactory resourceResolverFactory;
-	} 
-
- 
-In this case, the name is not used -- only the class name.
+	    @OSGiInjector
+	    private PrintWriter out;
+	 
+	    @OSGiInjector(name="log")
+	    private Logger logger;
+	 
+	    @OsgiInjector(filter="paths=/bin/something")
+	    private List<Servlet> servlets;
+	}
 
-## Collections
-Lists and arrays are supported by some injectors. For the details look at the table given in [Available Injectors](#available-injectors):
+## Collection support
+Lists and arrays are supported by some injectors. For the details look at the table given in [Available Injectors](#available-injectors-1):
 
 	::java
 	@Model(adaptables=Resource.class)

Review Comment:
   should we switch to a non-@Inject sample here as well?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1060535204


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   That should be already part of the description of the annotations.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] kwin commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
kwin commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1060513127


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   The recommendation is fine but please mention that this comes with limitations. Some injectors just require a request…



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] kwin commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
kwin commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1061127843


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -179,92 +150,121 @@ Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi
         // See the javadoc of the ModelFactory for which Exception can be expected here
     }
 
-In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.
+In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable. 
 
 ## Usage in HTL
-[Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1) (internally uses the `ModelFactory` from above).
+Please see [Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1); internally it uses the `ModelFactory` from above.
 
-# Other Options
-## Names
-If the field or method name doesn't exactly match the property name, `@Named` can be used:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Named("secondPropertyName")
-	    private String otherName;
-	} 
- 
+# Available injectors
+
+In the above cases just the `@ValueMapValue` annotation was used, but there other available injectors. For each injector there is a specialized annotation available. For the optional parameters see the next section.
+
+
+Injector Name  | Annotation          | Supported Optional Elements    | Description   | Array Support   | Parametrized Type Support

Review Comment:
   The first column is now a label and no longer the name. The name should still be documented as it must be used with annotation `@Source`



##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -89,40 +83,13 @@ Constructor injection is also supported (as of Sling Models 1.1.0):
 
 Because the name of a constructor argument parameter cannot be detected via the Java Reflection API a `@Named` annotation is mandatory for injectors that require a name for resolving the injection.
 
-Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)):
+Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
-    ::java
-    @Model(adaptables=Resource.class)
-    public class PublicConstructorModel {    
-        @Inject
-        public PublicConstructorModel() {
-          // constructor code
-        }
-    }
+## @Model and adaptable types
 
-    @Model(adaptables=Resource.class)
-    public class ProtectedConstructorModel {    
-        @Inject
-        protected ProtectedConstructorModel() {
-          // constructor code
-        }
-    }
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. All injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request. The only exception on the default injectors is the "Request Attribute" injector, which requires that the model is adapted from a SlingHttpServletRequest.

Review Comment:
   More prominent examples requiring request: script bindings and sling object



##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -660,86 +612,78 @@ 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;
+# Discouraged annotations
 
-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.
+In earlier versions of Sling Models the use of the annotation `@Inject` was suggested and documented; but over time it turned out that it had 2 major issues:
 
+* This injection iterated through all available injectors and injected the first non-null value provided by an injector. This lead to unpredictable behavior, although the order is well-defined. The addition of the `@Source` annotation did not really help.

Review Comment:
   Although @Source would have helped it was rarely used.



##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -660,86 +612,78 @@ 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;
+# Discouraged annotations
 
-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.
+In earlier versions of Sling Models the use of the annotation `@Inject` was suggested and documented; but over time it turned out that it had 2 major issues:
 
+* This injection iterated through all available injectors and injected the first non-null value provided by an injector. This lead to unpredictable behavior, although the order is well-defined. The addition of the `@Source` annotation did not really help.
+* This iteration turned out to the performance bottleneck, especially if (optional) injections were not succesful, and then all other injectors have to be tried.

Review Comment:
   turned out to be a performance bottleneck



##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -179,92 +150,121 @@ Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi
         // See the javadoc of the ModelFactory for which Exception can be expected here
     }
 
-In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.
+In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable. 
 
 ## Usage in HTL
-[Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1) (internally uses the `ModelFactory` from above).
+Please see [Sling Models Use Provider](/documentation/bundles/scripting/scripting-htl.html#java-use-provider-1); internally it uses the `ModelFactory` from above.
 
-# Other Options
-## Names
-If the field or method name doesn't exactly match the property name, `@Named` can be used:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Named("secondPropertyName")
-	    private String otherName;
-	} 
- 
+# Available injectors
+
+In the above cases just the `@ValueMapValue` annotation was used, but there other available injectors. For each injector there is a specialized annotation available. For the optional parameters see the next section.
+
+
+Injector Name  | Annotation          | Supported Optional Elements    | Description   | Array Support   | Parametrized Type Support
+----- | -----------------   | ------------------------------ |------------------------- | --------------- | ---------------------------
+Scripting Bindings|`@ScriptVariable`   | `injectionStrategy` and `name`          | Injects the script variable defined via [Sling Bindings](https://cwiki.apache.org/confluence/display/SLING/Scripting+variables). If `name` is not set the name is derived from the method/field name.  | no conversion is done |  If a parameterized type is passed, the bindings value must be of a compatible type of the parameterized type.
+ValueMap | `@ValueMapValue`    | `injectionStrategy`, `name`   | Injects a `ValueMap` value taken from the adapted resource (either taking from the adapted resource or the resource of the adapted SlingHttpServletRequest). If `name` is not set the name is derived from the method/field name. | Primitive arrays wrapped/unwrapped as necessary. Wrapper object arrays are unwrapped/wrapped as necessary. | Parameterized `List` and `Collection` injection points are injected by getting an array of the component type and creating an unmodifiable `List` from the array.
+Child Resource | `@ChildResource`    | `injectionStrategy`, `name`   | Injects a child resource by name (taken from the adapted resource (either taking from the adapted resource or the resource of the adapted SlingHttpServletRequest). If `name` is not set the name is derived from the method/field name. | none  | if a parameterized type `List` or `Collection` is passed, a `List<Resource>` is returned (the contents of which may be adapted to the target type) filled with all child resources of the resource looked up by the given name.
+Request Attribute | `@RequestAttribute` | `injectionStrategy`, `name`    | Injects a request attribute by name, it requires the the adaptable is a `SlingHttpServletRequest` . If `name` is not set the name is derived from the method/field name. | no conversion is done | If a parameterized type is passed, the request attribute must be of a compatible type of the parameterized type.
+Resource path | `@ResourcePath`     | `injectionStrategy`, `path`, and `name` |Injects a resource either by path or by reading a property with the given name. | yes | none
+OSGi service | `@OSGiService`      | `injectionStrategy`, `filter`           | Injects an OSGi service by type (and the optional filter) | yes | Parameterized `List` and `Collection` injection points are injected by getting an array of the services and creating an unmodifiable `List` from the array.
+Context-Aware Configuration | `@ContextAwareConfiguration` | `injectionStrategy`, `name`    |  Lookup context-aware configuration. See [Context-Aware Configuration](#context-aware-configuration) below. | yes | If a parameterized type `List` or `Collection` is used, a configuration collection is looked up.
+Self | `@Self`             | `injectionStrategy`                     |  Injects the adaptable itself. If the field type does not match with the adaptable it is tried to adapt the adaptable to the requested type. | none | none
+Sling Object | `@SlingObject`      | `injectionStrategy`                     | Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper | none | none
+
+# Parameters to the Injectors
+
+Injectors can support optional parameters as listed in the above table
+
 ## Optional and Required
-`@Inject`ed fields/methods are assumed to be required. To mark them as optional, use `@Optional`:
 
-	::java
-	@Model(adaptables=Resource.class)
-	public class MyModel {
-	 
-	    @Inject @Optional
-	    private String otherName;
-	}
+Injected fields/methods are assumed to be required. To mark them as optional, there are 2 options:
+
+* add the parameter `injectionStrategy=InjectionStrategy.OPTIONAL` to the annotation
+* or wrap the type into an `Optional`
+
+It is recommended to use the approach using the `Optional` type, because then this "optionality" is also expressed in the type system.
+
+    ::java
+    import java.util.Optional;
+
+    @Model(adaptables=Resource.class)
+    public class MyModel {
+
+	    @ValueMapValue(injectionStrategy=InjectionStrategy.OPTIONAL)
+	    private String optionalProperty;
+
+        @ValueMapValue
+        private Optional<String> anotherOptionalProperty;
+    }
+Please note, that also injections marked as optional are always tried. It is just that any failure to inject a value does not lead to the termination of the creation of the SlingModel, but instead it continues, leaving the field value/return value at the default value of the used type.

Review Comment:
   that even injections marked as



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh merged pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh merged PR #106:
URL: https://github.com/apache/sling-site/pull/106


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on PR #106:
URL: https://github.com/apache/sling-site/pull/106#issuecomment-1373810388

   I plan to merge it on Monday.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] kwin commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
kwin commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1060577140


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   It is crucial to mention it here as well as otherwise people might just choose adaptable Resource without being aware of those limitations.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1062398704


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -89,40 +83,13 @@ Constructor injection is also supported (as of Sling Models 1.1.0):
 
 Because the name of a constructor argument parameter cannot be detected via the Java Reflection API a `@Named` annotation is mandatory for injectors that require a name for resolving the injection.
 
-Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)):
+Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
-    ::java
-    @Model(adaptables=Resource.class)
-    public class PublicConstructorModel {    
-        @Inject
-        public PublicConstructorModel() {
-          // constructor code
-        }
-    }
+## @Model and adaptable types
 
-    @Model(adaptables=Resource.class)
-    public class ProtectedConstructorModel {    
-        @Inject
-        protected ProtectedConstructorModel() {
-          // constructor code
-        }
-    }
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. All injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request. The only exception on the default injectors is the "Request Attribute" injector, which requires that the model is adapted from a SlingHttpServletRequest.

Review Comment:
   is refined.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] joerghoh commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
joerghoh commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1059653312


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   Can you suggest a sentence for that? I feel a bit out of my comfort-zone here, especially when it comes to the ```@via``` annotation and it's replacement in the injector-specific annotations.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [sling-site] kwin commented on a diff in pull request #106: SLING-11711 rework of the Sling Model documentation, part 1

Posted by GitBox <gi...@apache.org>.
kwin commented on code in PR #106:
URL: https://github.com/apache/sling-site/pull/106#discussion_r1059652015


##########
src/main/jbake/content/documentation/bundles/models.md:
##########
@@ -85,6 +85,14 @@ Because the name of a constructor argument parameter cannot be detected via the
 
 Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https://issues.apache.org/jira/browse/SLING-8069)).
 
+## @Model and adaptable types
+
+While technically it is possible to provide any class implementing the `Adaptable` interface as the `adaptable` parameter to the `@Model` annotation, the Sling Model Framework and the default injectors is mostly built under the assumption that the adaption is done from a Sling Resource. Some injectors also support adaption from a `SlingHttpServletRequest` object, but normally this is then converted into a adaption of the resource of the request.

Review Comment:
   IMHO we should outline that all injectors can deal with adaptable SlingHttpServletRequest (potentially leveraging via) while Resource limits what injections are possible.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org