JSR 299: Web Beans

EJB defines a programming model for application components that access transactional resources in a multi-user environment. EJB allows concerns such as role-based security, transaction demarcation, concurrency and scalability to be specified declaratively using annotations and XML deployment descriptors and enforced by the EJB container at runtime.

EJB components may be stateful, but are not by nature contextual. References to stateful component instances must be explicitly passed between clients and stateful instances must be explicitly destroyed by the application.

Any EJB bean obtained via the Web Beans dependency injection service is a contextual object. It is bound to a context and available to other Web Beans that execute in that context. The Web Bean manager automatically calls the EJB container to create the EJB bean when it is needed by a client. When the context ends, the Web Bean manager automatically calls the EJB container to destroy the bean.

For any EJB bean, even EJB beans which are not obtained via the Web Beans dependency injection service, the Web Bean manager provides certain services, including injection of Web Bean instances and binding of Web Bean interceptors and decorators.

In general, The EJB container provides the services defined by the EJB specification, and the Web Bean manager provides the services defined by this specification. In particular, the Web Bean manager provides contextual lifecycle management, delegating the actual creation and destruction of the EJB bean to the EJB container. The Web Bean manager integrates with the EJB container via standard EJB and Java EE APIs.

JavaServer Faces is a web-tier presentation framework that provides a component model for graphical user interface components, a managed bean component model for application logic, and an event-driven interaction model that binds the two component models. The managed bean component model is a contextual model where managed beans are bound to one of the three web tier contexts and may hold contextual state.

Any Web Bean may fulfill the role of the managed bean in a JSF application. Thus, a JSF application may take advantage of the more sophisticated context and dependency injection model defined by this specification. Even better, the Web Bean may be an EJB bean, allowing direct use of EJB in any JSF page.

The Web Bean manager integrates with JSF via standard JSF APIs.

Web Beans may be called by a Servlet or JSP. The Web Bean manager integrates with the Servlet engine via standard APIs defined by the Java Servlets specification.

Servlets are not themselves Web Beans, because they may not be injected into another object by the Web Beans dependency injection mechanism. However, in the Java EE 6 environment, the Web Bean manager does provide injection of Web Beans into Servlets and binding of Web Bean interceptors and decorators to Servlets.

Note: we have requested an additional API from the Servlet specification to make this possible!

Certain functionality defined by Common Annotations for the Java Platform is available to any Web Bean. For Web Beans which are not EJB beans, this functionality is provided by the Web Bean manager.

The following JSF page defines a login prompt for a web application:

<f:view>
    <f:form>
        <h:panelGrid columns="2" rendered="#{!login.loggedIn}">
            <h:outputLabel for="username">Username:</h:outputLabel>
            <h:inputText id="username" value="#{credentials.username}"/>
            <h:outputLabel for="password">Password:</h:outputLabel>
            <h:inputText id="password" value="#{credentials.password}"/>
        </h:panelGrid>
        <h:commandButton value="Login" action="#{login.login}" rendered="#{!login.loggedIn}"/>
        <h:commandButton value="Logout" acion="#{login.logout}" rendered="#{login.loggedIn}"/>
    </f:form>
</f:view>

The Unified EL expressions in this page refer to Web Beans named credentials and login.

The Credentials class is a Web Bean whose lifecycle is bound to the JSF request:

@Model
public class Credentials {
	
    private String username;
    private String password;
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }
    
}

The @Model annotation is a stereotype that identifies the Credentials class as a Web Bean which acts as a model object in an MVC architecture.

The Login class is a Web Bean whose lifecycle is bound to the HTTP session:

@SessionScoped @Model
public class Login {

    @Current Credentials credentials;
    @PersistenceContext EntityManager userDatabase;

    private User user;
    
    public void login() {
    	
        List<User> results = userDatabase.createQuery(
            "select u from User u where u.username=:username and u.password=:password")
            .setParameter("username", credentials.getUserName())
            .setParameter("password", credentials.getPassword())
            .getResultList();
        
        if ( !results.isEmpty() ) {
            user = results.get(0);
        }
        
    }
    
    public void logout() {
        user = null;
    }
    
    public boolean isLoggedIn() {
        return user!=null;
    }
    
    @Produces @LoggedIn User getCurrentUser() {
        if (user==null) {
            throw new NotLoggedInException();
        }
        else {
            return user;
        }
    }

}

The @SessionScoped annotation is a scope type that specifies the lifecycle of instances of Login.

The @Current annotation is a binding annotation and causes the Credentials Web Bean to be injected into an instance of Login when it is created by the Web Bean manager.

The Common Annotations @PersistenceContext annotation causes a JPA EntityManager to be injected by the Web Bean manager.

The @LoggedIn annotation is also a binding annotation. The method annotated @Produces is a producer method, which will be called whenever another Web Bean in the system needs the currently logged-in user, for example, whenever the user attribute of the DocumentEditor class is injected by the Web Bean manager:

@Model
public class DocumentEditor {

    @Current Document document;
    @LoggedIn User user;
    @PersistenceContext EntityManager docDatabase;
    
    public void save() {
        document.setCreatedBy(currentUser);
        em.persist(document);
    }
    
}

When the login form is submitted, JSF sets the entered username and password onto an instance of the Credentials Web Bean that is automatically instantiated and provided by the Web Bean manager. Next, JSF calls the login() method on an instance of Login that is automatically instantiated and provided by the Web Bean manager. This instance continues to exist for and be available to other requests in the same HTTP session, and provides the User object representing the current user to any other Web Bean that requires it (for example, DocumentEditor). If the producer method is called before the login() method initializes the user object, it throws a NotLoggedInException.

Our Login class may take advantage of the functionality defined by EJB:

@Stateful @SessionScoped @Model
public class Login {

    @Current Credentials credentials;
    @PersistenceContext EntityManager userDatabase;

    private User user;
    
    @TransactionAttribute(REQUIRES_NEW) 
    @RolesAllowed("guest")
    public void login() {
        ...
    }
    
    public void logout() {
        user = null;
    }
    
    public boolean isLoggedIn() {
        return user!=null;
    }
    
    @RolesAllowed("user")
    @Produces @LoggedIn User getCurrentUser() {
        ...
    }

}

The @Stateful annotation specifies that this Web Bean is also an EJB stateful session bean. The @TransactionAttribute and @RolesAllowed annotations declare the EJB transaction demarcation and security attributes.

Web Beans interceptors allow common, cross-cutting concerns to be applied to Web Beans via custom annotations. Interceptor types may be individually enabled or disabled at deployment time.

The AuthorizationInterceptor class defines a custom authorization check:

@Secure @Interceptor public class AuthorizationInterceptor {
    
    @LoggedIn User user;
    
    @AroundInvoke public void authorize(InvocationContext ic) {
        try {
            if ( !user.isBanned() ) {
                System.out.println("Authorized");
                ic.proceed();
            }
            else {
                System.out.println("Not authorized");
                throw new NotAuthorizedException();
            }
        }
        catch (NotAuthenticatedException nae) {
            System.out.println("Not authenticated");
            throw nae;
        }
    }
    
}

The Web Beans @Interceptor annotation identifies the AuthorizationInterceptor class as a Web Beans interceptor. The @Secure annotation is a custom interceptor binding type.

@InterceptorBindingType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface Secure {}

The @Secure annotation is used to apply the interceptor to a Web Beans or EJB bean:

@Model
public class DocumentEditor {

    @Current Document document;
    @LoggedIn User user;
    @PersistenceContext EntityManager em;
    
    @Secure
    public void save() {
        document.setCreatedBy(currentUser);
        em.persist(document);
    }
    
}

When the save() method is invoked, the authorize() method of the interceptor will be called. The invocation will proceed to the DocumentEditor class only if the authorization check is successful.

Web Beans decorators are similar to interceptors, but apply only to Web Beans of a particular Java interface. Like interceptors, decorators may be easily enabled or disabled at deployment time. Unlike interceptors, decorators are aware of the semantics of the intercepted method.

For example, the DataAccess interface might be implemented by many Web Beans:

public interface DataAccess {
      
    public Object load(Object id);
    public Object getId();

    public void save();
    public void delete();
    
    public Class getDataType();
      
}

The DataAccessAuthorizationDecorator class defines the authorization checks:

@Decorator public abstract class DataAccessAuthorizationDecorator 
    implements DataAccess {
    
    @Decorates DataAccess delegate;
    
    @LoggedIn User user;
    
    public void save() {
        authorize("save");
        delegate.save();
    }
      
    public void delete() {
        authorize("delete");
        delegate.delete();
    }
    
    private void authorize(String action) {
        try {
            Object id = delegate.getId();
            Class type = delegate.getDataType();
            if ( user.hasPermission(action, type, id) )
            {
                System.out.println("Authorized for " + action);
            }
            else {
                System.out.println("Not authorized for " + action);
                throw new NotAuthorizedException(action);
            }
        }
        catch (NotAuthenticatedException nae) {
            System.out.println("Not authenticated");
            throw nae;
        }
    }
    
}

The @Decorator annotation identifies the DataAccessAuthorizationDecorator class as a Web Beans decorator. The @Decorates annotation identifies the delegate attribute, which the decorator uses to delegate method calls to the Web Bean manager. The decorator applies to any Web Bean that implements DataAccess.

The decorator intercepts invocations just like an interceptor. However, unlike an interceptor, the decorator contains functionality that is specific to the semantics of the method being called.

Decorators may be declared abstract, relieving the developer of the responsibility of implementing all methods of the decorated interface. If a decorator does not implement a method of an API type, the decorator will simply not be called when that method is invoked upon the decorated Web Bean.

If a Web Bean does not explicitly declare a binding type, the Web Bean has exactly one binding type: javax.webbeans.Current. This is called the default binding type.

The following declarations are equivalent:

@Current
public class Order {}

public class Order {}

The default binding type is also assumed for any injection point that does not explicitly declare a binding type. The following declarations are equivalent:

public class Order {
    public Order(@Current OrderProcessor processor) { ... }
}

public class Order {
    public Order(OrderProcessor processor) { ... }
}

A binding type is a Java annotation defined as @Target({METHOD, FIELD, PARAMETER, TYPE}) and @Retention(RUNTIME). All binding types must specify the @BindingType meta-annotation.

For example:

@BindingType
@Retention(RUNTIME)
@Target({METHOD, FIELD, PARAMETER, TYPE})
public @interface Synchronous {}

@BindingType
@Retention(RUNTIME)
@Target({METHOD, FIELD, PARAMETER, TYPE})
public @interface Asynchronous {}

A binding annotation may define annotation members.

@BindingType
@Retention(RUNTIME)
@Target({METHOD, FIELD, PARAMETER, TYPE})
public @interface PayBy {
    PaymentMethod value();
}

Binding annotation member values are significant to the typesafe resolution algorithm.

A Web Bean's binding types are declared by annotating the implementation class or producer method with the binding types.

@LDAP 
class LdapAuthenticator 
        implements Authenticator {
    ...
}

public class Shop {

   @Produces @All
   public List<Product> getAllProducts() { ... }

   @Produces @WishList
   public List<Product> getWishList() { ..... }
   
   @Produces @ShoppingCart
   public List<Product> getShoppingCart() { ..... }

}

Any Web Bean may declare multiple binding types.

@Synchronous @Reliable
class SynchronousReliablePaymentProcessor 
        implements PaymentProcessor {
    ...
}

If no binding type is explicitly specified, the default binding type is assumed.

If a Web Bean is declared in web-beans.xml, binding types may be specified using the binding type names:

<myapp:SynchronousPaymentProcessor>
    <myapp:Synchronous/>
    <myapp:Reliable/>
</myapp:SynchronousPaymentProcessor>

If any binding type is specified in XML, the binding annotations appearing on the implementation class or producer method are ignored and all binding types must be explicitly specified in XML.

Otherwise, if no binding types are specified in XML, the binding annotations that appear on the implementation class or producer method are used. If no binding annotations appear on the implementation class or producer method, the default binding type is used.

Binding annotations are applied to injected fields (see Section 3.6, “Injected fields”) to determine the Web Bean that is injected, according to the typesafe resolution algorithm defined in Section 4.9.2, “Typesafe resolution algorithm”.

@LDAP Authenticator authenticator;

A Web Bean may only be injected to an injection point if it has all the binding types of the injection point.

@Synchronous @Reliable PaymentProcessor paymentProcessor;

For the case of producer methods, the binding annotation help determine exactly which producer method is called:

@All List<Product> catalog;

@WishList List<Product> wishList;

@ShoppingCart List<Product> cart;

For a Web Bean defined in XML, the binding types of a field may be specified using XML:

<myapp:paymentProcessor>
    <myapp:Asynchronous/>
    <myapp:Reliable/>
</myapp:paymentProcessor>

When the binding types of a field are specified using XML, any binding type annotations of the field are ignored.

Binding annotations may be applied to parameters of producer methods, initializer methods, disposal methods, Web Bean remove methods or Web Bean constructors (see Chapter 3, Web Bean implementation) to determine the Web Bean instance that is passed when the method is called by the Web Bean manager. The Web Bean manager uses the typesafe resolution algorithm defined in Section 4.9.2, “Typesafe resolution algorithm” to determine values for these parameters.

For example, when the Web Bean manager encounters the following producer method, an instance of SynchronousPaymentProcessor will be passed to the first parameter and an instance of AsynchronousPaymentProcessor will be passed to the second parameter:

@Produces
PaymentProcessor getPaymentProcessor(@Synchronous PaymentProcessor sync, 
                                     @Asynchronous PaymentProcessor async) {
    return isSynchronous() ? sync : async;
}

For a Web Bean defined in XML, the binding types of a method parameter may be specified using XML:

<myapp:getPaymentProcessor>
    <Produces/>
    <myapp:PaymentProcessor>
        <myapp:Synchronous/>
    </myapp:PaymentProcessor>
    <myapp:PaymentProcessor>
        <myapp:Asynchronous/>
    </myapp:PaymentProcessor>
</myapp:getPaymentProcessor>

When the binding types of a parameter are specified using XML, any binding type annotations of the parameter are ignored.

There are several standard scope types defined by Web Beans. The @RequestScoped, @ApplicationScoped and @SessionScoped annotations defined in Section 8.5, “Context management for built-in scopes” represent the standard scopes defined by the Java Servlets specification. The @ConversationScoped annotation represents the Web Beans conversation scope defined in Section 8.5.4, “Conversation context lifecycle”. In addition, there is the @Dependent pseudo-scope for dependent objects, as defined in Section 8.3, “Dependent pseudo-scope”.

A Web Beans scope type is a Java annotation defined as @Target({TYPE, METHOD}) and @Retention(RUNTIME). All scope types must also specify the @ScopeType meta-annotation.

For example, the following annotation declares a "business process scope":

@ScopeType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface BusinessProcessScoped {}

An application or third-party framework might provide a context implementation for this custom scope (see Section 8.6, “Context management for custom scopes”).

The Web Bean's scope is defined by annotating the implementation class or producer method with a scope type.

A Web Bean implementation class or producer method may specify at most one scope type annotation. If an implementation class or producer method specifies multiple scope type annotations, a DefinitionException is thrown by the Web Bean manager at startup time.

The following examples demonstrate the use of built-in scope types:

@RequestScoped
public class ProductList implements DataModel { ... }

public class Shop {

   @Produces @SessionScoped @WishList
   public List<Product> getWishList() { ..... }

   @Produces @ConversationScoped @ShoppingCart
   public List<Product> getShoppingCart() { ..... }

}

Likewise, a Web Bean with the custom business process scope may be declared by annotating it with the @BusinessProcessScoped annotation:

@BusinessProcessScoped
public class Order {
    ...
}

Alternatively, a scope type may be specified using a stereotype annotation, as defined in Section 2.7.2, “Declaring the stereotypes for a Web Bean using annotations”.

If the Web Bean is declared in web-beans.xml, the scope may be specified using the scope annotation type name:

<myapp:ProductList>
    <RequestScoped/>
</myapp:ProductList>

If more than one scope type is specified in XML, a DefinitionException is thrown by the Web Bean manager at initialization time.

If an implementation class or producer method with a scope type annotation is specified and if no scope type is explicitly specified in XML, the scope defined by the scope type annotation is used.

Alternatively, a scope type may be specified using a stereotype declared in XML, as defined in Section 2.7.3, “Declaring the stereotypes for a Web Bean using XML”.

When no scope is explicitly declared by annotating the implementation class or producer method, or by using XML, the scope of a Web Bean is defaulted.

The default scope for a Web Bean which does not explicitly declare a scope depends upon its declared stereotypes:

If a Web Bean explicitly declares a scope, any default scopes declared by stereotypes are ignored.

There are two standard deployment types defined by Web Beans: @Production and @Standard.

All standard Web Beans defined by this specification, and provided by the Web Bean manager, are defined using the @Standard deployment type. For example, the Conversation object defined in Section 8.5.4, “Conversation context lifecycle” and the Manager object defined in Section 4.8, “The Manager object” have this deployment type. No Web Bean may be declared with the @Standard deployment type unless explicitly required by this specification.

Application Web Beans may be defined using the @Production deployment type.

A Web Beans deployment type is a Java annotation defined as @Target({TYPE, METHOD}) and @Retention(RUNTIME). All deployment types must also specify the @DeploymentType meta-annotation.

Applications and third-party frameworks may define their own deployment types. For example, the following deployment type might identify Web Beans which are used only at a particular site at which the application is deployed:

@DeploymentType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface Australian {}

This deployment type might be used by a third-party framework that extends Web Beans:

@DeploymentType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface DaoFramework {}

This deployment type might be used to define mock objects for integration testing:

@DeploymentType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface Mock {}

The deployment type of the Web Bean is declared by annotating the implementation class or producer method.

An implementation class or producer method may specify at most one deployment type. If multiple deployment type annotations are specified, a DefinitionException is thrown by the Web Bean manager at initialization time.

Open issue: is this too restrictive? We could allow multiple deployment types to be specified, and ignore all but the highest-precedence enabled deployment type.

This Web Bean has the deployment type @Production:

@Production
public class Order {}

This Web Bean has the deployment type @Mock:

@Mock
public class MockOrder extends Order {}

By default, if no deployment type annotation is explicitly specified, a producer method inherits the deployment type of the Web Bean in which it is defined.

This producer method has the deployment type @Production:

@Production
public class Login {

   @Produces
   public User getUser() { ... }

}

This producer method has the deployment type @Australian:

@Production
public class TaxPolicies {

   @Produces @Australian
   public TaxPolicy getAustralianTaxPolicy() { ... }

}

Alternatively, a deployment type may be specified using a stereotype annotation, as defined in Section 2.7.2, “Declaring the stereotypes for a Web Bean using annotations”.

When a Web Bean is declared in web-beans.xml, the deployment type may be specified using a tag with the annotation type name:

<myapp:AustralianTaxPolicy>
    <deployment:Australian/>
</myapp:AustralianTaxPolicy>

If more than one deployment type is specified in XML, a DefinitionException is thrown by the Web Bean manager at initialization time.

If an implementation class or producer method with a deployment type annotation is specified and if no deployment type is explicitly specified in XML, the deployment type defined by the deployment type annotation is used.

Alternatively, a deployment type may be specified using a stereotype declared in XML, as defined in Section 2.7.3, “Declaring the stereotypes for a Web Bean using XML”.

When no deployment type is explicitly declared by annotating the implementation class or producer method, or by use of XML, the deployment type is defaulted.

The default deployment type for a Web Bean which does not explicitly declare a deployment type depends upon its declared stereotypes:

Thus, the following declarations are equivalent:

@Production
public class Order {}

public class Order {}

If a Web Bean explicitly declares a deployment type, any default deployment type declared by stereotypes are ignored.

In a particular deployment, only some deployment types are enabled. Web Beans declared with a deployment type that is not enabled are not available to the resolution algorithms defined in Chapter 4, Lookup, dependency injection and EL resolution.

The Web Bean manager inspects the deployment type of each Web Bean that exists in a particular deployment (see Section 10.1, “Web Bean discovery”) to determine whether the Web Bean is enabled in this deployment. If the deployment type is enabled, an instance of the Web Bean may be obtained by lookup, injection or EL resolution. Otherwise, the Web Bean is never instantiated by the Web Bean manager.

By default, only the built-in deployment types are enabled. To enable a custom deployment type, a <Deploy> element must be included in a web-beans.xml file and the deployment type must be declared using the annotation type name.

<WebBeans>
    <Deploy>
        <Standard/>
        <Production/>
        <myfwk:DaoFramework/>
        <deployment:Australian/>
        <myfwk:Mock/>
    </Deploy>
</WebBeans>

If a <Deploy> element is specified, only the explicitly declared deployment types are enabled. The @Standard deployment type must be declared. If the @Standard deployment type is not declared, a DeploymentException is thrown by the Web Bean manager at initialization time.

If no <Deploy> element is specified in any web-beans.xml file, only the @Standard and @Production deployment types are enabled.

If the <Deploy> element is specified in more than one web-beans.xml document, a DeploymentException is thrown by the Web Bean manager at initialization time.

In a particular deployment, all enabled deployment types are strongly ordered in terms of precedence. The precedence of a deployment type is used by the resolution algorithms defined in Chapter 4, Lookup, dependency injection and EL resolution.

If a <Deploy> element is specified, the order of the deployment type declarations determines the deployment type precedence. Deployment types which appear later in this list have a higher precedence than deployment types which appear earlier. The @Standard deployment type must appear first and always has the lowest precedence of any deployment type.

If no <Deploy> element is specified, the @Production deployment type has a higher precedence than the @Standard deployment type.

To specify the name of a Web Bean, the @Named annotation is applied to the implementation class or producer method. This Web Bean is named products:

@Named("products")
public class ProductList implements DataModel { ... }

If the @Named annotation does not specify the value member, the default name is assumed.

If the Web Bean is declared in web-beans.xml, the name may be specified using <Named>:

<myapp:ProductList>
    <Named>products</Named>
</myapp:ProductList>

If the <Named> element is empty, the default name is assumed.

If an implementation class or producer method with a @Named annotation is specified, and if no <Named> element is explicitly specified, the name specified by the @Named annotation is used. If the @Named annotation does not specify the value member, the default name is assumed.

If a <Named> element is specified, the @Named annotation is ignored.

In the following circumstances, a default name must be assigned by the Web Bean manager:

The default name for a Web Bean depends upon the Web Bean implementation. The rules for determining the default name for a Web Bean are defined in Chapter 3, Web Bean implementation.

If neither <Named> nor @Named is specified, by the Web Bean or its stereotypes, a Web Bean has no name.

A Web Beans stereotype is a Java annotation defined as @Target({TYPE, METHOD}), @Target(METHOD) or @Target(TYPE) and @Retention(RUNTIME). All stereotypes must also specify the @Stereotype meta-annotation.

A stereotype may declare at most one scope type. If a stereotype declares more than one scope type, a DefinitionException is thrown by the Web Bean manager at initialization time.

A stereotype may declare at most one deployment type. If a stereotype declares more than one deployment type, a DefinitionException is thrown by the Web Bean manager at initialization time.

A stereotype may declare an empty @Named annotation. If a stereotype declares a non-empty @Named annotation, a DefinitionException is thrown by the Web Bean manager at initialization time.

A stereotype may declare zero, one or multiple interceptor binding types, as defined in Section 6.2.4, “Interceptor bindings”.

A stereotype may not declare any binding type annotation. If a stereotype declares a binding type annotation, a DefinitionException is thrown by the Web Bean manager at initialization time.

For example, the following stereotype might be used to identify action classes in a web application:

@RequestScoped
@Production
@Stereotype
@Target(TYPE)
@Retention(RUNTIME)
public @interface Action {}

Then actions would have scope @RequestScoped and deployment type @Production unless the scope or deployment type explicitly specified by the Web Bean.

We may specify interceptor bindings that apply to all actions:

@RequestScoped
@Secure
@Transactional
@Production
@Stereotype
@Target(TYPE)
@Retention(RUNTIME)
public @interface Action {}

We may specify that every Web Bean with the stereotype has a defaulted name when a name is not explicitly specified by the Web Bean:

@RequestScoped
@Secure
@Transactional
@Named
@Production
@Stereotype
@Target(TYPE)
@Retention(RUNTIME)
public @interface Action {}

If all actions are request scoped, we can make this restriction explicit:

@RequestScoped
@Secure
@Transactional
@Production
@Stereotype(supportedScopes=RequestScoped.class)
@Target(TYPE)
@Retention(RUNTIME)
public @interface Action {}

