You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by en...@apache.org on 2025/09/29 17:42:38 UTC
(sling-site) branch master updated: SLING-12874 Documentation updates for Models API 2.0.0 (#207)
This is an automated email from the ASF dual-hosted git repository.
enorman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new b2de84352 SLING-12874 Documentation updates for Models API 2.0.0 (#207)
b2de84352 is described below
commit b2de84352ab4b6479f36da583499f18d62e105ed
Author: Eric Norman <en...@apache.org>
AuthorDate: Mon Sep 29 10:42:32 2025 -0700
SLING-12874 Documentation updates for Models API 2.0.0 (#207)
---
.../jbake/content/documentation/bundles/models.md | 69 +++++++++++++---------
1 file changed, 41 insertions(+), 28 deletions(-)
diff --git a/src/main/jbake/content/documentation/bundles/models.md b/src/main/jbake/content/documentation/bundles/models.md
index 6837162a7..d253f6d36 100644
--- a/src/main/jbake/content/documentation/bundles/models.md
+++ b/src/main/jbake/content/documentation/bundles/models.md
@@ -95,7 +95,7 @@ Constructors may use any visibility modifier (as of [Sling Models 1.5.0](https:/
## @Model and Adaptable Types
-When defining a Sling Model class, the `adaptables` parameter to the `@Model` annotation is mostly determined by the injectors being used. The provided class must satisfy the needs of all injectors (for the details see [the table below](#available-injectors-1)). For example if the model class only uses the `ValueMap` injector, the adaptables parameter can be a `Resource`, a `SlingHttpServletRequest` or both. But if the `Request Attribute` injector is used, only an adaptable of the type ` [...]
+When defining a Sling Model class, the `adaptables` parameter to the `@Model` annotation is mostly determined by the injectors being used. The provided class must satisfy the needs of all injectors (for the details see [the table below](#available-injectors-1)). For example if the model class only uses the `ValueMap` injector, the adaptables parameter can be a `Resource`, a `SlingJakartaHttpServletRequest`, a `SlingHttpServletRequest` or both. But if the `Request Attribute` injector is u [...]
In order to increase the reuse it's advised to stick to `Resource` as adaptables if possible, as such a model can be used in the context of request and outside of it.
@@ -171,15 +171,15 @@ In the above cases just the `@ValueMapValue` annotation was used, but there othe
Title | Injector Name | Annotation | Supported Optional Elements | Description | Applicable to (including using `@Via`) | Array Support | Parametrized Type Support
----- | ----------------- | ------------------------------ |------------------------- | --------------- | ---------------------------
-Scripting Bindings|`script-bindings` | `@ScriptVariable` | `injectionStrategy` and `name` | Injects the script variable defined via [Sling Bindings](https://cwiki.apache.org/confluence/display/SLING/Scripting+variables). It requires the the adaptable is a `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name. | A ServletRequest object which has the `Sling Bindings` attribute defined | no conversion is done | If a parameterized type is [...]
-ValueMap | `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. |Any object which is or can be adapted to a `ValueMap` | Primitive arrays wrapped/unwrapped as necessary. Wrapper object arrays are unwrapped/wrapped as necessary. | Parameterized `List` [...]
-Child Resource | `child-resources` | `@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. | `Resource` objects | none | if a parameterized type `List` or `Collection` is passed, a `List<Resource>` is returned (the contents of which may be adapted to the t [...]
-Request Attribute | `request-attributes` | `@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. | `ServletRequest` objects | 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 | `resource-path` | `@ResourcePath` | `injectionStrategy`, `path`, and `name` |Injects a resource either by path or by reading a property with the given name. | `Resource` or `SlingHttpServletRequest` objects | yes | none
+Scripting Bindings|`script-bindings` | `@ScriptVariable` | `injectionStrategy` and `name` | Injects the script variable defined via [Sling Bindings](https://cwiki.apache.org/confluence/display/SLING/Scripting+variables). It requires the the adaptable is a `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name. | A ServletRequest object which has the `Sling Bindings` attribute defined | no conversion i [...]
+ValueMap | `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 SlingJakartaHttpServletRequest or SlingHttpServletRequest). If `name` is not set the name is derived from the method/field name. |Any object which is or can be adapted to a `ValueMap` | Primitive arrays wrapped/unwrapped as necessary. Wrapper object arrays are unwrapped/wrapped as [...]
+Child Resource | `child-resources` | `@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 SlingJakartaHttpServletRequest or SlingHttpServletRequest). If `name` is not set the name is derived from the method/field name. | `Resource` objects | none | if a parameterized type `List` or `Collection` is passed, a `List<Resource>` is returned (the content [...]
+Request Attribute | `request-attributes` | `@RequestAttribute` | `injectionStrategy`, `name` | Injects a request attribute by name, it requires the the adaptable is a `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest` . If `name` is not set the name is derived from the method/field name. | `ServletRequest` objects | 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 | `resource-path` | `@ResourcePath` | `injectionStrategy`, `path`, and `name` |Injects a resource either by path or by reading a property with the given name. | `Resource`, `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest` objects | yes | none
OSGi service | `osgi-services` | `@OSGiService` | `injectionStrategy`, `filter` | Injects an OSGi service by type (and the optional filter) | Any object | 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 | `ca-config` | `@ContextAwareConfiguration` | `injectionStrategy`, `name` | Lookup context-aware configuration. See [Context-Aware Configuration](#context-aware-configuration) below. | Any object | yes | If a parameterized type `List` or `Collection` is used, a configuration collection is looked up.
Self | `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. | any object | none | none
-Sling Object | `sling-object` | `@SlingObject` | `injectionStrategy` | Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper | `Resource`, `ResourceResolver` or `SlingHttpServletRequest` objects (not all objects can be resolved by all adaptables). | none | none
+Sling Object | `sling-object` | `@SlingObject` | `injectionStrategy` | Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper | `Resource`, `ResourceResolver`, `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest` objects (not all objects can be resolved by all adaptables). | none | none
# Parameters to the Injectors
@@ -253,7 +253,7 @@ The `@ResourcePath` injector supports the parameter `path` to inject a resource
OSGi injection can be filtered:
::java
- @Model(adaptables=SlingHttpServletRequest.class)
+ @Model(adaptables=SlingJakartaHttpServletRequest.class)
public class MyModel {
@OSGiService
@@ -332,7 +332,7 @@ While this feature does also work with the injector-specfic annotations above, i
By default, this can be done using a JavaBean property of the adaptable:
::java
- @Model(adaptables=SlingHttpServletRequest.class)
+ @Model(adaptables=SlingJakartaHttpServletRequest.class)
public interface MyModel {
// will return request.getResource().getValueMap().get("propertyName", String.class)
@@ -360,9 +360,9 @@ The following standard types are provided (all types are in the package `org.apa
`@Via` type value | Description
----------------------------- | ------------------------------
`BeanProperty` (default) | Uses a JavaBean property from the adaptable.
-`ChildResource` | Uses a child resource from the adaptable, assuming the adaptable is a `Resource`. In case the adaptable is a `SlingHttpServletRequest` uses a wrapper overwriting the `getResource()` to point to the given child resource ([SLING-7321](https://issues.apache.org/jira/browse/SLING-7321)).
-`ForcedResourceType` | Creates a wrapped resource with the provided resource type. If the adaptable is a `SlingHttpServletRequest`, a wrapped request is created as well to contain the wrapped resource.
-`ResourceSuperType` | Creates a wrapped resource with the resource type set to the adaptable's resource super type. If the adaptable is a `SlingHttpServletRequest`, a wrapped request is created as well to contain the wrapped resource.
+`ChildResource` | Uses a child resource from the adaptable, assuming the adaptable is a `Resource`. In case the adaptable is a `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest` uses a wrapper overwriting the `getResource()` to point to the given child resource ([SLING-7321](https://issues.apache.org/jira/browse/SLING-7321)).
+`ForcedResourceType` | Creates a wrapped resource with the provided resource type. If the adaptable is a `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest`, a wrapped request is created as well to contain the wrapped resource.
+`ResourceSuperType` | Creates a wrapped resource with the resource type set to the adaptable's resource super type. If the adaptable is a `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest`, a wrapped request is created as well to contain the wrapped resource.
Defining your own type for the `@Via` annotation is a two step process. The first step is to create a marker class implementing the `@ViaProviderType` annotation. This class can be entirely empty, e.g.
@@ -381,7 +381,7 @@ The second step is to create an OSGi service implementing the `ViaProvider` inte
The `@PostConstruct` annotation can be used to add methods which are invoked upon completion of all injections:
::java
- @Model(adaptables=SlingHttpServletRequest.class)
+ @Model(adaptables=SlingJakartaHttpServletRequest.class)
public class MyModel {
@SlingObject
@@ -456,7 +456,7 @@ Since API version 1.2.0 you can use the attribute `validation` on the Model anno
In case the model is not instantiated an appropriate error message is logged (if `adaptTo()` is used) or an appropriate exception is thrown if `ModelFactory.createModel()` is used.
-The only implementation for this Sling Models validation service is leveraging [Sling Validation](/documentation/bundles/validation.html) and is located in the bundle [org.apache.sling.models.validation-impl](https://github.com/apache/sling-org-apache-sling-models-validation-impl). Validation is only working on models which are adapted from either `Resource` or `SlingHttpServletRequest` and if the Sling Validation Bundle is deployed.
+The only implementation for this Sling Models validation service is leveraging [Sling Validation](/documentation/bundles/validation.html) and is located in the bundle [org.apache.sling.models.validation-impl](https://github.com/apache/sling-org-apache-sling-models-validation-impl). Validation is only working on models which are adapted from either `Resource`, `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest` and if the Sling Validation Bundle is deployed.
# Performance
@@ -470,10 +470,10 @@ By default, Sling Models do not do any caching of the adaptation result and ever
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:
+While this is true for `AbstractResource` subclasses, it is notably **not** the case for `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest` as this class does not extend `SlingAdaptable`. So:
::java
- // assume that request is some SlingHttpServletRequest object
+ // assume that request is some SlingJakartaHttpServletRequest or 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;
@@ -482,12 +482,12 @@ Since API version 1.3.4, Sling Models *can* cache an adaptation result, regardle
::java
- @Model(adaptable = SlingHttpServletRequest.class, cache = true)
+ @Model(adaptable = SlingJakartaHttpServletRequest.class, cache = true)
public class ModelClass {}
...
- // assume that request is some SlingHttpServletRequest object
+ // assume that request is some SlingJakartaHttpServletRequest or 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;
@@ -495,12 +495,12 @@ Since API version 1.3.4, Sling Models *can* cache an adaptation result, regardle
When `cache = true` is specified, the adaptation result is cached regardless of how the adaptation is done:
::java
- @Model(adaptable = SlingHttpServletRequest.class, cache = true)
+ @Model(adaptable = SlingJakartaHttpServletRequest.class, cache = true)
public class ModelClass {}
...
- // assume that request is some SlingHttpServletRequest object
+ // assume that request is some SlingJakartaHttpServletRequest or 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;
@@ -513,10 +513,10 @@ In general, it is **strongly** discouraged to store a reference to the original
The problem can be avoided by discarding the original adaptable when it is no longer needed. This can be done by setting affected field(s) to `null` at the end of the `@PostConstruct` annotated method:
::java
- @Model(adaptable = SlingHttpServletRequest.class, cache = true)
+ @Model(adaptable = SlingJakartaHttpServletRequest.class, cache = true)
public class CachableModelClass {
@Self
- private SlingHttpServletRequest request;
+ private SlingJakartaHttpServletRequest request;
@PostConstruct
private void init() {
@@ -529,9 +529,9 @@ The problem can be avoided by discarding the original adaptable when it is no lo
Alternatively, the same effect can be achieved using constructor injection, by not storing the reference to the adaptable:
::java
- @Model(adaptable = SlingHttpServletRequest.class, cache = true)
+ @Model(adaptable = SlingJakartaHttpServletRequest.class, cache = true)
public class CachableModelClass {
- public CachableModelClass(SlingHttpServletRequest request) {
+ public CachableModelClass(SlingJakartaHttpServletRequest request) {
... do something with request ...
}
}
@@ -560,7 +560,7 @@ To use it, the following additional bundles are required (with given minimal ver
Usage example for injecting a single Context-Aware configuration looked up in context of the current resource (`SingleConfig` is an annotation class describing the context-aware configuration):
::java
- @Model(adaptables = { SlingHttpServletRequest.class, Resource.class })
+ @Model(adaptables = { SlingJakartaHttpServletRequest.class, Resource.class })
public class SingleConfigModel {
@ContextAwareConfiguration
@@ -571,7 +571,7 @@ Usage example for injecting a single Context-Aware configuration looked up in co
Example for injecting a configuration list (`ListConfig` is an annotation class configured as context-aware configuration list):
::java
- @Model(adaptables = { SlingHttpServletRequest.class, Resource.class })
+ @Model(adaptables = { SlingJakartaHttpServletRequest.class, Resource.class })
public class ListConfigModel {
@ContextAwareConfiguration
@@ -631,7 +631,7 @@ more resource types. This is used in three different ways.
In the case of multiple model classes implementing the same interface, the class with the "closest" resource type will be used when
adapting to the interface.
-The `ModelFactory` service interface has methods `Object getModelFromResource(Resource)` and `Object getModelFromRequest(SlingHttpServletRequest)` which will dynamically determine the adapter class based on the `Resource` using its type. In the case of the `SlingHttpServletRequest` method, it uses the request's `Resource` object (i.e. by calling `request.getResource()`)
+The `ModelFactory` service interface has methods `Object getModelFromResource(Resource)`, `Object getModelFromRequest(SlingJakartaHttpServletRequest)` and `Object getModelFromRequest(SlingHttpServletRequest)` which will dynamically determine the adapter class based on the `Resource` using its type. In the case of the `SlingJakartaHttpServletRequest` or `SlingHttpServletRequest` methods, it uses the request's `Resource` object (i.e. by calling `request.getResource()`)
The resource type is also used as part of the Exporter framework (see next section).
@@ -657,7 +657,7 @@ In addition, model objects can have servlets automatically registered for their
results in the registration of a servlet with the resource type and extension specified and a selector of 'model' (overridable
through the `@Exporter` annotation's `selector` attribute). When this servlet is invoked, the `Resource` will be adapted to the
-model, exported as a `java.lang.String` (via the named Exporter) and then returned to the client. The `ExportServlet` only supports models for adaptable `org.apache.sling.api.resource.Resource` or `org.apache.sling.api.SlingHttpServletRequest`. If a model is adaptable from both the `Resource` is used.
+model, exported as a `java.lang.String` (via the named Exporter) and then returned to the client. The `ExportServlet` only supports models for adaptable `org.apache.sling.api.resource.Resource`, `org.apache.sling.api.SlingJakartaHttpServletRequest` or `org.apache.sling.api.SlingHttpServletRequest`. If a model is adaptable from both the `Resource` is used.
The ExportServlet allows to pass options to the exporter either via additional selectors (which just get the String value `"true"` in the used options map) or via regular request parameters (which are added to the options map with the given value or just with the String value `"true"` in case the request parameter didn't carry a value).
@@ -725,3 +725,16 @@ For these reasons the injector-specific annotations have been created, and this
`@Path`
: only used together with the resource-path injector to specify the path of a resource
+
+# Migration to version 2.x
+
+After migrating to the 2.x version, some annotations may be flagged as using deprecated apis. Below are some hints about how to resolve the warnings.
+
+ Deprecated Annotations From Models API 1.x | Change To Annotations From Models API 2.x
+ -------------- | ---------------
+ @Model(adaptables=SlingHttpServletRequest.class) | @Model(adaptables=SlingJakartaHttpServletRequest.class)
+ @SlingObject<br>protected SlingHttpServletRequest requestFromSlingObject; | @SlingObject<br>protected SlingJakartaHttpServletRequest requestFromSlingObject;
+ @ScriptVariable(name = "request")<br>protected SlingHttpServletRequest requestFromNamedScriptVariable; | @ScriptVariable(name = "jakartaRequest")<br>protected SlingJakartaHttpServletRequest requestFromNamedScriptVariable;
+ @ScriptVariable<br>protected SlingHttpServletRequest request; | @ScriptVariable<br>protected SlingJakartaHttpServletRequest jakartaRequest;
+ @Self<br>protected SlingHttpServletRequest requestFromSelf; | @Self<br>protected SlingJakartaHttpServletRequest requestFromSelf;
+