[[CDI_Reference]]
= CDI Reference

WildFly uses http://weld.cdi-spec.org/[Weld], the CDI reference
implementation as its CDI provider. To activate CDI for a deployment
simply add a `beans.xml` file in any archive in the deployment.

This document is not intended to be a CDI tutorial, it only covers CDI
usage that is specific to WildFly. For some general information on CDI
see the below links:

http://docs.jboss.org/cdi/spec/1.2/cdi-spec.html[CDI Specification] +
http://docs.jboss.org/weld/reference/latest/en-US/html/[Weld Reference
Guide] +
https://github.com/wildfly/quickstart/[The WildFly Quickstarts]

[[using-cdi-beans-from-outside-the-deployment]]
== Using CDI Beans from outside the deployment

For WildFly {wildflyVersion} onwards, it is now possible have classes outside the
deployment be picked up as CDI beans. In order for this to work you must
add a dependency on the external deployment that your beans are coming
from, and make sure the META-INF directory of this deployment is
imported, so that your deployment has visibility to the `beans.xml` file
(To import beans from outside the deployment they must be in an archive
with a `beans.xml` file).

There are two ways to do this, either using the `MANIFEST.MF` or using
`jboss-deployment-structure.xml`.

Using `MANIFEST.MF` you need to add a `Dependencies` entry, with
meta-inf specified after the entry, e.g.

....
Dependencies: com.my-cdi-module meta-inf, com.my-other-cdi-module meta-inf
....

Using `jboss-deployment-structure.xml` you need to add a dependency
entry with `meta-inf="import"`, e.g.

[source, xml]
----
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        <dependencies>
            <module name="deployment.d1.jar" meta-inf="import"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>
----

Note that this can be used to create beans from both modules in the
`modules` directory, and from other deployments.

For more information on class loading and adding dependencies to your
deployment please see the <<Class_Loading_in_WildFly,Class
Loading Guide>>

[[suppressing-implicit-bean-archives]]
== Suppressing implicit bean archives

CDI 1.1 brings new options to packaging of CDI-enabled applications. In
addition to well-known explicit bean archives (basically any archive
containing the *beans.xml* file) the specification introduces *implicit
bean archives*.

An implicit bean archive is any archive that contains one or more
classes annotated with a bean defining annotation (scope annotation) or
one or more session beans. As a result, the beans.xml file is no longer
required for CDI to work in your application.

In an implicit bean archive *only those classes* that are either
annotated with bean defining annotations or are session beans are
recognized by CDI as beans (other classes cannot be injected).

This has a side-effect, though. Libraries exist that make use of scope
annotation (bean defining annotations) for their own convenience but are
not designed to run with CDI support. Guava would be an example of such
library. If your application bundles such library it will be recognized
as a CDI archive and may
https://code.google.com/p/guava-libraries/issues/detail?id=1433[fail the
deployment].

Fortunately, WildFly makes it possible to suppress implicit bean
archives and only enable CDI in archives that bundle the beans.xml file.
There are two ways to achieve this:

[[per-deployment-configuration]]
=== Per-deployment configuration

You can either set this up for your deployment only by adding the
following content to the *META-INF/jboss-all.xml* file of your
application:

[source,xml]
----
<jboss xmlns="urn:jboss:1.0">
    <weld xmlns="urn:jboss:weld:1.0" require-bean-descriptor="true"/>
</jboss>
----

[[global-configuration]]
=== Global configuration

Alternatively, you may configure this for all deployments in your
WildFly instance by executing the following command:

[source,ruby]
----
/subsystem=weld:write-attribute(name=require-bean-descriptor,value=true)
----

[[development-mode]]
== Development mode

WildFly 10 introduces a special mode for application development which
allows you to inspect and monitor your CDI deployments. This mode is
turned off by default and note that some features of the *development
mode may have negative impact on the performance and/or functionality of
the application*.

[[per-deployment-configuration-1]]
=== Per-deployment configuration

You can enable it locally in your application `web.xml` by setting the
Servlet initialization parameter `org.jboss.weld.development` to `true:`

[source,xml]
----
 <context-param>
   <param-name>org.jboss.weld.development</param-name>
   <param-value>true</param-value>
 </context-param>
----

[[global-configuration-1]]
=== Global configuration

Alternatively, you can enable it globally in Weld subsystem by setting
`development-mode` attribute to `true:`

[source,ruby]
----
/subsystem=weld:write-attribute(name=development-mode,value=true)
----

For more details and example you can check
http://docs.jboss.org/weld/reference/latest/en-US/html_single/#devmode[Weld
development mode].

Once the development mode is enabled you can check your applications CDI
information using Weld Probe -
http://docs.jboss.org/weld/reference/latest/en-US/html_single/#probe[Weld
Probe].

[[non-portable-mode]]
== Non-portable mode

CDI 1.1 clarifies some aspects of how CDI protable extensions work. As a
result, some extensions that do not use the API properly (but were
tolerated in CDI 1.0 environment) may stop working with CDI 1.1.If this
is the case of your application you will see an exception like this:

....
org.jboss.weld.exceptions.IllegalStateException: WELD-001332: BeanManager method getBeans() is not available during application initialization
....

Fortunatelly, there is a non-portable mode available in WildFly which
skips some of the API usage checks and therefore allows the legacy
extensions to work as before.

Again, there are two ways to enable the non-portable mode:

[[per-deployment-configuration-2]]
=== Per-deployment configuration

You can either set this up for your deployment only by adding the
following content to the *META-INF/jboss-all.xml* file of your
application:

[source,xml]
----
<jboss xmlns="urn:jboss:1.0">
    <weld xmlns="urn:jboss:weld:1.0" non-portable-mode="true" />
</jboss>
----

[[global-configuration-2]]
=== Global configuration

Alternatively, you may configure this for all deployments in your
WildFly instance by executing the following command:

[source,ruby]
----
/subsystem=weld:write-attribute(name=non-portable-mode,value=true)
----

*Note that new portable extensions should always use the*
*http://docs.jboss.org/cdi/api/1.1/javax/enterprise/inject/spi/BeanManager.html[BeanManager
API]* *properly and thus never required the non-portable mode. The
non-portable mode only exists to preserve compatibility with legacy
extensions!*