Annotations in Servlet 2.5

Coming back to Servlet 2.5, the new specification describes how several annotations work in a servlet environment. Simple servlet containers can ignore these rules, while servlets in a JEE container must abide by them.

Some annotations provide an alternative to XML entries that would otherwise go in the web.xml deployment descriptor. Other annotations act as requests for the container to perform tasks that otherwise the servlet would have to perform itself. Some annotations do both.

The exact list of annotations isn't completely finalized, because the Servlet specification itself doesn't define the annotations; it only helps interpret how they affect a servlet environment. Here's a short summary of the annotations you can expect in JEE 5 along with their intended use:

• @Resource and @Resources: @Resource is placed on a class or variable to request a "resource injection" by the servlet container. When the container sees this annotation, it will prepopulate the annotated variable with an appropriate value before the servlet gets placed into service. By using this annotation, you avoid the need to make a JNDI (Java Naming and Directory Interface) lookup call and declare the resource manually in the web.xml deployment descriptor file. The server takes care of both tasks through introspecting the servlet. The name and type of the variable are determined automatically by reflection, although you can override that with annotation parameters. An injected resource may be a datasource, Java Message Service destination, or environment entry variable. Here's a basic example:

·                 @Resource javax.sql.DataSource catalog;

            

public getData() {

·                  Connection con = catalog.getConnection();

·                }

Now, before putting a servlet with this code into service, the container will locate the JNDI variable named catalog of type DataSource and manually assign that reference to the catalog variable.

For efficiency, only certain classes support resource injection: servlets, servlet filters, servlet event listeners, JavaServer Pages tag handlers and JSP library event listeners, JavaServer Faces scoped managed beans, and a few other class types unrelated to servlets.

The @Resources annotation is similar to @Resource, but used to hold an array of @Resource annotations. Both annotations are from JSR 250, the Common Annotations for the Java Platform.

• @PostConstruct and @PreDestroy: Attached to methods to make them act as lifecycle methods. The @PostConstruct method is called after the resource injection as a chance to initialize the injected resources. The @PreDestroy method is called when the servlet is taken out of service to give it a chance to release injected resources. The callback methods must be instance methods that return void and do not throw any checked exceptions. In a servlet, these annotations essentially let arbitrary methods act as secondary init() and destroy() methods. These properties also come from JSR 250.
• @EJB: Similar to @Resource, except designed for injecting Enterprise JavaBeans references. It has somewhat different parameters than @Resource in that @EJB parameters are specifically designed to locate EJB references. This annotation comes from the EJB 3.0 specification.
• @WebServiceRef: Similar to @Resource and @EJB, except designed for injecting Web service references. From the JAX-WS 2.0 Specification.
• @PersistenceContext, @PersistenceContexts, @PersistenceUnit, and @PersistenceUnits: Annotations from the EJB 3.0 Specification to support Java object persistence.
• @DeclareRoles: Defines the security roles used within the application. When defined on a servlet class, this annotation offers an alternative to <security-role> entries in the web.xml file. From JSR 250.
• @RunAs: Used to declare the role under which a class should run. When defined on a servlet class, it's an alternative to <run-as> entries in the web.xml file. From JSR 250.

Annotation performance

Whether or not you use annotations—and especially if you don't—it's important to understand the performance impact they can have on a server at startup. In order for the server to discover annotations on classes, it must load the classes, which means that at startup, a server will look through all the classes in WEB-INF/classes and WEB-INF/lib, looking for annotations. (Per the specification, servers don't have to look outside these two places.) You can avoid this search when you know you don't have any annotations by specifying a metadata-complete attribute on the <web-app> root like this:

 <web-app xmlns="http://java.sun.com/xml/ns/javaee"

         version="2.5" metadata-complete="true">

</web-app>

When you're not using annotations, this reenables lazy class loading.