JSR 299: Web Beans. Web Beans Expert Group. Version: Public Review

Transcription

1 JSR 299: Web Beans Web Beans Expert Group Version: Public Review

2 Table of Contents 1. Architecture Contracts Supported environments Relationship to other specifications Relationship to EJB Relationship to JSF Relationship to Java Servlets Relationship to Common Annotations for the Java Platform Introductory examples JSF example EJB example Interceptor example Decorator example Web Bean definition Functionality provided by the Web Bean manager to the Web Bean Web Bean API types Binding types Default binding type Defining binding types Declaring the binding types of a Web Bean using annotations Declaring the binding types of a Web Bean using XML Using binding annotations on injected fields Using binding annotations on method or constructor parameters Web Bean scopes Built-in scope types Defining new scope types Declaring the Web Bean scope using annotations Declaring the Web Bean scope using XML Default scope Deployment types Built-in deployment types Defining new deployment types Declaring the deployment type of a Web Bean using annotations Declaring the deployment type of a Web Bean using XML Default deployment type Enabled deployment types Deployment type precedence Web Bean names Declaring the Web Bean name using annotations Declaring the Web Bean name using XML Default Web Bean names Web Beans with no name Stereotypes Defining new stereotypes Declaring the stereotypes for a Web Bean using annotations Declaring the stereotypes for a Web Bean using XML Stereotype restrictions Built-in stereotypes Specialization Direct and indirect specialization Inconsistent specialization Web Bean implementation Restriction upon Web Bean instantiation Simple Web Beans Which Java classes are simple Web Beans? API types of a simple Web Bean Declaring a simple Web Bean using annotations...25 JSR-299 Public Review ii

3 JSR 299: Web Beans Declaring a simple Web Bean using XML Web Bean constructors Declaring a Web Bean constructor using annotations Declaring a Web Bean constructor using XML Web Bean constructor parameters Specializing a simple Web Bean Default name for a simple Web Bean Enterprise Web Beans Which EJBs are enterprise Web Beans? API types of an enterprise Web Bean Declaring an enterprise Web Bean using annotations Declaring an enterprise Web Bean using XML Web Bean remove methods Declaring a Web Bean remove method using annotations Declaring a Web Bean remove method using XML Remove method parameters Specializing an enterprise Web Bean Default name for an enterprise Web Bean Enterprise bean proxies Producer methods API types of a producer method Declaring a producer method using annotations Declaring a producer method using XML Producer method parameters Specializing a producer method Disposal methods Disposed parameter of a disposal method Declaring a disposal method using annotations Declaring a disposal method using XML Disposal method parameters Disposal method resolution Default name for a producer method JMS endpoints API types of a JMS endpoint Declaring a JMS endpoint using XML Injected fields Declaring an injected field using annotations Declaring an injected field using XML Initializer methods Declaring an initializer method using annotations Declaring an initializer method using XML Initializer method parameters binding type Support for Common Annotations The Bean object for a Web Bean Lookup, dependency injection and EL resolution Unsatisfied and ambiguous dependencies Primitive types and null values Injected reference validity Client proxies Unproxyable API types Client proxy invocation The default binding type at injection points Generic type literals Annotation type literals The Manager object Instance resolution Dynamic lookup Typesafe resolution algorithm Binding annotations with members Multiple binding annotations EL name resolution...50 JSR-299 Public Review iii

4 JSR 299: Web Beans Name resolution algorithm Integration with Unified EL Web Bean lifecycle Creation Destruction Lifecycle of simple Web Beans Lifecycle of stateful session enterprise Web beans Lifecycle of stateless session and singleton enterprise Web Beans Lifecycle of producer methods Lifecycle of JMS endpoints Lifecycle of EJB beans Lifecycle of Servlets Interceptors and decorators Business methods Interceptors Business method interceptors Lifecycle callback interceptors Support Interceptor bindings Interceptor binding types with additional interceptor bindings Interceptor bindings for stereotypes Web Beans interceptors Declaring a Web Beans interceptor using annotations Declaring a Web Beans interceptor using XML Binding a Web Beans interceptor to a Web Bean or EJB bean Binding a Web Beans interceptor using annotations Binding a Web Beans interceptor using XML Interceptor enablement and ordering The Interceptor object for an interceptor Interceptor resolution Interceptors with multiple binding types Interceptor binding types with members Interceptor stack creation Interceptor invocation Decorators Declaring a decorator using annotations Declaring a decorator using XML Decorator delegate attributes Decorated types of a decorator Decorator enablement and ordering The Decorator object for a decorator Decorator resolution Decorator stack creation Decorator invocation Events Event types and binding types Firing an event via the Manager interface Observing events via the Observer interface Observer invocation Observer methods Event parameter of an observer method Declaring an observer method using annotations Declaring an observer method using XML Observer method parameters Conditional observers Transactional observers Observer object for an observer method The Event interface Observer resolution Event binding annotations with members Multiple event binding annotations Scopes and contexts...77 JSR-299 Public Review iv

