EJB Entity Bean Quick Start

This chapter 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

    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 Examples3_EJB database to your SilverStream server.

   Examples3_EJB 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 Examples3_EJB database, but do not select anything.

   If you select an object, you will not be able to create a top-level package as required unless you close and restart the Main Designer.

3. Create a top-level package called quickstart in the Objects directory of the Examples3_EJB 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.

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

Component	Description
EBCompanyBean	The entity bean class. It implements the javax.ejb.EntityBean interface and includes two finder methods for retrieving records.
EBCompanyPrimaryKey	The entity bean's primary key class. Entity beans require a primary key. The primary key can be a separate class or as a field in the entity bean class itself. In this example you will define a separate class, which according to the EJB 1.1 Specification must implement: The java.io.Serializable interface An equals() method A hashCode() method
EBCompanyHome	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 these methods to the EBCompanyHome interface: create() findByPrimaryKey() findByLikeness()
EBCompany	The bean's remote interface. The remote interface exposes the bean's business methods to callers. The EBCompany remote interface will include the getCompanyID() and getCompanyName() methods.
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 SilverStream HTML page described here:

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 tutorial, you update this page so that it will execute properly.

Exercise 1: Creating the bean components   

To avoid compile errors, do the exercises in order.

To create the EBCompanyPrimaryKey class:

1. In the Examples3_EJB database, choose Objects.

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

3. Choose the New icon, then choose New Object to invoke the Business Object Wizard.

4. Follow the wizard instructions using these values:
   • Do not select any triggers

   • Name the object EBCompanyPrimaryKey

   • In the Interfaces pane, add the java.io.Serializable interface. (You do not have to check the Create stubs for interface methods check box.)

     When you complete the wizard, SilverStream constructs a shell for the EBCompanyPrimaryKey class that looks like this:

       public class EBCompanyPrimaryKey implements java.io.Serializable 
       { 
       } 
     

     NOTE   You may need to click the switch to whole file view button to see this.

5. Add the following line to the class definition (between the {}):

     public String m_companyid; 
   

6. Save the class.

To create the EBCompanyPrimaryKey equals() method:

1. Choose Tools>Add New Method to invoke the Add New Method Wizard.

2. Follow the wizard instructions using these values:
   • Method Name: equals

   • Visibility: public

   • Return Type: boolean

   • # of Parameters: 1

   • Do not check the Throws exceptions check box.

3. Choose Next.

4. Enter these values for Parameter 1:
   • Parameter Name: objPK

   • Parameter Type: Object

5. Choose Finish.

   SilverStream constructs an equals() method that looks like this:

     public boolean equals(Object objPK) 
     { 
     } 
   

6. Add the following code to implement the equals() method (between the {}):

     if (objPK == null) 
         return false; 
     if (!(objPK instanceof EBCompanyPrimaryKey)) 
         return false; 
     if (((EBCompanyPrimaryKey) objPK).m_companyid.equals(m_companyid)) 
         return true; 
     return false; 
   

7. Save the class.

To create the EBCompanyPrimaryKey hashCode() method:

1. Choose Tools>Add New Method to invoke the Add New Method Wizard.

2. Follow the wizard instructions using these values:
   • Method Name: hashCode

   • Visibility: public

   • Return Type: int

   • # of Parameters: 0

   • Do not check the Throws exceptions check box.

3. Choose Finish.

   SilverStream constructs a hashCode() method shell that looks like this:

     public int hashCode() 
     { 
     } 
   

4. Add the following code to implement the hashCode() method (between the {}):

     return m_companyid.hashCode(); 
   

5. Save the primary key class and exit the Business Object Designer.

To create the EBCompanyBean class:

1. With the quickstart.companydemo package selected, choose the New icon.

2. Choose New Object to invoke the Business Object Wizard.

3. Follow the wizard instructions using these values:
   • Do not select any triggers

   • Name the object EBCompanyBean

   • Add the javax.ejb.EntityBean interface and check the Create stubs for interface methods checkbox

     When you complete the wizard, SilverStream creates a shell for the EBCompanyBean class. This class includes a stub for each method in the javax.ejb.EntityBean interface.

4. In the General/Imports section, add the following:

     import javax.ejb.*;  
     import java.rmi.RemoteException; 
     import java.util.Collection; 
   

5. In the General/Declarations section, add the following:

     public String m_companyid; 
     public String m_companyname; 
   

6. Save the entity bean class.

Implementing entity bean business methods   

You need to add these methods to the EBCompanyBean bean class:

• Two lifecycle or callback methods:
  • ejbCreate()

  • ejbPostCreate()

• Two business methods:
  • getCompanyID()

  • getCompanyName()

To create the ejbCreate() method:

1. Choose Tools>Add New Method to invoke the Add New Method wizard.

2. Follow the wizard instructions using these following values:
   • Method Name: ejbCreate

   • Visibility: public

   • Return Type: EBCompanyPrimaryKey

   • # of parameters: 2

   • Check the Throws exceptions checkbox.

3. Enter the following values for Parameter 1 and Parameter 2:

   Field	Value for Parameter 1	Value for Parameter 2
   Parameter Name	psCompanyID	psCompanyName
   Type	String	String

4. Choose Add in the Exceptions pane and enter the following:
   • javax.ejb.CreateException

   • java.rmi.RemoteException

5. Choose Finish.

   SilverStream constructs an ejbCreate() method that looks like this:

     public EBCompanyPrimaryKey ejbCreate(String psCompanyID,  
        String psCompanyName) throws javax.ejb.CreateException, 
        java.rmi.RemoteException 
     { 
     } 
   

6. Add the following code to the method:

     m_companyid = psCompanyID; 
     m_companyname = psCompanyName; 
     return null; 
   

7. Save the bean class.

To create the ejbPostCreate() method:

1. Choose Tools>Add New Method to invoke the Add New Method Wizard.

2. Follow the wizard instructions using these values:
   • Method Name: ejbPostCreate

   • Visibility: public

   • Return Type: void

   • # of parameters: 2

   • Check the Throws Exceptions checkbox

3. Enter the following values for Parameter 1 and Parameter 2:

   Field	Value for Parameter 1	Value for Parameter 2
   Parameter Name	psCompanyID	psCompanyName
   Type	String	String

4. Add these exceptions:
   • javax.ejb.Create.Exception

   • java.rmi.RemoteException

5. Choose Finish.

   SilverStream constructs an ejbPostCreate() method that looks like this:

     public void ejbPostCreate(String psCompanyID,  
        String psCompanyName) throws CreateException,  
        RemoteException 
     { 
     } 
   

   NOTE   You will not add a method body.

To create the getCompanyID() method:

1. Choose Tools>Add New Method to invoke the Add New Method Wizard.

2. Follow the wizard instructions using these values:
   • Method Name: getCompanyID

   • Visibility: public

   • Return Type: String

   • # of parameters: 0

   • Check the Throws exceptions check box and add the java.rmi.RemoteException.

3. Choose Finish.

   SilverStream constructs a getCompanyID() method that looks like this:

     public String getCompanyID() throws java.rmi.RemoteException  
     { 
     } 
   

4. Add this code to the method:

     return m_companyid; 
   

5. Save the bean class.

To create the getCompanyName() method:

1. Choose Tools>Add New Method to invoke the Add New Method Wizard.

2. Follow the wizard instructions using these values:
   • Method Name: getCompanyName

   • Visibility: public

   • Return Type: String

   • # of parameters: 0

   • Check the Throws exceptions check box and add the java.rmi.RemoteException.

3. Choose Finish.

   SilverStream constructs a getCompanyName() method that looks like this:

     public String getCompanyName() throws java.rmi.RemoteException  
     {  
     } 
   

4. Add this code to the method:

     return m_companyname; 
   

5. Save the bean class and exit the Business Object Designer.

To create the EBCompany remote interface:

1. From the quickstart.companydemo package, choose the New icon.

2. Choose New Interface to invoke the Interface Wizard.

3. Follow the wizard instructions using these values:
   • Add the interface javax.ejb.EJBObject

   • Name the interface EBCompany

4. Choose Finish.

   SilverStream constructs a shell for the EBCompany interface that looks like this:

     public interface EBCompany extends javax.ejb.EJBObject{} 
   

5. Import the following package:

     import java.rmi.RemoteException; 
   

   NOTE   This should follow the package declaration.

6. Add the following methods to the interface (between the {}):

     public String getCompanyID() throws RemoteException; 
     public String getCompanyName() throws RemoteException; 
   

7. Save the EBCompany remote interface and exit the Business Object Designer.

To create the EBCompanyHome interface:

1. From the quickstart.companydemo package, choose the New icon.

2. Choose New Interface to invoke the Interface Wizard.

3. Follow the wizard instructions using these values:
   • Add a new interface javax.ejb.EJBHome

   • Name the interface EBCompanyHome

4. Choose Finish.

   SilverStream constructs a shell for the EBCompanyHome interface that looks like this:

     public interface EBCompanyHome extends javax.ejb.EJBHome 
     { 
     } 
   

5. Import these packages:

     import java.util.Collection; 
     import javax.ejb.*; 
     import java.rmi.RemoteException; 
   

   NOTE   This should follow the package declaration.

6. Add the create() method (corresponding to the EBCompanyBean's ejbCreate() method), the findByPrimaryKey() method, and the findByLikeness() method to the interface (between the {}):

     public EBCompany create(String psCompanyID, String 
        psCompanyName) throws CreateException, RemoteException; 
      
     public EBCompany findByPrimaryKey(EBCompanyPrimaryKey 
        pEntityPrimaryKeyCompany) throws FinderException,    RemoteException; 
      
     public Collection findByLikeness(String psCompanyName) 
        throws FinderException, RemoteException; 
   

7. Save the EBCompanyHome 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 (which includes mapping the persistent fields)

• Creating a deployment plan

• 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 (if not already chosen).

3. Choose Enterprise JavaBeans and right-click.

4. Choose Add Entity Bean.

   SilverStream creates an entry called UntitledEntityBean.

5. Highlight UntitledEntityBean.

6. Right-click and choose Properties.

7. Complete the Property Inspector so it looks like the one shown below.

   If you used a different package structure or object names, you should adjust your entries accordingly.

   NOTE   You can choose the ellipsis button (...) and select the correct entry from the dialog.

   

8. Verify that Container-managed persistence is selected in the Persistence type field.

9. Close the property sheet.

To specify the bean's persistent fields:

1. Choose Persistent Fields, right-click and choose Add.

2. Add both m_companyname and m_companyid.

To specify transaction attributes:

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

   SilverStream creates an UntitledTransaction entry.

2. Choose UntitledTransaction, right-click and choose Properties.

3. Provide these entries in the Property Inspector:
   • Name: TransactionRequired.

   • Attribute: Required.

   • Description: TransactionRequired (optional)

4. Choose the + Methods icon, then choose Edit Methods.

   SilverStream displays the Edit Methods dialog.

5. Choose the * under EBCompanyBean.

   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 followed by Jars.

2. From the list of JARS, choose QuickStartEB.

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 the EBCompanyBean.

8. Specify these values in the Bean tab of the Property Inspector:
   • JNDI Deployment Name: EBCompanyBean

   • Table: Companies

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

10. Add the getCompanyID() and getCompanyName() methods to the right pane of the selection dialog.

    The ability to specify the methods that do not modify fields is a SilverStream-specific deployment feature. For more information see the Deploying EJBs chapter in the Programmer's Guide.

11. With the Property Inspector open, click each of the persistent fields and map it 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 and specify these values in the Property Inspector:
    • Type: Expression

    • Where Clause: Companies.companyname like javaLangString0

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

    SilverStream prompts for a deployment plan name.

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

15. Choose Save and Deploy.

    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 Examples3_EJB 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 Examples3_EJB database.

2. Open the pgCompanyQuickStart.html page.

3. Open the Programming Editor.

4. In the General/Imports section, search for this comment (you might need to be in whole file view to do a search):

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

5. Add this import statement below the comment:

     import quickstart.companydemo.*; 
   

6. Make sure the page refers to the the EJB Remote JAR that you created earlier by choosing File> Jar Files and adding the following JAR file:

     Examples3_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/EBCompanyBean"); 
   

   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. The EBCompanyBean is the JNDI name you specified in the deployment pane of the JAR 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 = (EBCompanyHome) 
        javax.rmi.PortableRemoteObject.narrow(objEntityBeanLookup, 
        quickstart.companydemo.EBCompanyHome.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.

      EBCompany ebCompany = (EBCompany) 
         javax.rmi.PortableRemoteObject.narrow(objEntityBeanCompany,  
          quickstart.companydemo.EBCompany.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 Page Designer.

To call the bean:

1. Run the pgCompanyQuickStart.html page in test mode.

To get a company by Company ID:

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

   The page should return Anthony's Seafood 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 restaurants:

     ANTH Anthony's Seafood 
     ATLF Antlantic Fishes 
   

   This illustrates the findByLikeness() method.