Head First EJB

Writing a Session Bean: your job as Bean Provider

You put THREE kinds of methods in the bean class:

1. HOME things: ejbCreate() methods

   Write an ejbCreate() method in the bean to match each create() method in the home interface.

   

2. COMPONENT things: business methods

   Write a business method in the bean to match each method in your bean’s component interface.

   

3. SESSION BEAN things: container callbacks from the SessionBean interface

   Implement each of the four methods from the SessionBean interface, which your bean must implement in the official Java way (i.e. using the implements SessionBean declaration either in your bean class or one of its superclasses)

   

Sharpen your pencil

Compiler-checked?

Of the three types of methods you put in your bean, check off the ones the compiler cares about.

Methods to match the Home interface

Methods to match the Component interface

Methods from the SessionBean interface

Sharpen your pencil

Given the following interfaces, write the bean class code (you can leave the method empty) at the bottom of the page. Pay special attention to the Home create method... what does it take to ‘match’ this in the bean? Will it have the same return type? Hints are at the bottom of the page.

import javax.ejb.*;
import java.rmi.RemoteException;

public interface KennelHome extends EJBHome {
   public Kennel create(String custID) throws CreateException, RemoteException;
}

import javax.ejb.*;
import java.rmi.RemoteException;

public interface Kennel extends EJBObject {
   public KennelLease placePet(Pet p) throws RemoteException;
   public void renewLease(KLease lease) throws RemoteException, ExpiredException;
   public Pet getPet(KLease lease) throws RemoteException, DeadPetException;
}

Write the bean class here:

Hints: The home method in the bean has a slightly different name than the one in the home interface. The Container doesn’t need anything back from the bean during creation. Does Java have a rule that says the implementer of an interface must declare the same exceptions in the implementation class, that are declared on the methods in the interface?

Rules for the HOME methods: home interface

1. Local home interfaces must return the local component interface, and Remote home interfaces must return the Remote component interface.

   The return type of a home create method must ALWAYS be the component interface type.

   public interface AdviceLocalHome extends EJBLocalHome {
     public AdviceLocal create() throws CreateException;
   }
   
   public interface AdviceHome extends EJBHome {
     public Advice create() throws CreateException,
                                          RemoteException;
   }

2. Every create method in the home interface must declare a CreateException, regardless of whether the interface is local or Remote. You can also declare your own application (checked) exceptions.

   public Advice create() throws CreateException,
                                       NoAdviceException;

   

3. Local home interfaces must extend EJBLocalHome, and must NOT declare RemoteExceptions.

   public interface AdviceLocalHome extends EJBLocalHome {
     public AdviceLocal create() throws CreateException;
   }

4. Remote home interfaces must extend EJBHome, and must declare RemoteExceptions on every method.

   public interface AdviceHome extends EJBHome {
     public Advice create() throws CreateException,
                                     RemoteException;
   }

5. Stateless beans can have only one create() method, and it must NOT have arguments!

   public Advice create() throws CreateException;

6. Stateful beans must have one or more create() methods, and are NOT required to have a no-arg create(). The create() methods must start with the string “create”, and can be overloaded.

   Foo createBigFoo()
   Foo create()

7. Arguments and return types for Remote home interface methods must be legal RMI-IIOP types (Serializable, primitive, Remote, or collections or arrays of any of those).

Rules for the HOME methods: bean class

1. Every create method in the home must have a matching ejbCreate method in the bean class. The ejbCreate methods in the bean must have a void return type.

   public void ejbCreate() { }

2. The ejbCreate methods must be public and must NOT be marked final or static.

3. You do NOT have to declare the exceptions declared in the home interface, unless you might actually throw those exceptions from your own methods, although it is often good practice to declare CreateException. You MUST not declare RemoteException in your bean class, EVER.

   public void ejbCreate() { } // no declared exceptions,
   // because we don't actually throw any

   

4. You must NOT declare any application exceptions (i.e. checked exceptions) that were not declared in the home interface for that matching create method.

   Note

   The bean home methods must match the home interface methods, except you prefix the bean class methods with ‘ejb’, and capitalize the ‘‘c’ in create to ‘ejbCreate’

   public void ejbCreate() throws FireException { }
   // not legal unless FireException is declared on the
   // home interface create method!!

5. Stateless beans must have only one ejbCreate(), and it must have no arguments.

   public void ejbCreate() { } // must look like this!

6. Stateful beans must have one or more ejbCreate methods (matching the methods of the home interface), and must start with the string “ejbCreate”.

   HOME:
   public Foo createBigFoo() throws CreateException;
   
   BEAN:
   public void ejbCreateBigFoo() { }

Every create in the home must have a matching ejbCreate in the bean class (void return type).

Rules for the BUSINESS methods: component interface

1. Business method names must not begin with the string “ejb”.

2. Arguments and return types for Remote component interface methods must be legal RMI-IIOP types. That means Serializable, primitive, Remote, or an array or collection of any of those (as long as the collection implementation class is itself Serializable).

   public String getAdvice()throws RemoteException;
   // String is Serializable, so this method could be
   // in a Remote component interface
   
   public Socket getTheSocket();
   // Socket is NOT Serializable, so this method must
   // NOT be in a Remote interface (local would be OK)

   Remote component interface methods must have RMI-IIOP types as arguments and return types.

   String doSomething(int i)

   Note

   This method would be legal in either a Remote or local interface, because the argument and return type are legal RMI-IIOP types.

3. Local component interfaces must extend EJBLocalObject and must NOT declare RemoteExceptions.

   public interface AdviceLocal extends EJBLocalObject {
     public String getAdvice();
   }

4. Remote component interfaces must extend EJBObject and must declare RemoteExceptions on every method.

   public interface Advice extends EJBObject{
     public String getAdvice() throws RemoteException;
   }

5. You must not expose the local home or component interface of a bean through a Remote component interface method. In other words, you can’t have a local interface as the return type or argument type in a Remote component interface method.

Rules for the BUSINESS methods: bean class

1. Business methods must be declared as public, and must NOT be declared as final or static.

   public void doBigThings() { }

   Business methods must not throw application (checked) exceptions that aren’t declared in the component interface.

2. Method names must not begin with the string “ejb”.

3. You must NOT pass “this” as an argument or return value. Remember, you don’t want to give out a reference to the bean! Everybody must go through the EJB object (later, we’ll see how to do that).

   public void doStuff(this);  // not legal
   // from within a bean method!

4. Arguments and return types for Remote component interface methods must be legal RMI-IIOP types. That means Serializable, primitive, Remote, or an array or collection of any of those (as long as the collection implementation class is itself Serializable).

   public String getAdvice() { }
   // String is Serializable, so this method could be
   // in a Remote component interface
   
   public Socket getTheSocket() { }
   // Socket is NOT Serializable, so this method must
   // NOT be in a Remote interface (local would be OK)

   Note

   SessionBean extends EnterpriseBean

   There’s nothing in there, BUT... EnterpriseBean is Serializable. So that means your bean is automatically Serializable, without your having said so.

   If you have a scenario where you need to recognize if a bean is Serializable, IT IS, even though you don’t see the bean class say “implements Serializable”.

5. You do NOT have to declare the exceptions declared in the component interface, unless you might actually throw those exceptions from your own methods. You MUST not declare RemoteException in your bean class, EVER.

   public String getAdvice() { } // no declared exceptions,
   // because we don't actually throw any

6. You must NOT declare any application exceptions (i.e. checked exceptions) that were not declared in the component interface for that matching business method.

   public void getAdvice() throws AdviceException { }
   // not legal unless AdviceException is declared on the
   //component interface version of the method!

Other rules for your bean class

1. The class must implement javax.ejb.SessionBean, either directly or indirectly.

   public class AdviceBean implements SessionBean

2. The class must be public, and cannot be final or abstract.

3. The class must have a public, no-arg constructor. (That’s what the Container has to use). We recommend just letting the compiler insert the default constructor, since you do NOT want to put code in the constructor.

   public Advice() { }  // valid bean constructor

4. You must NOT have a finalize() method in your class!

5. The class is not required to (but is allowed to) implement the bean’s component interface. (We talked earlier, remember, about why you probably don’t want to “officially” implement your component interface.)

   Note

   Your bean class can have other methods

   Your bean class has to have the three types of methods: stuff from the home (ejbCreates to match creates), business methods from the component interface, and the four SessionBean methods. But nothing stops you from having your own non-exposed “helper’”methods, and those methods do NOT need to be public.

6. Your class MUST implement the matching home and component interface methods (i.e. an ejbCreate for every create in the home, and a matching business method for every method in the component interface).

7. If the bean is stateful, it can, optionally, implement the SessionSynchronization interface. (This interface gives the bean three more callbacks related to transactions, which we’ll look at in the transactions chapter.)

8. Your bean class can have a superclass. In other words, you can use normal Java inheritance with your bean class. (You just don’t get any special bean-specific inheritance, remember.)

The difference between create and ejbCreate

Note

You can have a return in an ejbCreate().

You KNOW that an ejbCreate() method must have a void return type, but don’t forget your basic Java rules: just because you see a return statement: return; does not mean you’re returning a value. Don’t be fooled by considering anything other than the actual declared return type of the ejbCreate() method.

Note

Pay attention to the “ejb” as in ejbRemove vs. just remove, and ejbCreate vs. create.

True or false: the Container calls a bean’s remove() method if the stateful bean times out while active.

FALSE! The bean doesn’t HAVE a remove() method, only an ejbRemove() method.

Watch for things like, “The Bean Provider is responsible for putting the create() method in the bean.” Not true, because there IS no create() method in the bean, only an ejbCreate().

Be sure to burn it into your head that anything starting with the letters ‘ejb’ is in the bean! Of course it would be easy if that were the ONLY rule... like if everything in the bean starts with “ejb” and nothing in the interfaces starts with ‘“ejb” , but of course that’s not true.

Business methods are identically named in both the component interface and the bean class, and they don’t ever start with “ejb” in either the interface or the bean class.

You also need to keep track of WHO invokes WHAT. For example, who invokes the create() method? The client or the Container? (client). Who invokes ejbCreate() (the Container). Who invokes setSessionContext()? (Container). Who invokes remove()? (client).

Note

Only ONE client can access a session bean at a time, regardless of whether the bean is stateless or stateful!

Session beans must NEVER be accessed by more than one client. If a bean is currently in use by a client and another client invokes a method on the bean, that second client gets an exception! BUT... there is a comment in the spec that says the Container is free to implement stateLESS beans as a single instance of the bean, which the Container then runs the clients through one at a time.

You aren’t supposed to know or care how the Container does it; the only thing you have to care about is that you do NOT have to write code to protect your bean from concurrent access. (Which you know anyway, since you know that you can’t even USE thread-related code in your bean like synchronized, wait, notify, etc.)

Sharpen your pencil

Who does What?

From the list of words below, arrange them in the appropriate lists according to whether it’s a responsibility of the Bean Provider, the Container, or the Client.