A top-level Java class is a simple Web Bean if it meets the following conditions:

All Java classes that meet these conditions are simple Web Beans and thus no special declaration is required to define a simple Web Bean. Additional simple Web Beans for the class may be defined using XML, by specifying the class in web-beans.xml.

The set of API types for a simple Web Bean contains the implementation class, every superclass and all interfaces it implements directly or indirectly.

Note the additional restrictions upon API types of Web Beans with normal scope types defined in Section 4.4.1, “Unproxyable API types”.

A simple Web Bean with a constructor that takes no parameters does not require any special annotations. The following classes are Web Beans:

public class Shop { .. }

class PaymentProcessorImpl implements PaymentProcessor { ... }

An implementation class may also specify a scope type, name, deployment type, stereotypes and/or binding annotations:

@ConversationScoped @Current
public class ShoppingCart { ... }

A simple Web Bean may extend another simple Web Bean:

@Named("loginAction")
public class LoginAction { ... }

@Mock
@Named("loginAction")
public class MockLoginAction extends LoginAction { ... }

The second Web Bean is a "mock object" that overrides the implementation of LoginAction when running in an embedded EJB Lite based integration testing environment.

Simple Web Beans may be declared in web-beans.xml using the implementation class name.

<myapp:Order>
    <deployment:Staging/>
    <ConversationScoped/>
    ...
</myapp:Order>

A simple Web Bean declared using XML must explicitly declare all producer, disposal and observer methods in XML. Any annotations of the implementation class that define producer, disposal or observer methods are ignored.

A simple Web Bean may even be declared at any injection point declared in XML, as defined in Section 9.6, “Inline Web Bean declarations”, in which case no binding types are specified.

If the implementation class of a simple Web Bean defined in XML is a parameterized type or a non-static inner class, a DefinitionException is thrown by the Web Bean manager at initialization time.

If the implementation class of a simple Web Bean defined in XML is an abstract class, and the simple Web Bean is not a Web Beans decorator, a DefinitionException is thrown by the Web Bean manager at initialization time.

If the implementation class of a simple Web Bean defined in XML is annotated @Interceptor, then the Web Bean must be explicitly declared as an interceptor in XML, as defined in Section 6.2.5.2, “Declaring a Web Beans interceptor using XML”. If a simple Web Bean defined in XML has an implementation class annotated @Interceptor and is not declared as an interceptor in XML, a DefinitionExceptionis thrown by the Web Bean manager at initialization time.

If the implementation class of a simple Web Bean defined in XML is annotated @Decorator, then the Web Bean must be explicitly declared as a decorator in XML, as defined in Section 6.3.2, “Declaring a decorator using XML”. If a simple Web Bean defined in XML has an implementation class annotated @Decorator and is not declared as a decorator in XML, a DefinitionException is thrown by the Web Bean manager at initialization time.

When the Web Bean manager instantiates a simple Web Bean, it calls the Web Bean constructor.

The application may call Web Bean constructors directly. However, if the application directly instantiates the Web Bean, no parameters are passed to the constructor by the Web Bean manager; the returned object is not bound to any context; no dependencies are injected by the Web Bean manager; and the lifecycle of the new instance is not managed by the Web Bean manager.

@SessionScoped
public class ShoppingCart {

   private User customer;
   
   @Initializer
   public ShoppingCart(User customer) {
       this.customer = customer;
   }
   
   public ShoppingCart(ShoppingCart original) {
       this.customer = original.customer;
   }
   
   ShoppingCart() {}
   
   ...

}

@ConversationScoped
public class Order {

   private Product product;
   private User customer;

   @Initializer
   public Order(@Selected Product product, User customer) {
       this.product = product;
       this.customer = customer;
   }
   
   public Order(Order original) {
       this.product = original.product;
       this.customer = original.customer;
   }
   
   Order() {}
   
   ...

}

<myapp:ShoppingCart>
    <ConversationScoped/>
    <myapp:User/>
</myapp:ShoppingCart>

<myapp:Order>
    <ConversationScoped/>
    <myapp:Product>
        <Selected/>
    </myapp:Product>
    <myapp:User/>
</myapp:Order>

If an implementation class of a simple Web Bean X defined using annotations is annotated @Specializes, then the implementation class of X must directly extend the implementation class of another simple Web Bean Y defined using annotations. Then:

We say that X directly specializes Y, and we can be certain that Y will never be instantiated or called by the Web Bean manager if X is enabled.

If the implementation class of X does not directly extend the implementation class of another simple Web Bean, a DefinitionException is thrown by the Web Bean manager at initialization time.

For example, MockLoginAction directly specializes LoginAction:

public class LoginAction { ... }

@Mock @Specializes
public class MockLoginAction extends LoginAction { ... }

If a simple Web Bean X defined in XML declares the <Specializes> element, then the implementation class of X must be the implementation class of another simple Web Bean Y defined using annotations. Then:

We say that X directly specializes Y, and we can be certain that Y will never be instantiated or called by the Web Bean manager if X is enabled.

The default name for a simple Web Bean is the unqualified class name of the Web Bean implementation class, after converting the first character to lower case.

For example, if the implementation class is named ProductList, the default Web Bean name is productList.

All EJB 3 style session and singleton beans declared via an EJB component defining annotation on the EJB bean class are Web Beans, and thus no special declaration is required. Additional enterprise Web Beans for these EJBs may be defined using XML, by specifying the bean class in web-beans.xml.

All EJB 3 style session and singleton beans declared in ejb-jar.xml are also Web Beans. Additional enterprise Web Beans for these EJBs may be defined using XML, by specifying the bean class and EJB name in web-beans.xml.

However, when a plugin Web Bean manager is used in a Java EE 5 environment, support for injection of enterprise Web Beans that implement multiple local interfaces and have any scope other than @Dependent is not required.

The set of API types for an enterprise Web Bean contains all local interfaces of the bean that do not have wildcard type parameters or type variables and their superinterfaces. If the EJB bean has a bean class local view and the bean class is not a parameterized type, the set of API types contains the bean class and all superclasses. In addition, java.lang.Object is an API type of every enterprise Web Bean.

Remote interfaces are not included in the set of API types.

An enterprise Web Bean does not require any special annotations. The following EJBs are Web Beans:

@Singleton
class Shop { .. }

@Stateless
class PaymentProcessorImpl implements PaymentProcessor { ... }

An implementation class may also specify a scope type, name, deployment type, stereotypes and/or binding annotations:

@ConversationScoped @Stateful @Current @Model
public class ShoppingCart { ... }

An enterprise Web Bean implementation class may extend another Web Bean implementation class:

@Stateless
@Named("loginAction")
public class LoginActionImpl implements LoginAction { ... }

@Stateless
@Mock
@Named("loginAction")
public class MockLoginActionImpl extends LoginActionImpl { ... }

Enterprise Web Beans may be declared in web-beans.xml using the bean class name (for EJBs defined using a component-defining annotation) or bean class and EJB name (for EJBs defined in ejb-jar.xml).

<myapp:OrderBean>
    <deployment:Staging/>
    <ConversationScoped/>
    ...
</myapp:OrderBean>

<myapp:OrderBean ejbName="RushOrder">
    <myapp:Rush/>
    <ConversationScoped/>
    ...
</myapp:OrderBean>

The ejbName attribute declares the EJB name of an EJB defined in ejb-jar.xml.

An enterprise Web Bean declared using XML must explicitly declare all producer, disposal and observer methods in XML. Any annotations of the implementation class that define producer, disposal or observer methods are ignored.

Enterprise Web Beans declared in XML may not be singleton beans. If an enterprise Web Bean declared in XML is a singleton bean, a DefinitionException is thrown by the Web Bean manager at initialization time.

Enterprise Web Beans may not be message-driven beans. If an enterprise Web Bean declared in XML is a message-driven bean, a DefinitionException is thrown by the Web Bean manager at initialization time.

When the Web Bean manager destroys an enterprise Web Bean instance that is an EJB stateful session bean, it calls the Web Bean remove method.

If an enterprise Web Bean that is a stateful session bean does not have a Web Bean remove method, it must be scoped @Dependent and the application must explicitly destroy every instance of the Web Bean by calling an EJB remove method before the Web Bean manager attempts to destroy the instance as specified by Section 8.3.4, “Dependent object destruction”.

If an enterprise Web Bean that is a stateful session bean and does not have a Web Bean remove method declares any scope other than @Dependent, a DefinitionException is thrown by the Web Bean manager at initialization time.

