deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rafab...@apache.org
Subject [3/4] DELTASPIKE-716 - Migration from Markdown to Asciidoc
Date Tue, 16 Sep 2014 19:52:33 GMT
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/data.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/data.adoc b/documentation/src/main/asciidoc/data.adoc
new file mode 100644
index 0000000..022322c
--- /dev/null
+++ b/documentation/src/main/asciidoc/data.adoc
@@ -0,0 +1,1390 @@
+= Data 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
+
+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
+scenarios of the data module:
+
+[source,java]
+----------------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    List<Person> findByAgeBetweenAndGender(int minAge, int maxAge, Gender gender);
+
+    @Query("select p from Person p where p.ssn = ?1")
+    Person findBySSN(String ssn);
+
+    @Query(named=Person.BY_FULL_NAME)
+    Person findByFullName(String firstName, String lastName);
+
+}
+----------------------------------------------------------------------------------
+
+As you see in the sample, there are several usage scenarios outlined
+here:
+
+* Declare a method which executes a query by simply translating its name
+and parameters into a query.
+* Declare a method which automatically executes a given JPQL query
+string with parameters.
+* Declare a method which automatically executes a named query with
+parameters.
+
+The implementation of the method is done automatically by the CDI
+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.
+
+
+== 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
+
+
+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:
+
+[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:*
+
+______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
+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.
+______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
+
+Including the API at compile time and only include the implementation at
+runtime protects you from inadvertantly depending on an implementation
+class.
+
+
+=== Setup your application
+
+DeltaSpike Data requires an `EntityManager` exposed via a CDI producer -
+which is common practice in Java EE 6 applications.
+
+[source,java]
+------------------------------------------------------
+public class EntityManagerProducer
+{
+
+    @PersistenceUnit
+    private EntityManagerFactory emf;
+
+    @Produces // you can also make this @RequestScoped
+    public EntityManager create()
+    {
+        return emf.createEntityManager();
+    }
+
+    public void close(@Disposes EntityManager em)
+    {
+        if (em.isOpen())
+        {
+            em.close();
+        }
+    }
+
+}
+------------------------------------------------------
+
+This allows the `EntityManager` to be injected over CDI instead of only
+being used with a `@PersistenceContext` annotation. Using multiple
+`EntityManager` is explored in more detail in a following section.
+
+If you use a JTA DataSource with your `EntityManager`, you also have to
+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!
+
+
+== 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
+features). All that is required is to mark the type as such with a
+simple annotation:
+
+[source,java]
+----------------------------------------
+@Repository(forEntity = Person.class)
+public abstract class PersonRepository {
+    ...
+}
+
+@Repository(forEntity = Person.class)
+public interface PersonRepository {
+    ...
+}    
+----------------------------------------
+
+The `@Repository` annotation tells the extension that this is a
+repository for the `Person` entity. Any method defined on the repository
+will be processed by the framework. The annotation does not require to
+set the entity class (we'll see later why) but if there are just plain
+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
+
+Although mainly intended to hold complex query logic, working with both
+a repository and an `EntityManager` in the service layer might
+unnecessarily clutter code. In order to avoid this for the most common
+cases, DeltaSpike Data provides base types which can be used to replace
+the entity manager.
+
+The top base type is the `EntityRepository` interface, providing common
+methods used with an `EntityManager`. The following code shows the most
+important methods of the interface:
+
+[source,java]
+-------------------------------------------------------------------------
+public interface EntityRepository<E, PK extends Serializable>
+{
+
+    E save(E entity);
+
+    void remove(E entity);
+
+    void refresh(E entity);
+
+    void flush();
+
+    E findBy(PK primaryKey);
+
+    List<E> findAll();
+
+    List<E> findBy(E example, SingularAttribute<E, ?>... attributes);
+
+    List<E> findByLike(E example, SingularAttribute<E, ?>... attributes);
+
+    Long count();
+
+    Long count(E example, SingularAttribute<E, ?>... attributes);
+
+    Long countLike(E example, SingularAttribute<E, ?>... attributes);
+
+} 
+-------------------------------------------------------------------------
+
+The concrete repository can then extend this basic interface. For our
+Person repository, this might look like the following:
+
+[source,java]
+------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    Person findBySsn(String ssn);
+
+} 
+------------------------------------------------------------------------
+
+*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
+
+
+This class is an implementation of the `EntityRepository` interface and
+provides additional functionality when custom query logic needs also to
+be implemented in the repository.
+
+[source,java]
+-------------------------------------------------------------------------------------
+public abstract class PersonRepository extends AbstractEntityRepository<Person, Long>
+{
+
+    public Person findBySSN(String ssn)
+    {
+        return typedQuery("select p from Person p where p.ssn = ?1")
+                .setParameter(1, ssn)
+                .getResultList();
+    }
+
+}
+-------------------------------------------------------------------------------------
+
+
+=== Using Multiple `EntityManager`
+
+While most applications will run just fine with a single
+`EntityManager`, there might be setups where multiple data sources are
+used. This can be configured with the `EntityManagerConfig` annotation:
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------
+@Repository
+@EntityManagerConfig(entityManagerResolver = CrmEntityManagerResolver.class, flushMode = FlushModeType.COMMIT)
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+    ...
+}
+
+public class CrmEntityManagerResolver implements EntityManagerResolver
+{
+    @Inject @CustomerData // Qualifier - assumes a producer is around...
+    private EntityManager em;
+
+    @Override
+    public EntityManager resolveEntityManager()
+    {
+        return em;
+    }
+}
+--------------------------------------------------------------------------------------------------------------
+
+Again, note that annotations on interfaces do not inherit, so it's not
+possible to create something like a base `CrmRepository` interface with
+the `@EntityManagerConfig` and then extending / implementing this
+interface.
+
+=== 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`
+interface for repositories, which offers most other methods available in
+a JPA 2.0 `EntityManager`:
+
+[source,java]
+-------------------------------------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>, EntityManagerDelegate<Person>
+{
+    ...
+}
+-------------------------------------------------------------------------------------------------------
+
+== 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
+
+Let's start by looking at a (simplified for readability) example:
+
+[source,java]
+------------------------------------------------------------------------
+@Entity
+public class Person
+{
+
+    @Id @GeneratedValue
+    private Long id;
+    private String name;
+    private Integer age;
+    private Gender gender;
+
+}
+
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    List<Person> findByNameLikeAndAgeBetweenAndGender(String name, 
+                              int minAge, int maxAge, Gender gender);
+
+}
+------------------------------------------------------------------------
+
+Looking at the method name, this can easily be read as query all Persons
+which have a name like the given name parameter, their age is between a
+min and a max age and having a specific gender. The DeltaSpike Data
+module can translate method names following a given format and directly
+generate the query implementation out of it (in EBNF-like form):
+
+----------------------------------------------------------------------------------
+(Entity|List<Entity>) findBy(Property[Comparator]){Operator Property [Comparator]}
+----------------------------------------------------------------------------------
+
+Or in more concrete words:
+
+* The query method must either return an entity or a list of entities.
+* It must start with the `findBy` keyword (or related `findOptionalBy`, `findAnyBy`).
+* Followed by a property of the Repository entity and an optional comparator (we'll define this later). The property will be used in the query together with the comparator. Note that the number of arguments passed to the method depend on the comparator.
+* You can add more blocks of property-comparator which have to be concatenated by a boolean operator. This is either an `And` or `Or`.
+
+Other assumptions taken by the expression evaluator:
+
+* The property name starts lower cased while the property in the expression has an upper cases first character.
+
+Following comparators are currently supported to be used in method
+expressions:
+
+[options="header, autowidth"]
+|===
+| Name              |# of Arguments     |Description
+| Equal             |1 | Property must be equal to argument value. If the operator is omitted in the expression, this is assumed as default.
+| NotEqual          |1 | Property must be not equal to argument value.
+| Like              |1 | Property must be like the argument value. Use the %-wildcard in the argument.
+| GreaterThan       |1 | Property must be greater than argument value.
+| GreaterThanEquals |1 | Property must be greater than or equal to argument value.
+| LessThan          |1 | Property must be less than argument value.
+| LessThanEquals    |1 | Property must be less than or equal to argument value.
+| Between           |2 | Property must be between the two argument values.
+| IsNull            |0 | Property must be null.
+| IsNotNull         |0 | Property must be non-null.
+|===
+
+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
+
+Beside comparators it's also possible to sort queries by using the
+`OrderBy` keyword, followed by the attribute name and the direction
+(`Asc` or `Desc`).
+
+[source,java]
+------------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    List<Person> findByLastNameLikeOrderByAgeAscLastNameDesc(String lastName);
+
+} 
+------------------------------------------------------------------------------
+
+=== Nested Properties
+
+To create a comparison on a nested property, the traversal parts can be
+separated by a `_`:
+
+[source,java]
+------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    List<Person> findByCompany_companyName(String companyName);
+
+}
+------------------------------------------------------------------------
+
+=== Query Options
+
+
+DeltaSpike supports query options on method expressions. If you want to
+page a query, you can change the first result as well as the maximum
+number of results returned:
+
+[source,java]
+-----------------------------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    List<Person> findByNameLike(String name, @FirstResult int start, @MaxResults int pageSize);
+
+}
+-----------------------------------------------------------------------------------------------
+
+=== Method Prefix
+
+In case the `findBy` prefix does not comply with your team conventions,
+this can be adapted:
+
+[source,java]
+--------------------------------------------------------------------------------------------------
+@Repository(methodPrefix = "fetchWith")
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    List<Person> fetchWithNameLike(String name, @FirstResult int start, @MaxResults int pageSize);
+
+}
+--------------------------------------------------------------------------------------------------
+
+== Query Annotations
+
+While method expressions are fine for simple queries, they will often
+reach their limit once things get slightly more complex. Another aspect
+is the way you want to use JPA: The recommended approach using JPA for
+best performance is over named queries. To help incorporate those use
+cases, the DeltaSpike Data module supports also annotating methods for
+more control on the generated query.
+
+
+=== 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
+looks like the following sample:
+
+[source,java]
+------------------------------------------------------------------------
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    @Query("select count(p) from Person p where p.age > ?1")
+    Long countAllOlderThan(int minAge);
+
+}
+------------------------------------------------------------------------
+
+The parameter binding in the query corresponds to the argument index in
+the method.
+
+You can also refer to a named query which is constructed and executed
+automatically. The `@Query` annotation has a named attribute which
+corresponds to the query name:
+
+[source,java]
+--------------------------------------------------------------------------------------------
+@Entity
+@NamedQueries({
+    @NamedQuery(name = Person.BY_MIN_AGE,
+                query = "select count(p) from Person p where p.age > ?1 order by p.age asc")
+})
+public class Person
+{
+
+    public static final String BY_MIN_AGE = "person.byMinAge";
+    ...
+
+}
+
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    @Query(named = Person.BY_MIN_AGE)
+    Long countAllOlderThan(int minAge);
+
+}
+--------------------------------------------------------------------------------------------
+
+Same as before, the parameter binding corresponds to the argument index
+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
+annotation is needed.
+_________________________________________________________________________________________
+
+[source,java]
+---------------------------------------------------------------------------------------------
+@NamedQuery(name = Person.BY_MIN_AGE,
+            query = "select count(p) from Person p where p.age > :minAge order by p.age asc")
+        
+...
+
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    @Query(named = Person.BY_MIN_AGE)
+    Long countAllOlderThan(@QueryParam("minAge") int minAge);
+
+}
+---------------------------------------------------------------------------------------------
+
+It is also possible to set a native SQL query in the annotation. The
+`@Query` annotation has a native attribute which flags that the query is
+not JPQL but plain SQL:
+
+[source,java]
+------------------------------------------------------------------------------------
+@Entity
+@Table(name = "PERSON_TABLE")
+public class Person
+{
+    ...
+}
+
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    @Query(value = "SELECT * FROM PERSON_TABLE p WHERE p.AGE > ?1", isNative = true)
+    List<Person> findAllOlderThan(int minAge);
+
+}
+------------------------------------------------------------------------------------
+
+=== Annotation Options
+
+Beside providing a query string or reference, the `@Query` annotation
+provides also two more attributes:
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    @Query(named = Person.BY_MIN_AGE, max = 10, lock = LockModeType.PESSIMISTIC_WRITE)
+    List<Person> findAllForUpdate(int minAge);
+
+}
+--------------------------------------------------------------------------------------
+
+[options="header, autowidth"]
+|===
+| Name | Description
+| max  | Limits the number of results. 
+| lock | Use a specific LockModeType to execute the query.
+|===
+
+Note that these options can also be applied to method expressions.
+
+=== 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
+example, sorting criteria could come from a user selection so they
+cannot be known beforehand. DeltaSpike allows you to apply query options
+at runtime by using the `QueryResult` result type:
+
+[source,java]
+------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    @Query("select p from Person p where p.age between ?1 and ?2")
+    QueryResult<Person> findAllByAge(int minAge, int maxAge);
+
+}
+------------------------------------------------------------------------
+
+Once you have obtained a `QueryResult`, you can apply further options to
+the query:
+
+[source,java]
+-----------------------------------------------------------
+List<Person> result = personRepository.findAllByAge(18, 65)
+    .sortAsc(Person_.lastName)
+    .sortDesc(Person_.age)
+    .lockMode(LockModeType.WRITE)
+    .hint("org.hibernate.timeout", Integer.valueOf(10))
+    .getResultList(); 
+-----------------------------------------------------------
+
+*CAUTION:*
+________________________________________________________________________________________________________________________________________________________________________________________________
+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
+
+
+We introduced the `QueryResult` type in the last chapter, which can also
+be used for pagination:
+
+[source,java]
+-----------------------------------------------------------
+// Query API style
+QueryResult<Person> paged = personRepository.findByAge(age)
+    .maxResults(10)
+    .firstResult(50);
+
+// or paging style
+QueryResult<Person> paged = personRepository.findByAge(age)
+    .withPageSize(10) // equivalent to maxResults
+    .toPage(5);
+
+int totalPages = paged.countPages();
+-----------------------------------------------------------
+
+
+=== 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
+scenario for repositories. DeltaSpike supports this with a special
+marking annotation `@Modifying`:
+
+[source,java]
+------------------------------------------------------------------------------
+@Repository
+public interface PersonRepository extends EntityRepository<Person, Long>
+{
+
+    @Modifying
+    @Query("update Person as p set p.classifier = ?1 where p.classifier = ?2")
+    int updateClassifier(Classifier current, Classifier next);
+
+}
+------------------------------------------------------------------------------
+
+Bulk operation query methods can either return void or int, which counts
+the number of entities affected by the bulk operation.
+
+=== Optional Query Results
+
+The JPA spec requires to throw exceptions in case the
+`getSingleResult()` method does either return no or more than one
+result. This can result in tedious handling with try-catch blocks or
+have potential impact on your transaction (as the `RuntimeException`
+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.
+
+=== 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
+method expressions, `Query` annotations and `QueryResult<E>` calls.
+
+[source,java]
+----------------------------------------------------------------------------
+@Repository(forEntity = Person.class)
+public interface PersonRepository
+{
+
+    Person findOptionalBySsn(String ssn);
+
+    @Query(named = Person.BY_NAME, singleResult = SingleResultType.OPTIONAL)
+    Person findByName(String firstName, String lastName);
+
+}
+----------------------------------------------------------------------------
+
+For method expressions, the `findOptionalBy` prefix can be used. For
+`@Query` annotations, the `singleResult` attribute can be overridden
+with the `SingleResultType.OPTIONAL` enum.
+
+In case the query returns more than one result, a
+`NonUniqueResultException` is still thrown.
+
+=== Any Result
+
+If the caller does not really mind what kind if result is returned, it's
+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
+first result out of the result list.
+
+[source,java]
+-----------------------------------------------------------------------
+@Repository(forEntity = Person.class)
+public interface PersonRepository
+{
+
+    Person findAnyByLastName(String lastName);
+
+    @Query(named = Person.BY_NAME, singleResult = SingleResultType.ANY)
+    Person findByName(String firstName, String lastName);
+
+}
+-----------------------------------------------------------------------
+
+For method expressions, the `findAnyBy` prefix can be used. For `@Query`
+annotations, the `singleResult` attribute can be overridden with the
+`SingleResultType.ANY` enum.
+
+This option will not throw an exception.
+
+== Transactions
+
+
+If you call any method expression, `@Query`-annotated method or a method
+from the `EntityRepository`, the repository will figure out if a
+transaction is needed or not, and if so, if there is already one
+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
+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
+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
+`@Transactional` and might look like the following sample.
+
+[source,java]
+---------------------------------------------------------------------------------------
+public class TxExtension<E> implements TxRepository // this is your extension interface
+{
+    @Inject
+    private EntityManager em;
+
+    @Override @Transactional
+    public List<E> transactional(ListResultCallback callback)
+    {
+        return callback.execute();
+    }
+
+}
+---------------------------------------------------------------------------------------
+
+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
+
+
+=== Query Delegates
+
+
+While repositories defines several base interfaces, there might still be
+the odd convenience method that is missing. This is actually intentional
+- things should not get overloaded for each and every use case. That's
+why in DeltaSpike you can define your own reusable methods.
+
+For example, you might want to use the QueryDsl library in your
+repositories:
+
+[source,java]
+---------------------------------------------------------
+import com.mysema.query.jpa.impl.JPAQuery;
+
+public interface QueryDslSupport
+{
+    JPAQuery jpaQuery();
+}
+
+@Repository(forEntity = Person.class)
+public interface PersonRepository extends QueryDslSupport
+{
+   ...
+}   
+---------------------------------------------------------
+
+=== Implementing the Query Delegate
+
+The first step is to define an interface which contains the extra
+methods for your repositories (as shown above):
+
+[source,java]
+--------------------------------
+public interface QueryDslSupport
+{
+    JPAQuery jpaQuery();
+}
+--------------------------------
+
+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
+marker interface):
+
+[source,java]
+--------------------------------------------------------------------------------------------
+public class QueryDslRepositoryExtension<E> implements QueryDslSupport, DelegateQueryHandler
+{
+
+    @Inject
+    private QueryInvocationContext context;
+
+    @Override
+    public JPAQuery jpaQuery()
+    {
+        return new JPAQuery(context.getEntityManager());
+    }
+
+}
+--------------------------------------------------------------------------------------------
+
+As you see in the sample, you can inject a `QueryInvocationContext`
+which contains utility methods like accessing the current
+`EntityManager` and entity class.
+
+Note that, if you define multiple extensions with equivalent method
+signatures, there is no specific order in which the implementation is
+selected.
+
+== 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
+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.
+
+DeltaSpike Data allows to directly plugin in such a mapping mechanism
+without the need to specify additional mapping methods:
+
+[source,java]
+----------------------------------------------------
+@Repository(forEntity = Person.class)
+@MappingConfig(PersonDtoMapper.class)
+public interface PersonRepository
+{
+
+    PersonDto findBySsn(String ssn);
+
+    List<PersonDto> findByLastName(String lastName);
+
+}
+----------------------------------------------------
+
+The `PersonDtoMapper` class has to implement the `QueryInOutMapper`
+interface:
+
+[source,java]
+---------------------------------------------------------------------------------
+public class PersonDtoMapper implements QueryInOutMapper<Person>
+{
+
+    @Override
+    public Object mapResult(Person result)
+    {
+        ... // converts Person into a PersonDto
+    }
+    ...
+
+    @Override
+    public Object mapResultList(List<Simple> result)
+    {
+        ... // result lists can also be mapped into something different
+            // than a collection.
+    }
+
+    @Override
+    public boolean mapsParameter(Object parameter)
+    {
+        return parameter != null && (
+                parameter instanceof PersonDto || parameter instanceof PersonId);
+    }
+
+    @Override
+    public Object mapParameter(Object parameter)
+    {
+        ... // converts query parameters if required
+    }
+}
+---------------------------------------------------------------------------------
+
+The mapper can also be used to transform query parameters. Parameters
+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
+`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:
+
+[source,java]
+-------------------------------------------------------------------------------
+@Repository(forEntity = Person.class)
+@MappingConfig(PersonDtoMapper.class)
+public interface PersonRepository extends EntityRepository<PersonDto, PersonId>
+{
+    ...
+}
+-------------------------------------------------------------------------------
+
+In this case, the `forEntity` attribute in the `@Repository` annotation
+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
+
+
+In many cases it's 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:
+
+[source,java]
+-------------------------------------------------------------------------------
+public class PersonMapper extends SimpleQueryInOutMapperBase<Person, PersonDto>
+{
+
+    @Override
+    protected Object getPrimaryKey(PersonDto dto)
+    {
+        return dto.getId();
+    }
+
+    @Override
+    protected PersonDto toDto(Person entity)
+    {
+        ...
+    }
+
+    @Override
+    protected Person toEntity(Person entity, PersonDto dto) {
+        ...
+        return entity;
+    }
+}
+-------------------------------------------------------------------------------
+
+The first method, `getPrimaryKey`, identifies the primary key of an
+incoming DTO (this might need mapping too). If there is a primary key in
+the DTO, Data tries to retrieve the Entity and feed it to the `toEntity`
+method, so the entity to be mapped is **attached to the persistence
+context**. If there is no primary key, a new instance of the Entity is
+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
+
+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.
+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
+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
+
+The API is centered around the Criteria class and is targeted to provide
+a fluent interface to write criteria queries:
+
+[source,java]
+---------------------------------------------------------------------------
+@Repository(forEntity = Person.class)
+public abstract class PersonRepository implements CriteriaSupport<Person>
+{
+
+    public List<Person> findAdultFamilyMembers(String name, Integer minAge)
+    {
+        return criteria()
+                .like(Person_.name, "%" + name + "%")
+                .gtOrEq(Person_.age, minAge)
+                .eq(Person_.validated, Boolean.TRUE)
+                .orderDesc(Person_.age)
+                .getResultList();
+    }
+
+}
+---------------------------------------------------------------------------
+
+Following comparators are supported by the API:
+
+[options="header,autowidth"]
+|===
+| Name                    | Description
+| .eq(..., ...)           | Property value must be equal to the given value
+| .in(..., ..., ..., ...) | Property value must be in one of the given values.
+| .notEq(..., ...)        | Negates equality
+| .like(..., ...)         | A SQL `like` equivalent comparator. Use % on the value.
+| .notLike(..., ...)      | Negates the like value
+| .lt(..., ...)           | Property value must be less than the given value.
+| .ltOrEq(..., ...)       | Property value must be less than or equal to the given value.
+| .gt(..., ...)           | Property value must be greater than the given value.
+| .ltOrEq(..., ...)       | Property value must be greater than or equal to the given value.
+| .between(..., ..., ...) | Property value must be between the two given values.
+| .isNull(...)            | Property must be `null`
+| .isNotNull(...)         | Property must be non-`null`
+| .isEmpty(...)           | Collection property must be empty
+| .isNotEmpty(...)        |Collection property must be non-empty
+|===
+
+The query result can be modified with the following settings:
+
+[options="header,autowidth"]
+|===
+| Name                     | Description
+| .orderAsc(...)           | Sorts the result ascending by the given property. Note that this can be applied to several properties
+| .orderDesc(...)          | Sorts the result descending by the given property. Note that this can be applied to several properties
+| .distinct()              | Sets distinct to true on the query.
+|=== 
+
+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
+
+For simple cases, restricting on the repository entity only works out
+fine, but once the Data model gets more complicated, the query will have
+to consider relations to other entities. The module's criteria API
+therefore supports joins as shown in the sample below:
+
+[source,java]
+-------------------------------------------------------------------------------------
+@Repository
+public abstract class PersonRepository extends AbstractEntityRepository<Person, Long>
+{
+
+    public List<Person> findByCompanyName(String companyName)
+    {
+        return criteria()
+                .join(Person_.company,
+                    where(Company.class)
+                        .eq(Company_.name, companyName)
+                )
+                .eq(Person_.validated, Boolean.TRUE)
+                .getResultList();
+    }
+
+}
+-------------------------------------------------------------------------------------
+
+Beside the inner and outer joins, also fetch joins are supported. Those
+are slighly simpler as seen in the next sample:
+
+[source,java]
+-------------------------------------------------------------------------------------
+public abstract class PersonRepository extends AbstractEntityRepository<Person, Long>
+{
+
+    public Person findBySSN(String ssn)
+    {
+        return criteria()
+                .fetch(Person_.familyMembers)
+                .eq(Person_.ssn, ssn)
+                .distinct()
+                .getSingleResult();
+    }
+
+}
+-------------------------------------------------------------------------------------
+
+
+=== 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
+disjunctions.
+
+[source,java]
+-------------------------------------------------------------------------------------
+public abstract class PersonRepository extends AbstractEntityRepository<Person, Long>
+{
+
+    public List<Person> findAdults()
+    {
+        return criteria()
+                .or(
+                    criteria().
+                        .gtOrEq(Person_.age, 18)
+                        .eq(Person_.origin, Country.SWITZERLAND),
+                    criteria().
+                        .gtOrEq(Person_.age, 21)
+                        .eq(Person_.origin, Country.USA)
+                )
+                .getResultList();
+    }
+
+}
+-------------------------------------------------------------------------------------
+
+
+=== Selections
+
+It might not always be appropriate to retrieve full entities - you might
+also be interested in scalar values or by modified entity attributes.
+The Criteria interface allows this with the selection method:
+
+[source,java]
+------------------------------------------------------------------------------------------------------
+public abstract class PersonRepository extends AbstractEntityRepository<Person, Long>
+{
+
+    public Statistics ageStatsFor(Segment segment)
+    {
+        return criteria()
+                 .select(Statistics.class, avg(Person_.age), min(Person_.age), max(Person_.age))
+                 .eq(Person_.segment, segment)
+                 .getSingleResult();
+    }
+
+    public List<Object[]> personViewForFamily(String name)
+    {
+        return criteria()
+                 .select(upper(Person_.name), attribute(Person_.age), substring(Person_.firstname, 1))
+                 .like(Person_.name, name)
+                 .getResultList();
+    }
+
+}
+------------------------------------------------------------------------------------------------------
+
+There are also several functions supported which can be used in the
+selection clause:
+
+[options="header,autowidth"]
+|===
+|Name                              | Description
+| abs(...)                         | Absolute value. Applicable to Number attributes.
+| avg(...)                         | Average value. Applicable to Number attributes.
+| count(...)                       | Count function. Applicable to Number attributes.
+| max(...)                         | Max value. Applicable to Number attributes.
+| min(...)                         | Min value. Applicable to Number attributes.
+| modulo(...)                      | Modulo function. Applicable to Integer attributes.
+| neg(...)                         | Negative value. Applicable to Number attributes.
+| sum(...)                         | Sum function. Applicable to Number attributes.
+| lower(...)                       | String to lowercase. Applicable to String attributes.
+| substring(int from, ...)         | Substring starting from. Applicable to String attributes.
+| substring(int from, int to, ...) | Substring starting from ending to. Applicable to String attributes.
+| upper(...)                       | String to uppercase. Applicable to String attributes.
+| currDate()                       | The DB sysdate. Returns a Date object.
+| currTime()                       | The DB sysdate. Returns a Time object.
+| currTStamp()                     | The DB sysdate. Returns a Timestamp object.
+|===
+
+
+== 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
+requirement for your audits, have a look at Hibernate Envers.
+______________________________________________________________________________________________________________________________________
+
+
+=== Activating Auditing
+
+DeltaSpike uses an entity listener to update auditing data before
+entities get created or update. The entity listener must be activated
+before it can be used. This can either be done globally for all entities
+of a persistent unit or per entity.
+
+Activation per persistence unit in `orm.xml`:
+
+[source,xml]
+-----------------------------------------------------------------------------------------------------------------------------------------
+<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+        xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_2_0.xsd" version="2.0">
+    <persistence-unit-metadata>
+        <persistence-unit-defaults>
+            <entity-listeners>
+                <entity-listener class="org.apache.deltaspike.data.impl.audit.AuditEntityListener" />
+            </entity-listeners>
+        </persistence-unit-defaults>
+    </persistence-unit-metadata>
+</entity-mappings>
+-----------------------------------------------------------------------------------------------------------------------------------------
+
+Activation per entity:
+
+[source,java]
+-------------------------------------------
+@Entity
+@EntityListeners(AuditEntityListener.class)
+public class AuditedEntity
+{
+
+    ...
+
+} 
+-------------------------------------------
+
+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
+
+All that has to be done now is annotating the entity properties which
+are used to audit the entity.
+
+==== Updating Timestamps
+
+To keep track on creation and modification times, following annotations
+can be used:
+
+[source,java]
+-------------------------------------
+@Entity
+public class AuditedEntity
+{
+
+    ...
+
+    @Temporal(TemporalType.TIMESTAMP)
+    @CreatedOn
+    private Date created;
+
+    @Temporal(TemporalType.TIMESTAMP)
+    @ModifiedOn
+    private Date updated;
+
+    ...
+
+}
+-------------------------------------
+
+In case the modification date should also be set during entity creation,
+the annotation can be customized:
+
+-----------------------------
+@ModifiedOn(setOnCreate=true)
+-----------------------------
+
+==== Who's Changing My Entities?
+
+Beside keeping track of when a change has happened, it's also often
+critical to track who's responsible for the change. Annotate a user
+tracking field with the following annotation:
+
+[source,java]
+-----------------------------
+@Entity
+public class AuditedEntity
+{
+
+    ...
+
+    @ModifiedBy
+    private String auditUser;
+
+    ... 
+
+}
+-----------------------------
+
+Now a little help is needed. The entity listener needs to be able to
+resolve the current user - there must be a bean available of the
+matching type for the annotation property, exposed over a special CDI
+qualifier:
+
+[source,java]
+----------------------------------
+public class UserProvider
+{
+
+    @Inject
+    private User user;
+
+    @Produces @CurrentUser
+    public String currentUser() {
+        return user.getUsername();
+    }
+
+    ... 
+
+}        
+----------------------------------
+
+*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.
+______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/d8d70fe9/documentation/src/main/asciidoc/index.adoc
----------------------------------------------------------------------
diff --git a/documentation/src/main/asciidoc/index.adoc b/documentation/src/main/asciidoc/index.adoc
new file mode 100644
index 0000000..a1c580f
--- /dev/null
+++ b/documentation/src/main/asciidoc/index.adoc
@@ -0,0 +1,729 @@
+= Documentation
+
+: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.2</deltaspike.version>
+</properties>
+--------------------------------------------------
+
+Or if you want to very bleeding edge, point to our current snapshot.
+
+[source,xml]
+-----------------------------------------------------------
+<properties>
+    <deltaspike.version>1.0.3-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</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]


Mime
View raw message