You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by ra...@apache.org on 2014/12/15 23:25:43 UTC
[1/9] deltaspike git commit: DELTASPIKE-690: module adoc pages edited
Repository: deltaspike
Updated Branches:
refs/heads/master 1596f17d1 -> fcb0fee3a
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/security.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/security.adoc b/documentation/src/main/asciidoc/security.adoc
index db96701..7340310 100644
--- a/documentation/src/main/asciidoc/security.adoc
+++ b/documentation/src/main/asciidoc/security.adoc
@@ -1,50 +1,69 @@
-= DeltaSpike Security Module
+= 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
+== 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.
-*Hint:* If you are using features described by this page with CDI 1.0
-(or DeltaSpike up to v1.1.0 with CDI 1.1+), you have
-to enable the security interceptor in your beans.xml file:
+== Configure Your Projects
+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
+Add the Security module to the list of dependencies in the project `pom.xml` file using this code snippet:
[source,xml]
-----------------------------------------------------------------------------------------
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-security-module-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-security-module-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+=== 2. Enable the Security Interceptor
+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]
+----
<beans>
<!-- Not needed with CDI 1.1+ and DeltaSpike v1.1.1+ -->
<interceptors>
<class>org.apache.deltaspike.security.impl.extension.SecurityInterceptor</class>
</interceptors>
</beans>
-----------------------------------------------------------------------------------------
-
+----
-SecurityBinding for class and method invocations
-------------------------------------------------
+== Use the Module Features
-This feature of the security module functions by intercepting method
-calls, and performing a security check before invocation is allowed to
-proceed.
+=== SecurityBinding for Class and Method Invocations
+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 your POM file. Once this is
+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.
-Create the SecurityBinding:
-
+.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
@@ -56,8 +75,7 @@ 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:
-
+.Create the Authorizer
[source,java]
---------------------------------------------------------------------------------------------------------------------------------
@ApplicationScoped
@@ -76,8 +94,7 @@ 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:
-
+.Secure a Bean Method
[source,java]
----------------------------------------
@ApplicationScoped
@@ -95,8 +112,7 @@ 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:
-
+.Create a Parameter Binding Annotation
[source,java]
--------------------------------
@Retention(value = RUNTIME)
@@ -111,8 +127,7 @@ 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
@@ -129,8 +144,7 @@ public class CustomAuthorizer
Note that our business method must also be annotated.
-Complete the parameter binding:
-
+.Complete the Parameter Binding
[source,java]
------------------------------------------------------
@ApplicationScoped
@@ -185,8 +199,7 @@ 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:
-
+.Complete the Parameter Binding
[source,java]
------------------------------------------------------
@ApplicationScoped
@@ -204,15 +217,14 @@ 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
-
+=== Integrating Third-party Security Frameworks
-=== @Secured
+==== @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
+alternative to the rest of the security module. It is a basic hook to
+integrate a custom security concept, third-party frameworks, etc. It
+doesis 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
@@ -224,8 +236,7 @@ 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.)
-Securing all intercepted methods of a CDI bean:
-
+.Securing All Intercepted Methods of a CDI Bean
[source,java]
-----------------------------------------
//...
@@ -236,10 +247,7 @@ public class SecuredBean
}
-----------------------------------------
-or
-
-Securing specific methods:
-
+.Securing Specific Methods
[source,java]
---------------------------------------------
//...
@@ -253,7 +261,7 @@ public class SecuredBean
}
---------------------------------------------
-=== AccessDecisionVoter
+==== AccessDecisionVoter
This interface is (besides the `Secured` annotation) the most important
part of the concept. Both artifact types are also the only required
@@ -273,9 +281,9 @@ public class CustomAccessDecisionVoter implements AccessDecisionVoter
}
--------------------------------------------------------------------------------------------------------
-[TODO] hint about the changed parameter/s
+[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`.
@@ -301,15 +309,14 @@ public class CustomAccessDecisionVoter extends AbstractAccessDecisionVoter
-----------------------------------------------------------------------------------------
-=== @Secured and Stereotypes with custom Meta-data
+==== @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
+constellations, it is 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:
-
+.Stereotype Support of @Secured
[source,java]
-------------------------------------------
@Named
@@ -327,10 +334,9 @@ public @interface Admin
}
-------------------------------------------
-Furthermore, it's possible to provide custom meta-data easily.
-
-Stereotype of @Secured with custom meta-data:
+Furthermore, it is possible to provide custom meta-data easily.
+.Stereotype of @Secured with Custom Meta-data
[source,java]
------------------------------------------------------------------------------------------
@Named
@@ -362,14 +368,14 @@ public class RoleAccessDecisionVoter implements AccessDecisionVoter
}
------------------------------------------------------------------------------------------
-== Making intitially requested and secured page available for redirect after login
+=== 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
+==== CDI Implementation to Redirect the Login to the First Denied Page
Your LoginService will fire a custom `UserLoggedInEvent`
@@ -440,7 +446,7 @@ public class AuthenticationListener {
}
----------------------------------------------------------------------------------------
-=== PicketLink Implementation to redirect the login to the first denied page
+==== 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
@@ -502,7 +508,7 @@ public class AuthenticationListener {
}
----------------------------------------------------------------------------------------
-== AccessDecisionVoterContext
+=== AccessDecisionVoterContext
Because the `AccessDecisionVoter` can be chained,
`AccessDecisionVoterContext` allows to get the current state as well as
@@ -512,21 +518,24 @@ 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
+* `getSource()` - Exposes, for example, the current instance of `javax.interceptor.InvocationContext` in combination with `@Secured` used as interceptor.
+* `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
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.:
+In case of global-alternatives an additional configuration needs to be added to
+`/META-INF/apache-deltaspike.properties`.
-`globalAlternatives.org.apache.deltaspike.security.spi.authorization.SecurityStrategy=mypackage.CustomSecurityStrategy`
+.Example
+----
+globalAlternatives.org.apache.deltaspike.security.spi.authorization.SecurityStrategy=mypackage.CustomSecurityStrategy
+----
-**Note**: The config for global-alternatives is following the pattern:
+TIP: The configuration for global-alternatives is following the pattern:
globalAlternatives.`<interface-name>`=`<implementation-class-name>`
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/servlet.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/servlet.adoc b/documentation/src/main/asciidoc/servlet.adoc
index 61e530f..f840b96 100644
--- a/documentation/src/main/asciidoc/servlet.adoc
+++ b/documentation/src/main/asciidoc/servlet.adoc
@@ -4,7 +4,33 @@
:toc:
-== Configuration
+== 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
+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
+Add the Servlet module to the list of dependencies in the project `pom.xml` file using this code snippet:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-servlet-module-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-servlet-module-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+== 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
@@ -13,12 +39,11 @@ 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.
+* Your container doesis not 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`:
+In these cases you will have to add the following section manually to the project `web.xml`:
[source,xml]
-------------------------------------------------------------------------------------------------------------
@@ -63,8 +88,9 @@ your `web.xml`:
</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
@@ -79,8 +105,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:
@@ -91,9 +116,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:
@@ -113,7 +136,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:
@@ -132,8 +155,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:
@@ -147,7 +169,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:
@@ -161,10 +183,9 @@ private Principal principal;
The `Principal` is obtained by calling `getUserPrincipal()` on the
`HttpServletRequest`.
+=== Servlet Event Propagation
-== Servlet event propagation
-
-The DeltaSpike Servlet module will propagate a number of Servlet object
+The DeltaSpike Servlet module propagates a number of Servlet object
lifecycle events to the CDI event bus. This allows regular CDI beans to
observe these events and react accordingly.
@@ -172,11 +193,10 @@ 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
+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
@@ -198,6 +218,7 @@ The events are emitted from a `ServletContextListener` called
`EventBridgeContextListener`. You can disable lifecycle events for the
`ServletContext` by deactivating the following class:
+[source,java]
-------------------------------------------------------------------
org.apache.deltaspike.servlet.impl.event.EventBridgeContextListener
-------------------------------------------------------------------
@@ -206,8 +227,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
@@ -246,6 +266,7 @@ All events of this category are emitted from a servlet filter called
just use DeltaSpike's deactivation mechanism to deactivate the following
class:
+[source,java]
----------------------------------------------------------
org.apache.deltaspike.servlet.impl.event.EventBridgeFilter
----------------------------------------------------------
@@ -254,8 +275,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
@@ -276,6 +296,7 @@ The lifecycle events for the HTTP session are sent from a
`HttpSessionListener` called `EventBridgeSessionListener`. To disable
this event category, deactivate the following class:
+[source,java]
-------------------------------------------------------------------
org.apache.deltaspike.servlet.impl.event.EventBridgeSessionListener
-------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/snapshots.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/snapshots.adoc b/documentation/src/main/asciidoc/snapshots.adoc
index 4ee98ed..5598645 100644
--- a/documentation/src/main/asciidoc/snapshots.adoc
+++ b/documentation/src/main/asciidoc/snapshots.adoc
@@ -6,7 +6,7 @@
If you want to be at the bleeding edge, you can work with DeltaSpike snapshots. These are available from the Apache Snapshot Repository for use in Maven-based projects. To begin using them, you must configure Maven with the repository location and your projects with the snapshot version.
-**Warning:** Snapshots provide previews of DeltaSpike during development. Snapshots are subject to change and may not yet include all expected features of the final release. Snapshots should not be used in production environments.
+WARNING: Snapshots provide previews of DeltaSpike during development. Snapshots are subject to change and may not yet include all expected features of the final release. Snapshots should not be used in production environments.
== 1. Configure Maven to Use the Apache Snapshot Repository
You must add the Apache Snapshot Repository to your Maven configuration `settings.xml` file. This ensures Maven can find the repository when it searches for your project DeltaSpike dependencies.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/spi.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/spi.adoc b/documentation/src/main/asciidoc/spi.adoc
index 5a1c705..bdc0f7a 100644
--- a/documentation/src/main/asciidoc/spi.adoc
+++ b/documentation/src/main/asciidoc/spi.adoc
@@ -8,16 +8,16 @@ DeltaSpike provides an Service Provider Interface (SPI) to enable you to extend
== 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 mechanism is only used for artifacts *like* implementations of (`javax.enterprise.inject.spi.Extension`) which *cais not* be deactivated with standard 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)).
+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 isis not needed, to provide a custom implementation if the default implementation isis not 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.
+To deactivate a class it is required to implement `ClassDeactivator`. Returning 'false' or 'true' allows to de-/activate the class in question. Retuning null means that the current class-deactivator doesis not have information about the class in question and cais not provide a result. Since `ClassDeactivator` implementations are configured with the low-level configuration of DeltaSpike, the class-deactivator with the highest ordinal has the final decision. DeltaSpike itself doesis not deactivate an implementation, however, an add-on or a third-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.
+IMPORTANT: Due to the ordinal feature of the low-level configuration approach it is possible that a class-deactivator with a higher ordinal, for example 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.
+*Please note* that you might have to deactivate the parts of the add-on or third-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 wois not be used any longer.
=== ClassDeactivator
@@ -25,7 +25,7 @@ A class-deactivator allows to specify deactivated classes.
[source,java]
----------------------------------------------------------------------------
-//This class needs to be configured via one of the supported config sources!
+//This class needs to be configured via one of the supported configuration sources!
public class CustomClassDeactivator implements ClassDeactivator
{
@Override
@@ -62,10 +62,9 @@ A class-deactivator will be resolved from the environment via the default resolv
== 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)*
+There are several application servers (using CDI 1.0) which cais not handle alternative CDI beans correctly (e.g. due to a too strict interpretation or a broken implementation). Therefore, DeltaSpike allows to use the standard `@Alternative` annotation and an additional configuration entry for DeltaSpike which allows to use the alternative implementation as a global alternative.
+.Standard CDI alternative implementation (without the required XML config)
[source,java]
----
public class CustomBean
@@ -79,7 +78,7 @@ 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.
+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 configuration entry for DeltaSpike again and move to the standard CDI configuration approach.
[source]
----
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/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 4f9936a..2e5238d 100644
--- a/documentation/src/main/asciidoc/test-control.adoc
+++ b/documentation/src/main/asciidoc/test-control.adoc
@@ -4,69 +4,101 @@
:toc:
-== Intro
+== 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.
-This module is available since version 0.6 and allows to write CDI based
-tests easily.
+== Configure Your Projects
+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>>.
-
-== Setup
-
-Setup for the CDI implementation of your choice and the following
-test-dependencies:
+=== 1. Declare Test-Control Module Dependencies
+Add the Test-Control module to the list of dependencies in the project `pom.xml` file using this code snippet:
[source,xml]
-----------------------------------------------------------------
+----
<dependency>
<groupId>org.apache.deltaspike.modules</groupId>
<artifactId>deltaspike-test-control-module-api</artifactId>
- <version>${ds.version}</version>
+ <version>${deltaspike.version}</version>
<scope>test</scope>
</dependency>
+
<dependency>
<groupId>org.apache.deltaspike.modules</groupId>
<artifactId>deltaspike-test-control-module-impl</artifactId>
- <version>${ds.version}</version>
+ <version>${deltaspike.version}</version>
<scope>test</scope>
</dependency>
-----------------------------------------------------------------
+----
+
+=== 2. Declare CDI Implemetation-specific Test-Control Module Dependencies
+The Test-Control module uses the Container-Control module, requiring a implementation-specific Container Control module to be declared in the project `pom.xml` file. Choose the appropriate option from those listed here.
-=== OpenWebBeans
+==== OpenWebBeans
-If you are using OpenWebBeans also add the following test-dependency
+If you are using OpenWebBeans, add the OpenWebBeans-specific Container Control module to the list of dependencies:
[source,xml]
-----------------------------------------------------
<dependency>
<groupId>org.apache.deltaspike.cdictrl</groupId>
<artifactId>deltaspike-cdictrl-owb</artifactId>
- <version>${ds.version}</version>
+ <version>${deltaspike.version}</version>
<scope>test</scope>
</dependency>
-----------------------------------------------------
+==== Weld
-=== Weld
-
-If you are using Weld also add the following test-dependency
+If you are using Weld, add the Weld-specific Container Control module to the list of dependencies:
[source,xml]
----------------------------------------------------
<dependency>
<groupId>org.apache.deltaspike.cdictrl</groupId>
<artifactId>deltaspike-cdictrl-weld</artifactId>
- <version>${ds.version}</version>
+ <version>${deltaspike.version}</version>
<scope>test</scope>
</dependency>
----------------------------------------------------
+==== OpenEJB
+
+If you are using OpenWebBeans as the CDI implementation and you need to test
+EJBs as well, add the OpenEJB-specific Container Control module to the list
+of dependencies instead of the OpenWebBeans-specific Container Control module:
-== CdiTestRunner
+[source,xml]
+----------------------------------------------------
+<dependency>
+ <groupId>org.apache.deltaspike.cdictrl</groupId>
+ <artifactId>deltaspike-cdictrl-openejb</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>test</scope>
+</dependency>
-JUnit Test-Runner to start/stop the CDI-Container autom. (per
-test-class) and one request and session per test-method:
+<dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-core</artifactId>
+ <version>${openejb.version}</version>
+ <scope>test</scope>
+</dependency>
+----------------------------------------------------
+=== 3. Complete Additional Project Configuration
+
+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
+
+==== 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.
+
+.Example of CdiTestRunner Usage
[source,java]
--------------------------------------------------------
@RunWith(CdiTestRunner.class)
@@ -85,27 +117,11 @@ public class ContainerAndInjectionControl
}
--------------------------------------------------------
-== @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
+==== CdiTestSuiteRunner
-JUnit Test-Suite-Runner to start/stop the CDI-Container autom. (per
-test-suite):
+Extend automated CDI container start and stop actions to whole test suites with CdiTestSuiteRunner, a JUnit Test-Suite-Runner.
+.Example of CdiTestSuiteRunner Usage
[source,java]
---------------------------------------
@RunWith(CdiTestSuiteRunner.class)
@@ -118,18 +134,41 @@ public class SuiteLevelContainerControl
}
---------------------------------------
-== Project-Stage Control
+==== Optional Shutdown Configuration
-It's possible to overrule the default-project-stage for unit-tests
-(ProjectStage.UnitTest.class):
+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
+
+==== @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
+created.
+.Example of @TestControl Usage
+[source,java]
+-----------------------------------------------
+@RunWith(CdiTestRunner.class)
+@TestControl(startScopes = SessionScoped.class)
+public class CustomizedScopeHandling
+{
+ //inject beans and test them
+}
+-----------------------------------------------
+
+==== ProjectStage Control
+
+Override the default ProjectStage for unit tests with `ProjectStage.UnitTest.class`.
+
+.Example of projectStage Usage
[source,java]
---------------------------------------------------------------
@RunWith(CdiTestRunner.class)
@TestControl(projectStage = CustomTestStage.class)
public class TestStageControl
{
- //tests here will see project-stage CustomTestStage.class
+ //tests here will see ProjectStage CustomTestStage.class
@Test
@TestControl(projectStage = ProjectStage.Development.class)
@@ -137,42 +176,24 @@ public class TestStageControl
{
}
- //tests here will see project-stage CustomTestStage.class
+ //tests here will see ProjectStage CustomTestStage.class
}
---------------------------------------------------------------
+=== Optional Configuration
-== 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 Config
-
-Since DeltaSpike 1.2 it's possible to provide a config for the underlying test-container.
+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.
To pass properties to the underlying test-container,
you have to add `/META-INF/apache-deltaspike_test-container.properties`
to the resources-directory of your test-classpath.
The content of the file are key/value pairs which get passed to the container.
-Therefore, it's a config which isn't used by DeltaSpike itself
-(it's just forwarded (as it is) to the underlying test-container).
+Therefore, it is a configuration which isis not used by DeltaSpike itself
+(it is just forwarded (as it is) to the underlying test-container).
-=== Reconfigure the config-file name/location
+==== Reconfigure the config-file Name or Location
-If you would like to point to an existing config-file, you have to add e.g.
+If you would like to point to an existing config-file, you have to add for example:
[source,Properties]
---------------------------------------------------------------
@@ -181,7 +202,7 @@ deltaspike.testcontrol.test-container.config-file=META-INF/existingConfig.proper
to `/META-INF/apache-deltaspike.properties`.
-If you would like to do it per project-stage, you can use e.g.:
+If you would like to do it per ProjectStage, you can use for example:
[source,Properties]
---------------------------------------------------------------
@@ -189,22 +210,20 @@ 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
+easier. Therefore it is possible to create (mock-)instances manually or
+via a mocking framework and add them, for example, via `DynamicMockManager`.
-Since v1 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`.
-
-*Attention:*
-Mocking CDI beans isn't supported for every feature of CDI and/or
-every implementation version. E.g. we can't mock intercepted CDI beans and
+**Attention:** Mocking CDI beans isis not supported for every feature of CDI and/or
+every implementation version. For example, we cais not mock intercepted CDI beans and
with some implementations mocking specialized beans fails.
-Usually all features are active per default, however,
-due to those reasons we deactivated this feature per default.
+Usually all features are active by default, however,
+due to those reasons we deactivated this feature by default.
You can enable it by adding
`deltaspike.testcontrol.mock-support.allow_mocked_beans=true`
@@ -261,9 +280,9 @@ public class RequestScopedBean
}
-------------------------------------------------------------
-Using a mocking framework makes no difference for adding the mock. E.g.
-via Mockito:
+Using a mocking framework makes no difference for adding the mock.
+.Example via Mockito
[source,java]
----------------------------------------------------------------------------------
@RunWith(CdiTestRunner.class)
@@ -290,8 +309,7 @@ public class MockitoMockedRequestScopedBeanTest
----------------------------------------------------------------------------------
Since CDI implementations like OpenWebBeans use a lot of optimizations,
-it's required to handle mocks for application-scoped beans differently -
-e.g.:
+it is required to handle mocks for application-scoped beans differently, for example:
[source,java]
--------------------------------------------------------------------------------------------------------------------------
@@ -347,8 +365,8 @@ public class MockedApplicationScopedBean extends ApplicationScopedBean
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.:
+It is also possible to mock qualified beans. Just add the
+literal-instance(s) as additional parameter(s), for example:
[source,java]
-------------------------------------------------------------
@@ -380,13 +398,13 @@ public class MockedQualifiedBeanTest
}
-------------------------------------------------------------
-In some cases it's needed to use `@javax.enterprise.inject.Typed`.
+In some cases it is necessary to use `@javax.enterprise.inject.Typed`.
Mocking such typed beans can result in an
-`AmbiguousResolutionException`. Therefore it's needed to exclude the
+`AmbiguousResolutionException`. Therefore it is necessary to exclude the
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
@@ -399,12 +417,12 @@ as content to
/META-INF/services/org.apache.deltaspike.testcontrol.spi.ExternalContainer
-(in your config-folder for tests e.g.: test/resources)
+(in your config-folder for tests, e.g. test/resources)
-== Mixed Tests
+=== 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
+you need to add, for example, a test without an external-container to your
test-module which uses external-containers, you can annotate your test
with:
@@ -419,12 +437,12 @@ public class JsfContainerTest
---------------------------------------------
-== Known Restrictions
+=== Known Restrictions
-=== Liquibase
+==== Liquibase
Liquibase invokes `#toString` in a `AfterDeploymentValidation` observer.
-*that isn't portable* and therefore you have to deactivate the
+*that isis not portable* and therefore you have to deactivate the
mocking-support via:
[source,java]
@@ -437,7 +455,7 @@ public class LiquibaseAwareClassDeactivator implements ClassDeactivator {
}
----------------------------------------------------------------------------------------------------------
-and add `LiquibaseAwareClassDeactivator` to `/META-INF/apache-deltaspike.properties` - e.g.:
+and add `LiquibaseAwareClassDeactivator` to `/META-INF/apache-deltaspike.properties`, for example:
---------------------------------------------------------------------------------------------------
org.apache.deltaspike.core.spi.activation.ClassDeactivator=myPackage.LiquibaseAwareClassDeactivator
@@ -445,11 +463,9 @@ org.apache.deltaspike.core.spi.activation.ClassDeactivator=myPackage.LiquibaseAw
Further details are available at deactivatable.
+=== SPI
-== SPI
-
-
-=== ExternalContainer
+==== ExternalContainer
org.apache.deltaspike.testcontrol.spi.ExternalContainer allows to
integrate containers which get started after the CDI container.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/site/src/main/asciidoc/steps_for_a_release.adoc
----------------------------------------------------------------------
diff --git a/site/src/main/asciidoc/steps_for_a_release.adoc b/site/src/main/asciidoc/steps_for_a_release.adoc
index d9d91dc..d7fdd73 100644
--- a/site/src/main/asciidoc/steps_for_a_release.adoc
+++ b/site/src/main/asciidoc/steps_for_a_release.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Preparations
@@ -41,7 +41,7 @@ mvn clean install -Pwildfly-build-managed
mvn clean install -Pglassfish-build-managed-3
-----------------------------------------------------------------------------------------------------------------------
-deploy a demo app esp. with jsf-impl-ee6 to an ee6 server and check the logs (if there are no optional ee7+ classes)
+deploy a demo app especially with jsf-impl-ee6 to an ee6 server and check the logs (if there are no optional ee7+ classes)
(https://github.com/os890/ee6-ds-demo can be used for it e.g.)
== First steps
@@ -52,7 +52,7 @@ git checkout -b deltaspike-[release version]
mvn release:prepare -Pdistribution -DreleaseProfiles=distribution
-//hint: don't use -DdryRun=true -- since it can break the next step
+//hint: dois not use -DdryRun=true -- since it can break the next step
mvn release:perform -Pdistribution -DreleaseProfiles=distribution
//!!!check the created commits including user-name and email
@@ -61,7 +61,7 @@ mvn release:perform -Pdistribution -DreleaseProfiles=distribution
//check esp. .../org/apache/deltaspike/deltaspike-project/[version]/deltaspike-project-[version]-source-release.zip
//close the repository
-//push the release-branch and tag to a 3rd party git repo
+//push the release-branch and tag to a third-party git repo
git remote add vote https://github.com/[user]/deltaspike-vote
git push -u vote master
git push vote deltaspike-[release version]
@@ -70,7 +70,7 @@ git push vote --tags
== Vote
-=== Start the vote
+=== Start the Vote
e.g.:
@@ -106,14 +106,14 @@ Thanks,
[4] http://www.apache.org/foundation/voting.html#ReleaseVotes
-----------------------------------------------------------------------------------------------------------------------
-== Announce the vote
+== Announce the Vote
- Create a link to the release notes at http://s.apache.org (format DeltaSpike_[version])
- Tweet about the vote via @DeltaSpikeTeam.
== Perform the final release
-=== Close the vote
+=== Close the Vote
After 72 hours close the vote.
@@ -159,8 +159,7 @@ git push origin master
- Wait some hours and check http://repo2.maven.org/maven2/org/apache/deltaspike
-
-=== Upload artifacts
+=== Upload Artifacts
-----------------------------------------------------------------------------------------------------------------------
svn co https://dist.apache.org/repos/dist/release/deltaspike
@@ -168,7 +167,7 @@ mkdir [version]
//add and commit the artifacts (at least *source-release.zip + asc, md5, sha1)
-----------------------------------------------------------------------------------------------------------------------
-=== Check downloads
+=== Check Downloads
- http://www.eu.apache.org/dist/deltaspike
- http://www.us.apache.org/dist/deltaspike
@@ -183,7 +182,7 @@ via CMS:
=== Announce the Release
-==== E-Mails
+==== E-mails
-----------------------------------------------------------------------------------------------------------------------
[7/9] deltaspike git commit: DELTASPIKE-690: Edited background
section in overview.adoc
Posted by ra...@apache.org.
DELTASPIKE-690: Edited background section in overview.adoc
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/0a034dd8
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/0a034dd8
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/0a034dd8
Branch: refs/heads/master
Commit: 0a034dd8dae84b41e9a61474748badfe5ce79ec1
Parents: 548383b
Author: michellemurray <mm...@redhat.com>
Authored: Wed Nov 26 17:52:09 2014 +1000
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Dec 15 20:24:45 2014 -0200
----------------------------------------------------------------------
documentation/src/main/asciidoc/overview.adoc | 35 +++++++++++++++++-----
1 file changed, 28 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/0a034dd8/documentation/src/main/asciidoc/overview.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/overview.adoc b/documentation/src/main/asciidoc/overview.adoc
index 09163b6..dd92304 100644
--- a/documentation/src/main/asciidoc/overview.adoc
+++ b/documentation/src/main/asciidoc/overview.adoc
@@ -4,19 +4,40 @@
:toc:
-== Background: Portable CDI Extensions
-Contexts and Dependency Injection (CDI) for Java EE (link:https://jcp.org/en/jsr/detail?id=299[JSR 299]) was introduced as part of Java EE6. It defines a collection of Java services that provides the foundation for frameworks, extensions, and integration with other technologies.
-Portable CDI extensions extend CDI implementations and improve existing Java EE APIs by enabling integration of different technologies. They can be used with any spec-compliant CDI implementation, such as JBoss Weld or Apache OpenWebBeans. The CDI container manages start and stop procedures, web beans, lifecycles, and injections. This means portable CDI extension injections can be handled by the container instead of the user.
+== Background
-== About DeltaSpike
-DeltaSpike is a collection of portable CDI extensions. These ready-to-use modules are created by the community and provide a method of integrating tested API extensions into your Java projects.
+=== CDI
+Java Contexts and Dependency Injection for the Java EE platform (link:https://jcp.org/en/jsr/detail?id=299[JSR 299]), abbreviated to CDI, was introduced as part of Java EE6. The core features of CDI are as follows:
+
+* improved stateful object lifecycles with an additional context named _Conversation_ that encompasses a series of requests within one session and lifecycle management by the container according to well-defined contexts
+* dependency injection conducted in a type-safe manner, with type checking conducted at compilation time so errors are exposed earlier and debugging is easier
+* event notification facility for object interaction
+* a better approach for interceptors with annotations binding interceptors to objects and with a new interceptor named _decorator_ that knows about individual bean attributes through inheritence and is more appropriate for use in solving business problems
+* a Service Provider Interface (SPI) for developing portable extensions to the CDI container
+
+CDI is a link:https://jcp.org/en/home/index[Java Community Process (JCP)] standard. All Java EE6 compliant application servers must provide support for CDI. link:http://weld.cdi-spec.org/[JBoss Weld] is a reference implementation of the CDI specification and other spec-compliant implementations exist such as link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)]. While CDI is a Java EE6 essential, CDI can also be used in Java SE environments with the aid of standalone CDI implementations.
+
+=== Portable CDI Extensions
+The CDI Service Provider Interface (SPI) is exposed to enable extension of the CDI feature set by third-parties. Portable CDI extensions extend CDI implementations and improve existing Java EE APIs by enabling integration of different technologies.
+
+As set out in the CDI specification, a portable CDI extenstion may integrate with a CDI container as follows:
+
+* providing its own beans, interceptors and decorators to the container
+* injecting dependencies into its own objects using the dependency injection service
+* providing a context implementation for a custom scope
+* augmenting or overriding the annotation-based metadata with metadata from some other source
+
+As indicated by the name, _portable_ CDI extensions can be used with any spec-compliant CDI implementation.
+
+== About Apache DeltaSpike
+Apache DeltaSpike is a collection of portable CDI extensions. These ready-to-use modules enable you to integrate tested API extensions into your Java projects.
DeltaSpike consists of a core module and a number of optional modules for providing additional enterprise functionality to your applications. The modules include features for enhanced security with type-safe control over method invocations, integration with schedulers, injection of CDI objects into validators, and a transactional context and scope. DeltaSpike also provides boot and shutdown control over CDI containers in Java SE applications.
-As portable CDI extensions, DeltaSpike requires a CDI implementation and supports both JBoss Weld and Apache OpenWebBeans. DeltaSpike has also been tested on a range of application servers and containers that provide these CDI implementations, such as Apache TomEE, JBoss AS, WildFly, Oracle GlassFish, and Jetty.
+As a CDI extension, DeltaSpike must be used in conjunction with a CDI implementation and supports both JBoss Weld and Apache OpenWebBeans. DeltaSpike has been tested on a range of application servers and containers that utilize these CDI implementations, such as Apache TomEE, JBoss AS, WildFly, Oracle GlassFish, and Jetty.
-In addition to the portable CDI extension modules, DeltaSpike provides a number of examples to assist you in understanding how to use and get the most from this technology.
+In addition to the portable CDI extension modules, DeltaSpike provides a number of examples to show you how to use and get the most from this technology.
== Features of DeltaSpike
[8/9] deltaspike git commit: DELTASPIKE-690: General text
imporvements to 'Get Started' pages
Posted by ra...@apache.org.
DELTASPIKE-690: General text imporvements to 'Get Started' pages
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/427897c3
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/427897c3
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/427897c3
Branch: refs/heads/master
Commit: 427897c3ab4f2208ca11f924d747df18883480f1
Parents: 0a034dd
Author: michellemurray <mm...@redhat.com>
Authored: Tue Dec 2 13:49:52 2014 +1000
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Dec 15 20:24:45 2014 -0200
----------------------------------------------------------------------
documentation/src/main/asciidoc/cdiimp.adoc | 47 +++++++++------------
documentation/src/main/asciidoc/configure.adoc | 12 +++---
documentation/src/main/asciidoc/examples.adoc | 32 +-------------
documentation/src/main/asciidoc/index.adoc | 4 +-
4 files changed, 30 insertions(+), 65 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/cdiimp.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/cdiimp.adoc b/documentation/src/main/asciidoc/cdiimp.adoc
index 6d6acbd..9b63d6f 100644
--- a/documentation/src/main/asciidoc/cdiimp.adoc
+++ b/documentation/src/main/asciidoc/cdiimp.adoc
@@ -4,7 +4,7 @@
:toc:
-DeltaSpike requires a CDI implementation to be available in the Java environment that your projects are deployed to. The implementation provides the CDI essentials, managing dependency injection and contextual lifecycles. link:http://weld.cdi-spec.org/[JBoss Weld] and link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)] are two widely used CDI implementations. Dependent on the Java environment you choose, some setup may be necessary as detailed here.
+DeltaSpike requires a CDI implementation to be available in the Java environment where your projects are deployed. The implementation provides the CDI essentials, managing dependency injection and contextual lifecycles. link:http://weld.cdi-spec.org/[JBoss Weld] and link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)] are two widely used CDI implementations. Dependent on the Java environment you choose, some setup may be necessary as detailed here.
== Java EE6+ Containers
CDI is part of Java EE6 and later so CDI implementations are included as standard in Java EE6+ compliant environments. There is no additional CDI configuration needed besides including the CDI-obligatory `beans.xml` file in your project.
@@ -23,7 +23,9 @@ DeltaSpike provides a dedicated Container Control module to enable applications
Instructions are provided here for adding the required resources to both Maven-based and Maven-independent projects and subsequently booting the CDI container from your project source code.
-=== Declare Dependencies for Maven-based Projects
+=== 1. Declare CDI Dependencies
+
+==== Option A: Declare Dependencies for Maven-based Projects
For Maven-based projects, the Container Control module is available in Maven Central together with the other DeltaSpike modules. You must configure your project to use the DeltaSpike Container Control API and one of the CDI container-specific modules.
. Open the project `pom.xml` file for editing
@@ -41,10 +43,9 @@ For Maven-based projects, the Container Control module is available in Maven Cen
+
. Add CDI container dependencies for one of the container options listed here
-==== Option A: For JBoss Weld
-
-. Open the project `pom.xml` file for editing
-. Add the JBoss Weld version to the list of properties, replacing the version as desired
++
+.For JBoss Weld
+a. Add the JBoss Weld version to the list of properties, replacing the version as desired
+
[source,xml]
----
@@ -53,7 +54,7 @@ For Maven-based projects, the Container Control module is available in Maven Cen
</properties>
----
+
-. Add the JBoss Weld dependency to the list of dependencies
+b. Add the JBoss Weld dependency to the list of dependencies
+
[source,xml]
----
@@ -65,7 +66,7 @@ For Maven-based projects, the Container Control module is available in Maven Cen
</dependency>
----
+
-. Add the DeltaSpike Weld-specific Container Control module to the list of dependencies
+c. Add the DeltaSpike Weld-specific Container Control module to the list of dependencies
+
[source,xml]
----
@@ -76,18 +77,10 @@ For Maven-based projects, the Container Control module is available in Maven Cen
<scope>runtime</scope>
</dependency>
----
-+
-. Save the `pom.xml` file changes
-. Download all required dependencies
-+
-----
-mvn clean install
-----
-
-==== Option B: For Apache OpenWebBeans
-. Open the project `pom.xml` file for editing
-. Add the Apache OpenWebBeans version to the list of properties, replacing the version as desired
++
+.For Apache OpenWebBeans
+a. Add the Apache OpenWebBeans version to the list of properties, replacing the version as desired
+
[source,xml]
----
@@ -96,7 +89,7 @@ mvn clean install
</properties>
----
+
-. Add the Apache OpenWebBeans dependencies to the list of dependencies
+b. Add the Apache OpenWebBeans dependencies to the list of dependencies
+
[source,xml]
----
@@ -115,7 +108,7 @@ mvn clean install
</dependency>
----
+
-. Add the DeltaSpike Apache OpenWebBeans-specific Container Control module to the list of dependencies
+c. Add the DeltaSpike Apache OpenWebBeans-specific Container Control module to the list of dependencies
+
[source,xml]
----
@@ -126,7 +119,7 @@ mvn clean install
<scope>runtime</scope>
</dependency>
----
-+
+
. Save the `pom.xml` file changes
. Download all required dependencies
+
@@ -134,12 +127,12 @@ mvn clean install
mvn clean install
----
-=== Declare Dependencies for Maven-independent Projects
+==== Option B: Declare Dependencies for Maven-independent Projects
For Maven-independent projects, the Container Control module is distributed together with the other DeltaSpike modules in `distribution-fill-<version>.zip`. You must add two of the files from the `cdictrl` directory to your project, namely `deltaspike-cdictrl-api.jar` and the .jar file that corresponds to the CDI container you have chosen. Add these files to the project `WEB-INF/lib` or `EAR/lib` directory for .war and .ear projects respectively.
-=== Start the CDI Container from Your Project
+=== 2. Start the CDI Container from Your Project
To start a CDI container in your application, you must instantiate a `CdiContainer` object and call the `#boot` method. When `#boot` is called, the `CdiContainer` scans CDI-enabled
-archives for beans and CDI extensions. An example is given in the code snippet here. Before the application exits, `#shutdown` must be called to correctly destroy all beans.
+archives for beans and CDI extensions. Before the application exits, `#shutdown` must be called to correctly destroy all beans. An example is given in the code snippet here.
[source,java]
----
@@ -174,7 +167,7 @@ public class MainApp {
CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
cdiContainer.boot();
- // Starting the application-context allows to use @ApplicationScoped beans
+ // Starting the application-context enables use of @ApplicationScoped beans
ContextControl contextControl = cdiContainer.getContextControl();
contextControl.startContext(ApplicationScoped.class);
@@ -185,7 +178,7 @@ public class MainApp {
}
----
-To resolve project beans, you can use the DeltaSpike `BeanProvider` class. Whether `EchoService` is a concrete implementation or just an interface depends on the application. In the case that it is an interface, the corresponding implementation is resolved. The resolved bean is a standard CDI bean and it can be used for all CDI concepts, such as @Inject, in the class without further uses of `BeanProvider`. An example of resolving the bean without qualifiers is given in the code snippet here.
+To resolve project beans, you can use the DeltaSpike `BeanProvider` class. Whether `EchoService` is a concrete implementation or just an interface depends on the application. In the case that it is an interface, the corresponding implementation is resolved. The resolved bean is a standard CDI bean and it can be used for all CDI concepts, such as `@Inject`, in the class without further uses of `BeanProvider`. An example of resolving the bean without qualifiers is given in the code snippet here.
[source,java]
----
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/configure.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configure.adoc b/documentation/src/main/asciidoc/configure.adoc
index df99230..3c8b4ff 100644
--- a/documentation/src/main/asciidoc/configure.adoc
+++ b/documentation/src/main/asciidoc/configure.adoc
@@ -6,9 +6,9 @@
DeltaSpike is available for use in Maven-based and Maven-independent projects. Instructions are given here for obtaining released final versions of DeltaSpike for both approaches.
-**Note:** You can also opt to use the lastest DeltaSpike snapshots; for more information, see <<snapshots#,Test Snapshots>>.
+**Note:** You can also opt to use the lastest DeltaSpike snapshots; for more information, see <<snapshots#,Use DeltaSpike Snapshots>>.
-== Configure DeltaSpike in Maven-based Projects
+== Option A: Configure DeltaSpike in Maven-based Projects
DeltaSpike released versions are available from the Maven Central repository for use in Maven-based projects. This means that you do not need to modify your Maven configuration `settings.xml` file; when building projects, Maven automatically searches the online Maven Central repository for project dependencies and downloads sources to your local Maven repository.
To begin use the DeltaSpike releases from Maven Central, you simply need to configure the project `pom.xml` file for each project with information about the release version and modules you want to use. At a minimum, you must add the DeltaSpike Core module, which provides the DeltaSpike API and utility classes.
@@ -57,7 +57,7 @@ For instructions on adding the optional DeltaSpike modules, see the relevant mod
* <<servlet#,Servlet>>
* <<test-control#,Test-Control>>
-== Configure DeltaSpike in Maven-independent Projects
+== Option B: Configure DeltaSpike in Maven-independent Projects
Deltaspike is provided as a set of downloadable .jar files for projects not utilizing the Maven build system. Alternatively, you can build the DeltaSpike .jar files from source; for instructions, see <<build#,Build DeltaSpike from Source>>. In both cases, you must add the DeltaSpike .jar files directly to your projects.
To use DeltaSpike without Maven from the downloadable .jar files, complete the following steps:
@@ -71,8 +71,8 @@ $ unzip distribution-full-<version>.zip
----
+
. Add the source to your project
- .. For .war projects, copy the .jar files to `WEB-INF/lib` directory
- .. For .ear projects, copy the .jar files to `EAR/lib directory` and add the following to `META-INF/application.xml`:
+a. For .war projects, copy the .jar files to the `WEB-INF/lib` directory
+b. For .ear projects, copy the .jar files to the `EAR/lib directory` and add the following to `META-INF/application.xml`:
+
[source,xml]
----
@@ -80,6 +80,6 @@ $ unzip distribution-full-<version>.zip
----
== Next
-* To check whether your Java envrionment needs any additional CDI-specific configuration, see <<cdiimp#,Enable CDI For Your Java Environment>>.
+* To check whether your Java environment needs any additional CDI-specific configuration, see <<cdiimp#,Enable CDI For Your Java Environment>>.
* To see ready-to-deploy example DeltaSpike applications, see <<examples#,See DeltaSpike in Action>>.
* To understand how the various DeltaSpike modules can enhance and extend your applications, see the individual module pages.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/examples.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/examples.adoc b/documentation/src/main/asciidoc/examples.adoc
index 2ba01eb..aaeb557 100644
--- a/documentation/src/main/asciidoc/examples.adoc
+++ b/documentation/src/main/asciidoc/examples.adoc
@@ -4,7 +4,7 @@
:toc:
-A collection of ready-to-build Maven-based projects are provided to demonstrate the inclusion of DeltaSpike in applications. Each example showcases a different DeltaSpike feature and explores the mechanics of DeltaSpike implementation. You can use these examples to see DeltaSpike in action and learn how to add these capabilities to your own projects. The Maven-based project examples are available in `deltaspike-project-<version>-source-release.zip` and each is briefly outlined here.
+A collection of ready-to-build Maven-based projects are provided to demonstrate the inclusion of DeltaSpike in applications. Each example showcases a different DeltaSpike feature and explores the mechanics of DeltaSpike implementation. You can use these examples to see DeltaSpike in action and learn how to add these capabilities to your own projects. The Maven-based project examples are available in `deltaspike-project-<version>-source-release.zip`.
To begin using the projects, complete the following steps:
@@ -22,32 +22,4 @@ $ unzip deltaspike-project-<version>-source-release.zip
----
$ cd /path/to/deltaspike-project-<version>/examples
$ mvn clean package
-----
-
-== jse-examples
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
-
-== jsf-examples
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
-
-== jsf-playground
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
-
-== scheduler-playground
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
\ No newline at end of file
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/427897c3/documentation/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/index.adoc b/documentation/src/main/asciidoc/index.adoc
index eec24a1..c83cfc9 100644
--- a/documentation/src/main/asciidoc/index.adoc
+++ b/documentation/src/main/asciidoc/index.adoc
@@ -2,12 +2,12 @@
: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.
-* Getting Started
+* Get Started
** <<overview#,Overview of DeltaSpike>>
** <<configure#,Configure DeltaSpike in Your Projects>>
** <<cdiimp#,Enable CDI For Your Java Environment>>
** <<examples#,See DeltaSpike in Action>>
-* Using Individual Modules
+* Use Individual Modules
** <<core#,Core>>
** <<bean-validation#,Bean Validation>>
** <<container-control#,Container Control>>
[4/9] deltaspike git commit: DELTASPIKE-690: More edits to existing
adoc
Posted by ra...@apache.org.
DELTASPIKE-690: More edits to existing adoc
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/9f897b75
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/9f897b75
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/9f897b75
Branch: refs/heads/master
Commit: 9f897b757bb6a95182e389234647ce00c3a0ce2b
Parents: 427897c
Author: michellemurray <mm...@redhat.com>
Authored: Wed Dec 3 16:44:53 2014 +1000
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Dec 15 20:24:45 2014 -0200
----------------------------------------------------------------------
documentation/src/main/asciidoc/addons.adoc | 25 ++----
documentation/src/main/asciidoc/build.adoc | 9 +--
documentation/src/main/asciidoc/cdiimp.adoc | 4 +-
documentation/src/main/asciidoc/configure.adoc | 2 +-
documentation/src/main/asciidoc/examples.adoc | 6 +-
documentation/src/main/asciidoc/external.adoc | 49 ++++--------
documentation/src/main/asciidoc/index.adoc | 8 +-
documentation/src/main/asciidoc/modules.adoc | 23 ++++++
documentation/src/main/asciidoc/overview.adoc | 2 +-
documentation/src/main/asciidoc/snapshots.adoc | 6 +-
documentation/src/main/asciidoc/source.adoc | 89 +++++++++------------
documentation/src/main/asciidoc/spi.adoc | 73 +++++------------
12 files changed, 126 insertions(+), 170 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/addons.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/addons.adoc b/documentation/src/main/asciidoc/addons.adoc
index 94d0716..05ad2bc 100644
--- a/documentation/src/main/asciidoc/addons.adoc
+++ b/documentation/src/main/asciidoc/addons.adoc
@@ -7,29 +7,16 @@
Add-ons extend the functionality of DeltaSpike and several have been developed external to the DeltaSpike project. Brief information is given here about each of the add-ons, with details of where they can be obtained from.
== Monitoring
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+`ds-monitoring-addon` provides simple monitoring for several common use-cases (exceptions, performance, audits), collecting information about the monitored method-invocations during a request and enabling you to process the entries based on your requirements. For more information about its use and implementation, see http://os890.blogspot.com.au/2014/04/add-on-monitoring-lite-with-deltaspike.html[os890: [add-on\] monitoring lite with deltaspike].
-* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
-* When would the user use this add-on?
-* Where can the user get the add-on from (https://github.com/os890/ds-monitoring-addon )?
-* Any special instructions for using the add-on correctly?
+**Source code:** https://github.com/os890/ds-monitoring-addon
== Spring Bridge
-`ds-spring-bridge-addon` is a two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible. You can obtain this add-on from https://github.com/os890/ds-spring-bridge-addon.
+`ds-spring-bridge-addon` is a two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible. For more information about its use and implementation, see http://os890.blogspot.com.au/2013/12/add-on-spring-bridge-with-deltaspike.html[os890: [add-on\] spring-bridge with deltaspike].
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
-* When would the user use this add-on?
-* Where can the user get the add-on from (https://github.com/os890/ds-spring-bridge-addon )?
-* Any special instructions for using the add-on correctly?
+**Source code:** https://github.com/os890/ds-spring-bridge-addon.
== Disruptor
-This add-on creates a disruptor process for every observer method. It currently works with Apache TomEE and JBoss AS 7.
-
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+`ds-disruptor-addon` improves CDI synchronous event-processing performance by creating a disruptor process for every observer method, enabling CDI synchronous events in conjunction with asynchronous observers. This add-on currently works with Apache TomEE and JBoss AS 7. For more information about its use and implementation, see http://os890.blogspot.com.au/2014/05/faster-cdi-like-events.html[os890: [add-on\] fast event processing with disruptor + deltaspike].
-* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
-* When would the user use this add-on?
-* Where can the user get the add-on from (https://github.com/os890/ds-disruptor-addon )?
-* Any special instructions for using the add-on correctly?
+**Source code:** https://github.com/os890/ds-disruptor-addon
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/build.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/build.adoc b/documentation/src/main/asciidoc/build.adoc
index 9ebca70..8d08f5c 100644
--- a/documentation/src/main/asciidoc/build.adoc
+++ b/documentation/src/main/asciidoc/build.adoc
@@ -4,11 +4,11 @@
:toc:
-The DeltaSpike source (modules and examples) is provided for inspection, contribution and testing purposes. The source must be built with Maven, which has been used to automate the compilation, testing and packaging processes. Arquillian tests are automatically conducted when DeltaSpike is built and CDI implementations or containers with which to carry out the tests can be specified.
+The DeltaSpike source (modules and examples) is provided for inspection, contribution and testing purposes. The source must be built with Maven, which has been used to automate the compilation, testing and packaging processes. Arquillian tests are included with the source and a CDI implementation or container can be specified with which to carry out the tests.
-In all cases, to obtain the DeltaSpike source, link:https://deltaspike.apache.org/download.html[download `deltaspike-project-<version>-source-release.zip`] and extract the contents.
+In all cases, to obtain the DeltaSpike source, link:https://deltaspike.apache.org/download.html[download] `deltaspike-project-<version>-source-release.zip` and extract the contents.
-**Note:** You can also obtain the DeltaSpike source from the project Git repository. The repository is subject to change and it can be used for contributing but should not be used in production environments. For more information, see <<source#,Get Source and compile it>>.
+**Note:** You can also obtain the DeltaSpike source from the project Git repository. The repository is subject to change and it can be used for contributing but should not be used in production environments. For more information, see <<source#,Contribute to the DeltaSpike Source>>.
== Build without CDI Implementation Tests
DeltaSpike can be built without executing tests against a CDI implementation, with the following commands:
@@ -42,8 +42,7 @@ $ mvn clean install -POWB
----
|===
-
-== Build and Test with CDI Containers
+== Build and Test with a CDI Container
Tests can be executed with JBoss Weld and Apache OpenWebBeans through Java EE 6+ application servers and containers. Configurations are currently provided as details in the table here.
[cols="2,3a", options="header"]
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/cdiimp.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/cdiimp.adoc b/documentation/src/main/asciidoc/cdiimp.adoc
index 9b63d6f..103ea8a 100644
--- a/documentation/src/main/asciidoc/cdiimp.adoc
+++ b/documentation/src/main/asciidoc/cdiimp.adoc
@@ -186,4 +186,6 @@ EchoService echoService = BeanProvider.getContextualReference(EchoService.class,
----
== Next
-* For more information about the Container Control module, see <<container-control#,Container Control Module>>.
\ No newline at end of file
+* For more information about the Container Control module, see <<container-control#,Container Control Module>>.
+* To understand how the various DeltaSpike modules can enhance and extend your applications, see <<modules#,Overview of DeltaSpike Modules>> and the individual module pages.
+* To see ready-to-deploy example DeltaSpike applications, see <<examples#,See DeltaSpike in Action>>.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/configure.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configure.adoc b/documentation/src/main/asciidoc/configure.adoc
index 3c8b4ff..bb6db2e 100644
--- a/documentation/src/main/asciidoc/configure.adoc
+++ b/documentation/src/main/asciidoc/configure.adoc
@@ -82,4 +82,4 @@ b. For .ear projects, copy the .jar files to the `EAR/lib directory` and add the
== Next
* To check whether your Java environment needs any additional CDI-specific configuration, see <<cdiimp#,Enable CDI For Your Java Environment>>.
* To see ready-to-deploy example DeltaSpike applications, see <<examples#,See DeltaSpike in Action>>.
-* To understand how the various DeltaSpike modules can enhance and extend your applications, see the individual module pages.
+* To understand how the various DeltaSpike modules can enhance and extend your applications, see <<modules#,Overview of DeltaSpike Modules>> and the individual module pages.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/examples.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/examples.adoc b/documentation/src/main/asciidoc/examples.adoc
index aaeb557..57c5c5e 100644
--- a/documentation/src/main/asciidoc/examples.adoc
+++ b/documentation/src/main/asciidoc/examples.adoc
@@ -22,4 +22,8 @@ $ unzip deltaspike-project-<version>-source-release.zip
----
$ cd /path/to/deltaspike-project-<version>/examples
$ mvn clean package
-----
\ No newline at end of file
+----
+
+== Next
+* To see more ready-to-deploy DeltaSpike examples and templates, see <<external#,External Examples>>.
+* To read how DeltaSpike is being used by developers, see <<articles#,Articles and Blogs>>.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/external.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/external.adoc b/documentation/src/main/asciidoc/external.adoc
index 8a2a1f8..3420d27 100644
--- a/documentation/src/main/asciidoc/external.adoc
+++ b/documentation/src/main/asciidoc/external.adoc
@@ -4,19 +4,21 @@
:toc:
-A number of DeltaSpike examples and templates have been developed external to the DeltaSpike project. These extend the DeltaSpike resources from which you can see DeltaSpike in action. Brief information is given here about each of the examples and templates, with details of where they can be obtained from.
+A number of DeltaSpike examples and templates have been developed external to the DeltaSpike project. These extend the DeltaSpike resources from which you can see DeltaSpike in action. Brief information is given here about the examples and templates, with details of where they can be obtained from.
-== Example: Confess 2012 Workshop Demo
+== Examples
+
+=== Confess 2012 Workshop Demo
This example was prepared for the Confess workshop and demonstrates how to use DeltaSpike instead of and side-by-side with MyFaces CODI. The secured web application demonstrates presenting users with differentiating content based on their account status.
**Source code:** https://github.com/confess/confess2012_deltaspike
-== Example: Fullstack EE6+ with DeltaSpike
+=== Fullstack EE6+ with DeltaSpike
Simple example based on Java EE6+ and DeltaSpike (tested with EE6 and EE7).
**Source code:** https://github.com/os890/ee6-ds-demo
-== Example: Fullstack CODI to DeltaSpike
+=== Fullstack CODI to DeltaSpike
This pair of examples show how to achieve the most important MyFaces CODI features with DeltaSpike and also how to migrate a CODI project to DeltaSpike. The examples are basic, compacting core CODI features into just a few JSF pages, and are intended for deployment with TomEE.
**Source code:** https://github.com/os890/tomee_mf_stack_001
@@ -24,40 +26,21 @@ This pair of examples show how to achieve the most important MyFaces CODI featur
* CODI version in master branch
* Migrated DeltaSpike version in codi2ds branch
-== Examples: JBoss Web Framework Kit Quickstarts
+=== JBoss Quickstarts
The JBoss quickstarts are small working examples that demonstrate recommended practices for specific Java EE technology use cases. A subset of these quickstarts are dedicated to demonstrating DeltaSpike, including custom authorization restrictions using annotations, constructing and modifying beans, extending the influence of CDI using BeanManager, and deactivating DeltaSpike features.
**Source code:** https://github.com/jboss-developer/jboss-wfk-quickstarts
-== Template: Java SE + CDI + DS
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javase-cdi-ds-project-template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
-
-== Template: JSF + CDI + DS (Servlet-Container)
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+== Templates
+=== Java SE + CDI + DS
+**Source code:** https://github.com/os890/javase-cdi-ds-project-template
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javaweb-cdi-ds-project-template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+=== JSF + CDI + DS (Servlet-Container)
+**Source code:** https://github.com/os890/javaweb-cdi-ds-project-template
-== Template: EJB + CDI + DS (Module)
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
-
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javaee_cdi_ejb_ds_project_template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
-
-== Template: JSF + EJB + CDI + DS (EE-Server)
-**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+=== EJB + CDI + DS (Module)
+**Source code:** https://github.com/os890/javaee_cdi_ejb_ds_project_template
-* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
-* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
-* Where can the user get the template from (https://github.com/os890/javaee_jsf_cdi_ejb_ds_project_template )?
-* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+=== JSF + EJB + CDI + DS (EE-Server)
+**Source code:** https://github.com/os890/javaee_jsf_cdi_ejb_ds_project_template
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/index.adoc b/documentation/src/main/asciidoc/index.adoc
index c83cfc9..5ad6044 100644
--- a/documentation/src/main/asciidoc/index.adoc
+++ b/documentation/src/main/asciidoc/index.adoc
@@ -8,6 +8,7 @@
** <<cdiimp#,Enable CDI For Your Java Environment>>
** <<examples#,See DeltaSpike in Action>>
* Use Individual Modules
+** <<modules#,Overview of DeltaSpike Modules>>
** <<core#,Core>>
** <<bean-validation#,Bean Validation>>
** <<container-control#,Container Control>>
@@ -20,11 +21,12 @@
** <<servlet#,Servlet>>
** <<test-control#,Test-Control>>
* Advanced Information
-** <<build#,Build DeltaSpike from Source>>
+** <<build#,Build and Test DeltaSpike from Source>>
** <<snapshots#,Use DeltaSpike Snapshots>>
** link:https://deltaspike.apache.org/migration-guide.html[Migrate to DeltaSpike]
+** <<source#,Contribute to the DeltaSpike Source>>
** <<spi#,DeltaSpike Service Provider Interface (SPI)>>
-* More Resources
+* Access More DeltaSpike Resources
** <<articles#,Articles and Blogs>>
** <<addons#,Add-ons>>
-** <<external#,External Examples>>
\ No newline at end of file
+** <<external#,External Examples>>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/modules.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/modules.adoc b/documentation/src/main/asciidoc/modules.adoc
new file mode 100644
index 0000000..a7a74fd
--- /dev/null
+++ b/documentation/src/main/asciidoc/modules.adoc
@@ -0,0 +1,23 @@
+= Overview of DeltaSpike Modules
+
+: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:
+
+DeltaSpike consists of ready-to-use modules. These include a core module and a number of optional modules for providing additional enterprise functionality to your applications. An overview of each module is provided here and for more information see the linked individual module pages.
+
+[cols="1,1,2a"]
+.DeltaSpike Modules
+|===
+|<<core#,Core>> | Required | For the essential API and util classes
+|<<bean-validation#,Bean Validation>> | Optional | For adding CDI support in Bean Validation, enabling creation of CDI aware `ConstraintValidator` methods that can use business objects (EJBs, ManagedBeans) to support validation needs
+|<<container-control#,Container Control>> | Optional |
+|<<data#,Data>> | Optional | For an enhanced JPA experience with declarative queries, reducing boilerplate to a minimum
+|<<jpa#,JPA>> | Optional |
+|<<jsf#,JSF>> | Optional |
+|<<partial-bean#,Partial-Bean>> | Optional |
+|<<scheduler#,Scheduler>> | Optional | For simple integration with Quartz v2 (per default) or any other scheduler which supports cron-expressions for job-classes
+|<<security#,Security>> | Optional | For intercept and check security
+|<<servlet#,Servlet>> | Optional | For integration with the Java Servlet API, enabling injection of common servlet objects and propagation of servlet events to the CDI event bus
+|<<test-control#,Test-Control>> | Optional | For easily writing CDI based tests
+|===
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/overview.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/overview.adoc b/documentation/src/main/asciidoc/overview.adoc
index dd92304..01d2724 100644
--- a/documentation/src/main/asciidoc/overview.adoc
+++ b/documentation/src/main/asciidoc/overview.adoc
@@ -89,4 +89,4 @@ In addition to the portable CDI extension modules, DeltaSpike provides a number
*Type-safe Project-Stages:* Compared to project-stages in JSF, DeltaSpike provides a type-safe, but still extensible approach which can be used in CDI based applications.
== Next
-For instructions on how to start using DeltaSpike, see <<configure#,Configure DeltaSpike in Your Projects>>.
+For instructions on how to start using DeltaSpike, see <<configure#,Configure DeltaSpike in Your Projects>> and <<cdiimp#,Enable CDI For Your Java Environment>>.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/snapshots.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/snapshots.adoc b/documentation/src/main/asciidoc/snapshots.adoc
index df99e68..4ee98ed 100644
--- a/documentation/src/main/asciidoc/snapshots.adoc
+++ b/documentation/src/main/asciidoc/snapshots.adoc
@@ -8,10 +8,10 @@ If you want to be at the bleeding edge, you can work with DeltaSpike snapshots.
**Warning:** Snapshots provide previews of DeltaSpike during development. Snapshots are subject to change and may not yet include all expected features of the final release. Snapshots should not be used in production environments.
-== Configure Maven to Use the Apache Snapshot Repository
+== 1. Configure Maven to Use the Apache Snapshot Repository
You must add the Apache Snapshot Repository to your Maven configuration `settings.xml` file. This ensures Maven can find the repository when it searches for your project DeltaSpike dependencies.
-. Open Maven configuration `settings.xml` file for editing
+. Open your Maven configuration `settings.xml` file for editing
. Add the Apache Snapshot Repository to the list of repositories
+
[source,xml]
@@ -33,7 +33,7 @@ You must add the Apache Snapshot Repository to your Maven configuration `setting
. Save the `settings.xml` file changes
-== Configure Your Project with the Snapshot Version
+== 2. Configure Your Project with the Snapshot Version
With Maven configured for the Apache Snapshot Repository, you can specify DeltaSpike snapshot versions in your Maven-based projects.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/source.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/source.adoc b/documentation/src/main/asciidoc/source.adoc
index aa80103..ad63f9e 100644
--- a/documentation/src/main/asciidoc/source.adoc
+++ b/documentation/src/main/asciidoc/source.adoc
@@ -1,74 +1,65 @@
-= Get Source and compile it
+= Contribute to the DeltaSpike Source
: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
+If you are looking to contribute to the DeltaSpike source, you must start with the latest version of the code base. DeltaSpike source is stored in the Apache Git repository at https://git-wip-us.apache.org/repos/asf/deltaspike.git
-== SCM / Repository
+It is also important that you follow the git workflows we have established for the project to ensure efficient and clean collaboration as detailed here.
-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].
+== 1. Get the Source
-
-=== Initial 'checkout'
-
-----------------------------------------------------------------
+. Checkout the source
++
+[source]
+----
git clone https://git-wip-us.apache.org/repos/asf/deltaspike.git
-----------------------------------------------------------------
-
-=== Update existing clone
-
------------------
-git pull --rebase
------------------
-
-
-=== Read-only Mirrors
-
-==== GitHub-Mirror
-
-----------------------------------------------
+----
++
+or for a read-only mirror version
++
+[source]
+----
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>>
+----
++
+. Update the repository clone
++
+[source]
+----
+git pull --rebase
+----
-== Tools / IDE
+== 2. Make Additions and Changes to the Source
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...
+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
+
+== 3. Build the Source
+Always build and test your changes before you make pull requests to the DeltaSpike repository. For instructions on building the source and running Arquillian tests, see <<build#,Build and Test DeltaSpike from Source>>.
+
+
+== 4. Make a Pull Request
+Ensure your commits and pull requests follow the our established https://deltaspike.apache.org/suggested-git-workflows.html[DeltaSpike GIT workflow].
+
+== Git Resources
+For general information about Git and using Git, see the following:
+
+* http://wiki.apache.org/couchdb/Git_At_Apache_Guide[Git At Apache Guide]
+* http://git-wip-us.apache.org[Git at The ASF]
+* http://git.or.cz/course/svn.html[Git - SVN Crash Course]
+* http://git-scm.com/book[Pro Git]
+* https://help.github.com/articles/which-remote-url-should-i-use[GitHub: Which remote URL should I use?]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/9f897b75/documentation/src/main/asciidoc/spi.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/spi.adoc b/documentation/src/main/asciidoc/spi.adoc
index 3b8f63c..5a1c705 100644
--- a/documentation/src/main/asciidoc/spi.adoc
+++ b/documentation/src/main/asciidoc/spi.adoc
@@ -4,42 +4,20 @@
:toc:
-== Introduction
+DeltaSpike provides an Service Provider Interface (SPI) to enable you to extend it.
== 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.
+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
@@ -62,12 +40,7 @@ public class CustomClassDeactivator implements ClassDeactivator
}
----------------------------------------------------------------------------
-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`).
+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
@@ -89,17 +62,12 @@ fully qualified name of the interface
== 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.
+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
{
}
@@ -109,14 +77,11 @@ public class CustomBean
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.
+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.
-----------------------------------------------
+[source]
+----
custom.CustomBean=custom.AlternativeCustomBean
-----------------------------------------------
+----
[5/9] deltaspike git commit: DELTASPIKE-690: Addng reorganised and
rewritten content
Posted by ra...@apache.org.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/snapshots.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/snapshots.adoc b/documentation/src/main/asciidoc/snapshots.adoc
new file mode 100644
index 0000000..df99e68
--- /dev/null
+++ b/documentation/src/main/asciidoc/snapshots.adoc
@@ -0,0 +1,50 @@
+= Use DeltaSpike Snapshots
+
+: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:
+
+If you want to be at the bleeding edge, you can work with DeltaSpike snapshots. These are available from the Apache Snapshot Repository for use in Maven-based projects. To begin using them, you must configure Maven with the repository location and your projects with the snapshot version.
+
+**Warning:** Snapshots provide previews of DeltaSpike during development. Snapshots are subject to change and may not yet include all expected features of the final release. Snapshots should not be used in production environments.
+
+== Configure Maven to Use the Apache Snapshot Repository
+You must add the Apache Snapshot Repository to your Maven configuration `settings.xml` file. This ensures Maven can find the repository when it searches for your project DeltaSpike dependencies.
+
+. Open Maven configuration `settings.xml` file for editing
+. Add the Apache Snapshot Repository to the list of repositories
++
+[source,xml]
+----
+<repositories>
+ <repository>
+ <id>apache-snapshot-repository</id>
+ <url>http://repository.apache.org/snapshots/</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+</repositories>
+----
++
+. Save the `settings.xml` file changes
+
+
+== Configure Your Project with the Snapshot Version
+
+With Maven configured for the Apache Snapshot Repository, you can specify DeltaSpike snapshot versions in your Maven-based projects.
+
+. Open the project `pom.xml` file for editing
+. Add the DeltaSpike snapshot version to the list of properties
++
+[source,xml]
+----
+<properties>
+ <deltaspike.version>1.0.3-SNAPSHOT</deltaspike.version>
+</properties>
+----
++
+. Save the `pom.xml` file changes
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/source.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/source.adoc b/documentation/src/main/asciidoc/source.adoc
index 0039233..aa80103 100644
--- a/documentation/src/main/asciidoc/source.adoc
+++ b/documentation/src/main/asciidoc/source.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Introduction
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/spi.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/spi.adoc b/documentation/src/main/asciidoc/spi.adoc
index 80faf81..3b8f63c 100644
--- a/documentation/src/main/asciidoc/spi.adoc
+++ b/documentation/src/main/asciidoc/spi.adoc
@@ -2,9 +2,7 @@
: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]
-
+:toc:
== Introduction
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/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 bbc76e7..4f9936a 100644
--- a/documentation/src/main/asciidoc/test-control.adoc
+++ b/documentation/src/main/asciidoc/test-control.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Intro
[3/9] deltaspike git commit: DELTASPIKE-690: module adoc pages edited
Posted by ra...@apache.org.
DELTASPIKE-690: module adoc pages edited
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/10c4e88f
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/10c4e88f
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/10c4e88f
Branch: refs/heads/master
Commit: 10c4e88f0d807d27229c597940b15f6b1a2460b8
Parents: 9f897b7
Author: michellemurray <mm...@redhat.com>
Authored: Fri Dec 12 17:20:54 2014 +1000
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Dec 15 20:24:45 2014 -0200
----------------------------------------------------------------------
.../src/main/asciidoc/bean-validation.adoc | 37 +-
documentation/src/main/asciidoc/build.adoc | 2 +-
documentation/src/main/asciidoc/cdiimp.adoc | 1 +
.../src/main/asciidoc/configuration.adoc | 58 +--
documentation/src/main/asciidoc/configure.adoc | 7 +-
.../src/main/asciidoc/container-control.adoc | 84 ++-
documentation/src/main/asciidoc/core.adoc | 272 +++++-----
documentation/src/main/asciidoc/data.adoc | 255 ++++------
documentation/src/main/asciidoc/jpa.adoc | 151 +++---
documentation/src/main/asciidoc/jsf.adoc | 507 +++++++++----------
documentation/src/main/asciidoc/modules.adoc | 16 +-
documentation/src/main/asciidoc/overview.adoc | 6 +-
.../src/main/asciidoc/partial-bean.adoc | 36 +-
.../src/main/asciidoc/projectstage.adoc | 49 +-
documentation/src/main/asciidoc/scheduler.adoc | 65 ++-
documentation/src/main/asciidoc/security.adoc | 135 ++---
documentation/src/main/asciidoc/servlet.adoc | 69 ++-
documentation/src/main/asciidoc/snapshots.adoc | 2 +-
documentation/src/main/asciidoc/spi.adoc | 21 +-
.../src/main/asciidoc/test-control.adoc | 222 ++++----
site/src/main/asciidoc/steps_for_a_release.adoc | 21 +-
21 files changed, 995 insertions(+), 1021 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/bean-validation.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/bean-validation.adoc b/documentation/src/main/asciidoc/bean-validation.adoc
index 298c832..c007fcb 100644
--- a/documentation/src/main/asciidoc/bean-validation.adoc
+++ b/documentation/src/main/asciidoc/bean-validation.adoc
@@ -4,33 +4,45 @@
:toc:
-== Introduction
+== Overview
+The Bean Validation module provides CDI integration for bean validation. It enables the creation of CDI-aware `ConstraintValidator` methods that can use business objects (EJBs, ManagedBeans) to support validation needs.
-The main feature of the Bean Validation module is to provide CDI
-integration in to `ConstraintValidator` `s. This allows you to inject CDI
-objects, EJBs etc in to your validators.
+== Configure Your Projects
+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>>.
-=== Scoping
+=== Declare Bean Validation Module Dependencies
+Add the Bean Validation module to the list of dependencies in the project `pom.xml` file using this code snippet:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-bean-validation-module-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+== Use the Module Features
-`ConstraintValidator` `s will inherit whatever scope as defined in the bean class.
+=== Scoping
-Inherently, a `ConstraintValidator` may be invoked by multiple threads so please keep that in mind when using them.
-You should consider using at least `RequestScoped` validators.
+A `ConstraintValidator` inherits the scope defined in the bean class.
+NOTE: A `ConstraintValidator` may be invoked by multiple threads. For this reason, you should consider using at least `RequestScoped` validators.
=== Code Requirements
There are no compile dependencies to use the Bean Validation module. You
-simply need to override the factory, either in Java:
+simply need to override the factory. Then you can build your `ConstraintValidator` based on CDI programming rules.
+.Overriding in Java
[source,java]
-------------------------------------------------------------------------
Validation.byDefaultProvider().configure().constraintValidatorFactory(new CDIAwareConstraintValidatorFactory()).buildValidatorFactory()
-------------------------------------------------------------------------
-Or in XML:
-
+.Overriding in XML
[source,xml]
--------------------------------------------------------------------------------
<validation-config xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
@@ -39,6 +51,3 @@ Or in XML:
<constraint-validator-factory>org.apache.deltaspike.beanvalidation.impl.CDIAwareConstraintValidatorFactory</constraint-validator-factory>
</validation-config>
--------------------------------------------------------------------------------
-
-And then you can simply build your `ConstraintValidator`s based on CDI
-programming rules.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/build.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/build.adoc b/documentation/src/main/asciidoc/build.adoc
index 8d08f5c..c3eea2e 100644
--- a/documentation/src/main/asciidoc/build.adoc
+++ b/documentation/src/main/asciidoc/build.adoc
@@ -8,7 +8,7 @@ The DeltaSpike source (modules and examples) is provided for inspection, contrib
In all cases, to obtain the DeltaSpike source, link:https://deltaspike.apache.org/download.html[download] `deltaspike-project-<version>-source-release.zip` and extract the contents.
-**Note:** You can also obtain the DeltaSpike source from the project Git repository. The repository is subject to change and it can be used for contributing but should not be used in production environments. For more information, see <<source#,Contribute to the DeltaSpike Source>>.
+NOTE: You can also obtain the DeltaSpike source from the project Git repository. The repository is subject to change and it can be used for contributing but should not be used in production environments. For more information, see <<source#,Contribute to the DeltaSpike Source>>.
== Build without CDI Implementation Tests
DeltaSpike can be built without executing tests against a CDI implementation, with the following commands:
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/cdiimp.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/cdiimp.adoc b/documentation/src/main/asciidoc/cdiimp.adoc
index 103ea8a..5da8d67 100644
--- a/documentation/src/main/asciidoc/cdiimp.adoc
+++ b/documentation/src/main/asciidoc/cdiimp.adoc
@@ -16,6 +16,7 @@ Apache OpenWebBeans (OWB) is integrated in Java EE containers including Apache T
== Java EE5 and Servlet Containers
CDI implementations are not distributed with Java EE5 application servers or Servlet-only environments such as Apache TomCat and Eclipse Jetty. You can use CDI in these environments by embedding a standalone CDI implementation. Both JBoss Weld and Apache OpenWebBeans can be used for this task; for more information, see the corresponding CDI implementation documentation.
+[[javase6]]
== Java SE6+
CDI is not part of Java SE but it can still be used. JBoss Weld and Apache OpenWebBeans implementations can be used to act as dependency injection bean managers but the respective containers must be booted manually.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/configuration.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configuration.adoc b/documentation/src/main/asciidoc/configuration.adoc
index 2e2107b..a6db44e 100644
--- a/documentation/src/main/asciidoc/configuration.adoc
+++ b/documentation/src/main/asciidoc/configuration.adoc
@@ -35,22 +35,22 @@ settings, JNDI or the current <<projectstage.adoc#,ProjectStage>>.
=== Drop-In Configuration
This mechanism also allows for dynamic configuration in case of a JAR
-drop-in. By adding some JAR to the classpath, all it's contained
+drop-in. By adding some JAR to the classpath, all its contained
configuration will get picked up and considered in the property value
evaluation. You could also use this mechanism to switch implementations
of some SPI (Service Provider Interface) in your own code.
=== CDI-Extension Configuration
-In some cases low-level configs are needed e.g. during the bootstrapping
+In some cases low-level configs are needed, for example during the bootstrapping
process of the CDI container.
The good news: our DeltaSpike configuration mechanism does not rely on
any other EE mechanism to be booted. Which means it can perfectly get
-used to even configure those parts itself. Since the mechanism doesn't
+used to even configure those parts itself. Since the mechanism does not
rely on CDI it can for example be used to configure CDI-Extensions.
-Currently this is e.g. used to configure the value of the current <<projectstage.adoc#,ProjectStage>>, configured values which can be
+Currently this is, for example, used to configure the value of the current <<projectstage.adoc#,ProjectStage>>, configured values which can be
used in the expressions for `@Exclude`, 'Deactivatable', etc. DeltaSpike
needs such a low-level approach for several features internally, but
users can utilize it for their own needs as well. This is done by using
@@ -133,27 +133,25 @@ the following lookup chain is used until a value got found:
* key, e.g. "databaseconfig.username"
-=== handling of default values
-
+=== Handling of Default Values
There is a 2nd variant of all those methods where it is possible to
provide a default value which gets returned instead of `null` or if the
final result is an empty String.
-*Performance Hint:*
-
-The only `ConfigResolver` operation which is cached is the determination
+.Performance Hint
+TIP: The only `ConfigResolver` operation which is cached is the determination
of the `ConfigSources`. The various getPropertyValue operations are not
cached in the ConfigResolver but might be cached in the ConfigSources.
This makes the overall calculation a bit slower, but allows for values
-to change dynamically if someone likes to e.g. implement a
+to change dynamically if someone likes to for example implement a
`JmxConfigSource` (not yet part of DeltaSpike, but easily
implementable).
== ConfigSource
-A `ConfigSource` is exactly what it's name says: a source for configured
+A `ConfigSource` is exactly what its name says: a source for configured
values. The `ConfigResolver` uses all configured implementations of
`ConfigSource` to lookup the property in question.
@@ -166,10 +164,10 @@ to amend configuration from outside a binary - given those outside
ConfigSources have a higher `deltaspike_ordinal` than the ones who
pickup the values from within the release binaries.
-=== ConfigSources provided by default
+=== ConfigSources Provided by Default
-Per default there are implementations for the following config sources
+By default there are implementations for the following configuration sources
(listed in the lookup order):
* System properties (deltaspike_ordinal = 400)
@@ -177,42 +175,38 @@ Per default there are implementations for the following config sources
* JNDI values (deltaspike_ordinal = 200, the base name is "java:comp/env/deltaspike/")
* Properties file values (apache-deltaspike.properties) (deltaspike_ordinal = 100, default filename is "META-INF/apache-deltaspike.properties")
-*It's possible to change this order and to add custom config sources.*
+*It is possible to change this order and to add custom configuration sources.*
-*Note:* Important Hints esp. for custom implementations: - The
-config-source with the highest ordinal gets used first. - If a custom
+.Important Tips Especially for Custom Implementations
+TIP: - The config-source with the highest ordinal gets used first. - If a custom
implementation should be invoked _before_ the default implementations,
-use an ordinal-value > 400 - If a custom implementation should be
-invoked _after_ the default implementations, use an ordinal-value < 100
+use an ordinal-value > 400. - If a custom implementation should be
+invoked _after_ the default implementations, use an ordinal-value < 100.
- The `ConfigResolver` performs no caching. If your custom ConfigSource
operation is expensive, then you might think about introducing some
caching.
-
-=== Reordering of the default order of Config-Sources
+=== Reordering of the Default Order of ConfigSources
To change the lookup order, you have to configure the ordinal in the
-corresponding config source (e.g. to change the config ordinal of the
-config source for system properties, you have to set the system property
+corresponding configuration source (e.g. to change the configuration ordinal of the
+configuration source for system properties, you have to set the system property
with the ordinal key 'deltaspike_ordinal' and the new value).
Example with `/META-INF/apache-deltaspike.properties`: If the properties
file/s should be used *before* the other implementations, you have to
-configure an ordinal > 400. That means, you have to add e.g.
+configure an ordinal > 400. That means, you have to add for example
`deltaspike_ordinal=401`.
Each single property file is treated as own `ConfigSource` and thus can
have different `deltaspike_ordinal` values!
-*Hint:*
-
-In case of *property files* which are supported by default
+NOTE: In case of *property files* which are supported by default
(`/META-INF/apache-deltaspike.properties`) every file is handled as
independent config-source, but all of them have ordinal 400 by default
(and can be reordered in a fine-grained manner).
-=== Custom Config-Sources
-
+=== Custom ConfigSources
ConfigSources are picked up using the `java.util.ServiceLoader'
mechanism.
@@ -225,16 +219,14 @@ into it.
If you need dynamic ConfigSources you can also register a
`ConfigSourceProvider` in a similar way. This is useful if you like to
-dynamically pick up multiple ConfigSources of the same kind. E.g. if you
+dynamically pick up multiple ConfigSources of the same kind. For example, if you
like to pick up all `myproject.properties` files from all the JARs in
your classpath.
Please note that a single `ConfigSource` should be either registered
directly or via a `ConfigSourceProvider`, but never both ways.
-*Important Hint:*
-
-Have a look at the abstract base-implementation of `ConfigSource`
+TIP: Have a look at the abstract base-implementation of `ConfigSource`
DeltaSpike is using internally, if a custom implementation should load
the ordinal value from the config-source like the default
implementations provided by DeltaSpike do.
@@ -274,7 +266,7 @@ dependency to the module that contains the property file._
</jboss-deployment-structure>
---------------------------------------------------------------------------------------------------
-== Type-safe configuration
+== Type-safe Configuration
DeltaSpike provides a way to directly inject configured values into your
code via the qualifier `@ConfigProperty`.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/configure.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configure.adoc b/documentation/src/main/asciidoc/configure.adoc
index bb6db2e..5c703c8 100644
--- a/documentation/src/main/asciidoc/configure.adoc
+++ b/documentation/src/main/asciidoc/configure.adoc
@@ -6,7 +6,7 @@
DeltaSpike is available for use in Maven-based and Maven-independent projects. Instructions are given here for obtaining released final versions of DeltaSpike for both approaches.
-**Note:** You can also opt to use the lastest DeltaSpike snapshots; for more information, see <<snapshots#,Use DeltaSpike Snapshots>>.
+NOTE: You can also opt to use the lastest DeltaSpike snapshots; for more information, see <<snapshots#,Use DeltaSpike Snapshots>>.
== Option A: Configure DeltaSpike in Maven-based Projects
DeltaSpike released versions are available from the Maven Central repository for use in Maven-based projects. This means that you do not need to modify your Maven configuration `settings.xml` file; when building projects, Maven automatically searches the online Maven Central repository for project dependencies and downloads sources to your local Maven repository.
@@ -19,7 +19,7 @@ To begin use the DeltaSpike releases from Maven Central, you simply need to conf
[source,xml]
----
<properties>
- <deltaspike.version>1.0.2</deltaspike.version>
+ <deltaspike.version>1.2.0</deltaspike.version>
</properties>
----
+
@@ -44,6 +44,8 @@ To begin use the DeltaSpike releases from Maven Central, you simply need to conf
+
. Save the `pom.xml` file changes
+TIP: The API is scoped for compile time and implementation only included for runtime, assisting to prevent you from inadvertantly depending on an implementation class.
+
For instructions on adding the optional DeltaSpike modules, see the relevant module page:
* <<bean-validation#,Bean Validation>>
@@ -57,6 +59,7 @@ For instructions on adding the optional DeltaSpike modules, see the relevant mod
* <<servlet#,Servlet>>
* <<test-control#,Test-Control>>
+[[config-maven-indep]]
== Option B: Configure DeltaSpike in Maven-independent Projects
Deltaspike is provided as a set of downloadable .jar files for projects not utilizing the Maven build system. Alternatively, you can build the DeltaSpike .jar files from source; for instructions, see <<build#,Build DeltaSpike from Source>>. In both cases, you must add the DeltaSpike .jar files directly to your projects.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/container-control.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/container-control.adoc b/documentation/src/main/asciidoc/container-control.adoc
index 0fdc767..39e1f4d 100644
--- a/documentation/src/main/asciidoc/container-control.adoc
+++ b/documentation/src/main/asciidoc/container-control.adoc
@@ -1,52 +1,41 @@
-= Container & Control
+= Container 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:
-== Introduction
+== Overview
+The Container Control module provides CDI container booting and shutdown, crucial for CDI use in Java SE6+ environments, and associated context lifecycle management. The module abstracts individual CDI container implementations, ensuring projects are container-independent.
-There are basically two parts:
+== Configure Your Projects
+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>>.
-* The `CdiContainer` interface allows to boot and shutdown the CDI container in SE applications.
-* The `ContextControl` interface allows to control the life-cycle of the built-in contexts of the CDI container.
+=== Declare Container Control Module Dependencies
+Add the Container Control module to the list of dependencies in the project `pom.xml` file using this code snippet:
-=== CdiContainer
-
-You can use the `CdiContainerLoader` as a simple factory to gain access
-to the underlying `CdiContainer` implementation. This is of little
-interest for Java EE applications since the CDI Container already gets
-properly booted and shut down by the Servlet container integration.
-
-[source,java]
-------------------------------------------------------------------------------------
-// this will give you a CdiContainer for Weld or OWB, depending on the jar you added
-CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
-
-// now we gonna boot the CDI container. This will trigger the classpath scan, etc
-cdiContainer.boot();
-
-// and finally we like to start all built-in contexts
-cdiContainer.getContextControl().startContexts();
-
-// now we can use CDI in our SE application.
-// And there is not a single line of OWB or Weld specific code in your project!
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.cdictrl</groupId>
+ <artifactId>deltaspike-cdictrl-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+----
-// finally we gonna stop the container
-cdiContainer.shutdown();
-------------------------------------------------------------------------------------
+== Use the Module Features
-=== ContextControl usage
+=== CdiContainer
+The `CdiContainer` interface provides booting and shutdown of the CDI containers from deployed applications, with `CdiContainerLoader` a simple factory providing access to the underlying `CdiContainer` implementation.
+This is useful to Java SE6+ applications in which a standalone CDI implementation must be provided and booted and shutdown by the application. Booting and shutdown of the CDI container for Java EE and servlet containers is managed by the servlet container integration.
-The `ContextControl` interface allows you to start and stop built-in
-standard Contexts like `@RequestScoped`, `@ConversationScoped`,
-`@SessionScoped`, etc. It is provided as `@Dependent` bean and can get
-injected in the classic CDI way. This is not only usable in Java SE
-projects but also very helpful in Servlets and Java EE containers.
+For instructions and examples on using this feature in your projects, see <<cdiimp#javase6,Enable CDI For Your Java Environment: Java SE6+>>.
-*Restarting the RequestContext in unit tests*
+=== ContextControl Usage
+The `ContextControl` interface provides life-cycle control of the CDI container built-in contexts. This includes starting and stoping built-in standard contexts like `@RequestScoped`, `@ConversationScoped`, and `@SessionScoped`. It is provided as an `@Dependent` bean and can be injected in the classic CDI way. This feature can be used and is helpful in all Java environments, including Java SE, as illustrated here.
+==== Restart the RequestContext in Unit Tests
In unit testing it can be necessary to test with attached and also with
detached JPA entities. A very common approach for JPA is the
http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html[entitymanager-per-request
@@ -54,8 +43,7 @@ approach] and thus have a producer method which creates a @RequestScoped
EntityManager. Since a single unit test is usually treated as one
‘request’ a problem arises detaching entities.
-Using ContextControl to detach entities:
-
+.Using ContextControl to Detach Entities
[source,java]
---------------------------------------------------------------------------------------
@Test
@@ -66,28 +54,26 @@ public void testMyBusinessLogic()
ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
- //stopping the request context will dispose the @RequestScoped EntityManager
+ //stop the RequestContext to dispose of the @RequestScoped EntityManager
ctxCtrl.stopContext(RequestScoped.class);
- // and now immediately restart the context again
+ //immediately restart the context again
ctxCtrl.startContext(RequestScoped.class);
- // the entity 'em' is now in a detached state!
+ //the entity 'em' is now in a detached state!
doSomeStuffWithTheDetachedEntity(em);
}
---------------------------------------------------------------------------------------
-Attaching a Request Context to a new thread in EE
-
+==== Attach a RequestContext to a New Thread in EE
Accessing the `@RequestScoped` bean in a new thread will result in a
-`ContextNotActiveException`. The request-context usually gets started
+`ContextNotActiveException`. The RequestContext usually gets started
for a particular thread via a simple `ServletRequestListener`. So "no
servlet-request" means that there is no Servlet-Context for the current
(/new) Thread. You might face such issues, if you would like to reuse
-business services in e.g. a Quartz Job.
-
-Controlling the request-context for a Quartz-Job:
+business services in for example a Quartz Job.
+.Using ContextControl to Control the RequestContext for a Quartz-Job
[source,java]
---------------------------------------------------------------------------------------------
public class CdiJob implements org.quartz.Job
@@ -113,8 +99,7 @@ public class CdiJob implements org.quartz.Job
---------------------------------------------------------------------------------------------
=== Embedded Servlet Support
-
-Starting with 1.0.2, you can use DeltaSpike to power embedded Servlet
+From DeltaSpike 1.0.2, you can use DeltaSpike to power embedded Servlet
runtimes. This work is done via Servlet Listeners. The configuration is
specific to each container, below are some examples.
@@ -125,7 +110,7 @@ containers this is all you need. For Tomcat specifically, you need to
use `CdiServletContextListener` which registers the
`CdiServletRequestListener`.
-The main usecase for this feature is for lightweight embedded runtimes,
+The main use case for this feature is for lightweight embedded runtimes,
microservices. For each of these, it is assumed that you are using the
following start up code somewhere:
@@ -182,7 +167,6 @@ server.start();
==== Tomcat
-
For Tomcat, you need to register the `CdiServletContextListener` instead
of the `CdiServletRequestListener`. It is added as an
`ApplicationListener` by passing in the class name as a `String`.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/core.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/core.adoc b/documentation/src/main/asciidoc/core.adoc
index e3d8270..3f6df66 100644
--- a/documentation/src/main/asciidoc/core.adoc
+++ b/documentation/src/main/asciidoc/core.adoc
@@ -1,45 +1,48 @@
-= Core
+= Core 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:
-== Core - API
+== Overview
+The Core module provides fundamental and defining DeltaSpike API and utility classes. As such, this module must be included in every project that uses DeltaSpike.
+== Configure Your Projects
-=== DeltaSpike Configuration
+Instructions for configuring your Maven-based and Maven-independent projects to use the DeltaSpike Core module are detailed in <<configure#, Configure DeltaSpike in Your Projects>> as part of the general instructions for configuring your projects for DeltaSpike.
+== Use the Module Features
-This is described in an own chapter solely targeting our <<configuration.adoc#,configuration>> mechanics, API and SPI.
+=== Core - API
-=== BeanProvider
+==== DeltaSpike Configuration
+This is described in a separate page solely targeting <<configuration.adoc#,configuration>> mechanics, API and SPI.
+==== BeanProvider
The `BeanProvider` is a class which provides (static) util methods which
-allow to lookup beans if it isn't possible to inject them via `@Inject`
+allow to lookup beans if it is not possible to inject them via `@Inject`
or if the lookup depends on dynamic conditions. Instead of using the
term 'bean', the term 'contextual instance' is used because that's the
term used by CDI itself.
The following example shows a simple lookup. With the second parameter
-it's possible to specify if the contextual instance is optional. If it
-isn't expected that the contextual instance is optional, but no instance
+it is possible to specify if the contextual instance is optional. If it
+is not expected that the contextual instance is optional, but no instance
has been found, an `IllegalStateException` will be thrown.
-Resolving a simple contextual instance:
-
+.Resolving a Simple Contextual Instance
[source,java]
-------------------------------------------------------------------------
MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false);
-------------------------------------------------------------------------
Pass `true` as second argument, if you look for an implementation of the
-given interface and an implementation isn't required or it isn't
+given interface and an implementation is not required or it is not
required that there is an instance with the given qualifier (see the
qualifier example for further details).
-Resolving an optional contextual instance:
-
+.Resolving an Optional Contextual Instance
[source,java]
---------------------------------------------------------------------------------------------------------
MyServiceInterface optionalService = BeanProvider.getContextualReference(MyServiceInterface.class, true);
@@ -49,8 +52,7 @@ Optionally you can provide a qualifier for the contextual instance in
question. CDI qualifiers are annotations, therefore you need to
implement a corresponding literal for providing an instance.
-Literal implementation for '@MyQualifier':
-
+.Literal Implementation for '@MyQualifier'
[source,java]
---------------------------------------------------------------------------------------------
import javax.enterprise.util.AnnotationLiteral;
@@ -62,10 +64,9 @@ public class MyQualifierLiteral extends AnnotationLiteral<MyQualifier> implement
---------------------------------------------------------------------------------------------
The following example will return a contextual instance with the
-qualifier `@MyQualifier`
-
-Resolving a simple contextual instance with qualifier:
+qualifier `@MyQualifier`.
+.Resolving a Simple Contextual Instance with Qualifier
[source,java]
---------------------------------------------------------------------------------------------------
MyBean myBean = BeanProvider.getContextualReference(MyBean.class, false, new MyQualifierLiteral());
@@ -75,68 +76,62 @@ The `@Named` qualifier has a special role and allows to specify a string
based name (e.g. for referencing CDI beans in EL-expressions). However,
the following examples show how to do a manual lookup by name.
-Resolving a simple contextual instance by name:
-
+.Resolving a Simple Contextual Instance by Name
[source,java]
---------------------------------------------------------------------
Object myBean = BeanProvider.getContextualReference("myBean", false);
---------------------------------------------------------------------
-Resolving a simple contextual instance by name and expected type:
-
+.Resolving a Simple Contextual Instance by Name and Expected Type
[source,java]
-----------------------------------------------------------------------------------
MyBean myBean = BeanProvider.getContextualReference("myBean", false, MyBean.class);
-----------------------------------------------------------------------------------
-Sometimes it's essential to resolve all contextual instances which
-implement e.g. an interface or all beans with the same type but a
+Sometimes it is essential to resolve all contextual instances which
+implement for example an interface or all beans with the same type but a
different qualifier. The following example shows how to do such a lookup
which returns all contextual instances (independent of the scope -> also
dependent scoped instances).
-Resolving all contextual instances of a given type:
-
+.Resolving All Contextual Instances of a Given Type
[source,java]
---------------------------------------------------------------------------------------------------------------
List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false);
---------------------------------------------------------------------------------------------------------------
Since dependent scoped beans have a special role in CDI (you have to
-destroy them manually - esp. if you get them via a manual lookup), you
+destroy them manually - especially if you get them via a manual lookup), you
can also call the previous util method with an additional parameter to
filter dependent scoped instances.
-Resolving all contextual instances of a given type without dependent
-scoped instances:
-
+.Resolving All Contextual Instances of a Given Type without Dependent
+Scoped Instances
[source,java]
----------------------------------------------------------------------------------------------------------------------
List<MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, false, false);
----------------------------------------------------------------------------------------------------------------------
-Furthermore, it's possible to trigger the injection of fields of any
-given instance, if it wasn't done by the container (e.g. because the
+Furthermore, it is possible to trigger the injection of fields of any
+given instance, if it was not done by the container (e.g. because the
class is in a jar-file without beans.xml) and `@Inject` is used for 1-n
fields.
-Manually inject fields:
-
+.Manually Inject Fields
[source,java]
------------------------------------
BeanProvider.injectFields(myObject);
------------------------------------
-=== BeanManagerProvider
+==== BeanManagerProvider
This mechanism provides access to the `BeanManager` by registering the
current `BeanManager` during the startup. This is really handy if you
like to access CDI functionality from places where no CDI based
injection is available. If a simple but manual bean-lookup is needed,
-it's easier to use the `BeanProvider`.
-
-Resolving the Bean-Manager:
+it is easier to use the `BeanProvider`.
+.Resolving the BeanManager
[source,java]
-----------------------------------------------------------------------------
//in most cases the following works without problems:
@@ -149,8 +144,8 @@ BeanManager beanManager = BeanManagerProvider.getInstance().getBeanManager();
//if CDI based injection is not available.
-----------------------------------------------------------------------------
-`BeanManagerProvider` uses an own approach to find the correct `BeanManager`,
-because a portable API for it is only available since CDI 1.1.
+`BeanManagerProvider` uses a different approach to find the correct `BeanManager`,
+because a portable API for it has only been available from CDI 1.1.
However, once you are using CDI 1.1+ DeltaSpike delegates the lookup to the CDI container
instead of using its own approach.
If you migrate from CDI 1.0 to a later version of CDI and you would like to keep
@@ -158,21 +153,18 @@ the lookup strategy you used before, you can deactivate the delegation to the co
`deltaspike.bean-manager.delegate_lookup=false` to your config-source
(e.g. in `/META-INF/apache-deltaspike.properties`).
-=== Type-safe ProjectStage
-
+==== Type-safe ProjectStage
The DeltaSpike <<projectstage.adoc#,ProjectStage>> mechanism allows to
use configuration and implementations depending on the server
environment you currently run on.
-=== @Exclude
-
+==== @Exclude
-With `@Exclude` it's possible to annotate beans which should be ignored
+With `@Exclude` it is possible to annotate beans which should be ignored
by CDI even if they are in a CDI enabled archive.
-Excluding a bean in any case:
-
+.Excluding a Bean in any Case
[source,java]
-------------------
@Exclude
@@ -181,8 +173,7 @@ public class NoBean
}
-------------------
-Excluding a bean in case of project-stage development:
-
+.Excluding a Bean in Case of ProjectStageDevelopment
[source,java]
---------------------------------------------------------
@Exclude(ifProjectStage = ProjectStage.Development.class)
@@ -191,8 +182,7 @@ public class MyBean
}
---------------------------------------------------------
-Excluding a bean if the project-stage is different from development:
-
+.Excluding a Bean if the pProjectStageis Different from Development
[source,java]
---------------------------------------------------------------
@Exclude(exceptIfProjectStage = ProjectStage.Development.class)
@@ -202,10 +192,9 @@ public class MyDevBean
---------------------------------------------------------------
The following usage allows to exclude a bean based on a configured value
-(see the <<configuration.adocl#_configsources_provided_by_default,supported config sources>>).
-
-Excluding a bean based on an expression which eval. to true:
+(see the <<configuration.adocl#_configsources_provided_by_default,supported configuration sources>>).
+.Excluding a Bean based on an Expression which Evaluates to True
[source,java]
-------------------------------------
@Exclude(onExpression = "db==prodDB")
@@ -214,12 +203,11 @@ public class DevDbBean
}
-------------------------------------
-By default a simple syntax is supported ([TODO]), however, it's possible
+By default a simple syntax is supported ([TODO]), however, it is possible
to provide a custom `ExpressionInterpreter` for interpreting custom
expressions.
-Excluding a bean based on a custom expression:
-
+.Excluding a Bean based on a Custom Expression
[source,java]
------------------------------------------------------------------------------------------
@Exclude(onExpression = "db eq prodDB", interpretedBy = SimpleExpressionInterpreter.class)
@@ -241,17 +229,16 @@ public class SimpleExpressionInterpreter implements ExpressionInterpreter<String
}
------------------------------------------------------------------------------------------
-In several cases it's also useful to combine this feature with the
+In several cases it is also useful to combine this feature with the
`@Alternative` annotation provided by CDI.
-In addition to the following snippet, it's required to configure the
-implementation as alternative in the beans.xml file. This config entry
-won't be changed e.g. for different environments, because it just gets
-active if it isn't excluded during the bootstrapping process.
-
-Excluding an alternative implementation if the project-stage is
-different from development:
+In addition to the following snippet, it is required to configure the
+implementation as alternative in the beans.xml file. This configuration entry
+will not be changed, for example for different environments, because it just gets
+active if it is not excluded during the bootstrapping process.
+.Excluding an Alternative Implementation if the pProjectStageis
+Different from Development
[source,java]
---------------------------------------------------------------
@Exclude(exceptIfProjectStage = ProjectStage.Development.class)
@@ -261,11 +248,11 @@ public class MyDevBean
}
---------------------------------------------------------------
-==== Custom ExpressionInterpreter
+===== Custom ExpressionInterpreter
-Per default only a very simple and limited syntax is supported. In real
+By default only a very simple and limited syntax is supported. In real
projects there are usually quite concrete requirements. Since it would
-be very complex to support most of them, it's easier for users to
+be very complex to support most of them, it is easier for users to
implement an optimized syntax. For such cases a custom
ExpressionInterpreter is needed:
@@ -290,7 +277,7 @@ public class ConfigAwareExpressionInterpreter implements ExpressionInterpreter<S
if (values.length != 2)
{
- throw new IllegalArgumentException("'" + expression + "' isn't a supported syntax");
+ throw new IllegalArgumentException("'" + expression + "' is not a supported syntax");
}
String configuredValue = ConfigResolver.getPropertyValue(values[0], null);
@@ -301,18 +288,17 @@ public class ConfigAwareExpressionInterpreter implements ExpressionInterpreter<S
}
----------------------------------------------------------------------------------------------------
-=== Type-safe View-Config
+==== Type-safe View-Config
TODO (Overview)
-=== Literals
+==== Literals
Literals allow the instantiation of annotations by extending the
abstract class 'javax.enterprise.util.AnnotationLiteral'
-*Example*
-
+.Example
[source,java]
----------------------------------------------------------------------------------------------
public abstract class PayByQualifier
@@ -322,7 +308,7 @@ public abstract class PayByQualifier
PayBy paybyCheque = new PayByQualifier() { public PaymentMethod value() { return CHEQUE; } };
----------------------------------------------------------------------------------------------
-DeltaSpike provides many annotation literals that you can use - e.g.:
+DeltaSpike provides many annotation literals that you can use, including the following:
* AlternativeLiteral
* AnyLiteral
@@ -339,13 +325,12 @@ DeltaSpike provides many annotation literals that you can use - e.g.:
* SpecializesLiteral
* TypedLiteral
-=== Messages & I18n
+==== Messages and I18n
The following implementation is the minimal effort to use type-safe
messages (which are hardcoded in this case).
-*Simple type-safe message*
-
+.Simple Type-safe Message
[source,java]
---------------------------------------------
@MessageBundle
@@ -361,8 +346,7 @@ a lookup in the default message bundle. The default bundle has the same
name as the interface (but .properties instead of .java (/.class) as
file extension).
-*Internationalized type-safe message*
-
+.Internationalized Type-safe Message
[source,java]
-----------------------------------------------------------------
@MessageBundle
@@ -388,8 +372,7 @@ welcome_to_deltaspike=Welcome to DeltaSpike
The following implementation uses the key `welcome_to_deltaspike` to do
a lookup in a custom message bundle known by `CustomMessageResolver`.
-*Internationalized type-safe message*
-
+.Internationalized Type-safe Message
[source,java]
--------------------------------------------------------------------
@MessageBundle
@@ -407,8 +390,7 @@ public interface SimpleMessage
The following implementation shows the usage of an internationalized
simple type-safe message.
-*Internationalized type-safe message with parameter/s*
-
+.Internationalized Type-safe Message with Parameter/s
[source,java]
----------------------------------------------------------------------------
@MessageBundle
@@ -434,11 +416,9 @@ public class MyBean
}
----------------------------------------------------------------------------
-=== Dynamic Message Builder
-
-
-==== Creating message instances
+==== Dynamic Message Builder
+===== Creating Message Instances
The following implementation creates an instance of `Message` for the
key `hello`. The final text will be resolved and interpolated lazily.
@@ -466,7 +446,7 @@ public class MyBean
}
---------------------------------------------------------------------------------------------
-Besides the static config via `@MessageContextConfig#messageSource`, you
+Besides the static configuration via `@MessageContextConfig#messageSource`, you
can also specify the message sources dynamically.
[source,java]
@@ -491,14 +471,13 @@ org/apache/deltaspike/example/message/Messages_de.properties
hello=Hello %s from %s
--------------------------------------------------------------------------------------------------------------------
-==== Customizing the message context
+===== Customizing the Message Context
-
-===== MessageResolver
+====== MessageResolver
A message-resolver is responsible for creating the message-text based on
the message-descriptor (key or inline-text), the current locale (and in
-some cases the message-payload). (The supported format e.g. if it's
+some cases the message-payload). (The supported format, for example, if it is
required to escape a key, if inline-text is supported,... depends on the
concrete implementation.) In case of a message-key, the message-resolver
has to transform it to the message-text by looking it up in a message
@@ -506,7 +485,7 @@ source like a resource-bundle.
*Configuration of a message-resolver*
-Besides the static config via `@MessageContextConfig#messageResolver`,
+Besides the static configuration via `@MessageContextConfig#messageResolver`,
you can use it dynamically via passing a custom message-resolver
instance to the current messageContext:
@@ -523,14 +502,14 @@ Message message = this.messageContext.messageResolver(new CustomMessageResolver(
The result of a `MessageResolver` is the message-text. The text might
contain placeholders which are processed by a `MessageInterpolator`
-===== MessageInterpolator
+====== MessageInterpolator
A `MessageInterpolator` replaces the placeholders in a message-text with
the arguments of the message.
*Configuration of a message-interpolator*
-Besides the static config via
+Besides the static configuration via
`@MessageContextConfig#messageInterpolator, you can use it dynamically
via passing a custom message-interpolator instance to the current
messageContext:
@@ -544,15 +523,15 @@ private MessageContext messageContext;
Message message = this.messageContext.messageInterpolator(new CustomMessageInterpolator()).message();
-----------------------------------------------------------------------------------------------------
-===== LocaleResolver
+====== LocaleResolver
-A locale resolver provides the current locale. The locale is e.g. used
+A locale resolver provides the current locale. The locale is, for example, used
to by a `MessageResolver` to choose the correct language for the
message-text.
*Configuration of a locale-resolver*
-Besides the static config via `@MessageContextConfig#localeResolver, you
+Besides the static configuration via `@MessageContextConfig#localeResolver, you
can use it dynamically via passing a custom locale-resolver instance to
the current messageContext:
@@ -564,7 +543,7 @@ private MessageContext messageContext;
Message message = this.messageContext.localeResolver(new CustomLocaleResolver()).message();
-------------------------------------------------------------------------------------------
-=== Injecting Resources
+==== Injecting Resources
DeltaSpike has simple APIs for performing basic resource loading and
property file reading.
@@ -582,7 +561,7 @@ and `FileResourceProvider`. They can be extended as well by implementing
the `InjectableResourceProvider` interface to allow reading from
alternate sources, if needed (e.g. database LOBs, NoSQL storage areas).
-=== Exception Control
+==== Exception Control
Exception handling in DeltaSpike is based around the CDI eventing model.
While the implementation of exception handlers may not be the same as a
@@ -603,7 +582,7 @@ developer. In most cases, you register an exception handler simply by
annotating a handler method. Alternatively, you can handle an exception
programmatically, just as you would observe an event in CDI.
-==== Usage
+===== Usage
The entire exception handling process starts with an event. This helps
keep your application minimally coupled to DeltaSpike, but also allows
@@ -613,7 +592,7 @@ for your application Events provide this delicate balance. Firing the
event is the main way of starting the exception handling proccess.
Manually firing an event to use DeltaSpike's exception handling is
-primarily used in your own try/catch blocks. It's very painless and also
+primarily used in your own try/catch blocks. It is very painless and also
easy. Let's examine a sample that might exist inside of a simple
business logic lookup into an inventory database:
@@ -641,8 +620,7 @@ your class for use later within a try/catch block.
The event is fired with a new instance of `ExceptionToCatchEvent`
constructed with the exception to be handled.
-==== Exception handlers
-
+===== Exception Handlers
As an application developer (i.e., an end user of DeltaSpike's exception
handling), you'll be focused on writing exception handlers. An exception
@@ -681,7 +659,7 @@ methods which have a parameter which is an instance of
`ExceptionEvent<T extends Throwable>` annotated with the `@Handles`
annotation.
-===== @ExceptionHandler
+====== @ExceptionHandler
The `@ExceptionHandler` annotation is simply a marker annotation that
instructs the DeltaSpike exception handling CDI extension to scan the
@@ -699,7 +677,7 @@ public class MyHandlers {}
That's all there is to it. Now we can begin defining exception handling
methods on this bean.
-===== @Handles and @BeforeHandles
+====== @Handles and @BeforeHandles
`@Handles` is a method parameter annotation that designates a method as
an exception handler. Exception handler methods are registered on beans
@@ -728,14 +706,14 @@ public class MyHandlers
The `@Handles` annotation on the first parameter designates this method
as an exception handler (though it is not required to be the first
parameter). This parameter must be of type
-`ExceptionEvent<T extends Throwable>`, otherwise it's detected as a
+`ExceptionEvent<T extends Throwable>`, otherwise it is detected as a
definition error. The type parameter designates which exception the
method should handle. This method is notified of all exceptions
(requested by the base exception type `Throwable`).
The `ExceptionEvent` instance provides access to information about the
exception and can be used to control exception handling flow. In this
-case, it's used to read the current exception being handled in the
+case, it is used to read the current exception being handled in the
exception chain, as returned by `getException()`.
This handler does not modify the invocation of subsequent handlers, as
@@ -806,7 +784,7 @@ unchecked exceptions. Should a handler throw an unchecked exception it
will propagate up the stack and all handling done via DeltaSpike will
cease. Any exception that was being handled will be lost.
-===== Ordinal
+====== Ordinal
When DeltaSpike finds more than one handler for the same exception type,
it orders the handlers by ordinal. Handlers with higher ordinal are
@@ -842,16 +820,16 @@ invoke (until a handler marks exception as handled):
5. If multiple handlers for same type, invoke handlers with higher ordinal first
6. Continue above steps for each exception in stack
-==== Exception Chain Processing
+===== Exception Chain Processing
-When an exception is thrown, chances are it's nested (wrapped) inside
+When an exception is thrown, chances are it is nested (wrapped) inside
other exceptions. (If you've ever examined a server log, you'll
appreciate this fact). The collection of exceptions in its entirety is
termed an exception chain.
The outermost exception of an exception chain (e.g., EJBException,
ServletException, etc) is probably of little use to exception handlers.
-That's why DeltaSpike doesn't simply pass the exception chain directly
+That's why DeltaSpike does not simply pass the exception chain directly
to the exception handlers. Instead, it intelligently unwraps the chain
and treats the root exception cause as the primary exception.
@@ -889,7 +867,7 @@ the handlers for `EJBException` from being invoked, which is a good
thing since what useful information can really be obtained from
`EJBException`?
-==== APIs for exception information and flow control
+===== APIs for Exception Information and Flow Control
There are two APIs provided by DeltaSpike that should be familiar to
application developers:
@@ -897,7 +875,7 @@ application developers:
* `ExceptionEvent`
* `ExceptionStackEvent`
-===== ExceptionEvent
+====== ExceptionEvent
In addition to providing information about the exception being handled,
the `ExceptionEvent` object contains methods to control the exception
@@ -922,35 +900,27 @@ the current cause.
invoked
Once a handler is invoked it is muted, meaning it will not be run again
-for that exception chain, unless it's explicitly marked as unmuted via
+for that exception chain, unless it is explicitly marked as unmuted via
the `unmute()` method on `ExceptionEvent`.
-=== Scopes
+==== Scopes
DeltaSpike Core provides the API and SPI for several scopes. Currently
all scopes are only implemented in the <<jsf.adoc#_scopes,JSF module>>.
+===== @WindowScoped
-==== @WindowScoped
-
-
-
-==== @ViewAccessScoped
+===== @ViewAccessScoped
+===== @GroupedConversationScoped
-@GroupedConversationScoped
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+==== Creating a Custom CDI Scope
+To create a custom CDI scope to match your needs, complete the following steps:
-=== Creating a custom CDI Scope
-
-
-If you want to create a custom CDI scope to match your needs, you will
-need to follow these steps:
-
-First, create an Annotation with annotated with @javax.inject.Scope;
-Example:
-
+1. Create an Annotation with annotated with @javax.inject.Scope;
++
+.Example
[source,java]
----------------------------------------------------------------
@Scope
@@ -958,10 +928,10 @@ Example:
@Target({ElementType.TYPE,ElementType.METHOD,ElementType.FIELD})
public @interface ACustomScope {}
----------------------------------------------------------------
-
-Second, create an Extension to add the scope and a context for it.
-Example:
-
++
+2. Create an Extension to add the scope and a context for it.
++
+.Example
[source,java]
---------------------------------------------------------------------------------------
public class ACustomScopeExtension implements Extension, Serializable {
@@ -975,10 +945,11 @@ public class ACustomScopeExtension implements Extension, Serializable {
}
}
---------------------------------------------------------------------------------------
-
-Implement a javax.enterprise.context.spi.Context interface to hold the
-javax.enterprise.inject.spi.Bean instances according to your needs
-
++
+3. Implement a javax.enterprise.context.spi.Context interface to hold the
+javax.enterprise.inject.spi.Bean instances according to your needs.
++
+.Example
[source,java]
-----------------------------------------------------------------------------------------------------
public class ACustomScopeContext implements Context, Serializable {
@@ -1021,8 +992,7 @@ public class ACustomScopeContext implements Context, Serializable {
}
-----------------------------------------------------------------------------------------------------
-=== Deactivatable
-
+==== Deactivatable
DeltaSpike allows you to deactivate its own Extensions. You just need to
implement your <<spi.adoc#_classdeactivator,ClassDeactivator>>.
@@ -1050,14 +1020,14 @@ public class CustomClassDeactivator implements ClassDeactivator
}
--------------------------------------------------------------------------
-now, we can use the file `/META-INF/apache-deltaspike.properties` (or any
+Now, we can use the file `/META-INF/apache-deltaspike.properties` (or any
other <<configuration.adoc#_configsources_provided_by_default,ConfigSource>>) with the following key/value:
------------------------------------------------------------------------------------------
org.apache.deltaspike.core.spi.activation.ClassDeactivator=org.test.CustomClassDeactivator
------------------------------------------------------------------------------------------
-== Core - Utils
+=== Core - Utils
DeltaSpike provides many utility-classes (no constructor / static
@@ -1065,7 +1035,7 @@ methods) that can be useful for your project.
Below you can find an information about these classes.
-=== ArraysUtils
+==== ArraysUtils
A collection of utilities for working with Arrays
@@ -1074,7 +1044,7 @@ A collection of utilities for working with Arrays
objects, the last object in the array will be placed in resultant set.
-=== BeanUtils
+==== BeanUtils
A set of utility methods for working with beans.
@@ -1082,7 +1052,7 @@ A set of utility methods for working with beans.
* `#extractAnnotation` - Extract the annotations.
* `#createInjectionPoints` - Given a method, and the bean on which the method is declared, create a collection of injection points representing the parameters of the method.
-=== ClassDeactivationUtils
+==== ClassDeactivationUtils
Helper methods for `ClassDeactivator`
@@ -1091,14 +1061,14 @@ Helper methods for `ClassDeactivator`
To add a custom `ClassDeactivator` add `org.apache.deltaspike.core.spi.activation.ClassDeactivator=my.CustomClassDeactivator` to `META-INF\apache-deltaspike.properties`. Or configure it via a custom `ConfigSource`.
-=== ExceptionUtils
+==== ExceptionUtils
Helper methods to deal with Exceptions
* `#throwAsRuntimeException` - helper which allows to use a trick to throw a catched checked exception without a wrapping exception.
* `#changeAndThrowException` - helper which allows to use a trick to throw a cached checked exception without a wrapping exception.
-=== PropertyFileUtils
+==== PropertyFileUtils
Helper methods for Property files
@@ -1107,14 +1077,14 @@ Helper methods for Property files
* `#getResourceBundle` - Return the ResourceBundle for the current default Locale.
-=== ProxyUtils
+==== ProxyUtils
Helper for CDI proxies
* `#getUnproxiedClass` - Return class of the real implementation.
* `#isProxiedClass` - Analyses if the given class is a generated proxy class.
-=== StringUtils
+==== StringUtils
A collection of utilities for working with Strings.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/data.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/data.adoc b/documentation/src/main/asciidoc/data.adoc
index 506bc10..6f1d245 100644
--- a/documentation/src/main/asciidoc/data.adoc
+++ b/documentation/src/main/asciidoc/data.adoc
@@ -4,23 +4,10 @@
:toc:
-== Introduction
-
-The repository pattern used to be one of the core J2EE patterns and
-could be found in most enterprise applications reading and writing data
-to persistent stores. While the Java Persistence API (JPA) as part of
-Java EE 5+ has replaced many aspects of the repository pattern, it is
-still a good approach to centralize complex query logic related to
-specific entities.
-
-The DeltaSpike Data module is intended to help you simplifying your
-repository layer. While you will have complex queries in a repository
-requiring your full attention, there will also be many simple ones often
-requiring boilerplate code and clutter. This is where the DeltaSpike
-Data module will help you keeping your repository lean so you can focus
-on the though things.
-
-The code sample below will give you a quick overview on the common usage
+== Overview
+The Data module provides capabilities for implementing repository patterns and thereby simplifying the repository layer. Repository patterns are ideal for simple queries that require boilerplate code, enabling cenertalization of query logic and consequently reducing code duplication and improving testability.
+
+The code sample below gives you a quick overview on the common usage
scenarios of the data module:
[source,java]
@@ -55,77 +42,54 @@ extension. A client can declare a dependency to the interface only. The
details on how to use those features are outlines in the following
chapters.
+== Configure Your Projects
-== Installation
-
-
-=== Prerequisites
-
-
-The simplest way using the DeltaSpike Data module is to run your
-application in a Java EE container supporting at least the Java EE 6 Web
-Profile. Other configurations like running it inside Tomcat or even a
-Java SE application should be possible - you need to include a JPA
-provider as well as a CDI container to your application manually.
-
-Also note that in order to use abstract classes as repositories, this
-currently requires the presence of the
-http://www.javassist.org[javassist] library in your classpath.
-
-*CAUTION:*
-
-________________________________________________________________________________________________
-Using DeltaSpike Data in an EAR deployment is currently restricted to
-annotation-based entities.
-________________________________________________________________________________________________
-
-=== Maven Dependency Configuration
+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 Data Module Dependencies
-If you are using Maven as your build tool, you can add the following
-dependencies to your `pom.xml` file to include the DeltaSpike data
-module:
+Add the Data module to the list of dependencies in the project `pom.xml` file using this code snippet:
[source,xml]
---------------------------------------------------------
+----
<dependency>
<groupId>org.apache.deltaspike.modules</groupId>
<artifactId>deltaspike-data-module-api</artifactId>
<version>${deltaspike.version}</version>
<scope>compile</scope>
</dependency>
+
<dependency>
<groupId>org.apache.deltaspike.modules</groupId>
<artifactId>deltaspike-data-module-impl</artifactId>
<version>${deltaspike.version}</version>
<scope>runtime</scope>
</dependency>
---------------------------------------------------------
+----
-*TIP:*
+=== 2. Complete Additional Java Environment Configuration
-______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
-Substitute the expression `${deltaspike.version}` with the most recent
-or appropriate version of DeltaSpike. Alternatively, you can create a
-Maven user-defined property to satisfy this substitution so you can
-centrally manage the version.
-______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
+The Data module requires a JPA implementation to be available in the Java environment where your projects are deployed.
-Including the API at compile time and only include the implementation at
-runtime protects you from inadvertantly depending on an implementation
-class.
+The simplest way using the DeltaSpike Data module is to run your
+application in a Java EE container supporting at least the Java EE6 Web
+Profile. Other configurations like running it inside Tomcat or even a
+Java SE application should be possible - you need to include a JPA
+provider as well as a CDI container to your application manually.
+Also note that in order to use abstract classes as repositories, this
+currently requires the presence of the
+http://www.javassist.org[javassist] library in your classpath.
-=== Setup your application
+=== 3. Complete Additional Project Configuration
DeltaSpike Data requires an `EntityManager` exposed via a CDI producer -
-which is common practice in Java EE 6 applications.
+which is common practice in Java EE6 applications.
[source,java]
------------------------------------------------------
public class EntityManagerProducer
{
-
@PersistenceUnit
private EntityManagerFactory emf;
@@ -142,7 +106,6 @@ public class EntityManagerProducer
em.close();
}
}
-
}
------------------------------------------------------
@@ -155,25 +118,26 @@ configure the `TransactionStrategy` your repositories use. Adapt your
`beans.xml` for this:
[source,xml]
-----------------------------------------------------------------------------------------------------
+----
<beans>
<alternatives>
<class>org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy</class>
</alternatives>
</beans>
-----------------------------------------------------------------------------------------------------
-
-You're now ready to use repositories in your application!
+----
+== Use the Module Features
-== Core Concepts
+IMPORTANT: Using the DeltaSpike Data module in an EAR deployment is currently restricted to
+annotation-based entities.
-=== Repositories
+=== Core Concepts
+==== Repositories
With the DeltaSpike Data module, it is possible to make a repository out
of basically any abstract class or interface (using a concrete class
-will work too, but you won't be able to use most of the CDI extension
+will work too, but you will not be able to use most of the CDI extension
features). All that is required is to mark the type as such with a
simple annotation:
@@ -198,7 +162,7 @@ classes or interfaces this is the only way to tell the framework what
entity the repository relates to. In order to simplify this, DeltaSpike
Data provides several base types.
-==== The `EntityRepository` interface
+===== The `EntityRepository` Interface
Although mainly intended to hold complex query logic, working with both
a repository and an `EntityManager` in the service layer might
@@ -254,19 +218,13 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
------------------------------------------------------------------------
-*TIP:*
-
-_____________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
-Annotations on interfaces do not inherit. If the `EntityRepository`
+TIP: Annotations on interfaces do not inherit. If the `EntityRepository`
interface is extended by another interface adding some more common
methods, it is not possible to simply add the annotation there. It needs
to go on each concrete repository. The same is not true if a base class
is introduced, as we see in the next chapter.
-_____________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
-
-
-==== The `AbstractEntityRepository` class
+===== The `AbstractEntityRepository` Class
This class is an implementation of the `EntityRepository` interface and
provides additional functionality when custom query logic needs also to
@@ -308,7 +266,7 @@ public interface PersonRepository implements Deactivatable{
}
----------------------------------------
-=== Using Multiple `EntityManager`
+==== Using Multiple `EntityManager`
While most applications will run just fine with a single
`EntityManager`, there might be setups where multiple data sources are
@@ -336,17 +294,17 @@ public class CrmEntityManagerResolver implements EntityManagerResolver
}
--------------------------------------------------------------------------------------------------------------
-Again, note that annotations on interfaces do not inherit, so it's not
+Again, note that annotations on interfaces do not inherit, so it is not
possible to create something like a base `CrmRepository` interface with
the `@EntityManagerConfig` and then extending / implementing this
interface.
-=== Other `EntityManager` methods
+==== Other `EntityManager` Methods
While the `EntityRepository` methods should cover most interactions
normally done with an `EntityManager`, for some specific cases it might
still be useful to have one or the other method available. For this
-case, it's possible to extend / implement the `EntityManagerDelegate`
+case, it is possible to extend / implement the `EntityManagerDelegate`
interface for repositories, which offers most other methods available in
a JPA 2.0 `EntityManager`:
@@ -359,14 +317,14 @@ public interface PersonRepository extends EntityRepository<Person, Long>, Entity
}
-------------------------------------------------------------------------------------------------------
-== Query Method Expressions
+=== Query Method Expressions
Good naming is a difficult aspects in software engineering. A good
method name usually makes comments unnecessary and states exactly what
the method does. And with method expressions, the method name is
actually the implementation!
-=== Using method expressions
+==== Using Method Expressions
Let's start by looking at a (simplified for readability) example:
@@ -437,9 +395,9 @@ Note that DeltaSpike will validate those expressions during startup, so
you will notice early in case you have a typo in those expressions.
-=== Query Ordering
+==== Query Ordering
-Beside comparators it's also possible to sort queries by using the
+Beside comparators it is also possible to sort queries by using the
`OrderBy` keyword, followed by the attribute name and the direction
(`Asc` or `Desc`).
@@ -454,7 +412,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
------------------------------------------------------------------------------
-=== Nested Properties
+==== Nested Properties
To create a comparison on a nested property, the traversal parts can be
separated by a `_`:
@@ -470,7 +428,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
------------------------------------------------------------------------
-=== Query Options
+==== Query Options
DeltaSpike supports query options on method expressions. If you want to
@@ -488,7 +446,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
-----------------------------------------------------------------------------------------------
-=== Method Prefix
+==== Method Prefix
In case the `findBy` prefix does not comply with your team conventions,
this can be adapted:
@@ -504,7 +462,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
--------------------------------------------------------------------------------------------------
-== Query Annotations
+=== Query Annotations
While method expressions are fine for simple queries, they will often
reach their limit once things get slightly more complex. Another aspect
@@ -514,7 +472,7 @@ cases, the DeltaSpike Data module supports also annotating methods for
more control on the generated query.
-=== Using Query Annotations
+==== Using Query Annotations
The simples way to define a specific query is by annotating a method and
providing the JPQL query string which has to be executed. In code, this
@@ -568,11 +526,8 @@ in the method. If the named query requires named parameters to be used,
this can be done by annotating the arguments with the `@QueryParam`
annotation.
-*TIP:*
-_________________________________________________________________________________________
-Java does not preserve method parameter names (yet), that's why the
+TIP: Java does not preserve method parameter names (yet), that's why the
annotation is needed.
-_________________________________________________________________________________________
[source,java]
---------------------------------------------------------------------------------------------
@@ -614,7 +569,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
}
------------------------------------------------------------------------------------
-=== Annotation Options
+==== Annotation Options
Beside providing a query string or reference, the `@Query` annotation
provides also two more attributes:
@@ -640,7 +595,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
Note that these options can also be applied to method expressions.
-=== Query Options
+==== Query Options
All the query options you have seen so far are more or less static. But
sometimes you might want to apply certain query options dynamically. For
@@ -673,18 +628,14 @@ List<Person> result = personRepository.findAllByAge(18, 65)
.getResultList();
-----------------------------------------------------------
-*CAUTION:*
-________________________________________________________________________________________________________________________________________________________________________________________________
-Note that sorting is only applicable to method expressions or non-named
+IMPORTANT: Note that sorting is only applicable to method expressions or non-named
queries. For named queries it might be possible, but is currently only
supported for Hibernate, EclipseLink and OpenJPA.
-________________________________________________________________________________________________________________________________________________________________________________________________
Note that the `QueryResult` return type can also be used with method
expressions.
-=== Pagination
-
+==== Pagination
We introduced the `QueryResult` type in the last chapter, which can also
be used for pagination:
@@ -704,8 +655,7 @@ QueryResult<Person> paged = personRepository.findByAge(age)
int totalPages = paged.countPages();
-----------------------------------------------------------
-
-=== Bulk Operations
+==== Bulk Operations
While reading entities and updating them one by one might be fine for
many use cases, applying bulk updates or deletes is also a common usage
@@ -728,7 +678,7 @@ public interface PersonRepository extends EntityRepository<Person, Long>
Bulk operation query methods can either return void or int, which counts
the number of entities affected by the bulk operation.
-=== Optional Query Results
+==== Optional Query Results
The JPA spec requires to throw exceptions in case the
`getSingleResult()` method does either return no or more than one
@@ -738,12 +688,12 @@ might roll it back).
DeltaSpike Data gives the option to change this to the way it makes most
sense for the current usecase. While the default behavior is still fully
-aligned with JPA, it's also possible to request optional query results.
+aligned with JPA, it is also possible to request optional query results.
-=== Zero or One Result
+==== Zero or One Result
With this option, the query returns `null` instead of throwing a
-`NoResultException` when there is no result returned. It's usable with
+`NoResultException` when there is no result returned. It is usable with
method expressions, `Query` annotations and `QueryResult<E>` calls.
[source,java]
@@ -767,9 +717,9 @@ with the `SingleResultType.OPTIONAL` enum.
In case the query returns more than one result, a
`NonUniqueResultException` is still thrown.
-=== Any Result
+==== Any Result
-If the caller does not really mind what kind if result is returned, it's
+If the caller does not really mind what kind if result is returned, it is
also possible to request any result from the query. If there is no
result, same as for optional queries `null` is returned. In case there
is more than one result, any result is returned, or more concretely the
@@ -795,8 +745,7 @@ annotations, the `singleResult` attribute can be overridden with the
This option will not throw an exception.
-== Transactions
-
+=== Transactions
If you call any method expression, `@Query`-annotated method or a method
from the `EntityRepository`, the repository will figure out if a
@@ -805,19 +754,14 @@ ongoing. The Data module uses the `TransactionStrategy` provided by the
http://deltaspike.apache.org/jpa[JPA Module] for this. See the JPA
module documentation for more details.
-*CAUTION:*
-_______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
-Some containers do not support `BeanManagedUserTransactionStrategy`! As
+IMPORTANT: Some containers do not support `BeanManagedUserTransactionStrategy`! As
JTA has still some portability issues even in Java EE 7, it might be
required that you implement your own `TransactionStrategy`. We will
think about providing an acceptable solution for this.
-_______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
-*CAUTION:*
-__________________________________________________________________________________________
-Annotating Repository methods with `@Transactional` is not yet
+IMPORTANT: Annotating Repository methods with `@Transactional` is not yet
supported, but will follow.
-__________________________________________________________________________________________
+
If you need to open a transaction on a concrete repository method, we
currently recommend creating an extension (see next chapter) which uses
@@ -841,14 +785,11 @@ public class TxExtension<E> implements TxRepository // this is your extension in
Repositories can then implement the `TxRepository` interface and call
their queries in the `transactional` method (where the callback
-implementation can be e.g. in an anonymous class).
-
-
-== Extensions
+implementation can be, for example, in an anonymous class).
+=== Extensions
-=== Query Delegates
-
+==== Query Delegates
While repositories defines several base interfaces, there might still be
the odd convenience method that is missing. This is actually intentional
@@ -874,7 +815,7 @@ public interface PersonRepository extends QueryDslSupport
}
---------------------------------------------------------
-=== Implementing the Query Delegate
+==== Implementing the Query Delegate
The first step is to define an interface which contains the extra
methods for your repositories (as shown above):
@@ -888,8 +829,8 @@ public interface QueryDslSupport
--------------------------------
As a next step, you need to provide an implementation for this interface
-once. It's also important that this implementation implements the
-`DelegateQueryHandler` interface (don't worry, this is just an empty
+once. It is also important that this implementation implements the
+`DelegateQueryHandler` interface (do not worry, this is just an empty
marker interface):
[source,java]
@@ -917,11 +858,11 @@ Note that, if you define multiple extensions with equivalent method
signatures, there is no specific order in which the implementation is
selected.
-== Mapping
+=== Mapping
While repositories are primarily intended to work with Entities, it
might be preferable in some cases to have an additional mapping layer on
-top of them, e.g. because the Entities are quite complex but the service
+top of them, for example because the Entities are quite complex but the service
layer needs only a limited view on it, or because the Entities are
exposed over a remote interface and there should not be a 1:1 view on
the domain model.
@@ -985,12 +926,12 @@ are converted before executing queries and calling repository
extensions.
Note that those mapper classes are treated as CDI Beans, so it is
-possible to use injection in those beans (you might e.g. inject an
+possible to use injection in those beans (e.g. you might inject an
`EntityManager` or other mappers). As the `@MappingConfig` refers to the
mapper class directly, the mapper must be uniquely identifiable by its
class.
-It's also possible to combine mappings with the base Repository classes:
+It is also possible to combine mappings with the base Repository classes:
[source,java]
-------------------------------------------------------------------------------
@@ -1007,10 +948,9 @@ is mandatory. Also it is up to the mapper to convert parameters
correctly (in this example, a conversion from a `PersonDto` parameter to
`Person` entity and from `PersonId` to `Long` is necessary).
-=== Simple Mappings
-
+==== Simple Mappings
-In many cases it's just required to map a DTO object back and forth. For
+In many cases it is just required to map a DTO object back and forth. For
this case, the `SimpleQueryInOutMapperBase` class can be subclassed,
which only requires to override two methods:
@@ -1048,30 +988,25 @@ created. In any case, there is no need to map the primary key to the
entity (it either does not exist or is already populated for an existing
entity).
-
-== JPA Criteria API Support
+=== JPA Criteria API Support
Beside automatic query generation, the DeltaSpike Data module also
provides a DSL-like API to create JPA 2 Criteria queries. It takes
advantage of the JPA 2 meta model, which helps creating type safe
queries.
-*TIP:*
-______________________________________________________________________________________________________________________________________________________________________________________
-The JPA meta model can easily be generated with an annotation processor.
+TIP: The JPA meta model can easily be generated with an annotation processor.
Hibernate or EclipseLink provide such a processor, which can be
integrated into your compile and build cycle.
-______________________________________________________________________________________________________________________________________________________________________________________
Note that this criteria API is not intended to replace the standard
-criteria API - it's rather a utility API that should make life easier on
+criteria API - it is rather a utility API that should make life easier on
the most common cases for a custom query. The JPA criteria API's
strongest point is certainly its type safety - which comes at the cost
of readability. We're trying to provide a middle way here. A less
powerful API, but still type safe and readable.
-
-=== API Usage
+==== API Usage
The API is centered around the Criteria class and is targeted to provide
a fluent interface to write criteria queries:
@@ -1130,8 +1065,7 @@ Once all comparators and query options are applied, the `createQuery()`
method is called. This creates a JPA TypedQuery object for the
repository entity. If required, further processing can be applied here.
-
-=== Joins
+==== Joins
For simple cases, restricting on the repository entity only works out
fine, but once the Data model gets more complicated, the query will have
@@ -1178,8 +1112,7 @@ public abstract class PersonRepository extends AbstractEntityRepository<Person,
}
-------------------------------------------------------------------------------------
-
-=== Boolean Operators
+==== Boolean Operators
By default, all query operators are concatenated as an and conjunction
to the query. The DeltaSpike criteria API also allows to add groups of
@@ -1207,8 +1140,7 @@ public abstract class PersonRepository extends AbstractEntityRepository<Person,
}
-------------------------------------------------------------------------------------
-
-=== Selections
+==== Selections
It might not always be appropriate to retrieve full entities - you might
also be interested in scalar values or by modified entity attributes.
@@ -1262,19 +1194,15 @@ selection clause:
|===
-== Auditing
+=== Auditing
A common requirement for entities is tracking what is being done with
them. DeltaSpike provides a convenient way to support this requirement.
-*TIP:*
-______________________________________________________________________________________________________________________________________
-DeltaSpike does not support creating revisions of entities. If this is a
+NOTE: DeltaSpike does not support creating revisions of entities. If this is a
requirement for your audits, have a look at Hibernate Envers.
-______________________________________________________________________________________________________________________________________
-
-=== Activating Auditing
+==== Activating Auditing
DeltaSpike uses an entity listener to update auditing data before
entities get created or update. The entity listener must be activated
@@ -1316,12 +1244,12 @@ Note that for this variant, you need a compile dependency on the impl
module. Alternatively, also the per entity listener can be configured by
XML.
-=== Using Auditing Annotations
+==== Using Auditing Annotations
All that has to be done now is annotating the entity properties which
are used to audit the entity.
-==== Updating Timestamps
+===== Updating Timestamps
To keep track on creation and modification times, following annotations
can be used:
@@ -1354,9 +1282,9 @@ the annotation can be customized:
@ModifiedOn(setOnCreate=true)
-----------------------------
-==== Who's Changing My Entities?
+===== Who's Changing My Entities?
-Beside keeping track of when a change has happened, it's also often
+Beside keeping track of when a change has happened, it is also often
critical to track who's responsible for the change. Annotate a user
tracking field with the following annotation:
@@ -1399,12 +1327,9 @@ public class UserProvider
}
----------------------------------
-*TIP:*
-______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
-The JPA Spec does not recommend to modify entity relations from within a
+TIP: The JPA Spec does not recommend to modify entity relations from within a
lifecycle callback. If you expose another entity here, make sure that
your persistence provider supports this. Also you should ensure that the
entity is attached to a persistent context. Also, be aware that the CDI
container will proxy a scoped bean, which might confuse the persistence
provider when persisting / updating the target entity.
-______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
[9/9] deltaspike git commit: DELTASPIKE-690: Fixed repeated typo in
.adocs
Posted by ra...@apache.org.
DELTASPIKE-690: Fixed repeated typo in .adocs
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/fcb0fee3
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/fcb0fee3
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/fcb0fee3
Branch: refs/heads/master
Commit: fcb0fee3a4ddc258f3a2356d183dd7001b2bc272
Parents: 10c4e88
Author: michellemurray <mm...@redhat.com>
Authored: Mon Dec 15 08:57:41 2014 +1000
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Dec 15 20:24:46 2014 -0200
----------------------------------------------------------------------
documentation/src/main/asciidoc/jsf.adoc | 32 ++++++++++----------
.../src/main/asciidoc/projectstage.adoc | 2 +-
documentation/src/main/asciidoc/spi.adoc | 2 +-
3 files changed, 18 insertions(+), 18 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/fcb0fee3/documentation/src/main/asciidoc/jsf.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jsf.adoc b/documentation/src/main/asciidoc/jsf.adoc
index 99f1c21..97ed3ae 100644
--- a/documentation/src/main/asciidoc/jsf.adoc
+++ b/documentation/src/main/asciidoc/jsf.adoc
@@ -304,7 +304,7 @@ public class MyClientWindow implements ClientWindow
}
---------------------------------------------------
-Dois not forget to set the `ClientWindowRenderMode` to 'CUSTOM' via the
+Do not forget to set the `ClientWindowRenderMode` to 'CUSTOM' via the
`JsfModuleConfig`:
[source,java]
@@ -357,7 +357,7 @@ In such an use-case you can use this scope. The simple rule is, as long
as the bean is referenced by a page - the bean will be available for the
next page (if it is used again the bean will be forwarded again). It is
important that it is based on the view-id of a page (it isis not based on
-the request) so, for example, Ajax requests dois not trigger a cleanup if the
+the request) so, for example, Ajax requests do not trigger a cleanup if the
request doesis not access all view-access scoped beans of the page. That's
also the reason for the name @__View__AccessScoped.
@@ -400,7 +400,7 @@ with:
Furthermore, the managed-bean annotation (javax.faces.bean.ManagedBean)
is mapped to @Named from CDI.
-All these annotations are mapped automatically. So you wois not face
+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.
@@ -415,7 +415,7 @@ messages (Section 2.5.2.4 of the JSF specification contains the list of
all JSF default messages that could be override.).
DeltaSpike can also reuse the same file to provide type-safe messages so
-you dois not have to use the naming convention nor `@MessageContextConfig`.
+you do not have to use the naming convention nor `@MessageContextConfig`.
If there is a config for supported locales it will be checked as well
and fallback to the configured default locale.
@@ -488,7 +488,7 @@ type-safe meta-data for security, navigation, callbacks for
view-controllers. Beyond configuring view (/pages) via this concept,
it is also possible to use the (view-)config classes for type-safe
navigation. Since it is standard Java, you can benefit from any Java-IDE and
-you dois not need special IDE-Addons to use it efficiently.
+you do not need special IDE-Addons to use it efficiently.
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
@@ -506,7 +506,7 @@ more work **initially**?
*The long answer is:* You can benefit from it from the first second:
* It is type-safe
-** the Java compiler ensures that you dois not have typos at the final usages (and the rest can be checked during bootstrapping of the application)
+** the Java compiler ensures that you do not have typos at the final usages (and the rest can be checked during bootstrapping of the application)
** you can benefit from the auto.complete features of any modern Java IDE.
* If you change the name of a file/folder, you need only one (easy) code-change in a single place and your (standard Java-) IDE will do the rest for you (= update all usages) without a special plug-in
* It is possible to restrict the navigation target -> you can ensure that the navigation target is still the intended one (e.g. after a refactoring)
@@ -535,7 +535,7 @@ like to use the mode `annotated`, please have a look at the tip at
While reading this section keep the following simple rules in mind:
Meta-data gets inherited along the path of Java inheritance
File-/Folder- paths are build based on nesting classes and interfaces
-Usually users dois not need to be aware of all descriptors, SPIs,... which
+Usually users do not need to be aware of all descriptors, SPIs,... which
are described by this documentation.
There are a lot of possibilities to configure views and some of them are
@@ -662,7 +662,7 @@ public Class<? extends Pages.Admin> toNextPage()
`@View` as well as `@Folder` are optional annotations. `@Folder` is only
needed for using a different folder-name or for marking folder configs
-if they dois not inherit from
+if they do not inherit from
`org.apache.deltaspike.core.api.config.view.ViewConfig` *nor* have a
view-config for a page nested into them (like Pages.Wizard1.Step1). If
it isis not used explicitly, it gets added automatically (so you can query
@@ -716,7 +716,7 @@ To customize it you can use `@Folder#name`, `@View#basePath`,
The rules are pretty simple. You will get what you write. There are only
two additional features:
-* You dois not have to care about duplicated '/' (e.g. /folder1//folder2/step1.xhtml would get corrected auto. to /folder1/folder2/step1.xhtml)
+* You do not have to care about duplicated '/' (e.g. /folder1//folder2/step1.xhtml would get corrected auto. to /folder1/folder2/step1.xhtml)
* With "." at the beginning (e.g. "./") you can keep the path before.
The following example
@@ -1068,7 +1068,7 @@ public class IndexController implements Serializable
----------------------------------------------------
The above example leads to the invocation of the pre-render-view logic before
-/pages/page1.xhtml gets rendered (and it wois not be called for other
+/pages/page1.xhtml gets rendered (and it will not be called for other
pages).
===== Using the (Optional) ViewNavigationHandler
@@ -1278,7 +1278,7 @@ annotation in one annotation.
Instead of using the same combination of annotations in multiple places,
you can use the stereotype annotation. If you query the meta-data at
runtime (see `ViewConfigDescriptor#getMetaData`), you can access
-`@Secured` as well as `@View` (in the example above). however, you wois not
+`@Secured` as well as `@View` (in the example above). however, you will not
see `@MySecuredView` itself at runtime, because stereotype annotations
are by default transparent.
@@ -1367,7 +1367,7 @@ 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
view-config without a corresponding view). Right now the validation is
restricted to folders and view-ids with .xhtml or .jsp as suffix. Other
-view-ids (e.g. *.faces) dois not get checked. In such cases a custom
+view-ids (e.g. *.faces) do not get checked. In such cases a custom
validator can be used (e.g. based on `ViewConfigPathValidator`).
To disable the view-config (path) validation, add a `ClassDeactivator`
@@ -1458,11 +1458,11 @@ is possible via `Folder.folderNameBuilder`.
Available from DeltaSpike 0.6.
-DeltaSpike conversations are based on the window-scope. Therefore, dois not
+DeltaSpike conversations are based on the window-scope. Therefore, do not
forget to add the `ds:windowId`
(`xmlns:ds="http://deltaspike.apache.org/jsf"`) component in case of
`ClientWindowConfig#CLIENTWINDOW` to your page(/template) and ensure
-that the window-handling works properly (otherwise conversations wois not
+that the window-handling works properly (otherwise conversations will not
work correctly). The base principle is similar to CODI-Conversations.
CODI users just have to ensure that they have to add `ds:windowId` and
the names are slightly different.
@@ -1540,7 +1540,7 @@ logical group of beans. Technically `@ConversationGroup` is just a CDI
qualifier. Internally DeltaSpike uses this information to identify a
conversation. In the previous example both beans exist in the same
conversation (group). If you terminate the conversation group, both
-beans will be destroyed. If you dois not use `@ConversationGroup`
+beans will be destroyed. If you do not use `@ConversationGroup`
explicitly, DeltaSpike uses the class of the bean as conversation group.
.Injecting a Conversation Scoped Bean with an Explicit Group
@@ -1713,7 +1713,7 @@ you can close them in a `@PostRenderView` callback.
Due to the parallel conversation concept of DeltaSpike there is no need
of something like nested conversations. Just use them in parallel and
-terminate them in a fine-granular way as soon as you dois not need them any
+terminate them in a fine-granular way as soon as you do not need them any
longer. As described above, you can terminate a whole
conversation-group. However, sometimes it is essential to have subgroups
if you need to end just a part of an use-case instead of all beans
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/fcb0fee3/documentation/src/main/asciidoc/projectstage.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/projectstage.adoc b/documentation/src/main/asciidoc/projectstage.adoc
index 287978c..3045d85 100644
--- a/documentation/src/main/asciidoc/projectstage.adoc
+++ b/documentation/src/main/asciidoc/projectstage.adoc
@@ -50,7 +50,7 @@ Therefore, you have to provide an implementation of the
ProjectStage implementations which have to be
`public static final class` and it is required to extend `ProjectStage`.
It is required to provide a `public static final` instance even though,
-you wois not use it directly.
+you will not use it directly.
ProjectStageHolder for custom project stage implementations:
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/fcb0fee3/documentation/src/main/asciidoc/spi.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/spi.adoc b/documentation/src/main/asciidoc/spi.adoc
index bdc0f7a..456ce23 100644
--- a/documentation/src/main/asciidoc/spi.adoc
+++ b/documentation/src/main/asciidoc/spi.adoc
@@ -17,7 +17,7 @@ To deactivate a class it is required to implement `ClassDeactivator`. Returning
IMPORTANT: Due to the ordinal feature of the low-level configuration approach it is possible that a class-deactivator with a higher ordinal, for example 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 third-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 wois not be used any longer.
+as soon as everything is initialized the class-deactivators will not be used any longer.
=== ClassDeactivator
[2/9] deltaspike git commit: DELTASPIKE-690: module adoc pages edited
Posted by ra...@apache.org.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/jpa.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jpa.adoc b/documentation/src/main/asciidoc/jpa.adoc
index 8143a67..a5e32cd 100644
--- a/documentation/src/main/asciidoc/jpa.adoc
+++ b/documentation/src/main/asciidoc/jpa.adoc
@@ -4,37 +4,63 @@
:toc:
-== @Transactional
+== Overview
+The JPA module provides a transactional context and scope, enabling execution of methods within transactions.
-This annotation is an alternative to transactional EJBs which allows to
-execute a method within a transaction. Before it's possible to start
-using the annotation, it's required to implement a CDI producer for an
-`EntityManager` and it's needed to inject the `EntityManager` in the
-bean which uses `@Transactional`. As shown later on it's also possible
-to use multiple qualifiers for using different `EntityManager`s.
+== Configure Your Projects
+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>>.
-*Hint:* If you are using features described by this page with CDI 1.0
-(or DeltaSpike up to v1.1.0 with CDI 1.1+), you have
-to enable the transaction interceptor in your beans.xml file:
+=== 1. Declare JPA Module Dependencies
+Add the JPA module to the list of dependencies in the project `pom.xml` file using this code snippet:
[source,xml]
-------------------------------------------------------------------------------------------
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jpa-module-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jpa-module-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+=== 2. Enable the Transaction Interceptor
+For CDI 1.0 (or DeltaSpike v1.1.0 and earlier together with CDI 1.1+), you must enable the transaction interceptor in the project `beans.xml` file:
+
+[source,xml]
+----
<beans>
<!-- Not needed with CDI 1.1+ and DeltaSpike v1.1.1+ -->
<interceptors>
<class>org.apache.deltaspike.jpa.impl.transaction.TransactionalInterceptor</class>
</interceptors>
</beans>
-------------------------------------------------------------------------------------------
+----
+
+== Use the Module Features
+
+=== @Transactional
+
+This annotation is an alternative to transactional EJBs which allows to
+execute a method within a transaction. Before it is possible to start
+using the annotation, it is required to implement a CDI producer for an
+`EntityManager` and it is needed to inject the `EntityManager` in the
+bean which uses `@Transactional`. As shown later on, it is also possible
+to use multiple qualifiers for using different `EntityManager`s.
The following example shows a simple producer for an `EntityManager` and
the corresponding dispose-method. Producing it as request scoped bean
means that the dispose method will be called on finishing the request.
-As an alternative it's possible to use a special scope called
+As an alternative it is possible to use a special scope called
`@TransactionScoped` provided by the same DeltaSpike module.
-Producer for the default EntityManager (**no EE-Server**):
-
+.Producer for the Default EntityManager (**no EE-Server**)
[source,java]
----------------------------------------------------------------------------
//...
@@ -61,8 +87,7 @@ public class EntityManagerProducer
}
----------------------------------------------------------------------------
-Producer for the default EntityManager (**EE-Server**):
-
+.Producer for the Default EntityManager (**EE-Server**)
[source,java]
-----------------------------------------------------------------------
@ApplicationScoped
@@ -92,8 +117,7 @@ public class EntityManagerProducer
The following examples show how to use the `EntityManager` produced by
the example above.
-Beans with transactional method:
-
+.Beans with Transactional Method
[source,java]
----------------------------------------
//...
@@ -110,8 +134,7 @@ public class TransactionalBean
}
----------------------------------------
-Simple transactional bean (all methods transactional):
-
+.Simple Transactional Bean (All Methods are Transactional)
[source,java]
----------------------------------------
//...
@@ -125,11 +148,10 @@ public class TransactionalBean
}
----------------------------------------
-As illustrated in the following example it's also possible to use
+As illustrated in the following example it is also possible to use
`@Transactional` for stereotypes.
-Stereotype for transactional beans (+ usage):
-
+.Stereotype for Transactional Beans (+ Usage)
[source,java]
----------------------------------------
@Stereotype
@@ -150,14 +172,13 @@ public class TransactionalBean
}
----------------------------------------
-Besides such simple usages, it's also supported to use qualifiers to
+Besides such simple usages, it is also supported to use qualifiers to
access multiple persistence-units in parallel. The default qualifier for
`@Transactional` is `@Any`. Therefore a transaction for every injected
entity manager will be started. The example afterwards shows how to
change this default behaviour.
-Producer for multiple entity managers (+ usage):
-
+.Producer for Multiple Entity Managers (+ Usage)
[source,java]
------------------------------------------------------------------------------------------
//...
@@ -236,8 +257,7 @@ public class NestedTransactionBean
The following example shows how to use only the specified
`EntityManager`/s
-Activating entity managers manually:
-
+.Activating Entity Managers Manually
[source,java]
-----------------------------------------------------------
public class MultiTransactionBean
@@ -277,8 +297,7 @@ All examples also work with nested calls. In the following example the
transaction handling is done on the entry point (after
FirstLevelTransactionBean#executeInTransaction).
-Joining existing transaction in nested call:
-
+.Joining Existing Transaction in Nested Call
[source,java]
----------------------------------------------------------
//...
@@ -313,11 +332,11 @@ public class NestedTransactionBean
The final transaction handling for all `EntityManager` s is also done
after the outermost transactional method if `NestedTransactionBean` uses
-a different `EntityManager`. So it's possible to catch an exception in
-`FirstLevelTransactionBean` e.g. to try an optional path instead of an
+a different `EntityManager`. So it is possible to catch an exception in
+`FirstLevelTransactionBean`, for example, to try an optional path instead of an
immediate rollback.
-== @TransactionScoped
+=== @TransactionScoped
`@Transactional` also starts a context which is available as long as the
transaction started by `@Transactional`. Besides other beans you can use
@@ -325,9 +344,8 @@ this scope for the `EntityManager` itself. That means the
`EntityManager` will be closed after leaving the method annotated with
`@Transactional`.
-Producer for the default EntityManager which should be used only for one
-transaction:
-
+.Producer for the Default EntityManager which should be Used Only for One
+Transaction
[source,java]
----------------------------------------------------------------------------
//...
@@ -354,40 +372,36 @@ public class EntityManagerProducer
}
----------------------------------------------------------------------------
-== Extended Persistence Contexts
-
+=== Extended Persistence Contexts
Frameworks like MyFaces Orchestra provide a feature which allows keeping
-an `EntityManager` across multiple requests. That means it isn't
+an `EntityManager` across multiple requests. That means it is not
required to call `EntityManager#merge` to add detached entities to the
-context. However, several application architectures don't allow such an
+context. However, several application architectures do not allow such an
approach (due to different reasons like scalability). In theory that
sounds nice and it works pretty well for small to medium sized projects
-esp. if an application doesn't rely on session replication in clusters.
+especially if an application does not rely on session replication in clusters.
That also means that such an approach restricts your target environment
from the very beginning. One of the base problems is that an
-`EntityManager` isn't serializable. Beans which are scoped in a
+`EntityManager` is not serializable. Beans which are scoped in a
normal-scoped CDI context have to be serializable. So by default it
-isn't allowed by CDI to provide a producer-method which exposes e.g. a
-conversation scoped `EntityManager` as it is. We *don't* recommend to
-use this approach and therefore it isn't available out-of-the-box.
+is not allowed by CDI to provide a producer-method which exposes, for example, a
+conversation scoped `EntityManager` as it is. We *do not* recommend this approach and therefore it is not available out-of-the-box.
However, if you really need this approach to avoid calling `#merge` for
-your detached entities, it's pretty simple to add this functionality.
-
-Usage of a simple `ExtendedEntityManager`
+your detached entities, it is pretty simple to add this functionality.
+.Usage of a Simple `ExtendedEntityManager`
[source,java]
------------------------------------
@Inject
private EntityManager entityManager;
------------------------------------
-As you see the usage is the same. You *don't* have to use
-`ExtendedEntityManager` at the injection point. It's just needed in the
+As you see the usage is the same. You *do not* have to use
+`ExtendedEntityManager` at the injection point. It is just needed in the
producer-method:
-Producer for the default Extended-`EntityManager` (**no EE-Server**):
-
+.Producer for the Default Extended-`EntityManager` (**no EE-Server**)
[source,java]
------------------------------------------------------------------------------------
//...
@@ -414,8 +428,7 @@ public class ExtendedEntityManagerProducer
}
------------------------------------------------------------------------------------
-Producer for the default Extended-`EntityManager` (**EE-Server**):
-
+.Producer for the Default Extended-`EntityManager` (**EE-Server**)
[source,java]
------------------------------------------------------------------------------------------
@ApplicationScoped
@@ -442,8 +455,7 @@ public class ExtendedEntityManagerProducer
}
------------------------------------------------------------------------------------------
-Implementation of a simple `ExtendedEntityManager`:
-
+.Implementation of a Simple `ExtendedEntityManager`
[source,java]
-------------------------------------------------------------------------
@Typed()
@@ -469,22 +481,22 @@ public class ExtendedEntityManager implements EntityManager, Serializable
}
-------------------------------------------------------------------------
-This approach just works if it *doesn't come to serialization* of this
-wrapper e.g. in case of session-replication. If those beans get
+This approach just works if it *does not come to serialization* of this
+wrapper, for example in case of session-replication. If those beans get
serialized, you have to overcome this restriction by storing the
persistence-unit-name and recreate the `EntityManager` via
`Persistence.createEntityManagerFactory(this.persistenceUnitName).createEntityManager();`
and sync it with the database before closing it on serialization.
Furthermore, you have to intercept some methods of the `EntityManager`
to merge detached entities automatically if those entities get
-serialized as well. However, as mentioned before *we don't recommend*
+serialized as well. However, as mentioned before *we do not recommend*
such an approach.
-== JTA Support
+=== JTA Support
-Per default the transaction-type used by `@Transactional`is
-'RESOURCE_LOCAL'. If you configure `transaction-type="JTA"`in the
-persistence.xml, you have to enable an alternative `TransactionStrategy`
+By default the transaction-type used by `@Transactional` is
+`RESOURCE_LOCAL`. If you configure `transaction-type="JTA"` in the
+persistence.xml file, you have to enable an alternative `TransactionStrategy`
in the beans.xml which is called
`org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy`.
@@ -503,10 +515,9 @@ than the production settings, you can use
`org.apache.deltaspike.jpa.impl.transaction.EnvironmentAwareTransactionStrategy`
instead.
-*Hint:*
-
-In case of some versions of Weld (or OpenWebBeans in BDA mode), you have
+NOTE: In case of some versions of Weld (or OpenWebBeans in BDA mode), you have
to configure it as global-alternative instead of an `<alternatives>` in
-beans.xml. That means you have to add e.g.:
-`globalAlternatives.org.apache.deltaspike.jpa.spi.transaction.TransactionStrategy=org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy`
-to /META-INF/apache-deltaspike.properties
+beans.xml. That means you have to add, for example,
+`globalAlternatives.org.apache.deltaspike.jpa.spi.transaction.TransactionStrategy
+=org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy`
+to `/META-INF/apache-deltaspike.properties`
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/jsf.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jsf.adoc b/documentation/src/main/asciidoc/jsf.adoc
index e261a9b..99f1c21 100644
--- a/documentation/src/main/asciidoc/jsf.adoc
+++ b/documentation/src/main/asciidoc/jsf.adoc
@@ -1,15 +1,60 @@
-= JSF
+= JSF 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:
-== Multi-Window Handling
+== 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.
-=== Intro
+== Configure Your Projects
+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
+Add the JSF module to the list of dependencies in the project `pom.xml` file using this code snippet:
-==== Historic Considerations
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jsf-module-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jsf-module-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+Some EE6 servers cannot handle optional classes. From DeltaSpike 1.0.1, if you do not like the corresponding log entries during startup or the deployment fails, you can use an alternative impl-module (instead of deltaspike-jsf-module-impl):
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-jsf-module-impl-ee6</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</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.
+
+=== Multi-Window Handling
+
+==== Background
+
+===== 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
@@ -19,8 +64,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
@@ -31,8 +75,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
@@ -49,9 +92,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
@@ -61,12 +104,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
@@ -83,9 +126,9 @@ 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 & feel of the windowhandler.html, you can simply
+To customize the look and feel of the windowhandler.html, you can simply
provide a own via:
[source,java]
@@ -101,7 +144,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
@@ -109,15 +152,15 @@ and redirect, with the windowId in the URL, to the same view again. The
current windowId will be stored in the `window.name` variable on the
client side. For all further requests, a lazy check will be performed to
check if the windowId in the URL is matching with the `window.name`. If
-it's not matching, the view will be refreshed with the right windowId in
+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
@@ -125,7 +168,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
@@ -156,31 +199,31 @@ 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
@ViewAccessScoped will not work. This is also the default mode if the
-current request doesn't support Javascript or if the user agent is a
+current request doesis 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
@@ -190,7 +233,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
@@ -204,7 +247,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.
@@ -226,7 +269,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
@@ -246,11 +289,11 @@ 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`
-implementation, you can just do it e.g. via CDI alternatives:
+implementation, you can just do it, for example, via CDI alternatives:
[source,java]
---------------------------------------------------
@@ -261,7 +304,7 @@ public class MyClientWindow implements ClientWindow
}
---------------------------------------------------
-Don't forget to set the `ClientWindowRenderMode` to 'CUSTOM' via the
+Dois not forget to set the `ClientWindowRenderMode` to 'CUSTOM' via the
`JsfModuleConfig`:
[source,java]
@@ -277,21 +320,21 @@ 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
session scope does). Usually you need the window-scope instead of the
-session-scope. There aren't a lot of use-cases which need shared data
+session-scope. There areis not a lot of use-cases which need shared data
between windows.
[source,java]
@@ -304,7 +347,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
@@ -312,10 +355,10 @@ you need beans with a lifetime which is as long as needed and as short
as possible - which are terminated automatically (as soon as possible).
In such an use-case you can use this scope. The simple rule is, as long
as the bean is referenced by a page - the bean will be available for the
-next page (if it's used again the bean will be forwarded again). It is
-important that it's based on the view-id of a page (it isn't based on
-the request) so e.g. Ajax requests don't trigger a cleanup if the
-request doesn't access all view-access scoped beans of the page. That's
+next page (if it is used again the bean will be forwarded again). It is
+important that it is based on the view-id of a page (it isis not based on
+the request) so, for example, Ajax requests dois not trigger a cleanup if the
+request doesis not access all view-access scoped beans of the page. That's
also the reason for the name @__View__AccessScoped.
[source,java]
@@ -327,25 +370,23 @@ public class WizardBean implements Serializable
}
-----------------------------------------------
-Hint: @ViewAccessScoped beans are best used in conjunction with the
+TIP: @ViewAccessScoped beans are best used in conjunction with the
`CLIENTWINDOW` window handling, which ensures a clean browser-tab
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 (since 0.6)
+==== @GroupedConversationScoped (From DeltaSpike 0.6)
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
@@ -359,11 +400,11 @@ with:
Furthermore, the managed-bean annotation (javax.faces.bean.ManagedBean)
is mapped to @Named from CDI.
-All these annotations are mapped automatically. So you won't face
+All these annotations are mapped automatically. So you wois 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.
@@ -374,12 +415,11 @@ messages (Section 2.5.2.4 of the JSF specification contains the list of
all JSF default messages that could be override.).
DeltaSpike can also reuse the same file to provide type-safe messages so
-you don't have to use the naming convention nor `@MessageContextConfig`.
+you dois not have to use the naming convention nor `@MessageContextConfig`.
If there is a config for supported locales it will be checked as well
and fallback to the configured default locale.
-Example:
-
+.Example
[source,java]
------------------------------------------------------------------------------------------------------------
@MessageBundle
@@ -420,8 +460,7 @@ welcome_to_deltaspike=Welcome to DeltaSpike
javax.faces.component.UIInput.REQUIRED = {0}: Please enter a value
------------------------------------------------------------------------------------------------------------
-On faces-config.xml file:
-
+.Faces-config.xml File
[source,xml]
--------------------------------------------------------------------------------------------
<faces-config>
@@ -431,10 +470,9 @@ On faces-config.xml file:
</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
@@ -445,64 +483,59 @@ located here.)
Thanks to features like multiple (meta-data-)inheritance via interfaces,
it provides a powerful approach to bind meta-data to one or multiple
-views. In case of the JSF integration it's possible to provide e.g.
+views. In case of the JSF integration it is possible to provide, for example,
type-safe meta-data for security, navigation, callbacks for
view-controllers. Beyond configuring view (/pages) via this concept,
-it's also possible to use the (view-)config classes for type-safe
-navigation. Since it's std. Java, you can benefit from any Java-IDE and
-you don't need special IDE-Addons to use it efficiently.
+it is also possible to use the (view-)config classes for type-safe
+navigation. Since it is standard Java, you can benefit from any Java-IDE and
+you dois not need special IDE-Addons to use it efficiently.
Even the concepts provided by modules (of DeltaSpike itself) are based
-on the basic API provided by the Core. So it's possible to introduce
+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
simple(r) strings. So why should you use something which is slightly
more work **initially**?
-*The short answer is:*
-
-It gives a good return in case of real applications (esp. beyond simple demos).
-
-*The long answer is:*
+*The short answer is:* It gives a good return in case of real applications (especially beyond simple demos).
-You can benefit from it from the first second:
+*The long answer is:* You can benefit from it from the first second:
-* It's type-safe ->
-** the Java compiler ensures that you don't have typos at the final usages (and the rest can be checked during bootstrapping of the application)
+* It is type-safe
+** the Java compiler ensures that you dois not have typos at the final usages (and the rest can be checked during bootstrapping of the application)
** you can benefit from the auto.complete features of any modern Java IDE.
-* If you change the name of a file/folder, you need only one (easy) code-change in a single place and your (std. Java-) IDE will do the rest for you (= update all usages) without a special plug-in
-* It's possible to restrict the navigation target -> you can ensure that the navigation target is still the intended one (e.g. after a refactoring)
+* If you change the name of a file/folder, you need only one (easy) code-change in a single place and your (standard Java-) IDE will do the rest for you (= update all usages) without a special plug-in
+* It is possible to restrict the navigation target -> you can ensure that the navigation target is still the intended one (e.g. after a refactoring)
* You can configure meta-data in a central place (which can get inherited via *multiple* inheritance based on Java interfaces)
* Easier for developers to find usages
* Allows easy(er) refactorings and maintenance
-* You can use your IDE more efficiently esp. in large projects (there are some users who initially switched to it, because their tools for displaying the config they had before open large config files very slowly...)
-* Modern Java IDEs show inheritance of interfaces and classes in a nice way. Since the view-config is based on std. classes and interfaces, you can benefit from it easily.
+* You can use your IDE more efficiently especially in large projects (there are some users who initially switched to it, because their tools for displaying the config they had before open large config files very slowly...)
+* Modern Java IDEs show inheritance of interfaces and classes in a nice way. Since the view-config is based on standard classes and interfaces, you can benefit from it easily.
Advantages which are planned for later (= currently not supported):
-* It's possible to check if the configured folders and files really exist during/after the bootstrapping phase of the application (currently it isn't implemented, but it's possible to do it).
-* It's also easy(er) for tools (IDE plugins,...) to validate it
-* It's possible to validate the config (if the corresponding path (view or folder) really exists (after v0.5 it's done out-of-the-box)
+* It is possible to check if the configured folders and files really exist during/after the bootstrapping phase of the application (currently it is not implemented, but it is possible to do it).
+* It is also easy(er) for tools (IDE plugins,...) to validate it
+* It is possible to validate the config (if the corresponding path (view or folder) really exists (after v0.5 it is done out-of-the-box)
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 hint at
+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
File-/Folder- paths are build based on nesting classes and interfaces
-Usually users don't need to be aware of all descriptors, SPIs,... which
+Usually users dois not need to be aware of all descriptors, SPIs,... which
are described by this documentation.
There are a lot of possibilities to configure views and some of them are
@@ -519,10 +552,10 @@ public class MyPage implements ViewConfig
}
-----------------------------------------
-Since it's a class (and not an interface) it's autom. recognized as
+Since it is a class (and not an interface), it is automatically recognized as
config for a page (and not a folder) and the default settings get
applied during bootstrapping. In case of JSF you can use it for
-navigation e.g. via action-methods.
+navigation, for example, via action-methods.
[source,java]
-----------------------------------------------
@@ -547,7 +580,7 @@ public class MyPage implements ViewConfig
}
-----------------------------------------
-But it's also possible to reflect the folder structure via nesting of
+But it is also possible to reflect the folder structure via nesting of
interfaces and classes. An example for it is:
[source,java]
@@ -566,17 +599,17 @@ public interface Pages
In case of the JSF integration it leads to the following view-ids:
/pages/index.xhtml /pages/adminArea/index.xhtml
-Like the optional `@View` for pages represented by the classes, it's
+Like the optional `@View` for pages represented by the classes, it is
possible to use the optional `@Folder` annotation for directories
represented by the (nested) interfaces.
-Furthermore, it's possible to inherit meta-data along with the normal
+Furthermore, it is possible to inherit meta-data along with the normal
inheritance.
In the following example `Pages.Admin.Index`, `Pages.Admin.Home` and
`Pages.Admin.Statistics.Home` inherit the meta-data from `Pages.Admin`
because they implement the interface whereas
-`Pages.Admin.Statistics.Index` doesn't. However, `Pages.Admin.Home`
+`Pages.Admin.Statistics.Index` doesis not. However, `Pages.Admin.Home`
overrides `View#navigation`. During the bootstrapping process the
meta-data gets merged and at runtime you only see the final result
(which is cached).
@@ -608,7 +641,7 @@ public interface Pages
------------------------------------------------------
In this case `Pages.Admin.Statistics` is just an interface to reflect
-the folder structure. For sure it's also possible that it extends an
+the folder structure. For sure it is also possible that it extends an
existing view-config interface and other folders and/or pages inherit
its meta-data (like `Pages.Admin`).
@@ -625,17 +658,17 @@ 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
-if they don't inherit from
+if they dois not inherit from
`org.apache.deltaspike.core.api.config.view.ViewConfig` *nor* have a
view-config for a page nested into them (like Pages.Wizard1.Step1). If
-it isn't used explicitly, it gets added automatically (so you can query
-the meta-data at runtime even in cases you haven't placed the
+it isis not used explicitly, it gets added automatically (so you can query
+the meta-data at runtime even in cases you haveis not placed the
annotations explicitly). `@View` allows to customize a bit more and it
-also gets added automatically if it isn't used explicitly. Whereas
+also gets added automatically if it isis not used explicitly. Whereas
`@Folder` gets added to all nested interfaces (above a view-config class
- like Pages and Pages.Wizard1), `@View` only gets added to classes
which in-/directly inherit from
@@ -678,12 +711,12 @@ 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:
-* You don't have to care about duplicated '/' (e.g. /folder1//folder2/step1.xhtml would get corrected auto. to /folder1/folder2/step1.xhtml)
+* You dois not have to care about duplicated '/' (e.g. /folder1//folder2/step1.xhtml would get corrected auto. to /folder1/folder2/step1.xhtml)
* With "." at the beginning (e.g. "./") you can keep the path before.
The following example
@@ -713,9 +746,9 @@ leads to the following paths:
* /w1/step1.xhtml
* /pages/w2/step1.xhtml
-===== @View
+====== @View
-The same naming rules apply to `@View#basePath`. However, it's only
+The same naming rules apply to `@View#basePath`. However, it is only
valid to be used at view-config nodes which represent pages (-> classes
and not interfaces). On interfaces always use `@Folder`
(`@View#basePath` will get ignored there).
@@ -785,21 +818,21 @@ 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
parameters which end up in the final URL after '?' (in case of the
-integration with JSF). It isn't needed to add all (types of) parameters
-that way. Some get added autom. based on special meta-data (e.g.
+integration with JSF). It isis not needed to add all (types of) parameters
+that way. Some get added automatically based on special meta-data (e.g.
`@View#navigation` and `@View#viewParams`). Instead of adding
-`"faces-redirect=true"` manually it's done for you as soon as you are
+`"faces-redirect=true"` manually it is done for you as soon as you are
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's needed to add an information in any case. So you can
+In some cases, it is needed to add an information in any case. So you can
annotate the view-config class with `@NavigationParameter`. Supported
values are static strings or EL-expressions.
@@ -818,7 +851,7 @@ public interface Pages extends ViewConfig
}
---------------------------------------------------------------------------
-Instead of using parameters in any case, it's also possible to configure
+Instead of using parameters in any case, it is also possible to configure
them statically for particular methods:
[source,java]
@@ -843,9 +876,9 @@ public class PageBean
}
-----------------------------------------------------------------------
-===== Dynamic Configuration via NavigationParameterContext
+====== Dynamic Configuration via NavigationParameterContext
-Instead of using parameters in a static fashion (as shown above), it's
+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
conditions).
@@ -873,21 +906,21 @@ 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 3rd party frameworks (or
+Security-module which allows to integrate third-party frameworks (or
custom approaches) to secure pages as well as whole folders. You can
annotate specific parts or a marker-interface.
`CustomAccessDecisionVoter` used in the following example can be any
implementation of
`org.apache.deltaspike.security.api.authorization.AccessDecisionVoter`
-and needs to be a std. CDI bean which means you can use
+and needs to be a standard CDI bean which means you can use
dependecy-injection to trigger any kind of security check. All parts
which inherit from `SecuredPages` (`Pages.Admin`, `Pages.Admin.Index`
and `Pages.Admin.Home`) are protected by `CustomAccessDecisionVoter`.
-(It's easy to check this hierarchy in a modern Java-IDE. Only for
+(It is easy to check this hierarchy in a modern Java-IDE. Only for
displaying the final meta-data for every node in the IDE a special
plug-in would be needed.)
@@ -911,7 +944,7 @@ public interface Pages extends ViewConfig
}
-----------------------------------------------
-For sure it's also possible to use it without a special interface. In
+For sure it is also possible to use it without a special interface. In
this case you would need:
[source,java]
@@ -954,7 +987,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.
@@ -981,12 +1014,11 @@ public class MyPageController
}
------------------------------------------
-Since v0.7 it's possible to observe exceptions thrown by a
+From DeltaSpike 0.7, it is possible to observe exceptions thrown by a
@PreRenderView callback and use your configured Default-Error-View to
display the exception.
-Example:
-
+.Example
[source,java]
--------------------------------------------------------------------------------------------------------------
@ExceptionHandler
@@ -1006,15 +1038,14 @@ 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
in the other direction. Use an existing view-config to reference one or
many view/s.
-That means e.g.
-
+.Example
[source,java]
----------------------------------------------------
public interface Pages extends ViewConfig
@@ -1036,12 +1067,11 @@ public class IndexController implements Serializable
}
----------------------------------------------------
-leads to the invocation of the pre-render-view logic before
-/pages/page1.xhtml gets rendered (and it won't be called for other
+The above example leads to the invocation of the pre-render-view logic before
+/pages/page1.xhtml gets rendered (and it wois 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
@@ -1050,8 +1080,7 @@ command-component. However, also JSF supports manual navigation via
type-safe view-configs which is easier to use (and can be used also for
other (supported) view technology).
-A simple example is:
-
+.Simple Example
[source,java]
-----------------------------------------------------------------
public interface Pages {
@@ -1076,12 +1105,11 @@ 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's possible to mark one view-config class as default error-view. That
+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
-automatically. Furthermore, it's also possible to use it in your code
+automatically. Furthermore, it is also possible to use it in your code
instead of hardcoding your error-view across the whole application.
In case of
@@ -1095,7 +1123,7 @@ public interface Pages {
}
------------------------------------------------------
-it's possible to navigate with `DefaultErrorView.class` instead of
+it is possible to navigate with `DefaultErrorView.class` instead of
hardcoding it to `Pages.CustomErrorPage.class`.
[source,java]
@@ -1137,14 +1165,13 @@ public class AnyController
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 std. (implicit) JSF navigation.
+transformed to a standard (implicit) JSF navigation.
-==== Using @Matches
+===== Using @Matches
This annotation is currently not integrated. [TODO]
-
-==== Using ViewConfigResolver
+===== Using ViewConfigResolver
If you would like to query view-meta-data yourself (for whatever
reason), you can do that with `ViewConfigResolver`.
@@ -1190,23 +1217,23 @@ public class ApiDemoBean
}
----------------------------------------------------------------------------------------------------------------------------------------
-For folders it's optional to implement the `ViewConfig` interface,
+For folders it is optional to implement the `ViewConfig` interface,
therefore you see 2 different types of API. `#getConfigDescriptor` as
the general API and `#getViewConfigDescriptor` which is specific for
pages (which have to implement the `ViewConfig` interface).
*Besides* translating a config class to the final path of the folder or
-page, it's possible to get the implicitly as well as explicitly
+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
[TODO]
-==== 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. Per default meta-data of a lower level overrides
+used for view-configs. By default meta-data of a lower level overrides
meta-data on a higher level which has the same type. That can be
customized via annotating the final annotation as a whole via
`@Aggregated(true)`.
@@ -1231,13 +1258,12 @@ 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.
-e.g.:
-
+.Example
[source,java]
-------------------------------------------------------------
@Target({TYPE})
@@ -1252,17 +1278,17 @@ e.g.:
Instead of using the same combination of annotations in multiple places,
you can use the stereotype annotation. If you query the meta-data at
runtime (see `ViewConfigDescriptor#getMetaData`), you can access
-`@Secured` as well as `@View` (in the example above). however, you won't
+`@Secured` as well as `@View` (in the example above). however, you wois not
see `@MySecuredView` itself at runtime, because stereotype annotations
-are per default transparent.
+are by default transparent.
-Since v1.0.1+ it's possible to access such stereotype annotations as
+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's possible to register custom
+Via a custom ConfigPreProcessor it is possible to register custom
callbacks dynamically. The following listing shows a view-config which
adds a simple callback including the corresponding `ConfigPreProcessor`
and `ExecutableCallbackDescriptor`.
@@ -1315,103 +1341,94 @@ List<Set<String> /*return type of one callback*/> callbackResult =
.execute("param1", "param2");
------------------------------------------------------------------------------------------------------------------
-It's also possible do register different callback-types per
+It is also possible do register different callback-types per
view-meta-data. An example can be found at `ViewControllerRef` which
registers different callback-types for `InitView`, `PreViewAction`,
-`PreRenderView` and `PostRenderView`. In this case it's needed to use
+`PreRenderView` and `PostRenderView`. In this case it is needed to use
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's used e.g. for `@ViewRef`.
-Via a `TargetViewConfigProvider` it's possible to point to the
+other classes than view-config-classes. It is used, for example, for `@ViewRef`.
+Via a `TargetViewConfigProvider` it is possible to point to the
view-config the meta-data should get applied to and via
-`InlineMetaDataTransformer` it's possible to convert it to a different
+`InlineMetaDataTransformer` it is possible to convert it to a different
meta-data-representation (which allows that at runtime you only have to
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
view-config without a corresponding view). Right now the validation is
restricted to folders and view-ids with .xhtml or .jsp as suffix. Other
-view-ids (e.g. *.faces) don't get checked. In such cases a custom
+view-ids (e.g. *.faces) dois not get checked. In such cases a custom
validator can be used (e.g. based on `ViewConfigPathValidator`).
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
[TODO]
-
-==== ConfigDescriptorValidator
+===== ConfigDescriptorValidator
Allows to validate the final view-config descriptors before they get
-deployed. Since the config-descriptor contains e.g. the final path, it's
+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
optional and only needed if it should result in the same at runtime, but
the inline-meta-data needs a different syntax via a different annotation
-(compared to the view-config meta-data). See e.g. `@ViewRef` vs.
+(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 e.g.
+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. E.g.
-inheritance via std. java inheritance vs. inheritance via nested
+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.
If you are using CDI 1.1+ with bean-discovery-mode `annotated`, you can
use `@ViewConfigRoot` in combination with `@ApplicationScoped` as marker
-annotations. Since DeltaSpike 1.0.1 this combination allows to add all
+annotations. From DeltaSpike 1.0.1, this combination allows to add all
nested interfaces and classes and therefore no additional annotations
(required by bean-discovery-mode `annotated`) are needed. Minimal
example:
@@ -1426,33 +1443,31 @@ 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`
-and/or `View.DefaultExtensionBuilder`. It's possible to change it for
+and/or `View.DefaultExtensionBuilder`. It is possible to change it for
one usage via `View.basePathBuilder` and/or `View.fileNameBuilder`
and/or `View.extensionBuilder` or globally via the config mechanism
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
-== (Grouped-)Conversations
-
-Available with all versions after 0.5.
+Available from DeltaSpike 0.6.
-DeltaSpike conversations are based on the window-scope. Therefore, don't
+DeltaSpike conversations are based on the window-scope. Therefore, dois not
forget to add the `ds:windowId`
(`xmlns:ds="http://deltaspike.apache.org/jsf"`) component in case of
`ClientWindowConfig#CLIENTWINDOW` to your page(/template) and ensure
-that the window-handling works properly (otherwise conversations won't
+that the window-handling works properly (otherwise conversations wois not
work correctly). The base principle is similar to CODI-Conversations.
CODI users just have to ensure that they have to add `ds:windowId` and
the names are slightly different.
-First of all it's important to mention that DeltaSpike starts (grouped)
+First of all, it is important to mention that DeltaSpike starts (grouped)
conversations automatically as soon as you access conversation scoped
beans. Furthermore, the invocation of `GroupedConversation#close` leads
to an immediate termination of the conversation.
@@ -1469,17 +1484,16 @@ public class DemoBean1 implements Serializable
... leads to a conversation which contains just one bean with the group
DemoBean1.
-Hint: If you would like to use the bean within your JSF pages, you have
+TIP: If you would like to use the bean within your JSF pages, you have
to add `@Named` (javax.inject.Named ).
-(In case of CDI std. conversations there is just one big conversation
+(In case of CDI standard conversations there is just one big conversation
which contains all conversation scoped beans.) The grouped conversations
provided by DeltaSpike are completely different. By default every
conversation scoped bean exists in an "isolated" conversation. That
means there are several parallel conversations within the same window.
-Example - Separated DeltaSpike conversations:
-
+.Separated DeltaSpike Conversations
[source,java]
----------------------------------------------
@GroupedConversationScoped
@@ -1495,14 +1509,13 @@ public class DemoBean3 implements Serializable
}
----------------------------------------------
- ... leads to two independent conversations in the same window (context).
+The above example leads to two independent conversations in the same window (context).
If you close the conversation of DemoBean2, the conversation of
DemoBean3 is still active. If you have an use-case (e.g. a wizard) which
uses multiple beans which are linked together very tightly, you can
create a type-safe conversation group.
-Example - Grouped conversation scoped beans:
-
+.Grouped Conversation Scoped Beans
[source,java]
----------------------------------------------
interface Wizard1 {}
@@ -1527,11 +1540,10 @@ logical group of beans. Technically `@ConversationGroup` is just a CDI
qualifier. Internally DeltaSpike uses this information to identify a
conversation. In the previous example both beans exist in the same
conversation (group). If you terminate the conversation group, both
-beans will be destroyed. If you don't use `@ConversationGroup`
+beans will be destroyed. If you dois not use `@ConversationGroup`
explicitly, DeltaSpike uses the class of the bean as conversation group.
-Example - Injecting a conversation scoped bean with an explicit group:
-
+.Injecting a Conversation Scoped Bean with an Explicit Group
[source,java]
------------------------------------
//...
@@ -1547,14 +1559,13 @@ public class CustomBean1
}
------------------------------------
-Since `@ConversationGroup` is a std. CDI qualifier you have to use it at
-the injection point. You have to do that esp. because it's possible to
+Since `@ConversationGroup` is a standard CDI qualifier you have to use it at
+the injection point. You have to do that especially because it is possible to
create beans of the same type which exist in different groups (e.g. via
producer methods).
-Example - Producer methods which produce conversation scoped beans with
-different groups:
-
+.Producer Methods which Produce Conversation Scoped Beans with
+Different Groups
[source,java]
------------------------------------------------
interface Group1 {}
@@ -1580,16 +1591,15 @@ 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
`GroupedConversationManager` which can be used to terminate a given
conversation (group). All conversations within a window are closed
-autom., once `WindowContext#closeWindow` gets called for the window.
-
-Example - Injecting and using the current conversation:
+automatically, once `WindowContext#closeWindow` gets called for the window.
+.Injecting and Using the Current Conversation
[source,java]
--------------------------------------------------------------------------------------------------------------------
@GroupedConversationScoped
@@ -1621,8 +1631,7 @@ public class DemoBean7 implements Serializable
}
--------------------------------------------------------------------------------------------------------------------
-Example - Injecting and using the explicitly grouped conversation:
-
+.Injecting and Using the Explicitly Grouped Conversation
[source,java]
----------------------------------------------------------------------------------------------------------------------
interface Wizard2 {}
@@ -1658,9 +1667,7 @@ public class DemoBean9 implements Serializable
}
----------------------------------------------------------------------------------------------------------------------
-Example - Terminating a grouped conversation outside of the
-conversation:
-
+.Terminating a Grouped Conversation Outside of the Conversation
[source,java]
-------------------------------------------------------------------------------------------------------------------------
//...
@@ -1678,8 +1685,7 @@ public class DemoBean10 implements Serializable
}
-------------------------------------------------------------------------------------------------------------------------
-Example - Terminate all conversations:
-
+.Terminate All Conversations
[source,java]
-------------------------------------------------------------------------------------------------------------------------
//...
@@ -1697,29 +1703,28 @@ public class DemoBean11 implements Serializable
}
-------------------------------------------------------------------------------------------------------------------------
-Hint: DeltaSpike conversations get closed/restarted immediately instead
-of keeping them until the end of the request like std. conversations do,
-because the behaviour of std. conversations breaks a lot of use-cases.
+TIP: DeltaSpike conversations get closed/restarted immediately instead
+of keeping them until the end of the request like standard conversations do,
+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
-terminate them in a fine-granular way as soon as you don't need them any
+terminate them in a fine-granular way as soon as you dois not need them any
longer. As described above, you can terminate a whole
-conversation-group. However, sometimes it's essential to have subgroups
+conversation-group. However, sometimes it is essential to have subgroups
if you need to end just a part of an use-case instead of all beans
related to an use-case. A sub-group is just a class or an interface used
to identify a bunch of beans within a group. To terminate such a
-sub-group, it's just needed to pass the class/interface to the
+sub-group, it is just needed to pass the class/interface to the
corresponding API for terminating a conversation. The sub-group gets
-detected autom. and instead of terminating a whole conversation-group,
+detected automatically and instead of terminating a whole conversation-group,
the beans of the sub-group get un-scoped.
-Example - Explicitly listing beans of a sub-group:
-
+.Explicitly Listing Beans of a Sub-group
[source,java]
--------------------------------------------------------------------------------
public class MyGroup{}
@@ -1745,8 +1750,7 @@ public class MySubGroup extends MyGroup {}
public class MySubGroup {}
--------------------------------------------------------------------------------
-Example - Terminating a sub-group:
-
+.Terminating a Sub-group
[source,java]
------------------------------------------------------------------
@Inject
@@ -1762,8 +1766,7 @@ the group or you specify it via the `@ConversationSubGroup#of`. With
the sub-group. If you have a lot of such beans or you would like to form
(sub-)use-case oriented groups, you can use implicit groups:
-Example - Implicit sub-group:
-
+.Implicit Sub-group
[source,java]
------------------------------------------------------------------------
public interface Wizard {}
@@ -1788,21 +1791,20 @@ 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 (TODO)
+=== Injection in JSF Artifacts (TODO)
-=== Converter & Validator
+==== Converter and Validator
-=== PhaseListener
+==== PhaseListener
-== Event broadcasting
+=== Event broadcasting
-=== BeforeJsfRequest / AfterJsfRequest (TODO)
+==== BeforeJsfRequest / AfterJsfRequest (TODO)
-=== BeforePhase / AfterPhase (TODO)
-
-=== JSF SystemEvents
+==== BeforePhase / AfterPhase (TODO)
+==== JSF SystemEvents
Following JSF SystemEvents can be observed via CDI:
@@ -1810,8 +1812,7 @@ Following JSF SystemEvents can be observed via CDI:
* javax.faces.event.PreDestroyApplicationEvent
* javax.faces.event.ExceptionQueuedEvent
-Example:
-
+.Example
[source,java]
-------------------------------------------------------------------
@ApplicationScoped
@@ -1824,17 +1825,15 @@ public class ApplicationConfig
}
-------------------------------------------------------------------
-Intergration with Exception Control (since 0.6)
------------------------------------------------
+=== Intergration with Exception Control (from DeltaSpike 0.6)
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
@@ -1850,7 +1849,7 @@ public class ApplicationExceptionHandler
}
-----------------------------------------------------------------------------
-==== Redirect
+===== Redirect
[source,java]
-----------------------------------------------------------------------------------------------------------------------------------
@@ -1870,9 +1869,9 @@ public class ApplicationExceptionHandler
}
-----------------------------------------------------------------------------------------------------------------------------------
-=== Using a custom qualifier for JSF Exceptions
+==== Using a Custom Qualifier for JSF Exceptions
-In some cases, it's required to differentiate exceptions from JSF and
+In some cases, it is required to differentiate exceptions from JSF and
normal exceptions. This is possible via a CDI qualifier:
[source,java]
@@ -1910,10 +1909,10 @@ 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's possible to use the tag
+processed multiple times, it is possible to use the tag
`<ds:preventDoubleSubmit/>`. As usual for DeltaSpike JSF-tags, the `ds`
namespace is `http://deltaspike.apache.org/jsf`. Just add this tag
within every JSF form-tag, you would like to safeguard.
@@ -1935,16 +1934,8 @@ within every JSF form-tag, you would like to safeguard.
</html>
--------------------------------------------------
-== Support of EAR deployments
-
-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.
-
-
-== Hints
+=== Tips
Using errorView, DefaultErrorView or ViewNavigationHandler will fail
-with Weld versions below 1.1.10 due to
+with Weld versions older than 1.1.10 due to
https://issues.jboss.org/browse/WELD-1178[WELD-1178].
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/modules.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/modules.adoc b/documentation/src/main/asciidoc/modules.adoc
index a7a74fd..4af32b6 100644
--- a/documentation/src/main/asciidoc/modules.adoc
+++ b/documentation/src/main/asciidoc/modules.adoc
@@ -9,15 +9,15 @@ DeltaSpike consists of ready-to-use modules. These include a core module and a n
[cols="1,1,2a"]
.DeltaSpike Modules
|===
-|<<core#,Core>> | Required | For the essential API and util classes
+|<<core#,Core>> | Required | For fundamental and defining DeltaSpike API and utility classes
|<<bean-validation#,Bean Validation>> | Optional | For adding CDI support in Bean Validation, enabling creation of CDI aware `ConstraintValidator` methods that can use business objects (EJBs, ManagedBeans) to support validation needs
-|<<container-control#,Container Control>> | Optional |
+|<<container-control#,Container Control>> | Optional | For CDI container booting and shutdown and associated context lifecycle management
|<<data#,Data>> | Optional | For an enhanced JPA experience with declarative queries, reducing boilerplate to a minimum
-|<<jpa#,JPA>> | Optional |
-|<<jsf#,JSF>> | Optional |
-|<<partial-bean#,Partial-Bean>> | Optional |
-|<<scheduler#,Scheduler>> | Optional | For simple integration with Quartz v2 (per default) or any other scheduler which supports cron-expressions for job-classes
-|<<security#,Security>> | Optional | For intercept and check security
+|<<jpa#,JPA>> | Optional | For transactional context and scope
+|<<jsf#,JSF>> | Optional | For 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
+|<<partial-bean#,Partial-Bean>> | Optional | For implementing a generic handler to replace manual implementations of interfaces (or abstract classes)
+|<<scheduler#,Scheduler>> | Optional | For simple integration with Quartz v2 (default) or any other scheduler that supports cron-expressions for job-classes
+|<<security#,Security>> | Optional | For intercept and security checking on method calls
|<<servlet#,Servlet>> | Optional | For integration with the Java Servlet API, enabling injection of common servlet objects and propagation of servlet events to the CDI event bus
-|<<test-control#,Test-Control>> | Optional | For easily writing CDI based tests
+|<<test-control#,Test-Control>> | Optional | For writing CDI-based tests easily
|===
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/overview.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/overview.adoc b/documentation/src/main/asciidoc/overview.adoc
index 01d2724..5bfde2c 100644
--- a/documentation/src/main/asciidoc/overview.adoc
+++ b/documentation/src/main/asciidoc/overview.adoc
@@ -49,7 +49,7 @@ In addition to the portable CDI extension modules, DeltaSpike provides a number
*Injectable resources:* Configuration, resource bundles,... are easy to inject when using CDI and Apache DeltaSpike.
-*@Exclude annotation:* it's possible to annotate beans which should be ignored by CDI even if they are in a CDI enabled archive on Java EE 6/CDI 1.0 environment where you can't use @Vetoed or a veto based on project-stages or expressions is needed.
+*@Exclude annotation:* it is possible to annotate beans which should be ignored by CDI even if they are in a CDI enabled archive on Java EE 6/CDI 1.0 environment where you cais not use @Vetoed or a veto based on ProjectStages or expressions is needed.
**Scheduling tasks**: Async processes in a non Java EE 7 environment.
@@ -76,7 +76,7 @@ In addition to the portable CDI extension modules, DeltaSpike provides a number
*New CDI scopes:* TransactionScoped, WindowScoped, ViewScoped, ViewAccess scope, Grouped conversion scope
-*Container Control & Test Control:* Java SE with CDI, all with a unifying API. Start, stop, add classes to a running CDI container.
+*Container Control and Test Control:* Java SE with CDI, all with a unifying API. Start, stop, add classes to a running CDI container.
*Data Module:* An out of the box entity framework solution complete with support for container or application managed persistence contexts, as well as JDBC.
@@ -86,7 +86,7 @@ In addition to the portable CDI extension modules, DeltaSpike provides a number
*Type-safe i18n messages:* Localized messages are easy to use with an interface and a resource bundle, no more boilerplate and your messages now have context within the code.
-*Type-safe Project-Stages:* Compared to project-stages in JSF, DeltaSpike provides a type-safe, but still extensible approach which can be used in CDI based applications.
+*Type-safe ProjectStages:* Compared to ProjectStages in JSF, DeltaSpike provides a type-safe, but still extensible approach which can be used in CDI based applications.
== Next
For instructions on how to start using DeltaSpike, see <<configure#,Configure DeltaSpike in Your Projects>> and <<cdiimp#,Enable CDI For Your Java Environment>>.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/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 e89ab00..97467d0 100644
--- a/documentation/src/main/asciidoc/partial-bean.adoc
+++ b/documentation/src/main/asciidoc/partial-bean.adoc
@@ -1,10 +1,40 @@
-= Partial-Bean
+= Partial-Bean 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:
-== Usage
+== Overview
+The Partial-Bean module provides means for implementing a generic handler to replace manual implementations of interfaces (or abstract classes).
+
+== Configure Your Projects
+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
+Add the Partial-Bean module to the list of dependencies in the project `pom.xml` file using this code snippet:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-partial-bean-module-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-partial-bean-module-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+== Use the Module Features
+
+IMPORTANT: Currently CDI Interceptors cannot be used for partial-beans.
+
+=== @PartialBeanBinding
Partial beans allow you to implement a generic handler to replace manual
implementations of interfaces (or abstract classes).
@@ -40,5 +70,3 @@ public class MyPartialBeanHandler implements java.lang.reflect.InvocationHandler
Using an abstract class as partial-bean requires javassist as an
additional dependency and allows to implement some methods manually.
-
-Attention: Currently CDI-Interceptors can't be used for partial-beans.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/projectstage.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/projectstage.adoc b/documentation/src/main/asciidoc/projectstage.adoc
index 224521c..287978c 100644
--- a/documentation/src/main/asciidoc/projectstage.adoc
+++ b/documentation/src/main/asciidoc/projectstage.adoc
@@ -7,12 +7,12 @@
== Introduction
Project stages allow to use implementations depending on the current
-environment. E.g. you can implement a bean which creates sample-data for
-system tests which gets activated only in case of project-stage
+environment. For example, you can implement a bean which creates sample-data for
+system tests which gets activated only in case of ProjectStage
`SystemTest`.
-_Besides custom project-stages_ it's possible to use the following
-pre-defined project-stages:
+_Besides custom ProjectStages_ it is possible to use the following
+pre-defined ProjectStages:
* UnitTest
* Development
@@ -22,14 +22,14 @@ pre-defined project-stages:
* Production
The core provides a pluggable and type-safe approach for using project
-stages in a project (it's also used within the framework). Furthermore,
-`@Exclude` allows to use e.g. i mplementations annotated with
-`javax.enterprise.inject.Alternative` for specific project-stages.
-Besides the out-of-the-box project-stages it's possible to implement
-_custom but type-safe_ project-stages which will be exposed by
+stages in a project (it is also used within the framework). Furthermore,
+`@Exclude` allows use of, for example, implementations annotated with
+`javax.enterprise.inject.Alternative` for specific ProjectStages.
+Besides the out-of-the-box ProjectStages it is possible to implement
+_custom but type-safe_ ProjectStages which will be exposed by
DeltaSpike.
-Resolving and using the Project-Stage:
+Resolving and using the ProjectStage:
[source,java]
-------------------------------------------------------------------------------
@@ -44,13 +44,13 @@ boolean isDevProjectStage = ProjectStage.Development.equals(this.projectStage);
=== Custom Project Stages
-It's possible to provide custom project stage implementations.
+It is possible to provide custom project stage implementations.
Therefore, you have to provide an implementation of the
`ProjectStageHolder` interface. In this class you nest the custom
-project-stage implementations which have to be
-`public static final class` and it's required to extend `ProjectStage`.
-It's required to provide a `public static final` instance even though,
-you won't use it directly.
+ProjectStage implementations which have to be
+`public static final class` and it is required to extend `ProjectStage`.
+It is required to provide a `public static final` instance even though,
+you wois not use it directly.
ProjectStageHolder for custom project stage implementations:
@@ -85,24 +85,25 @@ customProjectStage = CustomProjectStageHolder.CustomProjectStage;
----------------------------------------------------------------------------
-=== ProjectStageProducer (for 3rd party portable extensions)
+=== ProjectStageProducer (for Third-party Portable Extensions)
`ProjectStageProducer` provides the producer method which allows to
-inject the current project-stage. However, in some cases it's needed to
-use project-stages also during the bootstrapping process of the CDI
-container and you can't use injection. In such cases you can use
+inject the current ProjectStage. However, in some cases it is needed to
+use ProjectStages also during the bootstrapping process of the CDI
+container and you cais not use injection. In such cases you can use
`ProjectStageProducer.getInstance().getProjectStage()` to resolve the
-current project-stage. This helper also contains helpers for unit-tests
-- e.g. `#setProjectStage`. However, those methods shouldn't be needed
-for users (we just need them for testing different project-stage
+current ProjectStage. This helper also contains helpers for unit-tests
+- e.g. `#setProjectStage`. However, those methods shouldis not be needed
+for users (we just need them for testing different ProjectStage
scenarios).
-==== Setting the active ProjectStage
+==== Setting the Active ProjectStage
For setting the ProjectStage which shall get used in your application
you can specify it in a few ways. The underlying mechanism used to
-determine the string is the ConfigResolver. E.g.:
+determine the string is the ConfigResolver.
+.Example
------------------------------------------------
-Dorg.apache.deltaspike.ProjectStage=Development
------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/10c4e88f/documentation/src/main/asciidoc/scheduler.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/scheduler.adoc b/documentation/src/main/asciidoc/scheduler.adoc
index bf097e3..3ae912b 100644
--- a/documentation/src/main/asciidoc/scheduler.adoc
+++ b/documentation/src/main/asciidoc/scheduler.adoc
@@ -4,28 +4,48 @@
:toc:
-== Intro
+== Overview
+The Scheduler module provides simple integration with Quartz v2 (default) or any other scheduler that supports cron-expressions for job-classes.
-This module provides a simple integration with Quartz v2 (per default)
-or any other scheduler which supports cron-expressions for job-classes.
+== Configure Your Projects
+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
+Add the Scheduler module to the list of dependencies in the project `pom.xml` file using this code snippet:
-== External Dependencies
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-scheduler-module-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
-If you would like to use the default-integration with quartz (which is
-optional), you have to add quartz 2.x.
+<dependency>
+ <groupId>org.apache.deltaspike.modules</groupId>
+ <artifactId>deltaspike-scheduler-module-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+=== 2. Declare External Dependencies
+
+By default, the Scheduler module looks to integrate with Quartz. If this is the scheduler you would like to use, add Quartz 2.x to the list of project dependencies using this code snippet:
[source,xml]
--------------------------------------------
+----
<dependency>
<groupId>org.quartz-scheduler</groupId>
<artifactId>quartz</artifactId>
<version>2.2.1</version>
</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
@@ -54,9 +74,10 @@ 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.:
+With 'false' for `@Scheduled#onStartup`, it is even possible to
+schedule/install jobs dynamically.
+.Example
[source,java]
-------------------------------------------------------------------------------------
@ApplicationScoped
@@ -92,12 +113,12 @@ public class ProjectStageAwareSchedulerController
}
-------------------------------------------------------------------------------------
-== Manual Scheduler Control
+=== Manual Scheduler Control
-This SPI allows to control the scheduler (or integrate any other
+Th SPI allows to control the scheduler (or integrate any other
compatible scheduler as an alternative to Quartz2)
-Via std. injection like
+Via standard injection like
[source,java]
------------------------------------
@@ -105,13 +126,11 @@ Via std. injection like
private Scheduler<Job> jobScheduler;
------------------------------------
-it's possible to manually start/stop the scheduler,
+it is 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
+**Attention**: To use a typed injection-point and avoid deployment failure with some versions of Weld, you must use
[source,java]
------------------------------------------------------------------
@@ -135,11 +154,7 @@ or
</alternatives>
-----------------------------------------------------------------------------
-to use a typed injection-point. Otherwise the deployment will fail.
-
-== Custom Scheduler
+=== 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.
+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 http://org.apache.deltaspike.test.scheduler.custom.
[6/9] deltaspike git commit: DELTASPIKE-690: Addng reorganised and
rewritten content
Posted by ra...@apache.org.
DELTASPIKE-690: Addng reorganised and rewritten content
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/548383b7
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/548383b7
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/548383b7
Branch: refs/heads/master
Commit: 548383b7b7f3dc72c534d59c9160eed944e27190
Parents: 1596f17
Author: michellemurray <mm...@redhat.com>
Authored: Tue Sep 16 22:22:33 2014 +1000
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Mon Dec 15 20:24:45 2014 -0200
----------------------------------------------------------------------
documentation/src/main/asciidoc/addons.adoc | 35 +
documentation/src/main/asciidoc/articles.adoc | 29 +
.../src/main/asciidoc/bean-validation.adoc | 2 +-
documentation/src/main/asciidoc/build.adoc | 247 +++---
documentation/src/main/asciidoc/cdiimp.adoc | 196 +++++
.../src/main/asciidoc/configuration.adoc | 3 +-
documentation/src/main/asciidoc/configure.adoc | 85 +++
.../src/main/asciidoc/container-control.adoc | 2 +-
documentation/src/main/asciidoc/core.adoc | 2 +-
documentation/src/main/asciidoc/data.adoc | 2 +-
documentation/src/main/asciidoc/examples.adoc | 53 ++
documentation/src/main/asciidoc/external.adoc | 63 ++
documentation/src/main/asciidoc/index.adoc | 751 +------------------
documentation/src/main/asciidoc/jpa.adoc | 3 +-
documentation/src/main/asciidoc/jsf.adoc | 3 +-
documentation/src/main/asciidoc/overview.adoc | 71 ++
.../src/main/asciidoc/partial-bean.adoc | 2 +-
.../src/main/asciidoc/projectstage.adoc | 4 +-
documentation/src/main/asciidoc/scheduler.adoc | 2 +-
documentation/src/main/asciidoc/security.adoc | 2 +-
documentation/src/main/asciidoc/servlet.adoc | 2 +-
documentation/src/main/asciidoc/snapshots.adoc | 50 ++
documentation/src/main/asciidoc/source.adoc | 2 +-
documentation/src/main/asciidoc/spi.adoc | 4 +-
.../src/main/asciidoc/test-control.adoc | 2 +-
25 files changed, 734 insertions(+), 883 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/addons.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/addons.adoc b/documentation/src/main/asciidoc/addons.adoc
new file mode 100644
index 0000000..94d0716
--- /dev/null
+++ b/documentation/src/main/asciidoc/addons.adoc
@@ -0,0 +1,35 @@
+= Add-ons
+
+: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:
+
+Add-ons extend the functionality of DeltaSpike and several have been developed external to the DeltaSpike project. Brief information is given here about each of the add-ons, with details of where they can be obtained from.
+
+== Monitoring
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
+* When would the user use this add-on?
+* Where can the user get the add-on from (https://github.com/os890/ds-monitoring-addon )?
+* Any special instructions for using the add-on correctly?
+
+== Spring Bridge
+`ds-spring-bridge-addon` is a two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible. You can obtain this add-on from https://github.com/os890/ds-spring-bridge-addon.
+
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
+* When would the user use this add-on?
+* Where can the user get the add-on from (https://github.com/os890/ds-spring-bridge-addon )?
+* Any special instructions for using the add-on correctly?
+
+== Disruptor
+This add-on creates a disruptor process for every observer method. It currently works with Apache TomEE and JBoss AS 7.
+
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the add-on (e.g., A two-way cdi-spring bridge that allows spring-beans to be injected into cdi-beans and vice versa provided the concepts, for example qualifiers, are compatible.)?
+* When would the user use this add-on?
+* Where can the user get the add-on from (https://github.com/os890/ds-disruptor-addon )?
+* Any special instructions for using the add-on correctly?
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/articles.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/articles.adoc b/documentation/src/main/asciidoc/articles.adoc
new file mode 100644
index 0000000..f16fdfa
--- /dev/null
+++ b/documentation/src/main/asciidoc/articles.adoc
@@ -0,0 +1,29 @@
+= Articles and Blogs
+
+: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:
+
+You can find lots of content related to DeltaSpike with a quick internet search. But here is a list of some useful articles and blogs to get you started.
+
+If you know of useful DeltaSpike articles or blogs that are not listed, link:https://deltaspike.apache.org/community.html[let us know].
+
+== Ongoing
+
+* https://twitter.com/DeltaSpikeTeam[@DeltaSpikeTeam on Twitter]
+* https://twitter.com/hashtag/deltaspike[#deltaspike on Twitter]
+* http://os890.blogspot.com.au/search/label/deltaspike[os890 DeltaSpike posts]
+* http://rafabene.com/?s=deltaspike&submit=Search[Rafael Benevides DeltaSpike posts]
+* http://rmannibucau.wordpress.com/?s=deltaspike[RManiiBucau DeltaSpike posts]
+* https://struberg.wordpress.com/?s=deltaspike[Struberg DeltaSpike posts]
+
+
+== One-offs
+
+* https://blogs.oracle.com/theaquarium/entry/introducing_deltaspike_1_0[The Aquarium: Introducing DeltaSpike 1.0]
+* http://blog.arungupta.me/2014/06/deltaspike-1-0-extend-javaee-techtip32/[DeltaSpike 1.0 – Extend #JavaEE beyond #JavaEE]
+* http://www.tearsofaunicorn.com/articles/2014/06/10/configuring-deltaspike-through-environment-variables.html[Configuring Apache Deltaspike through environment variables]
+* http://blog.ctp.com/2013/11/27/bye-bye-cdi-query-hello-deltaspike-data/[Bye Bye CDI Query, Hello DeltaSpike Data]
+* http://rmannibucau.wordpress.com/2013/11/20/deltaspike-data-repositories-with-dtos/[DeltaSpike Data: repositories with DTOs!]
+* http://jaxenter.com/introducing-apache-deltaspike-42925.html[Closing the Gaps: Introducing Apache Deltaspike]
+* http://jsfcorner.blogspot.com.au/2013/01/deltaspike-jsf-message-system.html[DeltaSpike JSF message system]
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/bean-validation.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/bean-validation.adoc b/documentation/src/main/asciidoc/bean-validation.adoc
index fe26187..298c832 100644
--- a/documentation/src/main/asciidoc/bean-validation.adoc
+++ b/documentation/src/main/asciidoc/bean-validation.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Introduction
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/build.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/build.adoc b/documentation/src/main/asciidoc/build.adoc
index 48fb04b..9ebca70 100644
--- a/documentation/src/main/asciidoc/build.adoc
+++ b/documentation/src/main/asciidoc/build.adoc
@@ -1,155 +1,130 @@
-= Building DeltaSpike from source
+= Build and Test DeltaSpike from Source
: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
-
-Deltaspike uses http://maven.apache.org/[maven] build tool to automate the compilation, testing and packaging of the project
-
-=== Full build
-
------------------
-mvn clean install
------------------
-
-=== Build with test
-
-
-------------------------------------------------------------------
-mvn clean install -POWB //execute the unit tests with OpenWebBeans
-or
-mvn clean install -PWeld //execute the unit tests with Weld
-------------------------------------------------------------------
-
-
-=== Integration Tests
-
-
-With the unpack Maven-Plugin all Arquillian-Tests get copied to the
-integration-test module. Together with the special integration-tests
-they get executed via a remote container. Currently we have
-configurations for the following containers.
-
-
-==== TomEE
-
-
-*Executing the Arquillian tests with Apache TomEE*
-
----------------------------------------
-mvn clean install -Ptomee-build-managed
----------------------------------------
-
-
-==== JBoss AS7
-
-
-===== Without existing AS7
-
-
-*Executing the Arquillian tests with JBoss AS7 (without AS7 installation)*
-
--------------------------------------------
-mvn clean install -Pjbossas-build-managed-7
--------------------------------------------
-
-===== With existing AS7
-
-
-Set JBoss_HOME
-
-*Executing the Arquillian tests with JBoss AS7 (AS7 installation
-required)*
-
--------------------------------------
-mvn clean install -Pjbossas-managed-7
--------------------------------------
-
-
-==== WildFly 8
-
-
-===== Without existing WF8
-
-
-*Executing the Arquillian tests with JBoss-WF8 (without WF8 installation)*
-
------------------------------------------
+:toc:
+
+The DeltaSpike source (modules and examples) is provided for inspection, contribution and testing purposes. The source must be built with Maven, which has been used to automate the compilation, testing and packaging processes. Arquillian tests are automatically conducted when DeltaSpike is built and CDI implementations or containers with which to carry out the tests can be specified.
+
+In all cases, to obtain the DeltaSpike source, link:https://deltaspike.apache.org/download.html[download `deltaspike-project-<version>-source-release.zip`] and extract the contents.
+
+**Note:** You can also obtain the DeltaSpike source from the project Git repository. The repository is subject to change and it can be used for contributing but should not be used in production environments. For more information, see <<source#,Get Source and compile it>>.
+
+== Build without CDI Implementation Tests
+DeltaSpike can be built without executing tests against a CDI implementation, with the following commands:
+
+[source,shell]
+----
+$ cd /path/to/deltaspike-project-<version>/
+$ mvn clean install
+----
+
+== Build and Test with a CDI Implementation
+Tests can be executed with both the JBoss Weld and Apache OpenWebBeans CDI implementations.
+
+[cols="1,2a", options="header"]
+.Build Tests
+|===
+|Container |Command to Execute Arquillian Tests
+
+|JBoss Weld
+|
+[source,shell]
+----
+$ mvn clean install -PWeld
+----
+
+|Apache OpenWebBeans
+|
+[source,shell]
+----
+$ mvn clean install -POWB
+----
+|===
+
+
+== Build and Test with CDI Containers
+Tests can be executed with JBoss Weld and Apache OpenWebBeans through Java EE 6+ application servers and containers. Configurations are currently provided as details in the table here.
+
+[cols="2,3a", options="header"]
+.Integration Tests
+|===
+|Container |Command to Execute Arquillian Tests
+
+|Apache TomEE
+|
+[source,shell]
+----
+$ mvn clean install -Ptomee-build-managed
+----
+
+|JBoss AS7 (without AS7 installation)
+|
+[source,shell]
+----
+$ mvn clean install -Pjbossas-build-managed-7
+----
+
+|JBoss AS7 (AS7 installation required)
+|Set `JBoss_HOME`
+
+[source,shell]
+----
+$ mvn clean install -Pjbossas-managed-7
+----
+
+|JBoss WildFly 8 (without WildFly 8 installation)
+|
+[source,shell]
+----
mvn clean install -Pwildfly-build-managed
------------------------------------------
-
-
-===== With existing WF8
-
-
-Set WILDFLY_HOME
-
-*Executing the Arquillian tests with JBoss-WF8 (WF8 installation
-required)*
-
------------------------------------
-mvn clean install -Pwildfly-managed
------------------------------------
-
-
-==== GlassFish 3.1
-
-
+----
-===== Without existing GF3
+|JBoss WildFly 8 (WildFly 8 installation required)
+|Set `WILDFLY_HOME`
-*Executing the Arquillian tests with GF3 (without GF3 installation)*
+[source,shell]
+----
+$ mvn clean install -Pwildfly-managed
+----
----------------------------------------------
+|Oracle GlassFish 3 (without GlassFish 3 installation)
+|
+[source,shell]
+----
mvn clean install -Pglassfish-build-managed-3
----------------------------------------------
+----
+|Oracle GlassFish 3.1 (GlassFish 3.1 installation required)
+|Install GlassFish (default setup without admin-password) and start
+GlassFish with `asadmin start-domain` and `asadmin start-database`.
-===== With existing GF3
+[source,shell]
+----
+$ mvn clean install -Pglassfish-remote-3.1
+----
-Install GlassFish (default setup without admin-password) and start
-GlassFish with asadmin start-domain *and* asadmin start-database
-
-*Executing the Arquillian tests with Oracle Glassfish 3.1+*
-
-----------------------------------------
-mvn clean install -Pglassfish-remote-3.1
-----------------------------------------
-
-
-==== GlassFish 4
-
-===== Without existing GF4
-
-*Executing the Arquillian tests with GF4 (without GF4 installation)*
-
----------------------------------------------
+|Oracle GlassFish 4 (without Oracle GlassFish 4 installation)
+|
+[source,shell]
+----
mvn clean install -Pglassfish-build-managed-4
----------------------------------------------
+----
-
-==== WebLogic 12c
-
-
-Install WebLogic 12c. Start Confiuration Wizard to create a new basic
+|Oracle WebLogic 12c
+|Install WebLogic 12c. Start Configuration Wizard to create a new basic
WebLogic Domain. Default options and domain name = base_domain,
administrator user name = weblogic1, administrator password = weblogic1.
-Set WLS_HOME so that %WLS_HOME%.jar exists. Start the domain.
-
-*Executing the Arquillian tests with Oracle WebLogic 12c*
-
-----------------------------------
-mvn clean install -Pwls-remote-12c
-----------------------------------
-
-
-=== Jenkins Builds
+Set `WLS_HOME` so that `%WLS_HOME%.jar` exists. Start the domain.
-https://builds.apache.org/view/A-D/view/DeltaSpike/
+[source,shell]
+----
+$ mvn clean install -Pwls-remote-12c
+----
+|===
-=== Sonar
+== Next
+* For analysis of the DeltaSpike source, see https://analysis.apache.org/dashboard/index/org.apache.deltaspike:deltaspike-project
+* For information about DeltaSpike automated Jenkins builds, see https://builds.apache.org/view/A-D/view/DeltaSpike/
-https://analysis.apache.org/dashboard/index/org.apache.deltaspike:deltaspike-project
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/cdiimp.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/cdiimp.adoc b/documentation/src/main/asciidoc/cdiimp.adoc
new file mode 100644
index 0000000..6d6acbd
--- /dev/null
+++ b/documentation/src/main/asciidoc/cdiimp.adoc
@@ -0,0 +1,196 @@
+= Enable CDI For Your Java Environment
+
+: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:
+
+DeltaSpike requires a CDI implementation to be available in the Java environment that your projects are deployed to. The implementation provides the CDI essentials, managing dependency injection and contextual lifecycles. link:http://weld.cdi-spec.org/[JBoss Weld] and link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)] are two widely used CDI implementations. Dependent on the Java environment you choose, some setup may be necessary as detailed here.
+
+== Java EE6+ Containers
+CDI is part of Java EE6 and later so CDI implementations are included as standard in Java EE6+ compliant environments. There is no additional CDI configuration needed besides including the CDI-obligatory `beans.xml` file in your project.
+
+JBoss Weld is integrated in Java EE application servers including WildFly, JBoss Enterprise Application Platform, GlassFish, and Oracle WebLogic.
+
+Apache OpenWebBeans (OWB) is integrated in Java EE containers including Apache TomEE, Apache Geronimo, IBM WebSphere Application Server, and SiwPas.
+
+== Java EE5 and Servlet Containers
+CDI implementations are not distributed with Java EE5 application servers or Servlet-only environments such as Apache TomCat and Eclipse Jetty. You can use CDI in these environments by embedding a standalone CDI implementation. Both JBoss Weld and Apache OpenWebBeans can be used for this task; for more information, see the corresponding CDI implementation documentation.
+
+== Java SE6+
+CDI is not part of Java SE but it can still be used. JBoss Weld and Apache OpenWebBeans implementations can be used to act as dependency injection bean managers but the respective containers must be booted manually.
+
+DeltaSpike provides a dedicated Container Control module to enable applications deployed in Java SE environments to boot a CDI container. The Container Control module consists of the API component and components specific to the JBoss Weld, Apache OpenWebBeans and Apache OpenEJB CDI containers. The DeltaSpike module provides a layer of abstraction from the specific CDI containers, enabling you to write container-independent code in your project.
+
+Instructions are provided here for adding the required resources to both Maven-based and Maven-independent projects and subsequently booting the CDI container from your project source code.
+
+=== Declare Dependencies for Maven-based Projects
+For Maven-based projects, the Container Control module is available in Maven Central together with the other DeltaSpike modules. You must configure your project to use the DeltaSpike Container Control API and one of the CDI container-specific modules.
+
+. Open the project `pom.xml` file for editing
+. Add the DeltaSpike Container Control API to the list of dependencies
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.cdictrl</groupId>
+ <artifactId>deltaspike-cdictrl-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+----
++
+. Add CDI container dependencies for one of the container options listed here
+
+==== Option A: For JBoss Weld
+
+. Open the project `pom.xml` file for editing
+. Add the JBoss Weld version to the list of properties, replacing the version as desired
++
+[source,xml]
+----
+<properties>
+ <weld.version>1.1.9.Final</weld.version>
+</properties>
+----
++
+. Add the JBoss Weld dependency to the list of dependencies
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.jboss.weld.se</groupId>
+ <artifactId>weld-se</artifactId>
+ <version>${weld.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
++
+. Add the DeltaSpike Weld-specific Container Control module to the list of dependencies
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.cdictrl</groupId>
+ <artifactId>deltaspike-cdictrl-weld</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
++
+. Save the `pom.xml` file changes
+. Download all required dependencies
++
+----
+mvn clean install
+----
+
+==== Option B: For Apache OpenWebBeans
+
+. Open the project `pom.xml` file for editing
+. Add the Apache OpenWebBeans version to the list of properties, replacing the version as desired
++
+[source,xml]
+----
+<properties>
+ <owb.version>1.2.0</owb.version>
+</properties>
+----
++
+. Add the Apache OpenWebBeans dependencies to the list of dependencies
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.openwebbeans</groupId>
+ <artifactId>openwebbeans-impl</artifactId>
+ <version>${owb.version}</version>
+ <scope>runtime</scope>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.openwebbeans</groupId>
+ <artifactId>openwebbeans-spi</artifactId>
+ <version>${owb.version}</version>
+ <scope>compile</scope>
+</dependency>
+----
++
+. Add the DeltaSpike Apache OpenWebBeans-specific Container Control module to the list of dependencies
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.cdictrl</groupId>
+ <artifactId>deltaspike-cdictrl-owb</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
++
+. Save the `pom.xml` file changes
+. Download all required dependencies
++
+----
+mvn clean install
+----
+
+=== Declare Dependencies for Maven-independent Projects
+For Maven-independent projects, the Container Control module is distributed together with the other DeltaSpike modules in `distribution-fill-<version>.zip`. You must add two of the files from the `cdictrl` directory to your project, namely `deltaspike-cdictrl-api.jar` and the .jar file that corresponds to the CDI container you have chosen. Add these files to the project `WEB-INF/lib` or `EAR/lib` directory for .war and .ear projects respectively.
+
+=== Start the CDI Container from Your Project
+To start a CDI container in your application, you must instantiate a `CdiContainer` object and call the `#boot` method. When `#boot` is called, the `CdiContainer` scans CDI-enabled
+archives for beans and CDI extensions. An example is given in the code snippet here. Before the application exits, `#shutdown` must be called to correctly destroy all beans.
+
+[source,java]
+----
+import org.apache.deltaspike.cdise.api.CdiContainer;
+import org.apache.deltaspike.cdise.api.CdiContainerLoader;
+
+public class MainApp {
+ public static void main(String[] args) {
+
+ CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
+ cdiContainer.boot();
+
+ // You can use CDI here
+
+ cdiContainer.shutdown();
+ }
+}
+----
+
+Starting the container does not automatically start all CDI Contexts. Contexts must be started independently using the provided `ContextControl` class. An example of starting the Context for `@ApplicationScoped` beans is added to the code snippet here.
+
+[source,java]
+----
+import org.apache.deltaspike.cdise.api.CdiContainer;
+import org.apache.deltaspike.cdise.api.CdiContainerLoader;
+import org.apache.deltaspike.cdise.api.ContextControl;
+import javax.enterprise.context.ApplicationScoped;
+
+public class MainApp {
+ public static void main(String[] args) {
+
+ CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
+ cdiContainer.boot();
+
+ // Starting the application-context allows to use @ApplicationScoped beans
+ ContextControl contextControl = cdiContainer.getContextControl();
+ contextControl.startContext(ApplicationScoped.class);
+
+ // You can use CDI here
+
+ cdiContainer.shutdown();
+ }
+}
+----
+
+To resolve project beans, you can use the DeltaSpike `BeanProvider` class. Whether `EchoService` is a concrete implementation or just an interface depends on the application. In the case that it is an interface, the corresponding implementation is resolved. The resolved bean is a standard CDI bean and it can be used for all CDI concepts, such as @Inject, in the class without further uses of `BeanProvider`. An example of resolving the bean without qualifiers is given in the code snippet here.
+
+[source,java]
+----
+EchoService echoService = BeanProvider.getContextualReference(EchoService.class, false);
+----
+
+== Next
+* For more information about the Container Control module, see <<container-control#,Container Control Module>>.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/configuration.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configuration.adoc b/documentation/src/main/asciidoc/configuration.adoc
index 7f3e114..2e2107b 100644
--- a/documentation/src/main/asciidoc/configuration.adoc
+++ b/documentation/src/main/asciidoc/configuration.adoc
@@ -2,8 +2,7 @@
: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]
+:toc:
== Configuration Basics
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/configure.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/configure.adoc b/documentation/src/main/asciidoc/configure.adoc
new file mode 100644
index 0000000..df99230
--- /dev/null
+++ b/documentation/src/main/asciidoc/configure.adoc
@@ -0,0 +1,85 @@
+= Configure DeltaSpike in Your Projects
+
+: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:
+
+DeltaSpike is available for use in Maven-based and Maven-independent projects. Instructions are given here for obtaining released final versions of DeltaSpike for both approaches.
+
+**Note:** You can also opt to use the lastest DeltaSpike snapshots; for more information, see <<snapshots#,Test Snapshots>>.
+
+== Configure DeltaSpike in Maven-based Projects
+DeltaSpike released versions are available from the Maven Central repository for use in Maven-based projects. This means that you do not need to modify your Maven configuration `settings.xml` file; when building projects, Maven automatically searches the online Maven Central repository for project dependencies and downloads sources to your local Maven repository.
+
+To begin use the DeltaSpike releases from Maven Central, you simply need to configure the project `pom.xml` file for each project with information about the release version and modules you want to use. At a minimum, you must add the DeltaSpike Core module, which provides the DeltaSpike API and utility classes.
+
+. Open the project `pom.xml` file for editing
+. Add the DeltaSpike version to the list of properties
++
+[source,xml]
+----
+<properties>
+ <deltaspike.version>1.0.2</deltaspike.version>
+</properties>
+----
++
+. Add the DeltaSpike Core module to the list of dependencies
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.deltaspike.core</groupId>
+ <artifactId>deltaspike-core-api</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>compile</scope>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.deltaspike.core</groupId>
+ <artifactId>deltaspike-core-impl</artifactId>
+ <version>${deltaspike.version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
++
+. Save the `pom.xml` file changes
+
+For instructions on adding the optional DeltaSpike modules, see the relevant module page:
+
+* <<bean-validation#,Bean Validation>>
+* <<container-control#,Container Control>>
+* <<data#,Data>>
+* <<jpa#,JPA>>
+* <<jsf#,JSF>>
+* <<partial-bean#,Partial-Bean>>
+* <<scheduler#,Scheduler>>
+* <<security#,Security>>
+* <<servlet#,Servlet>>
+* <<test-control#,Test-Control>>
+
+== Configure DeltaSpike in Maven-independent Projects
+Deltaspike is provided as a set of downloadable .jar files for projects not utilizing the Maven build system. Alternatively, you can build the DeltaSpike .jar files from source; for instructions, see <<build#,Build DeltaSpike from Source>>. In both cases, you must add the DeltaSpike .jar files directly to your projects.
+
+To use DeltaSpike without Maven from the downloadable .jar files, complete the following steps:
+
+. Download the latest `distribution-full-<version>.zip` from https://deltaspike.apache.org/download.html
+. Extract the archive contents
++
+[source,shell]
+----
+$ unzip distribution-full-<version>.zip
+----
++
+. Add the source to your project
+ .. For .war projects, copy the .jar files to `WEB-INF/lib` directory
+ .. For .ear projects, copy the .jar files to `EAR/lib directory` and add the following to `META-INF/application.xml`:
++
+[source,xml]
+----
+<library-directory>lib</library-directory>
+----
+
+== Next
+* To check whether your Java envrionment needs any additional CDI-specific configuration, see <<cdiimp#,Enable CDI For Your Java Environment>>.
+* To see ready-to-deploy example DeltaSpike applications, see <<examples#,See DeltaSpike in Action>>.
+* To understand how the various DeltaSpike modules can enhance and extend your applications, see the individual module pages.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/container-control.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/container-control.adoc b/documentation/src/main/asciidoc/container-control.adoc
index 0298553..0fdc767 100644
--- a/documentation/src/main/asciidoc/container-control.adoc
+++ b/documentation/src/main/asciidoc/container-control.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Introduction
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/core.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/core.adoc b/documentation/src/main/asciidoc/core.adoc
index 149dca6..e3d8270 100644
--- a/documentation/src/main/asciidoc/core.adoc
+++ b/documentation/src/main/asciidoc/core.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Core - API
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/data.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/data.adoc b/documentation/src/main/asciidoc/data.adoc
index 8be71d7..506bc10 100644
--- a/documentation/src/main/asciidoc/data.adoc
+++ b/documentation/src/main/asciidoc/data.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Introduction
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/examples.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/examples.adoc b/documentation/src/main/asciidoc/examples.adoc
new file mode 100644
index 0000000..2ba01eb
--- /dev/null
+++ b/documentation/src/main/asciidoc/examples.adoc
@@ -0,0 +1,53 @@
+= See DeltaSpike in Action
+
+: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:
+
+A collection of ready-to-build Maven-based projects are provided to demonstrate the inclusion of DeltaSpike in applications. Each example showcases a different DeltaSpike feature and explores the mechanics of DeltaSpike implementation. You can use these examples to see DeltaSpike in action and learn how to add these capabilities to your own projects. The Maven-based project examples are available in `deltaspike-project-<version>-source-release.zip` and each is briefly outlined here.
+
+To begin using the projects, complete the following steps:
+
+. link:https://deltaspike.apache.org/download.html[Download `deltaspike-project-<version>-source-release.zip`]
+. Extract the archive contents
++
+[source,shell]
+----
+$ unzip deltaspike-project-<version>-source-release.zip
+----
++
+. Build the projects
++
+[source,shell]
+----
+$ cd /path/to/deltaspike-project-<version>/examples
+$ mvn clean package
+----
+
+== jse-examples
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+
+== jsf-examples
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+
+== jsf-playground
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+
+== scheduler-playground
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the example (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this example (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/external.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/external.adoc b/documentation/src/main/asciidoc/external.adoc
new file mode 100644
index 0000000..8a2a1f8
--- /dev/null
+++ b/documentation/src/main/asciidoc/external.adoc
@@ -0,0 +1,63 @@
+= External Examples and Templates
+
+: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:
+
+A number of DeltaSpike examples and templates have been developed external to the DeltaSpike project. These extend the DeltaSpike resources from which you can see DeltaSpike in action. Brief information is given here about each of the examples and templates, with details of where they can be obtained from.
+
+== Example: Confess 2012 Workshop Demo
+This example was prepared for the Confess workshop and demonstrates how to use DeltaSpike instead of and side-by-side with MyFaces CODI. The secured web application demonstrates presenting users with differentiating content based on their account status.
+
+**Source code:** https://github.com/confess/confess2012_deltaspike
+
+== Example: Fullstack EE6+ with DeltaSpike
+Simple example based on Java EE6+ and DeltaSpike (tested with EE6 and EE7).
+
+**Source code:** https://github.com/os890/ee6-ds-demo
+
+== Example: Fullstack CODI to DeltaSpike
+This pair of examples show how to achieve the most important MyFaces CODI features with DeltaSpike and also how to migrate a CODI project to DeltaSpike. The examples are basic, compacting core CODI features into just a few JSF pages, and are intended for deployment with TomEE.
+
+**Source code:** https://github.com/os890/tomee_mf_stack_001
+
+* CODI version in master branch
+* Migrated DeltaSpike version in codi2ds branch
+
+== Examples: JBoss Web Framework Kit Quickstarts
+The JBoss quickstarts are small working examples that demonstrate recommended practices for specific Java EE technology use cases. A subset of these quickstarts are dedicated to demonstrating DeltaSpike, including custom authorization restrictions using annotations, constructing and modifying beans, extending the influence of CDI using BeanManager, and deactivating DeltaSpike features.
+
+**Source code:** https://github.com/jboss-developer/jboss-wfk-quickstarts
+
+== Template: Java SE + CDI + DS
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Where can the user get the template from (https://github.com/os890/javase-cdi-ds-project-template )?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+
+== Template: JSF + CDI + DS (Servlet-Container)
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Where can the user get the template from (https://github.com/os890/javaweb-cdi-ds-project-template )?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+
+== Template: EJB + CDI + DS (Module)
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Where can the user get the template from (https://github.com/os890/javaee_cdi_ejb_ds_project_template )?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+
+== Template: JSF + EJB + CDI + DS (EE-Server)
+**Replace this text!** Write 2-3 sentences in plain language making sure you answer every question:
+
+* What is the purpose of the template (e.g., This quickstart demonstrates the use of a partial bean to provide dynamic implementations of an interface, and how this might be used to provide a generic query service.)?
+* When would the user use this template (e.g., The PersonQueryService provides an example of the end user API that might be available from such a framework. Extensive code comments document the example implementation.)?
+* Where can the user get the template from (https://github.com/os890/javaee_jsf_cdi_ejb_ds_project_template )?
+* Any special instructions for how to build and deploy (e.g., It does not contain any user interface; the tests must be run to verify everything is working correctly.)?
+
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/index.adoc b/documentation/src/main/asciidoc/index.adoc
index 4d6505f..eec24a1 100644
--- a/documentation/src/main/asciidoc/index.adoc
+++ b/documentation/src/main/asciidoc/index.adoc
@@ -2,728 +2,29 @@
: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
-
-
-Apache DeltaSpike project has been created to support the development of
-portable CDI extensions that provide useful features for Java
-applications not provided out of the box by the CDI spec (Security, JPA,
-...). CDI extensions created by the DeltaSpike community are packaged as
-modules.
-
-Therefore, Apache DeltaSpike is a great toolbox for CDI. More than a set
-of powerful extension and tools to ease extension development,
-DeltaSpike also proves that CDI allows Java EE to evolve between each
-release.
-
-The goal of the project is also to provide useful classes to :
-
-* Boot CDI Container (Weld, OpenWebbeans, OpenEJB) for Java SE,
-* Stage a project,
-* Provide new scopes (Window Scope, ...),
-* Manage messages and configurations
-
-The project is currently tested on different CDI implementations like
-Apache OpenWebBeans and JBoss Weld, and also on different Java Web
-containers like Apache TomEE or JavaEE, JBoss AS7, Oracle GlassFish
-3.1+, Oracle WebLogic Server 12c.
-
-
-=== What is a portable CDI extension ?
-
-A portable CDI extension means that CDI itself can be extended. Such
-extensions can be used with any spec. compliant CDI implementation. From
-the user perspective, it means that you can simply drop in CDI extension
-jars into your runtime e.g. to integrate third-party APIs with CDI or to
-improve existing JavaEE-APIs.
-
-The CDI Portable extensions SPI (Service Provider Interface) allows to
-define additional beans, scopes, stereotypes, interceptors and
-decorators. The SPI of CDI is a powerful vehicle for innovation and
-DeltaSpike is an example of it.
-
-
-=== DeltaSpike in a nutshell
-
-
-==== Java EE 7 without Java EE 7!
-
-*Transactional support for non-EJB beans:* The Transactional Interceptor
-in DeltaSpike paved the way for @Transactional in Java EE 7.
-
-*Injectable Servlet objects:* Allows the developer to inject CDI beans
-on Servlets on Java EE 6/CDI 1.0 environments
-
-*Injectable resources:* Configuration, resource bundles,... are easy to
-inject when using CDI and Apache DeltaSpike.
-
-*@Exclude annotation:* it's possible to annotate beans which should be
-ignored by CDI even if they are in a CDI enabled archive on Java EE
-6/CDI 1.0 environment where you can't use @Vetoed or a veto based on
-project-stages or expressions is needed.
-
-**Scheduling tasks**: Async processes in a non Java EE 7 environment.
-
-*Bean Validation integration:* Allows to inject CDI beans and EJB in to
-Constraint-Validators.
-
-*BeanProvider:* Access the BeanManager and CDI beans even in non managed
-classes like JPA-2.0 EntityListeners or Spring Beans.
-
-
-==== JSF Improvements
-
-*Multi-window handling:* Allows to manage logical windows for
-batches,... or in case of JSF it offers proper separation of
-browser-tabs.
-
-*Type-safe view-config:* It allows to bind meta-data (e.g. for security)
-to views with a type-safe, but flexible approach. It provides a more
-solid navigation in case of JSF and helps a lot in the maintenance
-phase.
-
-*View-Controller:* Based on type-safe view-configs view-controller
-annotations provide a type-safe alternative to standard-tags.
-
-*Injection on Converters and Validators:* Allows to inject CDI beans and
-EJB in to JSF Converters and Validators.
-
-*JSF event broadcasting to CDI:* Allows CDI to be notified about JSF
-events
-
-
-==== Productivity Improvements
-
-*Security based on annotations:* The foundation for building a robust,
-capable and non invasive security solution.
-
-*New CDI scopes:* TransactionScoped, WindowScoped, ViewScoped,
-ViewAccess scope, Grouped conversion scope
-
-*Container Control & Test Control:* Java SE with CDI, all with a
-unifying API. Start, stop, add classes to a running CDI container.
-
-*Data Module:* An out of the box entity framework solution complete with
-support for container or application managed persistence contexts, as
-well as JDBC.
-
-*Decoupled Exception handling:* Allows to do exception handling in one
-location similar to CDI Observers.
-
-*JMX integration:* Any CDI bean can be exposed via JMX easily with one
-annotation.
-
-*Type-safe i18n messages:* Localized messages are easy to use with an
-interface and a resource bundle, no more boilerplate and your messages
-now have context within the code.
-
-*Type-safe Project-Stages:* Compared to project-stages in JSF,
-DeltaSpike provides a type-safe, but still extensible approach which can
-be used in CDI based applications.
-
-
-== Getting Started
-
-A DeltaSpike project can be designed using or not Apache Maven and
-consists in a collection of jar files. Depending on your needs, you will
-package DeltaSpike core jar (api and impl) files or extend the list with
-DeltaSpike modules. DeltaSpike Api and Impl are mandatory and provide
-code required to benefits of portable CDI extensions or useful features
-created.
-
-Remark : For Java SE, an additional step is required as you have to
-select the CDI implementation of your choice to boot a CDI container.
-
-[TODO] Add a section or remark to explain how to package & deploy
-DeltaSpike in an OSGI environment (Apache Felix, Apache Karaf, Apache
-ServiceMix)
-
-
-=== Project Configuration without Maven
-
-
-You can manually download all JARs described above or you get <<source.adoc#,the source-code>> and <<build.adoc#,build>> DeltaSpike
-manually.
-
-=== Project Configuration with Maven
-
-*Hint:* In the listings below replace the placeholders for the version with the version of your choice or use:
-
-[source,xml]
---------------------------------------------------
-<properties>
- <deltaspike.version>1.0.3</deltaspike.version>
-</properties>
---------------------------------------------------
-
-Or if you want to very bleeding edge, point to our current snapshot.
-
-[source,xml]
------------------------------------------------------------
-<properties>
- <deltaspike.version>1.0.4-SNAPSHOT</deltaspike.version>
-</properties>
------------------------------------------------------------
-
-==== Configuration of DeltaSpike Core
-
-[source,xml]
--------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.core</groupId>
- <artifactId>deltaspike-core-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.core</groupId>
- <artifactId>deltaspike-core-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
--------------------------------------------------
-
-==== Configuration of DeltaSpike Modules
-
-Security Module
-+++++++++++++++
-
-[source,xml]
-------------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-security-module-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-security-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
-------------------------------------------------------------
-
-===== JPA Module
-
-[source,xml]
--------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-jpa-module-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-jpa-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
--------------------------------------------------------
-
-===== JSF Module
-
-[source,xml]
--------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-jsf-module-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-jsf-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
--------------------------------------------------------
-
-Some EE6 servers can't handle optional classes. If you don't like the
-corresponding log entries during the startup or the deployment fails,
-you can use an alternative impl-module (instead of
-deltaspike-jsf-module-impl) since v1.0.1:
-
-[source,xml]
------------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-jsf-module-impl-ee6</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
------------------------------------------------------------
-
-===== Bean Validation Module
-
-[source,xml]
--------------------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-bean-validation-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
--------------------------------------------------------------------
-
-===== Servlet Module
-
-[source,xml]
------------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-servlet-module-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-servlet-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
------------------------------------------------------------
-
-===== Data Module
-
-[source,xml]
---------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-data-module-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-data-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
---------------------------------------------------------
-
-===== Test-Control Module
-
-[source,xml]
-----------------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-test-control-module-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>test</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-test-control-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>test</scope>
-</dependency>
-----------------------------------------------------------------
-
-===== Scheduler Module
-
-[source,xml]
--------------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-scheduler-module-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.modules</groupId>
- <artifactId>deltaspike-scheduler-module-impl</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
--------------------------------------------------------------
-
-==== With Java SE
-
-
-To use DeltaSpike with Java SE, we must provide additional jars file
-corresponding to the DeltaSpike CDI Controller API and its
-implementation. The Controller uses Java Services to resolve the CDI
-container
-(http://docs.jboss.org/weld/reference/1.1.5.Final/en-US/html/[JBoss
-Weld], http://openwebbeans.apache.org[Apache OpenWebbeans] (and
-http://openejb.apache.org[Apache OpenEJB])) and implementation contains
-the code to manage the link:#_container_control_optional[CDI container and contexts].
-
-*Hint:* In the listings below replace the placeholders for the version
-with the version of your choice or use:
-
-[source,xml]
---------------------------------------------------
-<properties>
- <deltaspike.version>1.0.0</deltaspike.version>
- <owb.version>1.2.0</owb.version>
- <weld.version>1.1.9.Final</weld.version>
-</properties>
---------------------------------------------------
-
-===== Add the DeltaSpike Container Ctrl API
-
-[source,xml]
-----------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.cdictrl</groupId>
- <artifactId>deltaspike-cdictrl-api</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
-----------------------------------------------------
-
-===== Add a CDI container + Container Ctrl Impl
-
-
-==== ... for Apache OpenWebBeans
-
-
-[source,xml]
-----------------------------------------------------
-<dependency>
- <groupId>org.apache.openwebbeans</groupId>
- <artifactId>openwebbeans-impl</artifactId>
- <version>${owb.version}</version>
- <scope>runtime</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.openwebbeans</groupId>
- <artifactId>openwebbeans-spi</artifactId>
- <version>${owb.version}</version>
- <scope>compile</scope>
-</dependency>
-
-<dependency>
- <groupId>org.apache.deltaspike.cdictrl</groupId>
- <artifactId>deltaspike-cdictrl-owb</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
-----------------------------------------------------
-
-==== ... for JBoss Weld (RI)
-
-
-[source,xml]
-----------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.cdictrl</groupId>
- <artifactId>deltaspike-cdictrl-weld</artifactId>
- <version>${deltaspike.version}</version>
- <scope>runtime</scope>
-</dependency>
-
-<dependency>
- <groupId>org.jboss.weld.se</groupId>
- <artifactId>weld-se-core</artifactId>
- <version>${weld.version}</version>
- <scope>runtime</scope>
-</dependency>
-----------------------------------------------------
-
-==== For Embedded Servlet Runtimes, you can add
-
-
-[source,xml]
--------------------------------------------------------
-<dependency>
- <groupId>org.apache.deltaspike.cdictrl</groupId>
- <artifactId>deltaspike-cdictrl-servlet</artifactId>
- <version>${deltaspike.version}</version>
- <scope>compile</scope>
-</dependency>
--------------------------------------------------------
-
-==== Testing Snapshots
-
-
-If you would like to test the latest Snapshot, you can <<build.adoc#,build>> DeltaSpike locally or you
-get it from the Apache Snapshot-Repository:
-
-[source,xml]
-----------------------------------------------------------
-<repositories>
- <repository>
- <id>apache-snapshot-repository</id>
- <url>http://repository.apache.org/snapshots/</url>
- <releases>
- <enabled>false</enabled>
- </releases>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </repository>
-</repositories>
-----------------------------------------------------------
-
-== Deployment mode
-
-DeltaSpike can be deployed in different Java environments. Depending
-which Java container and release you are using, the procedure which is
-different is explained here after.
-
-=== With Java EE6+
-
-If you are using DeltaSpike in a Java EE6 environment, you don't need to
-configure a CDI implementation explicitly because it's shipped with the
-container.
-
-=== With Java EE5 or Servlet Containers
-
-Java EE5 application servers as well as pure servlet containers like
-Apache Tomcat / Eclipse Jetty don't provide a CDI implementation
-out-of-the-box. So don't forget to setup the CDI implementation of your
-choice.
-
-=== Standard Java SE6+
-
-If you are only using a JDK and runs Java in a standalone or standard
-mode (Java SE), then DeltaSpike will allow you to boot a CDI
-implementation where you can use Dependency Injection with a Bean
-Manager. Such an example will be presented at the next section.
-
-== Start a CDI container using Java SE
-
-This code snippet show you how with a Java MainApplication a CDI
-container can be started (= boot) by DeltaSpike using Java SE and how
-you define a CDI scope and resolve beans injected.
-
-**Hint**: To bootstrap a CDI container in your Java application, you
-just need to instantiate the `CdiContainer` and call the `#boot` method.
-
-[source,java]
--------------------------------------------------------------------------
-import org.apache.deltaspike.cdise.api.CdiContainer;
-import org.apache.deltaspike.cdise.api.CdiContainerLoader;
-
-public class MainApp {
- public static void main(String[] args) {
-
- CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
- cdiContainer.boot();
-
- // You can use CDI here
-
- cdiContainer.shutdown();
- }
-}
--------------------------------------------------------------------------
-
-When `#boot` is called, the `CdiContainer` will scan CDI enabled
-archives for beans and CDI extensions.
-
-**Note**: Booting the container does not automatically start all CDI
-Contexts!
-
-Example for starting the application-context:
-
-[source,java]
-----------------------------------------------------------------------------------
-import org.apache.deltaspike.cdise.api.CdiContainer;
-import org.apache.deltaspike.cdise.api.CdiContainerLoader;
-import org.apache.deltaspike.cdise.api.ContextControl;
-import javax.enterprise.context.ApplicationScoped;
-
-public class MainApp {
- public static void main(String[] args) {
-
- CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
- cdiContainer.boot();
-
- // Starting the application-context allows to use @ApplicationScoped beans
- ContextControl contextControl = cdiContainer.getContextControl();
- contextControl.startContext(ApplicationScoped.class);
-
- // You can use CDI here
-
- cdiContainer.shutdown();
- }
-}
-----------------------------------------------------------------------------------
-
-To resolve a bean of this project, you can use the `BeanProvider`
-provided by DeltaSpike. The following example shows how to resolve the a
-bean without qualifiers. It depends on the application if `EchoService`
-is a concrete implementation or just an interface. In case of an
-interface the corresponding implementation will be resolved. The
-resolved bean is a normal CDI bean which means you can use all CDI
-concepts like `@Inject` in the class (and you don't need further usages
-of `BeanProvider`).
-
-[source,java]
-----------------------------------------------------------------------------------------
-EchoService echoService = BeanProvider.getContextualReference(EchoService.class, false);
-----------------------------------------------------------------------------------------
-
-Before the application exits, you have to call `#shutdown` to destroy
-beans,... in a well-ordered fashion.
-
-== Module Overview
-
-The core features of DeltaSpike project are packaged under the following
-different modules. Some of them are mandatory while others are optional.
-
-=== Core (required)
-
-Definition : Contain the API and util classes of DeltaSpike project
-
-++++++++++++++++
-<a class="btn" href="core.html">View details »</a>
-++++++++++++++++
-
-=== Security (optional)
-
-Definition : Intercept and check security
-
-++++++++++++++++
-<a class="btn" href="security.html">View details »</a>
-++++++++++++++++
-
-=== JPA (optional)
-
-
-Definition :
-
-++++++++++++++++
-<a class="btn" href="jpa.html">View details »</a>
-++++++++++++++++
-
-
-=== JSF (optional)
-
-Definition :
-
-++++++++++++++++
-<a class="btn" href="jsf.html">View details »</a>
-++++++++++++++++
-
-
-=== Container Control (optional)
-
-Definition :
-
-++++++++++++++++
-<a class="btn" href="container-control.html">View details »</a>
-++++++++++++++++
-
-
-=== Bean Validation (optional)
-
-Definition : A module for adding CDI support in Bean Validation.
-
-Features : Allows a developer to create CDI aware `ConstraintValidator`s
-that can use business objects (EJBs, ManagedBeans) to support validation
-needs.
-
-++++++++++++++++
-<a class="btn" href="bean-validation.html">View details »</a>
-++++++++++++++++
-
-
-=== Servlet (optional)
-
-Definition : The DeltaSpike Servlet module provides integration with the
-Java Servlet API.
-
-Features :
-
-* Injection of common servlet objects.
-* Propagation of servlet events to the CDI event bus.
-
-++++++++++++++++
-<a class="btn" href="servlet.html">View details »</a>
-++++++++++++++++
-
-
-=== Partial-Bean (optional)
-
-++++++++++++++++
-<a class="btn" href="partial-bean.html">View details »</a>
-++++++++++++++++
-
-
-=== Data (optional)
-
-Definition : The DeltaSpike Data module provides enhanced JPA experience
-with declarative queries, reducing boilerplate to a minimum.
-
-Features :
-
-* Derive queries by simple method names or by method annotations
-defining JPQL, named queries or plain SQL
-* Result pagination and sorting
-* Auditing of entities
-* A simplified alternative to the Criteria API
-* Mapping of entities from and to DTOs
-
-++++++++++++++++
-<a class="btn" href="data.html">View details »</a>
-++++++++++++++++
-
-
-=== Test-Control (optional)
-
-Definition : This module allows to write CDI based tests easily.
-
-++++++++++++++++
-<a class="btn" href="test-control.html">View details »</a>
-++++++++++++++++
-
-
-=== Scheduler (optional)
-
-Definition : This module provides a simple integration with Quartz v2
-(per default) or any other scheduler which supports cron-expressions for
-job-classes.
-
-++++++++++++++++
-<a class="btn" href="scheduler.html">View details »</a>
-++++++++++++++++
-
-
-== DeltaSpike SPI
-
-DeltaSpike Service Provider Interface (SPI)
-
-++++++++++++++++
-<a class="btn" href="spi.html">View details »</a>
-++++++++++++++++
-
-
-== External
-
-=== Blogs
-
-* http://os890.blogspot.com/search/label/deltaspike
-
-
-=== Add-ons
-
-* https://github.com/os890/ds-monitoring-addon[Monitoring- and Auditing]
-* https://github.com/os890/ds-spring-bridge-addon[CDI/Spring Bridge]
-* https://github.com/os890/ds-disruptor-addon[Fast events via Disruptor]
-
-=== Project Templates
-
-* https://github.com/os890/javase-cdi-ds-project-template[Java SE + CDI + DS]
-* https://github.com/os890/javaweb-cdi-ds-project-template[JSF + CDI + DS (Servlet-Container)]
-* https://github.com/os890/javaee_cdi_ejb_ds_project_template[EJB + CDI + DS (Module)]
-* https://github.com/os890/javaee_jsf_cdi_ejb_ds_project_template[JSF + EJB + CDI + DS (EE-Server)]
-
-=== Examples
-
-See link:../examples.html#External[External Examples]
+* Getting Started
+** <<overview#,Overview of DeltaSpike>>
+** <<configure#,Configure DeltaSpike in Your Projects>>
+** <<cdiimp#,Enable CDI For Your Java Environment>>
+** <<examples#,See DeltaSpike in Action>>
+* Using Individual Modules
+** <<core#,Core>>
+** <<bean-validation#,Bean Validation>>
+** <<container-control#,Container Control>>
+** <<data#,Data>>
+** <<jpa#,JPA>>
+** <<jsf#,JSF>>
+** <<partial-bean#,Partial-Bean>>
+** <<scheduler#,Scheduler>>
+** <<security#,Security>>
+** <<servlet#,Servlet>>
+** <<test-control#,Test-Control>>
+* Advanced Information
+** <<build#,Build DeltaSpike from Source>>
+** <<snapshots#,Use DeltaSpike Snapshots>>
+** link:https://deltaspike.apache.org/migration-guide.html[Migrate to DeltaSpike]
+** <<spi#,DeltaSpike Service Provider Interface (SPI)>>
+* More Resources
+** <<articles#,Articles and Blogs>>
+** <<addons#,Add-ons>>
+** <<external#,External Examples>>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/jpa.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jpa.adoc b/documentation/src/main/asciidoc/jpa.adoc
index 76eccad..8143a67 100644
--- a/documentation/src/main/asciidoc/jpa.adoc
+++ b/documentation/src/main/asciidoc/jpa.adoc
@@ -2,8 +2,7 @@
: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]
-
+:toc:
== @Transactional
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/jsf.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/jsf.adoc b/documentation/src/main/asciidoc/jsf.adoc
index e4044ac..e261a9b 100644
--- a/documentation/src/main/asciidoc/jsf.adoc
+++ b/documentation/src/main/asciidoc/jsf.adoc
@@ -2,8 +2,7 @@
: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]
-
+:toc:
== Multi-Window Handling
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/overview.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/overview.adoc b/documentation/src/main/asciidoc/overview.adoc
new file mode 100644
index 0000000..09163b6
--- /dev/null
+++ b/documentation/src/main/asciidoc/overview.adoc
@@ -0,0 +1,71 @@
+= Overview of DeltaSpike
+
+: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:
+
+== Background: Portable CDI Extensions
+Contexts and Dependency Injection (CDI) for Java EE (link:https://jcp.org/en/jsr/detail?id=299[JSR 299]) was introduced as part of Java EE6. It defines a collection of Java services that provides the foundation for frameworks, extensions, and integration with other technologies.
+
+Portable CDI extensions extend CDI implementations and improve existing Java EE APIs by enabling integration of different technologies. They can be used with any spec-compliant CDI implementation, such as JBoss Weld or Apache OpenWebBeans. The CDI container manages start and stop procedures, web beans, lifecycles, and injections. This means portable CDI extension injections can be handled by the container instead of the user.
+
+== About DeltaSpike
+DeltaSpike is a collection of portable CDI extensions. These ready-to-use modules are created by the community and provide a method of integrating tested API extensions into your Java projects.
+
+DeltaSpike consists of a core module and a number of optional modules for providing additional enterprise functionality to your applications. The modules include features for enhanced security with type-safe control over method invocations, integration with schedulers, injection of CDI objects into validators, and a transactional context and scope. DeltaSpike also provides boot and shutdown control over CDI containers in Java SE applications.
+
+As portable CDI extensions, DeltaSpike requires a CDI implementation and supports both JBoss Weld and Apache OpenWebBeans. DeltaSpike has also been tested on a range of application servers and containers that provide these CDI implementations, such as Apache TomEE, JBoss AS, WildFly, Oracle GlassFish, and Jetty.
+
+In addition to the portable CDI extension modules, DeltaSpike provides a number of examples to assist you in understanding how to use and get the most from this technology.
+
+== Features of DeltaSpike
+
+=== Java EE 7 without Java EE 7!
+
+*Transactional support for non-EJB beans:* The Transactional Interceptor in DeltaSpike paved the way for @Transactional in Java EE 7.
+
+*Injectable Servlet objects:* Allows the developer to inject CDI beans on Servlets on Java EE 6/CDI 1.0 environments
+
+*Injectable resources:* Configuration, resource bundles,... are easy to inject when using CDI and Apache DeltaSpike.
+
+*@Exclude annotation:* it's possible to annotate beans which should be ignored by CDI even if they are in a CDI enabled archive on Java EE 6/CDI 1.0 environment where you can't use @Vetoed or a veto based on project-stages or expressions is needed.
+
+**Scheduling tasks**: Async processes in a non Java EE 7 environment.
+
+*Bean Validation integration:* Allows to inject CDI beans and EJB in to Constraint-Validators.
+
+*BeanProvider:* Access the BeanManager and CDI beans even in non managed classes like JPA-2.0 EntityListeners or Spring Beans.
+
+
+=== JSF Improvements
+
+*Multi-window handling:* Allows to manage logical windows for batches,... or in case of JSF it offers proper separation of browser-tabs.
+
+*Type-safe view-config:* It allows to bind meta-data (e.g. for security) to views with a type-safe, but flexible approach. It provides a more solid navigation in case of JSF and helps a lot in the maintenance phase.
+
+*View-Controller:* Based on type-safe view-configs view-controller annotations provide a type-safe alternative to standard-tags.
+
+*Injection on Converters and Validators:* Allows to inject CDI beans and EJB in to JSF Converters and Validators.
+
+*JSF event broadcasting to CDI:* Allows CDI to be notified about JSF events
+
+=== Productivity Improvements
+
+*Security based on annotations:* The foundation for building a robust, capable and non invasive security solution.
+
+*New CDI scopes:* TransactionScoped, WindowScoped, ViewScoped, ViewAccess scope, Grouped conversion scope
+
+*Container Control & Test Control:* Java SE with CDI, all with a unifying API. Start, stop, add classes to a running CDI container.
+
+*Data Module:* An out of the box entity framework solution complete with support for container or application managed persistence contexts, as well as JDBC.
+
+*Decoupled Exception handling:* Allows to do exception handling in one location similar to CDI Observers.
+
+*JMX integration:* Any CDI bean can be exposed via JMX easily with one annotation.
+
+*Type-safe i18n messages:* Localized messages are easy to use with an interface and a resource bundle, no more boilerplate and your messages now have context within the code.
+
+*Type-safe Project-Stages:* Compared to project-stages in JSF, DeltaSpike provides a type-safe, but still extensible approach which can be used in CDI based applications.
+
+== Next
+For instructions on how to start using DeltaSpike, see <<configure#,Configure DeltaSpike in Your Projects>>.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/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 e15b270..e89ab00 100644
--- a/documentation/src/main/asciidoc/partial-bean.adoc
+++ b/documentation/src/main/asciidoc/partial-bean.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Usage
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/projectstage.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/projectstage.adoc b/documentation/src/main/asciidoc/projectstage.adoc
index 8419c77..224521c 100644
--- a/documentation/src/main/asciidoc/projectstage.adoc
+++ b/documentation/src/main/asciidoc/projectstage.adoc
@@ -2,9 +2,7 @@
: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]
-
+:toc:
== Introduction
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/scheduler.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/scheduler.adoc b/documentation/src/main/asciidoc/scheduler.adoc
index 586357b..bf097e3 100644
--- a/documentation/src/main/asciidoc/scheduler.adoc
+++ b/documentation/src/main/asciidoc/scheduler.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Intro
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/security.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/security.adoc b/documentation/src/main/asciidoc/security.adoc
index 200b7c6..db96701 100644
--- a/documentation/src/main/asciidoc/security.adoc
+++ b/documentation/src/main/asciidoc/security.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Hint
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/548383b7/documentation/src/main/asciidoc/servlet.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/servlet.adoc b/documentation/src/main/asciidoc/servlet.adoc
index 7fe2d76..61e530f 100644
--- a/documentation/src/main/asciidoc/servlet.adoc
+++ b/documentation/src/main/asciidoc/servlet.adoc
@@ -2,7 +2,7 @@
: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]
+:toc:
== Configuration