EJB Session Bean Quick Start

This document provides a short tutorial that teaches you how to use the SilverStream Application Server IDE to build and deploy a stateful session bean. This quick start includes these sections:

For more information on SilverStream support for EJBs, see the chapter on using EJBs in the Programmer's Guide. For more information on session beans, see the chapter on writing session beans in the Programmer's Guide.

Prerequisites

This quick start assumes you have:

Sybase Adaptive Server Anywhere installed on your system
Some working knowledge of the SilverStream Application Server design environment

You do not need any EJB knowledge. But keep in mind that the intent of this quick start is to teach you how to use SilverStream to build session beans; it is not intended to teach you EJB theory or best practices.

Setting up your environment

Before doing the quick start exercises, you must set up your environment.

To set up your environment:

Add the EJB Examples database to your SilverStream server, if it isn't already.

The EJB Examples database is a Sybase Adaptive Server Anywhere database that is installed and configured as part of the SilverStream Full or Typical install. You can use the username dba and password sql to add the database to your server.

For information on adding a database, see the chapter on database configuration in the online Tools Guide.
Open the Objects directory of the EJB Examples database, but do not select anything.

If you have an item selected, you will not be able to create a top-level package. To unselect an item, press Ctrl and click the selected item.
Create a top-level package called quickstart in the Objects directory of the EJB Examples database. (It will already exist if you've already done the Entity Bean Quick Start.)

For more information on creating packages, see the chapter on the Business Object Designer in the online Tools Guide.
Select the quickstart package, then create a subpackage called calculatordemo.

About the session bean and its components

The session bean that you will build calculates a running total based on user-entered values.

You will create the following EJB components in the quickstart.calculatordemo package:

Component

Description

SBCalculatorBean

The session bean class. It contains the business logic that does the calculation and returns the value.

SBCalculator

The bean's remote interface.

SBCalculatorHome

The bean's home interface.

Component	Description
SBCalculatorBean	The session bean class. It contains the business logic that does the calculation and returns the value.
SBCalculator	The bean's remote interface.
SBCalculatorHome	The bean's home interface.

In addition, you will create the following JAR file:

File

Description

QuickStartSB.jar

The EJB JAR file. It contains the bean class, its home and remote interfaces, and a deployment descriptor.

File	Description
QuickStartSB.jar	The EJB JAR file. It contains the bean class, its home and remote interfaces, and a deployment descriptor.

You will call the session bean from the following SilverStream HTML page:

Component

Description

pgCalculate2.html

The user interface. It lets users enter two integer values. When the user presses a button, the value is calculated and the running total is displayed.

You will save the SilverStream-provided page pgCalculate.html as pgCalculate2.html. This allows you to modify the code to run your own SBCalculatorBean.

Component	Description
pgCalculate2.html	The user interface. It lets users enter two integer values. When the user presses a button, the value is calculated and the running total is displayed. You will save the SilverStream-provided page pgCalculate.html as pgCalculate2.html. This allows you to modify the code to run your own SBCalculatorBean.

Exercise 1: Creating the bean components

In this exercise you will use the EJB Create Wizard to create the:

SBCalculatorBean session bean class
SBCalculator remote interface
SBCalculatorHome home interface

To create the SBCalculatorBean bean class and its home and remote interfaces:

In the EJB Examples database, click Objects.
Choose the quickstart.calculatordemo package you created in Setting up your environment.
Choose the New icon, then choose New Enterprise JavaBean to invoke the Create EJB Wizard.
Follow the instructions for the wizard panes using these values:
- Choose the Create a new Session Bean radio button
- Root name: Calculator
- Package: quickstart.calculatordemo
- Number of methods: 1
Specify the following for the method:
- Method Name: doCalculation
- Visibility: public
- Return Type: int
- # of parameters: 2
- Check the Throws exceptions check box
Enter the following values for Parameter 1 and Parameter 2:

Field

Value for Parameter 1

Value for Parameter 2

Parameter name

piFirstValue

piSecondValue

Type

int

int
Add the following exception: java.rmi.RemoteException
The Create EJB wizard displays the following pane:
Accept the defaults and choose Finish.

SilverStream launches the SBCalculatorBean EJB class in the Programming Editor. It also constructs the SBCalculatorHome (extends javax.ejb.EJBHome) and SBCalculator (extends javax.ejb.EJBObject) interfaces in the quickstart.calculatordemo package. Only the SBCalculatorBean class needs further editing.

Field	Value for Parameter 1	Value for Parameter 2
Parameter name	piFirstValue	piSecondValue
Type	int	int

To finish the code in the SBCalculatorBean class:

In the Programming Editor, access the General/Declarations section and add the following:
```
  public int m_iTotal = 0;
```

Add the following code to the doCalculation() method (between the {})

  int iTotal = piFirstValue + piSecondValue;
  m_iTotal += iTotal;
  return m_iTotal;

Save the bean and exit the Business Object Designer.

Exercise 2: Deploying the bean

Now you will deploy the EJB components by:

Creating an EJB JAR file and providing a deployment descriptor
Creating a deployment plan
Deploying the EJB JAR to the SilverStream server

To create an EJB JAR file:

From the Main Designer, choose EJB JARs & Media.
Choose Jars, then choose the New icon.
Choose Create EJB JAR.
In the left side of the JAR Contents tab, expand Objects.
Expand quickstart, then expand calculatordemo.
Choose Package contents and add it to the JAR by choosing >.
Save the JAR naming it QuickStartSB.

To create the Deployment descriptor:

From within the JAR Designer, choose the Descriptor tab.
Choose Enterprise JavaBeans and right-click.
Choose Add Session Bean.

The JAR Designer creates an entry called UntitledSessionBean.
Choose UntitledSessionBean, right-click, and choose Properties.
Provide values for the bean's properties as shown in the following Property Inspector.
NOTE You can choose the ellipses buttons (...) to launch a dialog that lists the possible valid entries. When you select an entry from the dialog, the JAR Designer populates the text box with the selected value.
Close the Property Inspector and save the EJB JAR.

For this exercise, you can expect the Validation Status dialog to appear with the warning message shown here. This warning does not affect your ability to run the session bean.
Choose Done.

SilverStream launches a final dialog asking if you want to save the JAR even though it has errors.
Choose Yes.
Exit the JAR Designer.

To deploy the EJB JAR:

From the Main Designer, choose EJB JARs & Media
Expand Jars, then choose the QuickStartSB JAR from the list.
Right-click and choose Create EJB JAR Deployment Plan.

SilverStream launches the Deployment Plan Designer.
Choose Enterprise JavaBeans.
Right-click and choose Properties.
Make sure that Enabled is set to True.
Leaving the Property Inspector open, choose the SBCalculatorBean.
Enter SBCalculator as the JNDI deployment name.
Close the Property Inspector and choose File>Save in the Deployment Plan Designer.
Accept the default name for the deployment plan (QuickStartSBDeplPlan) and choose OK. This creates and saves the deployment plan.
Choose File>Save and Deploy. (This command saves an existing deployment plan but does not save a newly created one. You must use File>Save first, as in step 9.)

The Deployment Plan Designer displays the following dialog.
Accept the default names and choose OK.

SilverStream launches the rmi-iiop compiler to generate the deployment classes for this EJB application (the collection of classes is called the deployed object) and places them on the server. It also creates a remote access JAR file that contains all of the classes an EJB client needs to access the EJB classes on the server.

SilverStream again displays this Validation Status dialog.
Choose Done.

SilverStream displays the following message in the designer's message area: The JAR was successfully saved and activated.

Close the Deployment Plan Designer.

Now you can see the objects created during the deployment process. They are located in the JARs directory and include:

Object

Description

QuickStartSBDeployed

Represents the EJB deployment object. The deployment object is a collection of classes that the SilverStream server requires to execute EJBs.

You cannot manipulate the EJB deployment object except to activate or deactivate it using the SMC.

QuickStartSBDeplPlan

Represents the deployment plan for the EJB deployment object.

You can create multiple deployment plans for an EJB JAR.

QuickStartSBRemote.jar

Represents the collection of classes required by EJB clients.

You must make this JAR available to any clients wishing to call any of the EJBs that are part of this deployment object.

Object	Description
QuickStartSBDeployed	Represents the EJB deployment object. The deployment object is a collection of classes that the SilverStream server requires to execute EJBs. You cannot manipulate the EJB deployment object except to activate or deactivate it using the SMC.
QuickStartSBDeplPlan	Represents the deployment plan for the EJB deployment object. You can create multiple deployment plans for an EJB JAR.
QuickStartSBRemote.jar	Represents the collection of classes required by EJB clients. You must make this JAR available to any clients wishing to call any of the EJBs that are part of this deployment object.

Exercise 3: Calling the bean

Before you test your bean, you will see how it should execute by running the SilverStream-provided page (pgCalculate.html).

Then you will create pgCalculate2.html and modify the code that:

Imports the quickstart.calculatordemo package
Change the name of the remote JAR that the page references.
Does a JNDI lookup to find the bean's home interface
Calls the javax.rmi.PortableRemoteObject.narrow() method to obtain the correct object type

Finally, you will call your bean from pgCalculate2.html.

To run the SilverStream-provided page:

Choose the Pages directory in the EJB Examples database.
Run pgCalculate.html.

The page prompts you for two values. The SBCalculatorBean session bean contains a member variable that keeps a running total and is able to maintain this state across calls from the page. When you click the Add to Running Total button, the page gets the new running total from the bean.

The first time you calculate a total, the page displays a message about your first visit and expired sessions. It's not an error, just an informational message. When your session expires (determined by the server's timeout settings), the calculation starts over at 0, as it does for the first visit to the page.

To modify the page to call your bean:

Open the pgCalculate.html page, then choose File>Save As and accept the default name (pgCalculate2).
NOTE If you encounter any compiler errors now, ignore them.
Open the Programming Editor and choose the switch to single method view button (one of the code view buttons to the right of the two dropdown fields).
In the General/Imports section, comment out the com.examples.calculatordemo import statement shown here:
```
  // import com.examples.calculatordemo.*;
```
and add the import quickstart statement, as shown here:
```
  import quickstart.calculatordemo.*;
```

Choose File>Jar Files and change the JAR file used by the page from:

  ExamplesXX_EJB/CalculatorDemoRemote.jar

to:

  ExamplesXX_EJB/QuickStartSBRemote.jar

In the General/getTheCalculator method, comment out this JNDI lookup:

  // Object obj = 
  //    initialContext.lookup("RMI/sssw/Examples3n_EJB/
  //    CalculatorDemo/SBCalculator");

and replace it with the following:

  Object obj = initialContext.lookup("RMI/SBCalculator");

Still in the General/getTheCalculator method, comment out the reference to the com.examples.calculatordemo.SBCalculatorHome.class shown here:

  // javax.rmi.PortableRemoteObject.narrow(obj,
  // com.examples.calculatordemo.SBCalculatorHome.class);

and replace it with this line of code:

  javax.rmi.PortableRemoteObject.narrow(obj,
      quickstart.calculatordemo.SBCalculatorHome.class);

Save the page and close the Programming Editor.

To call the bean:

Run the pgCalculate2.html page in test mode.
Enter a number in the First Value and Second Value fields, then click Add to Running Total.

The page should display the sum of the two values, just as it did in the SilverStream-provided page that you ran earlier.
Repeat step 2.

The bean should return the running total.

Summary

In this Quick Start, you created the following objects:

Object

Purpose and actions

quickstart.calculatordemo package

Package for the session bean classes.

In the Objects directory of the database, you added a top-level package and subpackage.

SBCalculatorBean

Session bean class containing the business logic that does the calculation and returns the value.

The Create EJB Wizard created the class in the selected package. Then you edited the code for the calculation.

SBCalculator

Remote interface used by clients to invoke bean methods.

The Create EJB Wizard created the remote interface in the selected package. The generated code did not need editing.

SBCalculatorHome

Home interface used to locate the session bean on the server.

The Create EJB Wizard created the home interface in the selected package. The generated code did not need editing.

QuickStartSB.jar

EJB JAR file that holds all the bean's classes.

In the JARs directory, you used the New>Create EJB JAR option to open the JAR Designer. On the JAR Contents tab, you added the package contents. On the Descriptor tab, you added the session bean and identified the classes for each interface.

QuickStartSBDeplPlan

SilverStream deployment plan that specifies how the bean is deployed on the server. A JAR can have more than one plan.

You created the plan by right-clicking on the EJB JAR and choosing Create EJB JAR Deployment Plan. In the plan, you associated a JNDI name with the session bean.

You can open an existing plan in the Deployment Plan Designer by double-clicking the deployment plan object in the JARs directory.

QuickStartSBDeployed

Deployed JAR.

SilverStream created this deployed JAR when you chose File>Save and Deploy in the Deployment Plan Designer.

QuickStartSBRemote.jar

Deployed remote JAR.

SilverStream created the remote JAR when you chose File>Save and Deploy in the Deployment Plan Designer. The remote JAR must be available to clients that call the bean's methods. SilverStream pages run on the server and have access to it in the JARs directory.

pgCalculate2.html

The HTML page that calls the bean's methods. You edited its code to get your session bean using its JNDI name (initialContext.lookup()) and to narrow the returned object to your bean's home interface (javax.rmi.PortalRemoteObject.narrow()).

Object	Purpose and actions
quickstart.calculatordemo package	Package for the session bean classes. In the Objects directory of the database, you added a top-level package and subpackage.
SBCalculatorBean	Session bean class containing the business logic that does the calculation and returns the value. The Create EJB Wizard created the class in the selected package. Then you edited the code for the calculation.
SBCalculator	Remote interface used by clients to invoke bean methods. The Create EJB Wizard created the remote interface in the selected package. The generated code did not need editing.
SBCalculatorHome	Home interface used to locate the session bean on the server. The Create EJB Wizard created the home interface in the selected package. The generated code did not need editing.
QuickStartSB.jar	EJB JAR file that holds all the bean's classes. In the JARs directory, you used the New>Create EJB JAR option to open the JAR Designer. On the JAR Contents tab, you added the package contents. On the Descriptor tab, you added the session bean and identified the classes for each interface.
QuickStartSBDeplPlan	SilverStream deployment plan that specifies how the bean is deployed on the server. A JAR can have more than one plan. You created the plan by right-clicking on the EJB JAR and choosing Create EJB JAR Deployment Plan. In the plan, you associated a JNDI name with the session bean. You can open an existing plan in the Deployment Plan Designer by double-clicking the deployment plan object in the JARs directory.
QuickStartSBDeployed	Deployed JAR. SilverStream created this deployed JAR when you chose File>Save and Deploy in the Deployment Plan Designer.
QuickStartSBRemote.jar	Deployed remote JAR. SilverStream created the remote JAR when you chose File>Save and Deploy in the Deployment Plan Designer. The remote JAR must be available to clients that call the bean's methods. SilverStream pages run on the server and have access to it in the JARs directory.
pgCalculate2.html	The HTML page that calls the bean's methods. You edited its code to get your session bean using its JNDI name (initialContext.lookup()) and to narrow the returned object to your bean's home interface (javax.rmi.PortalRemoteObject.narrow()).