We may even require that all actions extend some ActionBase class:

@RequestScoped
@Secure
@Transactional
@Production
@Stereotype(requiredTypes=ActionBase.class)
@Target(TYPE)
@Retention(RUNTIME)
public @interface Action {}

Stereotype annotations may be applied to a Web Bean implementation class or producer method.

@Action
public class LoginAction { ... }

The default deployment type and default scope declared by the stereotype may be overridden by the Web Bean:

@Mock @ApplicationScoped @Action
public class MockLoginAction extends LoginAction { ... }

Multiple stereotypes may be applied to the same Web Bean:

@Dao @Action
public class LoginAction { ... }

If the Web Bean is declared in web-beans.xml, stereotypes may be declared using the stereotype annotation type name:

<myapp:LoginAction>
    <myfwk:Action/>
</myapp:LoginAction>

If any stereotype is specified in XML, the stereotypes appearing on the implementation class or producer method are ignored and all stereotypes must be explicitly specified in XML.

Otherwise, if no stereotypes are specified in XML, the stereotype annotations that appear on the implementation class or producer method are used. If no stereotype annotations appear on the implementation class or producer method, the Web Bean has no stereotypes.

A stereotype may place certain restrictions upon the Web Beans that declare the stereotype.

If a stereotype declares a requiredType, and the Web Bean API types do not include the type, a DefinitionException is thrown by the Web Bean manager at initialization time.

If a stereotype explicitly declares a set of scope types using supportedScopes, and the Web Bean scope is not in that set, a DefinitionException is thrown by the Web Bean manager at initialization time.

If a Web Bean declares multiple stereotypes, it must satisfy every restriction declared by every declared stereotype.

Web Beans provides a built-in stereotype. The @Model stereotype is intended for use with Web Beans that define the model layer of an MVC web application architecture such as JSF:

@Named
@RequestScoped
@Stereotype
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface Model {}

In addition, the special-purpose @Interceptor and @Decorator stereotypes are defined in Chapter 6, Interceptors and decorators.

The @Specializes annotation or <Specializes> XML element is used to indicate that one Web Bean directly specializes another Web Bean.

Formally, a Web Bean X is said to specialize another Web Bean Y if either:

If X specializes Y but does not directly specialize Y, we say that X indirectly specializes Y.

If, in a particular deployment, a Web Bean with a certain API type and set of binding types is not specialized by any other enabled Web Bean, we call it the most specialized Web Bean for that combination of type and binding types in that deployment.

Any producer methods, disposal methods (see Section 3.4.6, “Disposal methods”) or observer methods (see Section 7.5, “Observer methods”) declared by a Web Bean are invoked upon an instance of the most specialized enabled Web Bean that specializes the Web Bean, as defined by Section 5.6, “Lifecycle of producer methods” and Section 7.4, “Observer invocation”.

If, in a particular deployment, either

we say that inconsistent specialization exists, and an InconsistentSpecializationException is thrown by the Web Bean manager at initialization time.

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.

Certain legal API types cannot be proxied by the Web Bean manager:

If an injection point whose declared type cannot be proxied by the Web Bean manager resolves to a Web Bean with a normal scope type, an UnproxyableDependencyException is thrown by the Web Bean manager at initialization time.

Every time a method of the Web Bean is invoked upon a client proxy, the client proxy must:

In certain situations, injection is not the most convenient way to obtain a reference to a Web Bean instance. For example, it may not be used when the API type or and/binding types vary dynamically at runtime. In these situations, the application may directly call Manager.getInstanceByType().

When the application calls getInstanceByType() to obtain a Web Bean instance dynamically, it may need to pass instances of the binding annotation types.

The helper class javax.webbeans.AnnotationLiteral makes it easier to implement binding annotation types:

public class SynchronousBinding 
          extends AnnotationLiteral<Synchronous> 
          implements Synchronous {}

public abstract class PayByBinding 
          extends AnnotationLiteral<PayBy> 
          implements PayBy {}

Then the application may easily instantiate instances of the binding type:

PaymentProcessor pp = manager.getInstanceByType(PaymentProcessor.class, 
            new SynchronousBinding(),
            new PayByBinding() { public PaymentMethod value() { return CHEQUE; } });

Parameterized API types may be specified by passing a subclass of TypeLiteral:

PaymentProcessor pp = manager.getInstanceByType( new TypeLiteral<List<String>>() {}, 
            new WishListBinding() );

The process of matching a Web Bean to an injection point is called typesafe resolution. The Web Bean manager considers API type, binding annotations, and Web Bean precedences when resolving a Web Bean to be injected to an injection point.

Typesafe resolution usually occurs at Web Bean manager initialization time, allowing the Web Bean manager to warn the user if any enabled Web Beans have unsatisfied or ambiguous dependencies.

The resolveByType() method of the Manager interface returns the result of the typesafe resolution.

public interface Manager {
    
    public <T> Set<Bean<T>> resolveByType(Class<T> apiType, Annotation... bindingTypes);
    public <T> Set<Bean<T>> resolveByType(TypeLiteral<T> apiType, Annotation... bindingTypes);
    
    ...
    
}

If no binding annotations are passed to resolveByType(), the default binding annotation @Current is assumed.

If two instances of the same binding type are passed to resolveByType(), a DuplicateBindingTypeException is thrown.

If an instance of an annotation that is not a binding type is passed to resolveByType(), an IllegalArgumentException is thrown.

The following algorithm must be used by the Web Bean manager when resolving a Web Bean by type:

If resolveByType() is called with the API type java.lang.Object and no binding annotations, it returns the set of all enabled Web Beans.

@PayBy(CHEQUE)
class ChequePaymentProcessor implements PaymentProcessor { ... }

@PayBy(CREDIT_CARD)
class CreditCardPaymentProcessor implements PaymentProcessor { ... }

@PayBy(CHEQUE) PaymentProcessor paymentProcessor;

@PayBy(CREDIT_CARD) PaymentProcessor paymentProcessor;

@BindingType
@Retention(RUNTIME)
@Target({METHOD, FIELD, PARAMETER, TYPE})
public @interface PayBy {
    PaymentMethod value();
    @NonBinding String comment();
}

@Synchronous @PayBy(CHEQUE)
class ChequePaymentProcessor implements PaymentProcessor { ... }

@PayBy(CHEQUE) PaymentProcessor paymentProcessor;

@Synchronous PaymentProcessor paymentProcessor;

@Synchronous @PayBy(CHEQUE) PaymentProcessor paymentProcessor;

The process of matching a Web Bean to a name used in EL is called name resolution. Since there is no typing information available in EL, the Web Bean manager may consider only Web Bean names.

The resolveByName() method of the Manager interface performs name resolution.

public interface Manager {
    
    public Set<Bean<?>> resolveByName(String name);
    
    ...
    
}

The following algorithm must be used by the Web Bean manager when resolving a Web Bean by name:

The name resolution algorithm usually occurs at runtime.

In a Servlet or JSF application, the Web Bean manager must register the ELResolver with the web container.

In a JSF environment, the Web Bean manager calls Application.addELResolver() at initialization time (or provides a faces-config.xml file with an <el-resolver> element).

If necessary, the Web Bean manager will register the ELResolver directly with the JSP engine by calling JspFactory.getDefaultFactory(), JspFactory.getJspApplicationContext() and finally JspApplicationContext.addELResolver() at initialization time.

An interceptor method for business method invocations is a method of an interceptor with return type Object and a single parameter of type javax.interceptor.InvocationContext, annotated @AroundInvoke.

Interceptor methods for business method invocations are called when a business method is invoked.

If an interceptor has an interceptor method for business method invocations, we describe it as a business method interceptor.

An interceptor method for a lifecycle callback is a method of a Web Beans interceptor implementation class with return type void and a single parameter of type javax.interceptor.InvocationContext, annotated @PostConstruct, @PreDestroy, @PrePassivate or @PostActivate.

Interceptor methods for a lifecycle callbacks are called when the corresponding @PostConstruct, @PreDestroy, @PrePassivate or @PostActivate callbacks is invoked.

If an interceptor has an interceptor method for a lifecycle callback, we describe it as a lifecycle callback interceptor.

