deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rsme...@apache.org
Subject [1/2] deltaspike git commit: DELTASPIKE-898 Make documentation structure more comprehensible
Date Tue, 12 May 2015 18:42:24 GMT
Repository: deltaspike
Updated Branches:
  refs/heads/master 1c828f3fd -> e67d64a24


http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/jsf.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jsf.adoc b/documentation/src/main/asciidoc/jsf.adoc
index 865877b..88a830c 100644
--- a/documentation/src/main/asciidoc/jsf.adoc
+++ b/documentation/src/main/asciidoc/jsf.adoc
@@ -8,7 +8,7 @@
 == Overview
 The JSF module provides CDI integration with JSF, with type-safe view config, multi-window handling, new scopes (WindowScoped, ViewScope, ViewAccessScoped, GroupedConversationScoped) and integration with DeltaSpike “core” messages and exception handling.
 
-== Configure Your Projects
+== Project Setup
 The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
 
 === Declare JSF Module Dependencies
@@ -43,15 +43,13 @@ Some EE6 servers cannot handle optional classes. From DeltaSpike 1.0.1, if you d
 </dependency>
 ----
 
-== Use the Module Features
-
 .Support of EAR deployments
 IMPORTANT: Before using features described by this page, please ensure that you are
 aware of
 https://issues.apache.org/jira/browse/DELTASPIKE-335[DELTASPIKE-335] and
 the corresponding impact.
 
-=== JSF Messages
+== JSF Messages
 
 DeltaSpike provides an injectable component for typesafe FacesMessages.
 
@@ -85,11 +83,11 @@ In case of a String we use it for both the summary and detail information on the
 
 If a Message is returned, we lookup the 'detail' and 'summary' categories (see `org.apache.deltaspike.core.api.message.Message#toString(String)` for creating the FacesMessage.
 
-=== Multi-Window Handling
+== Multi-Window Handling
 
-==== Background
+=== Background
 
-===== Historic Considerations
+==== Historic Considerations
 
 Until the end of the 1990s web browsers are usually single threaded and
 only had one window. But in the last years browsers supporting multiple
@@ -99,7 +97,7 @@ server side. Sadly browser windows still lack of a native windowId, thus
 maintaining web application data in @SessionScoped backing beans is
 still used in most of the cases.
 
-===== How JSF-2 Changed the World
+==== How JSF-2 Changed the World
 
 The MyFaces Orchestra community did a good summary about the various
 ways to handle multiple window support in JSF Applications. Those
@@ -110,7 +108,7 @@ requests. Due to the new JSF-2 ability to use bookmarkable URLs and deep
 links, a typical JSF-2 application contains much more GET links than we
 used to see in JSF-1, thus we have far more href links to cope with.
 
-===== Standard windowId Handling
+==== Standard windowId Handling
 
 With a classical approach we would not be able to simply add a windowId
 parameter to such links because if the user would open the link in a new
@@ -127,9 +125,9 @@ destroy their information) while rendering the page, which means this is
 not feasible as general solution.
 
 
-==== Available Modes
+=== Available Modes
 
-===== CLIENTWINDOW
+==== CLIENTWINDOW
 
 Each GET request results in an intermediate small html page which checks
 if the browser tab fits the requested windowId. When the windowId is
@@ -139,12 +137,12 @@ dsRid/windowId will be added. On the server side, the verified windowId
 will be extracted from the cookie. For POST request detection, the
 windowId will be added as hidden input to all forms.
 
-====== Advantage
+===== Advantage
 
 * Covers all edge cases
 
 
-====== Disadvantage
+===== Disadvantage
 
 * Having the windowhandler.html site rendered between requests sometimes
 leads to some 'flickering' if the destination page takes some time to
@@ -161,7 +159,7 @@ parse a request and decide upon the UserAgent or any other information
 if a client will get an intermediate page or if he gets the result page
 directly.
 
-====== Change windowhandler.html
+===== Change windowhandler.html
 
 To customize the look and feel of the windowhandler.html, you can simply
 provide a own via:
@@ -179,7 +177,7 @@ public class MyClientWindowConfig extends DefaultClientWindowConfig
 }
 -------------------------------------------------------------------
 
-===== LAZY
+==== LAZY
 
 Always appends the windowId to all, from JSF generated, URLs. On the
 first GET request without a windowId, it will generate a new windowId
@@ -191,11 +189,11 @@ it is not matching, the view will be refreshed with the right windowId in
 the URL.
 
 
-====== Advantage
+===== Advantage
 
 * No windowhandler.html / loading screen required
 
-====== Disadvantage
+===== Disadvantage
 
 * It could happen that 2 tabs will share the same windowId for 1 request
 because the `LAZY` mode will check lazily, after rendering the view, if
@@ -203,7 +201,7 @@ the windowId matches the `window.name`. Therefore it could happen that
 @ViewAccessScoped or other scopes will unintentionally be destroyed.
 
 
-====== Workflow Example
+===== Workflow Example
 
 First GET request with windowId
 
@@ -234,7 +232,7 @@ Further GET request without windowId
 from `window.name`
 
 
-===== NONE
+==== NONE
 
 Any window or browser tab detection will be disabled for the current
 request. Scopes like @WindowScoped, @GroupedConversationScoped or
@@ -243,22 +241,22 @@ current request does not support Javascript or if the user agent is a
 bot/crawler.
 
 
-===== DELEGATED
+==== DELEGATED
 
 Delegates the complete window handling to the new JSF 2.2 ClientWindow
 (if not disabled).
 
 
-===== CUSTOM
+==== CUSTOM
 
 Enables to use an complete own
 `org.apache.deltaspike.jsf.spi.scope.window.ClientWindow`
 implementation.
 
 
-==== Configuration
+=== Configuration
 
-===== ds:windowId
+==== ds:windowId
 
 The component `ds:windowId`
 (`xmlns:ds="http://deltaspike.apache.org/jsf"`) is required to enable
@@ -268,7 +266,7 @@ mode. The best way, to apply it for all views, is to add this component
 to all of your templates.
 
 
