deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rafab...@apache.org
Subject [1/4] DELTASPIKE-716 - Migration from Markdown to Asciidoc
Date Tue, 16 Sep 2014 19:52:31 GMT
Repository: deltaspike
Updated Branches:
  refs/heads/master 90be5430d -> d8d70fe9f


http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.ad
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.ad b/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.ad
deleted file mode 100644
index c895ca8..0000000
--- a/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.ad
+++ /dev/null
@@ -1,84 +0,0 @@
-= DeltaSpike Release Notes v1.0.2
-
-:toc:
-
-== Announcement
-
-The DeltaSpike team is proud to announce the release of v1.0.2.  See http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/ANNOUNCE-Release-of-Apache-DeltaSpike-1-0-2-td4658671.html[our release announcement email^] for additional information.
-
-Please read our http://deltaspike.apache.org/documentation.html#getting-started[setup guide^] to add DeltaSpike to your application.
-
-== Highlights
-
-=== Code Changes
-
-  - Improvements in CDI Container Control module, in a few scenarios you could generate `NullPointerExceptions` in case of bad configuration
-  - Added a platform inspecific Servlet Listener for container control in embedded servlet runtimes
-  - Performance improvements in our JSF module
-    - Re-use of StringBuilder for ClientWindow generation
-    - Re-use of Maps for actionUrls
-  - When shutting down via `CdiContainer.shutdown` it will attempt to stop all contexts for you
-  - Improvements in JSF and Security integration, including
-    - Removed duplicate handling of exceptions
-    - Guarding against cases when `FacesContext` is null
-  - The data module now includes valid OSGi headers
-
-=== Documentation Changes
-
-Several important documentation changes went in as well
-
-  - Fix the Bean Validation module's package name when specifying the `ConstraintValidatorFactory`
-  - Document how to handle prevention of double form submission
-
-== Credits & Thanks
-
-  - Thanks to all those that contributed via https://www.openhub.net/p/DeltaSpike/contributors?query=&sort=latest_commit[OpenHub^]
-  - Thanks to those who reviewed and http://markmail.org/message/uvq62i4iioapkto2[voted^] on the release
-
-== Full Release Notes
-++++
-<h3>        Bug
-</h3>
-<ul>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-637'>DELTASPIKE-637</a>] -         duplicated handling of AccessDeniedException
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-672'>DELTASPIKE-672</a>] -         Wrong Bean Validation artifactId on documentation
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-679'>DELTASPIKE-679</a>] -         NPE in BeanManagerProvider if parentClassLoader is null
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-681'>DELTASPIKE-681</a>] -         Handling AccessDeniedException will run the secured method
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-684'>DELTASPIKE-684</a>] -         No OSGi headers in deltaspike-partial-bean-module-api
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-685'>DELTASPIKE-685</a>] -         Guard against null FacesContext in Exception Handler Bridge
-    </li>
-</ul>
-
-<h3>        Improvement
-</h3>
-<ul>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-506'>DELTASPIKE-506</a>] -         [perf] use a shared StringBuilder
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-509'>DELTASPIKE-509</a>] -         [perf] cache map in DefaultClientWindow#getQueryURLParameters
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-653'>DELTASPIKE-653</a>] -         Provide a platform inspecific servlet listener
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-665'>DELTASPIKE-665</a>] -         Add utility method to always get new context control.
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-666'>DELTASPIKE-666</a>] -         Improve BeanManager consistency
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-669'>DELTASPIKE-669</a>] -         Try to shutdown contexts when shutting down container
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-676'>DELTASPIKE-676</a>] -         ServletContext is available for injection before EventBridgeContextListener
-    </li>
-</ul>
-
-<h3>        Task
-</h3>
-<ul>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-641'>DELTASPIKE-641</a>] -         Document prevent double submit feature
-    </li>
-    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-689'>DELTASPIKE-689</a>] -         release notes for v1.0.2
-    </li>
-</ul>
-++++
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.adoc b/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.adoc
new file mode 100644
index 0000000..234cd69
--- /dev/null
+++ b/documentation/src/main/asciidoc/releasenotes/deltaspike_1.0.2.adoc
@@ -0,0 +1,84 @@
+= DeltaSpike Release Notes v1.0.2
+
+:toc:
+
+== Announcement
+
+The DeltaSpike team is proud to announce the release of v1.0.2.  See http://apache-deltaspike-incubator-discussions.2316169.n4.nabble.com/ANNOUNCE-Release-of-Apache-DeltaSpike-1-0-2-td4658671.html[our release announcement email^] for additional information.
+
+Please read our <<index.adoc#_getting_started,setup guide>> to add DeltaSpike to your application.
+
+== Highlights
+
+=== Code Changes
+
+  - Improvements in CDI Container Control module, in a few scenarios you could generate `NullPointerExceptions` in case of bad configuration
+  - Added a platform inspecific Servlet Listener for container control in embedded servlet runtimes
+  - Performance improvements in our JSF module
+    - Re-use of StringBuilder for ClientWindow generation
+    - Re-use of Maps for actionUrls
+  - When shutting down via `CdiContainer.shutdown` it will attempt to stop all contexts for you
+  - Improvements in JSF and Security integration, including
+    - Removed duplicate handling of exceptions
+    - Guarding against cases when `FacesContext` is null
+  - The data module now includes valid OSGi headers
+
+=== Documentation Changes
+
+Several important documentation changes went in as well
+
+  - Fix the Bean Validation module's package name when specifying the `ConstraintValidatorFactory`
+  - Document how to handle prevention of double form submission
+
+== Credits & Thanks
+
+  - Thanks to all those that contributed via https://www.openhub.net/p/DeltaSpike/contributors?query=&sort=latest_commit[OpenHub^]
+  - Thanks to those who reviewed and http://markmail.org/message/uvq62i4iioapkto2[voted^] on the release
+
+== Full Release Notes
+++++
+<h3>        Bug
+</h3>
+<ul>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-637'>DELTASPIKE-637</a>] -         duplicated handling of AccessDeniedException
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-672'>DELTASPIKE-672</a>] -         Wrong Bean Validation artifactId on documentation
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-679'>DELTASPIKE-679</a>] -         NPE in BeanManagerProvider if parentClassLoader is null
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-681'>DELTASPIKE-681</a>] -         Handling AccessDeniedException will run the secured method
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-684'>DELTASPIKE-684</a>] -         No OSGi headers in deltaspike-partial-bean-module-api
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-685'>DELTASPIKE-685</a>] -         Guard against null FacesContext in Exception Handler Bridge
+    </li>
+</ul>
+
+<h3>        Improvement
+</h3>
+<ul>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-506'>DELTASPIKE-506</a>] -         [perf] use a shared StringBuilder
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-509'>DELTASPIKE-509</a>] -         [perf] cache map in DefaultClientWindow#getQueryURLParameters
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-653'>DELTASPIKE-653</a>] -         Provide a platform inspecific servlet listener
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-665'>DELTASPIKE-665</a>] -         Add utility method to always get new context control.
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-666'>DELTASPIKE-666</a>] -         Improve BeanManager consistency
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-669'>DELTASPIKE-669</a>] -         Try to shutdown contexts when shutting down container
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-676'>DELTASPIKE-676</a>] -         ServletContext is available for injection before EventBridgeContextListener
+    </li>
+</ul>
+
+<h3>        Task
+</h3>
+<ul>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-641'>DELTASPIKE-641</a>] -         Document prevent double submit feature
+    </li>
+    <li>[<a href='https://issues.apache.org/jira/browse/DELTASPIKE-689'>DELTASPIKE-689</a>] -         release notes for v1.0.2
+    </li>
+</ul>
+++++
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/scheduler.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/scheduler.adoc b/documentation/src/main/asciidoc/scheduler.adoc
new file mode 100644
index 0000000..586357b
--- /dev/null
+++ b/documentation/src/main/asciidoc/scheduler.adoc
@@ -0,0 +1,145 @@
+= Scheduler Module
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+[TOC]
+
+== Intro
+
+This module provides a simple integration with Quartz v2 (per default)
+or any other scheduler which supports cron-expressions for job-classes.
+
+
+== External Dependencies
+
+If you would like to use the default-integration with quartz (which is
+optional), you have to add quartz 2.x.
+
+[source,xml]
+-------------------------------------------
+<dependency>
+    <groupId>org.quartz-scheduler</groupId>
+    <artifactId>quartz</artifactId>
+    <version>2.2.1</version>
+</dependency>
+-------------------------------------------
+
+
+== @Scheduled
+
+Just annotate your Quartz-Jobs with `@Scheduled` and they will get
+picked up and passed to the scheduler automatically (during the
+bootstrapping process).
+
+[source,java]
+---------------------------------------------------------------------------------
+@Scheduled(cronExpression = "0 0/10 * * * ?")
+public class CdiAwareQuartzJob implements org.quartz.Job
+{
+    @Inject
+    private MyService service;
+
+    @Override
+    public void execute(JobExecutionContext context) throws JobExecutionException
+    {
+        //...
+    }
+}
+---------------------------------------------------------------------------------
+
+In such Quartz-jobs CDI based dependency-injection is enabled.
+Furthermore, the request- and session-scope get started (and stopped)
+per job-execution. Therefore, the container-control module (of
+DeltaSpike) is required. That can be controlled via
+`@Scheduled#startScopes` (possible values: all scopes supported by the
+container-control module as well as `{}` for 'no scopes').
+
+With 'false' for `@Scheduled#onStartup` it's even possible to
+schedule/install jobs dynamically - e.g.:
+
+[source,java]
+-------------------------------------------------------------------------------------
+@ApplicationScoped
+public class ProjectStageAwareSchedulerController
+{
+    @Inject
+    private Scheduler<Job> jobScheduler;
+
+    @Inject
+    private ProjectStage projectStage; 
+
+    public void registerJobs()
+    {
+        if (ProjectStage.Production.equals(this.projectStage))
+        {
+            //see 'false' for @Scheduled#onStartup
+            this.jobScheduler.scheduleJob(ManualCdiAwareQuartzJob.class);
+        }
+    }
+
+    @Scheduled(cronExpression = "0 0/10 * * * ?", onStartup = false)
+    public class ManualCdiAwareQuartzJob implements org.quartz.Job
+    {
+        @Inject
+        private MyService service;
+ 
+        @Override
+        public void execute(JobExecutionContext context) throws JobExecutionException
+        {
+            //...
+        }
+    }
+}
+-------------------------------------------------------------------------------------
+
+== Manual Scheduler Control
+
+This SPI allows to control the scheduler (or integrate any other
+compatible scheduler as an alternative to Quartz2)
+
+Via std. injection like
+
+[source,java]
+------------------------------------
+@Inject
+private Scheduler<Job> jobScheduler;
+------------------------------------
+
+it's possible to manually start/stop the scheduler,
+pause/resume/interrupt/check scheduled jobs, register jobs manually or
+start a job once (without registering it permanently).
+
+**Attention**:
+
+With some versions of Weld you have to use
+
+[source,java]
+------------------------------------------------------------------
+public class QuartzSchedulerProducer
+{
+    @Produces
+    @ApplicationScoped
+    protected Scheduler<Job> produceScheduler(Scheduler scheduler)
+    {
+        return scheduler;
+    }
+}
+------------------------------------------------------------------
+
+or
+
+[source,xml]
+-----------------------------------------------------------------------------
+<alternatives>
+  <class>org.apache.deltaspike.scheduler.impl.QuartzSchedulerProducer</class>
+</alternatives>
+-----------------------------------------------------------------------------
+
+to use a typed injection-point. Otherwise the deployment will fail.
+
+== Custom Scheduler
+
+It's possible to replace the default integration with Quartz. Any other
+scheduler which supports cron-expressions for job-classes can be used.
+Please have a look at `org.apache.deltaspike.test.scheduler.custom` for
+further details.

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/security.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/security.adoc b/documentation/src/main/asciidoc/security.adoc
new file mode 100644
index 0000000..6d8a515
--- /dev/null
+++ b/documentation/src/main/asciidoc/security.adoc
@@ -0,0 +1,531 @@
+= DeltaSpike Security Module
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+[TOC]
+
+== Hint
+
+If you are using features described by this page and the CDI
+container you are using is Weld (or OpenWebBeans in BDA mode), you have
+to enable the security interceptor in your beans.xml file:
+
+[source,xml]
+----------------------------------------------------------------------------------------
+<beans>
+    <interceptors>
+        <class>org.apache.deltaspike.security.impl.extension.SecurityInterceptor</class>
+    </interceptors>
+</beans>
+----------------------------------------------------------------------------------------
+
+
+SecurityBinding for class and method invocations
+------------------------------------------------
+
+This feature of the security module functions by intercepting method
+calls, and performing a security check before invocation is allowed to
+proceed.
+
+In order to use the DeltaSpike security module, you must first have
+installed the proper dependencies into your POM file. Once this is
+complete, you may proceed to create a security parameter binding
+annotation. This is what we will use to add security behavior to our
+business classes and methods.
+
+Create the SecurityBinding:
+
+[source,java]
+-----------------------------------------
+@Retention(value = RUNTIME)
+@Target({TYPE, METHOD})
+@Documented
+@SecurityBindingType
+public @interface CustomSecurityBinding {
+}
+-----------------------------------------
+
+Next, we must define an Authorizer class to implement behavior for our
+custom SecurityBindingType. This class is simply a CDI bean which
+declares a @Secures method, qualified with the security binding
+annotation we created in the first step.
+
+This method has access to the InvocationContext of the method call, so
+if we need to access parameter arguments, we can do so using the given
+context. Note that we may also inject other beans into the parameter
+list of our @Secures method.
+
+Create the Authorizer:
+
+[source,java]
+---------------------------------------------------------------------------------------------------------------------------------
+@ApplicationScoped
+public class CustomAuthorizer
+{
+    @Secures
+    @CustomSecurityBinding
+    public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, @LoggedIn User user) throws Exception
+    {
+        return user.isLoggedIn(); // perform security check
+    }
+}
+---------------------------------------------------------------------------------------------------------------------------------
+
+We can then use our new annotation to secure business or bean methods.
+This binding annotation may be placed on the entire class (securing all
+methods,) or on individual methods that you wish to secure.
+
+Secure a bean method:
+
+[source,java]
+----------------------------------------
+@ApplicationScoped
+public class SecuredBean1
+{
+    @CustomSecurityBinding
+    public void doSomething(Thing thing)
+    {
+        thing.doSomething();
+    }
+}
+----------------------------------------
+
+Next, we may access parameter values from the method invocation directly
+in our authorizer bean by creating custom @SecurityParameterBinding
+types; this is a simple step once we have completed the work above:
+
+Create a parameter binding annotation:
+
+[source,java]
+--------------------------------
+@Retention(value = RUNTIME)
+@Target({PARAMETER})
+@Documented
+@SecurityParameterBinding
+public @interface CurrentThing {
+}
+--------------------------------
+
+Now, when a secured method is invoked, we can inject actual parameter
+values as arguments into our authorizer method, providing domain-level
+security in our applications:
+
+Update the Authorizer to use parameter binding:
+
+[source,java]
+------------------------------------------------------------------------------------------------------------------------------------------------------------
+@ApplicationScoped
+public class CustomAuthorizer
+{
+    @Secures
+    @CustomSecurityBinding
+    public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, @LoggedIn User user, @CurrentThing Thing thing) throws Exception
+    {
+        return thing.hasMember(user); // perform security check against our method parameter
+    }
+}
+------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+Note that our business method must also be annotated.
+
+Complete the parameter binding:
+
+[source,java]
+------------------------------------------------------
+@ApplicationScoped
+public class SecuredBean1
+{
+    @CustomSecurityBinding
+    public void doSomething(@CurrentThing Thing thing)
+    {
+        thing.doSomething();
+    }
+}
+------------------------------------------------------
+
+Our method is now secured, and we are able to use given parameter values
+as part of our security authorizer!
+
+There may be cases where you may want to base your authorization logic
+on the result of the secured method and do the security check after the
+method invocation. Just use the same security binding type for that
+case:
+
+[source,java]
+----------------------------------
+@ApplicationScoped
+public class SecuredBean1
+{
+    @CustomSecurityBinding
+    public Thing loadSomething()
+    {
+        return thingLoader.load();
+    }
+}
+----------------------------------
+
+Now you need to access the return value in the authorizer method. You
+can inject it using the @SecuredReturn annotation. Update the Authorizer
+to use a secured return value:
+
+[source,java]
+---------------------------------------------------------------------------------------------------
+@ApplicationScoped
+public class CustomAuthorizer
+{
+    @Secures
+    @CustomSecurityBinding
+    public boolean doSecuredCheck(@SecuredReturn Thing thing, @LoggedIn User user) throws Exception
+    {
+        return thing.hasMember(user); // perform security check against the return value
+}
+---------------------------------------------------------------------------------------------------
+
+Now the authorization will take place after the method invocation using
+the return value of the business method.
+
+Complete the parameter binding:
+
+[source,java]
+------------------------------------------------------
+@ApplicationScoped
+public class SecuredBean1
+{
+    @CustomSecurityBinding
+    public void doSomething(@CurrentThing Thing thing)
+    {
+        thing.doSomething();
+    }
+}
+------------------------------------------------------
+
+Our method is now secured, and we are able to use given parameter values
+as part of our security authorizer!
+
+
+== Integrating 3rd party security frameworks
+
+
+=== @Secured
+
+`@Secured` is build on `@SecurityBindingType` and a very simple
+alternative to the rest of the security module. It's a basic hook to
+integrate a custom security concept, 3rd party frameworks,... . It
+doesn't provide a full blown security concept like the rest of the
+security module, but other DeltaSpike modules ensure that the security
+concepts are integrated properly (e.g. correct behaviour within custom
+scope implementations,...). It just allows to integrate other security
+frameworks easily.
+
+(In MyFaces CODI it was originally a CDI interceptor. This part changed
+a bit, because between the interceptor and `@Secured` is the
+`@SecurityBindingType` concept which triggers `@Secured` as on possible
+approach. Therefore the basic behaviour remains the same and you can
+think about it like an interceptor.)
+
+Securing all intercepted methods of a CDI bean:
+
+[source,java]
+-----------------------------------------
+//...
+@Secured(CustomAccessDecisionVoter.class)
+public class SecuredBean
+{
+    //...
+}
+-----------------------------------------
+
+or
+
+Securing specific methods:
+
+[source,java]
+---------------------------------------------
+//...
+public class SecuredBean
+{
+    @Secured(CustomAccessDecisionVoter.class)
+    public String getResult()
+    {
+        //...
+    }
+}
+---------------------------------------------
+
+=== AccessDecisionVoter
+
+This interface is (besides the `Secured` annotation) the most important
+part of the concept. Both artifact types are also the only required
+parts:
+
+[source,java]
+--------------------------------------------------------------------------------------------------------
+public class CustomAccessDecisionVoter implements AccessDecisionVoter
+{
+    @Override
+    public Set<SecurityViolation> checkPermission(AccessDecisionVoterContext accessDecisionVoterContext)
+    {
+        Method method = accessDecisionVoterContext.<InvocationContext>getSource().getMethod();
+
+        //...
+    }
+}
+--------------------------------------------------------------------------------------------------------
+
+[TODO] hint about the changed parameter/s
+
+=== SecurityViolation
+
+In case of a detected violation a `SecurityViolation` has to be added to
+the result returned by the `AccessDecisionVoter`.
+
+=== AbstractAccessDecisionVoter
+
+You can also implement the abstract class `AbstractAccessDecisionVoter`.
+This is a convenience class which allows an easier usage:
+
+Example: :::java public class CustomAccessDecisionVoter extends
+AbstractAccessDecisionVoter \{
+
+[source,java]
+-----------------------------------------------------------------------------------------
+    @Override
+    protected void checkPermission(AccessDecisionVoterContext accessDecisionVoterContext,
+            Set<SecurityViolation> violations)
+    {
+        // check for violations
+        violations.add(newSecurityViolation("access not allowed due to ..."));
+    }
+}
+-----------------------------------------------------------------------------------------
+
+
+=== @Secured and Stereotypes with custom Meta-data
+
+If there are multiple `AccessDecisionVoter` and maybe in different
+constellations, it's easier to provide an expressive CDI stereotypes for
+it. Later on that also allows to change the behaviour in a central
+place.
+
+Stereotype support of @Secured:
+
+[source,java]
+-------------------------------------------
+@Named
+@Admin
+public class MyBean implements Serializable
+{
+  //...
+}
+
+//...
+@Stereotype
+@Secured(RoleAccessDecisionVoter.class)
+public @interface Admin
+{
+}
+-------------------------------------------
+
+Furthermore, it's possible to provide custom meta-data easily.
+
+Stereotype of @Secured with custom meta-data:
+
+[source,java]
+------------------------------------------------------------------------------------------
+@Named
+@Admin(securityLevel=3)
+public class MyBean implements Serializable
+{
+  //...
+}
+
+//...
+@Stereotype
+@Secured(RoleAccessDecisionVoter.class)
+public @interface Admin
+{
+  int securityLevel();
+}
+
+@ApplicationScoped
+public class RoleAccessDecisionVoter implements AccessDecisionVoter
+{
+    private static final long serialVersionUID = -8007511215776345835L;
+
+    public Set<SecurityViolation> checkPermission(AccessDecisionVoterContext voterContext)
+    {
+        Admin admin = voterContext.getMetaDataFor(Admin.class.getName(), Admin.class);
+        int level = admin.securityLevel();
+        //...
+    }
+}
+------------------------------------------------------------------------------------------
+
+== Making intitially requested and secured page available for redirect after login
+
+DeltaSpike can be combined with pure CDI or with any other security
+frameworks (like PicketLink) to track the denied page and make it
+available after user logs in.
+
+
+=== CDI Implementation to redirect the login to the first denied page
+
+Your LoginService will fire a custom `UserLoggedInEvent`
+
+[source,java]
+------------------------------------------------------------
+public class LoginService implements Serializable {
+
+    @Inject
+    private Event<UserLoggedInEvent> userLoggedInEvent;
+
+    public Usuario login(String username, char[] password) {
+        //do the loggin process
+        userLoggedInEvent.fire(new UserLoggedInEvent());
+    }
+
+}
+------------------------------------------------------------
+
+Use @SessionScoped or @WindowScoped for AdminAccessDecisionVoter and
+store the denied page on your own.
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------------------------------------------
+@SessionScoped //or @WindowScoped
+public class AdminAccessDecisionVoter extends AbstractAccessDecisionVoter {
+
+    @Inject
+    private ViewConfigResolver viewConfigResolver;
+
+    private Class<? extends ViewConfig> deniedPage = Pages.Home.class;
+
+    @Override
+    protected void checkPermission(AccessDecisionVoterContext context, Set<SecurityViolation> violations) {
+        if(loggedIn) {
+            //...
+        } else {
+            violations.add(/*...*/);
+            deniedPage = viewConfigResolver.getViewConfigDescriptor(FacesContext.getCurrentInstance().getViewRoot().getViewId()).getConfigClass();
+        }
+    }
+
+    public Class<? extends ViewConfig> getDeniedPage() {
+        try {
+            return deniedPage;
+        } finally {
+            deniedPage = Pages.Home.class;
+        }
+    }
+}
+--------------------------------------------------------------------------------------------------------------------------------------------------
+
+And in AuthenticationListener you inject AdminAccessDecisionVoter
+
+[source,java]
+----------------------------------------------------------------------------------------
+public class AuthenticationListener {
+
+    @Inject
+    private ViewNavigationHandler viewNavigationHandler;
+
+    @Inject
+    private AdminAccessDecisionVoter adminAccessDecisionVoter;
+
+    public void handleLoggedIn(@Observes UserLoggedInEvent event) {
+        this.viewNavigationHandler.navigateTo(adminAccessDecisionVoter.getDeniedPage());
+    }
+
+}
+----------------------------------------------------------------------------------------
+
+=== PicketLink Implementation to redirect the login to the first denied page
+
+Once that PicketLink handles the authentication for you, you only need
+to store the denied page and observe PicketLink `LoggedInEvent` to
+redirect you back to the denied page.
+
+Use @SessionScoped or @WindowScoped for AdminAccessDecisionVoter and
+store the denied page on your own.
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------------------------------------------
+@SessionScoped //or @WindowScoped
+public class AdminAccessDecisionVoter extends AbstractAccessDecisionVoter {
+
+    @Inject
+    private ViewConfigResolver viewConfigResolver;
+
+    private Class<? extends ViewConfig> deniedPage = Pages.Home.class;
+
+    @Override
+    protected void checkPermission(AccessDecisionVoterContext context, Set<SecurityViolation> violations) {
+
+        AuthorizationChecker authorizationChecker = BeanProvider.getContextualReference(AuthorizationChecker.class);
+        boolean loggedIn = authorizationChecker.isLoggedIn();
+
+        if(loggedIn) {
+            //...
+        } else {
+            violations.add(/*...*/);
+            deniedPage = viewConfigResolver.getViewConfigDescriptor(FacesContext.getCurrentInstance().getViewRoot().getViewId()).getConfigClass();
+        }
+    }
+
+    public Class<? extends ViewConfig> getDeniedPage() {
+        try {
+            return deniedPage;
+        } finally {
+            deniedPage = Pages.Home.class;
+        }
+    }
+}
+--------------------------------------------------------------------------------------------------------------------------------------------------
+
+And in AuthenticationListener you inject AdminAccessDecisionVoter
+
+[source,java]
+----------------------------------------------------------------------------------------
+public class AuthenticationListener {
+
+    @Inject
+    private ViewNavigationHandler viewNavigationHandler;
+
+    @Inject
+    private AdminAccessDecisionVoter adminAccessDecisionVoter;
+
+    public void handleLoggedIn(@Observes LoggedInEvent event) {
+        this.viewNavigationHandler.navigateTo(adminAccessDecisionVoter.getDeniedPage());
+    }
+
+}
+----------------------------------------------------------------------------------------
+
+== AccessDecisionVoterContext
+
+Because the `AccessDecisionVoter` can be chained,
+`AccessDecisionVoterContext` allows to get the current state as well as
+the results of the security check.
+
+There are several methods that can be useful
+
+* `getState()` - Exposes the current state : INITIAL, VOTE_IN_PROGRESS, VIOLATION_FOUND, NO_VIOLATION_FOUND
+* `getViolations()` - Exposes the found violations
+* `getSource()` - Exposes e.g. the current instance of `javax.interceptor.InvocationContext` in combination with `@Secured` used as interceptor.
+* `getMetaData()` - Exposes the found meta-data e.g. the view-config-class if `@Secured` is used in combination with type-safe view-configs
+* `getMetaDataFor(String, Class<T>)` - Exposes meta-data for the given key
+
+=== SecurityStrategy SPI
+
+The `SecurityStrategy` interface allows to provide a custom
+implementation which should be used for `@Secured`. Provide a custom
+implementation as bean-class in combination with `@Alternative` or
+`@Specializes` (or as global-alternative).
+
+In case of global-alternatives an additional config needs to be added to
+`/META-INF/apache-deltaspike.properties` - e.g.:
+
+`globalAlternatives.org.apache.deltaspike.security.spi.authorization.SecurityStrategy=mypackage.CustomSecurityStrategy`
+
+**Note**: The config for global-alternatives is following the pattern:
+globalAlternatives.`<interface-name>`=`<implementation-class-name>`

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/servlet.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/servlet.adoc b/documentation/src/main/asciidoc/servlet.adoc
new file mode 100644
index 0000000..7fe2d76
--- /dev/null
+++ b/documentation/src/main/asciidoc/servlet.adoc
@@ -0,0 +1,285 @@
+= Servlet Module
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+[TOC]
+
+== Configuration
+
+In most cases there is no need for any additional configuration beside
+adding the required dependencies to your project, because all required
+listeners and filters are automatically registered in the container.
+
+However there are certain situations in which you will have to manually
+register the listeners and filters in your `web.xml`:
+
+* Your container doesn't support Servlet 3.0 or newer.
+* You have set `metadata-complete=true` in your `web.xml`.
+* You packaged the servlet module in the `lib` directory of an EAR archive.
+
+In these cases you will have to add the following section manually to
+your `web.xml`:
+
+[source,xml]
+-------------------------------------------------------------------------------------------------------------
+<listener>
+    <display-name>EventBridgeContextListener</display-name>
+    <listener-class>org.apache.deltaspike.servlet.impl.event.EventBridgeContextListener</listener-class>
+</listener>
+
+<listener>
+    <display-name>EventBridgeSessionListener</display-name>
+    <listener-class>org.apache.deltaspike.servlet.impl.event.EventBridgeSessionListener</listener-class>
+</listener>
+
+<listener>
+    <display-name>ServletContextHolderListener</display-name>
+    <listener-class>org.apache.deltaspike.servlet.impl.produce.ServletContextHolderListener</listener-class>
+</listener>
+
+<listener>
+    <display-name>RequestResponseHolderListener</display-name>
+    <listener-class>org.apache.deltaspike.servlet.impl.produce.RequestResponseHolderListener</listener-class>
+</listener>
+
+<filter>
+    <display-name>RequestResponseHolderFilter</display-name>
+    <filter-name>RequestResponseHolderFilter</filter-name>
+    <filter-class>org.apache.deltaspike.servlet.impl.produce.RequestResponseHolderFilter</filter-class>
+</filter>
+<filter-mapping>
+    <filter-name>RequestResponseHolderFilter</filter-name>
+    <url-pattern>/*</url-pattern>
+</filter-mapping>
+
+<filter>
+    <display-name>EventBridgeFilter</display-name>
+    <filter-name>EventBridgeFilter</filter-name>
+    <filter-class>org.apache.deltaspike.servlet.impl.event.EventBridgeFilter</filter-class>
+</filter>
+<filter-mapping>
+    <filter-name>EventBridgeFilter</filter-name>
+    <url-pattern>/*</url-pattern>
+</filter-mapping>
+-------------------------------------------------------------------------------------------------------------
+
+
+== Injectable Servlet objects
+
+The DeltaSpike Servlet module contains producers for many objects of a
+Servlet environment. All produces are using the special qualifier
+`@DeltaSpike` for compatibility with CDI 1.1, which supports the
+injection of some Servlet objects out of the box.
+
+The following code shows the general injection pattern to use for all objects.
+
+[source,java]
+------------------------------------
+@Inject @DeltaSpike
+private ServletObject servletObject;
+------------------------------------
+
+
+=== ServletContext
+
+The `ServletContext` is made available in the application scope. It can
+be injected into any CDI bean like this:
+
+[source,java]
+--------------------------------------
+@Inject @DeltaSpike
+private ServletContext servletContext;
+--------------------------------------
+
+
+ServletRequest / HttpServletRequest
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `ServletRequest` is made available in the request scope. The current
+request can be injected into a CDI bean like this:
+
+[source,java]
+-------------------------------
+@Inject @DeltaSpike
+private ServletRequest request;
+-------------------------------
+
+In case of HTTP requests you can also inject the `HttpServletRequest`:
+
+[source,java]
+-----------------------------------
+@Inject @DeltaSpike
+private HttpServletRequest request;
+-----------------------------------
+
+
+=== ServletResponse / HttpServletResponse
+
+The `ServletResponse` is made available in the request scope. The
+current response can be injected into a CDI bean like this:
+
+[source,java]
+---------------------------------
+@Inject @DeltaSpike
+private ServletResponse response;
+---------------------------------
+
+In case of HTTP requests you can also inject the `HttpServletResponse`:
+
+[source,java]
+-------------------------------------
+@Inject @DeltaSpike
+private HttpServletResponse response;
+-------------------------------------
+
+
+=== HttpSession
+
+The `HttpSession` is made available in the session scope. You can inject
+the current session of a user into a CDI bean like this:
+
+[source,java]
+----------------------------
+@Inject @DeltaSpike
+private HttpSession session;
+----------------------------
+
+Please note that injecting the session this way will force the creation
+of a session.
+
+=== Principal
+
+The `Principal` is made available in the request scope. The current
+principal can be injected into a CDI bean like this:
+
+[source,java]
+----------------------------
+@Inject @DeltaSpike
+private Principal principal;
+----------------------------
+
+The `Principal` is obtained by calling `getUserPrincipal()` on the
+`HttpServletRequest`.
+
+
+== Servlet event propagation
+
+The DeltaSpike Servlet module will propagate a number of Servlet object
+lifecycle events to the CDI event bus. This allows regular CDI beans to
+observe these events and react accordingly.
+
+In most cases the event type is the object whose lifecycle is observed.
+To distinguish between construction and destruction of the corresponding
+object, DeltaSpike uses the qualifiers `@Initialized` and `@Destroyed`.
+
+The following sections will show which concrete Servlet objects are
+supported and how their lifecycle can be observed.
+
+
+=== Servlet context lifecycle events
+
+The Servlet module supports initialization and destruction events for
+the `ServletContext`. These events can for example be used to detect
+application startup or shutdown. The following code shows how these
+events can be observed:
+
+[source,java]
+-----------------------------------------------------------------------------------------
+public void onCreate(@Observes @Initialized ServletContext context) {
+    System.out.println("Initialized ServletContext: " + context.getServletContextName());
+}
+
+public void onDestroy(@Observes @Destroyed ServletContext context) {
+    System.out.println("Destroyed ServletContext: " + context.getServletContextName());
+}
+-----------------------------------------------------------------------------------------
+
+The events are emitted from a `ServletContextListener` called
+`EventBridgeContextListener`. You can disable lifecycle events for the
+`ServletContext` by deactivating the following class:
+
+-------------------------------------------------------------------
+org.apache.deltaspike.servlet.impl.event.EventBridgeContextListener
+-------------------------------------------------------------------
+
+If you manually registered the required filters and listeners, you can
+also simply remove the entry for the `EventBridgeContextListener` from
+your `web.xml` to disable the events.
+
+
+=== Request and response lifecycle events
+
+The Servlet module also supports initialization and destruction events
+for the `HttpServletRequest` and `HttpServletResponse`. These events can
+for example be used for initialization work like invoking
+`setCharacterEncoding` on the request.
+
+The following example shows how to observe lifecycle events for the
+request:
+
+[source,java]
+--------------------------------------------------------------------------------------
+public void onCreate(@Observes @Initialized HttpServletRequest request) {
+    System.out.println("Starting to process request for: " + request.getRequestURI());
+}
+
+public void onDestroy(@Observes @Destroyed HttpServletRequest request) {
+    System.out.println("Finished processing request for: " + request.getRequestURI());
+}
+--------------------------------------------------------------------------------------
+
+Observing lifecycle events for the response works the same way:
+
+[source,java]
+---------------------------------------------------------------------------
+public void onCreate(@Observes @Initialized HttpServletResponse response) {
+    System.out.println("HttpServletResponse created");
+}
+
+public void onDestroy(@Observes @Destroyed HttpServletResponse response) {
+    System.out.println("HttpServletResponse destroyed");
+}
+---------------------------------------------------------------------------
+
+All events of this category are emitted from a servlet filter called
+`EventBridgeFilter`. If you want to disable events for this category,
+just use DeltaSpike's deactivation mechanism to deactivate the following
+class:
+
+----------------------------------------------------------
+org.apache.deltaspike.servlet.impl.event.EventBridgeFilter
+----------------------------------------------------------
+
+If you manually registered the required filters and listeners you can
+also simply remove the entry for the `EventBridgeFilter` from your
+`web.xml` to disable the events.
+
+
+=== Session lifecycle events
+
+The last category of events supported by the DeltaSpike Servlet module
+are the lifecycle events for the user's HTTP session. The following
+example shows how these events can be observed from a regular CDI bean.
+
+[source,java]
+------------------------------------------------------------------
+public void onCreate(@Observes @Initialized HttpSession session) {
+    System.out.println("Session created: " + session.getId());
+}
+
+public void onDestroy(@Observes @Destroyed HttpSession session) {
+    System.out.println("Session destroyed: " + session.getId());
+}
+------------------------------------------------------------------
+
+The lifecycle events for the HTTP session are sent from a
+`HttpSessionListener` called `EventBridgeSessionListener`. To disable
+this event category, deactivate the following class:
+
+-------------------------------------------------------------------
+org.apache.deltaspike.servlet.impl.event.EventBridgeSessionListener
+-------------------------------------------------------------------
+
+If you manually registered the required filters and listeners you can
+also simply remove the entry for the `EventBridgeSessionListener` from
+your `web.xml` to disable the events.

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/source.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/source.adoc b/documentation/src/main/asciidoc/source.adoc
new file mode 100644
index 0000000..0039233
--- /dev/null
+++ b/documentation/src/main/asciidoc/source.adoc
@@ -0,0 +1,74 @@
+= Get Source and compile it
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+[TOC]
+
+== Introduction
+
+== SCM / Repository
+
+We are using GIT as a Version Control System. The official GIT
+repository of the project is available
+https://git-wip-us.apache.org/repos/asf/deltaspike.git[here].
+
+
+=== Initial 'checkout'
+
+----------------------------------------------------------------
+git clone https://git-wip-us.apache.org/repos/asf/deltaspike.git
+----------------------------------------------------------------
+
+=== Update existing clone
+
+-----------------
+git pull --rebase
+-----------------
+
+
+=== Read-only Mirrors
+
+==== GitHub-Mirror
+
+----------------------------------------------
+git clone https://github.com/apache/deltaspike
+----------------------------------------------
+
+More information can be found https://help.github.com/articles/which-remote-url-should-i-use[here].
+
+=== GIT Workflow
+
+We follow an link:../suggested-git-workflows.html[unified GIT workflow] to
+keep the commit history straight and therefore simple and clean. General
+details about GIT at Apache are available
+http://wiki.apache.org/couchdb/Git_At_Apache_Guide[here] and at
+http://git-wip-us.apache.org.
+
+*Hint:*
+
+If you are new to Git you might like to try the
+http://git.or.cz/course/svn.html[Git guide for subversion users] or have
+a look at the http://git-scm.com/book[Git community book].
+
+== Build
+
+So now you probably want to **`build the code`**. So follow the
+instructions <<build.adoc#,here>>
+
+== Tools / IDE
+
+Commits (and in the best case also patches), have to follow our
+"formatting rules". The following section provides settings for IDEs
+used by us.
+
+
+=== IntelliJ
+
+link:http://deltaspike.apache.org/resources/files/settings.jar[Attached] you can find the settings
+for formatting the source code. Import them via File | Import
+Settings...
+
+=== Eclipse
+
+For Eclipse you can use this
+link:http://deltaspike.apache.org/resources/files/deltaspike-code-conventions.xml[Code Formatter Profile]. Import it via Window | Preferences | Java | Code Style | Formatter

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/spi.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/spi.adoc b/documentation/src/main/asciidoc/spi.adoc
new file mode 100644
index 0000000..80faf81
--- /dev/null
+++ b/documentation/src/main/asciidoc/spi.adoc
@@ -0,0 +1,124 @@
+= DeltaSpike Service Provider Interface (SPI)
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+
+[TOC]
+
+
+== Introduction
+
+== Deactivatable
+
+This mechanism is only used for artifacts *like* implementations of
+(`javax.enterprise.inject.spi.Extension`) which *can't* be deactivated
+with std. CDI mechanisms.
+
+This interface is just a marker interface which is implemented by all
+pre-configured DeltaSpike artifacts which can be deactivated manually
+(e.g. to improve the performance if a part isn't needed, to provide a
+custom implementation if the default implementation isn't pluggable by
+default or to bypass an implementation which causes an issue (in this
+case please also *contact us* and we will fix it)).
+
+To deactivate a class it's required to implement `ClassDeactivator`.
+Returning 'false' or 'true' allows to de-/activate the class in
+question. Retuning null means that the current class-deactivator doesn't
+have information about the class in question and can't provide a result.
+Since `ClassDeactivator` implementations are configured with the
+low-level config of DeltaSpike, the class-deactivator with the highest
+ordinal has the final decision. DeltaSpike itself doesn't deactivate an
+implementation, however, an add-on or a 3rd party portable CDI extension
+based on DeltaSpike (Core+) can use the concept to deactivate a default
+implementation of DeltaSpike in favour of its own implementation.
+
+**Attention**: due to the ordinal feature of the low-level config
+approach it's possible that a class-deactivator with a higher ordinal,
+e.g. used in a concrete project, can re-activate a deactivated
+implementation. +
+*Please note* that you might have to deactivate the parts of the add-on
+or 3rd party CDI extension which relies on its own implementation.
+Therefore, you should **be really careful with re-activation**.) The
+implementation should be stateless because the result will be cached and
+as soon as everything is initialized the class-deactivators won't be
+used any longer.
+
+=== ClassDeactivator
+
+A class-deactivator allows to specify deactivated classes.
+
+[source,java]
+----------------------------------------------------------------------------
+//This class needs to be configured via one of the supported config sources!
+public class CustomClassDeactivator implements ClassDeactivator
+{
+    @Override
+    public Boolean isActivated(Class<? extends Deactivatable> targetClass)
+    {
+        if (targetClass.equals(MyClass.class))
+        {
+            return Boolean.FALSE;
+        }
+        return null; //no result for the given class
+    }
+}
+----------------------------------------------------------------------------
+
+A class-deactivator will be resolved from the environment via the
+default resolvers or via a custom resolver which allows to use any type
+of configuration-format. (see
+`org.apache.deltaspike.core.api.config.ConfigResolver`). The key is the
+fully qualified name of the interface
+(`org.apache.deltaspike.core.spi.activation.ClassDeactivator`).
+
+== ConfigSource
+
+[TODO]
+
+=== ConfigSourceProvider
+
+[TODO]
+
+=== BaseConfigPropertyProducer
+
+[TODO]
+
+
+== InterceptorStrategy
+
+
+[TODO]
+
+== Global Alternative
+
+There are several application servers (using CDI 1.0) which can't handle
+alternative CDI beans correctly (e.g. due to a too strict interpretation
+or a broken implementation). Therefore, DeltaSpike allows to use the
+std. `@Alternative` annotation and an additional config entry for
+DeltaSpike which allows to use the alternative implementation as a
+global alternative.
+
+*Std. CDI alternative implementation (without the required XML config)*
+
+[source,java]
+-----------------------------------------------------
+public class CustomBean
+{
+}
+
+@Alternative
+//...
+public class AlternativeCustomBean extends CustomBean
+{
+}
+-----------------------------------------------------
+
+Instead of configuring the alternative in the beans.xml, a global
+alternative needs to be configured in
+/META-INF/apache-deltaspike.properties. CDI 1.1 should fix this issue
+and migrating to it means to remove the config entry for DeltaSpike
+again and move to the std. CDI config approach.
+
+----------------------------------------------
+custom.CustomBean=custom.AlternativeCustomBean
+----------------------------------------------

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/test-control.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/test-control.adoc b/documentation/src/main/asciidoc/test-control.adoc
new file mode 100644
index 0000000..ba6cbc5
--- /dev/null
+++ b/documentation/src/main/asciidoc/test-control.adoc
@@ -0,0 +1,416 @@
+= Test-Control Module
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+[TOC]
+
+== Intro
+
+This module is available since version 0.6 and allows to write CDI based
+tests easily.
+
+
+== Setup
+
+Setup for the CDI implementation of your choice and the following
+test-dependencies:
+
+[source,xml]
+----------------------------------------------------------------
+<dependency>
+    <groupId>org.apache.deltaspike.modules</groupId>
+    <artifactId>deltaspike-test-control-module-api</artifactId>
+    <version>${ds.version}</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>org.apache.deltaspike.modules</groupId>
+    <artifactId>deltaspike-test-control-module-impl</artifactId>
+    <version>${ds.version}</version>
+    <scope>test</scope>
+</dependency>
+----------------------------------------------------------------
+
+
+=== OpenWebBeans
+
+If you are using OpenWebBeans also add the following test-dependency
+
+[source,xml]
+-----------------------------------------------------
+ <dependency>
+     <groupId>org.apache.deltaspike.cdictrl</groupId>
+     <artifactId>deltaspike-cdictrl-owb</artifactId>
+     <version>${ds.version}</version>
+     <scope>test</scope>
+ </dependency>
+-----------------------------------------------------
+
+
+=== Weld
+
+If you are using Weld also add the following test-dependency
+
+[source,xml]
+----------------------------------------------------
+<dependency>
+    <groupId>org.apache.deltaspike.cdictrl</groupId>
+    <artifactId>deltaspike-cdictrl-weld</artifactId>
+    <version>${ds.version}</version>
+    <scope>test</scope>
+</dependency>
+----------------------------------------------------
+
+
+== CdiTestRunner
+
+JUnit Test-Runner to start/stop the CDI-Container autom. (per
+test-class) and one request and session per test-method:
+
+[source,java]
+--------------------------------------------------------
+@RunWith(CdiTestRunner.class)
+public class ContainerAndInjectionControl
+{
+    @Inject
+    private ApplicationScopedBean applicationScopedBean;
+
+    @Inject
+    private SessionScopedBean sessionScopedBean;
+
+    @Inject
+    private RequestScopedBean requestScopedBean;
+
+    //test the injected beans
+}
+--------------------------------------------------------
+
+== @TestControl
+
+@TestControl allows to change the default-behavior. In the following
+case only one session for all test-methods (of the test-class) will be
+created:
+
+[source,java]
+-----------------------------------------------
+@RunWith(CdiTestRunner.class)
+@TestControl(startScopes = SessionScoped.class)
+public class CustomizedScopeHandling
+{
+    //inject beans and test them
+}
+-----------------------------------------------
+
+== CdiTestSuiteRunner
+
+JUnit Test-Suite-Runner to start/stop the CDI-Container autom. (per
+test-suite):
+
+[source,java]
+---------------------------------------
+@RunWith(CdiTestSuiteRunner.class)
+@Suite.SuiteClasses({
+    TestX.class,
+    TestY.class
+})
+public class SuiteLevelContainerControl
+{
+}
+---------------------------------------
+
+== Project-Stage Control
+
+It's possible to overrule the default-project-stage for unit-tests
+(ProjectStage.UnitTest.class):
+
+[source,java]
+---------------------------------------------------------------
+@RunWith(CdiTestRunner.class)
+@TestControl(projectStage = CustomTestStage.class)
+public class TestStageControl
+{
+    //tests here will see project-stage CustomTestStage.class
+
+    @Test
+    @TestControl(projectStage = ProjectStage.Development.class)
+    public void checkDevEnv()
+    {
+    }
+
+    //tests here will see project-stage CustomTestStage.class
+}
+---------------------------------------------------------------
+
+
+== Optional Config
+
+It's possible to set "deltaspike.testcontrol.stop_container" to "false"
+(via the std. DeltaSpike config). With that the CDI-Container will be
+started just once for all tests.
+
+
+== Hints
+
+Don't forget to add a beans.xml in the test-module (e.g.
+src/test/resources/META-INF/beans.xml).
+
+If you are using OpenWebBeans as CDI implementation and you need to test
+EJBs as well, you can use deltaspike-cdictrl-openejb +
+org.apache.openejb:openejb-core (instead of deltaspike-cdictrl-owb).
+
+
+== Optional Integrations
+
+
+=== Mock Frameworks
+
+With v0.8+ it's possible to mock CDI-Beans. Usually @Exclude (+
+project-stage) is enough, however, for some cases mocked beans might be
+easier. Therefore it's possible to create (mock-)instances manually or
+via a mocking framework and add them e.g. via `DynamicMockManager`.
+
+If you need dependency-injection in the mocked instances, you can use
+`BeanProvider.injectFields(myMockedBean);`.
+
+[source,java]
+-------------------------------------------------------------
+@RunWith(CdiTestRunner.class)
+public class MockedRequestScopedBeanTest
+{
+    @Inject
+    private RequestScopedBean requestScopedBean;
+
+    @Inject
+    private DynamicMockManager mockManager;
+
+    @Test
+    public void manualMock()
+    {
+        mockManager.addMock(new RequestScopedBean() {
+            @Override
+            public int getCount()
+            {
+                return 7;
+            }
+        });
+
+        Assert.assertEquals(7, requestScopedBean.getCount());
+        requestScopedBean.increaseCount();
+        Assert.assertEquals(7, requestScopedBean.getCount());
+    }
+}
+
+@RequestScoped
+public class RequestScopedBean
+{
+    private int count = 0;
+
+    public int getCount()
+    {
+        return count;
+    }
+
+    public void increaseCount()
+    {
+        this.count++;
+    }
+}
+-------------------------------------------------------------
+
+Using a mocking framework makes no difference for adding the mock. E.g.
+via Mockito:
+
+[source,java]
+----------------------------------------------------------------------------------
+@RunWith(CdiTestRunner.class)
+public class MockitoMockedRequestScopedBeanTest
+{
+    @Inject
+    private RequestScopedBean requestScopedBean;
+
+    @Inject
+    private DynamicMockManager mockManager;
+
+    @Test
+    public void mockitoMockAsCdiBean()
+    {
+        RequestScopedBean mockedRequestScopedBean = mock(RequestScopedBean.class);
+        when(mockedRequestScopedBean.getCount()).thenReturn(7);
+        mockManager.addMock(mockedRequestScopedBean);
+
+        Assert.assertEquals(7, requestScopedBean.getCount());
+        requestScopedBean.increaseCount();
+        Assert.assertEquals(7, requestScopedBean.getCount());
+    }
+}
+----------------------------------------------------------------------------------
+
+Since CDI implementations like OpenWebBeans use a lot of optimizations,
+it's required to handle mocks for application-scoped beans differently -
+e.g.:
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------------------
+@RunWith(CdiTestRunner.class)
+public class MockedApplicationScopedBeanTest
+{
+    @Inject
+    private ApplicationScopedBean applicationScopedBean;
+
+    @BeforeClass
+    public static void init()
+    {
+        ApplicationMockManager applicationMockManager = BeanProvider.getContextualReference(ApplicationMockManager.class);
+        applicationMockManager.addMock(new MockedApplicationScopedBean());
+    }
+
+    @Test
+    public void manualMock()
+    {
+        Assert.assertEquals(14, applicationScopedBean.getCount());
+        applicationScopedBean.increaseCount();
+        Assert.assertEquals(14, applicationScopedBean.getCount());
+    }
+}
+
+@ApplicationScoped
+public class ApplicationScopedBean
+{
+    private int count = 0;
+
+    public int getCount()
+    {
+        return count;
+    }
+
+    public void increaseCount()
+    {
+        this.count++;
+    }
+}
+
+@Typed() //exclude it for the cdi type-check
+public class MockedApplicationScopedBean extends ApplicationScopedBean
+{
+    @Override
+    public int getCount()
+    {
+        return 14;
+    }
+}
+--------------------------------------------------------------------------------------------------------------------------
+
+However, `ApplicationMockManager` can be used for adding all mocks, if
+they should be active for the lifetime of the CDI-container.
+
+It's also possible to mock qualified beans. Just add the
+literal-instance(s) as additional parameter(s) - e.g.:
+
+[source,java]
+-------------------------------------------------------------
+@RunWith(CdiTestRunner.class)
+public class MockedQualifiedBeanTest
+{
+    @Inject
+    @MyQualifier
+    private QualifiedBean qualifiedBean;
+
+    @Inject
+    private DynamicMockManager mockManager;
+
+    @Test
+    public void manualMockWithQualifier()
+    {
+        mockManager.addMock(new QualifiedBean() {
+            @Override
+            public int getCount()
+            {
+                return 21;
+            }
+        }, AnnotationInstanceProvider.of(MyQualifier.class));
+
+        Assert.assertEquals(21, qualifiedBean.getCount());
+        qualifiedBean.increaseCount();
+        Assert.assertEquals(21, qualifiedBean.getCount());
+    }
+}
+-------------------------------------------------------------
+
+In some cases it's needed to use `@javax.enterprise.inject.Typed`.
+Mocking such typed beans can result in an
+`AmbiguousResolutionException`. Therefore it's needed to exclude the
+mocked implementation via `@Exclude` or `@Typed()` (or a parametrized
+constructor) and specify the target-type via `@TypedMock`.
+
+=== JSF (via MyFaces-Test)
+
+add on of
+
+* org.apache.deltaspike.testcontrol.impl.jsf.MockedJsf2TestContainer
+* org.apache.deltaspike.testcontrol.impl.jsf.MockedJsfTestContainerAdapter
+* org.apache.deltaspike.testcontrol.impl.jsf.MyFacesContainerAdapter
+* org.apache.deltaspike.testcontrol.impl.jsf.MyFacesContainerPerTestMethodAdapter
+
+as content to
+
+/META-INF/services/org.apache.deltaspike.testcontrol.spi.ExternalContainer
+
+(in your config-folder for tests e.g.: test/resources)
+
+== Mixed Tests
+
+Usually you should have one kind of tests per test-module. However, if
+you need to add e.g. a test without an external-container to your
+test-module which uses external-containers, you can annotate your test
+with:
+
+[source,java]
+---------------------------------------------
+@RunWith(CdiTestRunner.class)
+@TestControl(startExternalContainers = false)
+public class JsfContainerTest
+{
+    //...
+}
+---------------------------------------------
+
+
+== Known Restrictions
+
+=== Liquibase
+
+Liquibase invokes `#toString` in a `AfterDeploymentValidation` observer.
+*that isn't portable* and therefore you have to deactivate the
+mocking-support via:
+
+[source,java]
+----------------------------------------------------------------------------------------------------------
+public class LiquibaseAwareClassDeactivator implements ClassDeactivator {
+    @Override
+    public Boolean isActivated(Class<? extends Deactivatable> targetClass) {
+        return !"org.apache.deltaspike.testcontrol.impl.mock.MockExtension".equals(targetClass.getName());
+    }
+}
+----------------------------------------------------------------------------------------------------------
+
+and add `LiquibaseAwareClassDeactivator` to `/META-INF/apache-deltaspike.properties` - e.g.:
+
+---------------------------------------------------------------------------------------------------
+org.apache.deltaspike.core.spi.activation.ClassDeactivator=myPackage.LiquibaseAwareClassDeactivator
+---------------------------------------------------------------------------------------------------
+
+Further details are available at deactivatable.
+
+
+== SPI
+
+
+=== ExternalContainer
+
+org.apache.deltaspike.testcontrol.spi.ExternalContainer allows to
+integrate containers which get started after the CDI container.
+Currently DeltaSpike provides:
+
+* MockedJsf2TestContainer (integration with MyFaces-Test)
+
+[TODO]

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/template/document.html.erb
----------------------------------------------------------------------
diff --git a/documentation/src/main/template/document.html.erb b/documentation/src/main/template/document.html.erb
index 781b518..5b7343e 100644
--- a/documentation/src/main/template/document.html.erb
+++ b/documentation/src/main/template/document.html.erb
@@ -17,7 +17,7 @@
 <link href="http://deltaspike.apache.org/resources/css/bootstrap-responsive.css" rel="stylesheet">
 
 <style type="text/css">
-<%= ::Asciidoctor::HTML5.default_coderay_stylesheet %>
+<%= ::Asciidoctor::Stylesheets.instance.coderay_stylesheet_data %>
 body {
 	padding-top: 60px;
 	padding-bottom: 40px;
@@ -82,7 +82,7 @@ body {
                 </div>
 
 				<div id="toc" class="<%= attr 'toc-class', 'toc' %>">
-       	 		<%= ::Asciidoctor::HTML5::DocumentTemplate.outline(self, (attr :toclevels, 3).to_i) %>
+       	 		<%= converter.convert_with_options @document, 'outline', :toclevels => 3  %>
        	 		<hr>	
        	 		
 				<%= document.content %>
@@ -91,10 +91,8 @@ body {
 			<hr>
 
 			<footer>
-				<p>Copyright © 2011-2014 The Apache Software Foundation,
-					Licensed under the Apache License, Version 2.0.</p>
-				<p>Apache and the Apache feather logo are trademarks of The
-					Apache Software Foundation.</p>
+				<p>Copyright © 2011-2014 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.</p>
+				<p>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
 			</footer>
 
 		</div>


Mime
View raw message