Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Upgrade and Migration Guide

- Previous: Migrating EJB Client Applications
- Next: Chapter 6 Migrating from Application Server 6.x/7.x to Application Server 8.1

# Migrating CMP Entity EJBs

This section describes the steps to migrate your application components from the EJB 1.1 architecture to the EJB 2.0 architecture.

In order to migrate a CMP 1.1 bean to CMP 2.0, we first need to verify if a particular bean can be migrated. The steps to perform this verification are as follows.

## To Verify if a Bean Can be Migrated

##### Steps

1. From the `ejb-jar.xml` file, go to the `<cmp-fields>` names and check if the optional tag `<prim-key-field>` is present in the `ejb-jar.xml file` and has an indicated value. If it does, go to next step.

   Look for the `<prim-key-class>` field name in the `ejb-jar.xml`, get the class name and get the `public instance variables` declared in the class. Now see if the signature (name and case) of these variables matches with the `<cmp-field>` names above. Segregate the ones that are found. In these segregated fields, check if some of them start with an upper case letter. If any of them do, then migration cannot be performed.

2. Look into the bean class source code and obtain the java types of all the `<cmp-field>` variables.

3. Change all the `<cmp-field>` names to lowercase and construct accessors from them. For example if the original field name is `Name` and its java type is `String`, the accessor method signature will be:

   `Public void setName(String name)Public String getName()`

4. Compare these accessor method signatures with the method signatures in the bean class. If there is an exact match found, migration is not possible.

5. Get the custom finder methods signatures and their corresponding SQLs. Check if there is a ”Join’ or ”Outer join’ or an ”OrderBy’ in the SQL, if yes, we cannot migrate, as EJB QL does not support ”joins’, ”Outer join’ and ”OrderBy’.

6. Any CMP 1.1 finder, which used `java.util.Enumeration,` must now use `java.util.Collection`. Change your code to reflect this. CMP2.0 finders cannot return j`ava.util.Enumeration`.

   Migrating the Bean Class explains how to perform the actual migration process.

## Migrating the Bean Class

This section describes the steps required to migrate the bean class to Sun Java System Application Server 8.1.

### To Migrate the Bean Class

##### Steps

1. Prepend the bean class declaration with the keyword `abstract`.

   For example if the bean class declaration was:

       public class CabinBean implements EntityBean

   change it to:

       abstract public class CabinBean implements EntityBean

2. Prefix the accessors with the keyword `abstract`.

3. Insert all the accessors after modification into the source(.java) file of the bean class at class level.

4. Comment out all the `cmp` fields in the source file of the bean class.

5. Construct protected instance variable declarations from the `cmp-field` names in lowercase and insert them at the class level.

6. Read up all the `ejbCreate()` method bodies (there could be more than one `ejbCreate`).

   Look for the pattern ”`<cmp-field>=`some value or local variable’, and replace it with the expression ”abstract mutator method name (same value or local variable)’.

   For example, if the `ejbCreate` body before migration is:

       public MyPK ejbCreate(int id, String name) {
          this.id = 10*id;
          Name = name;   //1
          return null;
       }

   Change it to:

       public MyPK ejbCreate(int id, String name) {
          setId(10*id);
          setName(name);   //1
          return null;
       }

   Note that the method signature of the abstract accessor in `//1` is as per the Camel Case convention mandated by the EJB 2.0 specification. Also, the keyword ”this’ may or may not be present in the original source, but it must be removed from the modified source file.

7. Initialize all the protected variables declared in the `ejbPostCreate()`methods in step 5.

   The protected variables will be equal in number with the `ejbCreate()` methods. This initialization will be done by inserting the initialization code in the following manner:

       protected String name;  //from step 5
       protected int id;  //from step 5
       public void ejbPostCreate(int id, String name) {
          name = getName();    /*abstract accessor*/ //inserted in this step
          id  = getId();        /*abstract accessor*/ //inserted in this step
       }

8. Inside the `ejbLoad` method, set the protected variables to the beans’ database state.

   To do so, insert the following lines of code:

       public void ejbLoad() {
          name = getName();    // inserted in this step
          id = getId();        // inserted in this step
          ...                  // existing code
       }

