Setting the State of a Bean from a Database

In the previous section, the capsule you created was a stateless session bean. Now you can use the same ideas to create a more complex capsule. This one is a stateful session bean. This tutorial walks you through building a session bean called SimpleBankEJB. It needs to track some properties for a user, so a stateful session bean is an appropriate design choice. This means that the bean needs a few data fields that hold state information between method calls. This section of the tutorial shows you how to add these variables and pull information from a database to fill them.

To create the capsule:

1. Enable JBoss if necessary.
2. Create a new stateful session bean capsule.
   File -> New Capsule... -> Stateful Session EJB
3. Name the capsule in the outline SimpleBankEJB.
4. Save your capsule as SimpleBankEJB.zac.

You now have an empty capsule that is a stateful session EJB. It currently has no functionality other than the default, but you could deploy it without error to an EJB application server.

Since this is a stateful session bean, it can retain information (state) that is particular for a client. This bean needs to track the account number, the customer's name and the account balance for the current client. To hold this information, add String and double variables from the Insert menu or Palette.

To insert variables:

1. Add a String data item and name it accountNumber.
2. Select the capsule in the outline and add a second String data item called name.
3. Select the capsule again and add a double data item named balance.

Your capsule outline should now look like this:

Using SQL Actors in the Capsule

Whenever a client wants to use an instance of a session bean, it must first call create on the home interface of the bean. This create method call tells the application server to get an instance of the session bean ready for use. When the client calls this method, it gets a reference to an instance of that session bean from the EJB server. For a stateful session bean capsule, you need to define the create method. If you did not define one, the compiler would create a default method with no arguments. Since the SimpleBank bean needs an account number argument to access the correct bank account, you have to define a create method that can pass this argument. You cannot use the default method that the compiler generates.

To define the ejbCreate method:

1. Select the SimpleBankEJB in the outline.
2. In the Details pane, create a new method by clicking on the icon.
3. Activate the method on ejbCreate.
4. Add an argument by clicking on the +Argument button. Name the argument accountNum and set its type to String.
5. Click OK.

You must name the method ejbCreate in order for it to correspond to the create method in the EJB's home interface. If you do not define a method called ejbCreate, the compiler generates a default one that takes no arguments. In general, ejbCreate methods have a transactional attribute of Supports because their behavior inside of a transaction has no specific requirements according to the EJB specification. In this case, use the default Supports transaction level.

If you are familiar with EJBs, you may notice that as currently defined, this ejbCreate method returns void instead of a reference to the EJB instance. When AppComposer generates the bean code, the home interface automatically includes the proper return type.

Now that the capsule has this required create method defined, you need to add some behaviors that generate the EJB instance correctly when the client calls the ejbCreate method. The behaviors need to use the account number passed into the method to look up the customer in a database, and should cache the current account balance and customer's name. This information is the state of the stateful session bean.

Since the account information resides in a database, you need to add an SQLSelect actor to the capsule to retrieve it. Not all ejbCreate methods need to retrieve information from a database, this is simply how we are doing it in this example.

To set up the query:

1. Add an SQL actor of type SQLSelect to the capsule and name it getUserInfo.
   Actors of type SQLSelect represent a query to a database.
2. Edit getUserInfo by clicking on the Edit button in the properties pane. The editor for the SQLSelect actor opens.
3. From the Tables tab, choose the ejbdata connection and add the table ACCOUNTS. The table and connection are from several examples provided with AppComposer to work with various example capsules.
   
4. From the Columns tab, choose the ACCOUNT_NUMBER, NAME, and BALANCE columns for the query to return.
   
5. In the Conditions tab, add a condition to the query that compares the column ACCOUNT_NUMBER to a parameter called accountNum. Be sure to select "Parameter" as the type for the second operand. You should not type the colon (":"). AppComposer adds this automatically. The value of accountNum is set when the query executes.
   
6. Click OK.

You have configured a query to retrieve the user's name and balance from the database, using the accountNum parameter. Now you need to add behaviors to the session bean capsule that can execute this query.

To execute the query:

1. Insert an action group behavior as a child of the capsule and name it ejbCreate . Set its activation to receive the Capsule.ejbCreate method.
   
2. Insert an action to the group and name it setAccountNumber. This behavior automatically activates from its parent, which is the ejbCreate group. Define this behavior so that it uses the accountNum argument passed by the ejbCreate event to set the accountNumber variable.
   
3. The SQL query actor getUserInfo expects a parameter called accountNum. Since the account number is passed by the event into this action group, we will set the query parameter with a behavior. Add another behavior to the action group and name it setAccountNumParm. Set the action to call the setParameterString method on the getUserInfo actor. The setParameterString method takes two arguments: the parameter to be set and the value. In this case, the parameter name and the value (passed through the activating event) have the same name, but the first one is a constant string. Note that AppComposer knows that the getUserInfo query expects an accountNum parameter, so it fills in the first argument for you. Since SQL doesn't care if a parameter name is upper or lower case, it doesn't matter that the parameter name is all caps. The second argument to setParameterString is (again) the accountNum argument passed by the ejbCreate event.
   
4. Add a final action behavior to the group to execute the SQL query getUserInfo. Name this behavior execute query. The execute message is found under the SQLAbstractStatement superclass submenu.
   

Your capsule outline should now look like this:

Setting the State of the Bean

SQL queries return data in the form of rows, and in this case is going to be a single row since the accountNum parameter is a unique primary key. Your capsule needs to get the customer's name and account balance from the result row. When a row is retrieved successfully from a database, it generates a rowRetrieved event. In this case, since only one row should match the parameter, only one event gets generated. Use this event to set the variables representing the state of the stateful session bean to the values that are retrieved from the database.

To store the retrieved values:

1. Insert an action group under the getUserInfo actor and name it rowRetrieved . Set it so it activates on the Sql.rowRetrieved event generated by its actor.
   
2. Add an action under rowRetrieved and name it getBalance. Have it retrieve the BALANCE column from the row and set the balance variable in the capsule to that value. Choose the getColumnDouble method with the String argument "BALANCE" filled in if you use the pop-up menu.
   
3. Insert another action under rowRetrieved and name it getName. It should retrieve the NAME column from the row and set the name data item in the capsule to that value.
   

This finishes the ejbCreate implementation. At the end of this method call, the session bean has some initial state set. At this point, your capsule should look like this:

So far, you have created your session bean capsule, and added actors, behaviors and data items that allow the bean to get information from a database and store it as the session's state. It can get and hold onto this information, but does not yet do anything with it. The next section of the tutorial shows you how to implement a simple withdrawal transaction that uses the state held in the session bean to update the information in the account record.