If an instance of an enterprise Web Bean that is a stateful session bean and does not have a Web Bean remove method is not explicitly destroyed by the application before the Web Bean manager attempts to destroy the instance, an UnremovedException is thrown by the Web Bean manager, as defined in Section 5.4, “Lifecycle of stateful session enterprise Web beans”.

The application may call any EJB remove method, at any time, but then no parameters will be passed to the method by the Web Bean manager. However, whenever any remove method of a Web Bean instance is called by the application, the Web Bean manager must remove the instance from the context with which it is associated.

Open issue: what restrictions exist upon invoking dependencies from the remove method?

@ConversationScoped @Stateful
public class Order {

   @Destructor @Remove
   public remove(Log log)
   {
       ...
   }

}

<myapp:Order>
    <ConversationScoped/>
    
    <myapp:remove>
        <Destructor/>
        <myfwk:Log/>
    </myapp:remove>
    
</myapp:ShoppingCart>

If an implementation class of an enterprise Web Bean X defined using annotations is annotated @Specializes, then the implementation class of X must directly extend the implementation class of another enterprise Web Bean Y defined using annotations. Then:

Furthermore:

Otherwise, a DefinitionException is thrown by the Web Bean manager at initialization time.

We say that X directly specializes Y, and we can be certain that Y will never be instantiated or called by the Web Bean manager if X is enabled.

If the implementation class of X does not directly extend the implementation class of another enterprise Web Bean, a DefinitionException is thrown by the Web Bean manager at initialization time.

For example, MockLoginActionBean directly specializes LoginActionBean:

@Stateless
public class LoginActionBean implements LoginAction { ... }

@Stateless @Mock @Specializes
public class MockLoginActionBean extends LoginActionBean { ... }

If an enterprise Web Bean X defined in XML declares the <Specializes> element, then the implementation class of X must be the implementation class of another enterprise Web Bean Y defined using annotations. Then:

We say that X directly specializes Y, and we can be certain that Y will never be instantiated or called by the Web Bean manager if X is enabled.

The default name for an enterprise Web Bean is the unqualified class name of the Web Bean implementation class, after converting the first character to lower case.

For example, if the bean class is named ProductList, the default Web Bean name is productList.

EJB local object references do not implement all local interfaces of the EJB. A local object reference may not be typecast to different local interface type, as required by Section 2.2, “Web Bean API types”. Therefore, the Web Bean manager proxies the local object reference. An enterprise bean proxy implements all local interfaces of the EJB.

When the proxy object is invoked, the proxy obtains the appropriate EJB local object reference from JNDI or using internal container APIs, and delegates the invocation to the local object reference. In either case, the Web Bean manager should follow the procedure defined in Section 10.3, “EJB lookup”.

When an enterprise Web Bean is invoked via the enterprise bean proxy, the interface returned by SessionContext.getInvokedBusinessInterface() will be specific to the Web Bean manager implementation. Portable applications should not rely upon the interface returned by this method.

The API types of a producer method depend upon the method return type:

Note the additional restrictions upon API types of Web Beans with normal scope types defined in Section 4.4.1, “Unproxyable API types”.

A producer method may be declared by annotating a method with the @Produces annotation.

public class Shop {

   @Produces PaymentProcessor getPaymentProcessor() { ... }

   @Produces List<Product> getProducts() { ... }

}

A producer method may also specify scope, name, deployment type, stereotypes and/or binding annotations.

public class Shop {

   @Produces @ApplicationScoped @Catalog @Named("catalog") 
   List<Product> getProducts() { ... }

}

If a producer method is annotated @Initializer or @Destructor, has a parameter annotated @Disposes, or has a parameter annotated @Observes, a DefinitionException is thrown by the Web Bean manager at initialization time.

For a Web Beans defined in XML, a producer method may be declared using the method name, the <Produces> element, the return type, and the parameter types of the method:

<myapp:Shop>
       
    <myapp:getProducts>
        <Produces>
            <ApplicationScoped/>
            <util:List>
                <myapp:Product/>
                <myapp:Catalog/>
            </util:List>
            <Named>catalog</Named>
        </Produces>
    </myapp:getProducts>
    
</myapp:Shop>

When a producer method is declared in XML, the Web Bean manager ignores binding annotations applied to the Java method or method parameters.

