SeamFramework.orgCommunity Documentation
Currently Web Beans only runs in JBoss AS 5; integrating the RI into other EE environments (for example another application server like Glassfish), into a servlet container (like Tomcat), or with an Embedded EJB3.1 implementation is fairly easy. In this Appendix we will briefly discuss the steps needed.
The Web Beans SPI is located in the webbeans-spi
module, and packaged as webbeans-spi.jar. Some
SPIs are optional, if you need to override the default behavior,
others are required.
All interfaces in the SPI support the decorator pattern and provide a
Forwarding class located in the
helpers sub package. Additional, commonly used,
utility classes, and standard implementations are also located in the
helpers sub package.
/**
* Gets list of all classes in classpath archives with META-INF/beans.xml (or
* for WARs WEB-INF/beans.xml) files
*
* @return An iterable over the classes
*/
public Iterable<Class<?>> discoverWebBeanClasses();
/**
* Gets a list of all deployment descriptors in the app classpath
*
* @return An iterable over the beans.xml files
*/
public Iterable<URL> discoverWebBeansXml();
The discovery of Web Bean classes and beans.xml
files is self-explanatory (the algorithm is described in Section 11.1
of the JSR-299 specification, and isn't repeated here).
Web Beans will run without an EJB container; in this case you don't need to implement the EJB SPI.
Web Beans also delegates EJB3 bean discovery to the container
so that it doesn't have to scan for EJB3 annotations or parse
ejb-jar.xml. For each EJB in the application an
EJBDescriptor should be discovered:
public interface EjbDescriptor<T>
{
/**
* Gets the EJB type
*
* @return The EJB Bean class
*/
public Class<T> getType();
/**
* Gets the local business interfaces of the EJB
*
* @return An iterator over the local business interfaces
*/
public Iterable<BusinessInterfaceDescriptor<?>> getLocalBusinessInterfaces();
/**
* Gets the remote business interfaces of the EJB
*
* @return An iterator over the remote business interfaces
*/
public Iterable<BusinessInterfaceDescriptor<?>> getRemoteBusinessInterfaces();
/**
* Get the remove methods of the EJB
*
* @return An iterator over the remove methods
*/
public Iterable<Method> getRemoveMethods();
/**
* Indicates if the bean is stateless
*
* @return True if stateless, false otherwise
*/
public boolean isStateless();
/**
* Indicates if the bean is a EJB 3.1 Singleton
*
* @return True if the bean is a singleton, false otherwise
*/
public boolean isSingleton();
/**
* Indicates if the EJB is stateful
*
* @return True if the bean is stateful, false otherwise
*/
public boolean isStateful();
/**
* Indicates if the EJB is and MDB
*
* @return True if the bean is an MDB, false otherwise
*/
public boolean isMessageDriven();
/**
* Gets the EJB name
*
* @return The name
*/
public String getEjbName();
The EjbDescriptor is fairly self-explanatory,
and should return the relevant metadata as defined in the EJB
specification. In addition to these two interfaces, there is
BusinessInterfaceDescriptor which represents a
local business interface (encapsulating the interface class and
jndi name used to look up an instance of the EJB).
The resolution of @EJB (for injection into simple
beans), the resolution of local EJBs (for backing session beans) and
remote EJBs (for injection as a Java EE resource) is delegated to
the container. You must provide an implementation of
org.jboss.webbeans.ejb.spi.EjbServices which
provides these operations. For resolving the @EJB
injection point, Web Beans will provide the
InjectionPoint; for resolving local EJBs, the
EjbDescriptor will be provided, and for remote
EJBs the jndiName, mappedName,
or ejbLink will be provided.
When resolving local EJBs (used to back session beans) a wrapper
(SessionObjectReference) around the EJB reference
is returned. This wrapper allows Web Beans to request a reference
that implements the given business interface, and, in the case of
SFSBs, request the removal of the EJB from the container.
Just as EJB resolution is delegated to the container, resolution of
@PersistenceContext for injection into simple
beans (with the InjectionPoint provided),
and resolution of persistence contexts and persistence units (with
the unitName provided) for injection as a Java EE
resource is delegated to the container.
To allow JPA integration, the JpaServices
interface should be implemented.
Web Beans also needs to know what entities are in a deployment (so
that they aren't managed by Web Beans). An implementation that
detects entities through @Entity and
orm.xml is provided by default. If you want to
provide support for a entities defined by a JPA provider (such as
Hibernate's .hbm.xml you can wrap or replace the
default implementation.
EntityDiscovery delegate = bootstrap.getServices().get(EntityDiscovery.class);
Web Beans must delegate JTA activities to the container. The SPI
provides a couple hooks to easily achieve this with the
TransactionServices interface.
public interface TransactionServices
{
/**
* Possible status conditions for a transaction. This can be used by SPI
* providers to keep track for which status an observer is used.
*/
public static enum Status
{
ALL, SUCCESS, FAILURE
}
/**
* Registers a synchronization object with the currently executing
* transaction.
*
* @see javax.transaction.Synchronization
* @param synchronizedObserver
*/
public void registerSynchronization(Synchronization synchronizedObserver);
/**
* Queries the status of the current execution to see if a transaction is
* currently active.
*
* @return true if a transaction is active
*/
public boolean isTransactionActive();
}
The enumeration Status is a convenience for
implementors to be able to keep track of whether a synchronization
is supposed to notify an observer only when the transaction is
successful, or after a failure, or regardless of the status of the
transaction.
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.
A number of JMS operations are not container specific, and so should
be provided via the SPI JmsServices.
JMS does not specify how to obtain a
ConnectionFactory so the SPI provides a method
which should be used to look up a factory. Web Beans also delegates
Destination lookup to the container via the SPI.
The resolution of @Resource (for injection into simple
beans) and the resolution of resources (for injection as a Java EE
resource) is delegated to the container. You must provide an
implementation of ResourceServices which
provides these operations. For resolving the
@Resource injection, Web Beans will provide the
InjectionPoint; and for Java EE resources, the
jndiName or mappedName will be
provided.
The resolution of web service references (for injection as a Java EE
resource) is delegated to the container. You must provide an
implementation of WebServices whichprovides this
operation. For resolving the Java EE resource, the
jndiName or mappedName will be
provided.
Web Beans uses a map like structure to store bean instances -
org.jboss.webbeans.context.api.BeanStore. You may
find
org.jboss.webbeans.context.api.helpers.ConcurrentHashMapBeanStore
useful.
Web Beans expects the Application Server or other container to
provide the storage for each application's context. The
org.jboss.webbeans.context.api.BeanStore should
be implemented to provide an application scoped storage.
The org.jboss.webbeans.bootstrap.api.Bootstrap
interface defines the bootstrap for Web Beans. To boot Web Beans,
you must obtain an instance of
org.jboss.webbeans.bootstrap.WebBeansBootstrap
(which implements Boostrap), tell it about the
SPIs in use, and then request the container start.
The bootstrap is split into phases, bootstrap initialization and boot and shutdown. Initialization will create a manager, and add the standard (specification defined) contexts. Bootstrap will discover EJBs, classes and XML; add beans defined using annotations; add beans defined using XML; and validate all beans.
The bootstrap supports multiple environments. An environment is
defined by an implementation of the Environment
interface. A number of standard envrionments are built in as the
enumeration Environments. Different environments
require different services to be present (for example servlet
doesn't require transaction, EJB or JPA services). By default an
EE environment is assumed, but you can adjust the environment by
calling bootstrap.setEnvironment().
Web Beans uses a generic-typed service registry to allow services to
be registered. All services implement the Service
interface. The service registry allows services to be added and
retrieved.
To initialize the bootstrap you call
Bootstrap.initialize(). Before calling
initialize(), you must register any services
required by your environment. You can do this by calling
bootstrap.getServices().add(JpaServices.class, new MyJpaServices()).
You must also provide the application context bean store.
Having called initialize(), the
Manager can be obtained by calling
Bootstrap.getManager().
To boot the container you call Bootstrap.boot().
To shutdown the container you call
Bootstrap.shutdown() or
webBeansManager.shutdown(). This allows the
container to perform any cleanup operations needed.
Web Beans delegates all JNDI operations to the container through the SPI.
A number of the SPI interface require JNDI lookup, and the class
AbstractResourceServices provides JNDI/Java EE
spec compliant lookup methods.
Web Beans 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 Web Beans, however this may not be correct for some
environments. If this is case, you can implement
org.jboss.webbeans.spi.ResourceLoader:
public interface ResourceLoader {
/**
* Creates a class from a given FQCN
*
* @param name The name of the clsas
* @return The class
*/
public Class<?> classForName(String name);
/**
* Gets a resource as a URL by name
*
* @param name The name of the resource
* @return An URL to the resource
*/
public URL getResource(String name);
/**
* Gets resources as URLs by name
*
* @param name The name of the resource
* @return An iterable reference to the URLS
*/
public Iterable<URL> getResources(String name);
}
Java EE / Servlet does not provide any hooks which can be used to provide injection into Servlets, so Web Beans provides an API to allow the container to request JSR-299 injection for a Servlet.
To be compliant with JSR-299, the container should request servlet injection for each newly instantiated servlet after the constructor returns and before the servlet is placed into service.
To perform injection on a servlet call
WebBeansManager.injectServlet(). The manager
can be obtained from Bootstrap.getManager().
There are a number of requirements that the Web Beans RI places on the container for correct functioning that fall outside implementation of APIs
If you are integrating the Web Beans RI into an environment that supports deployment of multiple applications, you must enable, automatically, or through user configuation, classloader isolation for each Web Beans application.
If you are integrating the Web Beans into a Servlet
environment you must register
org.jboss.webbeans.servlet.WebBeansListener
as a Servlet listener, either automatically, or through user
configuration, for each Web Beans application which uses
Servlet.
If you are integrating the Web Beans into a JSF
environment you must register
org.jboss.webbeans.jsf.WebBeansPhaseListener
as a phase listener, and
org.jboss.webbeans.el.WebBeansELREsolver as
an EL resolver, either automatically, or through user
configuration, for each Web Beans application which uses
JSF.
If you are integrating the Web Beans into a JSF environment
you must register
org.jboss.webbeans.servlet.ConversationPropagationFilter
as a Servlet listener, either automatically, or through user
configuration, for each Web Beans application which uses
JSF. This filter can be registered for all Servlet deployment
safely.
Web Beans only supports JSF 1.2 and above.
If you are integrating the Web Beans into an EJB
environment you must register
org.jboss.webbeans.ejb.SessionBeanInterceptor
as a EJB interceptor for all EJBs in the application, either
automatically, or through user configuration, for each Web
Beans application which uses enterprise beans.
You must register the SessionBeanInterceptor
as the inner most interceptor in the stack for all EJBs.
webbeans-core.jar
If you are integrating the Web Beans into an environment that
supports deployment of applications, you must insert the
webbeans-core.jar into the applications
isolated classloader. It cannot be loaded from a shared
classloader.
You should bind a Reference to the Manager
ObjectFactory into JNDI at
java:app/Manager. The type should be
javax.inject.manager.Manager and the
factory class is
org.jboss.webbeans.resources.ManagerObjectFactory