Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

New features added to Servlet 2.5

Servlets updated with annotations, web.xml conveniences, and more

By Jason Hunter, JavaWorld.com, 01/02/06

Page 2 of 5

Here's a simple Web service annotation example:

 import javax.jws.WebService;
import javax.jws.WebMethod;


@WebService
public class HelloWorldService {


  @WebMethod


  public String helloWorld() {
    return "Hello World!";
  }
} 

The @WebService and @WebMethod annotation types, specified in JSR 181 (Web Services Metadata for the Java Platform) and imported just like classes, mark this class as a Web service and mark its helloWorld() method as a Web service method. By themselves, the annotations don't do anything but sit there, kind of like Post-It notes; however, a container, upon loading this class and seeing those annotations in the bytecode, can wire up the class for Web services.

Annotations may accept name/value parameters. The parameter information is kept with the annotation and can be used to alter the behavior requested by the annotation. For example, here's a more advanced annotation example:

 @WebService(
  name = "PingService",
  targetNamespace="http://acme.com/ping"
)
@SOAPBinding(
  style=SOAPBinding.Style.RPC,
  use=SOAPBinding.Use.LITERAL
)
public class Ping {
  @WebMethod(operationName = "Foo")
  public void foo() { }
} 

Upon loading this class, a proper container will respect the annotations and their parameters, and wire up the class as a PingService with a Foo operation using the remote-procedure-call/literal encoding style. In a sense, annotations define the contract a class wishes to have with its container.

The Java language itself (through JSR 175) specifies only a tiny number of annotation types. The interesting annotation types come from other JSRs:

• JSR 250: Common Annotations for the Java Platform
• JSR 220: Enterprise JavaBeans 3.0
• JSR 224: Java API for XML-Based Web Services (JAX-WS) 2.0
• JSR 181: Web Services Metadata for the Java Platform

See Resources for more details on metadata and annotations.

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.

web.xml conveniences

Servlet 2.5 introduces several small changes to the web.xml deployment descriptor file format to make its use more convenient.

Servlet name wildcarding

First, when writing a <filter-mapping>, you can now use an asterisk in a <servlet-name> entry to represent all servlets (and thus all JSP pages as well). Previously, you could only bind one servlet at a time to a filter, like this: