Types of Session Beans

Session beans are of three types:

• Stateless: This type of bean does not maintain any conversational state on behalf of a client application.
• Stateful: This type of bean maintains a state, and a particular instance of the bean is associated with a specific client request. Stateful beans can be seen as extensions to client programs, which are running on the server.
• Singleton: This type of bean is instantiated only once per application. Singleton beans live for the full duration of the application and maintain their state between client invocations.

We will drill down into more specifics of stateless, stateful, and singleton beans in the following sections.

When Do You Use Session Beans?

Session beans are used to write business logic, maintain a conversation state for the client, and model back-end processes or user tasks that perform one or more business operations. Typical examples include the following:

• A session bean in a human resources application that creates a new employee and assigns the employee to a particular department
• A session bean in an expense reporting application that creates a new expense report
• A session bean in an order entry application that creates a new order for a particular customer
• A session bean that manages the contents of a shopping cart in an e-commerce application
• A session bean that leverages transaction services in an EJB container (removing the need for an application developer to write the transaction support)
• A session bean used to address deployment requirements when the client applications are not collocated on the same server
• A session bean that leverages the security support provided by the container on the component or method level
• A session bean that implements logging functionality and is shared between different components of an application

Session beans can be used in traditional 2-tier or 3-tier architectures with professional/rich client applications, or in 3-tier web-based applications. These applications can be deployed in different logical and physical tier combinations. In the next section, we will investigate some of the possible combinations.

The Bean Class

A stateless session bean class is any standard Java class that has a class-level annotation of @Stateless. If deployment descriptors are used instead of annotations, then the bean class should be denoted as a stateless session bean in the ejb-jar.xml descriptor. If you use both annotations and deployment descriptors (mixed mode), then the @Stateless annotation must be specified if any other class-level or member-level annotations are specified in the bean class. If both annotations and deployment descriptors are used, then the settings or values in the deployment descriptor will override the annotations in the classes during the deployment process.

To illustrate the use of stateless session beans, we will create a SearchFacade session bean that provides various search facilities to client applications regarding available wines. The workflow is as follows:

1. Users of the application will type in or choose one or more search criteria, which will be submitted to the SearchFacade session bean.
2. The SearchFacade bean will access back-end databases to retrieve the requested information. To simplify the code examples in this chapter, we will actually retrieve the list of hard-coded values within the bean class. In later chapters, we will augment the SearchFacade bean to access the back-end database.
3. The bean returns to the client applications the information that satisfied the search criteria.

Listing 2-1 shows the definition of the SearchFacade bean. In the following sections of this chapter, we will build the code that will show the preceding workflow in action. SearchFacadeBean is a standard Java class with a class-level annotation of @Stateless.

Listing 2-1.  SearchFacadeBean.java

package com.apress.ejb.chapter02;
import javax.ejb.Stateless;
@Stateless(name="SearchFacade")
public class SearchFacadeBean implements SearchFacade, SearchFacadeLocal {
    public SearchFacadeBean() {
    }
}

The Business Interface

A stateless session business interface is a standard Java interface with no other special requirements. This interface has a list of business method definitions that will be available for the client application. A session bean can have a business interface that is implemented by the bean class, generated at design time by tools such as JDeveloper, NetBeans, or Eclipse, or generated at deployment time by the EJB container.

Business interfaces can also use annotations, as described in the following list:

• The @Remote annotation can be used to denote the remote business interface.
• The @Local annotation can be used to denote the local business interface.

If no annotation is specified in the interface, then the public methods of the bean class itself become its own de facto local interface.

If your architecture has a requirement whereby the client application (web application or rich client) has to run on a different Java Virtual Machine (JVM) from the one that is used to run the session beans in an EJB container, then you need to use the remote interface. The separate JVMs can be on the same physical machine or on separate machines. If your application architecture is going to use the same JVM for both the client application and the session beans, then performance is improved by using a local interface (which can be the no-interface option).

