Stateless Session Beans

As we mentioned, a stateless session bean sets out to complete an operation within the lifetime of a single method. Stateless beans can implement many business operations, but each method cannot assume that any other was invoked before it.

This might sound like a limitation of the stateless bean, but it is by far the most common form of business service implementation. Unlike stateful session beans, which are good for accumulating state during a conversation (such as the shopping cart of a retail application), stateless session beans are designed to carry out independent operations very efficiently. Stateless session beans can scale to large numbers of clients with minimal impact to overall server resources.

public interface HelloService {
    public String sayHello(String name);
}

@Stateless
public class HelloServiceBean implements HelloService {
    public String sayHello(String name) {
        return "Hello, "  + name;
    }
}

@Stateless
public class HelloService {
    public String sayHello(String name) {
        return “Hello, “ + name;
    }
}

@Stateless
public class LoggerBean {
    private Logger logger;

    @PostConstruct
    void init() {
        logger = Logger.getLogger("notification");
    }

    public void logMessage(String message) {
        logger
.info(message);
    }
}

Stateful Session Beans

In our introduction to session beans, we described the difference between stateless and stateful beans as being based on the interaction style between client and server. In the case of stateless session beans, that interaction started and ended with a single method call. Sometimes clients need to issue multiple requests and have each request be able to access or consider the results of previous requests. Stateful session beans are designed to handle this scenario by providing a dedicated service to a client that starts when the client obtains a reference to the bean and ends only when the client chooses to end the conversation.

The quintessential example of the stateful session bean is the shopping cart of an e-commerce application. The client obtains a reference to the shopping cart, starting the conversation. Over the span of the user session, the client adds or removes items from the shopping cart, which maintains state specific to the client. Then, when the session is complete, the client completes the purchase, causing the shopping cart to be removed.

This is not unlike using a nonmanaged Java object in application code. You create an instance, invoke operations on the object that accumulate state, and then dispose of the object when you no longer need it. The only difference with the stateful session bean is that the server manages the actual object instance and the client interacts with that instance indirectly through a proxy object.

Stateful session beans offer a superset of the functionality available in stateless session beans. The features that we covered for stateless session beans apply equally to stateful session beans.

@Stateful
public class ShoppingCart {
    private HashMap<String,Integer> items = new HashMap<String,Integer>();

    public void addItem(String item, int quantity) {
        Integer orderQuantity = items.get(item);
        if (orderQuantity == null) {
            orderQuantity = 0;
        }
        orderQuantity += quantity;
        items.put(item, orderQuantity);
    }

    public void removeItem(String item, int quantity) {
        // ...
    }

    public Map<String,Integer> getItems() {
        // ...
    }

    // ...

    @Remove
    public void checkout(int paymentId) {
        // store items to database
        // ...
    }

    @Remove
    public void cancel() {
    }
}

@Stateful
public class OrderBrowser {
    DataSource ds;
    Connection conn;

    @PostConstruct
    void init() {
        // acquire the data source
        // ...

        acquireConnection();
    }
     
    @PrePassivate
    void passivate() { releaseConnection(); }

    @PostActivate
    void activate() { acquireConnection(); }

    @PreDestroy
    void shutdown() { releaseConnection(); }
     
    private void acquireConnection() {
        try {
            conn = ds.getConnection();
        } catch (SQLException e) {
            throw new EJBException(e);
        }
    }

    private void releaseConnection() {
        try {
            conn.close();
        } catch (SQLException e) {
        } finally {
            conn = null;
        }
    }

    public Collection<Order> listOrders() {
        // ...
    }

    @Remove
    public void remove() {}
}

Singleton Session Beans

Two of the most common criticisms of the stateless session bean have been the perceived overhead of bean pooling and the inability to share state via static fields. The singleton session bean attempts to provide a solution to both concerns by providing a single shared bean instance that can both be accessed concurrently and used as a mechanism for shared state. Singleton session beans share the same lifecycle callbacks as a stateless session bean, and server-managed resources such as persistence contexts behave the same as if they were part of a stateless session bean. But the similarities end there because singleton session beans have a different overall lifecycle than stateless session beans and have the added complexity of developer-controlled locking for synchronization.

