Servlet Annotation and Dependency Injection

WebLogic Annotation for Web Components 8-1

8

WebLogic Annotation for Web Components

[9] This chapter describes how to annotate Web components in WebLogic Server 12.1.3.

This chapter includes the following sections:

■ Section 8.1, "Servlet Annotation and Dependency Injection"

■ Section 8.2, "Annotating Servlets"

8.1 Servlet Annotation and Dependency Injection

The servlet 3.0 specification (see http://jcp.org/en/jsr/detail?id=315) provides annotations to enable declarative-style programming.

The servlet specification states that annotations can be defined on certain Web components, such as servlets, filters, listeners, and tag handlers. The annotations are used to declare dependencies on external resources. The container will detect annotations on such components and inject necessary dependencies before the component's life cycle methods are invoked. Dependency Injection (DI) will only be done on certain components, as described in Section 8.1.1, "Web Component Classes That Support Annotations".

Annotation processing and DI will be performed on all Web applications that have the version set to 2.5 or higher. However, annotation processing is expensive and it can increase the deployment time for Web applications depending on the size of the included classes. Set the metadata-complete attribute to true in the web.xml

descriptor if your Web application does not have any annotations and if you have the version set to 2.5 or higher to avoid unnecessary scanning of the Web applications classes for annotations. Alternatively, you can turn off annotation processing and DI for all the Web applications by setting -Dweblogic.servlet.DIDisabled=true flag when starting WebLogic Server.

For more information about using Java EE annotations and dependency injection with WebLogic Server applications, see "Using Java EE Annotations and Dependency Injection" and "Using Contexts and Dependency Injection for the Java EE Platform" in Developing Applications for Oracle WebLogic Server. For detailed information about

Note: This release of WebLogic Server deprecates WebLogic Server-specific annotations: @WLServlet, @WLFilter, @WLInitParam in favor of the standard annotations defined in the servlet 3.0 specification. Also, instead of

weblogic.servlet.http.AbstractAsyncServlet, you should use the standard asynchronous processing model defined in the servlet 3.0 specification.

Servlet Annotation and Dependency Injection

EJB-specific annotations for WebLogic Server Enterprise JavaBeans, see Developing Enterprise JavaBeans for Oracle WebLogic Server.

If you selected to install the server examples, you will find this servlet 3.0 annotation code example, "Using Annotations for Servlets, Filters and Listeners," in the EXAMPLES_

HOME\wl_server\examples\src\examples\javaee6\servlet directory of your

WebLogic Server distribution, where EXAMPLES_HOME represents the directory in which the WebLogic Server code examples are configured. For more information about the WebLogic Server code examples, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.

8.1.1 Web Component Classes That Support Annotations

This section describes the behavior of annotations and dependency injection (DI) of resources in a Java EE compliant Web container.

The Web container only processes annotations for the types of classes listed in Table 8–1.

The Web container will not process annotations on classes like Java Beans and other helper classes. The Web container follows these steps to achieve DI:

1. Annotation Processing—The Web container processes annotations during the Web application deployment phase. As annotations are processed, the container figures out the relevant entries in the descriptor that get affected by the annotation and updates the descriptor tree. The servlet specification indicates that all annotations can be declared in the descriptor by defining an injection target. The Web

container updates the descriptor tree with the injection targets so that as deployment continues the JNDI tree is updated with the necessary entries.

2. Dependency Injection (DI)—DI is done when instances are created (for the types listed in Table 8–1). For listeners and filters, this occurs during the deployment phase, and for servlets it can occur during deployment or run time.

8.1.2 Annotations Supported By a Web Container

Table 8–1 Web Components and Interfaces Supporting Annotations and Dependency Injection

Component Type Interfaces

Servlets javax.servlet.Servlet

Filters javax.servlet.Filter

Listeners javax.servlet.ServletContextListener

javax.servlet.ServletContextAttributeListener javax.servlet.ServletRequestListener

javax.servlet.ServletRequestAttributeListener javax.servlet.http.HttpSessionListener

javax.servlet.http.HttpSessionAttributeListener javax.servlet.AsyncListener

Tag handlers javax.servlet.jsp.tagext.SimpleTag javax.servlet.jsp.tagext.BodyTag

Note: In any Web application component, if one DI fails, it will cause all subsequent DIs upon the same component to be ignored.

Servlet Annotation and Dependency Injection

WebLogic Annotation for Web Components 8-3 The Web container makes use of the Java EE container's annotation processing and dependency injection mechanisms to achieve this functionality.

The specification states that the Web container should not process annotations when metadata-complete attributes are set to true in the web.xml descriptor. If annotations are properly defined and annotation processing succeeds and dependencies are properly injected, the annotated fields are initialized properly and annotated methods are invoked at the proper phase in the life cycle. If DI fails, these annotated fields will be null.

8.1.2.1 Fault Detection and Recovery

Any failure during annotation processing will yield a deployment exception that will prevent deployment of the Web application. If a failure happens during DI, the container will log a warning message in the server logs indicating the reason for the failure. The annotated fields in the instance of the class will be null and any life cycle annotated methods will not be invoked in case of DI failure.

8.1.2.2 Limitations

The WebLogic servlet container supports annotations on Web components that are declared in the web.xml descriptor. Any listeners, filters or servlets registered Table 8–2 List of Supported Annotations

@Annotation Specification Reference

DeclaresRoles 15.5.1

EJB 15.5.2

EJBs 15.5.3

PersistenceContext 15.5.5

PersistenceUnit 15.5.7

PersistenceUnits 15.5.8

PersistenceContexts 15.5.6

PostConstruct 15.5.9

PreDestroy 15.5.10

Resource 15.5.4

Resources 15.5.11

WebServiceRef 15.5.13

WebServiceRefs 15.5.14

RunAs 15.5.12

Note: If multiple methods in a Web component class, such as a servlet, filter, and such, are annotated with PostConstruct or PreDestroy, then the Web component will fail to deploy such an application. Similarly, if an EJB component class, such as a session bean, is annotated with PostConstruct or PreDestroy, or an EJB interceptor is annotated with PostConstruct, PreDestroy,

PostActivate, or PrePassivate, then the EJB component will also fail to deploy such an application.

Annotating Servlets

dynamically via the weblogic.servlet.WeblogicServletContext method will not have their annotations processed and no DI will be done for such components.