It is possible that your application architecture requires both remote and local interfaces. For example, an enterprise might have an order entry application that is developed using session beans that have business methods for submitting new orders and also addressing administrative tasks, such as data entry for the products. Potentially, you could have two different client applications that access the back-end order entry application, as follows:

• A web client application (as shown in Figure 2-3) that can be run in the same JVM as the session bean and used to submit new orders

  

  Figure 2-3.  A web client using local interfaces of session beans

• A rich client application (as shown in Figure 2-4) that runs on an end-user desktop machine and is used by the administrator for data entry purposes

  

  Figure 2-4.  A rich client using remote interfaces of session beans

The SearchFacade session bean has both remote and local interfaces, as shown in Figure 2-5.

Listing 2-2 shows the code snippet for the SearchFacade remote business interface with an @Remote annotation and a wineSearch() method declaration. The wineSearch() method takes one parameter that represents the type of the wine, and it returns a list of wines that match the wine type criteria.

Listing 2-2.  SearchFacade.java

package com.apress.ejb.chapter02;
import java.util.List;
import javax.ejb.Remote;

@Remote
public interface SearchFacade {
    List wineSearch(String wineType);
}

Listing 2-3 shows the code snippet for the SearchFacade local business interface with an @Local annotation and a wineSearch() method declaration.

Listing 2-3.  SearchFacadeLocal.java

package com.apress.ejb.chapter02;
import java.util.List;
import javax.ejb.Local;

@Local
public interface SearchFacadeLocal {
    List wineSearch(String wineType);
}

Business Methods

The methods implemented in the bean class must correspond to the business methods declared in the remote or local business interfaces. They are matched up based on the convention that they have the same name and method signature. Other methods in the bean class that do not have the corresponding declaration in the business interfaces will be private to the bean class methods.

The SearchFacade bean implements one method, wineSearch(), which has been declared in both remote and local business interfaces. The wineSearch() method returns a static wines list based on the type of wine. Listing 2-4 shows the implementation for wineSearch().

Listing 2-4.  SearchFacadeBean.java

package com.apress.ejb.chapter02;
import java.util.ArrayList;
import java.util.List;
import javax.ejb.Stateless;

@Stateless(name="SearchFacade")
public class SearchFacadeBean implements SearchFacade, SearchFacadeLocal {
    public SearchFacadeBean() {
    }

    public List wineSearch(String wineType) {
        List wineList = new ArrayList();
        if (wineType.equals("Red")) {
        wineList.add("Bordeaux");
        wineList.add("Merlot");
        wineList.add("Pinot Noir");
        }
        else if (wineType.equals("White")) {
        wineList.add("Chardonnay");
        }

        return wineList;
    }
}

public void <METHOD>(Object)

public java.util.concurrent.Future<V> <METHOD>(Object) throws <APPLICATION-EXCEPTION>

Dependency Injection

In Chapter 1, we introduced the concept of dependency injection as a programming design pattern. In this section, we will take a cursory look into using dependency injection in stateless session beans. Dependency injection is discussed in detail in Chapter 10.

EJB containers provide the facilities to inject various types of resources into stateless session beans. Typically, in order to perform user tasks or process requests from client applications, the business methods in the session bean require one or more types of resources. These resources can be other session beans, data sources, or message queues. Managed beans can be injected into session beans using Contexts and Dependency Injection (CDI).

The resources that the stateless session bean is trying to use can be injected using annotations or deployment descriptors. Resources can be acquired by annotation of instance variables or annotation of the setter methods. Listing 2-5 shows an example of setter and instance variable–based injection of myDb, which represents the data source.

Listing 2-5.  Data Source Injection

@Resource
DataSource myDb;

// or
@Resource
public void setMyDb(DataSource myDb) {
    this.myDb = myDb;
}

You’ll typically use the setter injections to preconfigure or initialize properties of the injected resource.

Lifecycle Callback Methods

There will be certain instances or use cases in which the application using session beans requires fine-grained control over lifecycle events like its own creation, removal, and so on. For example, the SearchFacade session bean might need to perform some database initialization when it is created or close some database connections when it is destroyed. The application can gain fine-grained control over the various stages of the bean lifecycle via methods known as callback methods. A callback method can be any method in the session bean that has callback annotations. The EJB container calls these methods at the appropriate stages of the bean’s lifecycle (bean creation and destruction).

