CMP2.x - new features available - shake out phase

[Gianny Damour <gi...@optusnet.com.au>]

Hi,

We have recently hooked in what we believe is sufficient enough to give 
a fair try to petstore1.3.1_02.

The new capabilities are (Dain, thanks for having logged these issues):
* GERONIMO-177 - Support for user defined primary key classes: nothing 
very special in here; it is now possible to specify a compound primary 
key, which may be mapped to multiple CMP fields. </jira/browse/GERONIMO-177>

* GERONIMO-179 - Support for CMRs </jira/browse/GERONIMO-179>: OTO, OTM 
and MTM container managed relationships are enabled.

* GERONIMO-176 - CMP table mapping support </jira/browse/GERONIMO-176>: 
it is the capability to map the CMP and CMR fields of an EntityBean  to 
a database. There are a couple of examples for each (primary key type, 
relationship multiplicity) couple in here:
openejb\modules\core\src\test-cmp

* GERONIMO- 377 - Unknown primary key support: this is used to support 
the deployment of EntityBean having an unknown primary key class. By 
now, no test-cases have been committed. Having said that, here is an 
explanation of how to use it:

EntityBeans having an unknown primary key class, i.e. java.lang.Object, 
must declare a <automatic-key-generation> element. This latter specifies 
the name of a primary key generator along with the class type returned 
by this same generator. A primary key generator can return either simple 
or compound primary keys. In the former case, a <primkey-field> needs to 
be specified along with the <automatic-key-generation>. In the latter 
case, no <primkey-field> must be specified.

"Virtual" CMP fields are to be defined in order to store the 
auto-generated primary keys. One does via the standard 
<cmp-field-mapping> element; though, one must also declare the class 
type of such "virtual" CMP fields via the <cmp-field-class> element.

As of this writing, two primary key generators are supported:
- sequence, store procedure or more generaly any SQL statement returning 
a unique identifier: this is the GBean 
org.openejb.entity.cmp.pkgenerator.SQLPrimaryKeyGeneratorWrapper; and
- sequence table, where a sequence is simulated via a table: this is the 
GBean 
org.openejb.entity.cmp.pkgenerator.SequenceTablePrimaryKeyGeneratorWrapper.

Example of unknown primary key definition - to be specified in 
openejb-jar.xml:

       <entity>
           <ejb-name>ProfileEJB</ejb-name>   // ProfileEJB has an 
unknown primary key as per ejb-jar.xml.
           <table-name>ProfileEJBTable</table-name>
               <cmp-field-mapping>
                   <cmp-field-name>id</cmp-field-name>   // id is not 
defined in ejb-jar.xml; this is a "virtual" CMP field.
                   <cmp-field-class>java.lang.Integer</cmp-field-class>  
// one must specify the class type "virtual" CMP fields.
                   <table-column>id</table-column>
               </cmp-field-mapping>
              ...
              <primkey-field>id</primkey-field>  // defines the 
"virtual" CMP field storing the auto-generated identity.
             <automatic-key-generation>
                 
<generator-name>geronimo.server:role=CMPPKGenerator,name=IntegerGenerator</generator-name> 
// reference a primary key generators
                 <primary-key-class>java.lang.Integer</primary-key-class>
              </automatic-key-generation>
       <entity>

    // this is the declaration of the primary key generator used by 
ProfileEJB.
    <gbean 
name="geronimo.server:role=CMPPKGenerator,name=IntegerGenerator" 
class="org.openejb.entity.cmp.pkgenerator.SequenceTablePrimaryKeyGeneratorWrapper">
        <reference 
name="ManagedConnectionFactoryWrapper">geronimo.server:J2EEServer=geronimo,j2eeType=JCAManagedConnectionFactory,name=MySQL</reference>
    <attribute name="tableName" 
type="java.lang.String">SEQUENCE_TABLE</attribute>
    <attribute name="sequenceName" 
type="java.lang.String">SEQUENCE_NAME</attribute>
    <attribute name="batchSize" type="int">10</attribute>
     </gbean>

For sure, there are some bugs and it will take a couple of weeks to 
identify and fix them. So, if you want to trial these new features with 
your home-grown CMP2.x EntityBean and help in this shake out process, 
then that would be awesome.

Thanks,
Gianny