9. Similarly, update the beans’ state inside `ejbStore()`so that its database state gets updated.

   But remember, you are not allowed to update the setters that correspond to the primary key outside the `ejbCreate()`, so do not include them inside this method. Insert the following lines of code:

       public void ejbStore() {
           setName(name);       //inserted in this step
           setId(id);           //Do not insert this if
                                //it is a part of the
                                //primary key.
           ...                  //already present code
       }

10. Replace all occurrences of any `<cmp-field>` variable names with the equivalent protected variable name (as declared in step 5).

    If you do not migrate the bean, at the minimum you need to insert the `<cmp-version>1.`x`</cmp-version>` tag inside the `ejb-jar.xml` file at the appropriate place, so that the unmigrated bean still works on Sun Java System Application Server 8.1.

## Migration of ejb-jar.xml

To migrate the file `ejb-jar.xml` to Sun Java System Application Server 8.1, perform the following steps:

### To Migrate the EJB Deployment Descriptor

To migrate the EJB deployment descriptor file, `ejb-jar.xml`, edit the file and make the following changes.

##### Steps

1. Convert all `<cmp-fields>` to lowercase.

2. Insert the tag `<abstract-schema-name>` after the `<reentrant>` tag.

   The schema name will be the name of the bean as in the `< ejb-name>` tag, prefixed with “ias_”.

3. Insert the following tags after the `<primkey-field>` tag:

       <security-identity>
          <use-caller-identity/>
       </security-identity>

4. Use the SQL obtained above to construct the EJB QL from SQL.

5. Insert the `<query>` tag and all its nested child tags with all the required information just after the `<security-identity>` tag.

## Custom Finder Methods

The custom finder methods are the `findBy`... methods (other than the default `findByPrimaryKey` method), which can be defined in the home interface of an entity bean. Since the EJB 1.1 specification does not stipulate a standard for defining the logic of these finder methods, EJB server vendors are free to choose their implementations. As a result, the procedures used to define the methods vary considerably between the different implementations chosen by vendors.

Sun ONE Application Server 6.x uses standard SQL to specify the finder logic.

Information concerning the definition of this finder method is stored in the enterprise bean’s persistence descriptor (`Account-ias-cmp.xml)` as follows:

    <bean-property>
      <property>
        <name>findOrderedAccountsForCustomerSQL</name>
        <type>java.lang.String</type>
        <value>
           SELECT BRANCH_CODE,ACC_NO FROM ACCOUNT where CUST_NO = ?
        </value>
        <delimiter>,</delimiter>
      </property>
    </bean-property>
    <bean-property>
      <property>
        <name>findOrderedAccountsForCustomerParms</name>
        <type>java.lang.Vector</type>
        <value>CustNo</value>
        <delimiter>,</delimiter>
      </property>
    </bean-property>

Each `findXXX` finder method therefore has two corresponding entries in the deployment descriptor (SQL code for the query, and the associated parameters).

In Sun Java System Application Server 8.1 the custom finder method logic is also declarative, but is based on the EJB query language EJB QL.

The EJB-QL language cannot be used on its own. It has to be specified inside the file `ejb-jar.xml`, in the `<ejb-ql>` tag. This tag is inside the `<query>` tag, which defines a query (finder or select method) inside an EJB. The EJB container can transform each query into the implementation of the finder or select method. Here’s an example of an `<ejb-ql>` tag:

    <ejb-jar>
      <enterprise-beans>
        <entity>
          <ejb-name>hotelEJB</ejb-name>
          ...
          <abstract-schema-name>TMBankSchemaName</abstract-schema-name>
          <cmp-field>
          ...
          <query>
            <query-method>
              <method-name>findByCity</method-name>
                <method-params>
                  <method-param>java.lang.String</method-param>
                </method-params>
            </query-method>
            <ejb-ql>
              <![CDATA[SELECT OBJECT(t) FROM TMBankSchemaName AS t
                                             WHERE t.city = ?1]]>
            </ejb-ql>
          </query>
        </entity>
        ...
      </enterprise-beans> ...
    </ejb-jar>

- Previous: Migrating EJB Client Applications
- Next: Chapter 6 Migrating from Application Server 6.x/7.x to Application Server 8.1

- © 2010, Oracle Corporation and/or its affiliates