documentation/src/main/asciidoc/cdiimp.adoc

= Enable CDI For Your Java Environment

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

DeltaSpike requires a CDI implementation to be available in the Java environment where your projects are deployed. The implementation provides the CDI essentials, managing dependency injection and contextual lifecycles. link:http://weld.cdi-spec.org/[JBoss Weld] and link:http://openwebbeans.apache.org/[Apache OpenWebBeans (OWB)] are two widely used CDI implementations. Dependent on the Java environment you choose, some setup may be necessary as detailed here.

== Java EE6+ Containers
CDI is part of Java EE6 and later so CDI implementations are included as standard in Java EE6+ compliant environments. There is no additional CDI configuration needed besides including the CDI-obligatory `beans.xml` file in your project.

JBoss Weld is integrated in Java EE application servers including WildFly, JBoss Enterprise Application Platform, GlassFish, IBM WebSphere Application Server (8.5.5 and up) and Oracle WebLogic.

Apache OpenWebBeans (OWB) is integrated in Java EE containers including Apache TomEE, Apache Geronimo, IBM WebSphere Application Server, and SiwPas.

== Java EE5 and Servlet Containers
CDI implementations are not distributed with Java EE5 application servers or Servlet-only environments such as Apache TomCat and Eclipse Jetty. You can use CDI in these environments by embedding a standalone CDI implementation. Both JBoss Weld and Apache OpenWebBeans can be used for this task; for more information, see the corresponding CDI implementation documentation.

[[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.

DeltaSpike provides a dedicated Container Control module to enable applications deployed in Java SE environments to boot a CDI container. The Container Control module consists of the API component and components specific to the JBoss Weld, Apache OpenWebBeans and Apache OpenEJB CDI containers. The DeltaSpike module provides a layer of abstraction from the specific CDI containers, enabling you to write container-independent code in your project.

Instructions are provided here for adding the required resources to Maven based, Gradle based and build independent projects and subsequently booting the CDI container from your project source code.

=== Declare CDI Dependencies 

==== Dependencies for Maven and Gradle based Projects
For Maven-based projects, the Container Control module is available in Maven Central together with the other DeltaSpike modules. You must configure your project to use the DeltaSpike Container Control API and one of the CDI container-specific modules.

. Import the project as defined in link:/documentation/configure.html[Configure DeltaSpike in Your Projects]
. Import the CDI Control API to your project.
a. If you're using Maven, add the following to `pom.xml`
+
[source,xml]
----
<dependency>
    <groupId>org.apache.deltaspike.cdictrl</groupId>
    <artifactId>deltaspike-cdictrl-api</artifactId>
    <scope>compile</scope>
</dependency>
----
+
b. If you're using Gradle, add the following to `build.gradle`
+
[source]
----
dependencies {
    compile 'org.apache.deltaspike.cdictrl:deltaspike-cdictrl-api'
}
----
+
. Add CDI container dependencies for one of the container options listed here
- For JBoss Weld
.. Add the JBoss Weld version to the list of properties, replacing the version as desired
+
[source,xml]
----
<properties>
    <weld.version>2.3.3.Final</weld.version>
</properties>
----
+
.. Add the JBoss Weld dependency to the list of dependencies
+
[source,xml]
----
<dependency>
    <groupId>org.jboss.weld.se</groupId>
    <artifactId>weld-se</artifactId>
    <version>${weld.version}</version>
    <scope>runtime</scope>
</dependency>
----
+
.. Add the DeltaSpike Weld-specific Container Control module to the list of dependencies
+
[source,xml]
----
<dependency>
    <groupId>org.apache.deltaspike.cdictrl</groupId>
    <artifactId>deltaspike-cdictrl-weld</artifactId>
    <scope>runtime</scope>
</dependency>
----
+
- JBoss Weld with Gradle
.. If you're using Gradle, add the following to `build.gradle`
+
[source]
----
def weldVersion = '2.3.3.Final'
dependencies {
    runtime 'org.jboss.weld.se:weld-se:'+weldVersion
    runtime 'org.apache.deltaspike.cdictrl:deltaspike-cdictrl-weld'
}
----
+
- For Apache OpenWebBeans
.. Add the Apache OpenWebBeans version to the list of properties, replacing the version as desired
+
[source,xml]
----
<properties>
    <owb.version>1.6.3</owb.version>
</properties>
----
+
.. Add the Apache OpenWebBeans dependencies to the list of dependencies
+
[source,xml]
----
<dependency>
    <groupId>org.apache.openwebbeans</groupId>
    <artifactId>openwebbeans-impl</artifactId>
    <version>${owb.version}</version>
    <scope>runtime</scope>
</dependency>

<dependency>
    <groupId>org.apache.openwebbeans</groupId>
    <artifactId>openwebbeans-spi</artifactId>
    <version>${owb.version}</version>
    <scope>compile</scope>
</dependency>
----
+
.. Add the DeltaSpike Apache OpenWebBeans-specific Container Control module to the list of dependencies
+
[source,xml]
----
<dependency>
    <groupId>org.apache.deltaspike.cdictrl</groupId>
    <artifactId>deltaspike-cdictrl-owb</artifactId>
    <scope>runtime</scope>
</dependency>
----
+
- Apache OpenWebBeans with Gradle
.. If you're using Gradle, add the following to `build.gradle`
+
[source]
----
def owbVersion = '1.6.3'
dependencies {
    runtime 'org.apache.openwebbeans:openwebbeans-impl:'+owbVersion
    compile 'org.apache.openwebbeans:openwebbeans-spi:'+owbVersion
    runtime 'org.apache.deltaspike.cdictrl:deltaspike-cdictrl-owb'
}
----
+
- Save the `pom.xml` file changes
+
----
mvn clean install
----
+
- Save the `build.gradle` file changes
+
----
gradle build
----

==== Dependencies for build independent projects
For build independent projects, the Container Control module is distributed together with the other DeltaSpike modules in `distribution-full-<version>.zip`. You must add two of the files from the `cdictrl` directory to your project, namely `deltaspike-cdictrl-api.jar` and the .jar file that corresponds to the CDI container you have chosen. Add these files to the project `WEB-INF/lib` or `EAR/lib` directory for .war and .ear projects respectively.

== Next
* For more information about the Container Control module, see <<container-control#,Container Control Module>>.
* To understand how the various DeltaSpike modules can enhance and extend your applications, see <<modules#,Overview of DeltaSpike Modules>> and the individual module pages.
* To see ready-to-deploy example DeltaSpike applications, see link:http://deltaspike.apache.org/examples.html[See DeltaSpike in Action].