Skip to content

Latest commit

 

History

History
333 lines (206 loc) · 14.3 KB

implementation_ee.asciidoc

File metadata and controls

333 lines (206 loc) · 14.3 KB
Raw

Addition to programming model for Jakarta EE

When running in Jakarta EE, the container must extend the rules defined in [implementation], and must also provide built-in support for injection and contextual lifecycle management of the following kinds of bean:

  • Session beans

  • Resources (Jakarta EE resources, persistence contexts, persistence units, remote EJBs and web services)

Jakarta EE and embeddable EJB containers are required by the Jakarta EE and EJB specifications to support EJB session beans and the Jakarta EE component environment. Other containers are not required to provide support for injection or lifecycle management of session beans or resources.

Managed beans in Jakarta EE

Which Java classes are managed beans in Jakarta EE?

When running in Jakarta EE, a top-level Java class is a managed bean if it meets requirements described in [what_classes_are_beans] or if it is defined to be a managed bean by any other Jakarta EE specification and if

  • It is not annotated with an EJB component-defining annotation or declared as an EJB bean class in ejb-jar.xml.

EJB Session beans

A session bean is a bean that is implemented by a session bean with an EJB 3.x client view that is not annotated with @Vetoed or in a package annotated @Vetoed. The basic lifecycle and semantics of EJB session beans are defined by the EJB specification.

A stateless session bean must belong to the @Dependent pseudo-scope. A singleton session bean must belong to either the @ApplicationScoped scope or to the @Dependent pseudo-scope. If a session bean specifies an illegal scope, the container automatically detects the problem and treats it as a definition error. A stateful session bean may have any scope.

When a contextual instance of a session bean is obtained via the dependency injection service, the behavior of SessionContext.getInvokedBusinessInterface() is specific to the container implementation. Portable applications should not rely upon the value returned by this method.

If the bean class of a session bean is annotated @Interceptor or @Decorator, the container automatically detects the problem and treats it as a definition error.

If the session bean class is a generic type, it must have scope @Dependent. If a session bean with a parameterized bean class declares any scope other than @Dependent, the container automatically detects the problem and treats it as a definition error.

EJB remove methods of session beans

If a session bean is a stateful session bean:

  • If the scope is @Dependent, the application may call any EJB remove method of a contextual instance of the session bean.

  • Otherwise, the application may not directly call any EJB remove method of any contextual instance of the session bean.

The session bean is not required to have an EJB remove method in order for the container to destroy it.

If the application directly calls an EJB remove method of a contextual instance of a session bean that is a stateful session bean and declares any scope other than @Dependent, an UnsupportedOperationException is thrown.

If the application directly calls an EJB remove method of a contextual instance of a session bean that is a stateful session bean and has scope @Dependent then no parameters are passed to the method by the container. Furthermore, the container ignores the instance instead of destroying it when Contextual.destroy() is called, as defined in [stateful_lifecycle].

Bean types of a session bean

The unrestricted set of bean types for a session bean contains all local interfaces of the bean and their superinterfaces. If the session bean has a no-interface view, the unrestricted set of bean types contains the bean class and all superclasses. In addition, java.lang.Object is a bean type of every session bean.

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

The resulting set of bean types for a session bean consists only of legal bean types, all other types are removed from the set of bean types.

Declaring a session bean

A session bean does not require any special annotations apart from the component-defining annotation (or XML declaration) required by the EJB specification. The following EJBs are beans:

@Singleton
class Shop { .. }
@Stateless
class PaymentProcessorImpl implements PaymentProcessor { ... }

A bean class may also specify a scope, bean name, stereotypes and/or qualifiers:

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

A session bean class may extend another bean class:

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

Specializing a session bean

If a bean class of a session bean X is annotated @Specializes, then the bean class of X must directly extend the bean class of another session bean Y. Then X directly specializes Y, as defined in [specialization].

If the bean class of X does not directly extend the bean class of another session bean, the container automatically detects the problem and treats it as a definition error.

For example, MockLoginActionBean directly specializes LoginActionBean:

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

Default bean name for a session bean

The default name for a session bean is the unqualified class name of the session bean class, after converting the first character to lower case.

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

Producer methods on EJB session bean

A producer method defined in an EJB session bean follows the rules defined in [producer_method] with the following addition:

  • A producer method defined in an EJB session bean must be either a business method exposed by a local business interface of the EJB or a static method of the bean class.

Declaring a producer method in an EJB session bean

A producer method declaration in an EJB session bean follows the rules defined in [declaring_producer_method] with the following addition:

  • if a non-static method of a session bean class is annotated @Produces, and the method is not a business method exposed by a local business interface of the session bean, the container automatically detects the problem and treats it as a definition error.

Producer field on EJB session bean

A producer field defined in an EJB session bean follows the rules defined in [producer_field] with the following addition:

  • A producer field defined in an EJB session bean must be a static field of the bean class.

Declaring a producer field in an EJB session bean

A producer field declaration in an EJB session bean follows the rules defined in [declaring_producer_field] with the following addition:

  • If a non-static field of an EJB session bean class is annotated @Produces, the container automatically detects the problem and treats it as a definition error.

