Head First EJB

Five things you do to build a bean:

1. Code the bean class with all of the business methods.

   

2. Code two interfaces for the bean: home and component.

   

3. Create an XML deployment descriptor that tells the server what your bean is and how it should be managed. You must name it ejb-jar.xml.

   

4. Put the bean, the interfaces, and the deployment descriptor into an ejb-jar file. (There might be more than one bean in the ejb-jar, but there will always be just one deployment descriptor.)

   

5. Deploy the bean into the server, using the tools provided by the server vendor.

   

Relax

You don’t need to be an XML expert.

In fact, you don’t have to know anything at all about how XML works. You do need to know about many of the deployment descriptor tags, but you don’t need to know about XML in order to learn the tags. If you think of the tags as simply labels in a document, with very specific requirements for what you’re allowed to type within those labels, then all you need to know for the exam is the name, and requirements, for some of the most important labels (tags). We’ll look at those crucial tags in several chapters.

1 bean class

2 interfaces

3 XMLDD

4 ejb-jar

5 deploy

1. Write the bean class with the actual business methods the client calls.

   This is where it all happens. The implementation of your business methods defined in the component interface. In other words, you write your business logic in the bean class.

   There are three bean types to choose from, Session, Entity, and Message-driven, and we’ll cover each one in detail in later chapters of the book. Before making a bean, though, you must decide what type you need because your bean class must implement one of three interfaces, depending on the type you choose.

   We’ve chosen a Session bean here because it’s perfect for the Advice Guy application. Advice Guy gives back an advice String when you invoke the surprisingly-named getAdvice() method. So our bean class (on the next page) implements the SessionBean interface. And SessionBean isn’t just a marker interface^[2]—it has methods your bean class must implement.

   The methods you implement from the SessionBean interface are known as container-callbacks, because the container uses them to notify you of important milestones in the bean’s life.

   

   Watch it!

   You must know how to write all the code by hand, without using an EJB-ready development tool.

   You’re expected to know how to write the two interfaces and the bean class (or, for message-driven beans, just the bean class). That means you should NOT use an EJB-aware development tool that builds some of the bean or interface code for you, until you’re certain you know exactly what code the tool is creating for you.

   There’s a pile of rules you need to know for the exam, and in the next few chapters we’ll get into the gory details. For now, don’t worry about memorizing anything from the code in this exercise. Just know that you WILL need to learn it all before we’re done.

   There is some good news, however—you CAN use a tool to build the XML deployment descriptor. The exam doesn’t expect you to memorize all the XML tags! (Although you will need to know a few elements; we’ll cover them later.)

   Bean class

   

   The AdviceBean implements the SessionBean interface, so it must implement the methods declared in javax.ejb.SessionBean. We’ll grill you on everything a little later, for now, just remember that the bean class is where your actual business logic goes. In other words, the reason your bean exists in the first place. For the Advice Guy, that means the getAdvice() method.

   

   1 bean

   2 interfaces

   3 XML DD

   4 ejb-jar

   5 deploy

   

2. Write two interfaces for the bean.

   These are the interfaces the client sees. We have an entire chapter devoted to these interfaces, so you don’t have to understand it all now.

   COMPONENT interface

   This is where all the business methods are declared. In other words, it’s where you put the methods the client wants to call.

   

   component interface: business methods

   

   HOME interface

   The client uses the home interface to ask for a reference to the component interface. The home is the client’s starting point for getting hold of a reference to a bean (or at least what the client thinks is the bean, but we’ll get to that later). For now, think of the home as a kind of factory that makes and distributes bean references to clients.

   

   home interface: a factory for bean references

   
   

   Hmmm... two good questions. In a non-bean Java world, the way we’re doing things here wouldn’t make much sense. But bean world has different rules and practices. We could write the interfaces first, and some developers do. Sometimes the choice of which to develop first depends on the development tools you’re using to build your beans. Some tools, for example, expect you to first build your bean (coding the actual business logic), and then the tool will build the interfaces to match. And some tools do just the opposite, looking at the interfaces and building a “your code goes here” bean class, with all of the methods from the interface. For learning EJB, we like to start with the bean, focusing on the business logic, before figuring out the interfaces. Later in the book, we’ll do it the other way around.

   As for the bean not implementing the component interface, you could do it that way, but this time we strongly urge you not to. On the next page, we’ll look at this in more detail.

   

There are no Dumb Questions

Q:	Q: So why doesn’t the bean class (AdviceBean) implement the component interface (Advice) if it has to implement the same methods? Java classes are allowed to implement more than one interface, so what’s the problem with saying: class AdviceBean implements Advice, SessionBean
A:	A: Legally, the bean class can implement the component interface, but the spec doesn’t recommend it. Remember, although to the client it looks as though the AdviceBean is the object the client’s invoking methods on (the object that implements—in the true Java sense—the component interface), the client really invokes methods on something called an EJBObject, that’s implemented by the server at deploy-time. The client never interacts directly with the bean. Never, ever, ever. Later in the book, you’ll see that if the bean does implement the component interface, you could sneak things past the compiler that would explode at runtime. So we strongly urge you not to have your bean implement the component interface. But there’s another issue as well—the component interface extends another interface. In our example, Advice extends EJBObject, and EJBObject is not a marker interface. It has methods! This means that any class implementing Advice must also implement the methods of EJBObject! So, your bean would end up implementing a bunch of methods it should never have (like getHandle(), getEJBHome()...)
Q:	Q: But there’s an easy solution to THAT problem: you could have the bean extend a class that has all the implementations that you need to satisfy the compiler, but don’t really need to implement in your code. Like the adapter event listener classes in AWT. Why not do something like that here and make a superclass for your bean that implements the methods?
A:	A: Yes, you could do that, and it would be legal. But it still means your bean is capable of having methods invoked that the bean should never know about. The methods of EJBObject are methods for the client to call on the bean, but NOT for the bean to actually implement. So it’s not the best OO practice. And there’s still another reason why it’s not good practice to have the bean implement the component interface—if the interface is remote (and EJBObject is, since it extends the java.rmi.Remote interface), that would make the bean class a Remote class, and that must never be! The bean is protected by the server, and must never be accessed in any other way, by anything but the server. It’s the server that makes the EJBObject (by implementing the Advice interface), which IS remote, and which intercepts all business method calls to the bean.
Q:	Q: But if you don’t have the bean implement the interface, in other words, if AdviceBean doesn’t implement Advice, doesn’t this mean that the compiler won’t catch you if the bean blows it and doesn’t match the methods of the interface?
A:	A: Yes, that’s exactly what it means. And yes, that makes most Java developers a little queasy just thinking about it. After all, that’s one of the benefits of interfaces in Java—that the compiler guarantees that you have all of the interface methods properly implemented. But don’t panic! In our development in this book, we do have to be careful since the compiler isn’t making sure that we’ve implemented the business methods from the component interface. In the real world, however, you’ll almost certainly be using an EJB-ready development environment that will make sure you provide the methods, either by putting a “your code goes here” version of the method in your bean class, or by doing the reverse—finding the business method in the bean class and putting it into the component interface. At the very least, most servers will check (before or at the time you deploy the bean) that your component interface and bean class have matching methods. If this still bothers you, though, we do have a technique for getting around it that we’ll look at a little later. Chances are, you won’t need to use it.

Brain Power

You saw how the bean doesn’t implement the component interface, even though the bean must have the same methods. Brainstorm a way (there may be more than one) in which you could handle these requirements for the Advice Guy bean:

1. The component interface (Advice) must extend EJBObject.

2. The bean must implement the SessionBean interface. The bean must not implement the component interface (Advice).

3. We want the compiler to verify that the bean (AdviceBean) has the same methods as those in the component interface.

(Hint: “the same methods as those in the component interface”, does not mean the same thing as “the same methods as those declared in the component interface.”)

(Hint: this requires only Java knowledge, not EJB knowledge.)

Note

The naming convention for beans is NOT part of the EJB spec.

Advice, AdviceHome, AdviceBean...

You’re not required to use these names for enterprise beans! (It’s a really, really, really good idea, however.) Be sure that you’re not fooled by the name of a class or interface—it’s legal to have a component interface named AdviceHome and a component interface named AdviceBean, for example. On the exam, always go by the class or interface declaration rather than the name of the class.

Off the path

Bean-aware development tools

Today, many EJB programmers use EJB-savvy development tools. In other words, a bean-capable IDE that knows how the three pieces—home interface, component interface, and bean class—are related to one another. Many of these tools also know how to talk directly to one or more app servers, so that you can use the tool to both develop and deploy your bean, rather than switching from a development environment to the server’s own (and often less-friendly) deployment tools. One of the advantages of an EJB development tool is that you might not have to worry about matching up the business methods in the component interface with the actual bean class, or vice-versa. A good EJB-aware IDE will make sure you’ve got everything synced up.

1 bean

2 interfaces

3 XML DD

4 ejb-jar

5 deploy

1. Create an XML deployment descriptor that tells the server what your bean is and how it should be managed.

   Note

   (In this book, we won’t actually write this ourselves; we’ll let the deployment tools build it for us.)

   The deployment descriptor (DD) describes the structure of your bean including how the three files (component interface, home interface, and bean class) are related to one another. The server won’t look at your naming convention and figure out which is the home, which is the bean, etc. You have to tell the server, through the DD, which class is which, and how they’re connected. But the DD does a lot more than that. And for some beans, the DD can be several pages long!

   For this simple bean, the DD is short. Remember, you don’t need to memorize the syntax of the XML in the DD. Later in the book (in several different chapters), we’ll go over the aspects of the DD that you do need to know.

   You don’t have to write the XML by hand if you use a tool that can help you build a deployment descriptor.

   You can use the J2EE RI bean wizard to do it for you, and the XML it spits out will work in any EJB 2.0 container!

   <?xml version="1.0" encoding="UTF-8"?>
   
   <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems,
   Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://
   java.sun.com/dtd/ejb-jar_2_0.dtd'>
   
   <ejb-jar>
     <display-name>Ejb1</display-name>
     <enterprise-beans>
   
       <session>
         <display-name>AdviceBean</display-name>
         <ejb-name>AdviceBean</ejb-name>
         <home>headfirst.AdviceHome</home>
         <remote>headfirst.Advice</remote>
         <ejb-class>headfirst.AdviceBean</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Bean</transaction-type>
         <security-identity>
           <description></description>
           <use-caller-identity></use-caller-identity>
         </security-identity>
       </session>
   
    </enterprise-beans>
   </ejb-jar>

   Note

   For now, just know that every bean in an application must have an element in the DD that describes the bean’s structure and type.

   1 bean

   2 interfaces

   3 XML DD

   4 ejb-jar

   5 deploy

   

2. Put the bean, the interfaces, and the deployment descriptor into an ejb-jar file.

   Note

   (in this book, we won’t use the JAR tool to make the ejb-bar ourselves; we’ll let the deploytools do it)

   As a bean developer (officially called a Bean Provider), you’ll always put your beans in a JAR. The spec says an ejb-jar is a JAR file that holds the things the bean depends on (classes and interfaces, along with the deployment descriptor).

   You don’t have to do this by hand since we’ll use the RI! Rather than writing the XML DD and using the jar tool to package it, we’ll use the RI deploytool wizard to make it easier (and less error-prone). In other words, we’re going to combine steps 4 and 5 into one. For now, you need to know that a bean isn’t a bean until you make a JAR file with the compiled class and interfaces, and the DD.

   

   Watch it!

   The exam expects you to know what is supposed to be in the ejb-jar file and also what is not supposed to be in there. The classes and interfaces generated by the container (you’ll learn what those are a little later) must not be in the ejb-jar file! Think of the ejb-jar as the thing you create, as a bean developer. It’s your deliverable! The container/server has its own deliverables, and those deliverables don’t go into the ejbjar. Imagine that you work for Beans-R-Us, and you don’t even have an EJB-capable server. That’s the whole idea of the ejb-jar: it’s where the bean developer puts his building block components (i.e. beans), that some other developer can use to assemble an application. You might use a server tool to help create the XML DD, but the DD is still your deliverable, regardless of who (or what) creates it.

   1 bean

   2 interfaces

   3 XML DD

   4 ejb-jar

   5 deploy

   

3. Deploy the bean into the server, using the tools provided by the server vendor.

   Sooner or later, your beans have to do something. They have to be assembled into an application and deployed into a server, waiting for clients to call.

   This is a huge step. In fact, we cheated a little, because it’s actually two steps: Application Assembly and Deployment.

   • Application Assembly

   This means taking the bean from the reusable component stage to being part of an application. For simple beans, that might mean simply writing a client that can access the bean (i.e. call the bean’s business methods). In other words, a single bean might be the entire application on the server side. But this could also be the step where you integrate multiple beans (and other Java classes) into a custom application, and that usually means taking different beans (each in its own ejb-jar with its own DD) and putting them into a new, single ejb-jar, with a single DD that might describe how two or more beans are related to one another.

   During assembly, you might also add new information to the DD, for things the bean developer didn’t know about. For example, the bean developer might write code that uses a special bean-specific “property” (called an environment entry, which we’ll get into in a later chapter) for the tax amount used by this application. But the bean developer has no idea what value to give the tax amount property, so he leaves the value blank in the DD. Then the application assembler comes along, sees (by reading the DD) that the bean uses a property, figures out what the value should be, and adds it to the DD.

   For the Advice bean, putting the bean in the ejb-jar, building the DD, and deploying will happen as one big step.

   • Deployment

   This is where the rubber meets the road, the bean meets the server, the developer meets the sys admin. The two crucial parts of deployment are naming the bean (so the client will know how to find it) and getting the bean into the container’s control.

   The spec doesn’t say anything about the way in which you deploy your beans; it all depends on the EJB server/container that you’re using.

---

^[2] A marker interface (also called a tag interface) has no methods to implement and exists so that you can announce to the world that, “Yes, I can do this.”