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:45 UTC
[3/9] deltaspike git commit: DELTASPIKE-690: module adoc pages edited
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.
-______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________