-===== ds:disableClientWindow
+==== ds:disableClientWindow
 
 Similiar to JSF 2.2' `disableClientWindow` attribute,
 `ds:disableClientWindow` provides the ability to disable the rendering
@@ -282,7 +280,7 @@ of the windowId to all links of all child components:
 <h:link value="Link with windowId" outcome="target.xhtml"/>
 -------------------------------------------------------------------
 
-===== Number of Active Windows
+==== Number of Active Windows
 
 By default, DeltaSpike allows `1024` active windows per session. Anyway, this number is reduced inside this JSF module to `64` for JSF applications. Once that the limit number of active windows is reached, DeltaSpike will drop the oldest active window.
 
@@ -304,7 +302,7 @@ public class MyClientWindowConfig extends DefaultClientWindowConfig
 }
 -----------------------------------------------------------------------------------
 
-===== Switch Mode
+==== Switch Mode
 
 To switch the mode, just provide a
 `org.apache.deltaspike.jsf.api.config.JsfModuleConfig` and overwrite
@@ -324,7 +322,7 @@ public class MyJsfModuleConfig extends JsfModuleConfig
 ---------------------------------------------------------------------------
 
 
-===== Provide a Custom ClientWindow
+==== Provide a Custom ClientWindow
 
 If you would like to provide an custom
 `org.apache.deltaspike.jsf.spi.scope.window.ClientWindow`
@@ -355,16 +353,16 @@ public class MyJsfModuleConfig extends JsfModuleConfig
 }
 ---------------------------------------------------------------------------
 
-==== Based Scopes
+=== Based Scopes
 
 * @WindowScoped
 * @ViewAccessScoped
 * @GroupedConversationScoped
 
 
-=== Scopes
+== Scopes
 
-==== @WindowScoped
+=== @WindowScoped
 
 The window-scope is like a session per window. That means that the data
 is bound to a window/tab and it not shared between windows (like the
@@ -382,7 +380,7 @@ public class PreferencesBean implements Serializable
 ----------------------------------------------------
 
 
-==== @ViewAccessScoped
+=== @ViewAccessScoped
 
 In case of conversations you have to un-scope beans manually (or they
 will be terminated automatically after a timeout). However, sometimes
@@ -411,17 +409,17 @@ separation without touching the old windowId. Otherwise a 'open in new
 tab' on a page with a @ViewAccessScoped bean might cause the termination
 (and re-initialization) of that bean.
 
-==== @GroupedConversationScoped (From DeltaSpike 0.6)
+=== @GroupedConversationScoped
 
 See (Grouped-)Conversations
 
-==== @ViewScoped
+=== @ViewScoped
 
 DeltaSpike provides an CDI context for the JSF 2.0/2.1
 @javax.faces.bean.ViewScoped. You can simply annotate your bean with
 @javax.faces.bean.ViewScoped and @Named.
 
-==== JSF 2.0 Scopes
+=== JSF 2.0 Scopes
 
 JSF 2.0 introduced new annotations as well as a new scope - the View
 Scope. CODI allows to use all the CDI mechanisms in beans annotated
@@ -439,7 +437,7 @@ All these annotations are mapped automatically. So you will not face
 issues, if you import a JSF 2 annotation instead of the corresponding
 CDI annotation.
 
-=== Integration with DeltaSpike Type-safe Messages
+== Integration with DeltaSpike Type-safe Messages
 
 You can use <<core.adoc#_messages_i18n,DeltaSpike type-safe messages>>
 with JSF to provide i18n messages and test to an JSF appplicaton.
@@ -505,9 +503,9 @@ javax.faces.component.UIInput.REQUIRED = {0}: Please enter a value
 </faces-config>
 --------------------------------------------------------------------------------------------
 
-=== Type-safe View-Configs
+== Type-safe View-Configs
 
-==== Intro
+=== Intro
 
 Type-safe view-configs are static configs which can be used in
 combination with every view-technology which is based on Java. Currently
@@ -529,7 +527,7 @@ Even the concepts provided by modules (of DeltaSpike itself) are based
 on the basic API provided by the Core. So it is possible to introduce
 custom concepts the same way DeltaSpike itself does.
 
-==== Motivation
+=== Motivation
 
 Instead of learning the concepts and rules of view-configs provided by
 DeltaSpike, it might be easier for simple demos to just type some
@@ -559,13 +557,13 @@ Advantages which are planned for later (= currently not supported):
 
 If you are still not convinced, you just have to try it. You will see how your daily workflow benefits from it pretty soon.
 
-==== Bean-discovery-mode Annotated
+=== Bean-discovery-mode Annotated
 
 CDI 1.1 introduced a concept called bean-discovery-mode. If you would
 like to use the mode `annotated`, please have a look at the tip at
 @ViewConfigRoot
 
-==== Basic API Usages
+=== Basic API Usages
 
 While reading this section keep the following simple rules in mind:
 Meta-data gets inherited along the path of Java inheritance
@@ -693,7 +691,7 @@ public Class<? extends Pages.Admin> toNextPage()
 }
 ------------------------------------------------
 
-===== File (@View) and Folder (@Folder) Paths
+==== File (@View) and Folder (@Folder) Paths
 
 `@View` as well as `@Folder` are optional annotations. `@Folder` is only
 needed for using a different folder-name or for marking folder configs
@@ -746,7 +744,7 @@ To customize it you can use `@Folder#name`, `@View#basePath`,
 `@View#name` and `@View#extension` (or you register custom
 `NameBuilder`s inline or globally).
 
-====== @Folder#name
+===== @Folder#name
 
 The rules are pretty simple. You will get what you write. There are only
 two additional features:
@@ -781,7 +779,7 @@ leads to the following paths:
 * /w1/step1.xhtml
 * /pages/w2/step1.xhtml
 
