# Using CMP2.0 persistence

This document highlights the main differences that occur when using CMP as defined in EJB 2.0 specification (called CMP2.0) compared to CMP as defined in EJB 1.1 specification (called CMP1.1). The main new features in the standard development and deployment of CMP2.0 entity beans are listed (and compared to CMP1.1 way of doing), as well as the JOnAS specific stuff.

The content of this guide is the following:

1. Standard CMP2.0 aspects
   1. Entity Bean Implementation Class
   2. Standard Deployment Descriptor
2. JOnAS specific aspects
   1. Database mappers
   2. JOnAS specific Deployment Descriptor

## Standard CMP2.0 aspects

This section briefly lists the new features available in CMP2.0 compared to CMP 1.1, and how it modifies the way to develop entity beans.

### Entity Bean Implementation Class

The EJB implementation class implements the bean's business methods of the component interface, the methods dedicated to the EJB environment (the interface of which are explicitely defined in the EJB specification) and defines the abstract methods representing both the persistent fields (cmp-fields) and the relationship fields (cmr-fields). The class must implement the `javax.ejb.EntityBean` interface, must be defined as public, and must be abstract (which is not the case for CMP1.1, where it must not be abstract). The abstract methods are the get and set accessor methods of the bean cmp and cmr fields. See example and details in section Developing Entity Beans of the JOnAS documentation.

### Standard Deployment Descriptor

First of all, the standard way to indicate to an EJB platform that an entity bean has container-managed persistence is to fill the `<persistence-type>` tag of the deployment descriptor with the value "container" and to fill the `<cmp-field>` tags of the deployment descriptor with the list of container-managed fields (the fields that the container will have in charge to make persistent) and the `<cmr-field>` tags identifying the relationships. The CMP version (1.x or 2.x) should also be specified in the <cmp-version> tag. In the textual format of the deployment descriptor, this is represented by the following lines:

        <persistence-type>container</persistence-type>
        <cmp-version>1.x</cmp-version>
        <cmp-field>
          <field-name>fieldOne</field-name>
        </cmp-field>
        <cmp-field>
          <field-name>fieldTwo</field-name>
        </cmp-field>

Note that for running your CMP1.1 defined entity beans upon an EJB2.0 platform, such as JOnAS 3.x, you must introduce this <cmp-version> element in your deployment descriptors, since the default cmp-version value (if not specified) is 2.x.

It has to be noted that for CMP 2.0, the information defining the behaviour of the implementation of a find<method> method is located in the standard deployment descriptor, as an EJB-QL query, i.e. this is not a jonas specific information. With CMP 1.1, this information is located in the jonas specific deployment descriptor, as a SQL WHERE clause specified in a <finder-method-jdbc-mapping> element.

Finder method example in CMP 2.0: for a `findLargeAccounts(double val)` method defined on the Account entity bean of the JOnAS eb example.

          <query>
            <query-method>
              <method-name>findLargeAccounts</method-name>
              <method-params>
                  <method-param>double</method-param>
              </method-params>
            </query-method>
            <ejb-ql>SELECT OBJECT(o) FROM accountsample o WHERE o.balance &gt; ?1</ejb-ql>
          </query>

## JOnAS specific aspects

### Database mappers

For implementing the EJB 2.0 persistence (CMP2.0), JOnAS relies on the JORM framework. JORM itself relies on JOnAS DataSources (specified in DataSource properties files) for connecting to the actual database. JORM must adapt its object-relational mapping to the underlying database, and makes use of adapters called "mappers" for this purpose. So for each kind of database (and more precisely for each JDBC driver), the corresponding mapper must be specified in the DataSource. This is the purpose of the datasource.mapper property of the DataSource properties file. Note that all JOnAS provided DataSource properties files (in JOnAS_ROOT/conf) already contain this property with the right mapper.

property name | description | possible values
--- | --- | ---
datasource.mapper | JORM database mapper | rdb: generic mapper (JDBC standard driver ...) rdb.postgres: mapper for PostgreSQL rdb.oracle: mapper for Oracle rdb.mckoi: mapper for McKoi Db rdb.mysql: mapper for MySQL

If you are using other databases and need a mapper, just contact the JOnAS team.

The container code generated at deployment (GenIC or ejbjar ant task) is dependent of this mapper. It is thus possible to deploy (generate container code) a bean for several mappers, in case you would like to change the database (i.e. the DataSource file) without redeploying the bean. These mappers should be specified as the mappernames argument of the GenIC command, or as the mappernames attribute of the JOnAS ANT ejbjar task, the value is a comma separated list of mapper names, for which the container classes will be generated. This list of mappers corresponds to the list of potential databases upon which you will be able to deploy your entity beans. E.g. for deploying your entity beans in order that they may be used on either Oracle or PostgreSQL, you will run GenIC as:

             GenIC -mappernames rdb.oracle,rdb.postgres eb.jar

The same example in a ANT build.xml file:

      <target name="deploy"
              description="Build and deploy the ejb-jars"
              depends="compile>
        <ejbjar naming="directory"
            ....
            ....
          <jonas destdir="${ejbjars.dir}"
                 jonasroot="${jonas.root}"
                 orb="${orb}"
                 jarsuffix=".jar"
                 secpropag="yes"
                 keepgenerated="true"
                 mappernames="${mapper.names}"
                 additionalargs="${genicargs}">
          </jonas>
          ...
          ...
        </ejbjar>
      </target>

having in build.properties:

    # mappers for entity CMP2
    mapper.names            rdb.oracle,rdb.postgres

### JOnAS specific Deployment Descriptor

The mapping of the CMP2.0 persistent schema to the relational database schema is entirely generated, and currently no control over it is provided to the deployer. Therefore, the JOnAS specific deployment descriptor is almost empty. The relational tables definitions are generated from the "abstract schema names", the cmp-field names and cmr-field names.

For a CMP 2.0 entity bean, only the `jndi-name` element of the `jdbc-mapping` is necessary, since the mapping is implicit. This is the JNDI name of the DataSource representing the database storing the entity bean.

        <jdbc-mapping>
          <jndi-name>jdbc_1</jndi-name>
        </jdbc-mapping>

For a CMP 2.0 entity bean, the jonas specific deployment descriptor contains an additional element, `cleanup`, at the same level as the `jdbc-mapping` element, which may have one of the following value:

`removedata`
  at bean loading time, the content of the tables storing the bean data is deleted
`removeall`
  at bean loading time, the tables storing the bean data are dropped (if they exist) and created
`none`
  do nothing
`create`
  default value (if the element is not specified), at bean loading time, the tables for storing the bean data are created if they do not exist

So if you want the database data to be deleted each time you load your bean, which may be useful for testing purpose, the part of the JOnAS specific deployment descriptor related to your entity bean may look like:

        <jdbc-mapping>
          <jndi-name>jdbc_1</jndi-name>
        </jdbc-mapping>
        <cleanup>removedata</cleanup>