WebLogic Annotation for Web Components

7 WebLogic Annotation for Web Components

Learn how to annotate Web components in WebLogic Server.

This chapter includes the following sections:

Servlet Annotation and Dependency Injection
The Servlet 4.0 specification provides annotations to enable declarative-style programming.
Annotating Servlets
The WebLogic servlet container provides the @WLServlet annotation for servlets and the WLFilter annotation for filters that you develop 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.

Servlet Annotation and Dependency Injection

The Servlet 4.0 specification provides annotations to enable declarative-style programming.

Note:

As of WebLogic Server 12.1.3, WebLogic Server-specific annotations have been deprecated and will be removed in a future release: @WLServlet, @WLFilter, and @WLInitParam, in favor of the standard annotations defined in the Servlet 4.0 specification. Also, instead of weblogic.servlet.http.AbstractAsyncServlet, you should use the standard asynchronous processing model defined in the Servlet 4.0 specification.

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 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 Jakarta EE annotations and dependency injection with WebLogic Server applications, see Using Jakarta EE Annotations and Dependency Injection and Using Contexts and Dependency Injection for the Jakarta EE Platform in Developing Applications for Oracle WebLogic Server. For detailed information about EJB-specific annotations for WebLogic Server EJBs, see Developing EJBs for Oracle WebLogic Server.

If you selected to install the server examples, you will find this Servlet 3.x annotation code example, "Using Annotations for Servlets, Filters and Listeners," in the ORACLE_HOME\wlserver\samples\server\examples\examples\src\examples\javaee7\servlet\annotation directory of your WebLogic Server distribution, where ORACLE_HOME represents the directory in which you installed the WebLogic Server. For more information about the WebLogic Server code examples, see Sample Applications and Code Examples in Understanding Oracle WebLogic Server.

Parent topic: WebLogic Annotation for Web Components

Web Component Classes That Support Annotations

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

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

Table 7-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`

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

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.
Dependency Injection (DI)—DI is done when instances are created (for the types listed in Table 7-1). For listeners and filters, this occurs during the deployment phase, and for servlets it can occur during deployment or run time.

Note:

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

Parent topic: Servlet Annotation and Dependency Injection

Annotations Supported By a Web Container

Table 7-2 lists all the annotations that must be supported by the Web container.

Table 7-2 List of Supported Annotations

@Annotation
DeclaresRoles
EJB
EJBs
PersistenceContext
PersistenceUnit
PersistenceUnits
PersistenceContexts
PostConstruct
PreDestroy
Resource
Resources
WebServiceRef
WebServiceRefs
RunAs

The Web container makes use of the Jakarta 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.

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.

Parent topic: Servlet Annotation and Dependency Injection

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.

Parent topic: Annotations Supported By a Web Container

Limitations

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.

Parent topic: Annotations Supported By a Web Container

Annotating Servlets

The WebLogic servlet container provides the @WLServlet annotation for servlets and the WLFilter annotation for filters that you develop 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 metadata 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.

Note:

Parent topic: WebLogic Annotation for Web Components

WLServlet

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.

Parent topic: Annotating Servlets

Attributes

Table 7-3 Attributes of WLServlet Annotation

Name	Description	Data Type	Required?
displayName	Display name for the servlet after deployment	String	No
description	Servlet description	String	No
icon	Icon location	String	No
name	Servlet name	String	No
initParams	Initialization parameters for the servlet	WLInitParam[]	No
loadOnStartup	Whether the servlet should load on startup	int	No
runAs	The run-as user for the servlet	String	No
mapping	The url-pattern for the servlet	String[]	No

Example 7-1 illustrates the usage of the annotation in a servlet class.

Example 7-1 WLServlet Annotation

@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.

Example 7-2 shows how the descriptor bean looks after being updated.

Example 7-2 Updated web.xml Descriptor

<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>

Parent topic: WLServlet

Fault Detection And Recovery

Any error during the processing of this annotation will result in a deployment error with a proper message in the server logs.

Parent topic: WLServlet

WLFilter

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.

Parent topic: Annotating Servlets

Attributes

Table 7-4 Attributes of WLFilter Annotation

Name	Description	Data Type	Required?
displayName	Display name for the filter after deployment	String	No
description	Filter description	String	No
icon	Icon location	String	No
name	Filter name	String	No
initParams	Initialization parameters for the filter	WLInitParam[]	No
mapping	The url-pattern for the filter	String[]	No

Example 7-3 illustrates the usage of the annotation in a filter class.

Example 7-3 WLFilter Annotation

@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 Web application deployment, the descriptor bean corresponding to web.xml descriptor is updated with the relevant entries corresponding to the annotation.

Example 7-4 shows how the descriptor bean looks after being updated.

Example 7-4 Updated web.xml Descriptor

<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>

Parent topic: WLFilter

Fault Detection and Recovery

Any error during the processing of this annotation will result in a deployment error with a proper message in the server logs.

Parent topic: WLFilter

WLInitParam

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.

Attributes

Parent topic: Annotating Servlets

Attributes

Table 7-5 Attributes of WLFilter Annotation

Name	Description	Data Type	Required?
name	The initial parameter name.	String	No
value	The initial parameter value.	String	No

Example 7-5 provides an example of WLInitParam annotation.

Example 7-5 Example 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 Example 7-6 in the web.xml descriptor.

Example 7-6 Init Params In web.xml

. . .
<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>
. . .

Parent topic: WLInitParam