The EntityContext extends the javax.ejb.EJBContext class, which is also the base class for the SessionContext session beans use. EJBContext defines several methods that provide useful information to a bean at runtime.

Here is the definition of the EJBContext interface:

package javax.ejb;
public interface EJBContext {
   
    // EJB home methods
    public EJBHome getEJBHome();
    // EJB 2.0 only
    public EJBLocalHome getEJBLocalHome();
   
    // security methods
    public java.security.Principal getCallerPrincipal();
    public boolean isCallerInRole(java.lang.String roleName);
   
    // transaction methods
    public javax.transaction.UserTransaction getUserTransaction() 
        throws java.lang.IllegalStateException;
    public boolean getRollbackOnly() 
        throws java.lang.IllegalStateException;
    public void setRollbackOnly() 
        throws java.lang.IllegalStateException;

    // deprecated methods
    public java.security.Identity getCallerIdentity();
    public boolean isCallerInRole(java.security.Identity role); 
    public java.util.Properties getEnvironment();

}

The getEJBHome() and getEJBLocalHome() (EJB 2.0) methods return a reference to the bean’s EJB home. This is useful if the bean needs to create or find entity beans of its own type. Access to the EJB home proves more useful in bean-managed entity beans and CMP 1.1 entity beans than in CMP 2.0 entity beans, which have select methods and CMR fields.

As an example, if all of the employees in Titan’s system (including managers) are represented by CMP 1.1 Employee beans, a manager who needs access to subordinate employees can use the getEJBHome() method to get beans representing the appropriate employees:

public class EmployeeBean implements EntityBean {
    int id;
    String firstName;
    ...
    public Enumeration getSubordinates() {            
        Object ref = ejbContext.getEJBHome();
        EmployeeHome home = (EmployeeHome)
            PortableRemoteObject.narrow(ref, EmployeeHome.class);
        Integer primKey = (Integer)context.getPrimaryKey();
        Enumeration subordinates = home.findByManagerID(primKey);
        return subordinates;
    }
    ...
}

The getCallerPrincipal() method is used to obtain the Principal object representing the client that is currently accessing the bean. The Principal object can, for example, be used by the Ship bean to track the identities of clients making updates:

public class ShipBean implements EntityBean {
    String lastModifiedBy;
    EntityContext context;
    ...
    public void setTonnage(double tons) {
        tonnage = tons;
        Principal principal = context.getCallerPrincipal();
        String modifiedBy = principal.getName();
    }
    ...
}

The isCallerInRole() method tells you whether the client accessing the bean is a member of a specific role, identified by a role name. This method is useful when more access control is needed than simple method-based access control can provide. In a banking system, for example, you might allow the Teller role to make most withdrawals but only the Manager role to make withdrawals of over $10,000. This kind of fine-grained access control cannot be addressed through EJB’s security attributes because it involves a business logic problem. Therefore, we can use the isCallerInRole() method to augment the automatic access control provided by EJB. First, let’s assume that all managers are also tellers. The business logic in the withdraw() method uses isCallerInRole() to make sure that only the Manager role can withdraw sums over $10,000.00:

public class AccountBean implements EntityBean {
    int id;
    double balance;
    EntityContext context;

    public void withdraw(Double withdraw) throws AccessDeniedException {
        
        if (withdraw.doubleValue() > 10000) {
            boolean isManager = context.isCallerInRole("Manager");
            if (!isManager) {
                // Only Managers can withdraw more than 10k.
                throw new AccessDeniedException();
            }
        }
        balance = balance - withdraw.doubleValue();

    }
    ...
}

The EJBContext contains some methods that were used in EJB 1.0 but were deprecated in EJB 1.1 and have been abandoned in EJB 2.0. Support for these deprecated methods is optional for EJB 1.1 containers, which can host EJB 1.0 beans. EJB containers that do not support the deprecated security methods will throw a RuntimeException. The deprecated security methods are based on EJB 1.0’s use of the Identity object instead of the Principal object. The semantics of the deprecated methods are basically the same but, because Identity is an abstract class, it has proven to be too difficult to use.

The getEnvironment() method has been replaced by the JNDI environment naming context, which is discussed later in this book. Support for the deprecated getEnvironment() method in EJB 1.1 is discussed in detail in Chapter 12. The transactional methods—getUserTransaction(), setRollbackOnly(), and getRollbackOnly()—are described in detail in Chapter 14.

The material on the EJBContext covered in this section applies equally well to session and message-driven beans. There are some exceptions, however, and these differences are covered in Chapter 12 and Chapter 13.

Starting with EJB 1.1, the bean-container contract for entity and stateful beans was expanded beyond the EJBContext using the Java Naming and Directory Interface ( JNDI). A special JNDI name space, which is referred to as the environment naming context (ENC), was added to allow any enterprise bean to access environment entries, other beans, and resources (such as JDBC DataSource objects) specific to that enterprise bean.

The JNDI ENC continues to be an extremely important part of the bean-container contract in EJB 2.0. Although we used the JNDI ENC to access JDBC in the bean-managed persistence chapter (Chapter 10), it’s not specific to entity beans. The JNDI ENC is used by session, entity, and message-driven beans alike. To avoid unnecessary duplication, a detailed discussion of this important facility is left for Chapter 12. What you learn about using the JNDI ENC in Chapter 12 applies equally well to session, entity, and message-driven beans.