5 JSR 299: Web Beans 8.1. The Context interface Normal scopes and pseudo-scopes Dependent pseudo-scope Dependent objects of a simple or enterprise Web Bean Dependent objects of a producer method Dependent objects of an EJB bean or Servlet Dependent object destruction Passivating scopes and serialization Context management for built-in scopes Request context lifecycle Session context lifecycle Application context lifecycle Conversation context lifecycle Context management for custom scopes XML based metadata XML namespace for a Java package Web Bean declarations Child elements of a Web Bean declaration Type-level metadata for a Web Bean Web Bean constructor declarations Fields of a Web Bean Field initial value declarations Methods of a Web Bean Producer method declarations Child elements of a producer method declaration Return type and binding types of a producer method Method-level metadata for a producer method Interceptor and decorator declarations Decorator delegate attribute Injection point declarations Inline Web Bean declarations Specifying API types and binding types Annotation members Deployment declarations The <Deploy> declaration The <Interceptors> declaration The <Decorators> declaration Packaging and deployment Web Bean discovery Web Bean registration EJB lookup Initialization event Java EE integration Exceptions Definition errors Deployment problems Execution errors JSR-299 Public Review v

6 Chapter 1. Architecture Web Beans provides a powerful new set of services to Java EE components. This specification defines: The lifecycle and interactions of stateful components bound to well-defined contexts, where the set of contexts is extensible A sophisticated, typesafe dependency injection mechanism, including a facility for choosing between various components that implement the same Java interface at deployment time Integration with the Unified Expression Language (EL), allowing any component to be used directly within a JSF or JSP page Generalization of the method and component lifecycle interceptors defined by EJB 3.0 to other kinds of components, along with an improved approach to binding interceptors to components and a new type of interceptor, called a decorator An event notification model A web conversation context in addition to the three standard web contexts defined by the Java Servlet specification An SPI allowing third-party frameworks that execute in the Java EE environment to integrate cleanly with Web Beans To take advantage of these facilities, the Java EE component developer provides additional component-level and application-level metadata in the form of Java annotations and/or XML-based deployment descriptors. A Java EE component with a lifecycle bound to a Web Beans context is called a Web Bean. Any Web Bean may be injected into other Java EE components by the Web Beans dependency injection service. The use of Web Beans significantly simplifies the task of creating Java EE applications by integrating the Java EE web tier with Java EE enterprise services. In particular, Web Beans allows EJB 3 components to be used as JSF managed beans, thus integrating the the component models of EJB and JSF and significantly simplifying the programming model when EJB and JSF are used together. In an environment that supports Web Beans, all EJB 3 session and singleton beans are Web Beans no Web Beans specific metadata is required. Furthermore, Web Beans makes it easy to use most plain Java classes as Java EE components that may inject, or be injected into, other Java EE components such as EJBs or Servlets. Web Beans promotes plain Java classes to the status of managed Java EE components. In particular, in an environment that supports Web Beans, all JavaBeans are Web Beans no Web Beans specific metadata is required. Even when EJB, or JSF, or both, are not used, Web Beans may be used to simplify development of the business-logic layer of an application. It is even possible for applications developed using third-party frameworks to take advantage of the services provided by Web Beans via a framework integration SPI Contracts This specification defines the responsibilities of a user who writes an application that executes inside an environment that supports Web Beans and uses the functionality provided by Web Beans, along with responsibilities of a vendor who implements the functionality defined by this specification and provides a runtime environment in which Web Beans execute the Web Bean manager. Both the application that uses Web Beans and the Web Bean manager are written to comply with Java EE contracts and may take advantage of the functionality provided by Java EE. The Web Bean manager may be provided by a Java EE container vendor as integrated functionality of the Java EE container or embeddable EJB Lite implementation. Alternatively, a plugin Web Bean manager may be provided by some third-party for use with various Java EE containers and embeddable EJB Lite implementations Supported environments A Web Bean application may be designed to execute in either the Java EE 6, Java EE 5 or Java SE environments. When a Web Bean application executes in a Java SE environment, an embeddable EJB Lite implementation provides the Java EE services. JSR-299 Public Review 1