Unlike other session beans, the singleton can be declared to be created eagerly during application initialization and exist until the application shuts down. Once created, it will continue to exist until the container removes it, regardless of any exceptions that occur during business method execution. This is a key difference from other session bean types because the bean instance will never be re-created in the event of a system exception.

The long life and shared instance of the singleton session bean make it the ideal place to store common application state, whether read-only or read-write. To safeguard access to this state, the singleton session bean provides a number of concurrency options depending on the needs of the application developer. Methods can be completely unsynchronized for performance, or automatically locked and managed by the container.

@Singleton
public class HitCounter {
    int count;

    public void increment() { ++count; }

    public void getCount() { return count; }

    public void reset() { count = 0; }
}

Dependency Lookup

The first strategy for resolving dependencies in application code that we will discuss is called dependency lookup. This is the traditional form of dependency management in Java EE, in which the application code is responsible for looking up a named reference using the Java Naming and Directory Interface (JNDI).

All the resource annotations support an attribute called name that defines the JNDI name of the reference. When the resource annotation is placed on the class definition, this attribute is mandatory. If the resource annotation is placed on a field or a setter method, the server will generate a default name. When using dependency lookup, annotations are typically placed at the class level, and the name is explicitly specified. Placing a resource reference on a field or setter method has other effects besides generating a default name that we will discuss in the next section.

The role of the name is to provide a way for the client to resolve the reference dynamically. Every Java EE application server supports JNDI, even though it is less frequently used by applications since the advent of dependency injection, and each Java EE component has its own locally scoped JNDI naming context called the environment naming context. The name of the reference is bound into the environment naming context, and when it is looked up using the JNDI API, the server resolves the reference and returns the target of the reference.

Consider the DeptService session bean shown in Listing 3-9. It has declared a dependency on a session bean using the @EJB annotation and given it the name “deptAudit.” The beanInterface element of the @EJB annotation references the session bean class. In the PostConstruct callback, the audit bean is looked up and stored in the audit field. The Context and InitialContext interfaces are both defined by the JNDI API. The lookup() method of the Context interface is the traditional way to retrieve objects from a JNDI context. To find the reference named deptAudit, the application looks up the name “java:comp/env/deptAudit” and casts the result to AuditService. The prefix “java:comp/env/” that was added to the reference name indicates to the server that the environment naming context should be searched to find the reference. If the name is incorrectly specified, the lookup will fail.

Listing 3-9.  Looking Up an EJB Dependency

@Stateless
@EJB(name="deptAudit", beanInterface=AuditService.class)
public class DeptService {
    private AuditService audit;

    @PostConstruct
    void init() {
        try {
            Context ctx = new InitialContext();
            audit = (AuditService) ctx.lookup("java:comp/env/deptAudit");
        } catch (NamingException e) {
            throw new EJBException(e);
        }
    }

    // ...
}

Using the JNDI API to look up resource references from the environment naming context is supported by all Java EE components. It is, however, a somewhat cumbersome method of finding a resource because of the exception-handling requirements of JNDI. EJBs also support an alternative syntax using the lookup() method of the EJBContext interface. The EJBContext interface (and subinterfaces such as SessionContext) is available to any EJB and provides the bean with access to runtime services such as the timer service. Listing 3-10 shows the same example as Listing 3-9 using the lookup() method. The SessionContext instance in this example is provided via a setter method that is called by the container. We will revisit this example later in the section called “Referencing Server Resources” to see how it is invoked.

Listing 3-10.  Using the EJBContext lookup() Method

@Stateless
@EJB(name="deptAudit", beanInterface=AuditService.class)
public class DeptService  {
    SessionContext context;
    AuditService audit;

    public void setSessionContext(SessionContext context) {
        this.context = context;
    }