Following are two such callbacks for stateless session beans:

• PostConstruct: Denoted with the @PostConstruct annotation. Methods on the bean class that use a specific signature, as described below, can be marked with this annotation.
• PreDestroy: Denoted with the @PreDestroy annotation. Again, any method in the bean class with a specific signature, as described below, can be marked with this annotation.

Callback methods defined on a bean class should have the following signature:

void <METHOD>()

Callback methods can also be defined on a bean’s listener class; these methods should have the following signature:

void <METHOD>(Object)

where Object may be declared as the actual bean type, which is the argument passed to the callback method at run time. Lifecycle callback methods can have public, private, protected, or package level access. A lifecycle callback method must not be declared as final or static.

PostConstruct callbacks happen after a bean instance is instantiated in the EJB container. If the bean is using any dependency injection mechanisms for acquiring references to resources or other objects in its environment, PostConstruct will occur after injection is performed and before the first business method in the bean class is called. In the case of the SearchFacade session bean, you could have a business method, wineSearchByCountry(), which would return the wine list for a particular country and have a PostConstruct callback method, initializeCountryWineList(), that would initialize the country’s wine list whenever the bean gets instantiated. Ideally, you would load the list from a back-end datastore; but in this chapter, we will just use some hard-coded values that get populated into a HashMap, as shown in Listing 2-6.

Listing 2-6.  The PostConstruct Method

@PostConstruct
public void initializeCountryWineList() {
    // countryMap is HashMap
    countryMap.put("Australia", "Sauvignon Blanc");
    countryMap.put("Australia", "Grenache");
    countryMap.put("France","Gewurztraminer");
    countryMap.put("France","Bordeaux");
}

The PreDestroy callback happens before the container destroys an unused or expired bean instance from its object pool. This callback can be used to close any connection pool that has been created with dependency injection and also to release any other resources.

In the case of the SearchFacade session bean, we could add a PreDestroy callback method (destroyWineList()) into the SearchFacade bean, which would clear the country wine list whenever the bean gets destroyed. Ideally, during PreDestroy, we would close any resources that have been created with dependency injection; but in this chapter, we will just clear the HashMap that has the countries and wine list. Listing 2-7 shows the destroyWineList() code.

Listing 2-7.  The PreDestroy Method

@PreDestroy
public void destroyWineList() {
    countryMap.clear();
}

Interceptors

The EJB specification provides annotations called interceptors, which allow you to interpose on a business method invocation to add your own wrapper code before and/or after the method is called. An interceptor method can be defined for session and message-driven beans (MDBs). We will show you the usage of interceptors in the session bean context.

There are number of use cases for interceptors in a typical application in which you would find a need to perform a certain task before or after the business method is invoked. For example, you may wish to do one of the following:

• Perform additional security checks before a critical business method that transfers more than $100,000 dollars
• Do some performance analysis to compute the time it takes to perform the task
• Do additional logging before or after the method invocation

There are two ways to define an interceptor. You can either add an @AroundInvoke annotation on a particular method, or you can annotate the bean class to designate an interceptor class that will interpose on all (or an explicit subset of) methods on the bean class. An interceptor class is denoted by the @Interceptor annotation on the bean class with which it is associated. In the case of multiple interceptor classes, the @Interceptors annotation is used. Method specific interceptor is denoted by applying the @Interceptors annotation to the business method. Methods that are annotated with @AroundInvoke should have the following signature:

Object <METHOD>(InvocationContext) throws Exception

AroundInvoke methods can have public, private, protected, or package level access. An AroundInvoke method must not be declared as final or static. The definition of InvocationContext is as follows:

package javax.ejb;
public interface InvocationContext {
   public Object getBean();
   public java.lang.reflect.Method getMethod();
   public Object[] getParameters();
   public void setParameters(Object[] params);
   public EJBContext getEJBContext();
   public java.util.Map getContextData();
   public Object proceed() throws Exception;
}

