Migrating and Upgrading EJB 1.1 Enterprise Beans

If you want to use enterprise beans that were built according to the Enterprise JavaBeans Specification version 1.1 (EJB 1.1), you can use the Sun ONE Studio 5 IDE to migrate your beans to the currently supported version (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 Recent Releases

Some of the differences between recent and older versions of the EJB specification 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 IDE, the bean is automatically converted 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. 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.)

• Old CMP entity beans are mainly OK to use in development, but update them before deployment. When you're ready to deploy a CMP 1.x entity bean to Sun ONE Application Server 7, you must make a few changes by hand in the query-language statements for any finder and selector methods. See Understanding the Application Server's Generated SQL for some discussion, and the application server's documentation 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 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 in the EJB 1.1 environment.

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 Chapter 4 to create a new CMP entity bean.

On the last page 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 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 in the EJB 1.1 environment, 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 window 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 IDE. If possible, you should recreate your old enterprise beans using the 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 sheets can be used to modify these enterprise beans.

---