svn commit: r1422315 - /incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext

[gp...@apache.org]

Author: gpetracek
Date: Sat Dec 15 18:58:45 2012
New Revision: 1422315

URL: http://svn.apache.org/viewvc?rev=1422315&view=rev
Log:
description of BeanProvider

Modified:
    incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext

Modified: incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext?rev=1422315&r1=1422314&r2=1422315&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/core.mdtext Sat Dec 15 18:58:45 2012
@@ -18,6 +18,61 @@ Notice:    Licensed to the Apache Softwa
 
 # Core - API
 
+## BeanProvider
+
+The `BeanProvider` is a class which provides (static) util methods which allow to lookup beans if it isn't possible to inject them via `@Inject` or if the lookup depends on dynamic conditions. Instead of using the term 'bean', the term 'contextual instance' is used because that's the term used by CDI itself.
+
+The following example shows a simple lookup. With the second parameter it's possible to specify if the contextual instance is optional. If it isn't expected that the contextual instance is optional, but no instance has been found, an `IllegalStateException` will be thrown.
+
+Resolving a simple contextual instance:
+
+    MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false);
+
+Pass `true` as second argument, if you look for an implementation of the given interface and an implementation isn't required or it isn't required that there is an instance with the given qualifier (see the qualifier example for further details).
+
+Resolving an optional contextual instance:
+
+    MyServiceInterface optionalService = BeanProvider.getContextualReference(MyServiceInterface.class, true);
+
+Optionally you can provide a qualifier for the contextual instance in question. CDI qualifiers are annotations, therefore you need to implement a corresponding literal for providing an instance.
+
+Literal implementation for '@MyQualifier':
+
+    import javax.enterprise.util.AnnotationLiteral;
+    //...
+
+    public class MyQualifierLiteral extends AnnotationLiteral<MyQualifier> implements MyQualifier
+    {
+    }
+
+The following example will return a contextual instance with the qualifier {{@MyQualifier}}
+
+Resolving a simple contextual instance with qualifier:
+
+    MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false, new MyQualifierLiteral());
+
+The `@Named` qualifier has a special role and allows to specify a string based name (e.g. for referencing CDI beans in EL-expressions). However, the following examples show how to do a manual lookup by name.
+
+Resolving a simple contextual instance by name:
+
+    Object myBean = BeanProvider.getContextualReference("myBean", false);
+
+Resolving a simple contextual instance by name and expected type:
+
+    MyBean myBean = BeanProvider.getContextualReference("myBean", false, MyBean.class);
+
+Sometimes it's essential to resolve all contextual instances which implement e.g. an interface or all beans with the same type but a different qualifier. The following example shows how to do such a lookup which returns all contextual instances (independent of the scope -> also dependent scoped instances).
+
+Resolving all contextual instances of a given type:
+
+    List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false);
+
+Since dependent scoped beans have a special role in CDI (you have to destroy them manually - esp. if you get them via a manual lookup), you can also call the previous util method with an additional parameter to filter dependent scoped instances.
+
+Resolving all contextual instances of a given type without dependent scoped instances:
+
+    List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false, false);
+
 ## Type-safe ProjectStage
 
 TODO
@@ -30,10 +85,6 @@ TODO
 
 TODO
 
-## BeanProvider
-
-TODO
-
 ## Type-safe config
 
 TODO