-====== @View
+===== @View
 
 The same naming rules apply to `@View#basePath`. However, it is only
 valid to be used at view-config nodes which represent pages (-> classes
@@ -853,7 +851,7 @@ interface Pages extends ViewConfig
 It leads to the same paths, but in addition `@View#navigation` gets
 inherited along the inheritance path.
 
-===== Navigation Parameters
+==== Navigation Parameters
 
 Since the view-config is static, an approach to add parameters is
 needed. The following part shows different possibilities to add
@@ -865,7 +863,7 @@ that way. Some get added automatically based on special meta-data (e.g.
 using `@View(navigation = REDIRECT)`. The same goes for
 `"includeViewParams=true"` and `@View(viewParams = INCLUDE)`.
 
-===== Static Configuration via @NavigationParameter
+==== Static Configuration via @NavigationParameter
 
 In some cases, it is needed to add an information in any case. So you can
 annotate the view-config class with `@NavigationParameter`. Supported
@@ -911,7 +909,7 @@ public class PageBean
 }
 -----------------------------------------------------------------------
 
-====== Dynamic Configuration via NavigationParameterContext
+===== Dynamic Configuration via NavigationParameterContext
 
 Instead of using parameters in a static fashion (as shown above), it is
 also possible to add them dynamically (e.g. in case of special
@@ -941,7 +939,7 @@ public class PageBean
 }
 --------------------------------------------------------------------------------------
 
-===== Security Integration via @Secured
+==== Security Integration via @Secured
 
 This annotation is a custom view-meta-data provided by the
 Security-module which allows to integrate third-party frameworks (or
@@ -1022,7 +1020,7 @@ public interface Pages extends ViewConfig
 -------------------------------------------------
 
 
-===== View-Controller Callbacks via @ViewControllerRef
+==== View-Controller Callbacks via @ViewControllerRef
 
 This annotation is a custom view-meta-data provided by the JSF-module
 which allows to configure beans which should act as view-controllers.
@@ -1073,7 +1071,7 @@ public class ErrorViewAwareExceptionHandler {
 }
 --------------------------------------------------------------------------------------------------------------
 
-===== Referencing Views via @ViewRef
+==== Referencing Views via @ViewRef
 
 With `@ViewControllerRef#value` you can annotate a view-config class to
 bind (/reference) a controller to it. `@ViewRef#config` allows the same
@@ -1106,7 +1104,7 @@ The above example leads to the invocation of the pre-render-view logic before
 /pages/page1.xhtml gets rendered (and it will not be called for other
 pages).
 
-===== Using the (Optional) ViewNavigationHandler
+==== Using the (Optional) ViewNavigationHandler
 
 With JSF you typically navigate with the action-method bound to a
 command-component. However, also JSF supports manual navigation via
@@ -1140,7 +1138,7 @@ Also in this case (optional) meta-data will be used for the navigation
 process, since `ViewNavigationHandler` just delegates to the active
 navigation-handler (of JSF).
 
-===== Configuring a Default Error-View
+==== Configuring a Default Error-View
 
 It is possible to mark one view-config class as default error-view. That
 means in case of errors it will be used as navigation target
@@ -1202,7 +1200,7 @@ However, in case of JSF you have to ensure that you are at a valid point
 in the JSF request-lifecycle for a navigation, because invocation gets
 transformed to a standard (implicit) JSF navigation.
 
-===== Using ViewConfigResolver
+==== Using ViewConfigResolver
 
 If you would like to query view-meta-data yourself (for whatever
 reason), you can do that with `ViewConfigResolver`.
@@ -1257,9 +1255,9 @@ pages (which have to implement the `ViewConfig` interface).
 page, it is possible to get the implicitly as well as explicitly
 configured (view-)meta-data and get and/or execute configured callbacks.
 
-==== Advanced API Usages
+=== Advanced API Usages
 
-===== Creating Custom Meta-Data via @ViewMetaData
+==== Creating Custom Meta-Data via @ViewMetaData
 
 This meta-annotation allows to create custom view-meta-data which can be
 used for view-configs. By default meta-data of a lower level overrides
@@ -1287,7 +1285,7 @@ ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDesc
 List<InfoPage> metaDataList = viewConfigDescriptor.getMetaData(InfoPage.class)
 ----------------------------------------------------------------------------------------------------------
 
-===== Creating Custom Meta-Data via @Stereotype
+==== Creating Custom Meta-Data via @Stereotype
 
 Like with CDI itself you can encapsulate multiple view meta-data
 annotation in one annotation.
@@ -1315,7 +1313,7 @@ From DeltaSpike 1.0.1, it is possible to access such stereotype annotations as
 well, once you annotate them with `@ViewMetaData`.
 
 
-===== Creating Custom Callbacks via @ViewMetaData
+==== Creating Custom Callbacks via @ViewMetaData
 
 Via a custom ConfigPreProcessor it is possible to register custom
 callbacks dynamically. The following listing shows a view-config which
@@ -1378,7 +1376,7 @@ the type of the callback (= class of the annotation) as additional
 parameter for `#getExecutableCallbackDescriptor`.
 
 
-===== Creating Custom inline Meta-Data via @InlineViewMetaData
+==== Creating Custom inline Meta-Data via @InlineViewMetaData
 
 This annotation can be used for view-meta-data which can be placed on
 other classes than view-config-classes. It is used, for example, for `@ViewRef`.
@@ -1390,7 +1388,7 @@ support one side since the inline-meta-data was converted to the same
 meta-data representation which is used for the normal view-meta-data).
 
 
-==== Path-Validation
+=== Path-Validation
 
 DeltaSpike (after v0.5) validates your configs out-of-the-box. The
 application will fail to start, if there is an invalid config (e.g. a
@@ -1403,26 +1401,26 @@ To disable the view-config (path) validation, add a `ClassDeactivator`
 which restricts
 `org.apache.deltaspike.jsf.impl.config.view.ViewConfigPathValidator`.
 
-==== View-Config SPI
+=== View-Config SPI
 
-===== ConfigDescriptorValidator
+==== ConfigDescriptorValidator
 
 Allows to validate the final view-config descriptors before they get
 deployed. Since the config-descriptor contains, for example, the final path, it is
 also possible to validate if the corresponding file exists. Use
 `@ViewConfigRoot` to configure 1-n validators.
 
-===== ConfigNodeConverter
+==== ConfigNodeConverter
 
 Allows to provide custom strategies to process the nodes of the built
 config-tree. Use `@ViewConfigRoot` to configure a custom converter.
 
-===== ConfigPreProcessor
+==== ConfigPreProcessor
 
 Allows to change the found meta-data (e.g. replace default values,
 callbacks,...) or the `ViewConfigNode` itself.
 
-===== InlineMetaDataTransformer
+==== InlineMetaDataTransformer
 
 Allows to transform an annotation annotated with `@InlineViewMetaData`
 to an annotation annotated with `@ViewMetaData`. This transformer is
@@ -1431,24 +1429,24 @@ the inline-meta-data needs a different syntax via a different annotation
 (compared to the view-config meta-data). See for example `@ViewRef` vs.
 `@ViewControllerRef`.
 
-===== TargetViewConfigProvider
+==== TargetViewConfigProvider
 
 Allows to provide a custom reference to `ViewConfig` classes (see for example
 `@InlineViewMetaData` and `@ViewRef`)
 
-===== ViewConfigInheritanceStrategy
+==== ViewConfigInheritanceStrategy
 
 Allows to customize the inheritance-strategy for meta-data. For example,
 inheritance via standard java inheritance vs. inheritance via nested
 interfaces. Use `@ViewConfigRoot` to configure a custom
 inheritance-strategy.
 
-===== ViewConfigNode
+==== ViewConfigNode
 
 Node-type used for building the meta-data-tree during the bootstrapping
 process.
 
-===== @ViewConfigRoot
+==== @ViewConfigRoot
 
 Optional annotation which allows to provide custom implementations. Only
 annotate one `ViewConfig` class which represents the root node.
@@ -1470,7 +1468,7 @@ public interface Pages extends ViewConfig
 }
 -----------------------------------------
 
-==== Activation of Custom Naming Conventions
+=== Activation of Custom Naming Conventions
 
 DeltaSpike allows to customize the default naming convention via
 `View.DefaultBasePathBuilder` and/or `View.DefaultFileNameBuilder`
@@ -1481,9 +1479,7 @@ provided by DeltaSpike. The same is supported for folders via
 `Folder.DefaultFolderNameBuilder`. In this case changing only one usage
 is possible via `Folder.folderNameBuilder`.
 
-=== (Grouped-)Conversations
-
-Available from DeltaSpike 0.6.
+== (Grouped-)Conversations
 
 DeltaSpike conversations are based on the window-scope. Therefore, do not
 forget to add the `ds:windowId`
@@ -1618,7 +1614,7 @@ public class CustomBean2
 }
 ------------------------------------------------
 
