Step 2: Define the Entity Bean

In this step you will create the entity bean Visit, which will hold information about visitors and the number of prior visits. An entity bean interacts with a database table to store, find, and update information.

The tasks in this step are:


To Create a Package

All EJBs (and all Java classes) must be part of a Java package.

  1. Right-click the MyEJBProject folder in the Application tab, and select New-->Folder.
  2. Enter the folder name hello.
  3. Click OK.

To Create an Entity Bean

  1. Right-click the hello folder in the Application tab, and select New-->Entity Bean.
  2. Enter the file name VisitBean.ejb.

  3. Click Create.

The entity bean opens in Design View. The Application tab should now look like the picture on the right.

The top-level folder GettingStarted_EJB is the containing folder for the entire application. All of the source files for your application exist in this folder.

The folder MyEJBProject is the EJB project folder. An application can contain any number of project folders and there are many different kinds of project folders, including Web projects, Web Services projects, Schema projects, and so forth.

The Modules folder is for the storage of stand-alone applications (packaged as WAR and JAR files) that can deployed parallel with your web service, if you wish.

The Libraries folder is for the storage of resources that are to be used across multiple projects, provided the resources are packaged as JAR files. For example, if you had a control or an EJB that you wanted to re-use across all your projects, you would store it in the Libraries folder.

The Security Roles folder lets you define security roles and test users for your web application. You can test the security design of your web application by logging in as a test user.

To Change the Database Table

When a new entity bean is created, a number of properties are automatically set for you. These properties are listed in the Property Editor. For example, notice that the ejb-name is Visit, the data-source-name is MyDataSource, the name of the database table used to store the data is visit, and that the create-tables setting is set to CreateOnly. The latter setting means that when you build and deploy this EJB, the table will be automatically created for you. To learn more about the other table creation options set with this property, see @ejbgen:jar-settings Annotation. Notice that the create-tables setting is part of the JAR settings. In other words, for every entity bean created as part of this project, the same table creation setting applies.

Also notice that the names of the bean's local interfaces are already set. The home interface class, set in the Home class name property, is called VisitHome, while the business interface, set in the Bean class name property, is Visit. Finally, the JNDI name, used to locate the entity bean, is ejb.VisitLocalHome. JNDI naming is discussed in detail in the next step. To learn more about the entity bean architecture, see Getting Started with Entity Beans.

Let's use the Property Editor to make two changes. First, the data source name for the Visit bean does not match the name of the data source that is used in the workshop domain. Second, let's rename the database table to better reflect that it is part of this tutorial:

  1. From the Tools menu, select WebLogic Server-->DataSource Viewer. The DataSource Viewer dialog appears.
  2. Notice that one of the data sources is called cgSampleDataSource. Click OK.

    Note. If you cannot find cgSampleDataSource, verify that the correct workshop domain was selected in Step 1 of the tutorial.

  3. In the Property Editor, locate data-source-name and change the entry to cgSampleDataSource.
  4. In the Property Editor, locate table-name and the table name to visit_GS_EJB.

When you build and deploy the Visit bean, the table with the table name visit_GS_EJB will be created for you, and the bean will interact with this database table to persist data about visits.

To Define CMP Fields

Now you define the container-managed persistence (CMP) fields for the Visit bean. CMP fields are virtual fields that are not defined in the entity bean itself but are mapped to columns in the database table. The entity bean code only implements the accessor (getter and setter) methods to read and write the data stored in these fields. In WebLogic Workshop these accessor methods are by default added to the bean's local business interface for you.

