SeamFramework.orgCommunity Documentation
If you are using JBoss AS 5.2, 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 5.2, 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:
jboss.home=/path/to/jboss-as-5.x
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.
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.
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:
<listener>
<listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
</listener>
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:
<Context>
<Resource name="BeanManager"
auth="Container"
type="javax.enterprise.inject.spi.BeanManager"
factory="org.jboss.weld.resources.ManagerObjectFactory"/>
</Context>
and make it available to your deployment by adding this to the bottom of web.xml:
<resource-env-ref>
<resource-env-ref-name>BeanManager</resource-env-ref-name>
<resource-env-ref-type>
javax.enterprise.inject.spi.BeanManager
</resource-env-ref-type>
</resource-env-ref>
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:
<Listener className="org.jboss.weld.environment.tomcat.WeldLifecycleListener"/>
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:
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN"
"http://jetty.mortbay.org/configure.dtd">
<Configure id="webAppCtx" class="org.mortbay.jetty.webapp.WebAppContext">
<New id="BeanManager" class="org.mortbay.jetty.plus.naming.Resource">
<Arg><Ref id="webAppCtx"/></Arg>
<Arg>BeanManager</Arg>
<Arg>
<New class="javax.naming.Reference">
<Arg>javax.enterprise.inject.spi.BeanManager</Arg>
<Arg>org.jboss.weld.resources.ManagerObjectFactory</Arg>
<Arg/>
</New>
</Arg>
</New>
</Configure>
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.
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:
POJOs (no EJBs)
Typesafe Dependency Injection
Application and Dependent Contexts
Qualifiers
Stereotypes
Typesafe Event Model
Weld provides an extension which will boot a CDI bean manager in Java SE, automatically registering all
simple beans found on the classpath. Application developers need not write any bootstrapping code. The entry
point for application code is a simple bean which observes the special
ContainerInitialized event provided by this extension. The command line parameters can be
injected using either of the following:
@Inject @Parameters List<String> params;
@Inject @Parameters String[] paramsArray; // useful for compatability with existing classes
Here's an example of a simple CDI SE application:
@ApplicationScoped
public class HelloWorld
{
@Inject @Parameters List<String> parameters;
public void printHello(@Observes ContainerInitialized event) {
System.out.println("Hello " + parameters.get(0));
}
}
CDI SE applications can be bootstrapped by running the StartMain class like so:
java org.jboss.weld.environments.se.StartMain <args>
If you need to do any custom initialization of the CDI bean manager, for example registering custom contexts
or initializing resources for your beans you can do so in response to the
AfterBeanDiscovery or AfterDeploymentValidation events. The following
example registers a custom context:
public class PerformSetup {
public void setup(@Observes AfterBeanDiscovery event) {
event.addContext( ThreadContext.INSTANCE );
}
}
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.