Any Web Bean implementation class may declare interceptors using @Interceptors. If the Web Bean is an EJB bean, the EJB container is responsible for calling interceptors declared using @Interceptors. Otherwise, the Web Bean manager is responsible for calling the interceptors. In both cases, the semantics are fully defined by the EJB specification.

As an extension to the functionality defined by the javax.interceptor package, Web Beans provides an alternative method of binding interceptors to simple Web Beans, enterprise Web Beans and EJB session, singleton and message driven beans. Interceptors bound using this mechanism are always called by the Web Bean manager.

Even when interceptors are bound using this mechanism, the interception semantics are defined by the EJB specification.

An interceptor binding type is a Java annotation defined as @Target({TYPE, METHOD}) or @Target(TYPE) and @Retention(RUNTIME). All interceptor binding types must also specify the @InterceptorBindingType meta-annotation.

@InterceptorBindingType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface Transactional {}

Multiple interceptors may be bound to the same interceptor binding type or types.

@InterceptorBindingType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
@Transactional
public @interface DataAccess {}

@Transactional
@Secure
@Production
@RequestScoped
@Stereotype
@Target(TYPE)
@Retention(RUNTIME)
public @interface Action {}

A Web Beans interceptor is a simple Web Bean with an implementation class that is also an interceptor class as defined by the EJB specification. Web Beans interceptors must declare at least one interceptor binding type.

A Web Beans interceptor may be either a business method interceptor, a lifecycle callback interceptor or both.

Web Beans lifecycle callback interceptors may only declare interceptor binding types that are defined as @Target(TYPE). If a lifecycle callback interceptor declares an interceptor binding type that is defined @Target({TYPE, METHOD}), a DefinitionException is thrown by the Web Bean manager at initialization time.

If a Web Beans interceptor does not declare any interceptor binding type, a DefinitionException is thrown by the Web Bean manager at initialization time.

Open issue: do we need to support defining interceptor methods in XML?

Open issue: should we support injection into interceptor methods?

@Transactional @Interceptor
public class TransactionInterceptor {

   @AroundInvoke 
   public Object manageTransaction(InvocationContext ctx) { ... }

}

<myfwk:TransactionInterceptor>
    <Interceptor/>
    <myfwk:Transactional/>
</myfwk:TransactionInterceptor>

A Web Beans lifecycle callback interceptor may be bound to any simple Web Bean that is not an interceptor or decorator, any enterprise Web Bean or any EJB session, singleton or message-driven bean by declaring, at the class level, the same interceptor binding types that were declared by the interceptor.

A Web Beans business method interceptor may be bound to all non-static, non-private, non-final methods of a simple Web Bean that is not an interceptor or decorator or to all business methods of an enterprise Web Bean or EJB session, singleton or message-driven bean by declaring the same interceptor binding types, at the class level, that were declared by the interceptor.

A Web Beans business method interceptor may be bound to a non-static, non-private, non-final method of a simple Web Bean that is not an interceptor or decorator or to a business method of an enterprise Web Bean or EJB session, singleton or message-driven bean by declaring the same interceptor binding types, at the method level, that were declared by the interceptor.

If a simple Web Bean implementation class that is not an interceptor or decorator is declared final, or has any non-static, non-private, final methods, and also declares an interceptor binding type or a stereotype with interceptor bindings, a DefinitionException is thrown by the Web Bean manager at initialization time.

If a non-static, non-private method of a simple Web Bean implementation class is declared final and also declares an interceptor binding type, an DefinitionException is thrown by the Web Bean manager at initialization time.

@Transactional
public class ShoppingCart { ... }

public class ShoppingCart {

   @Transactional 
   public void placeOrder() { ... }

}

<myapp:ShoppingCart>
   <myfwk:Transactional/>
</myapp:ShoppingCart>

<myapp:ShoppingCart>
   <myapp:placeOrder>
       <myfwk:Transactional/>
   </myapp:placeOrder>
</myapp:ShoppingCart>

By default, interceptors bound via interceptor binding types are not enabled. An interceptor must be explicitly enabled by listing its implementation class under the <Interceptors> element in web-beans.xml.

<Interceptors>
    <myfwk:TransactionInterceptor/>
    <myfwk:LoggingInterceptor/>
</Interceptors>

The order of the interceptor declarations determines the interceptor ordering. Interceptors which occur earlier in the list are called first.

If the <Interceptors> element is specified in more than one web-beans.xml document, a DefinitionException is thrown by the Web Bean manager at initialization time.

Interceptors declared using @Interceptors or in ejb-jar.xml are called before interceptors declared using Web Beans interceptor bindings.

Interceptors are called before decorators.

Open issue: how can we guarantee this for EJBs?

The Bean object for an interceptor must extend the abstract class Interceptor.

public abstract class Interceptor extends Bean<Object> {

    protected Interceptor(Manager manager) {
        super(manager);
    }

    public abstract Set<Annotation> getInterceptorBindingTypes();

    public abstract Method getMethod(InterceptionType type);

}

An InterceptionType identifies the kind of lifecycle callback or business method.

public enum InterceptionType { 
    AROUND_INVOKE, POST_CONSTRUCT, PRE_DESTROY, PRE_PASSIVATE, POST_ACTIVATE 
}

The getMethod() method returns the interceptor method for the specified kind of lifecycle callback or business method. The getMethod() method must return a null value if the interceptor does not intercepts callbacks or business methods of the given type.

The following method returns the ordered list of enabled interceptors for a set of interceptor binding types.

public interface Manager {
      
    List<Interceptor> resolveInterceptors(InterceptionType type, 
                                                Annotation... interceptorBindingTypes);
    
    ...
    
}

If two instances of the same interceptor binding type are passed to resolveInterceptors(), a DuplicateBindingTypeException is thrown.

If no interceptor binding type instance is passed to resolveInterceptors(), an IllegalArgumentException is thrown.

If an instance of an annotation that is not an interceptor binding type is passed to resolveInterceptors(), an IllegalArgumentException is thrown.

The following algorithm must be used by the Web Bean manager when resolving interceptors:

@Transactional @Secure @Interceptor
public class TransactionalSecurityInterceptor {

   @AroundInvoke 
   public void aroundInvoke() { ... }

}

@Transactional @Secure
public class ShoppingCart { ... }

@Transactional
public class ShoppingCart {

   @Secure
   public void placeOrder() { ... }
 
}

@Transactional
public class ShoppingCart {

   public void placeOrder() { ... }
 
}

@InterceptorBindingType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface Transactional {
   boolean requiresNew() default false;
}

@Transactional(requiresNew=true) @Interceptor
public class RequiresNewTransactionInterceptor {

   @AroundInvoke 
   public Object manageTransaction(InvocationContext ctx) { ... }

}

@Transactional(requiresNew=true)
public class ShoppingCart { ... }

@Transactional
public class ShoppingCart { ... }

@InterceptorBindingType
@Target({TYPE, METHOD})
@Retention(RUNTIME)
public @interface Transactional {
   @NonBinding boolean requiresNew() default false;
}

When a simple or enterprise Web Bean is created, the Web Bean manager must:

The resulting ordered lists of interceptor instances are called interceptor stacks.

Whenever a business method or lifecycle callback is invoked on an instance of a simple Web Bean, enterprise Web Bean or EJB session, singleton, or message driven bean, the Web Bean manager intercepts the method invocation and invokes interceptors of the callback or business method.

The Web Bean manager identifies the first interceptor in the interceptor stack for the method. If no such interceptor exists, the Web Bean manager starts processing the decorator stack, as defined in Section 6.3.9, “Decorator invocation”. Otherwise, the Web Bean manager builds an instance of javax.interceptor.InvocationContext and calls the appropriate interceptor method of the interceptor.

When any interceptor is invoked by the Web Bean manager, it may in turn call InvocationContext.proceed(). The Web Bean manager then identifies the first interceptor in the interceptor stack for the method such that the interceptor has not previously been invoked during this business method or lifecycle callback invocation. If no such interceptor exists, the Web Bean manager starts processing the decorator stack. Otherwise, the Web Bean manager calls the appropriate interceptor method.

Eventually, by recursion, the interceptor stack is exhausted of uninvoked interceptors.

A decorator is declared by annotating the implementation class with the @Decorator stereotype.

@Decorator
class TimestampLogger implements Logger { ... }

Additional decorators may be declared in web-beans.xml, using the decorator implementations class name and the <Decorator> element:

<myfwk:TimestampLogger>
    <Decorator/>
    ...
</myfwk:TimestampLogger>

If the decorator implementation class is already annotated @Decorator, two different decorators exist.

All decorators inject a delegate attribute using the @Decorates annotation or <Decorates> element:

@Decorator
class TimestampLogger implements Logger {
    @Decorates Logger logger;
    ...
}

<myfwk:TimestampLogger>
    <Decorator/>
    <myfwk:logger>
        <Decorates>
            <myfwk:Logger/>
        </Decorates>
    </myfwk:logger>
</myfwk:TimestampLogger>

In this case, the decorator is bound to any Web Bean or EJB bean that has the type of the delegate attribute as an API type.

The declared type of the delegate attribute must be a Java interface type. If the declared type of a delegate attribute is not a Java interface type, a DefinitionException is thrown by the Web Bean manager at initialization time.

The delegate may optionally declare one or more binding types:

@Decorator
class TimestampLogger implements Logger {
    @Decorates @Debug Logger logger;
    ...
}

<myfwk:TimestampLogger>
    <Decorator/>
    <myfwk:logger>
        <Decorates>
            <myfwk:Logger>
                <myfwk:Debug/>
            </myfwk:Logger>
        </Decorates>
    </myfwk:logger>
</myfwk:TimestampLogger>

In this case, the decorator is bound to any Web Bean or EJB bean that has the type of the delegate attribute as an API type, and declares all the binding types specified by the delegate attribute.

All delegate binding types must be explicitly declared. If no binding type is explicitly declared by the delegate attribute, the set of binding types is empty.

A decorator must declare exactly one delegate attribute. If a decorator declares more than one delegate attribute, or does not declare a delegate attribute, a DefinitionException is thrown by the Web Bean manager at initialization time.

When a decorator is declared in XML, it must explicitly declare a delegate attribute. The Web Bean manager ignores any delegate attribute declared using annotations.

If a decorator applies to a simple Web Bean, and the Web Bean implementation class is declared final, a DefinitionException is thrown by the Web Bean manager at initialization time.

If a decorator applies to a simple Web Bean with a non-static, non-private, final method, and the decorator also implements that method, a DefinitionException is thrown by the Web Bean manager at initialization time.

A decorator is not required to implement all of the API types of its delegate attribute. If a decorator does not implement an API type of the delegate attribute, that API will not be intercepted by the decorator.

A decorator may be an abstract Java class, and is not required to implement all methods of its API types. If a decorator does not implement a method of one of its API types, that method will not be intercepted by the decorator.

The declared type of the decorator delegate attribute must implement or extend all of the decorated types of the decorator. If a decorator delegate attribute does not implement or extend a decorated type of the decorator, a DefinitionException is thrown by the Web Bean manager at initialization time.

By default, decorators are not enabled. A decorator must be explicitly enabled by listing its implementation class under the <Decorators> element in web-beans.xml.

<Decorators>
    <myfwk:TimestampLogger/>
    <myfwk:IdentityLogger/>
</Decorators>

The order of the decorator declarations determines the decorator ordering. Decorators which occur earlier in the list are called first.

If the <Decorators> element is specified in more than one web-beans.xml document, a DeploymentException is thrown by the Web Bean manager at initialization time.

Decorators are called after interceptors.

Would it be better to unify interceptors and decorators into a single stack, so that they can be interleaved?

The Bean object for an interceptor must extend the abstract class Decorator.

public abstract class Decorator extends Bean<Object> {

	protected Decorator(Manager manager) {
		super(manager);
	}

	public abstract Class<?> getDelegateType();

	public abstract Set<Annotation> getDelegateBindingTypes();
	
	public abstract void setDelegate(Object instance, Object delegate);

}

The following method returns the ordered list of enabled decorators for a set of API types and a set of binding types.

public interface Manager {
      
    List<Decorator> resolveDecorators(Set<Class<?>> types, Annotation... bindingTypes);
    
    ...
    
}

The first argument is the set of API types of the decorated Web Bean. The annotations are binding types declared by the decorated Web Bean.

If two instances of the same binding type are passed to resolveDecorators(), a DuplicateBindingTypeException is thrown.

If an instance of an annotation that is not a binding type is passed to resolveDecorators(), an IllegalArgumentException is thrown.

If the set of API types is empty, an IllegalArgumentException is thrown.

The following algorithm must be used by the Web Bean manager when resolving decorators:

When a simple or enterprise Web Bean is created, the Web Bean manager must:

The resulting ordered list of decorator instances is called the decorator stack.

Whenever a business method is invoked on an instance of a simple Web Bean, enterprise Web Bean or EJB session, singleton, or message driven bean, the Web Bean manager intercepts the business method invocation and, after processing the interceptor stack, as defined in Section 6.2.11, “Interceptor invocation”, invokes decorators of the Web Bean.

The Web Bean manager searches for the first decorator in the decorator stack for the instance that implements the method that is being invoked as a business method. If no such decorator exists, the Web Bean manager invokes the business method of the Web Bean instance. Otherwise, the Web Bean manager calls the method of the decorator.

When any decorator is invoked by the Web Bean manager, it may in turn invoke a method of the delegate attribute. The Web Bean manager intercepts the delegate invocation and searches for the first decorator in the decorator stack for the instance such that:

If no such decorator exists, the Web Bean manager invokes the business method of the Web Bean instance. Otherwise, the Web Bean manager calls the method of the decorator.

Eventually, by recursion, the decorator stack is exhausted of uninvoked decorators.

Each observer method must have exactly one event parameter, of the same type as the event type it observes. When searching for observer methods for an event, the Web Bean manager considers the type and binding types of the event parameter.

If the event parameter does not explicitly declare any binding type, the observer method observes events with no binding type.

If the type of the event parameter contains type variables or wildcards, a DefinitionException is thrown by the Web Bean manager at initialization time.

A observer method may be declared using annotations by annotating a parameter @Observes. That parameter is the event parameter.

public void afterLogin(@Observes LoggedInEvent event) { ... }

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

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

The event parameter may declare binding types:

public void afterLogin(@Observes @Admin LoggedInEvent event) { ... }

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

<myapp:afterLogin>
    <Observes>
        <myapp:LoggedInEvent/>
    </Observes>
</myapp:afterLogin>

<myapp:afterLogin>
    <Observes>
        <myapp:LoggedInEvent>
            <myapp:Admin/>
        </myapp:LoggedInEvent>
    </Observes>
</myapp:afterLogin>

When an observer 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 parameters that match those declared in XML, a NonexistentMethodException is thrown by the Web Bean manager at initialization time.

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

public void afterLogin(@Observes LoggedInEvent event, @Manager User user, @Logger Log log) { ... }

public void afterAdminLogin(@Observes @Admin LoggedInEvent event, @Logger Log log) { ... }

<myapp:afterLogin>
    
    <Observes>
        <myapp:LoggedInEvent/>
    </Observes>
    
    <myapp:User>
        <myapp:Manager/>
    </myapp:User>
    
    <myfwk:Log>
        <myfwk:Logger/>
    </myfwk:Log>
    
</myapp:afterLogin>

<myapp:afterAdminLogin>
    
    <Observes>
        <myapp:LoggedInEvent>
            <myapp:Admin/>
        </myapp:LoggedInEvent>
    </Observes>
    
    <myfwk:Log>
        <myfwk:Logger/>
    </myfwk:Log>
    
</myapp:afterAdminLogin>

Conditional observers are observer methods which are notified of an event only if an instance of the Web Bean that defines the observer method already exists in the current context.

A conditional observers may be declared by annotating the event parameter with the @IfExists annotation.

public void refreshOnDocumentUpdate(@IfExists @Observes @Updated Document doc) { ... }

Conditional observers may be declared in XML by adding a child <IfExists> element to the <Observes> element.

<myapp:refreshOnDocumentUpdate>
    <Observes>
        <IfExists/>
        <myapp:Document>
            <myapp:Updated/>
        </myapp:Document>
    </Observes>
</myapp:refreshOnDocumentUpdate>

Transactional observers are observer methods which receive event notifications during the before or after completion phase of the transaction in which the event was fired. If no transaction is in progress when the event is fired, they are notified at the same time as other observers.

Transactional observers may be declared by annotating the event parameter of the observer method.

void onDocumentUpdate(@Observes @AfterTransactionSuccess @Updated Document doc) { ... }

Transactional observers may be declared in XML by a child element of the <Observes> element.

<myapp:onDocumentUpdate>
    <Observes>
        <AfterTransactionSuccess/>
        <myapp:Document>
            <myapp:Updated/>
        </myapp:Document>
    </Observes>
</myapp:onDocumentUpdate>

For every observer method of an enabled Web Bean, the Web Bean manager is responsible for providing and registering an appropriate implementation of the Observer interface, that delegates event notifications to the observer method.

The notify() method of the Observer implementation for an observer method either invokes the observer method immediately, or registers the observer method for later invocation during the transaction completion phase, via a JTA Synchronization object.

To invoke an observer method, the Web Bean manager must:

Observer methods may throw exceptions:

The observer object is registered by calling Manager.addObserver(), passing the event parameter type as the observed event type, and the binding types of the event parameter as the observed event binding types.

As usual, the binding type may have annotation members:

@EventBindingType
@Target(PARAMETER)
@Retention(RUNTIME)
public @interface Role {
    String value();
}

Consider the following event:

public void login() {
    final User user = ...;
    manager.fireEvent( new LoggedInEvent(user), 
            new RoleBinding() { public String value() { return user.getRole(); } );
}

Where RoleBinding is an implementation of the binding type Role:

public abstract class RoleBinding extends 
        AnnotationLiteral<Role> 
        implements Role {}

Then the following observer method will always be notified of the event:

public void afterLogin(@Observes LoggedInEvent event) { ... }

Whereas this observer method may or may not be notified, depending upon the value of user.getRole():

public void afterAdminLogin(@Observes @Role("admin") LoggedInEvent event) { ... }

As usual, the Web Bean manager uses equals() to compare event binding type member values.

An event parameter may have multiple binding annotations:

public void afterDocumentUpdatedByAdmin(@Observes @Updated @ByAdmin Document doc) { ... }

Then this observer method will only be notified if all the event binding types are specified when the event is fired:

manager.fireEvent( document, new UpdatedBinding() {}, new ByAdminBinding() {} );

Other, less specific, observers will also be notified of this event:

public void afterDocumentUpdated(@Observes @Updated Document doc) { ... }

public void afterDocumentEvent(@Observes Document doc) { ... }

A Web Bean may create an instance of a Web Bean with scope type @Dependent by calling Manager.getInstance() from the Web Bean constructor, the Web Bean remove method, initializer methods, producer methods, disposal methods, @PostConstruct and @PreDestroy callbacks and Web Beans interceptors or decorators for any of these methods.

An instance of a @Dependent scoped Web Bean is said to be a dependent object of a simple or enterprise Web Bean instance if:

An instance of a @Dependent scoped Web Bean is said to be a dependent object of a producer method Web Bean instance if:

An EJB bean may create an instance of a Web Bean with scope type @Dependent by calling Manager.getInstance() from initializer methods and @PostConstruct and @PreDestroy callbacks.

An Servlet may create an instance of a Web Bean with scope type @Dependent by calling Manager.getInstance() from initializer methods.

An instance of a @Dependent scoped Web Bean is said to be a dependent object of an EJB bean or Servlet if:

The Web Bean manager is responsible for destroying @Dependent scoped Web Bean instances by passing them to the Bean.destroy() method.

The Web Bean manager must:

Finally, the Web Bean manager is permitted to destroy any @Dependent scoped Web Bean instance at any time if the instance is no longer referenced by the application (excluding weak, soft and phantom references).

The Web Beans request context is provided by a built-in context object for the built-in scope type javax.webbeans.RequestScoped.

Open issue: currently it is impossible to intercept timeout methods. This needs to be fixed in EJB 3.1.

In a Java EE 5 environment, the Web Bean manager is not required to support an active request context during timeout method invocation.

Open issue: is the request context (and application context) active during servlet filter execution?

The Web Beans session context is provided by a built-in context object for the built-in passivating scope type javax.webbeans.SessionScoped.

The session scope is active during the service() method of any servlet in the web application.

The session context is shared between all servlet requests that occur in the same HTTP servlet session. The session context is destroyed when the HTTPSession is invalidated or times out.

The Web Beans application context is provided by a built-in context object for the built-in scope type javax.webbeans.ApplicationScoped.

The application context is shared between all servlet requests, web service invocations, EJB remote method invocations, EJB timeouts and message deliveries to message driven beans that execute within the same application. The application context is destroyed when the application is undeployed.

The Web Beans conversation context is provided by a built-in context object for the built-in passivating scope type javax.webbeans.ConversationScoped.

The conversation context provides access to state associated with a particular conversation. Every JSF request has an associated conversation. This association is managed automatically by the Web Bean manager according to the following rules:

Any conversation is in one of two states: transient or long-running.

All long-running conversations have a string-valued unique identifier, which may be set by the application when the conversation is marked long-running, or generated by the Web Bean manager.

The Web Bean manager provides a built-in Web Bean with API type javax.webbeans.Conversation, scope @RequestScoped, deployment type @Standard and binding type @Current, named javax.webbeans.conversation.

public interface Conversation {
   public void begin();
   public void begin(String id);
   public void end();
   public boolean isLongRunning();
   public String getId();
   public long getTimeout();
   public void setTimeout(long milliseconds);
}

If the conversation associated with the current JSF request is in the transient state at the end of a JSF request, it is destroyed, and the conversation context is also destroyed.

If the conversation associated with the current JSF request is in the long-running state at the end of a JSF request, it is not destroyed. Instead, it may be propagated to other requests according to the following rules:

When no conversation is propagated to a JSF request, the request is associated with a new transient conversation.

All long-running conversations are scoped to a particular HTTP servlet session and may not cross session boundaries.

In the following cases, a propagated long-running conversation cannot be restored and reassociated with the request:

If the propagated conversation cannot be restored, the request is associated with a new transient conversation.

The method Conversation.setTimeout() is a hint to the Web Bean manager that a conversation should not be destroyed if it has been active within the last given interval in milliseconds.

Open issue: allow the request to be blocked if the conversation cannot be restored.

The Web Bean manager ensures that a long-running conversation may be associated with at most one request at a time, by blocking or rejecting concurrent requests.

Open issue: define a mechanism for "blocking" requests. For example, allow the request to be redirected.

The Web Beans manager inspects the direct child elements of the Web Bean declaration. For each child element:

Type-level metadata is specified via direct child elements of the Web Bean declaration that represent Java annotation types.

The name of the child element is interpreted as the name of a Java annotation type in the package corresponding to the child element namespace.

For each child element, the Web Bean manager inspects the annotation type:

The Web Bean constructor for a simple Web Bean is declared by the list of direct child elements of the Web Bean declaration that represent Java class or interface types. The Web Bean manager interprets these elements as declaring parameters of the constructor.

<myapp:Order>
    <ConversationScoped/>
    <myapp:PaymentProcessor>
        <myapp:Asynchronous/>
    </myapp:PaymentProcessor>
    <myapp:User/>
</myapp:Order>

Each constructor parameter declaration is interpreted as an injection point declaration, as specified in Section 9.5, “Injection point declarations”.

If the simple Web Bean implementation class has exactly one constructor such that:

then the element is interpreted to represent that constructor, and that constructor is the Web Bean constructor.

If more than one constructor exists which satisfies these conditions, a DefinitionException is thrown by the Web Bean manager at initialization time.

If no constructor of the simple Web Bean implementation class satisfies these conditions, a NonexistentConstructorException is thrown by the Web Bean manager at initialization time.

For any constructor parameter, the API type declared in XML may be a subtype of the Java parameter type. In this case, the Web Bean manager will use the API type declared in XML when resolving the dependency.

A field of a Web Bean is declared by a direct child element of the Web Bean declaration. The name of the field is the same as the name of the element.

If a direct child element of a Web Bean declaration:

then it is interpreted as a field declaration.

If the Web Bean implementation class has a field with the same name as the child element, then the child element is interpreted to represent that field.

If the Web Bean implementation class does not have have a field with the specified name, a NonexistentFieldException is thrown by the Web Bean manager at initialization time.

If more than one child element represents the same field, a DefinitionException is thrown by the Web Bean manager at initialization time.

A field declaration may have an arbitrary number of direct child <value> elements in the Web Beans namespace.

Alternatively, a field declaration may have a direct child element that is not a <value> element. If so, the child element is interpreted as an injection point declaration, as specified in Section 9.5, “Injection point declarations”. If the declared type is not assignable to the Java type of the field, a DefinitionException is thrown by the Web Bean manager at initialization time.

If a field declaration has more than one direct child element, and at least one of these elements is not <value> element in the Web Beans namespace, a DefinitionException is thrown by the Web Bean manager at initialization time.

The API type declared in XML may be a subtype of the Java field type. In this case, the Web Bean manager will use the API type declared in XML when resolving the dependency.

An element that represents a field may declare an injected field or a field with an initial value.

The initial value of a field of a simple Web Bean or enterprise Web Bean with any one of the following types may be specified in XML:

The initial value of the field is specified in the body of an XML element representing the field.

<myapp:Config>
    <myapp:version>1.2.5</myapp:version>
    <myapp:timeout>1000</myapp:timeout>
    <myapp:administrators>
        <value>juan</value>
        <value>antonio</value>
        <value>sonia</value>
        <value>sara</value>
    </myapp:administrators>
</myapp:Config>

If a field with an initial value specified in XML is not of one of the listed types, or if the initial value is not specified in the correct format for the type of the field, a DefinitionException is thrown by the Web Bean manager at initialization time.

The initial value of a field of type java.util.List is specified by a list of <value> elements. The body of the value element is specified using the string value or unqualified name of the enumeration value.

If an element representing a field specifies both an initial value and a type declaration, a DefinitionException is thrown by the Web Bean manager at initialization time.

A method of a Web Bean is declared by a direct child element of the Web Bean declaration. The name of the declared method is the same as the name of the child element.

If a direct child element of a Web Bean declaration:

then it is interpreted as a method declaration.

A method declaration may have any number of direct child elements.

The Web Beans manager inspects the direct child elements of the method declaration. For each child element, the name of the element is interpreted as a Java type name in the package corresponding to the element's namespace. If no such Java type exists in the classpath, a NonexistentTypeException is thrown by the Web Bean manager at initialization time.

If a method declaration has more than one direct child element which is an <Initializer>, <Destructor>, <Produces>, <Disposes> or <Observes> element in the Web Beans namespace, a DefinitionException is thrown by the Web Bean manager at initialization time.

If a <Disposes> element does not contain exactly one direct child element, a DefinitionException is thrown by the Web Bean manager at initialization time.

If an <Observes> element does not contain exactly one direct child element that is not an <IfExists>, <AfterTransactionCompletion>, <AfterTransactionSuccess>, <AfterTransactionFailure> or <BeforeTransactionCompletion> element in the Web Beans namespace, a DefinitionException is thrown by the Web Bean manager at initialization time.

Each method parameter declaration is interpreted as an injection point declaration, as specified in Section 9.5, “Injection point declarations”.

If the Web Bean implementation class has exactly one method such that:

then the element is interpreted to represent that method.

If more than one method exists which satisfies these conditions, a DefinitionException is thrown by the Web Bean manager at initialization time.

If no method of the Web Bean implementation class satisfies these conditions, a NonexistentMethodException is thrown by the Web Bean manager at initialization time.

For any method parameter, the API type declared in XML may be a subtype of the Java parameter type. In this case, the Web Bean manager will use the API type declared in XML when resolving the dependency.

If more than one child element of a Web Bean declaration represents the same method of the Web Bean implementation class, a DefinitionException is thrown by the Web Bean manager at initialization time.

An element that represents a method may declare an initializer method, a Web Bean remove method, an observer method, a producer method or a disposal method. Alternatively, or additionally, it may declare method-level interceptor binding types.

The Web Bean manager inspects the direct child elements of the producer method declaration.

If there is more than one child <Produces> element in the Web Beans namespace, a DefinitionException is thrown by the Web Bean manager at initialization time.

The Web Bean manager inspects the direct child elements of the <Produces> element. For each child element, the name of the element is interpreted as a Java type name in the package corresponding to the child element namespace. If no such Java type exists in the classpath, a NonexistentTypeException is thrown by the Web Bean manager at initialization time.

If more than one child element represents a Java class or interface type, or if no child element represents a Java class or interface type, a DefinitionException is thrown by the Web Bean manager at initialization time.

Every XML producer method declaration has a direct child <Produces> element. This element must, in turn, have a direct child element which declares the return type of the producer method and which is interpreted by the Web Bean manager as a type declaration, as defined in Section 9.7, “Specifying API types and binding types”.

This type declaration specifies the return type and binding types of the producer method Web Bean. The return type is used to calculate the set of API types. The return type declared in XML must be a supertype or subtype of the Java method type. If the declared return type is not a supertype or subtype of the Java method type, a DefinitionException is thrown by the Web Bean manager at initialization time.

Method-level metadata for a producer method declaration is specified via direct child elements of the <Produces> element that represent Java annotation types.

The name of each child element is interpreted as the name of a Java annotation type in the package corresponding to the child element namespace. If the declared type is not a Java annotation type, a DefinitionException is thrown by the Web Bean manager at initialization time.

The Web Bean manager inspects the annotation type:

Decorator declarations must declare the delegate attribute. A delegate declaration is a direct child element of the decorator declaration. The name of the delegate attribute is the same as the name of the element.

If a direct child element of a decorator declaration:

then it is interpreted as a delegate declaration.

If a decorator declaration does not contain exactly one delegate declaration, a DefinitionException is thrown by the Web Bean manager at initialization time.

If the Web Bean implementation class has a field with the same name as the child element, then the child element is interpreted to represent that field.

If the Web Bean implementation class does not have have a field with the specified name, a NonexistentFieldException is thrown by the Web Bean manager at initialization time.

If a delegate declaration has more than one direct child element, a DefinitionException is thrown by the Web Bean manager at initialization time. This child element is a <Decorates> element in the Web Beans namespace. If the <Decorates> element does not, in turn, have exactly one direct child element, a DefinitionException is thrown by the Web Bean manager at initialization time.

The direct child element of the <Decorates> element is interpreted as a type declaration as specified by Section 9.7, “Specifying API types and binding types”. If the declared API type is not assignable to the type of the Java field, a DefinitionException is thrown by the Web Bean manager at initialization time.

The API type declared in XML may be a subtype of the Java field type. In this case, the Web Bean manager will use the API type declared in XML when resolving the dependency.

If simple Web Bean declaration that is not a decorator declaration contains a direct child element that in turn contains a direct child <Decorates> element, a DefinitionException is thrown by the Web Bean manager at initialization time.

Each direct child element of a <Deploy> element is interpreted as the declaring an enabled deployment type, as specified in Section 2.5.6, “Enabled deployment types”.

For each child element, the name of the child element is interpreted as the name of a Java annotation type in the package corresponding to the child element namespace. If no such Java type exists in the classpath, a DefinitionException is thrown by the Web Bean manager at initialization time. If the type is not a Web Beans deployment type, a DefinitionException is thrown by the Web Bean manager at initialization time.

If the same deployment type is declared more than once, a DefinitionException is thrown by the Web Bean manager at initialization time.

Each direct child element of an <Interceptors> element is interpreted as the declaring an enabled interceptor, as specified in Section 6.2.7, “Interceptor enablement and ordering”.

For each child element, the name of the child element is interpreted as the name of a Java class in the package corresponding to the child element namespace. If no such Java class exists in the classpath, a DefinitionException is thrown by the Web Bean manager at initialization time. If the class is not the implementation class of at least one interceptor, a DefinitionException is thrown by the Web Bean manager at initialization time.

If the same interceptor is declared more than once, a DefinitionException is thrown by the Web Bean manager at initialization time.

Each direct child element of a <Decorators> element is interpreted as the declaring an enabled decorator, as specified in Section 6.3.5, “Decorator enablement and ordering”.

For each child element, the name of the child element is interpreted as the name of a Java class in the package corresponding to the child element namespace. If no such Java class exists in the classpath, a DefinitionException is thrown by the Web Bean manager at initialization time. If the class is not the implementation class of at least one decorator, a DefinitionException is thrown by the Web Bean manager at initialization time.

If the same decorator is declared more than once, a DefinitionException is thrown by the Web Bean manager at initialization time.