You need to define two fields that hold the name of the visitor and the number of visits. The name of the visitor will also be used as the primary key. The primary key is the unique index in a database table. In other words, you make the assumption that each visitor's name is unique and that you can use it to uniquely identify what stored data about the number of visits belongs to him/her.

  1. Ensure that the Visit bean is displayed in Design View.
  2. Right-click the VisitBean and choose Add CMP field. A CMP field called String field1 appears in the CMP Fields section.
  3. Rename the field String visitorName. If you step off the field and need to rename it, right-click the field and select Change declaration.
  4. Right-click the field String visitorName and select Primary Key. A key icon appears in front of the field definition. The yellow diamond indicates that the method getVisitorName and setVisitorName will be declared in the local business interface.
  5. Make sure the visitorName declaration in Design View is still selected and verify in the Property Editor tab, which now displays the properties for this field, that the database column is visitorName. If this is not the case, make this change now.
  6. Right-click the VisitBean again, and choose Add CMP field. A CMP field called String field1 appears in the CMP Fields section.
  7. Rename the field int visitNumber. If you step off the field and need to rename it, right-click the field and select Change declaration.
  8. Select the visitNumber declaration in Design View and verify in the Property Editor tab that the database column is visitNumber. If this is not the case, make this change now.
  9. Save your results.
  10. Go to source view and examine the code. Notice that the getter and setter methods have been defined for these properties but that there are no variables declared in the bean class to hold the actual property values.

Now you have defined two CMP fields and their accessor methods. Also, you have mapped these fields to columns with the same names in the database table. (The name of the CMP field and the corresponding column name can be different, but for consistency reasons you have given them the same name here.) Finally, you have assigned one of these fields to function as the primary key.

To Add EJBCreate

Now you will add an ejbCreate method, which when invoked creates a new Visit bean and adds the corresponding record to the database table. To create a new instance, you must minimally provide the primary key to unique identify the record.

In addition to creating the ejbCreate method in the bean class, a corresponding create method must be defined in the bean's home interface. When you follow the steps below to define the ejbCreate method, WebLogic Workshop automatically defines the corresponding create method in the home interface for you.

  1. Ensure that the Visit bean is displayed in Design View.
  2. Right-click the Visit bean and and choose Add EJBCreate. The Add ejbCreate method dialog appears.

  3. Click OK. The method you created appears in the EJB Create Methods section.
  4. Click the ejbCreate method to go to Source View, and add the following line shown in red:
        public java.lang.String ejbCreate(java.lang.String VisitorName)
        {
          setVisitorName(VisitorName);
          setVisitNumber(1);
          
          return null; // FIXME return PK value 
        }
    
  5. Save your results.

When a new Visit bean instance is created using this ejbCreate method, the name of the visitor, passed as an argument in the method, is entered in the database. Also, it is noted that this is the visitor's first visit. In the next step of the tutorial you will see how to invoke this method.

An entity bean can have multiple ejbCreate methods. For instance, you could create another ejbCreate method for the Visit bean that would take a String name and an int number as arguments, and use these to set the name and visit number for a new bean instance. Each ejbCreate method must be unique, that is, it must have a unique set of parameters as arguments. For instance, for the Visit bean you cannot create a second ejbCreate method that has a String parameter as its sole argument.

When you go back to Design View, the Visit bean should look like this:

Build and Deploy

Now let's build the entity bean to make sure it is defined correctly. If the Visit bean builds successfully, it will be automatically deployed on the server.

  1. Locate the Build window in the IDE. If the Build window is not there, select View-->Windows-->Build.
  2. In the Application pane, right-click MyEJBProject, and select Build MyEJBProject.
  3. Monitor the Build window and verify that the build completes correctly, and that the EJB JAR MyProjectEJB.jar is created. You will see this JAR appear in the MyEJBProject folder.
  4. After the build completes, the EJB deploys: Watch the green ball in the WebLogic Server status bar at the bottom of WebLogic Workshop turn yellow with the message Updating Server. Wait until the ball turns green again. The EJB is now deployed on the server.

If you encounter build errors, verify that the various methods and interfaces have been created correctly. If you encounter a deployment error, make sure that the data source and database table settings are set correctly.

Optionally you can expand MyProjectEJB.jar and the contained hello folder. In this folder you will see (among other files) the Java classes for the bean and its interfaces, and the corresponding compiled .class classes.

Related Topics

Getting Started with Entity Beans

Click one of the following arrows to navigate through the tutorial: