Author: kwin
Date: Thu Nov 13 16:06:53 2014
New Revision: 1639376
URL: http://svn.apache.org/r1639376
Log:
SLING-4156, extend documentation around default injection strategy
also document limitations for injector-specific annotations
add subsections for the Other Options section
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=1639376&r1=1639375&r2=1639376&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/models.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/models.mdtext Thu Nov 13
16:06:53 2014
@@ -86,7 +86,7 @@ Or
As with other AdapterFactories, if the adaptation can't be made for any
reason, `adaptTo()` returns null.
# Other Options
-
+## Names
If the field or method name doesn't exactly match the property name, `@Named`
can be used:
::java
@@ -97,7 +97,7 @@ If the field or method name doesn't exac
private String otherName;
}
-
+## Optional and Required
`@Inject`ed fields/methods are assumed to be required. To mark them as
optional, use `@Optional`:
::java
@@ -119,7 +119,13 @@ strategy by using adding `defaultInjecti
private String otherName;
}
+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.
+
+`@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):
::java
@@ -154,6 +160,7 @@ OSGi services can be injected:
In this case, the name is not used -- only the class name.
+## Collections
Lists and arrays are supported:
::java
@@ -186,6 +193,7 @@ Is suitable for a resource structure suc
In this case, the `addresses` `List` will contain `address1` and `address2`.
+## OSGi Service Filters
OSGi injection can be filtered:
::java
@@ -204,7 +212,7 @@ OSGi injection can be filtered:
private List<Servlet> servlets;
}
-
+## PostConstruct Methods
The `@PostConstruct` annotation can be used to add methods which are invoked
upon completion of all injections:
::java
@@ -225,7 +233,8 @@ The `@PostConstruct` annotation can be u
}
`@PostConstruct` methods in a super class will be invoked first.
-
+
+## Via
If the injection should be based on a JavaBean property of the adaptable, you
can indicate this using the `@Via` annotation:
::java
@@ -237,6 +246,7 @@ If the injection should be based on a Ja
String getPropertyName();
}
+## Source
If there is ambiguity where a given injection could be handled by more than
one injector, the `@Source` annotation can be used to define which injector is
responsible:
::java
@@ -248,6 +258,7 @@ If there is ambiguity where a given inje
Resource getResource();
}
+## Adaptations
If the injected object does not match the desired type and the object
implements the `Adaptable` interface, Sling Models will try to adapt it. This
provides the ability to create rich object graphs. For example:
::java
@@ -357,7 +368,7 @@ Annotation | Supported Optional
## Hints
-Those annotations replace `@Via`, `@Filter`, `@Named`, `@Optional`, `@Source`
and `@Inject`.
+Those annotations replace `@Via`, `@Filter`, `@Named`, `@Optional`,
`@Required`, `@Source` and `@Inject`.
`@Default` may still be used in addition to the injector-specific annotation
to set default values. All elements given above are optional.
## Custom Annotations