7 Architecture All plugin Web Bean managers are required to support any Java EE 6 compliant container and any embeddable EJB Lite implementation. An integrated Web Bean manager is not required to support any environment other than that in which it is integrated. A compliant plugin Web Bean manager may optionally support Java EE 5. Certain functionality defined in this specification is optional when the Web Bean manager executes in a Java EE 5 environment. This is the case only when explicitly noted in this specification. All other functionality defined by this specification must be supported by a compliant plugin Web Bean manager that supports Java EE 5 when it executes in the Java EE 5 environment. A plugin Web Bean manager integrates with the Java EE container or embeddable EJB Lite implementation via standard Java EE APIs such as JNDI, EJB interceptors and servlet filters Relationship to other specifications An application developer using Web Beans creates Java EE components such as EJBs, Servlets and JavaBeans and then provides additional Web Beans metadata that defines additional behavior in terms of the Web Beans context model. These components may take advantage of the services defined by this specification, together with the enterprise and presentational aspects defined by other Java EE platform technologies. This specification defines the collaboration between the Web Bean manager and Java EE component technologies such as EJB, JavaServer Faces and Java Servlets. In addition, this specification defines an SPI that allows a Web Bean manager to be integrated with alternative, nonplatform technologies, for example, alternative web presentation technologies. Open issue: the Web Beans annotations for dependency injection, scope and interceptor binding are currently defined in the package javax.webbeans. To make these annotations more easily consumable by other specifications, should they instead be categorized by concern into packages such as javax.dependency, javax.contexts and javax.interceptors? Relationship to EJB 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 Relationship to JSF 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. JSR-299 Public Review 2

8 Architecture The Web Bean manager integrates with JSF via standard JSF APIs Relationship to Java Servlets 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! Relationship to Common Annotations for the Java Platform 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 Introductory examples The following examples demonstrate the Web Beans programming model JSF example 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 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; 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 public class Login Credentials EntityManager userdatabase; private User user; JSR-299 Public Review 3

