Working With Enterprise Beans

The relationships between the elements of an enterprise bean can be intricate and complex. The Sun ONE Studio 5 IDE makes certain assumptions to preserve the integrity of your beans, but also flexibly supports various options for reusing beans. This appendix prescribes the best practices for working with existing enterprise beans.

---

Using Recommended Approaches When Editing Beans

To be certain that changes take place as you intended, make your edits through the enterprise bean's logical node and property sheets. If you use these recommended approaches, the IDE can ensure that the standards in the J2EE specification are followed.

These approaches are explained next.

Working Through the Logical Node

As a general rule, it's best to go through the logical node of your enterprise bean to make changes in the bean's code. This node's icon looks like a coffee bean: The node was designed to organize all the elements of your enterprise bean.

When you work through the logical node, the IDE can most easily propagate the changes correctly throughout the bean.

All the classes in your bean are represented under this one node, as if the bean were a single object. There you can edit your enterprise beans without having to think about which class must receive each change. For example:

• When you add a new method to the Create Methods node under a bean's logical node, the body of that method (ejbCreateXxx) and its related method (ejbPostCreateXxx, required for entity beans) are added to the bean class. Depending on which types of interface the bean has, the corresponding method signature (createXxx) is added to the local home interface, the home interface, or both.
• When you add a new method to the Finder Methods node under an entity bean's logical node, the Add New Finder Method dialog box prompts you for the correct name of the method. The method signature is added to the local home interface, the home interface, or both.
• In a CMP entity bean, the Add New Finder Method dialog box also prompts you for EJB QL Select, From, and Where statements. When you deploy your bean to a supported application server, this EJB QL code is automatically converted into the kind of SQL that the server needs.

If you want to define a new finder or select method but you aren't ready to provide the EJB QL code yet, you can disable the EJB Compiler's requirement for EJB QL. See Compiling and Validating Enterprise Beans.

• In a BMP entity bean, the corresponding ejbFind method is also added to the bean class.)

• When you add a new method to the Business Methods node under a bean's logical node, the method body is added to the bean class. Depending on which types of interface the bean has, the method signature is added to the local interface, the remote interface, or both.
• When you add a new method to the Home Methods node under the logical node, the method body is added to the bean class, and the method signature is added to the appropriate interface or interfaces.
• When you add a new method to the Select Methods node under a CMP entity bean's logical node, the Add New Select Method dialog box prompts you for all the information needed to complete the method, including EJB QL statements. The method body is added to the bean class.

In many cases, the IDE can propagate your changes and synchronize your bean's classes and interface even when you go through other nodes of your bean to edit the Java code. However, you get the most consistent results by working through the logical node.

Using the Customizer or Property Sheet

When you need to modify a method's name or return type, or when you need to edit or add a parameter or exception, the best place to do so is in the method's Customizer dialog box or property sheet. Under the logical node, select the method, right-click, and choose Customize or Properties.

• The Customizer has the same format as the dialog box in which you created the method.
• The property sheet shows the method's parts in tabbed interfaces that correspond to the classes that the method inhabits.

Any change you make in one of these two places is validated and propagated in the right form to the right classes.

When you need to add code to complete a method, use the IDE's Source Editor.

---

Caution - If you make changes outside the logical node, by working within the bean class node or one of the interface nodes, the EJB Builder still tries to propagate your changes. However, in certain cases, you might need to manually ensure that your code matches Sun's J2EE specification. See the specific examples that follow.

---

Using the Source Editor to Edit Beans

You can create or modify any part of an enterprise bean by using the IDE's Source Editor exclusively. However, the IDE's wizards and other GUI tools are designed to save you work and to help prevent inconsistencies, so that you can produce standard, J2EE-compliant enterprise beans quickly.

In some cases, if you bypass the assistance offered by the EJB Builder, you might get mixed results. The EJB Builder tries to keep the changes you make in one class synchronized appropriately with the other classes, but the tool might not always be able to understand your intent and might not apply all the changes needed. Therefore, if you make direct changes to class code, the result might be an enterprise bean with errors that you must correct by hand.

A few examples follow:

• You open a bean's interface class (home, remote, local home, or local) in the Source Editor, and you add code for a new method.

To be valid, a method must have a name and the correct return type, and the method must throw the appropriate exceptions. If the new method is valid, it is automatically added to the bean class. If not, the method remains as you coded it, in the interface only.

Afterward, you might find and fix the problem in the method. However, the EJB Builder might not always be able to add the repaired method to the bean class; you might have to add it yourself. Until you make the manual addition, the method's node in the Explorer displays an error badge with a red X. (See Understanding the IDE's Error Information.)

Here are two examples of how changes are propagated between classes:

• If you correctly add a create method to the home interface, the EJB Builder automatically adds the corresponding ejbCreateXxx method to the bean class.
• If you correctly add an ejbCreateXxx method to the bean class, the EJB Builder automatically adds the corresponding create method to the appropriate interface or interfaces.

• You open a bean class in the Source Editor, and you add a finder method.

The compiler validates the code. Assuming that the method is valid, it is automatically added to the correct interface or interfaces.

• You open a bean class in the Source Editor, and you add a business method.

The compiler validates the code as far as is possible. However, it's possible that you might have intended your addition merely as a helper or utility method within the bean class, and therefore the method is not propagated to the remote or local interface.

• You add a business method with the correct exception to a bean's remote or local interface.

The method is automatically propagated to the bean class.

• You use the Source Editor to modify a create method in a bean's home (or local home) interface or a business method in a bean's remote (or local) interface.

The EJB Builder propagates your changes to the bean class.

• You modify the ejbCreateXxx method in the bean class.

The compiler validates the code as far as is possible, but does not propagate the change to the home or local home interface. (Relationships between Java interface classes are treated similarly throughout the IDE.)

• You modify a method in a bean's home interface. In the process, you make the method invalid by removing a required exception.

The compiler validates the code and provides error information, but does not propagate the change to the bean class.

• You enter a new create method in the bean class and give it a name other than ejbCreate or ejbCreateXxx. Or, you enter a new finder method in a home or local home interface and name it other than findByXxx. (Or, you modify such a method.)

The compiler verifies that the declaration is syntactically correct and that the return type and parameter types are valid Java classes that can be resolved.

---

Caution - Once you start working on a class in the Source Editor, your enterprise bean is not saved until you explicitly save it.

---

---

Understanding the IDE's Error Information

If you create code that is inconsistent with the J2EE specification, a warning badge or an error badge appears on a node's icon in the Explorer. To see a description of the problem, select the offending node, right-click, and choose Error Information or Validate EJB.

This yellow triangle warning badge on the logical node means that the bean or one of its classes might have a validation problem. Expand the logical node to see where the problem lies. For instance, a method defined in the remote interface might not be in the bean class, or a class might extend the wrong Java superclass. Even if you can compile the bean, it will encounter problems.

This red X error badge on the logical node means that the bean or one of its classes might have a severe problem. For instance, an entire class could be missing. A bean bearing this error badge will not execute or even allow interaction.

---

Compiling and Validating Enterprise Beans

The EJB Builder contains a custom compiler that validates your enterprise beans against the Enterprise JavaBeans Specification. You can decide whether to have compilation and validation done separately. However, when you select an enterprise bean node, right-click it, and choose Validate EJB, the default action is to compile the bean and then immediately validate it.

Notice that compilation alone does not catch all errors, and that if a bean has compilation errors, it is not validated.

Validation and compilation in the IDE serve different purposes. When you only compile an enterprise bean, the IDE compiles the various classes that constitute the bean. If these individual classes have Java code that is syntactically correct, the bean can compile without errors, even if one class is not consistent with another or with the J2EE specifications. To ensure consistency between the elements of an enterprise bean, you must also validate the bean.

The EJB Compiler conforms to the IDE's definitions of build, compile, and clean.

• If the bean is out of date (that is, the bean's deployment descriptor has been modified, or a directly referenced Java class has been modified since the last successful compilation), a compilation both compiles and validates the Java class according to the Enterprise JavaBeans Specification.
• A clean removes the directly referenced Java class files and the time stamp of the last EJB compilation.
• A build first performs a clean and then compiles the referenced classes.

In most cases, you can save considerable time by using the EJB Compiler with its default options during your iterative development cycle. However, under certain conditions (for example, if you must change a superclass after a successful compilation), compilation does not catch Java or EJB validation errors. In such cases, you might need to perform a build (possibly traversing several directories, depending on the location of all your bean's Java files) to detect or resolve compilation errors.

The compiler also does some semantic checking of the EJB QL in the select and finder methods of a CMP entity bean. Again, you can choose whether or not to have the compiler require EJB QL statements. Sometimes, you might find it convenient to turn off that requirement, so that you can develop, compile, and validate your enterprise bean without receiving error messages about missing EJB QL statements.

However, you must add the EJB QL (and turn the compiler's EJB QL requirement option back on) before you deploy the bean to the IDE's embedded application server, Sun ONE Application Server 7. This server and some others require EJB QL, which the server plugin converts to the SQL it needs in order to run queries in your finder and select methods.

To set compilation and validation options for your enterprise bean, do as follows:

1. From the main menu, choose Tools Options.

2. Expand the Options node, the Building node, and the Compiler Types node.

3. Select EJB 2.0 Compiler.

4. In the property sheet, make your selections.

The default setting for both fields is True. Change the setting in the following cases:

• Change the Require Compilation field to False if you want to be able to validate your bean in a separate step before you compile it.
• Change the Require EJB QL field to False if you want your bean to pass validation without EJB QL statements in its finder and select methods.

If you have chosen to separate validation from compilation, validate your bean as follows:

In the Explorer's Filesystems tab, select the bean's logical node, right-click, and choose Validate EJB.

Depending on the size of your bean, validation might take a few moments. When it's finished, an output window opens and displays messages about your bean.

When you compile an EJB module or do anything to a module that involves a compile (such as exporting an EJB JAR file, or calculating the class files for export), the module and all its component beans are validated automatically.

---

Saving Your Changes

In many cases, your work is saved automatically. However, this is not always true. For example, compiling a bean does not always save it. When you exit from the IDE, notice the confirmation dialog box and save the work you want to. For best results, use File Save All periodically while you work in the IDE.

---

Renaming an Enterprise Bean

When you rename a bean, you don't have to manually rename all the bean's related objects and their internal references. Use the IDE's GUI support as explained next, and the IDE synchronizes all interfaces automatically (both their external object names and related references within the source code). Do as follows:

1. Select the bean's logical node, right-click, and choose Rename.

The Rename dialog box appears. As soon as you begin typing into the New Name field, the checkbox options are activated.

2. Use the checkboxes to rename all the bean's related objects at once.

However, if you obtained one of your bean's objects from elsewhere, carefully consider whether or not you want to rename it. For example, if two or more entity beans share the same home and remote interfaces, you might want to keep similar interfaces named the same wherever they occur.

---

Caution - If you rename any one of the related objects independently, connections between the objects can be lost.

---

---

Modifying a Bean Based on Another Bean

An enterprise bean's class can be based on a class from another bean. For example, you can create an enterprise bean that uses another bean's remote interface. When you modify a class that is based on another class, you are actually modifying the original class. The more recent bean points to the earlier bean's class. You are not working with a separate copy of the class file. This is part of the IDE's design to promote easy reuse of enterprise bean elements.

---

Copying and Pasting an Enterprise Bean

When you copy and paste a bean into another package, the IDE creates a node in the new package that points to classes and interfaces in the original package. The IDE does not make the assumption that you want everything in one package; some organizations need to reuse bean elements more flexibly. Therefore, if you want an exact copy of one bean in another package, you must also ensure that the paths of all the bean's classes and interfaces are changed to the new package.

To copy and paste an enterprise bean from one package to another, do as follows:

1. In the Explorer's Filesystems tab, right-click the logical node of the bean you want to copy and choose Copy.

2. Right-click the package to which you want to copy the bean and choose Paste Copy.

3. Expand the Classes node under the original bean's logical node, right-click the node for a class or interface, and choose Copy. Then paste the class or interface into the destination package by right-clicking the destination package and choosing Paste Copy.

Repeat this step for each of the bean's classes and interfaces.

4. Right-click the logical node of the copied bean and choose Properties.

5. In the property sheet, update each class to point to the destination package. Find the following fields:

• bean class
• home interface (if any)
• remote interface (if any)
• local home interface (if any)
• local interface (if any)
• primary-key class (if any)

a. Click each field, then click the ellipsis (...) button.

b. In the property editor, navigate to the destination package, select the copy of the class or interface you pasted into the package, and click OK.

The property value changes to PackageName.classname.

When you're done, each class and interface property has the package name appended to the original name. The destination package contains a complete copy of the bean.

---

Exchanging Bean Classes or Interfaces

After you create an enterprise bean, you might need to change it to use an element from another bean, such as a home or remote interface. To do this, use the bean's property sheet as follows:

1. In the Explorer window, select the bean that needs a different class or interface, right-click, and choose Properties.

2. In the Properties tab, click the appropriate property (Bean Class, Home Interface, Primary Key Class, or Remote Interface), and click the ellipsis (...) button.

3. Navigate to the class or interface you want to use, select it, and click OK.

The property field shows the fully qualified path name of the new class or interface. Your bean does not contain a copy of the new element. It merely points to the original element.

---

Editing a Bean's Methods

When you have added a method using the GUI support available from the Explorer window, you can edit the method in the Source Editor. If all you need to do is complete the body of the method in the bean class, and your edits don't affect any other class or interface, you should use the Source Editor. However, for changes that might have a ripple effect on other classes, you might need to synchronize the changes in the bean's related objects. For examples, see Using the Source Editor to Edit Beans.

Or, you can simply use the Customizer dialog box as follows:

1. In the Explorer window, expand the logical node of the bean whose method you want to edit. Navigate to the method.

2. Select the method, right-click, and choose Customize.

The Customizer dialog box appears with the same fields as the New Method dialog box.

3. Edit the fields as needed. Click Close when you're done.

The IDE propagates your changes throughout the bean.

---

Viewing a Method

To see any method you have created for an enterprise bean, expand the bean's logical node and navigate to the sub-node for the kind of method you want to view. Right-click the method's node and choose Open. The Source Editor opens the class directly to the method code.

---

Changing an Entity Bean's Fields

Depending on whether your entity bean uses container-managed or bean-managed persistence, you use different methods to rename a field and to change a field's type.

Renaming a Field

In a CMP bean, use the GUI support available from the Explorer window. Do as follows:

1. Expand the bean's logical node and select the CMP field. Right-click, and choose Rename.

2. Use the checkboxes to specify the extent of your change.

In a BMP bean, use the Source Editor to rename a persistent or a nonpersistent field.

Changing the Type of a Field

In a CMP bean, use the Explorer's GUI support. Change a field's type as follows:

1. Expand the bean's logical node and select the CMP field. Right-click, and choose Customize.

2. In the Customizer dialog box, select another type.

In a BMP bean, use the Source Editor to change the type of a persistent or a nonpersistent field.

---

Deleting an Enterprise Bean

Regardless of the type of enterprise bean, delete a bean only as follows:

1. Select the bean's logical node, right-click, and choose Delete.

The Confirm EJB Deletion dialog box appears.

2. Use the checkboxes to confirm that you want to delete all the bean's related objects at once.

If one of your bean's related objects is used elsewhere, carefully consider whether or not you want to delete it. For example, if several entity beans use the same primary-key class, you should deselect its checkbox before deleting the rest of the bean's classes.

---

Caution - Don't choose Edit Delete from the menu bar when deleting beans; the IDE simply deletes the selected class without trying to synchronize your bean's constituent classes.

---