Migrating and Upgrading EJB 1.1 Enterprise Beans

If you used the previous version of the Sun ONE Studio IDE to build enterprise beans, that is, if your enterprise beans were built according to the Enterprise JavaBeans Specification version 1.1 (EJB 1.1), you can migrate your beans to the current version of the IDE and to Enterprise JavaBeans Specification version 2.0 (EJB 2.0). Depending on the type of EJB 1.1 enterprise bean and what you want to do with it, the bean might be converted automatically by the IDE. Or, you might have to make some manual changes, which are described in this appendix.

---

Understanding Updates in the Current Release

Some of the differences between the current and previous IDE release involve container-managed persistent (CMP) entity beans, their properties, and the validation of enterprise beans in general. Notice the following points.

• Most bean conversions are automatic. In most cases, when you import an EJB 1.1 enterprise bean into the current version of the IDE, the IDE automatically converts it to an EJB 2.0 enterprise bean. However, CMP entity beans created in the EJB 1.1 environment are a special case.

You can easily identify these beans by their version tag, a feature that was added in the current IDE. In the property sheets for a CMP entity bean, in the CMP Version field, you see that a bean created in the current IDE has the value 2.x, while the older CMP entity bean has the value 1.x. (We'll refer to the older type of bean as a CMP 1.x entity bean.)

• EJB validation now catches more. In the current release of the IDE, validation has been tightened up. You might find that this upgraded feature points out failures in Java code that seemed to succeed in the previous release. An example is the transient modifier, described next.

Use EJB Validate (from the contextual menu on the enterprise bean in the IDE's Explorer) or Build All (from the contextual menu on the package) to see whether an application containing that bean can be deployed in the current version of the IDE. If validation uncovers errors in your code, see the following sections.

Once the bean is validated successfully, assemble it into a module and an application, and try to deploy it. If deployment fails, check to see whether changes in the bean's property sheets could be causing the problem.

• Get rid of transient in session beans. The previous version of the IDE seemed to allow the use of the transient modifier, but validation in this version catches it and issues an error message. See Avoiding the transient Modifier for instructions on finding and changing the modifier.
• Old CMP entity beans are mainly OK to use in development, but update them before deployment. If you have changed the bean's transient modifier, you shouldn't experience any problems using CMP 1.x entity beans in your development work with the current IDE. However, when you're ready to deploy a CMP 1.x entity bean in this IDE, you must make a few changes by hand, as follows:
• Shift certain bean properties to the EJB module for RI deployment. A significant change in the current release is the way data source references are declared for CMP entity beans that are deployed to the J2EE reference-implementation application server (RI). The RI-related properties for such a bean must now be set in the EJB module. For details, see Shifting a Bean's RI Properties to the EJB Module Level.
• Edit generated SQL for RI deployment. If you're deploying a CMP 1.x entity bean to the RI, you must edit one of the SQL statements that the RI plugin generates. Specifically, you must edit the WHERE clause in the SELECT statement of the finder method. See If Your EJB Module Contains an EJB 1.1 CMP Entity Bean for details.

When you have made these changes, the CMP entity bean still has the CMP Version value 1.x; it hasn't been converted to a CMP 2.x entity bean. However, the bean and its existing interfaces should operate and deploy without problems in the current IDE, assuming you're deploying the beans to an application server that complies with EJB 2.0.

• Convert old CMP entity beans before adding new features. You can't add new EJB 2.0 features such as local interfaces to a CMP 1.x entity bean. If you need new features in an old bean, you must first convert the bean manually to the CMP 2.x level. These instructions are given in Converting a CMP 1.x Entity Bean.

---

Making Specific Changes

In the sections that follow are instructions for updating enterprise beans that were created using the previous version of the IDE.

Converting a CMP 1.x Entity Bean

Sometimes you can't recreate a CMP 1.x entity bean from scratch, but you want the bean to be able to use new EJB 2.0 features such as local interfaces, local references, select and home methods. In this case, you will probably need to manually upgrade the bean. Convert it to a CMP 2.x bean as follows:

1. In the Explorer window, create a new Java package.

2. Copy the Java files from the CMP 1.x entity bean's old package. Paste them into the new package (as copies, not as links).

3. Use the EJB Builder Wizard as discussed in to create a new CMP entity bean.

On the last pane of the wizard, specify the copied classes as the bean's remote and home interfaces. Also specify the bean class and primary-key class.

For the moment, ignore the IDE's warning that no CMP (persistent) fields have been found.

4. Add fields as needed and make other edits to correct EJB Validation errors.

When you import any other kind of EJB 1.1 enterprise bean into the current version of the IDE, the bean is automatically updated to conform to EJB 2.0.

Avoiding the Use of New Features in an Old Bean

If you try to use new features in an enterprise bean that was created using the previous version of the IDE, the results cannot be predicted. Two examples follow.

Don't Add Local Interfaces to a CMP 1.x Entity Bean

When you use the product as intended, EJB 1.1 beans have a different contextual menu (the menu that appears in the Explorer window when you right-click the bean's logical node), and the menu options are limited. However, if you choose Customize from the contextual menu, you see a window that seems to allow a local home and a local interface file.

These fields are not editable directly, and the file paths of the local interface do not appear on the property sheet of an EJB 1.1 CMP entity bean.

---

Caution - Do not add local interfaces in this way. If you do, you will not be able to remove the interfaces again. The CMP entity bean will become invalid and cannot be repaired.

---

Don't Add Local EJB References, Either

The same caveat applies to local EJB references. They cannot be added to a CMP 1.x entity bean, even though the Customizer window might appear to allow it. If you have done so, you can go to the Customizer dialog box and delete the references you added.

The EJB 2.0 standard is quite large, and its new coding practices are strongly encouraged or enforced by the current version of the IDE. If possible, you should recreate your old enterprise beans using the current IDE's EJB Builder Wizard. Carefully evaluate your code and upgrade it where necessary to conform to the current EJB standard.

---

Note - You can add local interfaces and local EJB references, if needed, to another type of EJB 1.1 enterprise bean, because the IDE converts those beans automatically to conform to the current EJB standard. Either the Customizer dialog box or the property sheet can be used to modify these enterprise beans.

---

Changing the PointBase User Name and Password

The default database user ID and password for the PointBase database have changed from public to pbpublic. All property sheets must be modified to reflect the change. Remember to press the Enter or Return key after typing the password.

Avoiding the transient Modifier

The previous version of the IDE seemed to allow statements of this form in session beans:

public class HelloBean implements javax.ejb.SessionBean { private transient SessionContext context; 

In the previous version, validation did not catch the use of the transient modifier. In the current version, validation catches and disallows that modifier.

A simple EJB Validate command on an EJB 1.1 session bean might not catch the use of this modifier. To be sure your bean is validated completely, do the following:

1. In the Explorer window, select the bean.

2. In the main menu, choose Build Build.

The IDE builds all the bean's Java classes and performs a validation check. The Compiler output window shows the result of the build, including any error messages.

If the transient modifier is present in your session bean, you see an error when building the bean or when a client executes against the bean. To correct the problem, remove the word transient from the EJB Bean class, and then validate or build the bean again. If validation or building is successful, deploy the bean and run the client again.

Version 2.0 of the Enterprise JavaBeans Specification says:

The Bean Provider must assume that the content of transient fields may be lost between the ejbPassivate and ejbActivate notifications. Therefore, the Bean Provider should not store in a transient field a reference to any of the following objects: SessionContext object; environment JNDI naming context or any its subcontexts; home and remote interfaces; or the UserTransaction interface.

Shifting a Bean's RI Properties to the EJB Module Level

For any CMP entity bean that is deployed to the RI, you must move its RI-related properties from the bean level to the level of the EJB module.

The property sheets for enterprise beans have changed slightly. When one enterprise bean calls another, a reference is set on the calling bean. Two changes must be made so that this type of application can execute. If these changes are not made, you might see a Cannot save deployment error. This type of error is probably due to database-related information being in the wrong property sheets of a CMP entity bean. To correct the problem, do as follows:

1. In the Explorer window, right-click the bean's EJB module node and choose Properties.

2. Go to the J2EE RI tabbed interface of the Properties window.

Three properties that were on the bean's J2EE RI property sheet in the previous version of the IDE now appear here. They represent the database connection that the CMP entity bean will use.

3. Specify each property for the database.

If you're using the PointBase database, type the following values:

• In the Datasource JNDI Name field: jdbc/Pointbase (the JNDI name that exists in the application server. Type Pointbase with only an initial capital)
• In the Datasource Password field: pbpublic (the new password default. Press the Enter or Return key after typing the password)
• In the Datasource User Name field: pbpublic (the new user-name default)

Changing CMP Entity Bean Properties Before Testing the Bean

In the previous release of the IDE, if a CMP enterprise bean had the correct information for database connection, then the test application that was generated for the bean could be deployed to the RI with no further changes.

In the current release, you don't have to make any changes in the EJB test application for session beans or bean-managed persistent (BMP) entity beans.

However, for CMP entity beans that you intend to deploy to the RI and test against PointBase, a change is required. As mentioned earlier, the properties for the Data Source JNDI Name, user ID, and password have been moved from the enterprise bean level to the EJB module level, the PointBase default user ID and password have changed, and the JNDI name on an EJB reference's J2EE RI tabbed interface has only one property. A CMP bean's property sheet is not updated automatically.

To change these properties, do as follows:

1. In the Explorer window, right-click the node for the EJB module that the testing feature generated. Choose Properties.

2. In the property sheet, click the J2EE RI tab.

3. In the J2EE RI tabbed interface, update the three data source fields as explained in Shifting a Bean's RI Properties to the EJB Module Level.

If you try to deploy your application before setting those properties, you get an error message, with the details of the error in the Deploying Application tab of the Output Window.