Author: kwin
Date: Fri Jan 22 13:37:56 2016
New Revision: 1726209
URL: http://svn.apache.org/viewvc?rev=1726209&view=rev
Log:
SLING-4155 document new annotation element injectionStrategy
clarify the parametrization for each injector
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=1726209&r1=1726208&r2=1726209&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/models.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/models.mdtext Fri Jan 22
13:37:56 2016
@@ -139,8 +139,6 @@ To still mark some fields/methods as bei
`@Optional` annotations are only evaluated when using the
`defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED` (which is the
default), `@Required` annotations only if using `defaultInjectionStrategy =
DefaultInjectionStrategy.OPTIONAL`.
-*The `defaultInjectionStrategy` is currently not considered for fields/methods
annotated with Injector-specific annotations (see also
[SLING-4155](https://issues.apache.org/jira/browse/SLING-4155))*
-
## Defaults
A default value can be provided (for Strings & primitives):
@@ -362,12 +360,12 @@ Injectors are invoked in order of their
Title | Name (for `@Source`) | Service Ranking | Available
Since (Implementation Version) | Description | Applicable To (including using
`@Via`) | Accepts Null Name? | Array Support | Parameterized Type Support
----------------- | ----------------------- | ------------------- |
---------------------------------------- | ------------ |
-------------------------------------- | ------------------ | ------------- |
--------------------------
-Script Bindings | `script-bindings` | 1000 | 1.0.0
| Lookup objects in the script bindings object |
A ServletRequest object which has the `Sling Bindings` attribute defined | no |
no conversion is done | If a parameterized type is passed, the bindings value
must be of a compatible type of the parameterized type.
-Value Map | `valuemap` | 2000 | 1.0.0
| Gets a property from a `ValueMap` | Any object
which is or can be adapted to a `ValueMap`| no | 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 Resources | `child-resources` | 3000 | 1.0.0
| Gets a child resource by name | `Resource`
objects | no | none | if a parameterized type is passed, a `List<Resource>` is
returned (the contents of which may be adapted to the target type).
-Request Attributes | `request-attributes` | 4000 | 1.0.0
| Get a request attribute |
`ServletRequest` objects | no | no conversion is done | If a parameterized type
is passed, the request attribute must be of a compatible type of the
parameterized type.
-OSGi Services | `osgi-services` | 5000 | 1.0.0
| Lookup services based on class name | Any
object | yes | yes | Parameterized `List` and `Collection` injection points are
injected by getting an array of the services and creating an unmodifiable
`List` from the array.
-Resource Path | `resource-path` | 2500 | 1.1.0
| Injects a resource by its path. | `Resource`
or `SlingHttpServletRequest` objects | yes | none | none
+Script Bindings | `script-bindings` | 1000 | 1.0.0
| Lookup objects in the script bindings object
by name. | A ServletRequest object which has the `Sling Bindings` attribute
defined | no | no conversion is done | If a parameterized type is passed, the
bindings value must be of a compatible type of the parameterized type.
+Value Map | `valuemap` | 2000 | 1.0.0
| Gets a property from a `ValueMap` by name. |
Any object which is or can be adapted to a `ValueMap`| no | 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 Resources | `child-resources` | 3000 | 1.0.0
| Gets a child resource by name. | `Resource`
objects | no | none | if a parameterized type is passed, a `List<Resource>` is
returned (the contents of which may be adapted to the target type).
+Request Attributes | `request-attributes` | 4000 | 1.0.0
| Get a request attribute by name. |
`ServletRequest` objects | no | no conversion is done | If a parameterized type
is passed, the request attribute must be of a compatible type of the
parameterized type.
+OSGi Services | `osgi-services` | 5000 | 1.0.0
| Lookup services based on class name. | Any
object | yes | yes | Parameterized `List` and `Collection` injection points are
injected by getting an array of the services and creating an unmodifiable
`List` from the array.
+Resource Path | `resource-path` | 2500 | 1.1.0
| Injects a resource by its path derived from
the name. | `Resource` or `SlingHttpServletRequest` objects | yes | none | none
Self | `self` | `Integer.MAX_VALUE` | 1.1.0
| Injects the adaptable object itself (if the
class of the field matches or is a supertype). If the @Self annotation is
present it is tried to adapt the adaptable to the field type. | Any object |
yes | none | none
Sling Object | `sling-object` | `Integer.MAX_VALUE` | 1.1.0
| Injects commonly used sling objects if the
field matches with the class: request, response, resource resolver, current
resource, SlingScriptHelper. This works only if the adaptable can get the
according information, i.e. all objects are available via
`SlingHttpServletRequest` while `ResourceResolver` can only resolve the
`ResourceResolver` object and nothing else. A discussion around this limitation
can be found at [SLING-4083](https://issues.apache.org/jira/browse/SLING-4083).
Also `Resource`s can only be injected if the according injector-specific
annotation is used (`@SlingObject`). | `Resource`, `ResourceResolver` or
`SlingHttpServletRequest` objects (not all objects can be resolved by all
adaptables). | yes | none | none
@@ -386,18 +384,19 @@ The follow annotations are provided whic
Annotation | Supported Optional Elements | Injector | Description
----------------- | ------------------------------ |-------------------------
-`@ScriptVariable` | `optional` and `name` | `script-bindings` |
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.
-`@ValueMapValue` | `optional`, `name` and `via` | `valuemap` | 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.
-`@ChildResource` | `optional`, `name` and `via` | `child-resources` |
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.
-`@RequestAttribute` | `optional`, `name` and `via` | `request-attributes` |
Injects a request attribute by name. If `name` is not set the name is derived
from the method/field name.
-`@ResourcePath` | `optional`, `path`, and `name` | `resource-path` |
Injects a resource either by path or by reading a property with the given name.
-`@OSGiService` | `optional`, `filter` | `osgi-services` |
Injects an OSGi service by type. The `filter` can be used give an OSGi service
filter.
-`@Self` | `optional` | `self` | 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.
-`@SlingObject` | `optional` | `sling-object` |Injects
commonly used sling objects if the field matches with the class: request,
response, resource resolver, current resource, SlingScriptHelper
+`@ScriptVariable` | `injectionStrategy` and `name` |
`script-bindings` | 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.
+`@ValueMapValue` | `injectionStrategy`, `name` and `via` | `valuemap` |
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.
+`@ChildResource` | `injectionStrategy`, `name` and `via` |
`child-resources` | 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.
+`@RequestAttribute` | `injectionStrategy`, `name` and `via` |
`request-attributes` | Injects a request attribute by name. If `name` is not
set the name is derived from the method/field name.
+`@ResourcePath` | `injectionStrategy`, `path`, and `name` |
`resource-path` | Injects a resource either by path or by reading a property
with the given name.
+`@OSGiService` | `injectionStrategy`, `filter` |
`osgi-services` | Injects an OSGi service by type. The `filter` can be used
give an OSGi service filter.
+`@Self` | `injectionStrategy` | `self` |
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.
+`@SlingObject` | `injectionStrategy` | `sling-object`
|Injects commonly used sling objects if the field matches with the class:
request, response, resource resolver, current resource, SlingScriptHelper
## Hints
-Those annotations replace `@Via`, `@Filter`, `@Named`, `@Optional`,
`@Required`, `@Source` and `@Inject`.
+Those annotations replace `@Via`, `@Filter`, `@Named`, `@Optional`,
`@Required`, `@Source` and `@Inject`.
+Instead of using the deprecated annotation element `optional` you should
rather use `injectionStrategy` with the values `DEFAULT`, `OPTIONAL` or
`REQUIRED` (see also
[SLING-4155](https://issues.apache.org/jira/browse/SLING-4155)).
`@Default` may still be used in addition to the injector-specific annotation
to set default values. All elements given above are optional.
## Custom Annotations