-==== Terminating Conversations
+=== Terminating Conversations
 
 You can inject the conversation via `@Inject` and use it to terminate
 the conversation immediately or you inject the
@@ -1736,7 +1732,7 @@ because the behaviour of standard conversations breaks a lot of use-cases.
 However, if you really need to keep them until the end of the request,
 you can close them in a `@PostRenderView` callback.
 
-==== Sub-Conversation-Groups
+=== Sub-Conversation-Groups
 
 Due to the parallel conversation concept of DeltaSpike there is no need
 of something like nested conversations. Just use them in parallel and
@@ -1818,16 +1814,16 @@ In the listing above all beans which implement the Wizard interface will
 be closed as soon as you close the ImplicitSubGroup.
 
 
-=== Injection in JSF Artifacts
+== Injection in JSF Artifacts
 
-==== Converter and Validator
+=== Converter and Validator
 
 Per default the JSF module of DeltaSpike handles JSF converters and validators as std. CDI beans and
 therefore it's possible to use injection, lifecycle-callbacks, scope-annotations,...
 the same way as with any other CDI bean.
 The usage is the same as for `PhaseListener` s.
 
-==== PhaseListener
+=== PhaseListener
 
 Once a std. JSF-`PhaseListener` is annotated with `@org.apache.deltaspike.jsf.api.listener.phase.JsfPhaseListener`,
 that `PhaseListener` gets active without additional config in `faces-config.xml`.
@@ -1867,9 +1863,9 @@ public class DoubleSubmitAwarePhaseListener implements PhaseListener, Deactivata
 ------------------------------------------------------------------------
 
 
-=== Event broadcasting
+== Event broadcasting
 
-==== Observe Faces-Requests
+=== Observe Faces-Requests
 
 It is possible to observe JSF-Requests via `@Observes` in combination with
 `@org.apache.deltaspike.core.api.lifecycle.Initialized` or
@@ -1889,7 +1885,7 @@ public void onAfterFacesRequest(@Observes @Destroyed FacesContext facesContext)
 }
 ------------------------------------------------------------------------
 
-==== BeforePhase / AfterPhase
+=== BeforePhase / AfterPhase
 
 It is possible to observe JSF request-lifecycle phase-events via `@Observes` in combination with
 `@org.apache.deltaspike.jsf.api.listener.phase.BeforePhase` or
@@ -1909,7 +1905,7 @@ public void onPhaseEnd(@Observes @AfterPhase(JsfPhaseId.ANY_PHASE) PhaseEvent ev
 }
 ------------------------------------------------------------------------
 
-==== JSF SystemEvents
+=== JSF SystemEvents
 
 Following JSF SystemEvents can be observed via CDI:
 
@@ -1930,15 +1926,15 @@ public class ApplicationConfig
 }
 -------------------------------------------------------------------
 
-=== Intergration with Exception Control (from DeltaSpike 0.6)
+== Integration with Exception Control
 
 Whenever a unhandled exception occurs within the JSF lifecycle, our JSF
 ExceptionHandler provides a integration to the DeltaSpike Exception
 Control.
 
-==== Examples
+=== Examples
 
-===== Basic
+==== Basic
 
 -----------------------------------------------------------------------------
 @ExceptionHandler
@@ -1954,7 +1950,7 @@ public class ApplicationExceptionHandler
 }
 -----------------------------------------------------------------------------
 