The following list describes the methods in the preceding code:

• getBean() returns the instance of the bean on which the method was called.
• getMethod() returns the method on the bean instance that was called.
• getParameters() returns the parameters for the method call.
• setParameters() modifies the parameters used for the method call.
• getEJBContext() gives the interceptor methods access to the bean’s EJBContext.
• getContextData() allows values to be passed between interceptor methods in the same InvocationContext instance using the Map returned.
• proceed() invokes the next interceptor, if there is one, or invokes the target bean method.

In the SearchFacade session bean, we can add an interceptor that logs the time taken to execute each business method when invoked by the client applications. Listing 2-8 shows a time log method that will print out the time taken to execute a business method. InvocationContext is used to get the name of bean class and the invoked method name. Before invoking the business method, current system time is captured and deducted from the system time after the business method is executed. Finally, the details are printed out to the console log using System.out.println.

Listing 2-8.  The Interceptor Method

@AroundInvoke
public Object TimerLog (InvocationContext ctx) throws Exception {
    String beanClassName = ctx.getClass().getName();
    String businessMethodName = ctx.getMethod().getName();
    String target = beanClassName + "." + businessMethodName ;
    long startTime = System.currentTimeMillis();
    System.out.println ("Invoking " + target);
    try {
        return ctx.proceed();
    }
    finally {
        System.out.println ("Exiting" + target);
        long totalTime = System.currentTimeMillis() - startTime;
        System.out.println ("Business method" + businessMethodName +
        "in" + beanClassName + "takes" + totalTime + "ms to execute");
    }
}

The Bean Class

A stateful session bean class is any standard Java class that has a class-level annotation of @Stateful. If deployment descriptors are used instead of annotations, the bean class should be denoted as a stateful session bean. In the case of mixed mode, in which you are using annotations and deployment descriptors, the @Stateful annotation must be specified if any other class-level or member-level annotations are specified in the class.

To illustrate a stateful session bean, we will create a ShoppingCart session bean that will keep track of the items added to a user’s shopping cart and their respective quantities. In this chapter, we will use hard-coded values for the shopping cart to illustrate the state and conversation maintenance between the client and stateful session bean. Listing 2-9 shows the definition of a ShoppingCart session bean.

Listing 2-9.  ShoppingCartBean.java

package com.apress.ejb.chapter02;
import javax.ejb.Stateful;
@Stateful(name="ShoppingCart")
public class ShoppingCartBean implements ShoppingCart, ShoppingCartLocal {
    public ShoppingCartBean() {
    }
}

There will be certain use cases in which the application wants to be notified by the EJB container before or after transactions take place and then use these notifications to manage data and cache. A stateful session bean can receive this kind of notification by the EJB container when it implements the javax.ejb.SessionSynchronization interface. This is an optional feature. There are three different types of transaction notifications that the stateful session bean receives from the EJB container:

• afterBegin: Indicates that a new transaction has begun
• beforeCompletion: Indicates that the transaction is going to be committed
• afterCompletion: Indicates that a transaction has been completed

For example, the ShoppingCart session bean could implement the javax.ejb.SessionSynchronization interface to get an afterCompletion notification so that it can clear out the shopping cart cache.

The Business Interface

Business interfaces for stateful session beans are similar to those used for stateless session beans, and they are annotated in the same way, using @Local and @Remote annotations. Local view of stateful session beans can be accessed without a separate local business interface. The ShoppingCart session bean has both remote and local interfaces, as shown in Figure 2-6.

We will primarily use the local interface from our web application. The remote interface is added to facilitate unit testing of the bean in this chapter.

Listings 2-10 and 2-11 show the remote and local ShoppingCart business interfaces, with @Remote and @Local annotations, respectively.

Listing 2-10.  ShoppingCart.java

package com.apress.ejb.chapter02;
import javax.ejb.Remote;
@Remote
public interface ShoppingCart {
}

