svn commit: r1529107 - /openwebbeans/cms-site/trunk/content/cdi_explained.mdtext

[st...@apache.org]

Author: struberg
Date: Fri Oct  4 09:16:42 2013
New Revision: 1529107

URL: http://svn.apache.org/r1529107
Log:
introduction chapter to CDI

Modified:
    openwebbeans/cms-site/trunk/content/cdi_explained.mdtext

Modified: openwebbeans/cms-site/trunk/content/cdi_explained.mdtext
URL: http://svn.apache.org/viewvc/openwebbeans/cms-site/trunk/content/cdi_explained.mdtext?rev=1529107&r1=1529106&r2=1529107&view=diff
==============================================================================
--- openwebbeans/cms-site/trunk/content/cdi_explained.mdtext (original)
+++ openwebbeans/cms-site/trunk/content/cdi_explained.mdtext Fri Oct  4 09:16:42 2013
@@ -16,12 +16,85 @@ Notice:    Licensed to the Apache Softwa
            specific language governing permissions and limitations
            under the License.
 
-# OpenWebBeans FAQ
+# What can OpenWebBeans as CDI container do for you?
+
+
+## An introduction to CDI
+
+Contexts and Dependency Injection for Java a.k.a. CDI is a JavaEE specification with the number JSR-299.
+Apache OpenWebBeans implements this standard. This page will give you an introduction to features of 
+CDI in general. We will add a special hint whenever a feature is ambiguous in the specification 
+and OpenWebBeans implements it in a certain way which might be different on other CDI containers.
+
+## What is CDI at all?
+
+Originally developed under the name ‘Web Beans’, the CDI specification was created 
+to fill the gaps which could not be filled by Enterprise Java Beans (EJB) on the back end, 
+and JavaServer Faces (JSF) in the view layer. The first draft targeted only 
+Java Enterprise Edition (Java EE), but during the creation of the specification 
+it became clear that most features were very useful for any Java environment, 
+including Java SE.
+
+Even if the full name of the specification is 
+
+> Contexts and Dependency Injection for the Java Enterprise platform
+
+this does not mean that CDI applications can only run in JavaEE those days. 
+At least OpenWebBeans provides CDI functionality which also runs in pure Java SE apps like Swing, JavaFX
+and even Eclipse RCP apps as well.
+
+### Relation to JSR-330
+
+A half year before the CDI specification became final, other communities 
+(Spring and guice) had begun an effort to specify the basics of injection as 
+
+> “JSR-330: Dependency Injection for Java” (nicknamed “AtInject”). 
+
+Considering that it did not make sense to provide a new dependency injection container 
+without collaborating on the actual injection API, the AtInject and CDI expert groups 
+worked closely together to ensure a common solution across dependency injection frameworks. 
+
+As a result, CDI uses the annotations from the AtInject specification, 
+meaning that every CDI implementation fully implements the AtInject specification, 
+just like Guice and Spring. 
+
+CDI and AtInject are both included in Java Enterprise Edition 6 (JSR-316) 
+and thus nowadays an integral part of almost every Java Enterprise Edition server.
+
+
+## CDI features
+
+Before we go on to dive into some code, let’s take a quick look at some key CDI features:
+
+- Type Safety: Instead of injecting objects by a (string) name, 
+CDI uses the Java type to resolve injections. When the type is not sufficient, 
+a Qualifier annotation can be used. This allows the compiler to easily detect errors, 
+and provides easy refactoring.
+    
+- POJOs: Almost every Java object can be injected by CDI! 
+This includes EJBs, JNDI resources, Persistence Units and Persistence Contexts, 
+as well as any object which previously would have been created by a factory method.
+    
+- Extensibility: Every CDI container can enhance its functionality 
+by using portable “Extensions”. The attribute “portable” means that 
+those CDI Extensions can run on every CDI container and Java EE 6 server, 
+no matter which vendor. This is accomplished by a well-specified 
+SPI (Service Provider Interface) which is part of the JSR-299 specification.
+   
+- Interceptors: It has never been easier to write your own Interceptors. 
+Because of the portable behaviour of JSR-299, they now also run on every 
+EE 6-certified server and on all standalone CDI containers.
+    
+- Decorators: These allow to dynamically extend existing interface 
+implementations with business aspects.
+    
+- Events: CDI specifies a type-safe mechanism to send 
+and receive events with loose coupling.
+    
+- Unified EL integration: EL-2.2 opens a new horizon 
+in regard of flexibility and functionality. 
+CDI provides out-of-the-box support for it!
 
 
-TODO
-- where does OWB differ from the CDI-1.0 spec
-- what is the default EL version used in OWB
-- how can I provide own plugins if there is a new spec part (e.g EL-3.0) I like to support