-===== Redirect
+==== Redirect
 
 [source,java]
 -----------------------------------------------------------------------------------------------------------------------------------
@@ -1974,7 +1970,7 @@ public class ApplicationExceptionHandler
 }
 -----------------------------------------------------------------------------------------------------------------------------------
 
-==== Using a Custom Qualifier for JSF Exceptions
+=== Using a Custom Qualifier for JSF Exceptions
 
 In some cases, it is required to differentiate exceptions from JSF and
 normal exceptions. This is possible via a CDI qualifier:
@@ -2014,7 +2010,7 @@ public class ApplicationExceptionHandler
 }
 -----------------------------------------------------------------------------------------------------------------------------------
 
-=== Double-Submit Prevention
+== Double-Submit Prevention
 
 To avoid that the same content of a form gets submitted and therefore
 processed multiple times, it is possible to use the tag
@@ -2039,7 +2035,7 @@ within every JSF form-tag, you would like to safeguard.
 </html>
 --------------------------------------------------
 
-=== Tips
+== Tips
 
 Using errorView, DefaultErrorView or ViewNavigationHandler will fail
 with Weld versions older than 1.1.10 due to

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/partial-bean.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/partial-bean.adoc b/documentation/src/main/asciidoc/partial-bean.adoc
index b5a1c69..991598a 100644
--- a/documentation/src/main/asciidoc/partial-bean.adoc
+++ b/documentation/src/main/asciidoc/partial-bean.adoc
@@ -7,7 +7,7 @@
 == Overview
 The Partial-Bean module provides means for implementing a generic handler to replace manual implementations of interfaces (or abstract classes).
 
-== Configure Your Projects
+== Project Setup
 The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
 
 === Declare Partial-Bean Module Dependencies
@@ -30,12 +30,10 @@ Add the Partial-Bean module to the list of dependencies in the project `pom.xml`
 </dependency>
 ----
 
-== Use the Module Features
-
 IMPORTANT: Currently CDI Interceptors applied via @Interceptors and @Decorator are not supported by partial beans!
 
 
-=== @PartialBeanBinding
+== @PartialBeanBinding
 
 Partial beans allow you to implement a generic handler to replace manual
 implementations of interfaces (or abstract classes).

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/scheduler.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/scheduler.adoc b/documentation/src/main/asciidoc/scheduler.adoc
index 70fe4ba..d8ae424 100644
--- a/documentation/src/main/asciidoc/scheduler.adoc
+++ b/documentation/src/main/asciidoc/scheduler.adoc
@@ -8,7 +8,7 @@
 == Overview
 The Scheduler module provides simple integration with Quartz v2 (default) or any other scheduler that supports cron-expressions for job-classes.
 
-== Configure Your Projects
+== Project Setup
 The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
 
 === 1. Declare Scheduler Module Dependencies
@@ -65,9 +65,7 @@ Scheduled jobs can have built-in CDI contexts started for the duration of their
 </dependency>
 ----
 
-== Use the Module Features
-
-=== @Scheduled
+== @Scheduled
 
 Just annotate your Quartz-Jobs with `@Scheduled` and they will get
 picked up and passed to the scheduler automatically (during the
@@ -135,7 +133,7 @@ public class ProjectStageAwareSchedulerController
 }
 -------------------------------------------------------------------------------------
 
-=== Manual Scheduler Control
+== Manual Scheduler Control
 
 Th SPI allows to control the scheduler (or integrate any other
 compatible scheduler as an alternative to Quartz2)
@@ -176,7 +174,7 @@ or
 </alternatives>
 -----------------------------------------------------------------------------
 
-=== Custom Scheduler
+== Custom Scheduler
 
 It is possible to replace the default integration with Quartz. Any scheduler that supports cron-expressions for job-classes can be used.
 For more information, see link:https://deltaspike.apache.org/javadoc/{latestStable}/org/apache/deltaspike/scheduler/spi/Scheduler.html[Scheduler javadoc].

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/security.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/security.adoc b/documentation/src/main/asciidoc/security.adoc
index 362a37a..3282002 100644
--- a/documentation/src/main/asciidoc/security.adoc
+++ b/documentation/src/main/asciidoc/security.adoc
@@ -5,9 +5,19 @@
 :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.
 
 == Overview
-The Security module provides intercept and security checking on method calls. This module also enables integration of third-party security frameworks and custom security concepts.
 
-== Configure Your Projects
+The Security module provides APIs for authorization of method invocations.
+
+There are two different APIs provided for two different approaches -- one simple interceptor-style API and another for more complex scenarios.
+
+* *<<_simple_interceptor_style_authorization, Simple interceptor-style API>>:* the method that is to be secured is loosely coupled to a predicate method
+(called _authorizer_ method) which decides whether the secured method invocation should proceed. Similarly to CDI
+interceptors, the secured method and the authorizer are tied together using a binding annotation --
+`@SecurityBindingType` in this case.
+
+* *<<_advanced_authorization, Advanced API>>:* this API offers fine-grained control over the authorization process. Multiple independent _voters_ can participate in making the authorization decision and possibly return _security violations_ and thus prevent the method invocation. The voters share a common context. This API is suitable for integration with third-party security frameworks. Also, this API can be used to <<jsf.adoc#_security_integration_via_secured, secure JSF view access>> when using the DeltaSpike JSF module.
+
+== Project Setup
 The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
 
 === 1. Declare Security Module Dependencies
@@ -30,7 +40,7 @@ Add the Security module to the list of dependencies in the project `pom.xml` fil
 </dependency>
 ----
 
-=== 2. Enable the Security Interceptor
+=== 2. Enable the SecurityInterceptor
 For CDI 1.0 (or DeltaSpike v1.1.0 and earlier together with CDI 1.1+), you must enable the security interceptor in the project `beans.xml` file:
 
 [source,xml]
@@ -43,46 +53,39 @@ For CDI 1.0 (or DeltaSpike v1.1.0 and earlier together with CDI 1.1+), you must
 </beans>
 ----
 
