Managing Relationships

Entity 2.0 beans with container managed persistence may have relationships with each other. Relationships may be one-to-one, one-to-many, or many-to-many relationships. Studio provides a Relationship Manager, which is very useful in situations where the user wants to define new relationships after the bean as been created or modify the existing relationships.

The following sections describe how to manage relationships and simplify the complex process of building and managing such components using the Relationship Manager.

Starting the Relationship Manager

Click on Tools > Relationship Manager from the main menu to bring up the relationship manager. Relationship Manager comes up only when the Desk contains at least one EJB 2.0 module with CMP 2.0 beans.

The Relationship Manager is used to define new relationships and modify, and delete existing relationships between beans in the same module. Studio supports self relationships (bean having a relationship with itself). This dialog therefore appears even when there is only one bean in the module.

Note: In case of Self bi-directional relationships, Pramati Server supports only "One-to-many" relationships.

Using the Relationship Manager

In the Relationship Manager dialog that comes up, follow the given steps and perform the required functionalities:

Module Name Select from the modules existing in the active Desk to start working with the container managed relationships.

Bean Name Filter Select the bean name from the combo box to view only those relationships that have been defined using the specific bean. Selecting Show All from the combo box displays all the relationships existing in the specific module. The option Show All is selected by default.

Once the above fields have been selected, the existing relationships are displayed in the lower half of the dialog. The fields displayed are:

Source The source bean name in the relationship is displayed in this field.

Relation The nature of relation existing between the two beans is displayed in this field. The relation is defined by the multiplicity and navigability.

Target The target bean name in the relationship is displayed in this field. If there is a relationship defined, where the target EJBName does not exist, the target EJBName alone is displayed in red. On selecting that row in the table, the buttons Add, Delete and Modify are enabled and the button Revert disabled.

Join Click on the symbol appearing in this column and a new dialog called Join Condition pops up. The Join Condition dialog is used to define the Join conditions.

Refer the section, `JOIN Condition' for detailed information on defining JOIN conditions for container managed relationships.

Adding New Relationships

Click on the Add button to define a new relationship. This brings up the dialog, Create New Relationship where the new relationship to be added is defined. This dialog is divided in three sections - Source, Relation and Target.

The Source and Target EJB Names are displayed in a combo box and contain only those EJBNames that can participate in the relationship. Only CMP 2.0 beans containing Local Interfaces can have relationships. If the user types a CMR name that is already in use, a message "XYZ CMR name is already in use in a relationship with ABC Bean" is displayed. The CMR name is then displayed in red and the OK button disabled.

The OK button is enabled only after all the enabled fields have been appropriately filled. Click on the OK button after the relationship has been defined. The added relationship row is displayed in green color.

Clicking on the OK button brings up the progress bar, which displays the process of addition being performed. Clicking on the Cancel button reverts all the modifications done to the source code and the user is taken back to the Relationship Manager dialog.

Once the additions have been completed, the Cancel button changes to Undo, allowing the user to undo all the changes made in the source code, if any. Clicking on the Close button, saves the relationship information in the beans.

Deleting Relationships

Select the relationship row to be deleted and click on the Delete button. This marks the relationship for deletion and displays it in red. Clicking on the OK button confirms the deletion process. A relationship which has been added in the same session, when deleted is removed from the table without asking the user for confirmation.

Clicking on the OK button brings up the progress bar, which displays the deletions being performed. Clicking on the Cancel button reverts all the deletions and the user is taken back to the Relationship Manager dialog.

Once the deletions have been completed, the Cancel button changes to Undo, allowing the user to undo the delete command. Clicking on the Close button, deletes the relationships and saves the information in the beans.

Modifying Existing Relationships

Select the relationship to be modified from the Relationship Manager panel and click on the Modify button. This brings up the Modify Relationship panel, where the existing relationship can be modified.

Rows marked for deletion cannot be modified, and selecting such a row disables the Modify button. For such relationship rows, select the row, click on the Revert button, and then click on the Modify button.

In the Modify Relationship dialog that pops up, the Source and Target EJB Names cannot be modified. When an invalid relationship is selected for being modified, only the Target EJBName is displayed as a combo box and is editable, while the Source EJBName remains un-editable.

In the Modifying Relationships dialog, details of the modifications made are shown in a text area that can be hidden. These details are also logged in a file under the Desk's folder location. The file name starts with "Relationship_changes_" and is suffixed with the time stamp when the changes were made. While the modification are still in progress, the user can choose to cancel the modification, in which case, all the modifications done to the source code will be reverted, and the Relationship Manager's main dialog pops up on the screen.

The OK button is enabled only after all the enabled fields have been appropriately filled. Click on OK after making the necessary modifications. Modified relationship rows are displayed in blue color, except when the modified relationship was added in the current session. In such a case, the relationship row remains green in color, indicating that the relationship has been added in the current session.

Clicking on the OK button brings up the progress bar, which displays the modifications performed. Clicking on the Cancel button reverts all the modifications done to the source code and the user is taken back to the Relationship Manager dialog.

Once the modifications have been completed, the Cancel button changes to Undo, allowing the user to undo all the changes made in the source code, if any. Clicking on the Close button, compiles all the modified sources and then the new relationship is saved in the beans.

The Relationship Manager changes only the signatures of the Get/Set methods of the bean class and the local interface. All the places in the code where these methods have been used, have to be manually changed by the user, and therefore in most cases, the compilation performed after modifications might give errors.

It is strongly recommended that before using the Relationship Manager, all source files involving source code modifications are in a parseable state, are not open in the editor; or being used by other programs.

Reverting Commands

The Revert command is used for cancelling a delete or modify command. The button is enabled only when the selected row has been marked for modification or deletion.

Before trying to revert a relationship to its original state, ensure that the original state is still valid, like old CMR names not being used by other relationships.