Create the OrderGift entity bean

Tutorials > Program model > Extend the object model and modifying an existing task command
< Previous | Next >

Create the OrderGift entity bean

The OrderGift entity bean allows you to access the information in the XORDGIFT table. Within the entity bean we will create fields that map to the columns in the XORDGIFT table.

Procedure
Open WebSphere Commerce Developer to the J2EE Perspective.

Within the Enterprise Explorer view, expand WebSphereCommerceServerExtensionsData > Deployment Descriptor: WebSphereCommerceServerExtensionsData.

From the Deployment Descriptor's pop-up menu, select New > Enterprise Bean.

In the Create an Enterprise Bean window:

Select Entity bean with container-managed persistence (CMP) fields.

From the EJB Project list, ensure WebSphereCommerceServerExtensionsData is selected.

In the Bean name field, enter OrderGift

In the Source folder field, leave the default value of ejbModule.

In the Default package field, enter com.ibm.commerce.extension.objects.
This is the package name WebSphere Commerce suggests for all new custom entity beans.

From the CMP vlist, select 1.x.

Click Next.

In the CMP Attributes text box, add fields that correspond to columns in the XORDGIFT table:

Select the default value id : Java.lang.Integer and click Remove.

Click Add.

Create the ordersId field, with the following information:

Parameter name Parameter value
Name ordersId
Type java.lang.Long
You must use the java.lang.Long data type, not the long data type.
Key Field Select

Click Apply.

Create the receiptName field,...

Parameter name Parameter value
Name receiptName
Type java.lang.String
Access with getter and setter methods Select
Promote getter and setter methods to remote interface Clear

Click Apply. Clearing the promote getter and setter methods to remote interface causes less overhead and better performance. Since the getter and setter methods are not promoted to the remote interface, clients will not be able to access the methods. Instead of using the remote interface, CopyHelper Access Beans exist that contain getters and setters for CMP fields that do not exist on the remote interface. The methods within the CopyHelper Access Beans write data to a hash table that in turn updates the database when commitCopyHelper() is called. The hash table can record multiple database changes then update the database in one transaction, unlike the remote methods which require one transaction per change. A method called refreshCopyHelper() that does the reverse function of commitCopyHelper(). The method refreshCopyHelper() writes to the hash table from the database. Clearing the check box ensures that the hashtable is used, resulting in the performance increase.

Create the senderName field,...

Parameter name Parameter value
Name senderName
Type java.lang.String
Access with getter and setter methods Select
Promote getter and setter methods to remote interface Clear

Click Apply.

Create the msgField1 field,...

Parameter Name Parameter Value
Name msgField1
Type java.lang.String
Access with getter and setter methods Select
Promote getter and setter methods to remote interface Clear

Click Apply.

Create the msgField2 field,...

Parameter name Parameter value
Name msgField2
Type java.lang.String
Access with getter and setter methods Select
Promote getter and setter methods to remote interface Clear

Click Apply.

Create the optcounter field,...

Parameter name Parameter value
Name optcounter
Type short
Access with getter and setter methods Clear

Click Apply then click Close.

Ensure Use the single key attribute type for the key class is not selected, then click Next. Clearing this check box ensures that a key class is created, ensuring consistency with other beans.

In the EJB Java Class Details window:

To select the bean's superclass, click Browse. The Type Selection window opens.

In the Select a class using: (any) field, enter ECEntityBean and click OK. This selects the com.ibm.commerce.base.objects.ECEntityBean as the superclass.

Click Next.

Deselect Add bean to Class Diagram.

Click Finish.

Set the isolation level for the OrderGift entity bean
An entity bean's isolation level defines when updated data is accessible to other transactions.
To set the isolation level for the OrderGift entity bean:

Double-click Deployment Descriptor: WebSphereCommerceServerExtensionsData to open it for editing.

Click the Access tab.

Click Add next to the Isolation Level field.

Select Read Committed, then click Next.

Select the OrderGift bean, then click Next.

Select OrderGift to select all of its methods, or click Apply to all.

Click Finish.

Save the work and keep the editor open.

Set the security identity of the OrderGift entity bean
You will specify that the OrderGift entity bean uses the security identity of the EJB container.
To set the security identity of the bean:

In the Deployment Descriptor editor, select the Access tab.

Click Add next to the Security Identity (Method level) field.

Select Use identity of EJB server, then click Next. Always use this setting for all new entity beans.