-== Use the Module Features
-
-=== SecurityBinding for Class and Method Invocations
+== Simple interceptor-style authorization
 This feature of the Security module intercepts method calls and performs 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 the `pom.xml` 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.
+The first piece of code required to use this API is a _security binding_ annotation. This is what we will use to add security behavior to our business classes and methods.
 
-.Create the SecurityBinding
+.Create the security binding annotation
 [source,java]
 ----
 @Retention(value = RUNTIME)
 @Target({TYPE, METHOD})
 @Documented
 @SecurityBindingType
-public @interface CustomSecurityBinding {
-}
+public @interface UserLoggedIn {}
 ----
 
-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
+Next, we must define an _authorizer_ class to implement behavior for our
+custom security binding type. This class is simply a CDI bean which
+declares a method annotated `@Secures`, qualified with the security binding
 annotation we created in the first step.
 
-This method has access to the InvocationContext of the method call, so
+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.
+list of our authorizer method.
 
-.Create the Authorizer
+.Create the authorizer
 [source,java]
 ---------------------------------------------------------------------------------------------------------------------------------
 @ApplicationScoped
-public class CustomAuthorizer
+public class LoggedInAuthorizer
 {
     @Secures
-    @CustomSecurityBinding
+    @UserLoggedIn
     public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, Identity identity) throws Exception
     {
         return identity.isLoggedIn(); // perform security check
@@ -92,15 +95,15 @@ public class CustomAuthorizer
 
 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.
+methods) or on individual methods that you wish to secure.
 
