Weld Reference Guide

Tomcat 9, which implements Servlet 4.0 specification, is supported.

Jetty 9.4.14 and newer are supported. Context activation/deactivation and dependency injection into Servlets and Filters works out of the box. Injection into Servlet listeners works on Jetty 9.1.1 and newer.

No further configuration is needed when starting Jetty as an embedded webapp server from within another Java program. However, if you’re using a Jetty standalone instance one more configuration step is required, one of the jetty modules listed below needs to be enabled.

Weld supports context activation/deactivation and dependency injection into Servlets when running on Undertow. Injection into Filters and Servlet listeners is not currently supported. Weld’s listener needs to be registered programmatically:

WildFly Web is a lightweight Servlet container that uses Undertow. Weld supports context activation/deactivation and dependency injection into Servlets. Injection into Filters and Servlet listeners is not currently supported. Weld integration is started automatically when weld-servlet is part of your application.

By default, bean archive isolation is enabled. It means that alternatives, interceptors and decorators can be selected/enabled for a bean archive by using a beans.xml descriptor.

This behaviour can be changed by setting the servlet initialization parameter org.jboss.weld.environment.servlet.archive.isolation to false. In this case, Weld will use a "flat" deployment structure - all bean classes share the same bean archive and all beans.xml descriptors are automatically merged into one. Thus alternatives, interceptors and decorators selected/enabled for a bean archive will be enabled for the whole application.