Disposer methods on EJB session bean

A disposer method defined in an EJB session bean follows the rules defined in [disposer_method] with the following addition:

  • A disposer method defined in an EJB session bean must be either a business method exposed by a local business interface of the EJB or a static method of the bean class.

Declaring a disposer method on an EJB session bean

A disposer method declaration in an EJB session bean follows the rules defined in [declaring_disposer_method] with the following addition:

  • If a non-static method of an EJB session bean class has a parameter annotated @Disposes, and the method is not a business method exposed by a local business interface of the session bean, the container automatically detects the problem and treats it as a definition error.

Jakarta EE components

Most Jakarta EE components support injection and interception, as defined in the Jakarta EE Platform, Specification, table EE.5-1, but are not considered beans (as defined by this specification). EJBs, as defined in EJB Session beans are the exception.

The instance used by the container to service an invocation of a Jakarta EE component will not be the same instance obtained when using @Inject, instantiated by the container to invoke a producer method, observer method or disposer method, or instantiated by the container to access the value of a producer field. It is recommended that Jakarta EE components should not define observer methods, producer methods, producer fields or disposer methods. It is safe to annotate Jakarta EE components with @Vetoed to prevent them being considered beans.

Resources

A resource is a bean that represents a reference to a resource, persistence context, persistence unit, remote EJB or web service in the Jakarta EE component environment.

By declaring a resource, we enable an object from the Jakarta EE component environment to be injected by specifying only its type and qualifiers at the injection point. For example, if @CustomerDatabase is a qualifier:

@Inject @CustomerDatabase Datasource customerData;
@Inject @CustomerDatabase EntityManager customerDatabaseEntityManager;
@Inject @CustomerDatabase EntityManagerFactory customerDatabaseEntityManagerFactory;
@Inject PaymentService remotePaymentService;

The container is not required to support resources with scope other than @Dependent. Portable applications should not define resources with any scope other than @Dependent.

A resource may not have a bean name.

Declaring a resource

A resource may be declared by specifying a Jakarta EE component environment injection annotation as part of a producer field declaration. The producer field may be static.

  • For a Jakarta EE resource, @Resource must be specified.

  • For a persistence context, @PersistenceContext must be specified.

  • For a persistence unit, @PersistenceUnit must be specified.

  • For a remote EJB, @EJB must be specified.

  • For a web service, @WebServiceRef must be specified.

The injection annotation specifies the metadata needed to obtain the resource, entity manager, entity manager factory, remote EJB instance or web service reference from the component environment.

@Produces @WebServiceRef(lookup="java:app/service/PaymentService")
PaymentService paymentService;
@Produces @EJB(ejbLink="../their.jar#PaymentService")
PaymentService paymentService;
@Produces @Resource(lookup="java:global/env/jdbc/CustomerDatasource")
@CustomerDatabase Datasource customerDatabase;
@Produces @PersistenceContext(unitName="CustomerDatabase")
@CustomerDatabase EntityManager customerDatabasePersistenceContext;
@Produces @PersistenceUnit(unitName="CustomerDatabase")
@CustomerDatabase EntityManagerFactory customerDatabasePersistenceUnit;

The bean type and qualifiers of the resource are determined by the producer field declaration.

If the producer field declaration specifies a bean name, the container automatically detects the problem and treats it as a definition error.

If the matching object in the Jakarta EE component environment is not of the same type as the producer field declaration, the container automatically detects the problem and treats it as a definition error.

Bean types of a resource

The unrestricted set of bean types for a resource is determined by the declared type of the producer field, as specified by [producer_field_types].

The resulting set of bean types for a resource consists only of legal bean types, all other types are removed from the set of bean types.

Additional built-in beans

A Jakarta EE or embeddable EJB container must provide the following built-in beans, all of which have qualifier @Default:

  • a bean with bean type jakarta.transaction.UserTransaction, allowing injection of a reference to the JTA UserTransaction, and

  • a bean with bean type java.security.Principal, allowing injection of a Principal representing the current caller identity.

A servlet container must provide the following built-in beans, all of which have qualifier @Default:

  • a bean with bean type jakarta.servlet.http.HttpServletRequest, allowing injection of a reference to the HttpServletRequest

  • a bean with bean type jakarta.servlet.http.HttpSession, allowing injection of a reference to the HttpSession,

  • a bean with bean type jakarta.servlet.ServletContext, allowing injection of a reference to the ServletContext,

These beans are passivation capable dependencies, as defined in [passivation_capable_dependency].

If a Jakarta EE component class has an injection point of type UserTransaction and qualifier @Default, and may not validly make use of the JTA UserTransaction according to the Jakarta EE platform specification, the container automatically detects the problem and treats it as a definition error.

Injected fields in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined for bean classes in [injected_fields] to Jakarta EE component classes supporting injection.

Initializer methods in Jakarta EE

When running in Jakarta EE, the container must extend the rules defined for bean classes in [initializer_methods] to Jakarta EE component classes supporting injection. The container must also ensure that:

  • An initializer method defined in an EJB session bean is not required to be a business method of the session bean.