7 Using Annotations for Services and Resource References

Overview of How Annotations Work

In J2SE 5.0 or greater, you can specify configuration data and dependency on external resources in Java code as metadata, also referred to as annotations. You can define such data in configuration files or in annotations for services, such as EJBs or Web services, and for resource references, such as data sources and JMS destinations.

For example, in J2EE 1.4, before a servlet can refer to an EJB, the developer must define an ejb-local-ref element, like this one:

<ejb-local-ref>
 <ejb-ref-name>ejb/HelloWorld</ejb-ref-name>
 <local>oracle.ejb.HelloWorld</local>
</ejb-local-ref>

Then, to refer to the EJB in code, the developer has to use JNDI, as in this code fragment:

Context ic = new InitialContext();   
HelloWorld helloWorld = (HelloWorld)ic.lookup("java:comp/env/ejb/HelloWorld");
helloWorld.greet(ÒHello!Ó);

In servlet 2.5, the client code is simplified and OC4J injects the correct resource or service. The client only needs to specify the resource or service in an annotation, such as this one:

@EJB
private HelloWorld helloWorld;
helloWorld.greet("Hello!");

Annotations and Injection

The metadata-complete attribute of the web-app element in a Web application's deployment descriptor specifies whether the Web descriptor and other related deployment descriptors for this module (such as Web service descriptors) are complete. If the web.xml file uses servlet 2.5 by setting version="2.5" or points to the servlet 2.5 schema namespace, the OC4J servlet container will check the metadata-complete flag to determine whether or not to process annotations. If version is set to 2.4 or an earlier version, the servlet container does not process any annotations.

If metadata-complete is set to true, the default value for Servlet 2.4, the servlet container ignores any servlet annotations that are in the class files of the application. If the metadata-complete attribute is missing or is set to false, the default value for Servlet 2.5, and version is set to 2.5, the servlet container examines the class files of the application for servlet annotations and supports the annotations as follows:

1. The OC4J servlet container inspects resource or service references for annotation references for classes of a Web application that are located in the WEB-INF/ directory or in a JAR file under the WEB-INF/lib/ directory.

   The servlet container also provides annotation support for jar files listed in MANIFEST.MF.

2. The OC4J servlet container provides annotation support for managed component classes that are declared in the Web application deployment descriptor and that implement the following interfaces:

   • javax.servlet.Servlet

   • javax.servlet.Filter

   • javax.servlet.ServletContextListener

   • javax.servlet.ServletContextAttributeListencer

   • javax.servlet.ServletRequestListener

   • javax.servlet.ServletRequestAttributeListener

   • javax.servlet.http.HttpSessionListener

   • javax.servlet.http.HttpSessionAttributeListener