9 Architecture 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() { User getcurrentuser() { if (user==null) { throw new NotLoggedInException(); else { return user; annotation is a scope type that specifies the lifecycle of instances of Login. 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 annotation causes a JPA EntityManager to be injected by the Web Bean manager. annotation is also a binding annotation. The method 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 public class DocumentEditor Document User 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 EJB example Our Login class may take advantage of the functionality defined @Model public class Login Credentials credentials; JSR-299 Public Review 4

10 EntityManager userdatabase; private public void login() {... public void logout() { user = null; public boolean isloggedin() { @LoggedIn User getcurrentuser() {... annotation specifies that this Web Bean is also an EJB stateful session bean. annotations declare the EJB transaction demarcation and security attributes Interceptor example 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 public class AuthorizationInterceptor User 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 annotation identifies the AuthorizationInterceptor class as a Web Beans interceptor. annotation is a custom interceptor Secure { annotation is used to apply the interceptor to a Web Beans or EJB public class DocumentEditor Document User EntityManager public void save() { JSR-299 Public Review 5

11 Architecture 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 Decorator example 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 public abstract class DataAccessAuthorizationDecorator implements DataAccess DataAccess 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; annotation identifies the DataAccessAuthorizationDecorator class as a Web Beans decorator. 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. JSR-299 Public Review 6

12 Architecture 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. JSR-299 Public Review 7

13 Chapter 2. Web Bean definition A Web Bean is a Java EE component that bears additional metadata defining its lifecycle and interactions with other components according to the Web Beans context model. Speaking more abstractly, a Web Bean is a source of contextual objects which define application state and/or logic. These objects are called instances of the Web Bean. The Web Bean manager creates and destroys these instances and associates them with the appropriate Web Beans context. Instances of a Web Bean may be injected into other objects (including other Web Bean instances) that execute in the same context, and may be used in EL expressions that are evaluated in the same context. A Web Bean comprises the following attributes: A (nonempty) set of API types A (nonempty) set of binding annotation types A scope A deployment type Optionally, a Web Bean name A set of interceptor binding types A Web Bean implementation In most cases, a Web Bean developer provides the Web Bean implementation by writing business logic in Java code. The developer then defines the remaining attributes by providing additional Web Beans specific metadata, or by allowing them to be defaulted by the Web Bean manager. In certain other cases, for example JMS endpoints defined in Section 3.5, JMS endpoints, the developer provides only the Web Beans specific metadata and the Web Bean implementation is provided by the Web Bean manager. It is sometimes convenient to use XML instead of annotations to define this metadata. The web-beans.xml file format defined in Chapter 9, XML based metadata supports XML declaration of Web Beans. A Web Bean implementation may be a Java class, an EJB session or singleton bean class, a producer method or a JMS queue or topic, as specified in Chapter 3, Web Bean implementation. The other attributes of the Web Bean are either: declared explicitly by annotating the implementation class, declared explicitly in web-beans.xml, or defaulted by the Web Bean manager. The deployment type, API types and binding types of a Web Bean determine where its instances will be injected by the Web Bean manager. The Web Bean developer may also create Web Beans interceptors and/or decorators or reuse existing interceptors and/or decorators. The interceptor binding types of a Web Bean determine which interceptors will be applied at runtime. The API types and binding types of a Web Bean determine which decorators will be applied at runtime. Interceptors, decorators and interceptor binding types are specified in Chapter 6, Interceptors and decorators. A Web Bean implementation may produce or consume events. The Web Beans event notification facility is specified in Chapter 7, Events Functionality provided by the Web Bean manager to the Web Bean A Web Bean is provided by the Web Bean manager with the following capabilities: transparent creation and destruction and scoping to a particular Web Beans context, specified in Chapter 5, Web Bean lifecycle and Chapter 8, Scopes and contexts, JSR-299 Public Review 8

14 Web Bean definition scoped resolution by API type and binding annotation type when injected into a Java-based client, as defined by Section 4.9, Instance resolution, scoped resolution by name when used in a Unified EL expression, as defined by Section 4.10, EL name resolution, lifecycle callbacks and automatic injection of other Web Bean instances, specified in Chapter 3, Web Bean implementation, method interception, callback interception, and decoration, as defined in Chapter 6, Interceptors and decorators, and event notification, as defined in Chapter 7, Events Web Bean API types A Web Bean API type defines a client-visible type of the Web Bean. A Web Bean may have multiple API types. For example, the following Web Bean has three API types: public class BookShop extends Business implements Shop<Book> {... The API types are BookShop, Business and Shop<Book>. Meanwhile, this EJB has only the local interfaces BookShop and Auditable as API types, since the bean class is not a client-visible public class BookShopBean extends Business implements BookShop, Auditable {... The rules for determining the set of API types for a Web Bean are defined in Chapter 3, Web Bean implementation. The API types of a Web Bean are used by the resolution algorithms defined in Chapter 4, Lookup, dependency injection and EL resolution. An API type may be a parameterized type with an actual type parameter. For the purposes of the typesafe resolution algorithm defined in Section 4.9.2, Typesafe resolution algorithm, parameterized API types are considered identical by the Web Bean manager only if both the type and the type parameters (if any) are identical. However, API types may not declare a type variable or wildcard. Aside from this restriction, almost any Java type may be an API type of a Web Bean: An API type may be an interface, a concrete class or an abstract class, and may be declared final or have final methods. An API type may be an array type. Two array types are considered identical only if the element type is identical. An API type may be a primitive types. Primitive types are considered to be identical to their corresponding wrapper types in java.lang. However, certain additional restrictions are specified in Section 4.4.1, Unproxyable API types for Web Beans with a normal scope type, as defined in Section 8.2, Normal scopes and pseudo-scopes. All Web Beans have the API type java.lang.object. A client of a Web Bean may typecast its reference to any instance of the Web Bean to any API type of the Web Bean. For example, if our simple Web Bean was injected to the following Shop<Book> bookshop; Then the following typecast is legal and will not result in an exception: JSR-299 Public Review 9

15 Web Bean definition Business biz = (Business) bookshop; Likewise, if our EJB was injected to the following BookShop bookshop; Then the following typecast is legal and will not result in an exception: Auditable aud = (Auditable) bookshop; Open issue: currently it is impossible for the client of a stateful session bean to typecast its reference to a different local interface. We need a new API defined by the EJB specification Binding types For a given API type, there may be multiple Web Beans which implement the type. For example, an application may have two implementations of the interface PaymentProcessor: class SynchronousPaymentProcessor implements PaymentProcessor {... class AsynchronousPaymentProcessor implements PaymentProcessor {... A client that needs a PaymentProcessor that processes payments synchronously needs some way to distinguish between the two different implementations. One approach would be for the client to explicitly specify the class that implements that PaymentProcessor interface. However, this approach creates a hard dependence between client and implementation exactly what use of the interface was designed to avoid! A Web Beans binding type represents some client-visible semantic of an API implementation that is satisfied by some implementations of the API (and not by others). For example, we could introduce binding types representing synchronicity and asynchronicity. In Java code, binding types are represented by class SynchronousPaymentProcessor implements PaymentProcessor class AsynchronousPaymentProcessor implements PaymentProcessor {... Finally, binding types are applied to injection points to distinguish which implementation is required by the client. For example, when the Web Bean manager encounters the following injected field, an instance of SynchronousPaymentProcessor will be PaymentProcessor paymentprocessor; But in this case, an instance of AsynchronousPaymentProcessor will be PaymentProcessor paymentprocessor; The Web Bean manager inspects the binding annotations and type of the injected attribute to determine the Web Bean instance to be injected, according to the resolution algorithm defined in Chapter 4, Lookup, dependency injection and EL resolution. Binding types are also used as event selectors by observers of Web Beans events, as defined in Chapter 7, Events, and to bind decorators to Web Beans, as specified in Section 6.3, Decorators. JSR-299 Public Review 10

16 Web Bean definition Default binding type 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 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) { Defining binding types A binding type is a Java annotation defined FIELD, PARAMETER, TYPE) All binding types must specify meta-annotation. @Target({METHOD, FIELD, PARAMETER, TYPE) @Target({METHOD, FIELD, PARAMETER, TYPE) Asynchronous { A binding annotation may define @Target({METHOD, FIELD, PARAMETER, TYPE) PayBy { PaymentMethod value(); Binding annotation member values are significant to the typesafe resolution algorithm Declaring the binding types of a Web Bean using annotations A Web Bean's binding types are declared by annotating the implementation class or producer method with the binding class LdapAuthenticator implements Authenticator {... public class public List<Product> JSR-299 Public Review 11

17 Web Bean definition public List<Product> public List<Product> getshoppingcart() {... Any Web Bean may declare multiple class SynchronousReliablePaymentProcessor implements PaymentProcessor {... If no binding type is explicitly specified, the default binding type is assumed Declaring the binding types of a Web Bean using XML 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 Using binding annotations on injected fields 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 Authenticator authenticator; A Web Bean may only be injected to an injection point if it has all the binding types of the PaymentProcessor paymentprocessor; For the case of producer methods, the binding annotation help determine exactly which producer method is List<Product> List<Product> 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 Using binding annotations on method or constructor parameters Binding annotations may be applied to parameters of producer methods, initializer methods, disposal methods, Web Bean JSR-299 Public Review 12

18 Web Bean definition 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 PaymentProcessor PaymentProcessor 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 Web Bean scopes Unlike JSF managed beans, Java EE components such as Servlets, EJBs and JavaBeans do not have a well-defined scope. These components are either: singletons, such as EJB singleton beans, whose state is shared between all clients, stateless objects, such as Servlets and stateless session beans, which do not contain client-visible state, or objects that must be explictly created and destroyed by their client, such as JavaBeans and stateful session beans, whose state is shared by explicit reference passing between clients. Scoped objects, by contrast, exist in a well-defined context: they may be automatically created when needed and then automatically destroyed when the context in which they were created ends, and their state is automatically shared by clients that execute in the same context. All Web Beans have a scope. The scope of a Web Bean determines the lifecycle of its instances, and which instances of the Web Bean are visible to instances of other Web Beans, as defined in Chapter 8, Scopes and contexts. A scope type is represented by an annotation type. For example, an object that represents the current user is represented by a session User getcurrentuser() {... An object that represents an order is represented by a conversation scoped public class Order {... A list that contains the results of a search screen might be represented by a request @Named("orders") JSR-299 Public Review 13

19 Web Bean definition List<Order> getordersearchresults() {... The set of scope types is extensible Built-in scope types There are several standard scope types defined by Web annotations defined in Section 8.5, Context management for built-in scopes represent the standard scopes defined by the Java Servlets specification. annotation represents the Web Beans conversation scope defined in Section 8.5.4, Conversation context lifecycle. In addition, there is pseudo-scope for dependent objects, as defined in Section 8.3, Dependent pseudo-scope Defining new scope types A Web Beans scope type is a Java annotation defined METHOD) All scope types must also specify meta-annotation. For example, the following annotation declares a "business 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 ) Declaring the Web Bean scope using annotations 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 public class ProductList implements DataModel {... public class @WishList public List<Product> @ShoppingCart public List<Product> getshoppingcart() {... Likewise, a Web Bean with the custom business process scope may be declared by annotating it with 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 Declaring the Web Bean scope using XML If the Web Bean is declared in web-beans.xml, the scope may be specified using the scope annotation type name: JSR-299 Public Review 14

20 Web Bean definition <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 Default scope 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 the Web Bean does not declare any stereotype with a declared default scope, the default scope for the Web Bean If all stereotypes declared by the Web Bean that have some declared default scope have the same default scope, then that scope is the default scope for the Web Bean. If there are two different stereotypes declared by the Web Bean that declare different default scopes, then there is no default scope and the Web Bean must explicitly declare a scope. If it does not explicitly declare a scope, a DefinitionException is thrown by the Web Bean manager at initialization time. If a Web Bean explicitly declares a scope, any default scopes declared by stereotypes are ignored Deployment types In many applications, there are various implementations of a particular API, and the implementation used at runtime varies between different deployments of the system. Web Beans allows the developer to associate a particular implementation of an API with a certain deployment scenario. A Web Beans deployment type represents a deployment scenario. Web Beans may be classified by deployment type, and thereby associated with various deployment scenarios. Deployment types allow the Web Bean manager to identify which Web Beans should be enabled for use in a particular deployment of the system. The deployment type also determines the precedence of a Web Bean, used by the resolution algorithms specified in Chapter 4, Lookup, dependency injection and EL resolution. The set of deployment types is extensible Built-in deployment types There are two standard deployment types defined by Web All standard Web Beans defined by this specification, and provided by the Web Bean manager, are defined using 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 deployment type unless explicitly required by this specification. Application Web Beans may be defined using deployment type Defining new deployment types A Web Beans deployment type is a Java annotation defined METHOD) All JSR-299 Public Review 15

21 Web Bean definition deployment types must also specify 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 Australian { This deployment type might be used by a third-party framework that extends DaoFramework { This deployment type might be used to define mock objects for Mock { Declaring the deployment type of a Web Bean using annotations 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 public class Order { This Web Bean has the 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 public class Login public User getuser() {... This producer method has the public class 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. JSR-299 Public Review 16

22 Web Bean definition Declaring the deployment type of a Web Bean using XML 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 Default deployment type 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: If a Web Bean does not declare any stereotype with a declared default deployment type, then the default deployment type Otherwise, the default deployment type for the Web Bean is the highest-precedence default deployment type declared by any stereotype declared by the Web Bean. Thus, the following declarations are public class Order { public class Order { If a Web Bean explicitly declares a deployment type, any default deployment type declared by stereotypes are ignored Enabled deployment types 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> JSR-299 Public Review 17