Creating Session EJBs

Enterprise JavaBeans™ (EJBs) are Java server-side components.Ý Systems generally use them as middleware components in large distributed applications, connecting the data at the back end to the users at the front end. In the Enterprise JavaBeans model there are two main kinds of beans, entity beans and session beans. Entity beans were designed to represent persistent objects. Session beans generally represent an abstraction of a client that resides on an application server or a transient service in an environment that provides scalability. For example, in an e-commerce application, entity beans might be used to represent products to be purchased, while a session bean would be used to represent a shopping cart.

Note that rather than using entity beans to represent persistent objects, it is instead possible to use session beans and store the persistent data explicitly in a database. This requires slightly more work since it requires moving the data explicitly in and out of a database, but it gives more control over the database operations and can often result in more efficient programs. Thus it is not uncommon for enterprise applications to be built entirely out of session beans.

In AppComposer, you can build capsules that represent session EJBs. When you save a session EJB capsule as a jar, AppComposer generates all the required parts of the EJB: the bean implementation, the home interface, the remote interface, and the deployment descriptor. You can then use this bean in other capsules and programs. AppComposer creates only session beans, not entity beans. You can use any standard programming environment to create entity beans, if desired.

This example builds a session bean that follows an example first introduced in the Using Enterprise JavaBeans tutorial. The SimpleBank bean interacts with a database to perform basic banking transactions such as withdrawing or depositing funds, or obtaining an account balance. You will redesign the SimpleBank entity bean illustrated in that example as a stateful session bean that stores data in a database.

This tutorial assumes that you are familiar with Enterprise JavaBeans and AppComposer. For an introduction to EJB, see the Using Enterprise JavaBeans tutorial or Sun's website. For an introduction to AppComposer, see the Introductory Tutorial.

Note: Enterprise JavaBeans require an EJB container or application server in order to run. AppComposer includes the JBoss EJB application server, which must be enabled (in the AppComposer preferences) for this example to work.

AppComposer allows you to build three types of session beans:

• Stateful Session Beans A stateful session bean can hold information, or state, representing a client session. This information is managed by the bean on an application server. A client always contacts the same instance of the bean, because the bean retains information particular to that client. For example, in an e-commerce implementation, a stateful session bean could act as the shopping cart. The bean would track who the customer is and what items are currently in their cart. A "buy" method on a bean like this would need no arguments because the bean already has all of the information required to execute a "buy". The bean on the server manages all of the data required to interact with the commerce application and data.
• Stateless Session Beans Each time a client uses a reference to a stateless session bean, it may talk to a different instance in the application server. This means that stateless session beans do not hold onto any information specific to a particular client. Build these beans to provide a generic service. To use the e-commerce example again, if a client executed a "buy" through a stateless session bean, it would have to include with the buy method the information about what items to purchase and the customer identification information. Since these beans do not retain state information, the client has to manage this data.
• Stateful Synchronization Session Bean A stateful session bean that implements session synchronization provides more functionality for transaction boundaries. It has three extra methods available to it: afterBegin(), beforeCompletion(), and afterCompletion(boolean committed). When a transactional method call is made to a stateful synchronization session bean, these three methods act in conjunction with the method called. As an example, the buy method call from above would exist within the scope of a transaction since it changes data. So when the buy method is called, the application server actually calls all of these methods in the following order:
1. afterBegin() - the bean has just joined a transaction.
2. buy() - the method that was called by the client.
3. beforeCompletion() - the method has finished, but you do not know if the method can commit yet.
4. afterCompletion(boolean committed) - called once the transaction commits or aborts. If the commit succeeded, true gets passed as the argument, if not, committed has a value of false.

You would implement these method calls to perform whatever additional tasks you want to take place at each point in the transaction.

The Basics: A Simple Stateless Session Bean Capsule

To help you gain familiarity with how session bean capsules work, this tutorial walks you through creating a simple stateless session bean that has a single method defined. Stateless session beans can be as complex as needed for their tasks. In this case all you need to do is demonstrate the principle of how to use session bean capsules, so this one is as simple as possible.

Start AppComposer and enable JBoss if necessary. The console displays a tab for JBoss messages when it is running.

To create a stateless session bean capsule:

1. Create a new capsule.
   File -> New Capsule -> Stateless Session EJB
2. In the outline, name the capsule MyFirstEJB.
   Notice that the capsule details pane includes an area to define EJB Resources. This allows you to point to resources on the EJB application server that your EJB uses at runtime.
3. Save the capsule as MyFirstEJB.zac. Save this capsule somewhere under the main AppComposer directory, for example in a subdirectory you create under the examples directory, such as AppComposer/examples/EJBtutorial.

An empty capsule of the correct type (stateless session bean, in this example) provides default implementations of all of the required EJB methods. Later, when you save the capsule as a jar file, AppComposer compiles it and generates the appropriate interfaces and the required deployment descriptor that application servers use to run that type of bean. Of course, unless you add some functionality to it, the capsule will compile, but will not actually do anything.

To make the bean useful, it needs least one method.

To add a test method:

1. Add a method to the capsule.
   Click the icon next to Methods in the Details pane.
2. Set the activation to getTestString.
   This becomes the name of the method.
3. Set the return type of the method to String.
4. The method has no arguments.

Notice that two other attributes are available on your method. The permissions and transaction level attributes are only available for EJB capsule methods. Use them to build a deployment descriptor for an EJB. At runtime, the EJB container uses Permissions to restrict access to methods. If you are a novice EJB user, you do not need to worry about setting this yet. If you are an experienced user, you can set this field to any String value.

The transaction level attribute tells the EJB container how the method should behave with respect to transactions. The two most common settings are:

• Supports - The method does not need to execute inside of a transaction, but if called from inside of a transaction, it becomes part of the transaction. This is the default value if you do not specify one. Since the method in this example does not require a transaction, use the default.
• Required - The method must execute inside of a transaction. If a transaction is already started, it becomes part of that transaction. If a transaction is not in progress, one starts in order to call the method.

Others settings include:

• Mandatory - The method must execute inside of an existing transaction. If no transaction is in progress, it throws an exception.
• NotSupported - The method should never execute inside of a transaction. If a transaction is in progress, it suspends while the method executes and resumes when the method completes.
• Never - The method should never execute when a transaction is executing. If called from within an executing transaction, it throws an exception.
• RequiresNew - The method must execute within its own transaction. If one is already in progress, it is suspended, a new transaction starts for the method, and the original transaction resumes when the method finishes. If you are familiar with transaction processing, this is not the same as a nested transaction. The transaction success/failures are independent.

Click on the OK button to finish defining the capsule method. Now that you have declared the method on the capsule, the capsule needs to know what to do when this method is called. You need to add a behavior that returns a string to the caller of the getTestString method..

To implement getTestString:

1. Add a return value behavior to the capsule.
2. Name it onGetTestString.
3. Use the method you just defined, getTestString, to activate this behavior.
   Capsule -> getTestString
   Notice the special EJB methods available from the Receive field. Since this is an EJB type capsule, AppComposer makes these methods available automatically.
4. Add a comment that says: Returns the test String in the expression field below when onGetTestString is called.
5. Return the String "My EJB worked!".

Your simple capsule outline should now look like this:

You now have a simple EJB capsule that you can deploy and use in AppComposer or other EJB environments. If you have used session beans before, you may notice that AppComposer does not require you to define an ejbCreate method for this bean. AppComposer implements the ejbCreate method for stateless session beans automatically. You may still add functionality to the method, but you do not have to define it.

To deploy the session bean capsule, you need to save it as a jar file.

To create and deploy the jar file:

1. Save the changes in your session bean capsule.
2. Create a jar file.
   File -> Save As Jar
3. The default jar name is MyFirstEJB.jar. Use this name. Save it in the same directory where you saved your capsule (.zac) file.
4. Click Yes to import the EJB into AppComposer.
5. Click Yes to deploy the EJB to JBoss.

If you open the EJBGen menu in the Palette pane, you see an entry for MyFirstEJB in the acejb package. This means you successfully imported and deployed your EJB capsule. From this point, it works like any other EJB created in an outside development environment or acquired from a component vendor. If you look in the beans subdirectory of the main AppComposer directory, you will see a file called MyFirstEJB1.jar, which is the JavaBean stub used to talk remotely to the EJB (the home and remote interface for the EJB, in JavaBean format). The actual EJB itself is deployed on the JBoss application server, down in the JBoss subdirectory of the main AppComposer directory (for example, in C:\AppComposer\jBoss\ server\default\deploy).

To use the stateless session EJB:

For testing purposes, AppComposer includes a servlet called MyEJBServlet.zac that uses your EJB. Try out the simple method you created.

1. Open AppComposer/docs/tutorials/sessionbeans/MyEJBServlet.zac.
   Look at the outline of this servlet. You see that it contains an instance of the EJB you created. Open the ServletGet behavior to see how the interaction works. The first thing the servlet does is call create on the EJB. This is always the first method called on an EJB. It creates an instance of the EJB in the EJB container (JBoss) and sets a remote pointer in the (JavaBean) actor to point to the EJB instance. The next behavior in the ServletGet, SetHTMLText, calls the session bean's getTestString method that you created and sets the HTMLText actor in this capsule to the value returned by the EJB. The final behavior of the ServletGet group removes the EJB instance. Since the servlet no longer needs the bean, it is good practice to notify the container that it can remove this instance.
2. Since this capsule is a servlet, make sure that the Debug Server is enabled.
3. Run the servlet.
   You should see the message "My EJB worked!".

That is all there is to it. Congratulations! You just created and ran your first enterprise session bean capsule! AppComposer takes care of the mechanical parts of creating an EJB, so you can concentrate on building your functionality.

Normally the methods you define in an EJB would be more complex and would leverage the benefits of the EJB framework. In this case, you built a very simple method just to explore the creation, deployment and testing process. You would not normally implement this simple functionality as an EJB, since it requires none of the features provided by the Enterprise JavaBeans framework.

The rest of this tutorial takes you through building and using a more complex and useful session bean. You will build a stateful session bean that interacts with a database and can send dynamic output to a servlet. The data used is from the SimpleBank database, and you will create a session bean that can handle a customer withdrawing money from their account. As the first step in that process, the next section of this tutorial shows you how to set up some variables to hold the beans state, and connect the bean to the database so it can assign information from the database to those variables.