The following sections describe how to annotate web components.
With Java EE metadata annotations, the standard web.xml
deployment descriptor is now optional. The
Servlet 2.5 specification, states 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 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. 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 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 Annotations and Dependency Injection in Developing Applications With WebLogic Server. For detailed information about EJB-specific annotations for WebLogic Server Enterprise JavaBeans, see Programming WebLogic Enterprise JavaBeans, Version 3.0.
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:
java:comp/env
tree is updated with the necessary entries. Note: | In any WebApp component, if one DI fails, then it will cause all subsequent DIs upon the same component to be ignored. |
Table 8-2 lists all the annotations that must be supported by the web container.
The web container make use of the Java EE container’s annotation processing and dependency injection mechanisms to achieve this functionality.
The
Servlet 2.5 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
.
Caution: | If multiple methods in a web component class, such as a servlet, filter, etc., 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. |
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.
The WebLogic Servlet container supports annotations on web components that are declared in the web.xml
descriptor. Any listeners, filters or servlets registered dynamically via the weblogic.servlet.WeblogicServletContext
method will not have their annotations processed and no DI will be done for such components.
The WebLogic Servlet container provides the @WLServlet
annotation for servlets and the WLFilter
annotation for filters that you to develop servlets and filters in a web application without having to declare them in a web.xml
descriptor. The WebLogic Servlet container also provides the WLInitParam
annotation to specify the initial parameters for servlets and filters declared using the WLServlet
and WLFilter
annotations.
All the required meta-data can be annotated in the servlet or filter and the container will detect them and update the descriptor tree so that the annotated servlet or filter is deployed.
You can annotate a servlet class with WLServlet
annotation (weblogic.servlet.annotation.WLServlet
). This annotation defines various attributes for declaring parameters for the servlet. All attributes on this annotation are optional.
Listing 8-1 illustrates the usage of the annotation in a Servlet class.
@WLServlet (
name = "FOO",
runAs = "SuperUser"
initParams = { @WLInitParam (name="one", value="1") }
mapping = {"/foo/*"}
)
. . .
The WebLogic Servlet container detects the annotation and installs this servlet for deployment. During the annotation processing phase of the web applications deployment, the descriptor bean corresponding to web.xml
descriptor is updated with the relevant entries corresponding to the annotation.
Listing 8-2 shows how the descriptor bean looks after being updated.
<web-app>
. . .
<servlet>
<servlet-name>FOO</servlet-name>
<servlet-class>my.TestServlet</servlet-class>
<init-param>
<param-name>one</param-name>
<param-value>1</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>FOO</servlet-name>
<url-pattern>/foo/*</url-pattern>
</servlet-mapping>
. . .
</web-app>
Any error during the processing of this annotation will result in a deployment error with a proper message in the server logs.
You can annotate a filter class with WLFilter
annotation (weblogic.servlet.annotation.WLFilter
). This annotation defines various attributes for declaring parameters for the filter. All attributes on this annotation are optional.
Listing 8-3 illustrates the usage of the annotation in a Filter class.
@WLFilter (
name = "BAR",
initParams = { @WLInitParam (name="one", value="1") }
Mapping = {"/bar/*"}
)
. . .
The WebLogic Servlet container detects the annotation and installs this filter for deployment. During the annotation processing phase of the WebApp deployment, the descriptor bean corresponding to web.xml
descriptor is updated with the relevant entries corresponding to the annotation.
Listing 8-4 shows how the descriptor bean looks after being updated.
<web-app>
. . .
<filter>
<filter-name>BAR</filter-name>
<filter-class>my.TestFilter</filter-class>
<init-param>
<param-name>one</param-name>
<param-value>1</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>BAR</filter-name>
<url-pattern>/bar/*</url-pattern>
</filter-mapping>
. . .
</web-app>
Any error during the processing of this annotation will result in a deployment error with a proper message in the server logs.
You can use the @WLInitParam
annotation (weblogic.servlet.annotation.WLInitParam
) to specify the initial parameters for servlets and filters declared using the @WLServlet
and @WLFilter
annotations.
Listing 8-5 provides an example of WLInitParam
annotation.
initParams = {@WLInitParam(name="one", value="1"),
@WLInitParam(name="two", value="2")}
Annotating a Servlet or Filter class with the above annotation is equivalent to declaring the init params in Listing 8-6 in the web.xml
descriptor.
. . .
<init-param>
<param-name>one</param-name>
<param-value>1</param-value>
</init-param>
<init-param>
<param-name>two</param-name>
<param-value>2</param-value>
</init-param>
. . .