4.4 Implementing Services with EJB Session Beans

A session bean exposes the functionality of the business layer to the client.

One common use of a session bean is to implement the session facade J2EE design pattern. A session facade is a session bean that aggregates data and presents it to the application through the service layer. Session facades have methods that access entities as well as methods that expose services to clients. Session beans have a transactional context via the container, so they automatically support persistent CRUD (Create, Retrieve, Update, Delete) functionality.

Figure 4-2 Session Facade Functionality

4.4.1 How to Create a Session Bean

To create a session bean, use the Create Session Bean wizard. This wizard is available from the New Gallery, in the Business Tier category.

To create a session bean:

1. From the File menu in JDeveloper select New->Business Tier->EJB->Session Bean.

2. Follow the steps in the wizard to specify the EJB version, stateful and stateless functionality, and session facade methods. For more information on session facade methods, see Section 4.4.1.1, "Generating Session Facade Methods"

3. On the Class Definitions page, in the Bean Class field, choose a package. For more information about packages, see Section 4.4.1.2, "Choosing a Package".

4. On the Component Interface page, specify the interfaces you want to generate. For more information about interfaces, see Section 4.4.1.3, "Remote, Local and Web Service Interfaces".

Tip: For an SOA application, you should choose an EJB 3.0 version session bean, a stateless session, and container-managed transactions (CMT); bean-managed transactions (BMT) are beyond the scope of this book.

4.4.1.1 Generating Session Facade Methods

A session facade contains core CRUD methods used to create and update entities, as well as methods to access entities. To generate session facade methods, select the checkbox for Generate Session Facade Methods in the Create Session Bean wizard, and use the following page to specify which methods to generate. JDeveloper automatically detects all the entities in the project and allows you to choose which entities and methods to use when creating session facade methods.

Figure 4-3 Selecting Session Facade Methods

You can generate session facade methods for every entity in the same project, which can be useful for testing purposes, but is often too much clutter in a single session bean. Session beans are often tailored to a specific task, and contain no more information than is required for that task. Use the tree control to explicitly choose which methods to generate.

Note: You can create session facade methods for any named queries on your entities. In Figure 4-3, the "find" methods are named queries. When you generate session facade methods for a named query, you may have to specify the return type of the method. For lists and collections, this is not necessary, but for a single object you must specify the return type. For more information, see Section 4.5.3.1, "How to Change the Return Type of a Method That Returns a Single Value".

4.4.1.2 Choosing a Package

In a large application, having all of your objects in the same package can be very confusing. To organize your project you may want to partition your objects in separate packages. For example, in the Customer Service application in the SOA Order Booking application, there are separate packages for the business service (session bean), persistence (JPA entities), and client (Java test client). When you create a session bean, entity, or sample Java client, you have the option of changing the package name in the wizard or dialog, as shown in Figure 4-4:

Figure 4-4 Location of packages in the Applications Navigator

4.4.1.3 Remote, Local and Web Service Interfaces

The type of interface required depends on the client. If the client is running in the same virtual machine (VM), a local interface is usually the best choice. If the client runs on a separate VM, a remote interface is required. Most Web applications (JSF/JSP/Servlet) have the client and service running in the same VM, so a local interface is the best practice. The Customer Service sample application runs everything locally in the same VM. Java clients (ADF Swing) run in a separate VM and require a remote interface.

If you have a stateless session bean that you will use as a web service, select to generate a web service endpoint interface.

4.4.2 What Happens When You Create a Session Bean

The session bean class contains session-wide fields and service methods. When you create a session bean, JDeveloper generates the bean class and a separate file for the local and/or remote interfaces. The remote interface is the name of the session bean, for example, CustomerService.java, while the bean class is appended with Bean.java and the local interface is appended with Local.java.

Note: You should not need to modify the interface files directly, so they are not visible in the Application Navigator. To view the interface files, use the System Navigator or the Structure Pane.

Example 4-3 CustomerServiceBean.java Bean Class

package org.soademo.customerservice.business;
 
import javax.ejb.Stateless;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import org.soademo.customerservice.persistence.Customer;
 
@Stateless(name = "CustomerService")
public class CustomerServiceBean implements CustomerService, 
                                            CustomerServiceLocal {
    @PersistenceContext(unitName = "customerServiceUnit" )
   
    private EntityManager em;
 
    public CustomerServiceBean() {
    }
 
    public Object mergeEntity(Object entity) {
        return em.merge(entity);
    }
 
    public Object persistEntity(Object entity) {
        em.persist(entity);
        return entity;
    }
 
    public Object refreshEntity(Object entity) {
        em.refresh(entity);
        return entity;
    }
 
    public void removeEntity(Object entity) {
        em.remove(em.merge(entity));
    }
 
    /** <code>select object(cust) from Customer cust where cust.custid = :custid</code> */
    public Customer queryCustomerFindCustomerById(String custid) {
        return (Customer)em.createNamedQuery("Customer.findCustomerById").setParameter("custid", 
                                                                              custid).getSingleResult();
    }
 
    public String getCustomerStatus(String CustomerID) {
        return findCustomerById(CustomerID).getStatus();
 
    }
 
    public String addNewCustomer(Customer customer) {
        em.persist(customer);
        return "New customer added sucessfully to customer database";
    }
 
    public Customer findCustomerByEmail(String email, String password) {
        return (Customer)em.createNamedQuery("Customer.findCustomerByEmail").setParameter("email", 
                                                                                          email).setParameter("password", 
                                                                                                              password).getSingleResult();
    }
 
}

4.4.3 What You May Need to Know When Creating a Session Bean

Typically you create one session facade for every logical unit in your application. A logical unit might be defined by its scope within the application. For example, create one session facade for administrative client operations and another session facade for customer client operations. How you create and name your session facades can facilitate UI development, so tailoring your session facades toward a particular task and using names that describe the task is a good practice.

4.4.4 How to Update an Existing Session Bean With New Entities

New session beans can be created at any time using the wizard. However, you may have an existing session bean that already contains custom implementation code that you want to update with new persistent data objects or methods.

To update an existing session bean with new entities:

1. In the Navigator, right click the session bean and choose Edit Session Facade.

2. Use the Session Facade Options dialog to select the entities and methods to expose.

4.4.5 How to Add New Methods to the Session Bean

Once you've created your session bean and entities, you will probably want to create additional methods on the session bean.

The easiest way to create methods is to use the Bean Method Details dialog. Open this dialog by selecting the session bean in the Navigator, and then right clicking the Methods folder in the Structure pane, as shown in Figure 4-5:

Figure 4-5 Using the context menu to add a method

Use the Bean Method Details dialog to specify various details, as shown Figure 4-6:

Figure 4-6 Adding method details to the session bean

Once you've created the method, you need to go to the source file (the bean class) and add implementation code. For example, in the SOA Order Booking application, the following code was used to get a customer's status:

Example 4-4 getCustomerStatus method

public String getCustomerStatus(String CustomerID) {
    return findCustomerById(CustomerID).getStatus();
}