svn commit: r1639376 - /sling/site/trunk/content/documentation/bundles/models.mdtext

[kw...@apache.org]

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