Example: Creating a session bean facade

This topic demonstrates how to use the Create Session Bean Facade wizard to generate a session bean facade. It also gives several examples of using annotations to change the session bean facade.

For this scenario, you have an EJB project that includes CMP entity beans that manage the persistence of data for an auction application. For example, your CMP entity beans handle the registration of user accounts, the handling of accounts payable, and the management of bids and items for sale. The project includes an EJB 2.1 CMP entity bean called Registration.

The Registration CMP entity bean is designed to persist all data related to a given user. For example, the Registration bean includes the following attributes:

You want to create a session bean facade and SDOs for the Registration CMP entity bean to manage users and their accounts payable. You can use the Create Session Bean Facade wizard to quickly create the facade and SDOs.

Remember: Because the sample bean code is not provided for this example, the following steps simply demonstrate the process and the resulting output. You can experiment with the wizard and annotations using your own CMP entity beans.

To open the wizard, right-click your Registration CMP entity bean in the Project Explorer and select Create Session Bean Facade from the pop-up menu. The Create Session Bean Facade wizard opens.
Name the session bean facade RegistrationFacade, and select the Registration CMP entity bean.
On the next page of the wizard, name the SDO and make sure that it is not read only.
Select the CMP attributes and container-managed relationship (CMR) fields that you want to include in the service data objects (SDOs).
- For this example, you include all the attributes defined in the Registration bean. The required attributes, including the userid primary key field, are selected by default. The wizard also selects the foreign key relationship (fk_shipaddress : Address).
- You then select the check box next to the [0..*] accountspayable: Accountspayable CMR relationship:
  
  Note:
  - Required fields are selected by default and must be included if the SDO is not read only.
  - CMR entities that are currently selected in the right-side table are highlighted with blue text in the left table.
At this point, click Finish, or click Next to specify a visual diagram that you want to add the session bean facade to.
- The wizard generates the RegistrationFacadeBean session bean in the EJB project.
  
  In addition to the standard enterprise bean methods (ejbCreate, ejbActivate, ejbPassivate, ejbRemove, getSessionContext, and setSessionContext), the new RegistrationFacade session bean includes the following methods for the Registration SDO:
  - applyRegistrationRootChanges
  - createRegistration
  - deleteRegistration
  - getAllRegistrationObjects
  - getRegistrationByKey
  - getRegistrationRoot
  - updateRegistration
  The RegistrationFacade session bean includes both remote and local client views, which are generated in the EJB client JAR project.
- The SDO Java classes and utility Java classes are generated in the EJB client JAR project.
  - The RegistrationRoot.java file is the root SDO interface. It includes create() methods for non-contained relationships and for the Registration entity itself.
  - The Address.java, Accountspayable.java, and Registration.java are the SDOs for each of the included CMR relationships that you included. Each SDO includes the getter and setter methods for the attributes that were included.
  - The SdoClientFactory.java class is a factory that includes a createNewEmptyRegistrationRoot() method.
- Because the Registration CMP entity bean was selected as the root entity bean for the facade, annotations were added to the RegistrationBean.java file. The annotations are used by the workbench to generate the appropriate session bean classes and SDO classes. By completing the wizard as described in this scenario, the following annotations are added:
  - At the beginning of the RegistrationBean.java file, a @ws.sbf.session-facade tag is used to define the name of the facade and the associated SDO value-object. A @ws.sdo.value-object tag defines the SDO:
```
/**
 * @ws.sbf.session-facade
 *     name="RegistrationFacade"
 *     value-objects="Registration"
 * @ws.sdo.value-object
 *     name="Registration"
 *     read-only="false"
 * Bean implementation class for Enterprise Bean: Registration
 */
public abstract class RegistrationBean implements javax.ejb.EntityBean {
```
  - For each CMP attribute in the Registration entity bean that was selected in the wizard to be part of the session bean facade, the following annotation is added in the RegistrationBean.java file:
```
/**
     * @ws.sdo.value-object
     *     match="Registration"
     * Get accessor for persistent attribute: email
     */
    public abstract java.lang.String getEmail();
```
  - For each container-managed relationship defined in the RegistrationBean.java file that was selected in the wizard to be part of the session bean facade, the following annotation is added in the RegistrationBean.java file:
```
/**
     * @ws.sdo.value-object
     *     match="Registration"
     *     target-value-object="Address"
     *     contained="false"
     * This method was generated for supporting the relationship role named fk_shipaddress.
     * It will be deleted/edited when the relationship is deleted/edited.
     */
    public abstract sample.AddressLocal getFk_shipaddress();
```
- Because the relationship to the AccountsPayable entity bean was added to the facade in the wizard, the following annotations were added to the AccountsPayable bean:
```
/**
 * @ws.sdo.value-object
 *     name="Accountspayable"
 *     read-only="false"
 * Bean implementation class for Enterprise Bean: Accountspayable
 */
```
Edit the annotations in RegistrationBean.java to modify the name of the session bean facade. Change the value of the name parameter to RegistrationFacade1 and save your changes.
```
/**
 * @ws.sbf.session-facade
 *     name="RegistrationFacade1"
 *     value-objects="Registration"
 * @ws.sdo.value-object
 *     name="Registration"
 *     read-only="false"
 * Bean implementation class for Enterprise Bean: Registration
 */
```
After you save your changes, the workbench rebuilds a new RegistrationFacade1 session bean based on the changed annotations:
Use the annotations to add a query to the session bean facade.
1. In the RegistrationBean.java file, insert a new @ws.sbf.query annotation. As you type the annotation, you can enter Ctrl-Space to use the content assist feature. The following image shows the editor suggesting valid entries:
2. Name the query FindRegistrationByEmail.
3. Use the content assist feature to enter [select {$Registration} as r where r.email = ?1] as the query value.
4. Add the new query to the session facade by adding the queries parameter to the @ws.sbf.session-facade tag:
```
/**
 * @ws.sbf.session-facade
 *     name="RegistrationFacade1"
 *     value-objects="Registration"
 *  queries="FindRegistrationByEmail"
 * @ws.sdo.value-object
 *     name="Registration"
 *     read-only="false"
 * @ws.sbf.query
 *   name="FindRegistrationByEmail"
 *   query="[select {$Registration} as r where r.email = ?1]"
 * Bean implementation class for Enterprise Bean: Registration
 */
```
  After you save your changes, the workbench rebuilds the RegistrationFacade1 session bean based on the changed annotations with the new query. The RegistrationFacade1 now includes the following two new methods:
  - applyFindRegistrationByEmailChanges(FindRegistrationByEmail)
  - getFindRegistrationByEmail(Serializable[])
    Note: The arguments in this array are indexed based on the indexes defined in the query arguments.
Add a new RegistrationLite SDO to the session bean facade that includes the email and userid attributes in the Registration entity bean:
1. In the Registration entity bean, define a new @ws.sdo.value-object tag with the name RegistrationLite. The RegistrationLite value-object also needs to be added (delimited by a space) in the value-objects parameter of the @ws.sbf.session-facade tag:
```
/**
 * @ws.sbf.session-facade
 *     name="RegistrationFacade1"
 *     value-objects="Registration RegistrationLite"
 *  queries="FindRegistrationByEmail"
 * @ws.sdo.value-object
 *     name="Registration"
 *     read-only="false"
 * @ws.sdo.value-object
 *  name="RegistrationLite"
 *  read-only="false"
 * @ws.sbf.query
 *   name="FindRegistrationByEmail"
 *   query="[select {$Registration} as r where r.email = ?1]"
 * Bean implementation class for Enterprise Bean: Registration
 */
```
2. Update the annotations for the userid and email attributes to include them in the new RegistrationLite object:
```
/**
     * @ws.sdo.value-object
     *     match="Registration"
     * @ws.sdo.value-object
     *   match="RegistrationLite"
     * Get accessor for persistent attribute: userid
     */
    public abstract java.lang.Integer getUserid();
```
```
/**
     * @ws.sdo.value-object
     *     match="Registration"
     * @ws.sdo.value-object
     *   match="RegistrationLite"
     * Get accessor for persistent attribute: email
     */
    public abstract java.lang.String getEmail();
```
  Because the RegistrationLite SDO was not defined as read-only and only the userid and email attributes were included in the SDO, validation warnings are displayed in the editor stating that required fields are not part of the SDO. The warnings are given because a "create" will fail if the key and required attributes are not part of the SDO.
The RegistrationFacade1Bean now includes the following methods:
- applyRegistrationLiteRootChanges(RegistrationLiteRoot)
- createRegistrationLite(RegistrationLite)
- deleteRegistrationLite(RegistrationLite)
- getAllRegistrationLiteObjects()
- getRegistrationLiteByKey(RegistrationKey)
- getRegistrationLiteRoot()
- updateRegistrationLite(RegistrationLite)
Add another SDO for the Status entity bean to the same RegistrationFacade1 session bean facade:
1. In the StatusBean.java file, add the following annotations to the bean implementation
```
/**
 * @ws.sbf.session-facade
 * match="RegistrationFacade1"
 * value-objects="Status"
 * @ws.sdo.value-object
 *   name="Status"
 *   read-only="true"
 * Bean implementation class for Enterprise Bean: Status
 */
```
2. In the RegistrationBean.java file, add the Status value-object to the list defined for the session bean facade:
```
* value-objects="Registration RegistrationLite Status"
```
Because you defined the Status SDO as read-only, the following methods are added to the RegistrationFacade1Bean class (no update, create, or delete methods are added):
- getAllStatusObjects()
- getStatusByKey(StatusKey)
- getStatusRoot()

Parent topic

Creating session bean facades

Related concepts

Session bean facades and SDOs