3. The OC4J servlet container injects resource or service references before any lifecycle methods are called on the instance.

   • (init() for javax.servlet.Servlet and javax.servlet.Filter

   • contextInitialized() for javax.servlet.ServletContextListener

   • requestInitialized() for javax.servlet.ServletRequestListener

4. If both an annotation and a deployment descriptor entry declare an environment entry, information in the deployment descriptor entry can override some of the information in a Resource, EJB, or WebServiceRef annotation.

   The following specifications describe the rules for using a deployment descriptor entry to override annotation information:

   • For rules to override Resource annotations, see the Java EE 5 specification.

   • For rules to override EJB annotations, see the EJB specification.

   • For rules to override WebServiceRef annotations, see the Web Services specification.

5. If the OC4J servlet container cannot find a resource or service that it needs to inject for a class, the initialization of the class fails and OC4J issues this warning message:

   Some resource(s) and/or service(s) to be injected cannot be found for class name. class name will not be put to service.
   
   

6. After all the resource or service references have been injected, and before any lifecycle methods are called on the instance, the method marked with the PostConstruct annotation, if any, must be invoked to give the servlet a chance to initialize the injected resources. See "PostConstruct Annotation".

7. Before the servlet is taken out of service, the method marked with a PreDestroy annotation, if any, must be invoked to give the servlet a chance to release the injected resources. See "PreDestroy Annotation".

Annotations in OC4J

This section describes the annotations that OC4J supports:

EJB Annotation

Resource Annotation

Resources Annotation

PostConstruct Annotation

PreDestroy Annotation

PersistenceUnit(s) Annotation

PersistenceContext(s) Annotation

WebServiceRef Annotation

DeclaresRoles Annotation

RunAs Annotation

@EJB private ShoppingCart myCart;

@EJB(
      name = "ejb/shopping-cart",
      beanName = "Cart1",
      beanInterface = ShoppingCart.class,
      description = "Items for purchase"
   )
   private ShoppingCart myCart;

@Resource
   private DataSource myDB;

@Resource(name="customerDB")
   private DataSource myDB;

public @interface Resources {
      Resource[] value;
  }
  // value – Array of multiple resources.

@Resources ({
      @Resource (name = "myDB", type=javax.sql.DataSource),
      @Resource (name = "myCF", type=javax.jms.ConnectionFactory)
   )
   public class MulResClass {
      //...
   }

@PostConstruct
   void doPostInjectionProcessing {
      //...

@PreDestroy
   void doPreDestroyProcessing {
      //...
      }

@PersistenceUnit
   EntityManagerFactory emf;

@PersistenceUnit(unitName=ÓInventoryManagementÓ)
      EntityManagerFactory emf;

@PersistenceContext
   EntityManager em;

@PersistenceContext(unitName=ÓInventoryManagementÓ)
   EntityManager em;

// Generated Service Interface
   @WebServiceRef
   private StockQuoteService stockQuoteService;

   // SEI
   @WebServiceRef(StockQuoteService.class)
   private StockQuoteProvider stockQuoteProvider;

@DeclaresRoles("Manager")
   public class CorporationServlet {
      //...
   }

<web-app>
      <security-role>
         <role-name>Manager</role-name>
      </security-role>
   </web-app>

@RunAs("Admin")
   public class CorporationServlet {
      //...
   }

<servlet>
      <servlet-name>CorporationServlet</servlet-name>
      <run-as>Admin</run-as>
   </servlet>

Annotation Rules and Guidelines

Here are some rules for using annotations. For more information on general annotation guidelines, see the Java EE 5 specification.

• A field or a method of the following container-managed component classes can be annotated to request that an entry from the component's environment be injected into the class:

  
  javax.servlet.Servlet
javax.servlet.Filter
javax.servlet.ServletContextListener
javax.servlet.ServletContextAttributeListencer
javax.servlet.ServletRequestListener
javax.servlet.ServletRequestAttributeListener
javax.servlet.http.HttpSessionListener
javax.servlet.http.HttpSessionAttributeListener
  

• A field or method can have any access qualifier (such as public or private).

• A field or method cannot be static, except for the fields or methods of the application client main class that have been annotated for injection. These fields or methods must be static.

• Any violation of the preceding rules is an error that will result in a message or messages being logged. The violating class will not be put in service.

• Annotations applied on a class do not cause resource injections. Instead, they declare an entry in an application component's environment that the application component can look up through JNDI or the component context lookup method.

• Resource annotations can be specified in any of the classes in the first item of this list or on any of their superclasses, as the following example shows. Injection of resources follows the Java language overriding rules for visibility of fields and methods.

  Class A { 
     @Resource 
     private DataSource myDS; // Injected resource not visible in class B
     //...
  }
  
  Class B extends Class A {
     public DataSource myDS; // Not a resource, needs to do JNDI lookup
     //...
  }
  
  

How Annotations Affect Performance with Servlet Version 2.5

Whether or not annotations are used for Web applications with servlet version 2.5, if the metadata-complete attribute of <web-app> is missing from the deployment descriptor or is set to false (the servlet 2.5 default value), OC4J needs to load all the classes under WEB-INF/ and WEB-INF/lib to look for annotations. This loading can have some impact on Oracle Application Server performance at startup. When you are not using annotations, you can avoid this performance impact by specifying metadata-complete="true".

This startup performance impact is applicable only for Web applications with servlet version 2.5. For Web applications with servlet version 2.4 or lower, there will be no performance impact.

Annotation Example

This section contains an example of a servlet using annotations and the corresponding web.xml file.

The servlet illustrates the Servlet 2.5 way of doing things and then commented out is the Servlet 2.4 way of doing things as a comparison. The servlet demonstrates one @EJB annotation and two @Resource annotations.

The web.xml file illustrates the version= and metadata-complete settings required to enable annotations to be used:

<web-app version="2.5" metadata-complete="false">
 ...
</web-app>

For additional information, see the document "How-To: Using Dependency Injection In Web Module" on the following site:

http://www.oracle.com/technology/tech/java/oc4j/10131/how_to/index.html

Here is the web.xml file example.

<?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
        version="2.5"
        metadata-complete="false"
>

    <display-name>Annotation Example</display-name>
        <description>A few examples of Servlet 2.5 Annotation and Resource Injection</description>

    <servlet>
        <display-name>hello</display-name>
        <servlet-name>HelloServlet</servlet-name>
        <servlet-class>HelloServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>HelloServlet</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>

  <env-entry>
    <env-entry-name>EmpNo</env-entry-name>
    <env-entry-type>java.lang.Integer</env-entry-type>
    <env-entry-value>15</env-entry-value>
  </env-entry>
</web-app>

Here is the HelloServlet.java servlet example.

import java.io.*;

import javax.servlet.*;
import javax.servlet.http.*;
import javax.annotation.Resource;
import javax.sql.*;
import java.sql.*;
import javax.naming.*;
import org.acme.*; 
import javax.rmi.*;
import javax.ejb.*;
public class HelloServlet extends HttpServlet {

    @EJB HelloObject bean;
    @Resource(name="EmpNo") int empNo;
    @Resource(name="jdbc/OracleDS") private DataSource db;

    public void doGet(HttpServletRequest req, HttpServletResponse res)
            throws ServletException, IOException {
        res.setContentType("text/html");

        PrintWriter writer = res.getWriter();

        // ejb invocation
        writer.println(bean.sayHello()+"<br>");

        // fetch value set by deployer
        writer.println("EmpNo="+empNo+"<br>");

        // make a db connection
        writer.println("db="+getConnection()+"<br>");
    }

    public Connection getConnection() {
      Connection conn = null; 
  
      try {
          if (db != null) {
              conn = db.getConnection();
          }
      } catch (Exception e) {
          e.printStackTrace();
      }
      return conn;
    }

    // The following is the pre-2.5 way to do it.
/*

   public void doGet(HttpServletRequest req, HttpServletResponse res)
            throws ServletException, IOException {
        res.setContentType("text/html");

        PrintWriter writer = res.getWriter();

        InitialContext ctx = new InitialContext();
        Object obj = ctx.lookup("java:comp/env/ejb/Hello");

        HelloHome ejbHome = (HelloHome)
                    PortableRemoteObject.narrow(obj,HelloHome.class);
        HelloObject bean = ejbHome.create();

        // ejb invocation
        writer.println(bean.sayHello()+"<br>");

        // fetch value set by deployer
        Context myEnv = (Context) ctx.lookup("java:comp/env");
        Integer empNoInteger = (Integer) myEnv.lookup("EmpNo");
        int empNo = empNoInteger.intValue();

        writer.println("EmpNo="+empNo+"<br>");

        // make a db connection
        writer.println("db="+getConnection()+"<br>");
    }

    public Connection getConnection() {

        Context initCtx = new InitialContext();
        javax.sql.DataSource db = 
           (javax.sql.DataSource) initCtx.lookup("java:comp/env/jdbc/OracleDS");

        Connection conn = null;

        try {
            if (db != null) {
                conn = db.getConnection();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return conn;
    }
*/
}