    @PostConstruct
    public void init() {
        audit = (AuditService) context.lookup("deptAudit");
    }

    // ...
}

The EJBContext lookup() method has two advantages over the JNDI API. The first is that the argument to the method is the name exactly as it was specified in the resource reference. The second is that only runtime exceptions are thrown from the lookup() method so the checked exception handling of the JNDI API can be avoided. Behind the scenes, the exact same sequence of JNDI API calls from Listing 3-9 is being made, but the JNDI exceptions are handled automatically.

Dependency Injection

When a resource annotation is placed on a field or setter method, two things occur. First, a resource reference is declared just as if it had been placed on the bean class (similar to the way the @EJB annotation worked in the example in Listing 3-9), and the name for that resource will be bound into the environment naming context when the component is created. Second, the server does the lookup automatically on your behalf and sets the result into the instantiated class.

The process of automatically looking up a resource and setting it into the class is called dependency injection because the server is said to inject the resolved dependency into the class. This technique, one of several commonly referred to as inversion of control, removes the burden of manually looking up resources from the JNDI environment context.

Dependency injection is considered a best practice for application development, not only because it reduces the need for JNDI lookups but also because it simplifies testing. Without any JNDI API code in the class that has dependencies on the application server runtime environment, the bean class can be instantiated directly in a unit test. The developer can then manually supply the required dependencies and test the functionality of the class in question instead of worrying about how to work around the JNDI lookup.

@Stateless
public class DeptService {
    @EJB AuditService audit;

    // ...
}

@Stateless
public class DeptService {
    private AuditService audit;

    @EJB
    public void setAuditService(AuditService audit) {
        this.audit = audit;
    }

    // ...
}

Declaring Dependencies

The following sections describe some of the resource annotations described in the Java EE specification. Each annotation has a name attribute for optionally specifying the reference name for the dependency. Other attributes on the annotations are specific to the type of resource that needs to be acquired.

@Stateless
public class EmployeeService {
    @PersistenceContext(unitName="EmployeeService")
    EntityManager em;

    // ...
}

@Stateful
public class EmployeeService {
    @PersistenceUnit(unitName="EmployeeService")
    private EntityManagerFactory emf;
    private EntityManager em;

    @PostConstruct
    public void init() {
        em = emf.createEntityManager();
    }

    // ...
}

@Stateless
@EJB(name="audit", beanInterface=AuditService.class)
public class DeptService {
    @Resource
    SessionContext context;
    AuditService audit;

    @PostConstruct
    public void init() {
        audit = (AuditService) context.lookup("audit");
    }

    // ...
}

CDI Beans

One of the benefits of EJBs is that it provides all of the services that one might need, from security to automatic transaction management and concurrency control. However, the full service model can be seen as a drawback if you don’t use or want some of the services, since the perception is that there is at least some cost associated with having them. Managed beans, and the CDI extensions to them, provide more of a pay-as-you-go model. You only get the services that you specify. Don't be fooled, though, into thinking that CDI beans are any less bulky than a modern EJB. When it comes down to implementation, both types of objects are proxied by the container in pretty much the same way and the service hooks will be added in and triggered as necessary.

What are CDI beans, anyway? A CDI bean is any class that qualifies for the CDI injection services, the primary requirement of which is simply that it be a concrete class.² Even session beans can be CDI beans and thus qualify for CDI injection services, although there are some caveats about their lifecycle contexts.

Injection and Resolution

A bean may have its fields or properties be the target of injection if they are annotated by @javax.inject.Inject. CDI defines a sophisticated algorithm for resolving the correct type of object to inject, but in the general case, if you have a field declared of type X, then an instance of X will be injected into it. We can rewrite the example in Listing 3-10 to use simple managed CDI beans instead of EJBs. Listing 3-16 shows the use of the injection annotation on a field. The AuditService instance will get injected after the DeptService instance gets instantiated.

Listing 3-16.  CDI Bean with Field Injection

public class DeptService {
    @Inject AuditService audit;

