Application servers and environments supported by Weld
Using Weld with JBoss AS If you are using JBoss AS 6.0, no additional configuration is required to use Weld (or CDI for that matter). All you need to do is make your application a bean bean archive by adding META-INF/beans.xml to the classpath or WEB-INF/beans.xml to the web root! Unfortunately, you can't use Weld with earlier versions of JBoss AS since they are missing key libraries. If you want to learn how to upgrade the built-in support on JBoss AS 6.0, then read on. Upgrading the Weld add-on is easy. The Weld distribution has a build that can take care of this task for you in a single command. First, we need to tell Weld where JBoss AS is located. Create a new file named local.build.properties in the examples directory of the Weld distribution and assign the path of your JBoss AS installation to the property key jboss.home, as follows: Now we can install the Weld deployer from the jboss-as directory of the Weld distribution: $> cd jboss-as $> ant update A new deployer, weld.deployer is added to JBoss AS. This adds supports for JSR-299 deployments to JBoss AS, and allows Weld to query the EJB 3 container and discover which EJBs are installed in your application. It also performs an upgrade of the Javassist library, if necessary.
GlassFish Weld is also built into GlassFish from V3 onwards. Since GlassFish V3 is the Java EE 6 reference implementation, it must support all features of CDI. What better way for GlassFish to support these features than to use Weld, the JSR-299 reference implementation? Just package up your CDI application and deploy.
Servlet containers (such as Tomcat or Jetty) While JSR-299 does not require support for servlet environments, Weld can be used in any servlet container, such as Tomcat 6.0 or Jetty 6.1. There is a major limitation to using a servlet container. Weld doesn't support deploying session beans, injection using @EJB or @PersistenceContext, or using transactional events in servlet containers. For enterprise features such as these, you should really be looking at a Java EE application server. Weld should be used as a web application library in a servlet container. You should place weld-servlet.jar in WEB-INF/lib in the web root. weld-servlet.jar is an "uber-jar", meaning it bundles all the bits of Weld and CDI required for running in a servlet container, provided for your convenience. Alternatively, you could use its component jars: jsr299-api.jar weld-api.jar weld-spi.jar weld-core.jar weld-logging.jar weld-servlet-int.jar javassist.jar dom4j.jar google-collections.jar You also need to explicitly specify the servlet listener (used to boot Weld, and control its interaction with requests) in WEB-INF/web.xml in the web root: org.jboss.weld.environment.servlet.Listener ]]>
Tomcat Tomcat has a read-only JNDI, so Weld can't automatically bind the BeanManager extension SPI. To bind the BeanManager into JNDI, you should populate META-INF/context.xml in the web root with the following contents: ]]> and make it available to your deployment by adding this to the bottom of web.xml: BeanManager javax.enterprise.inject.spi.BeanManager ]]> Tomcat only allows you to bind entries to java:comp/env, so the BeanManager will be available at java:comp/env/BeanManager Weld also supports Servlet injection in Tomcat. To enable this, place the weld-tomcat-support.jar in $TOMCAT_HOME/lib, and add the following to META-INF/context.xml: ]]>
Jetty Like Tomcat, Jetty has a read-only JNDI, so Weld can't automatically bind the Manager. To bind the Manager to JNDI, you should populate WEB-INF/jetty-env.xml with the following contents: BeanManager javax.enterprise.inject.spi.BeanManager org.jboss.weld.resources.ManagerObjectFactory ]]> Notice that Jetty doesn't not have built-in support for an javax.naming.spi.ObjectFactory like Tomcat, so it's necessary to manually create the javax.naming.Reference to wrap around it. Jetty only allows you to bind entries to java:comp/env, so the BeanManager will be available at java:comp/env/BeanManager Weld does not currently support Servlet injection in Jetty.
Java SE In addition to improved integration of the Enterprise Java stack, the "Contexts and Dependency Injection for the Java EE platform" specification also defines a state of the art typesafe, stateful dependency injection framework, which can prove useful in a wide range of application types. To help developers take advantage of this, Weld provides a simple means for being executed in the Java Standard Edition (SE) environment independently of any Java EE APIs. When executing in the SE environment the following features of Weld are available: Managed beans with @PostConstruct and @PreDestroy lifecycle callbacks Dependency injection with qualifiers and alternatives @Application, @Dependent and @Singleton scopes Interceptors and decorators Stereotypes Events Portable extension support EJB beans are not supported.
CDI SE Module 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: params;]]> The second form is useful for compatibility with existing classes. The command line parameters do not become available for injection until the ContainerInitialized event is fired. If you need access to the parameters during initialization you can do so via the public static String[] getParameters() method in StartMain. Here's an example of a simple CDI SE application: parameters) { System.out.println("Hello " + parameters.get(0)); } }]]>
Bootstrapping CDI SE CDI SE applications can be bootstrapped in the following ways.
The ContainerInitialized Event Thanks to the power of CDI's typesafe event model, application developers need not write any bootstrapping code. The Weld SE module comes with a built-in main method which will bootstrap CDI for you and then fire a ContainerInitialized event. The entry point for your application code would therefore be a simple bean which observes the ContainerInitialized event, as in the previous example. In this case your application can be started by calling the provided main method like so: ]]>
Programatic Bootstrap API For added flexibility, CDI SE also comes with a bootstrap API which can be called from within your application in order to initialize CDI and obtain references to your application's beans and events. The API consists of two classes: Weld and WeldContainer. instance() {...} /** Provides access to all events within the application. */ public Event event() {...} /** Provides direct access to the BeanManager. */ public BeanManager getBeanManager() {...} }]]> Here's an example application main method which uses this API to initialize a bean of type MyApplicationBean. Alternatively the application could be started by firing a custom event which would then be observed by another simple bean. The following example fires MyEvent on startup.
Thread Context 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. org.jboss.weld.environment.se.threading.RunnableDecorator ]]> It is not necessary to use @ThreadScoped in all multithreaded applications. The thread context is not intended as a replacement for defining your own application-specific contexts. It is generally only useful in situtations where you would otherwise have used ThreadLocal directly, which are typically rare.
Setting the Classpath Weld SE comes packaged as a 'shaded' jar which includes the CDI API, Weld Core and all dependant classes bundled into a single jar. Therefore the only Weld jar you need on the classpath, in addition to your application's classes and dependant jars, is the Weld SE jar.