Implementing RESTful views of an EJB with local interfaces

If you have Enterprise JavaBeans (EJB) applications that are exposed using a local interface view, you can expose a RESTful interface to the enterprise bean using Java™ API for RESTful Web Services (JAX-RS). By implementing JAX-RS annotated enterprise beans, you keep the EJB functionality including transaction support, injection of Java EE components and resources, and other EJB session bean capabilities.

1. Create enterprise bean local interfaces for your enterprise bean application.
   The following example demonstrates a simple local business interface, the Purchasable EJB local interface, for items to purchase:

   package com.example.jaxrs;
   @javax.ws.rs.Path("itemsForPurchase/{itemID}")
   public interface Purchasable {
   
       public int getItemsLeft(String itemID);
   
       @javax.ws.rs.POST
       public Order purchase(
           @javax.ws.rs.PathParam("itemID") String itemID,
           @javax.ws.rs.QueryParam("orderId") String orderID);
   }

   The getItemsLeft method is a regular EJB method that is not JAX-RS related. A javax.ws.rs.Path annotation denotes the HTTP request path to use. When an HTTP POST request is made to the itemsForPurchase/{itemID} object, the JAX-RS runtime environment finds an EJB bean that implements the Purchasable local interface and invokes the purchase method on the enterprise bean.

   You can still use the purchase method outside of a JAX-RS runtime environment request. You can use injection or a JNDI lookup for a purchasable enterprise bean and invoke the purchase method with the two String arguments, itemID and orderID.

   Best practice: If there are multiple enterprise beans that implement a local business interface, the JAX-RS runtime environment chooses a random EJB bean to use when a JAX-RS request is made. It is a best practice to only enable one bean class to implement a JAX-RS annotated EJB local interface. If necessary, create a separate EJB local interface, use the JAX-RS annotations on the new interface, and then modify the metadata for the bean class so that it implements the new EJB local interface.
2. Create the enterprise bean that implements the local business interface.
   The following example illustrates the Purchasable EJB bean:

       public int getItemsLeft(String itemID) {
           // Return the number of items that remain.  
       }
   
       public Order purchase(String itemID, String orderId) {
           // Add the given item to the order id and return it.  
       }
   
   }

3. Declare that the Book class is an enterprise bean and implements a local interface.
   Use one of the following methods to declare your class as an enterprise bean that implements the local interface. In the following example, the Book class is declared an enterprise bean that implements a local interface:
   • Use the EJB annotations @javax.ejb.Stateless or @javax.ejb.Singleton on the Book class to specify that you want the EJB to be stateless or singleton. Also, add the @javax.ejb.Local annotation with the local interfaces as the annotation value; for example:

     @javax.ejb.Stateless
     @javax.ejb.Local(Purchasable.class)
     public class Book {

     If you have implemented multiple local business interfaces, add the interface classes to the @javax.ejb.Local annotation value; for example:

     @javax.ejb.Local({Purchasable.class, Rentable.class})

   • You can use a deployment descriptor to declare that an EJB bean and the business interfaces it implements; for example:

     <ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" version="3.1"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd">
     <!--
         This file must exist in the WEB-INF/
         directory of your WAR file. See EJB 3.1 spec 20.4 for more details.
     -->
         <enterprise-beans>
             <session>
                 <ejb-name>Book</ejb-name>
                 <business-local>com.example.jaxrs.Purchasable</business-local>
                 <ejb-class>com.example.jaxrs.Book</ejb-class>
                 <session-type>Stateless</session-type>
             </session>
         </enterprise-beans>
     </ejb-jar>

     If you have implemented multiple local business interfaces, you must add business-local elements to each local interface in your bean definition.

   • If you have only one local business interface, you can implement the interface directly; for example:

     @javax.ejb.Stateless
     public class Book implements Purchasable {

4. (optional) Add @javax.annotation.Resource annotated Java EE resource fields and properties to your JAX-RS EJB classes to easily access resources in your application.
   The Java EE injections do not work in plain Java classes with JAX-RS annotations. Injecting @javax.annotation.Resource annotated Java EE resource fields and properties to your JAX-RS EJB classes only works if your JAX-RS annotated classes are either an enterprise bean or a Java Context and Dependency Injection (JCDI) (JSR-299) managed bean; for example:

   package com.example.jaxrs;
   
   @javax.ejb.Stateless
   @javax.ejb.Local(Purchasable.class)
   public class Book implements Purchasable {
       @javax.annotation.Resource(name="jdcb/TestDataSource")
       private javax.sql.DataSource datasource;
   
       public int getItemsLeft(String itemID) {
           // Reads from the datasource. 
           // Returns the number of items that remain.  
       }
   
       public Order purchase(String itemID, String orderId) {
           // Reads from the datasource. 
           // Adds the given item to the order id and returns it.  
       }
   }

   In this example, if a data source is properly configured with the correct JNDI name, a DataSource object is injected into the resource class.
5. (optional) Use JAX-RS @javax.ws.rs.core.Context injection to obtain access to information about the request.
   You can add an @javax.ws.rs.core.Context UriInfo field to your JAX-RS EJB class to access information about the request URI; for example:

   package com.example.jaxrs;
   
   @javax.ejb.Stateless
   @javax.ejb.Local(Purchasable.class)
   public class Book implements Purchasable {
       @javax.ws.rs.core.Context
       private UriInfo uriInfo;
   
       public int getItemsLeft(String itemID) {
           // Return the number of items that remain.  
       }
   
       public Order purchase(String itemID, String orderId) {
           // Add the given item to the order id and return it.  
       }
   }

   To read parameters from the request such as @javax.ws.rs.HeaderParam, @javax.ws.rs.QueryParam, and @javax.ws.rs.PathParam, add a parameter to your resource method; for example:

   package com.example.jaxrs;
   
   @javax.ws.rs.Path("itemsForPurchase/{itemID}")
   public interface Purchasable {
       public int getItemsLeft(String itemID);
   
       @javax.ws.rs.POST
       public Order purchase(
           @javax.ws.rs.PathParam("itemID") String itemID,
           @javax.ws.rs.QueryParam("orderId") String orderID);
   }
   

   package com.example.jaxrs;
   
   @javax.ejb.Stateless
   @javax.ejb.Local(Purchasable.class)
   public class Book implements Purchasable {
       @javax.ws.rs.core.Context
       private UriInfo uriInfo;
   
       public int getItemsLeft(String itemID) {
           // Returns the number of items that remain.  
       }
   
       public Order purchase(String itemID, String orderId) {
           // The method parameters contain the request values. 
           // Add the given item to the order id and return it.  
       }
   
       /*  The following field will not be set. */
       @javax.ws.rs.QueryParam("q")
       private String willNotWork;
   
       @javax.ws.rs.QueryParam("q")
       public void setMyQueryParam(String q) {
           /* This property will not be set. */
       }
   }

   Supported configurations: The JAX-RS parameter annotations must be added to the resource methods in the EJB business interface when using business interfaces. They cannot be added to the implementation bean.
6. Package the enterprise beans into the WEB-INF/classes directory of the WAR file, or inside a JAR file that is included in the WEB-INF/lib directory of your WAR file.

   When a client makes a request to a JAX-RS annotated enterprise bean, the JAX-RS runtime environment looks up and uses an EJB instance of the class to then invoke the JAX-RS resource method.