If the implementation class of a Web Bean declared in XML does not have a method with the name and parameter types declared in XML, a NonexistentMethodException is thrown by the Web Bean manager at initialization time.

If the producer method has parameters, the Web Bean manager calls Manager.getInstanceByType() to determine a value for each parameter and calls the producer method with those parameter values.

public class OrderFactory {

   @Produces @ConversationScoped
   public Order createCurrentOrder(@New Order order, @Selected Product product)
   {
       order.setProduct(product);
       return order;
   }

}

<myapp:OrderFactory>
       
    <myapp:createCurrentOrder>
        
        <Produces>
            <ConversationScoped/>
            <myapp:Order/>
        </Produces>
        
        <myapp:Order>
            <New/>
        </myapp:Order>
        
        <myapp:Product>
            <myapp:Selected/>
        </myapp:Product>
        
    </myapp:createCurrentOrder>
    
</myapp:OrderFactory>

If a producer method X is annotated @Specializes, then it must directly override another producer method Y. Then:

We say that X directly specializes Y, and we can be certain that Y will never be called by the Web Bean manager if X is enabled.

If the method does not directly override another producer method, a DefinitionException is thrown by the Web Bean manager at initialization time.

For example:

@Mock
public class MockShop extends Shop {

   @Override @Specializes
   @Produces 
   PaymentProcessor getPaymentProcessor() { 
      return new MockPaymentProcessor(); 
   }

   @Override @Specializes
   @Produces 
   List<Product> getProducts() {
      return PRODUCTS;
   }
   
   ...

}

A disposal method allows the application to perform customized cleanup of an object returned by a producer method.

A disposal method must be a non-static method of a simple Web Bean implementation class or enterprise Web Bean implementation class. If the Web Bean is an enterprise Web Bean, the disposal method must be a business method of the EJB.

A Web Bean may declare multiple disposal methods.

Each disposal method must have exactly one disposed parameter, of the same type as the corresponding producer method return type. When searching for disposal methods for a producer method, the Web Bean manager considers the type and binding types of the disposed parameter. If a disposed parameter resolves to a producer method according to the typesafe resolution algorithm, the Web Bean manager must call this method when destroying an instance returned by that producer method.

If the disposed parameter does not resolve to any producer method according to the typesafe resolution algorithm, an UnsatisfiedDependencyException is thrown by the Web Bean manager at initialization time.

A disposal method may be declared using annotations by annotating a parameter @Disposes. That parameter is the disposed parameter.

public class UserDatabaseEntityManager {

    @Produces @ConversationScoped @UserDatabase
    public EntityManager create(EntityManagerFactory emf) {
        return emf.createEntityManager();
    }
    
    public void close(@Disposes @UserDatabase EntityManager em) {
        em.close();
    }

}

If a method has more than one parameter annotated @Disposes, a DefinitionException is thrown by the Web Bean manager.

If a disposal method is annotated @Produces, @Initializer or @Destructor, or has a parameter annotated @Observes, a DefinitionException is thrown by the Web Bean manager at initialization time.

For a Web Beans defined in XML, a disposal method may be declared using the method name, the <Disposes> element, and the parameter types of the method:

<myfwk:UserDatabaseEntityManager>
       
    <myfwk:create>
        <Produces>
            <ConversationScoped/>
            <jpa:EntityManager>
                <myapp:UserDatabase/>
            </jpa:EntityManager>
        </Produces>
        <jpa:EntityManagerFactory/>
    </myfwk:create>
    
    <myfwk:close>
        <Disposes>
            <jpa:EntityManager>
                <myapp:UserDatabase/>
            </jpa:EntityManager>
        </Disposes>
    </myfwk:close>
    
</mmyfwk:UserDatabaseEntityManager>

When a disposal method is declared in XML, the Web Bean manager ignores binding annotations applied to the Java method parameters.

If the implementation class of a Web Bean declared in XML does not have a method with the name and parameter types declared in XML, a NonexistentMethodException is thrown by the Web Bean manager at initialization time.

In addition to the disposed parameter, a disposal method may declare additional parameters, which may also specify binding types. The Web Bean manager calls Manager.getInstanceByType() to determine a value for each parameter of a disposal method and calls the disposal method with those parameter values.

public void close(@Disposes @UserDatabase EntityManager em, @Logger Log log) { ... }

<myfwk:close>

    <Disposes>
        <jpa:EntityManager>
            <myapp:UserDatabase/>
        </jpa:EntityManager>
    </Disposes>
    
    <myfwk:Log>
        <myfwk:Logger/>
    <myfwk:Log>
    
</myfwk:close>

When searching for disposal methods for a producer method, the Web Bean manager searches for disposal methods which satisfy the following rules:

If there are multiple disposal methods for a producer method, a DefinitionException is thrown by the Web Bean manager at initialization time.

The default name for a producer method is the method name, unless the method follows the JavaBeans property getter naming convention, in which case the default name is the JavaBeans property name.

For example, this producer method is named products:

public class Shop {

   @Produces @Named
   public List<Product> getProducts() { ... }

}

This producer method is named paymentProcessor:

public class Shop {

   @Produces @Named
   public PaymentProcessor paymentProcessor() { ... }

}

The API types of a JMS endpoint depend upon whether it represents a queue or topic.

In addition, java.lang.Object is an API type of every JMS endpoint.

A JMS endpoint may be declared using the <Topic> or <Queue> elements in web-beans.xml. The JNDI name of the queue or topic must be specified using <destination> and the JNDI name of the JMS connection factory must be specified using <connectionFactory>.

<Queue>
    <destination>java:comp/env/jms/PaymentQueue</destination>
    <connectionFactory>java:comp/env/jms/QueueConnectionFactory</connectionFactory>
    <myapp:PaymentProcessor/>    
</Queue>

<Topic>
    <destination>java:comp/env/jms/Prices</destination>
    <connectionFactory>java:comp/env/jms/TopicConnectionFactory</connectionFactory>
    <myapp:Prices/>    
</Topic>

Open issue: do we need to allow specification of transacted and acknowledgeMode for the session?

An injected field may be declared by annotating the field with any binding type.

@ConversationScoped
public class Order {
   
   @Selected Product product;
   @Current User customer;

}

For a Web Beans defined in XML, an injected field may be declared using the field name and a child element representing the type of the field:

<myapp:Order>
    <ConversationScoped/>
    
    <myapp:product>
        <myapp:Product>
            <myapp:Selected/>
        </myapp:Product/>
    </myapp:product>
    
    <myapp:customer>
        <myapp:User/> 
    </myapp:customer>
    
</myapp:Order>

When an injected field is declared in XML, the Web Bean manager ignores binding annotations applied to the Java field.

If the type element does not declare any binding type, the default binding type @Current is assumed.

If the implementation class of a Web Bean declared in XML does not have a field with the name and type declared in XML, a NonexistentFieldException is thrown by the Web Bean manager at initialization time.

A Web Bean declared using XML has the following injected fields:

An initializer method may be declared by annotating the method @Initializer.

@ConversationScoped
public class Order {
   
   private Product product;
   private User customer;

   @Initializer 
   void setProduct(@Selected Product product)
   {
       this.product = product;
   }
   
   @Initializer 
   public void setCustomer(User customer)
   {
       this.customer = customer;
   }

}

If an initializer method is annotated @Produces or @Destructor, has a parameter annotated @Disposes, or has a parameter annotated @Observes, a DefinitionException is thrown by the Web Bean manager at initialization time.

For a Web Beans defined in XML, an initializer method may be declared using the method name, the <Initializer> element and the parameter types of the method.

<myapp:Order>
    <ConversationScoped/>
    
    <myapp:setProduct>
        <Initializer/>
        <myapp:Product>
            <myapp:Selected/>
        </myapp:Product>
    </myapp:setOrder>

    <myapp:setCustomer>
        <Initializer/>
        <myapp:User/>
    </myapp:setCustomer>

</myapp:Order>

When an initializer method is declared in XML, the Web Bean manager ignores binding annotations applied to the Java method parameters.

If the implementation class of a Web Bean declared in XML does not have a method with the name and parameter types declared in XML, a NonexistentMethodException is thrown by the Web Bean manager at initialization time.

A Web Bean declared using XML has the following injected fields and initializer methods:

If an initializer method of a Web Bean declared in XML is declared using both XML and annotations, the annotations are ignored.

An initializer method may have any number of parameters. If the initializer method has parameters, the Web Bean manager calls Manager.getInstanceByType() to determine a value for each parameter and calls the initializer method with those parameter values.