    // ...
}

The annotation could similarly be placed on a property method to employ setter injection. Yet another way to achieve the same result is to use a third kind of injection called constructor injection. As the name suggests, constructor injection involves the container invoking the constructor method and injecting the arguments. Listing 3-17 shows how constructor injection can be configured. Constructor injection is particularly good for testing outside of the container since a test framework can easily do the necessary injection by simply calling the constructor without having to proxy the object.

Listing 3-17.  CDI Bean with Constructor Injection

public class DeptService {
    private AuditService audit;

    @Inject DeptService(AuditService audit) {
        this.audit = audit;
    }
    // ...
}

Scopes and Contexts

A scope defines a pair of temporal demarcation points: a beginning and an end. For example, a request scope would begin when the request starts and end when the reply has been sent back. Similarly, other scopes define durations based upon client actions and conditions. There are five pre-defined scopes, three of which (request, session, and application) are defined by the servlet specification, one more (conversation) that was added by CDI, and another that was added by the JTA spec:

1. Request: Delineated by a specific client method request.
2. Session: Starts on initiation from an HTTP client and ends upon the termination of the HTTP session. Shared by all requests in the same HTTP session.
3. Application: Global to the entire application for as long as it is active.
4. Conversation: Spans a series of sequential JSF requests.
5. Transaction: Maps to the lifetime of an active JTA transaction.

A bean type is associated with a scope by annotating the bean class with the intended scope annotation. Managed instances of that bean will have a lifecycle similar to the declared scope.

Each scope that is active will have a current context associated with it. For example, when a request arrives, a request context will be created for that request scope. Each request will have its own current request context, but there will be a single session scoped context for all of the requests coming from the same HTTP session. The context is just the place where the scoped instances reside for the duration of the scope. There can be only one instance of each bean type in each context.

The application scoped AuditService bean that would be injected into the DeptService bean in Listings 3-16 or 3-17 would look like the following:

@ApplicationScoped
public class AuditService { ... }

Because it is application scoped, only a single instance would be created by CDI and reside in the application scoped context. Note that this is similar to a singleton EJB in that only a single instance would be created and used by the entire application.

An additional scope, dependent, also exists, but is really the absence of scope. If no scope is specified, then the dependent scope is assumed, meaning that no instances of the bean are put into any context and a new instance is created each time an injection of that bean type occurs. The @Dependent annotation can be used to explicitly mark a bean as being dependent. Scope annotations are defined in the javax.enterprise.context package.

Qualified Injection

A qualifier is an annotation that is used to constrain or distinguish a bean type from other bean types that have the same inherited or implemented interface type. A qualifier can help the container resolve which bean type to inject.

The qualifier annotation class is typically defined by the application and then used to annotate one or more bean classes. The qualifier annotation definition should be annotated with the @Qualifier meta-annotation, defined in the javax.inject package. An example of defining a qualifier annotation is in Listing 3-18.

Listing 3-18.  Qualifier Annotation Definition

@Qualifier
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface Secure { }

This annotation can now be used on a bean class, such as the new SecureDeptService bean shown in Listing 3-19. The qualifier indicates that the bean is a secure variety of DeptService, as opposed to a regular (non-secure?) one.

Listing 3-19.  Qualified Bean Class

@Secure
public class SecureDeptService extends DeptService { ... }

When a DeptService is to be injected into another component, the qualifier can be placed at the injection site and CDI will activate its resolution algorithm to determine which instance to create. It will match the qualifiers to use the SecureDeptService instead of DeptService. Listing 3-20 shows how a servlet, for example, might inject a secure DeptService without even having to know the name of the subclass.

Listing 3-20.  Qualified Injection

public class LoginServlet extends HttpServlet {

    @Inject @Secure DeptService deptService
;
    // ...
}

Producer Methods and Fields

When the container needs to inject an instance of a bean type, it will first look in the current contexts to see if one already exists. If it does not find one, then it must obtain or create a new instance. CDI provides a way for the application to control the instance that gets "created" for a given type by using a producer method or field.

A producer method is a method that the CDI container will invoke to obtain a new bean instance. The instance may be instantiated by the producer method or the producer may obtain it through some other means; it is entirely up to the implementation of the producer method how it produces the instance. Producer methods may even decide based on runtime conditions to return a different bean subclass.

A producer method can be annotated with a qualifier. Then when an injection site is similarly qualified, the container will call that correspondingly qualified producer method to obtain the instance.

In Listing 3-21, we show a producer method that returns new secure instances of DeptService. This might be useful, for example, if we were not able to modify the SecureDeptService class to annotate it with the @Secure annotation as we did in Listing 3-19. We could instead declare a producer method that returned instances of SecureDeptService and they would be injected into fields qualified with @Secure (such as the one shown in Listing 3-20). Note that a producer method may be on any managed bean. It may be a static or instance method, but it must be annotated with @Produces. We have created a bean class named ProducerMethods to hold the producer method and separate it from the rest of the application logic.

Listing 3-21.  Producer Method

public class ProducerMethods {

    @Produces @Secure
    DeptService secureDeptServiceProducer() {
        return new SecureDeptService();
    }
}

Producer fields work the same way as producer methods except that the container accesses the field to get the instance instead of invoking a method. It is up to the application to ensure that the field contains an instance when the container needs it. You will see an example of using a producer field in the next section.

Using Producer Methods with JPA Resources

Now that you know some of the basics of CDI, it's time to learn how CDI can be used to help manage JPA persistence units and contexts. You can use a combination of Java EE resource injection with CDI producer fields and qualifiers to inject and maintain your persistence contexts.

Let's assume we have two persistence units, one named "Employee" and the other named "Audit". We want to use CDI beans and contextual injection. We will create a class named EmProducers and use producer fields and Java EE resource injection to obtain the entity managers. The producer code and qualifier annotation definitions are in Listing 3-22.

Listing 3-22.  Producer Class and Qualifier Annotation Definitions

@RequestScoped
public class EmProducers {

    @Produces @EmployeeEM
    @PersistenceContext(unitName="Employee")
    private EntityManager em1;

    @Produces @AuditEM
    @PersistenceContext(unitName="Audit")
    private EntityManager em2;

}

@Qualifier
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface EmployeeEM { }

@Qualifier
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface AuditEM { }

The Java EE @PersistenceContext annotation will cause the Java EE container to inject the producer fields with the entity manager for the given persistence unit. The producer fields will then be used by CDI to obtain the entity manager with the matching qualifier of the injection site. Because the producer class is request scoped, new entity managers will be used for each request. The appropriate scope will obviously depend upon the application architecture. The only thing left to do is to have a bean that is injected with these entity managers. A corresponding DeptService bean that references the entity managers is shown in Listing 3-23. A same approach could just as easily be used to inject an entity manager factory using the @PersistenceUnit resource annotation.

Listing 3-23.  DeptService Bean with Injected EntityManager Fields

public class DeptService {

    @Inject @EmployeeEM
    private EntityManager empEM;

    @Inject @AuditEM
    private EntityManager auditEM;

    // ...
}

In the majority of our examples we will simply use the @PersistenceContext annotation since it does not involve any additional producer code. It is also supported by Spring and other kinds of JPA containers, so the bean will be more generic.

Transaction Review

A transaction is an abstraction that is used to group together a series of operations. Once grouped together, the set of operations is treated as a single unit, and all of the operations must succeed or none of them can succeed. The consequence of only some of the operations being successful is to produce an inconsistent view of the data that will be harmful or undesirable to the application. The term used to describe whether the operations succeed together or not at all is called atomicity, and it is arguably the most important of the four basic properties that are used to characterize how transactions behave. Understanding these four properties is fundamental to understanding transactions. The following list summarizes these properties:

• Atomicity: Either all the operations in a transaction are successful or none of them are. The success of every individual operation is tied to the success of the entire group.
• Consistency: The resulting state at the end of the transaction adheres to a set of rules that define acceptability of the data. The data in the entire system is legal or valid with respect to the rest of the data in the system.
• Isolation: Changes made within a transaction are visible only to the transaction that is making the changes. Once a transaction commits the changes, they are atomically visible to other transactions.
• Durability: The changes made within a transaction endure beyond the completion of the transaction.

A transaction that meets all these requirements is said to be an ACID transaction (the familiar ACID term being obtained by combining the first letter of each of the four properties).

Not all transactions are ACID transactions, and those that are often offer some flexibility in the fulfillment of the ACID properties. For example, the isolation level is a common setting that can be configured to provide either looser or tighter degrees of isolation than what was described earlier. They are typically done for reasons of either increased performance or, on the other side of the spectrum, if an application has more stringent data consistency requirements. The transactions that we discuss in the context of Java EE are normally of the ACID variety.

Enterprise Transactions in Java

Transactions actually exist at different levels within the enterprise application server. The lowest and most basic transaction is at the level of the resource, which in our discussion is assumed to be a relational database fronted by a DataSource interface. This is called a resource-local transaction and is equivalent to a database transaction. These types of transactions are manipulated by interacting directly with the JDBC DataSource that is obtained from the application server. Resource-local transactions are used less frequently in servers than container transactions.

The broader container transaction uses the Java Transaction API (JTA) that is available in every compliant Java EE application server and most of the Java-based web servers. This is the typical transaction that is used for enterprise applications and can involve or enlist a number of resources, including data sources as well as other types of transactional resources. Resources defined using Java Connector Architecture (JCA) components can also be enlisted in the container transaction.

Containers typically add their own layer on top of the JDBC DataSource to perform functions such as connection management and pooling that make more efficient use of the resources and provide a seamless integration with the transaction management system. This is also necessary because it is the responsibility of the container to perform the commit or rollback operation on the data source when the container transaction completes.

Because container transactions use JTA and because they can span multiple resources, they are also called JTA transactions or global transactions. The container transaction is a central aspect of programming within Java servers.

@Stateless
@TransactionManagement(TransactionManagementType.BEAN)
public class ProjectService {
    // methods in this class manually
control transaction demarcation
}

@Stateful
public class ShoppingCart {

    @TransactionAttribute(TransactionAttributeType.SUPPORTS)
    public void addItem(String item, Integer quantity) {
        verifyItem(item, quantity);
        // ...
    }

    // ...
}

@Transactional
@SessionScoped
public class ShoppingCart {

    @Transactional(TxType.SUPPORTS)
    public void addItem(String item, Integer quantity) {
        verifyItem(item, quantity);
        // ...
    }

    // ...
}

public interface UserTransaction {
    public abstract void begin();
    public abstract void commit();
    public abstract int getStatus();
    public abstract void rollback();
    public abstract void setRollbackOnly();
    public abstract void setTransactionTimeout(int seconds);
}

public class ProjectServlet extends HttpServlet {
    @Resource UserTransaction tx;
    @EJB ProjectService bean;

    protected void doPost(HttpServletRequest request, HttpServletResponse response)
        throws ServletException, IOException {
        // ...

        try {
            tx.begin();
            bean.assignEmployeeToProject(projectId, empId);
            bean.updateProjectStatistics();
            tx.commit();
        } catch (Exception e) {
            // Try to roll back (may fail if exception came from begin() or commit(), but that's ok)
            try { tx.rollback(); } catch (Exception e2) {}
            throw new MyRuntimeException(e);
        }

        // ...
    }
}

Defining the Component

To begin, let’s consider the definition of the EmployeeService class from Listing 2-9 in Chapter 2. The goal of this class is to provide business operations related to the maintenance of employee data. In doing so, it encapsulates all the persistence operations. To introduce this class into the Java EE environment, we must first decide how it should be represented. The service pattern exhibited by the class suggests a session bean or similar component. Because the business methods of the bean have no dependency on each other, we can further decide that any stateless bean, such as a stateless session bean, is suitable. In fact, this bean demonstrates a very typical design pattern called a session façade⁵, in which a stateless session bean is used to shield clients from dealing with a particular persistence API. To turn the EmployeeService class into a stateless session bean we need only annotate it with @Stateless.

In the Java SE example, the EmployeeService class must create and maintain its own entity manager instance. We can replace this logic with dependency injection to acquire the entity manager automatically. Having decided on a stateless session bean and dependency injection, the converted stateless session bean is demonstrated in Listing 3-29. With the exception of how the entity manager is acquired, the rest of the class is identical. This is an important feature of the Java Persistence API because the same EntityManager interface can be used both inside and outside of the application server.

Listing 3-29.  The EmployeeService Session Bean

@Stateless
public class EmployeeService {
    @PersistenceContext(unitName="EmployeeService")
    protected EntityManager em;

    EntityManager getEntityManager() {
        return em;
    }

    public Employee createEmployee(int id, String name, long salary) {
        Employee emp = new Employee(id);
        emp.setName(name);
        emp.setSalary(salary);
        getEntityManager().persist(emp);
        return emp;
    }

    public void removeEmployee(int id) {
        Employee emp = findEmployee(id);
        if (emp != null) {
            getEntityManager().remove(emp);
        }
    }

    public Employee changeEmployeeSalary(int id, long newSalary) {
        Employee emp = findEmployee(id);
        if (emp != null) {
            emp.setSalary(newSalary);
        }
        return emp;
    }

    public Employee findEmployee(int id) {
        return getEntityManager().find(Employee.class, id);
    }

    public List<Employee> findAllEmployees() {
        TypedQuery query = getEntityManager().createQuery("SELECT e FROM Employee e", Employee.class);
        return query.getResultList();
    }
}

Defining the User Interface

The next question to consider is how the bean will be accessed. A web interface is a common presentation method for enterprise applications. To demonstrate how this stateless session bean might be used by a servlet, consider Listing 3-30. The request parameters are interpreted to determine the action, which is then carried out by invoking methods on the injected EmployeeService bean. Although only the first action is described, you can see how this could easily be extended to handle each of the operations defined on EmployeeService.

Listing 3-30.  Using the EmployeeService Session Bean from a Servlet

public class EmployeeServlet extends HttpServlet {
    @EJB EmployeeService bean;

    protected void doPost(HttpServletRequest request,
                          HttpServletResponse response) {
        String action = request.getParameter("action");

        if (action.equals("create")) {
            String id = request.getParameter("id");
            String name = request.getParameter("name");
            String salary = request.getParameter("salary");
            bean.createEmployee(Integer.parseInt(id), name,
                                Long.parseLong(salary));
        }

        // ...
    }
}

Packaging It Up

In the Java EE environment, many properties required in the persistence.xml file for Java SE can be omitted. In Listing 3-31, you see the persistence.xml file from Listing 2-11 converted for deployment as part of a Java EE application. Instead of JDBC properties for creating a connection, we now declare that the entity manager should use the data source name “jdbc/EmployeeDS”. If the data source was defined to be available in the application namespace instead of the local component naming context, then we might instead use the data source name of “java:app/jdbc/EmployeeDS”. The transaction-type attribute has also been removed to allow the persistence unit to default to JTA. The application server will automatically find entity classes, so even the list of classes has been removed. This example represents the ideal minimum Java EE configuration.

Because the business logic that uses this persistence unit is implemented in a stateless session bean, the persistence.xml file would typically be located in the META-INF directory of the corresponding EJB JAR, or the WEB-INF/classes/META-INF directory of the WAR. We will fully describe the persistence.xml file and its placement within a Java EE application in Chapter 14.

Listing 3-31.  Defining a Persistence Unit in Java EE

<persistence>
    <persistence-unit name="EmployeeService">
        <jta-data-source>jdbc/EmployeeDS</jta-data-source>
    </persistence-unit>
</persistence>