CDI 1.1 introduced the bean discovery mode of annotated used for implicit bean archives (see also Packaging and deployment . This mode may bring additional overhead during container bootstrap. Therefore, Weld Servlet supports the use of Jandex bytecode scanning library to speed up the scanning process. Simply put the jandex.jar on the classpath. If Jandex is not found on the classpath Weld will use the Java Reflection as a fallback.

In general, an implicit bean archive does not have to contain a beans.xml descriptor. However, such a bean archive is not supported by Weld Servlet, i.e. it’s excluded from discovery.

Weld servlet container integration is delivered as a single artifact, so that it’s possible to include this artifact in a war and deploy the application to any of the suported servlet containers. This approach has advantages but also drawbacks. One of them is the fact that Weld attempts to detect the servlet container automatically. While this works most of the time, there are few rare cases, when it might be necessary to specify the container manually by setting the servlet initialization parameter org.jboss.weld.environment.container.class to:

Weld provides an extension which will boot a CDI bean manager in Java SE, automatically registering all simple beans found on the classpath. The command line parameters can be injected using either of the following:

The second form is useful for compatibility with existing classes.

Here’s an example of a simple CDI SE application:

CDI SE applications can be bootstrapped in the following ways.

Weld introduces an @ActivateRequestContext interceptor binding which enables you to explicitly activate the request context and use @RequestScoped beans in Java SE. The following example shows how to achieve that:

In contrast to Java EE applications, Java SE applications place no restrictions on developers regarding the creation and usage of threads. Therefore Weld SE provides a custom scope annotation, @ThreadScoped, and corresponding context implementation which can be used to bind bean instances to the current thread. It is intended to be used in scenarios where you might otherwise use ThreadLocal, and does in fact use ThreadLocal under the hood.

To use the @ThreadScoped annotation you need to enable the RunnableDecorator which 'listens' for all executions of Runnable.run() and decorates them by setting up the thread context beforehand, bound to the current thread, and destroying the context afterwards.

Another option how to use thread context is to enable it at class or method level by @ActivateThreadScope interceptor binding and related ActivateThreadScopeInterceptor.

Weld SE comes packaged as a 'shaded' jar which includes the CDI API, Weld Core and all dependent classes bundled into a single jar. Therefore the only Weld jar you need on the classpath, in addition to your application’s classes and dependent jars, is the Weld SE jar. If you are working with a pure Java SE application you launch using java, this may be simpler for you.

If you prefer to work with individual dependencies, then you can use the weld-se-core jar which just contains the Weld SE classes. Of course in this mode you will need to assemble the classpath yourself.

If you work with a dependency management solution such as Maven you can declare a dependency such as:

By default, bean archive isolation is enabled. It means that alternatives, interceptors and decorators can be selected/enabled for a bean archive by using a beans.xml descriptor.

This behaviour can be changed by setting a system property org.jboss.weld.se.archive.isolation to false or through the Weld.property() method. In this case, Weld will use a "flat" deployment structure - all bean classes share the same bean archive and all beans.xml descriptors are automatically merged into one. Thus alternatives, interceptors and decorators selected/enabled for a bean archive will be enabled for the whole application.

CDI 1.1 introduced the bean discovery mode of annotated used for implicit bean archives (see also Packaging and deployment . This mode may bring additional overhead during container bootstrap. Therefore, Weld Servlet supports the use of Jandex bytecode scanning library to speed up the scanning process. Simply put the jandex.jar on the classpath. If Jandex is not found on the classpath Weld will use the Java Reflection as a fallback.

By default, an implicit bean archive that does not contain a beans.xml descriptor is excluded from discovery. However, it is possible to instruct Weld to scan all class path entries and discover such archive. You can do so by setting Weld system property org.jboss.weld.se.scan.classpath.entries or CDI 2.0 system property javax.enterprise.inject.scan.implicit to true. Another approach is to use Weld.property() and SeContainerInitializer.addProperty() methods.

If you are running with discovery mode annotated, then only classes with bean defining annotations will be picked up as beans. The set of these annotations is given by CDI but Weld SE allows you to expand it via Weld.addBeanDefiningAnnotations(Class<? extends Annotation>…​ annotations). Any annotation added this way will be considered a bean defining annotation when performing discovery.

Just note that added annotations are ignored if you are also using <trim/> option or Weld configuration key org.jboss.weld.bootstrap.vetoTypesWithoutBeanDefiningAnnotation.

CDI requires that beans that are normal-scoped, intercepted or decorated always define a no-argument constructor. This requirement applies even if the bean already defines an @Inject annotated constructor with parameters. This is purely a technical requirement implied by how Java allocates class instances.

Weld is however able to operate fine even if this requirement is not met. Weld uses special non-portable JVM APIs that allow it to allocate proxy instances without calling proxy’s constructor. This mode is not enabled by default. It can be enabled using the following configuration option:

Note that relaxed construction is enabled by default in Weld SE .

By default Weld supports concurrent loading and deploying of beans. However, in certain deployment scenarios the default setup may not be appropriate.

For certain types of tasks Weld uses its own thread pool. The thread pool is represented by the ExecutorServices service.

First of all, let’s see what types of thread pools are available:

Now let’s see how to configure Weld to use a particular thread pool type:

By default the application initialization is performed in the portable mode which denotes specification-compliant behaviour. However it’s also possible to enable the non-portable mode, in which some definition errors and deployment problems do not cause application initialization to abort. Currently the non-portable mode allows extension developers to call all the BeanManager’s methods before the `AfterDeploymentValidation event is fired.

Weld offers a non-standard way to create proxies for non-private, non-static final methods. When using this option, such final method will be ignored during proxy generation and the Java type will be proxied (as opposed to classical behavior when there would be an exception thrown). Since the method was ignored during proxy creation, it should never be invoked.

In order to make this work, use the below shown configuration key and pass it a regular expression. When Weld finds an unproxyable type which matches this pattern, the final methods will be ignored and the type will be proxied.

Weld caches already resolved injection points in order to resolve them faster in the future. A separate type-safe resolver exists for beans, decorators, disposers, interceptors and observers. Each of them stores resolved injection points in its cache, which maximum size is bounded by a default value (common to all of them).

For debugging purposes, it’s possible to dump the generated bytecode of client proxies and enhanced subclasses to the filesystem.

For certain combinations of scopes, the container is permitted to optimize an injectable reference lookup. Enabling this feature brings some performance boost but causes javax.enterprise.context.spi.AlterableContext.destroy() not to work properly for @ApplicationScoped and @RequestScoped beans. Therefore, the optimization is disabled by default.

This optimization is used to reduce the HTTP session replication overhead. However, the inconsistency detection mechanism may cause problems in some development environments. It’s recommended to disable this optimization during the development phase.

The delimiter is used to abbreviate a bean archive identifier (which is usually derived from the archive name) before used as a part of an identifier of an internal component (such as bean).

The abbreviation proceeds as follows:

Note that the delimiter is used for all bean archives forming the application.

An example: Given an application with two versions going by the names test__1-1.war and test__1-2.war. Weld normally cannot support replication of @SessionScoped beans between these two deployments. Using this configuration option with delimiter "__" will allow Weld to see both applications simply as test.war, hence allowing for session replication.

Some features of the development mode may have negative impact on the performance and/or functionality of the application. The following configuration properties allow to tune or disable these features, e.g. to specify the set of components which will be monitored.

Weld provides configuration properties to override values for default conversation timeout and default conversation concurrent access timeout which represents the maximum time to wait on the conversation concurrent lock.

Sometimes it might be useful to process all types during bootstrap, i.e. fire/observe ProcessAnnotatedType event for each Java class discovered, but veto types which are not annotated with a bean defining annotation. The main reason is that not all classes that meet all of the necessary conditions are intended to become beans. And so vetoing such types helps to conserve memory used by the container. Note that if you use bean-discovey-mode=annotated (implicit bean archive) then no ProcessAnnotatedType will be fired for any such type because it’s not discovered at all. And there might be portable extensions which use ProcessAnnotatedType to extract some important information from classes which are not beans.

Therefore, Weld allows to use bean-discovey-mode=all (explicit bean archive) and veto types without a bean defining annotation whose AnnotatedType#getJavaClass().getName() matches a regular expression. In other words, a type is vetoed if its name matches a regular expression and at the same time is not annotated with a bean defining annotation. The functionality is implemented as a built-in portable extension processing all types from all bean archives.

CDI applications consist of user-defined beans implementing the business logic, but also beans coming from libraries (e.g. DeltaSpike) and integrations (e.g. various Java EE technologies - JSF, Bean Validation, Batch). Most applications actually use only a small part of the beans provided by libraries and integrations. Still, Weld has to retain the metadata for all the beans in memory which can be considerably vast footprint, depending on the application. If Optimized cleanup after bootstrap is allowed, Weld can remove unused beans after bootstrap.

An unused bean:

The following properties can be used to restrict the set of beans Weld is going to remove, e.g. to eliminate the false positives.

For a web application, set the Servlet initialization parameter org.jboss.weld.development to true:

For a Java SE application, set the system property org.jboss.weld.development to true:

or use the Weld.enableDevMode() method:

You should see the following log message during initialization of your application:

This tool allows you to inspect the application CDI components at runtime. There is a default UI - HTML client (single-page application), which is only available in web applications. Just point your browser to protocol://host:port/webappContextPath/weld-probe, e.g. http://localhost:8080/weld-numberguess/weld-probe. However, it’s also posible to obtain the JSON data through the REST API, eventually (if JMX support is enabled ) through the MXBean of name org.jboss.weld.probe:type=JsonData,context=ID where ID should be replaced with an idenfitier of an application. Right now, Probe integration is provided for WildFly, Tomcat and Jetty (Weld Servlet), and Weld SE.

If a deployment validation fails and the development mode is enabled a simple HTML report is generated. The report contains a lot of useful information such as Weld version, list of enabled beans, list of bean archives, Weld configuration, etc. By default, the report is generated to the user’s current working directory, ie. user.dir. However, it is also possible to specify a path to the target directory using the org.jboss.weld.probe.exportDataAfterDeployment configuration property - see also Development Mode .

You should see a similar log message which contains the path to the report file:

Weld 3.1.7.Final - CDI Reference Implementation

There are several new things in Weld API allowing for this. Firstly, all contexts supporting propagation now implement org.jboss.weld.context.WeldAlterableContext, an interface extending javax.enterprise.context.spi.AlterableContext. Methods on WeldAlterableContext allow to capture current context state, returning a collection of all contextual instances, as well as clear and set the context state by feeding it a collection of contextual instances.

In order to get hold of these contexts, the best approach is to use WeldManager, an injectable bean providing some capabilities on top of what BeanManager has. Following WeldManager methods are useful for context propagation:

There is a concise example in a form of a test in our code showing how to propagate all built-in contexts. This doc only contains an excerpt from it, you can look here to get the full picture.

Following code shows a service that provides an extra thread onto which you offload a Callable<T> that uses beans from currently active context. The service activates contexts, propagates state from original thread, executes task and cleans up. Bound versions of Weld context implementations are used as on this new thread there is no actual HTTP request or session existing.

There are several things that can possibly go wrong when propagating contexts. User code needs to be aware that propagation can happen and prepare their beans accordingly. For instance request scoped beans could now theoretically be accessed concurrently which wasn’t the case before.

@PreDestroy and @Disposes on your beans could cause inconsistent state based on how you perform the propagation. Since the same bean is now used in several threads, all of them can, in invalidating and deactivating contexts, trigger these methods but the bean will still exist in yet another thread. The example given above avoids calling context.invalidate() and only performs context.deactivate() - this avoids invoking @PreDestroy/@Disposes methods but could possibly lead to never invoking them if no thread does it. Note that this problem only concerns request, session and conversation beans where you manually need to activate/deactivate contexts. Application/singleton scoped bean would still work and their cleanup callbacks will only be invoked once during container shutdown.

There is currently no way to propagate any other contexts than those mentioned here. Custom scopes as well as scopes from other EE specifications have no support for this feature. The reason is that while technically any context implementing WeldAlterableContext can be used to obtain/set collection of contextual instances, there is no way of knowing how to activate custom contexts in different threads.

Last but not least, context propagator needs to be aware of context implementations existing in Weld, see Available Contexts in Weld. However, in a new thread some extra knowledge is required to activate the contexts. Bound versions (backed by a provided storage; a map in our case) were used, and those need to have a storage associated before activating them, hence the code such as requestContext.associate(requestMap). There is no need to use bound version though; propagators are free to choose from other context implementations.

Weld 3.1.7.Final - CDI Reference Implementation

An application is often comprised of a number of modules. For example, a Java EE deployment may contain a number of EJB modules (containing business logic) and war modules (containing the user interface). A container may enforce certain accessibility rules which limit the visibility of classes between modules. CDI allows these same rules to apply to bean and observer method resolution. As the accessibility rules vary between containers, Weld requires the container to describe the deployment structure, via the Deployment SPI.

The CDI specification discusses Bean Archives (BAs)—archives which are marked as containing beans which should be deployed to the CDI container, and made available for injection and resolution. Weld reuses this description and uses Bean Deployment Archives (BDA) in its deployment structure SPI.

Each deployment exposes the containing BDAs that form a graph. A node in the graph represents a BDA. Directed edges between nodes designate visibility. Visibility is not transitive (i.e. a bean from BDA A can only see beans in BDAs with which A is directly connected by a properly oriented edge).

To describe the deployment structure to Weld, the container should provide an implementation of Deployment. Deployment.getBeanDeploymentArchives() allows Weld to discover the modules which make up the application. The CDI specification also allows beans to be specified programmatically as part of the bean deployment. These beans may, or may not, be in an existing BDA. For this reason, Weld will call Deployment.loadBeanDeploymentArchive(Class clazz) for each programmatically described bean.

As programmatically described beans may result in additional BDAs being added to the graph, Weld will discover the BDA structure every time an unknown BDA is returned by Deployment.loadBeanDeploymentArchive.

BeanDeploymentArchive provides three methods which allow it’s contents to be discovered by Weld—BeanDeploymentArchive.getBeanClasses() must return all the classes in the BDA, BeanDeploymentArchive.getBeansXml() must return a data structure representing the beans.xml deployment descriptor for the archive, and BeanDeploymentArchive.getEjbs() must provide an EJB descriptor for every EJB in the BDA, or an empty list if it is not an EJB archive.

To aid container integrator, Weld provides a built-in beans.xml parser. To parse a beans.xml into the data-structure required by BeanDeploymentArchive, the container should call Bootstrap.parse(URL). Weld can also parse multiple beans.xml files, merging them to become a single data-structure. This can be achieved by calling Bootstrap.parse(Iterable<URL>).

When multiple beans.xml files are merged, Weld keeps duplicate enabled entries (interceptors, decorators or alternatives). This may cause validation problems when multiple physical archives which define an overlapping enabled entries are merged. A version of the Bootstrap.parse() method that provides control over whether duplicate enabled entries are remove or not is provided: Bootstrap.parse(Iterable<URL> urls, boolean removeDuplicates).

BDA X may also reference another BDA Y whose beans can be resolved by, and injected into, any bean in BDA X. These are the accessible BDAs, and every BDA that is directly accessible by BDA X should be returned. A BDA will also have BDAs which are accessible transitively, and the transitive closure of the sub-graph of BDA X describes all the beans resolvable by BDA X.

To specify the directly accessible BDAs, the container should provide an implementation of BeanDeploymentArchive.getBeanDeploymentArchives().

Certain services are provided for the whole deployment, whilst some are provided per-BDA. BDA services are provided using BeanDeploymentArchive.getServices() and only apply to the BDA on which they are provided.

The contract for Deployment requires the container to specify the portable extensions (see chapter Packaging and deployment of the CDI specification) which should be loaded by the application. To aid the container integrator, Weld provides the method Bootstrap.loadExtensions(ClassLoader) which will load the extensions for the specified classloader.

Weld delegates EJB 3 bean discovery to the container so that it doesn’t duplicate the work done by the EJB container, and respects any vendor-extensions to the EJB definition.

The EjbDescriptor should return the relevant metadata as defined in the EJB specification. Each business interface of a session bean should be described using a BusinessInterfaceDescriptor.

By default, Weld uses the EJB component class when creating new EJB instances. This may not always be desired especially if the EJB container uses subclassing internally. In such scenario, the EJB container requires that the subclass it generated is used for creating instances instead of the component class. An integrator can communicate such layout to Weld by additionally implementing the optional SubclassedComponentDescriptor interface in the EjbDescriptor implementation. The return value of the SubclassedComponentDescriptor.getComponentSubclass() method determines which class will be used by Weld when creating new EJB instances.

All the EE resource services are per-BDA services, and may be provided using one of two methods. Which method to use is at the discretion of the integrator.

The integrator may choose to provide all EE resource injection services themselves, using another library or framework. In this case the integrator should use the EE environment, and implement the Injection Services SPI.

Alternatively, the integrator may choose to use CDI to provide EE resource injection. In this case, the EE_INJECT environment should be used, and the integrator should implement the EJB services, Resource Services and JPA services.

If the container performs EE resource injection, the injected resources must be serializable. If EE resource injection is provided by Weld, the resolved resource must be serializable.

Weld registers resource injection points with EjbInjectionServices, JpaInjectionServices, ResourceInjectionServices and JaxwsInjectionServices implementations upfront (at bootstrap). This allows validation of resource injection points to be performed at boot time rather than runtime. For each resource injection point Weld obtains a ResourceReferenceFactory which it then uses at runtime for creating resource references.

A ResourceReference provides access to the resource reference to be injected. Furthermore, ResourceReference allows resource to be release once the bean that received resource injection is destroyed.

EJB services are split between two interfaces which are both per-BDA.

EjbServices is used to resolve local EJBs used to back session beans, and must always be provided in an EE environment. EjbServices.resolveEjb(EjbDescriptor ejbDescriptor) returns a wrapper—SessionObjectReference—around the EJB reference. This wrapper allows Weld to request a reference that implements the given business interface, and, in the case of SFSBs, both request the removal of the EJB from the container and query whether the EJB has been previously removed.

EjbInjectionServices.registerEjbInjectionPoint(InjectionPoint injectionPoint) registers an @EJB injection point (on a managed bean) and returns a ResourceReferenceFactory as explained above. This service is not required if the implementation of Injection Services takes care of @EJB injection.

Just as EJB resolution is delegated to the container, resolution of @PersistenceContext for injection into managed beans (with the InjectionPoint provided), is delegated to the container.

To allow JPA integration, the org.jboss.weld.injection.spi.JpaInjectionServices interface should be implemented. This service is not required if the implementation of Injection Services takes care of @PersistenceContext injection.

Weld delegates JTA activities to the container. The SPI provides a couple hooks to easily achieve this with the TransactionServices interface.

Any javax.transaction.Synchronization implementation may be passed to the registerSynchronization() method and the SPI implementation should immediately register the synchronization with the JTA transaction manager used for the EJBs.

To make it easier to determine whether or not a transaction is currently active for the requesting thread, the isTransactionActive() method can be used. The SPI implementation should query the same JTA transaction manager used for the EJBs.

The resolution of @Resource (for injection into managed beans) is delegated to the container. You must provide an implementation of ResourceInjectionServices which provides these operations. This service is not required if the implementation of Injection Services takes care of @Resource injection.

The resolution of @WebServiceRef (for injection into managed beans) is delegated to the container. An integrator must provide an implementation of JaxwsInjectionServices. This service is not required if the implementation of Injection Services takes care of @WebServiceRef injection.

An integrator may wish to use InjectionServices to provide additional field or method injection over-and-above that provided by Weld. An integration into a Java EE environment may use InjectionServices to provide EE resource injection for managed beans.

InjectionServices provides a very simple contract, the InjectionServices.aroundInject(InjectionContext ic); interceptor will be called for every instance that CDI injects, whether it is a contextual instance, or a non-contextual instance injected by InjectionTarget.inject().

The InjectionContext can be used to discover additional information about the injection being performed, including the target being injected. ic.proceed() should be called to perform CDI-style injection, and call initializer methods.

In order to obtain the Principal representing the current caller identity, the container should provide an implementation of SecurityServices.

The org.jboss.weld.bootstrap.api.Bootstrap interface defines the initialization for Weld, bean deployment and bean validation. To boot Weld, you must create an instance of org.jboss.weld.bootstrap.WeldBootstrap which implements org.jboss.weld.bootstrap.api.CDI11Bootstrap which extends the above mentioned Bootstrap. Then you need to tell it about the services in use, and finally request the container start.

The bootstrap is split into phases, container initialization, bean deployment, bean validation and shutdown. Initialization will create a manager, and add the built-in contexts, and examine the deployment structure. Bean deployment will deploy any beans (defined using annotations, programmatically, or built in). Bean validation will validate all beans.

To initialize the container, you call Bootstrap.startInitialization(). Before calling startInitialization(), you must register any services required by the environment. You can do this by calling, for example, bootstrap.getManager().getServices().add(JpaServices.class, new MyJpaServices()).

Having called startInitialization(), the org.jboss.weld.manager.api.WeldManager for each BDA can be obtained by calling Bootstrap.getManager(BeanDeploymentArchive bda).

To deploy the discovered beans, call Bootstrap.deployBeans().

To validate the deployed beans, call Bootstrap.validateBeans().

To place the container into a state where it can service requests, call Bootstrap.endInitialization()

To shutdown the container you call Bootstrap.shutdown(). This allows the container to perform any cleanup operations needed.

Weld needs to load classes and resources from the classpath at various times. By default, they are loaded from the Thread Context ClassLoader if available, if not the same classloader that was used to load Weld, however this may not be correct for some environments. If this is case, you can implement org.jboss.weld.resources.spi.ResourceLoader.

Integrators with bytecode-scanning capabilities may implement an optional ClassFileServices service.

Bytecode-scanning is used by some application servers to speed up deployment. Compared to loading a class using ClassLoader, bytecode-scanning allows to obtain only a subset of the Java class file metadata (e.g. annotations, class hierarchy, etc.) which is usually loaded much faster. This allows the container to scan all classes initially by a bytecode scanner and then use this limited information to decide which classes need to be fully loaded using ClassLoader. Jandex is an example of a bytecode-scanning utility.

ClassFileServices may be used by an integrator to provide container’s bytecode-scanning capabilities to Weld. If present, Weld will try to use the service to avoid loading of classes that do not need to be loaded. These are classes that:

This usually yields improved bootstrap performance especially in large deployments with a lot of classes in explicit bean archives.

See the JavaDoc for more details.

The standard way for an integrator to provide Service implementations is via the deployment structure. Alternatively, services may be registered using the ServiceLoader mechanism. This is useful e.g. for a library running in weld-servlet environment. Such library may provide TransactionServices implementation which would not otherwise be provided by weld-servlet.

A service implementation should be listed in a file named META-INF/services/org.jboss.weld.bootstrap.api.Service

A service implementation can override another service implementation. The priority of a service implementation is determined from the javax.annotation.Priority annotation. Service implementations with higher priority have precedence. A service implementation that does not define priority explicitly is given implicit priority of 4500.

If you are integrating Weld into an environment that supports deployment of multiple applications, you must enable, automatically, or through user configuration, classloader isolation for each CDI application.

If you are integrating Weld into a Servlet environment you must register org.jboss.weld.servlet.WeldInitialListener and org.jboss.weld.servlet.WeldTerminalListener as Servlet listeners, either automatically, or through user configuration, for each CDI application which uses Servlet.

You must ensure that WeldInitialListener is called before any other application-defined listener is called and that WeldTerminalListener is called only after all application-defined listeners have been called.

You must ensure that WeldInitialListener.contextInitialized() is called after beans are deployed is complete (Bootstrap.deployBeans() has been called).

A CDI implementation is required to provide a Servlet filter named ``CDI Conversation Filter''. The filter may be mapped by an application in the web descriptor. That allows application to place another filter around the CDI filter for dealing with exceptions.

Weld provides this filter with a fully qualified class name of`org.jboss.weld.servlet.ConversationFilter`.

If the application contains a filter mapping for a filter named CDI Conversation Filter'', the integrator is required to register org.jboss.weld.servlet.ConversationFilter as a filter with CDI Conversation Filter'' as its filter name. If no such mapping exists in the application, the integrator is not required to register the filter. In that case, WeldInitialListener will take care of conversation context activation/deactivation at the beginning of HTTP request processing.

If you are integrating Weld into a JSF environment you must register org.jboss.weld.el.WeldELContextListener as an EL Context listener.

If you are integrating Weld into a JSF environment you must register org.jboss.weld.jsf.ConversationAwareViewHandler as a delegating view handler.

If you are integrating Weld into a JSF environment you must obtain the bean manager for the module and then call BeanManager.wrapExpressionFactory(), passing Application.getExpressionFactory() as the argument. The wrapped expression factory must be used in all EL expression evaluations performed by JSF in this web application.

If you are integrating Weld into a JSF environment you must obtain the bean manager for the module and then call BeanManager.getELResolver(), The returned EL resolver should be registered with JSF for this web application.

If you are integrating Weld into a JSF environment you must register org.jboss.weld.servlet.ConversationPropagationFilter as a Servlet listener, either automatically, or through user configuration, for each CDI application which uses JSF. This filter can be registered for all Servlet deployment safely.

If you are integrating Weld into a JSP environment you must register org.jboss.weld.el.WeldELContextListener as an EL Context listener.

If you are integrating Weld into a JSP environment you must obtain the bean manager for the module and then call BeanManager.wrapExpressionFactory(), passing Application.getExpressionFactory() as the argument. The wrapped expression factory must be used in all EL expression evaluations performed by JSP.

If you are integrating Weld into a JSP environment you must obtain the bean manager for the module and then call BeanManager.getELResolver(), The returned EL resolver should be registered with JSP for this web application.

org.jboss.weld.ejb.SessionBeanInterceptor takes care of activating the request scope around EJB method invocations in a non-servlet environment, such as message-driven bean invocation, @Asynchronous invocation or @Timeout. If you are integrating Weld into an EJB environment you must register the aroundInvoke method of SessionBeanInterceptor as a EJB around-invoke interceptor for all EJBs in the application, either automatically, or through user configuration, for each CDI application which uses enterprise beans.

If you are running in a EJB 3.2 environment, you should register this as an around-timeout interceptor as well.

In addition, since CDI 1.1 the aroundInvoke method of SessionBeanInterceptor should be invoked around @PostConstruct callbacks of EJBs.

Weld can reside on an isolated classloader, or on a shared classloader. If you choose to use an isolated classloader, the default SingletonProvider, IsolatedStaticSingletonProvider, can be used. If you choose to use a shared classloader, then you will need to choose another strategy.

You can provide your own implementation of Singleton and SingletonProvider and register it for use using SingletonProvider.initialize(SingletonProvider provider).

Weld also provides an implementation of Thread Context Classloader per application strategy, via the TCCLSingletonProvider.

You should bind the bean manager for the bean deployment archive into JNDI at java:comp/BeanManager. The type should be javax.enterprise.inject.spi.BeanManager. To obtain the correct bean manager for the bean deployment archive, you may call bootstrap.getBeanManager(beanDeploymentArchive)

CDI 1.1 provides a simplified approach to accessing the BeanManager / CDI container from components that do not support injection. This is done by the CDI class API. The integrating part can either use org.jboss.weld.AbstractCDI or org.jboss.weld.SimpleCDI provided by Weld core and register it using javax.enterprise.inject.spi.CDIProvider file that is visible to the CDI API classes or use the CDI.setCDIProvider(CDIProvider provider) method method early in the deployment.

Alternatively, an integrating part may provide a specialized implementation such as the one provided by WildFly integration.

The CDI specification requires the container to provide injection into non-contextual resources for all Java EE component classes. Weld delegates this responsibility to the container. This can be achieved using the CDI defined InjectionTarget SPI. Furthermore, you must perform this operation on the correct bean manager for the bean deployment archive containing the EE component class.

The CDI specification also requires that a ProcessInjectionTarget event is fired for every Java EE component class. Furthermore, if an observer calls ProcessInjectionTarget.setInjectionTarget() the container must use the specified injection target to perform injection.

To help the integrator, Weld provides WeldManager.fireProcessInjectionTarget() which returns the InjectionTarget to use.

The container may intersperse other operations between these calls. Further, the integrator may choose to implement any of these calls in another manner, assuming the contract is fulfilled.

When performing injections on EJBs you must use the Weld-defined SPI, WeldManager. Furthermore, you must perform this operation on the correct bean manager for the bean deployment archive containing the EJB.

Weld implements support for constructor call interception and invokes interceptors that are associated with the particular component either using an interceptor binding or the @Interceptors annotation.

This can be suppressed by calling WeldCreationalContext.setConstructorInterceptionSuppressed(true)

In addition, an integrator may register a callback in which it performs additional operations around the constructor call. This way an integrator may for example implement support for additional interceptors (e.g. those bound using the deployment descriptor).

See AroundConstructCallback and WeldCreationalContext.registerAroundConstructCallback() for more details.

Optionally, an integrator may register the following Probe Development Tool components in order to enable its functionality. Note that these components should only be registered if the development mode is enabled - see also How to enable the development mode .

Weld can perfom additional cleanup operations after bootstrap, in order to conserve resources. See for example Memory consumption optimization - removing unused beans .

However, this feature is disabled by default. An integrator may enable this feature provided the following requirements are met:

All the changes are documented in this external migration document.

Weld 3.0 implements CDI 2.0 so this is a huge update which contains bunch of new features. However, this document only covers part which might prove problematic while moving existing application from Weld 2.4 to Weld 3.0. For more information on the CDI 2.0 itself, please consult the specification.