Listing 2-11.  ShoppingCartLocal.java

package com.apress.ejb.chapter02;
import javax.ejb.Local;
@Local
public interface ShoppingCartLocal {
}

Alternatively, you can use the coding style shown in Listing 2-12, in which you can specify the @Local and @Remote annotations before specifying @Stateful or @Stateless with the name of the business interface.

Listing 2-12.  ShoppingCartBean.java

package com.apress.ejb.chapter02;
import javax.ejb.Local;
import javax.ejb.Remote;
import javax.ejb.Stateful;

@Local({ShoppingCartLocal.class})
@Remote({ShoppingCart.class})
@Stateful(name="ShoppingCart")

public class ShoppingCartBean implements ShoppingCart, ShoppingCartLocal {
    public ShoppingCartBean() {
    }
}

Business Methods

Business methods in stateful session beans are similar to those in stateless session beans. We will augment the ShoppingCart bean by adding business methods that will add and remove wines from the shopping cart and return a list of cart items.

Listing 2-13 shows the ShoppingCart bean implementing the addWineItem(), removeWineItem(), and getCartItems() methods.

Listing 2-13.  ShoppingCartBean.java

package com.apress.ejb.chapter02;
import java.util.ArrayList;
import javax.ejb.Stateful;

@Stateful(name="ShoppingCart")
public class ShoppingCartBean implements ShoppingCart, ShoppingCartLocal {
    public ShoppingCartBean() {
    }
    public ArrayList cartItems;
    public void addWineItem(String wine) {
       cartItems.add(wine);
    }

    public void removeWineItem(String wine) {
       cartItems.remove(wine);
    }

    public void setCartItems(ArrayList cartItems) {
        this.cartItems = cartItems;
    }

    public ArrayList getCartItems() {
        return cartItems;
    }
}

Lifecycle Callback Methods

Stateful session beans support callback events for construction, destruction, activation, and passivation. Following are the callbacks that map to the preceding events:

• PostConstruct: Denoted with the @PostConstruct annotation.
• PreDestroy: Denoted with the @PreDestroy annotation.
• PreActivate: Denoted with the @PreActivate annotation.
• PrePassivate: Denoted with the @PrePassivate annotation.

The PostConstruct callback happens after a bean instance is instantiated in the EJB container. If the bean is using any dependency injection mechanism for acquiring references to resources or other objects in its environment, the PostConstruct event happens after injection is performed and before the first business method in the bean class is called.

In the case of the ShoppingCart session bean, we could have a business method called initialize() that initializes the cartItems list, as shown in Listing 2-14.

Listing 2-14.  The PostConstruct Method

@PostConstruct
public void initialize() {
    cartItems = new ArrayList();
}

The PreDestroy callback happens after any method where an @Remove annotation has been completed. In the case of the ShoppingCart session bean, we could have a business method called exit() that writes the cartItems list into a database. In this chapter, we will just print out a message to the system console to illustrate the callback. Listing 2-15 shows the code for the exit() method, which has the @PreDestroy annotation.

Listing 2-15.  The PreDestroy Method

@PreDestroy
public void exit() {
    // items list into the database.
    System.out.println("Saved items list into database");
}

The @Remove annotation is a useful lifecycle method for stateful session beans. When the method with the @Remove annotation is called, the container will remove the bean instance from the object pool after the method is executed. Listing 2-16 shows the code for the stopSession() method, which has the @Remove annotation.

Listing 2-16.  The Remove Method

@Remove
public void stopSession() {
    // The method body can be empty.
    System.out.println("From stopSession method with @Remove annotation");
}

The PrePassivate callback kicks in when a stateful session bean instance is idle for too long. During this event, the container might passivate and store its state to a cache. The method tagged with @PrePassivate is called before the container passivates the bean instance.

The PostActivate event gets raised when the client application again uses a passivated stateful session bean. A new instance with restored state is created. The method with the @PostActivate annotation is called when the bean instance is ready.

Interceptors