-.Secure a Bean Method
+.Secure a bean method
 [source,java]
 ----------------------------------------
 @ApplicationScoped
 public class SecuredBean1
 {
-    @CustomSecurityBinding
+    @UserLoggedIn
     public void doSomething(Thing thing)
     {
         thing.doSomething();
@@ -109,10 +112,10 @@ public class SecuredBean1
 ----------------------------------------
 
 Next, we may access parameter values from the method invocation directly
-in our authorizer bean by creating custom @SecurityParameterBinding
+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
+.Create a parameter binding annotation
 [source,java]
 --------------------------------
 @Retention(value = RUNTIME)
@@ -127,14 +130,14 @@ 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
+.Update the authorizer to use parameter binding
 [source,java]
 ------------------------------------------------------------------------------------------------------------------------------------------------------------
 @ApplicationScoped
 public class CustomAuthorizer
 {
     @Secures
-    @CustomSecurityBinding
+    @UserLoggedIn
     public boolean doSecuredCheck(InvocationContext invocationContext, BeanManager manager, Identity identity, @CurrentThing Thing thing) throws Exception
     {
         return thing.hasMember(identity); // perform security check against our method parameter
@@ -150,7 +153,7 @@ Note that our business method must also be annotated.
 @ApplicationScoped
 public class SecuredBean1
 {
-    @CustomSecurityBinding
+    @UserLoggedIn
     public void doSomething(@CurrentThing Thing thing)
     {
         thing.doSomething();
@@ -171,7 +174,7 @@ case:
 @ApplicationScoped
 public class SecuredBean1
 {
-    @CustomSecurityBinding
+    @UserLoggedIn
     public Thing loadSomething()
     {
         return thingLoader.load();
@@ -180,7 +183,7 @@ public class SecuredBean1
 ----------------------------------
 
 Now you need to access the return value in the authorizer method. You
-can inject it using the @SecuredReturn annotation. Update the Authorizer
+can inject it using the `@SecuredReturn` annotation. Update the authorizer
 to use a secured return value:
 
 [source,java]
@@ -189,7 +192,7 @@ to use a secured return value:
 public class CustomAuthorizer
 {
     @Secures
-    @CustomSecurityBinding
+    @UserLoggedIn
     public boolean doSecuredCheck(@SecuredReturn Thing thing, Identity identity) throws Exception
     {
         return thing.hasMember(identity); // perform security check against the return value
@@ -199,36 +202,9 @@ public class CustomAuthorizer
 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 Third-party Security Frameworks
+== Advanced authorization
 
-==== @Secured
-
-`@Secured` is build on `@SecurityBindingType` and a very simple
-alternative to the rest of the security module. It is a basic hook to
-integrate a custom security concept, third-party frameworks, etc. It
-does not 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.
+This is an alternative to the simple annotation-based interceptor-style API. This API uses the annotation `@Secured` and is mainly a hook for integration of custom security concepts and third-party frameworks. The DeltaSpike Security module is _not_ a full application security solution, but some of the other DeltaSpike modules are security-enabled and use this API (e.g. correct behaviour within custom scope implementations,...). Internally, this `@Secured` API uses the `@Secures`/`@SecurityBindingType` API.
 
 (In MyFaces CODI it was originally a CDI interceptor. This part changed
 a bit, because between the interceptor and `@Secured` is the
@@ -236,6 +212,8 @@ a bit, because between the interceptor and `@Secured` is the
 approach. Therefore the basic behaviour remains the same and you can
 think about it like an interceptor.)
 
+The entry point to this API is the `@Secured` annotation placed either on the whole class -- enabling security for all methods -- or on individual methods. The only other prerequisite is at least one `AccessDecisionVoter` implementation, explained in the next section.
+
 .Securing All Intercepted Methods of a CDI Bean
 [source,java]
 -----------------------------------------
@@ -261,9 +239,9 @@ public class SecuredBean
 }
 ---------------------------------------------
 
-==== AccessDecisionVoter
+=== AccessDecisionVoter
 
-This interface is (besides the `Secured` annotation) the most important
+This interface is (besides the `@Secured` annotation) the most important
 part of the concept. Both artifact types are also the only required
 parts:
 
@@ -281,9 +259,11 @@ public class CustomAccessDecisionVoter implements AccessDecisionVoter
 }
 --------------------------------------------------------------------------------------------------------
 
+////
 [TODO] tip about the changed parameter/s
+////
 
-==== SecurityViolation
+=== SecurityViolation
 
 In case of a detected violation a `SecurityViolation` has to be added to
 the result returned by the `AccessDecisionVoter`.
@@ -309,7 +289,7 @@ public class CustomAccessDecisionVoter extends AbstractAccessDecisionVoter
 -----------------------------------------------------------------------------------------
 
 
-==== @Secured and Stereotypes with Custom Meta-data
+=== @Secured and stereotypes with custom metadata
 
 If there are multiple `AccessDecisionVoter` and maybe in different
 constellations, it is easier to provide an expressive CDI stereotypes for
@@ -334,9 +314,9 @@ public @interface Admin
 }
 -------------------------------------------
 
-Furthermore, it is possible to provide custom meta-data easily.
+Furthermore, it is possible to provide custom metadata easily.
 
-.Stereotype of @Secured with Custom Meta-data
+.Stereotype of @Secured with custom metadata
 [source,java]
 ------------------------------------------------------------------------------------------
 @Named
@@ -368,146 +348,6 @@ public class RoleAccessDecisionVoter implements AccessDecisionVoter
 }
 ------------------------------------------------------------------------------------------
 
-=== 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,
@@ -522,7 +362,7 @@ There are several methods that can be useful
 * `getMetaData()` - Exposes the found meta-data, for example 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
+=== SecurityStrategy SPI
 
 The `SecurityStrategy` interface allows to provide a custom
 implementation which should be used for `@Secured`. Provide a custom
@@ -537,5 +377,21 @@ In case of global-alternatives an additional configuration needs to be added to
 globalAlternatives.org.apache.deltaspike.security.spi.authorization.SecurityStrategy=mypackage.CustomSecurityStrategy
 ----
 
-TIP: The configuration for global-alternatives is following the pattern:
-globalAlternatives.`<interface-name>`=`<implementation-class-name>`
+TIP: The configuration for global alternatives is following the pattern:
+`globalAlternatives._<interface-name>_=_<implementation-class-name>_`
+
+
+=== Examples
+
+==== Redirect to requested page 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.
+
+An example of this use case is available in the examples module in the DeltaSpike repository:
+
+* link:https://github.com/apache/deltaspike/tree/master/deltaspike/examples/security-requested-page-after-login-cdi[Making initially requested secured page available for redirect after login with CDI]
+
+* link:https://github.com/apache/deltaspike/tree/master/deltaspike/examples/security-requested-page-after-login-picketlink[Making initially requested secured page available for redirect after login with PicketLink]
+
+The relevant classes are `AuthenticationListener` and `LoggedInAccessDecisionVoter`.

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/documentation/src/main/asciidoc/servlet.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/servlet.adoc b/documentation/src/main/asciidoc/servlet.adoc
index 4466a0c..8701db6 100644
--- a/documentation/src/main/asciidoc/servlet.adoc
+++ b/documentation/src/main/asciidoc/servlet.adoc
@@ -7,7 +7,7 @@
 == Overview
 The Servlet module provides CDI integration with the Java Servlet API. It enables injection of common servlet objects and propagation of servlet events to the CDI event bus.
 
-== Configure Your Projects
+== Project Setup
 The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
 
 === 1. Declare Servlet Module Dependencies
@@ -30,7 +30,7 @@ Add the Servlet module to the list of dependencies in the project `pom.xml` file
 </dependency>
 ----
 
-== 2. Configure Listeners and Filters
+=== 2. Configure Listeners and Filters
 
 In most cases there is no need for any additional configuration beside
 adding the required dependencies to your project, because all required
@@ -88,9 +88,7 @@ In these cases you will have to add the following section manually to the projec
 </filter-mapping>
 -------------------------------------------------------------------------------------------------------------
 
-== Use the Module Features
-
-=== Injectable Servlet Objects
+== Injectable Servlet Objects
 
 The DeltaSpike Servlet module contains producers for many objects of a
 Servlet environment. All produces are using the special qualifier
@@ -105,7 +103,7 @@ The following code shows the general injection pattern to use for all objects.
 private ServletObject servletObject;
 ------------------------------------
 
-==== ServletContext
+=== ServletContext
 
 The `ServletContext` is made available in the application scope. It can
 be injected into any CDI bean like this:
@@ -116,7 +114,7 @@ be injected into any CDI bean like this:
 private ServletContext servletContext;
 --------------------------------------
 
-==== ServletRequest / HttpServletRequest
+=== ServletRequest / HttpServletRequest
 
 The `ServletRequest` is made available in the request scope. The current
 request can be injected into a CDI bean like this:
@@ -136,7 +134,7 @@ private HttpServletRequest request;
 -----------------------------------
 
 
-==== ServletResponse / HttpServletResponse
+=== ServletResponse / HttpServletResponse
 
 The `ServletResponse` is made available in the request scope. The
 current response can be injected into a CDI bean like this:
@@ -155,7 +153,7 @@ In case of HTTP requests you can also inject the `HttpServletResponse`:
 private HttpServletResponse response;
 -------------------------------------
 
-==== HttpSession
+=== 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:
@@ -169,7 +167,7 @@ private HttpSession session;
 Please note that injecting the session this way will force the creation
 of a session.
 
-==== Principal
+=== Principal
 
 The `Principal` is made available in the request scope. The current
 principal can be injected into a CDI bean like this:
@@ -183,7 +181,7 @@ private Principal principal;
 The `Principal` is obtained by calling `getUserPrincipal()` on the
 `HttpServletRequest`.
 
-=== Servlet Event Propagation
+== Servlet Event Propagation
 
 The DeltaSpike Servlet module propagates a number of Servlet object
 lifecycle events to the CDI event bus. This allows regular CDI beans to
@@ -196,7 +194,7 @@ object, DeltaSpike uses the qualifiers `@Initialized` and `@Destroyed`.
 The following sections shows which concrete Servlet objects are
 supported and how their lifecycle can be observed.
 
-==== Servlet Context Lifecycle Events
+=== Servlet Context Lifecycle Events
 
 The Servlet module supports initialization and destruction events for
 the `ServletContext`. These events can for example be used to detect
@@ -227,7 +225,7 @@ 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
+=== Request and Response Lifecycle Events
 
 The Servlet module also supports initialization and destruction events
 for the `HttpServletRequest` and `HttpServletResponse`. These events can
@@ -275,7 +273,7 @@ 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
+=== 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

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/e67d64a2/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
index 0ce28dd..6a9ccc2 100644
--- a/documentation/src/main/asciidoc/test-control.adoc
+++ b/documentation/src/main/asciidoc/test-control.adoc
@@ -8,7 +8,7 @@
 == Overview
 The Test-Control module enables you to write CDI-based tests easily. Calls to stop and start the CDI container are built into the Test-Control API, with simplified commands for customizing the management of contexts and other aspects during testing.
 
-== Configure Your Projects
+== Project Setup
 The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <<configure#, Configure DeltaSpike in Your Projects>>. For Maven-independent projects, see <<configure#config-maven-indep,Configure DeltaSpike in Maven-independent Projects>>.
 
 === 1. Declare Test-Control Module Dependencies
@@ -104,11 +104,9 @@ of dependencies instead of the OpenWebBeans-specific Container Control module:
 
 Add a `beans.xml` file in the project test module (e.g. src/test/resources/META-INF/beans.xml).
 
-== Use the Module Features
+== Automated Container Booting and Shutdown
 
-=== Automated Container Booting and Shutdown
-
-==== CdiTestRunner
+=== CdiTestRunner
 
 Start and stop the CDI container automatically per test class with CdiTestRunner, a JUnit Test-Runner. 
 This also starts and stops one request and session per test-method.
@@ -132,7 +130,7 @@ public class ContainerAndInjectionControl
 }
 --------------------------------------------------------
 
-==== CdiTestSuiteRunner
+=== CdiTestSuiteRunner
 
 Extend automated CDI container start and stop actions to whole test suites with CdiTestSuiteRunner, a JUnit Test-Suite-Runner.
 
@@ -149,13 +147,13 @@ public class SuiteLevelContainerControl
 }
 ---------------------------------------
 
-==== Optional Shutdown Configuration
+=== Optional Shutdown Configuration
 
 You can set `deltaspike.testcontrol.stop_container` to `false` (via the standard DeltaSpike config), resulting in the CDI Container being started just once for all tests.
 
-=== Test Customization
+== Test Customization
 
-==== @TestControl
+=== @TestControl
 
 Customize the default behavior of CdiTestRunner with @TestControl. In the following
 case only one session for all test-methods (of the test-class) will be
@@ -172,7 +170,7 @@ public class CustomizedScopeHandling
 }
 -----------------------------------------------
 
-==== ProjectStage Control
+=== ProjectStage Control
 
 Override the default ProjectStage for unit tests with `ProjectStage.UnitTest.class`.
 
@@ -195,7 +193,7 @@ public class TestStageControl
 }
 ---------------------------------------------------------------
 
-=== Optional Configuration
+== Optional Configuration
 
 From DeltaSpike 1.2, it is possible to provide a configuration for the underlying test-container.
 However, currently only the adapter for OpenEJB embedded (available in CDI-Control) supports it out-of-the-box.
@@ -206,7 +204,7 @@ The content of the file are key/value pairs which get passed to the container.
 Therefore, it is a configuration which is not used by DeltaSpike itself
 (it is just forwarded (as it is) to the underlying test-container).
 
-==== Reconfigure the config-file Name or Location
+=== Reconfigure the config-file Name or Location
 
 If you would like to point to an existing config-file, you have to add for example:
 
@@ -225,9 +223,9 @@ deltaspike.testcontrol.test-container.config-file.UnitTest=META-INF/unit-test/ex
 ---------------------------------------------------------------
 
 
-=== Optional Integrations
+== Optional Integrations
 
-==== Mock Frameworks
+=== Mock Frameworks
 
 From DeltaSpike 1.0, it is possible to mock CDI-Beans. Usually @Exclude (+
 ProjectStage) is enough, however, for some cases mocked beans might be
@@ -419,7 +417,7 @@ Mocking such typed beans can result in an
 mocked implementation via `@Exclude` or `@Typed()` (or a parametrized
 constructor) and specify the target-type via `@TypedMock`.
 
-==== JSF (via MyFaces-Test)
+=== JSF (via MyFaces-Test)
 
 add on of
 
@@ -434,7 +432,7 @@ as content to
 
 (in your config-folder for tests, e.g. test/resources)
 
-=== Using jersey-test with test-control
+== Using jersey-test with test-control
 
 Jersey-test starts jetty which answers requests in a separated thread. Since ds test-control just handles the thread of the test itself, it's needed to integrate jetty and jersey with the cdi-container. Usually that's done via a ServletRequestListener - the following part describes an alternative approach for jersey-test:
 
@@ -509,7 +507,7 @@ public class CdiAwareHandlerWrapper extends HandlerWrapper
 }
 -------------------------------------------------------------------------------------------
 
-=== Mixed Tests
+== Mixed Tests
 
 Usually you should have one kind of tests per test-module. However, if
 you need to add, for example, a test without an external-container to your
@@ -527,9 +525,9 @@ public class JsfContainerTest
 ---------------------------------------------
 
 
-=== Known Restrictions
+== Known Restrictions
 
-==== Liquibase
+=== Liquibase
 
 Liquibase invokes `#toString` in a `AfterDeploymentValidation` observer.
 *that is not portable* and therefore you have to deactivate the
@@ -553,7 +551,7 @@ org.apache.deltaspike.core.spi.activation.ClassDeactivator=myPackage.LiquibaseAw
 
 Further details are available at deactivatable.
 
-==== Gradle
+=== Gradle
 
 Gradle by default does not put resources and compiled sources in to the same directory.
 When running a test using Gradle, this means your classes will not be in bean archives as
@@ -574,9 +572,9 @@ sourceSets {
 }
 ----------------------------------------------------------------------------------------------------------
 
-=== SPI
+== SPI
 
-==== ExternalContainer
+=== ExternalContainer
 
 org.apache.deltaspike.testcontrol.spi.ExternalContainer allows to
 integrate containers which get started after the CDI container.


Mime
View raw message