Select the OrderGift bean, then click Next.

Click Apply to all.

Click Finish.

Save the work and keep the deployment descriptor editor open.

Set the security role of the OrderGift entity bean
The security role of an entity bean determines which roles can execute the methods within the bean at runtime. You will specify the WCSecurityRole as the role that can execute the OrderGift entity bean's methods.
To set the security role for the methods in the bean:

In the Deployment Descriptor editor, select the Assembly tab.

In the Method permissions section, click Add.

Select Security Roles then WCSecurityRole and click Next.

From the list of beans found, select OrderGift and click Next.

In the Method elements page, click Apply to All, then click Finish.

Save the work and close the deployment descriptor editor.

Remove generated fields and methods
In the next section, you remove the fields and methods related to the entity context that are generated by Rational Application Developer. These fields and methods are not required since the ECEntityBean base class provides its own implementation of these methods.
To delete the generated entity context fields and methods:

In the Enterprise Explorer view, expand the WebSphereCommerceServerExtensionsData project.

Expand the Deployment Descriptor: WebSphereCommerceServerExtensionsData > Entity Beans > OrderGift then double-click OrderGiftBean.

In the Outline view, delete the following generated fields and methods:

myEntityCtx

getEntityContext()

setEntityContext(EntityContext)

unsetEntityContext()