There are some minor differences between interceptors for stateless and stateful session beans. AroundInvoke methods can be used with stateful session beans. For stateful session beans that implement SessionSynchronization, afterBegin occurs before any methods that have AroundInvoke annotations and before the beforeCompletion() callback method.

Exception Handling

The EJB specification outlines two types of exceptions:

• Application exceptions
• System exceptions

Application exceptions are exceptions related to execution of business logic that the client should handle. For example, an application exception might be raised if the client application passes an invalid argument, such as the wrong credit card number.

System exceptions, on the other hand, are caused by system-level faults, such as Java Naming and Directory Interface (JNDI) errors or failure to acquire a database connection. A system exception must be a subclass of a java.rmi.RemoteException or a subclass of a java.lang.RuntimeException that is not an application exception.

From the EJB application point of view, application exceptions are completed by writing application-specific exception classes that subclass the java.lang.Exception class.

In the case of a system exception, the application catches particular exceptions, such as a NamingException that results from a JNDI failure, and throws an EJBException. In this chapter, the examples aren’t using any resources as such, but there are more examples of system exceptions in the later chapters.

The Bean Class

A singleton session bean class is any standard Java class that has a class-level annotation of @Singleton. If deployment descriptors are used instead of annotations, the bean class should be denoted as a singleton session bean. If you are using annotations and deployment descriptors (mixed mode), then the @Singleton annotation must be specified if any other class-level or member-level annotations are specified in the class.

To illustrate a singleton session bean, we will create a ShopperCount session bean that will keep track of the number of users logged onto our shopping website. Listing 2-17 shows the definition of the ShopperCount session bean.

Listing 2-17.  ShopperCountBean.java

package com.apress.ejb.chapter02;

import javax.ejb.Singleton;
import javax.ejb.Startup;
@Singleton (name = "ShopperCount")
@Startup
public class ShopperCountBean {
   private int shopperCounter;

   // Increment number of shopper counter
   public void incrementShopperCount() {
       shopperCounter++;
   }

   // Return number of shoppers
   public int getShopperCount() {
       return shopperCounter;
   }
}

A singleton session bean is instantiated at the discretion of the EJB container. However, you can annotate the bean class with @Startup to indicate that the container must initialize the singleton bean during the application startup sequence.

When multiple singleton session beans are used within an application, the application might require that they be initialized in a specific sequence. @DependsOn annotation declares the startup dependencies of a singleton session bean. Listing 2-18 shows the definition of the LogShopperCount session bean that is dependent on the ShopperCount session bean.

Listing 2-18.  LogShopperCount.java

package com.apress.ejb.chapter02;

import javax.ejb.Singleton;
import javax.ejb.Startup;
import javax.ejb.DependsOn;
import java.util.logging.Logger;

@Singleton
@Startup
@DependsOn("ShopperCount")
public class LogShopperCount {
   private final Logger log = Logger.getLogger("LogShopperCount.class");

   public void logShopperCount() {
       // Log shopper count
   }
}

Unlike stateless and stateful session beans, a singleton session bean must not implement the javax.ejb.SessionSynchronization interface or use session synchronization annotations.

The Business Interface

Business interfaces for singleton session beans are similar to the interfaces for stateless and stateful session beans, and they are annotated in the same way using @Local and @Remote annotations. Singleton session beans support the no-interface local view, making the declaration of a business interface optional for a local view.

Business Methods

Business methods in singleton session beans are similar to the methods in stateless and stateful session beans. We will augment the ShopperCount bean by adding a business method that will reset the counter.

Listing 2-19 shows the ShopperCount bean implementing business methods.

Listing 2-19.  ShopperCountBean.java

package com.apress.ejb.chapter02;

import javax.ejb.Singleton;
import javax.ejb.Startup;

@Singleton(name = "ShopperCount")
@Startup
public class ShopperCountBean {
   private int shopperCounter = 0;

   // Increment number of shopper counter
   public void incrementShopperCount() {
       shopperCounter++;
   }

   // Return number of shoppers
   public int getShopperCount() {
       return shopperCounter;
   }

   // Reset counter
   public void resetCounter() {
       shopperCounter = 0;
   }
}

Lifecycle Callback Methods

Singleton session beans support callback events for construction and destruction. Following are the callbacks that map to the preceding events:

• PostConstruct: Denoted with the @PostConstruct annotation
• PreDestroy: Denoted with the @PreDestroy annotation.

PostConstruct callback happens after a bean instance is instantiated in the EJB container. If the bean is using any dependency injection mechanism for acquiring references to resources or other objects in its environment, the PostConstruct event happens after injection is performed and before the first business method in the bean class is called.

PreDestroy callback happens during application shutdown. The container considers the DependsOn relationship between singleton session beans and removes them in a sequence that is in the reverse order of the sequence in which they were created. For the ShopperCount example, LogShopperCount bean will be removed before the ShopperCount bean.

Listing 2-20 shows the code for the applicationStartup() method with the @PostConstruct annotation. This method resets the shopperCounter on startup. Listing 2-20 also shows the code for the applicationShutdown() method with the @PreDestroy annotation. This method prints a message on application shutdown.

Listing 2-20.  ShopperCountBean.java

package com.apress.ejb.chapter02;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.Singleton;
import javax.ejb.Startup;

@Singleton(name = "ShopperCount")
@Startup
public class ShopperCountBean {
   private int shopperCounter;

   // Increment number of shopper counter
   public void incrementShopperCount() {
       shopperCounter++;
   }

   // Return number of shoppers
   public int getShopperCount() {
       return shopperCounter;
   }

   // Reset counter
   public void resetCounter() {
       shopperCounter = 0;
   }

   // Reset counter
   @PostConstruct
   public void applicationStartup() {
       System.out.println("From applicationStartup method.");
       resetCounter();
   }

   @PreDestroy
   public void applicationShutdown() {
      System.out.println("From applicationShutdown method.");
   }
}

Like a stateless session bean, a singleton session bean is never passivated, so the @PrePassivate and @PostActivate annotations should not be used to decorate methods on a singleton session bean.

Concurrency Management

A singleton session bean is instantiated only once per application, and hence it is designed to support concurrent access. Concurrent access means multiple clients can access the same instance of a singleton session bean at the same time. The management of concurrent access is transparent to the clients. A client needs only a reference to a singleton session bean, and it is unconcerned about other clients accessing the same instance of the singleton session bean.

Concurrency is managed in two ways:

• Container-Managed concurrency: The container controls concurrent access and allows fine-grained control of the state synchronization behavior by offering a fixed set of options. This is the default concurrency management type.
• Bean-Managed concurrency: The container allows full access to the concurrent bean instance, and the user is responsible for state synchronization.

The type of concurrency—container-managed or bean-managed—is specified by the javax.ejb.ConcurrencyManagement annotation specified on the singleton session bean class. For container-managed concurrency, the type attribute of @ConcurrencyManagement is set to javax.ejb.ConcurrencyManagementType.CONTAINER; for bean-managed concurrency, the type attribute of @ConcurrencyManagement is set to javax.ejb.ConcurrencyManagementType.BEAN.

package com.apress.ejb.chapter02;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.ConcurrencyManagement;
import javax.ejb.ConcurrencyManagementType;
import javax.ejb.Lock;
import javax.ejb.LockType;
import javax.ejb.Singleton;
import javax.ejb.Startup;

@Singleton(name = "ShopperCount")
@Startup
@ConcurrencyManagement(ConcurrencyManagementType.CONTAINER)
public class ShopperCountBean {
    private int shopperCounter;
    // Increment number of shopper counter
    @Lock(LockType.WRITE)
    public void incrementShopperCount() {
        shopperCounter++;
    }

    // Return number of shoppers
    @Lock(LockType.READ)
    public int getShopperCount() {
        return shopperCounter;
    }

    // Reset counter
    public void resetCounter() {
        shopperCounter = 0;
    }

    // Reset counter
    @PostConstruct
    public void applicationStartup() {
        resetCounter();
    }

    @PreDestroy
    public void applicationShutdown() {
        System.out.println("From applicationShutdown method.");
    }
}

Error Handling

Errors can occur during initialization of a singleton session bean. These errors are fatal and, as a result, the singleton session bean instance must be discarded. Attempted invocations on a singleton session bean instance that failed to initialize will result in the javax.ejb.NoSuchEJBException. Once a singleton session bean is instantiated successfully, it will not be destroyed if exceptions are thrown from either business methods or callbacks.

Calendar-Based Time Expressions

The Timer Service is inspired by the UNIX cron utility. Table 2-1 lists the various attributes of a calendar-based time expression.

Examples of Calendar-Based Time Expressions

Let us see some examples that demonstrate the use of calendar-based time expressions.

• “Every second of every minute of every hour of everyday”

• @Schedule(second="*", minute="*", hour="*")

• “Every fifteen minutes within the hour”

• @Schedule(minute="*/15", hour="*")
• @Schedule(minute="0, 15, 30, 45", hour="*")

• “Every Friday at midnight”

• @Schedule(dayOfWeek="Fri")

• “Every six hours on weekends”

• @Schedule(hour="*/6", dayOfWeek="Sat, Sun")

• “Every weekday morning at 7:30am U.S. Pacific Time”

• @Schedule(minute="30", hour="7", dayOfWeek="Mon-Fri", timezone="America/Los_Angeles")

• “On 10th of January and September at 6am”

• @Schedule(month="Jan, Sep", dayOfMonth="10", hour="6")

• “Last Friday of December at 6pm”

• @Schedule(month="Dec", dayOfMonth="Last Fri", hour="18")

• “Second to last day (one day before the last day) of each month”

• @Schedule(dayOfMonth="-1")

• “Every day only for year 2013”

• @Schedule(year="2013")

Timer Persistence

Timers are persistent. A timer is persisted by the Timer Service by storing it in a database. The database used by the Timer Service can be changed by setting the Timer Service’s Timer DataSource setting to a valid JDBC resource. Persistence helps timers survive application shutdown, container crashes, and container shutdowns.

Persistence can be disabled on a per-timer basis by setting the persistent attribute of the @Schedule annotation to false. A non-persistent timer’s lifetime is associated with the JVM that created it. A non-persistent timer is considered cancelled in the event of application shutdown, container crash, or crash/shutdown of the JVM on which the timer was created.

Prerequisites

Before performing any of the steps detailed in the next sections, complete the “Getting Started” section of Chapter 1. This section will walk you through the installation and environment setup required for the samples in this chapter.

Compiling the Session Beans and their Clients

Copy the Chapter02-SessionSamples directory and its contents into a directory of your choice. Run the NetBeans IDE and open the Chapter02-SessionSamples project using the File Open Project menu. Make sure the Open Required Projects checkbox is checked.

Expand the Chapter02-SessionSamples-ejb node and observe that the three session beans that we created appear in the com.apress.ejb.chapter02 package. Similarly, the three client servlets appear under the Chapter02-SessionSamples-war node.

Invoke the context menu on Chapter02-SessionSamples node and build the application by selecting the Clean and Build menu option.

Deploying the Session Beans and their Clients

Once you have compiled the session beans and the servlet clients, you can deploy the application to the GlassFish application server. Invoke the context menu on Chapter02-SessionSamples node and deploy the application by selecting the Deploy menu option.

NetBeans will start the integrated GlassFish application server and deploy the application to the server. The server’s log window will log the deployment status of the application.

Running the Client Programs

Once the session beans and their client servlets are successfully deployed, we need to set the run target that we wish to execute. We have a choice of 3 run targets: ShopperCountClient, SearchFacadeClient, or ShoppingCartClient. To set the run target invoke the context menu on Chapter02-SessionSamples node and select the Properties menu option. Select the Run category and enter the run target in Relative URL text field and OK the dialog.

To run the client servlets invoke the context menu on Chapter02-SessionSamples node and select the Run menu option.

NetBeans will open your default browser and execute the selected servlet. Here is the output for the 3 client servlets.