EJB Entity Bean Quick Start

This document provides a quick tutorial that teaches you how to use the SilverStream Application Server IDE to build and deploy an entity bean using container-managed persistence (CMP). This quick start includes these sections:

• Prerequisites

• Setting up your environment

• About the entity bean and its components

• Exercise 1: Creating the bean components

• Exercise 2: Deploying your EJB

• Exercise 3: Calling the bean

• Summary

    For more information on SilverStream support for EJBs, see the chapter on using EJBs in the Programmer's Guide. For more information on entity beans, see the chapter on writing entity 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 CMP entity 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:

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

   The EJB Examples database is a Sybase Adaptive Server 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 it to your server.

       For information on adding a database, see the chapter on the Main Designer in the online Tools Guide.

2. 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.

3. Create a top-level package called quickstart in the Objects directory of the database. (This package may exist already if you have done the EJB Session Bean Quick Start.)

       For information on creating packages, see the chapter on the Business Object Designer in the online Tools Guide.

4. Select the quickstart package, then create a subpackage called companydemo.

About the entity bean and its components

The entity bean you will build retrieves a row from the company table. You can retrieve the row by company ID (the primary key) or by company name. The Create EJB Wizard lets you use a database table as a template for generating code for the data you want to access. The entity bean is not tied to that table until you create the deployment plan. At that time, you can choose to map the bean to any appropriate table.

You will create the following entity bean components in the quickstart.companydemo package:

Component	Description
EBcompaniesBean	The entity bean class. It implements the javax.ejb.EntityBean interface and includes two finder methods for retrieving records.
EBcompaniesHome	The bean's home interface. The home interface for a CMP entity bean includes any create or finder methods. In this exercise you will add the findByLikeness() method to the EBcompaniesHome interface.
EBcompanies	The bean's remote interface. The remote interface exposes the bean's business methods to callers. The EBcompanies remote interface will include the getCompanyid() and getCompanyname() methods.

In addition, you will create the following JAR file:

File	Description
QuickStartEB.jar	The EJB JAR file. It will contain the bean class, its primary key class, its home and remote interfaces, and a deployment descriptor.

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

Component	Description
pgCompanyQuickStart.html	This page lets users find a company by company ID or company name (including pattern matching for the company name). Most of the code for this page is supplied, but it is not enough for it to compile. During the quick start, you update this page so that it will execute properly.

Exercise 1: Creating the bean components

To create the EBcompaniesBean class and its home and remote interfaces:

1. In the EJB Examples database, choose Objects.

2. Choose the quickstart.companydemo package you created in Setting up your environment.

3. Choose the New icon, then choose New Enterprise JavaBean to invoke the Create EJB wizard.

4. Follow the instructions for the wizard panes using these values:

   • Choose the Create a new Entity Bean based on a table radio button

   • Table: companies

   • Root Name: companies (the default)

   • Package name: quickstart.companydemo (the default)

5. Select the companyid and companyname fields and click > to put them in the right pane.

6. For the companyid field, specify these values:

   • Check the Primary key and Persistent check boxes

   • Check the Bean and Remote Interface radio button for get methods

   • Choose the None radio button for set methods

7. For the companyname field, specify these values:

   • Check the Persistent check box

   • Choose the Bean and Remote Interface radio button for get methods

   • Choose the None radio button for set methods

8. The Create EJB wizard displays the following pane:

   

9. Choose the Home interface check box and choose Finish.

The EJB Create Wizard constructs the following:

• EBcompaniesHome (the home interface)

• EBcompanies (the remote interface)

• EBcompaniesBean (the bean class)

It opens EBcompaniesHome for editing.

To complete the EBcompaniesHome interface:

1. In the Programming Editor, add the following import statement:

     import java.util.Collection;
   

2. Add the findByLikeness method to the home interface as follows:

     public Collection findByLikeness(String psCompanyName)
        throws FinderException, RemoteException;
   

3. Save the EBcompaniesHome interface and exit the Business Object Designer.

Exercise 2: Deploying your EJB

Now you will deploy the entity bean and its components by:

• Creating an EJB JAR and completing a deployment descriptor with transaction attributes

• Creating a deployment plan (which includes mapping the persistent fields to the table the bean will access)

• Deploying the EJB JAR to the SilverStream server

To create an EJB JAR file:

1. From the Main Designer, choose EJB JARs & Media.

2. Choose Jars, then choose the New icon.

3. Choose Create EJB JAR.

4. In the left pane of the JAR Contents tab, expand Objects.

5. Expand quickstart.companydemo.

6. Choose Package contents and add them to the JAR by choosing >.

7. Save the JAR, naming it QuickStartEB.

To create the deployment descriptor:

1. From within the JAR Designer, choose the Descriptor tab.

2. Choose List View at the bottom of the window (if not already chosen).

3. Choose Enterprise JavaBeans and right-click.

4. Choose Add Entity Bean.

   SilverStream creates an entry called UntitledEntityBean.

5. Select UntitledEntityBean.

6. Right-click and choose Properties.

7. Provide the bean name, bean class, home interface class, and remote interface class as shown in the following Property Inspector.

   You can choose the ellipses button (...) and select the correct entry from the dialog for the bean class, home interface class, and remote interface class.

   NOTE   The rest of the fields are handled in the following steps.

   

8. Before specifying Primary key class, change the Persistence type field to Container-managed.

9. Leaving the Property Inspector open, choose Persistent Fields (on the Descriptor pane of the JAR Designer), right-click and choose Add.

   • Add both m_companyname and m_companyid and click OK.

10. Go back to the Property Inspector and in the Primary key class field, type java.lang.Integer.

11. In the Primary key field field, choose the ellipsis button, then choose m_companyid.

To specify transaction attributes:

1. Choose Transactions (located under Application Assembly in the JAR Designer), right-click and choose Add.

   SilverStream creates an UntitledTransaction entry.

2. Select UntitledTransaction.

3. Provide these entries in the Property Inspector:

   • Name: TransactionRequired

   • Attribute: Required

   • Description: TransactionRequired (optional)

4. Choose Edit Methods. If Edit Methods is not visible, choose the + Methods icon first.

   SilverStream displays the Edit Methods dialog.

5. Choose the * under EBCompanyBean, choose > to add it, then choose OK.

   This means that all of the EBCompanyBean methods execute with the transaction attribute Required.

6. Close the Property Inspector and save the EJB JAR.

   SilverStream validates the EJB JAR and displays any errors or warnings in a Validation Status dialog. This dialog provides helpful information about the errors and warnings which can help you locate and fix them. You should not encounter any validation errors in this exercise.

7. Exit the JAR Designer.

Creating the EJB deployment plan

An EJB deployment plan provides additional information that the SilverStream server needs to properly execute the EJBs within the EJB JAR.

To create the EJB deployment plan:

1. Choose EJB JARs & Media and expand the Jars section.

2. From the list of JARs, choose QuickStartEB.jar.

3. Right-click and choose Create EJB JAR Deployment Plan.

   SilverStream launches the Deployment Plan Designer.

4. Choose Enterprise JavaBeans.

5. Right-click and choose Properties to open the Property Inspector.

6. Make sure Enabled is set to True.

7. Leaving the Property Inspector open, choose EBCompanyBean.

8. Specify these values in the Bean tab of the Property Inspector:

   • JNDI Deployment Name: EBCompaniesBean

   • Table: companies

9. In the Property Inspector, click the Edit Methods link (located below Methods that modify no fields).

10. In the Edit Methods dialog, add the getCompanyid() and getCompanyname() methods to the right pane and click OK.

    The ability to specify the methods that do not modify fields is a SilverStream-specific deployment feature.

        For more information on methods that do not modify fields, see the chapter on J2EE archive deployment in the Facilities Guide of the server's Core Help.

11. With the Property Inspector open, click each of the persistent fields in the Deployment Plan Designer and map them to the database columns as follows:

    • Map m_companyid to the database column companyid

    • Map m_companyname to the database column companyname

12. Choose the findByLikeness Finder method in the Deployment Plan Designer and specify these values in the Property Inspector:

    • Type: Expression

    • Where Clause: companies.companyname like javaLangString0

13. Close the Property Inspector and save the deployment plan.

    SilverStream prompts for a deployment plan name.

14. Accept the default name (QuickStartEBDeplPlan) and choose OK.

    NOTE   It is necessary to save the plan once before choosing Save and Deploy in the next step.

15. Choose File>Save and Deploy to create the remote JAR and deploy the main JAR to the server.

    SilverStream prompts you for names for the deployed object and the remote access JAR.

16. Accept the defaults.

    SilverStream launches the rmi2iiop compiler, which creates the classes needed for the beans in the EJB JAR. Then SilverStream displays this message:

      The JAR was successfully saved and activated.
    

    You should not encounter any warnings or errors.

17. 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
QuickStartEBDeployed	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.
QuickStartEBDeplPlan	Represents the deployment plan for the EJB deployment object. You can create multiple deployment plans for an EJB JAR.
QuickStartEBRemote.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 can call the EBCompanyBean you just deployed, you need to modify the SilverStream page (pgCompanyQuickStart.html) that resides in the EJB Examples database. This page will not yet compile because you need to add code that:

• Imports the quickstart.companydemo package

• Does a JNDI lookup to find the bean's home interface

• Calls the javax.rmi.PortableRemoteObject.narrow() method to obtain the correct object type

To modify the pgCompanyQuickStart.html page:

1. Open the Pages directory in the EJB Examples database.

2. Open the pgCompanyQuickStart.html page.

3. Open the Programming Editor.

4. In the General/Imports section, search for this comment (you need to be in whole file view to do a search. You can change the view with the buttons on the right above the editing area.):

     //*************************************************************
     //         For Quick Start imports 
     //         Insert code below
     //*************************************************************
   

5. Add this import statement below the comment:

     import quickstart.companydemo.*;
   

6. Add to the page the EJB remote JAR that you created earlier by choosing File>Jar Files and adding the following JAR file:

     ExamplesXX_EJB/QuickStartEBRemote.jar
   

7. In the page's General/getTheEntityBeanHome method, locate the Java comment that says:

     //**************************************************************
     //          For Quick Start JNDI lookup
     //          Insert code below
     //****************************************************************	 	 	 	 
   

   Add the following code which does the JNDI lookup() for the bean:

     Object objEntityBeanLookup =
        initialContext.lookup("RMI/EBCompaniesBean");
   

   The RMI/ specifies the root of the JNDI context where SilverStream stores EJB home references when the EJBs are deployed. You must use it with all SilverStream JNDI EJB lookups. EBCompaniesBean is the JNDI name you specified in the Deployment Plan Designer.

8. Still in the page's General/getTheEntityBeanHome event, locate the comment that says:

     //*************************************************************
     //         For Quick Start Home Object
     //          javax.rmi.PortableRemoteObject.narrow()
     //          Insert code below (before the return statement)
     //*************************************************************
   

9. Add this line of code to narrow (not cast) the returned EJBHome object to your user defined type:

     m_ebCompanyHome = (EBcompaniesHome)
        javax.rmi.PortableRemoteObject.narrow(objEntityBeanLookup,
        quickstart.companydemo.EBcompaniesHome.class);
   

10. In the handle_btnFindLikeName_pageActionPerformed method, locate the comment that says:

      //*************************************************************
      //          For Quick Start Remote Object
      //          javax.rmi.PortableRemoteObject.narrow() 
      //          Insert code below (before the first sHTML statement)
      //*************************************************************
    

11. Add this line of code to narrow (not cast) the returned EJBObject to your user defined type.

      EBcompanies ebcompanies = (EBcompanies)
         javax.rmi.PortableRemoteObject.narrow(objEntityBeanCompany,
         quickstart.companydemo.EBcompanies.class);
    

    The EJB1.1 Specification requires that you use the javax.rmi.PortableRemoteObject.narrow() method because it works with both JRMP and RMI-IIOP protocols. This allows your code to work with EJBs on any type of EJB-compliant server.

12. Save the page and exit the Programming Editor.

To call the bean:

• In the Page Designer, run the pgCompanyQuickStart.html page in test mode.

To get a company by Company ID:

• Enter 1 in the Company ID field, then click the Find Using Company ID button.

  The page should return Computers R Us in the Company Name field.

  This illustrates the findByPrimaryKey() method.

To get a company by name:

1. Clear the fields.

2. Enter A% in the Company Name field.

3. Click the Find Using Company Name button.

   The page should return the following companies:

     4 Always Publishing Corporation
     5 ACME Fireworks
     7 Alot of Java
   

   This illustrates the findByLikeness() method.

Summary

In this Quick Start, you created the following objects:

Object	Purpose and actions
quickstart.companydemo package	Package for the entity bean classes. In the Objects directory of the database, you added a top-level package and subpackage.
EBcompaniesBean	Entity bean class. To create it in the Objects directory, you selected the package and used the Create EJB Wizard to create the entity bean using an existing table and its columns as a model. The generated code did not need editing. NOTE   Using an existing table just gets the process started. In the deployment step, you select the table the bean will use.
EBcompanies	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.
EBcompaniesHome	Home interface used to locate the entity bean on the server. The Create EJB Wizard created the home interface in the selected package. Then you added the code for the finder method.
QuickStartEB.jar	EJB JAR file that holds all the bean's classes, including the bean class, home and remote interfaces, and deployment descriptor. 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 bean, identified the classes for each interface, specified transaction attributes, and identified the type of persistence, the primary key, and the persistent fields.
QuickStartEBDeplPlan	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 entity bean, mapped get methods for the persistent fields to database columns, and specified a where clause for the finder method. You can open an existing plan in the Deployment Plan Designer by double-clicking the deployment plan object in the JARs directory.
QuickStartEBDeployed	Deployed JAR. SilverStream created this deployed JAR when you chose Save and Deploy in the Deployment Plan Designer.
QuickStartEBRemote.jar	Deployed remote JAR. SilverStream created the remote JAR when you chose 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.
pgCompanyQuickStart.html	The HTML page that displays data from the entity bean. You edited its code to get your entity bean using its JNDI name (initialContext.lookup()) and to narrow the returned object to your bean's home interface (javax.rmi.PortalRemoteObject.narrow()).

Copyright © 2001, SilverStream Software, Inc. All rights reserved.