Save the work.
Set all gift message fields in the ejbCreate method
Modify the generated ejbCreate method so that four gift message fields are explicitly set when a new OrderGift bean is created. You will set fields to null because you do not yet know their values.
To set the fields to null:
In the Outline view, select the ejbCreate(Long) method. Its source code displays...
public com.ibm.commerce.extension.objects.OrderGiftKey 
   ejbCreate(java.lang.Long ordersId)
   throws javax.ejb.CreateException {
      _initLinks();
      this.ordersId = ordersId;
      return null;
}
Add the following line as the first line of the method after the {: this.initializeFields();
Add the following lines after the this.ordersId = ordersId; line.
this.senderName = null;
this.receiptName = null;
this.msgField1 = null;
this.msgField2 = null;
OrderGiftKey myNewOrderGiftKey = new OrderGiftKey(ordersId);
this.initializeOptCounter(myNewOrderGiftKey);
The resulting method displays...
public com.ibm.commerce.extension.objects.OrderGiftKey
  ejbCreate(java.lang.Long ordersId)    throws javax.ejb.CreateException {      
 this.initializeFields();_initLinks();
this.ordersId = ordersId;
this.senderName = null;
this.receiptName = null;
this.msgField1 = null;
this.msgField2 = null;
OrderGiftKey myNewOrderGiftKey = new OrderGiftKey(ordersId);
this.initializeOptCounter(myNewOrderGiftKey);
return null; } 
Save the changes.
Create new ejbCreate and ejbPostCreate methods
Create new ejbCreate and ejbPostCreate methods that take the orders ID, recipient name, sender name and message fields as parameters.
To create the ejbCreate method:
Create a new ejbCreate(Long, String, String, String, String) method, by adding the following code into the class:
/*
* Takes the ordersId and gift message as parameters and sets
* the values of the fields as appropriate.
* @param ordersId The unique identifier of the order with the gift message
* @param receiptName Name of the gift recipient
* @param  senderName Name of the person sending the gift
* @param msgField1 First part of the message
* @param msgField2 Second part of the message
*/
public com.ibm.commerce.extension.objects.OrderGiftKey 
   ejbCreate(java.lang.Long ordersId,              
   java.lang.String receiptName,
   java.lang.String senderName,
   java.lang.String msgField1,
   java.lang.String msgField2)
   throws javax.ejb.CreateException {
      _initLinks();
      this.initializeFields();
      this.ordersId = ordersId;
      this.senderName = senderName;
      this.receiptName = receiptName;
      this.msgField1 = msgField1;
      this.msgField2 = msgField2; 
      this.initializeOptCounter(ordersId);
      return null;
  }
Save the code changes.
A warning might display because you do not have a matching ejbPostCreate method. The warning can be ignored as this will be done in next step.

You must add this new ejbCreate method to the home interface to make the method available in the generated access bean. In the Outline view, from the ejbCreate(Long, String, String, String, String) method's pop-up menu, select Enterprise Bean > Promote to Home Interface.
Next create a new ejbPostCreate(Long, String, String, String, String) method so that it has the same parameters as the ejbCreate(Long, String, String, String, String) method:
Double-click the OrderGiftBean class to open it and view its source code.
Create a new ejbPostCreate(Long ordersId, String receiptName, String senderName, String msgField1, String msgField2) method, by adding the following code into the class:
public void ejbPostCreate(
   java.lang.Long ordersId,    java.lang.String receiptName,    java.lang.String senderName,    java.lang.String msgField1,    java.lang.String msgField2)
      throws javax.ejb.CreateException {
   }
Save the code changes.
Create a database and table definition

If you have not completed the programming tutorial Tutorial: Creating new business logic, create a database definition. If you completed that tutorial then you already have a database definition and can skip this step and continue with step 13b.

Right-click WebSphereCommerceServerExtensionsData and select New > Other.

From the wizard, select Data > Physical Data Model and enter MyDBSchema as the file name.

Select the appropriate database type for the development environment:

DB2 for Linux, UNIX, and Windows

Oracle

The destination folder should populate after selecting the database type.

Select the appropriate database version:

v9.5

v11

Click Finish.

In the Enterprise Explorer view, navigate to WebSphereCommerceServerExtensionsData > Data Models > MyDBSchema.dbm.

Right-click Database > Add Data Object > Schema. In the properties panel, enter NULLID in the name field. You use NULLID as the schema name because this allows flexibility for EJB beans to work against any schema. If the schema name is filled in with a specific value other than NULLID, the EJB bean would only work for tables created using a specific schema.

Right-click NULLID > Add Data Object > Table. Enter XORDGIFT as the table name.

Add columns to the table by clicking the Columns tab and clicking the New symbol, just above the name column:

Create the following columns:

ORDERSID column properties and values
Property Value
Name ORDERSID
Primary key Selected
Data type

BIGINT
If selected, the other properties cannot be modified by default.

Number

Length
38
Scale
0
Not null Selected

RECEIPTNAME column properties and values
Property Value
Name RECEIPTNAME
Data type

VARCHAR

VARCHAR2

Length 50

SENDERNAME column properties and values
Property Value
Name SENDERNAME
Data type

VARCHAR

VARCHAR2

Length 50

MSGFIELD1 column properties and values
Property Value
Name MSGFIELD1
Data type

VARCHAR

VARCHAR2

Length 50

MSGFIELD2 column properties and values
Property Value
Name MSGFIELD2
Data type

VARCHAR

VARCHAR2

Length 50

OPTCOUNTER column properties and values
Property Value
Name OPTCOUNTER
Data type SMALLINT
Not null Selected

Map the XORDGIFT table to the OrderGift entity bean
The next step is to map the XORDGIFT table to the OrderGift entity bean. Since the OrderGift bean and the XORDGIFT table already exist, Meet-in-the-middle mapping is used.

If you have completed Tutorial: Creating new business logic, do the following to create the mapping:

In the J2EE perspective, Enterprise Explorer view, highlight the EJB Projects > WebSphereCommerceServerExtensionsData > ejbModule > META-INF > backends > databaseType > Map.mapxmi file.

From the Map.mapxmi file's pop-up menu, select Open With > Mapping Editor.

When the Map.mapxmi file opens, in the Enterprise Beans pane, highlight the OrderGift bean. In the Tables pane, highlight the XORDGIFT table.

Map the fields in the OrderGift bean to the columns in the XORDGIFT table by selecting Match By Name from the bean's pop-up menu.

Save the Map.mapxmi file.

If you have not completed Tutorial: Creating new business logic, do the following to create the mapping:

In the J2EE perspective, right-click WebSphereCommerceServerExtensionsData and select Jave EE > EJB to RDB Mapping (1.x - 2.x) > Generate Map.

On the first page of the Mapping wizard we will be asked to Specify the backend folder that will contain generated mapping file, database schema and other runtime information. The Use an existing backend folder radio button is pre-selected.

Click Next.

Select Meet In The Middle and click Next.

Select None and click Finish. The Map.mapxmi editor opens.

In the Enterprise Beans pane, highlight the OrderGift bean. In the Tables pane, highlight the XORDGIFT table.

Map the fields in the OrderGift bean to the columns in the XORDGIFT table by right-clicking the OrderGift bean and selecting Match By Name from the bean's pop-up menu.

Save the Map.mapxmi file.

Enable optimistic locking
To enable optimistic locking:

Enable optimistic locking in the deployment descriptor:

In the EJB Deployment Descriptor in the Bean tab select the OrderGift entity bean.

Scroll down to the Concurrency Control section.

Select Enable optimistic locking.

Save the changes.

Set the optimistic predicate value of the optcounter field:

Double-click WebSphereCommerceServerExtensionsData > ejbModule > META-INF > backends > databaseType > Map.mapxmi.

Map.mapxmi should open in the Mapping Editor.

In the Overview section, in the Enterprise Beans pane, select optcounter : short.

Select the Properties view, and ensure true is selected from the OptimisticPredicate list. Your screen should resemble the following screen capture:

Create an access bean
Once the OrderGiftBean entity has been created and the schema is correctly mapped, you can create a Copy Helper access bean for the entity bean. This access bean makes it simpler for applications to access information contained in the OrderGift entity bean. The methods within the Copy Helper access bean write data to a hash table that in turn updates the database when commitCopyHelper() is called. The hash table can record multiple database changes then update the database in one transaction, unlike the remote methods which require one transaction per change. A method called refreshCopyHelper() that does the reverse function of commitCopyHelper(). The method refreshCopyHelper() writes to the has table from the database. Deselecting the box ensures that the hashtable is used, resulting in the performance increase.
To create the Copy Helper access bean for the OrderGift entity bean:

Open the deployment descriptor.

In the Bean tab, select OrderGift.

In the bottom right pane, scroll down to the Access Beans section and click Add.

Select Copy Helper and click Next.

Select the OrderGift bean and click Next.

From the Constructor method drop-down list, select findByPrimaryKey(com.ibm.commerce.extension.objects.OrderGiftKey).

Select all attributes in the Attribute Helpers section.

Click Finish.

Save the changes.

You can view the newly generated access bean code by switching to the Project Navigator view, expand the WebSphereCommerceServerExtensionsData project, and expand ejbModule sub-folder, then expand com.ibm.commerce.extension.objects. A new class called OrderGiftAccessBean and a new interface called OrderGiftAccessBeanData are created and display inside the package.

Generate the deployed code
The code generation utility analyzes the beans to ensure that Sun Microsystems' EJB specifications are met and it ensures that rules specific to the EJB server are followed. In addition, for each selected enterprise bean, the code-generation tool generates the home and EJBObject (remote) implementations and implementation classes for the home and remote interfaces, as well as the JDBC persister and finder classes for CMP beans. It also generates the Java ORB, stubs, and tie classes required for RMI access over IIOP, as well as stubs for the home and remote interfaces.
To generate the deployed code:

Navigate to EJB Projects > WebSphereCommerceServerExtensionsData.

Open Deployment Descriptor WebSphereCommerceServerExtensionsData.

In the Overview tab, scroll down to the JNDI - CMP Connection Factory Binding section and in the JNDI name field enter the value that matches the database type:

jdbc/WebSphere Commerce Cloudscape DataSource demo

jdbc/WebSphere Commerce DB2 DataSource demo

jdbc/WebSphere Commerce Oracle DataSource demo

Save and close the Deployment Descriptor.

Right-click WebSphereCommerceServerExtensionsData and select Java EE > Prepare for Deployment.
< Previous | Next >

+
Search Tips | Advanced Search

Parameter name	Parameter value
Name	ordersId
Type	java.lang.Long You must use the java.lang.Long data type, not the long data type.
Key Field	Select

Parameter name	Parameter value
Name	receiptName
Type	java.lang.String
Access with getter and setter methods	Select
Promote getter and setter methods to remote interface	Clear

Parameter name	Parameter value
Name	senderName
Type	java.lang.String
Access with getter and setter methods	Select
Promote getter and setter methods to remote interface	Clear

Parameter Name	Parameter Value
Name	msgField1
Type	java.lang.String
Access with getter and setter methods	Select
Promote getter and setter methods to remote interface	Clear

Parameter name	Parameter value
Name	msgField2
Type	java.lang.String
Access with getter and setter methods	Select
Promote getter and setter methods to remote interface	Clear

Parameter name	Parameter value
Name	optcounter
Type	short
Access with getter and setter methods	Clear

Property	Value
Name	ORDERSID
Primary key	Selected
Data type	BIGINT If selected, the other properties cannot be modified by default. Number
Length	38
Scale	0
Not null	Selected