<?xml version="1.0" encoding="UTF-8"?>

<section version="5.0" 
         xmlns="http://docbook.org/ns/docbook" 
         xmlns:xlink="http://www.w3.org/1999/xlink" 
         xmlns:xi="http://www.w3.org/2001/XInclude" 
         xmlns:svg="http://www.w3.org/2000/svg" 
         xmlns:mml="http://www.w3.org/1998/Math/MathML" 
         xmlns:html="http://www.w3.org/1999/xhtml" 
         xmlns:db="http://docbook.org/ns/docbook" 
         xml:lang="en" 
         xml:id="ejb.cmp2">
  <info><title>Using the CMP 2 Persistence in Entity Beans</title></info>
  
  <para>
      This section highlights the main differences between CMP as defined in EJB 2.0 specification (called CMP2.0) and CMP as defined in EJB 1.1 specification (called CMP1.1). Major new features in the standard development and deployment of CMP2.0 entity beans are listed (comparing them to CMP1.1), along with JOnAS-specific information. Mapping CMP2.0 entity beans to the database is described in detail. Note that the database mapping can be created entirely by JOnAS, in which case the JOnAS-specific deployment descriptor for an entity bean should contain only the datasource and the element indicating how the database should be initialized.
  </para>
  <section xml:id="cmp2.std">
    <info><title>Standard CMP2.0 Aspects</title></info>
      
    <para>
        This section briefly describes the new features available in CMP2.0 as compared to CMP 1.1, and how these features change the development of entity beans.
    </para>
    <section xml:id="cmp2.std.impl">
      <info><title>Entity Bean Implementation Class</title></info>
        
      <para>
          The EJB implementation class 1) implements the bean's business methods of the component interface, 2) implements the methods dedicated to the EJB environment (the interface of which is explicitly defined in the EJB specification), and 3) defines the abstract methods representing both the persistent fields (cmp-fields) and the relationship fields (cmr-fields). The class must implement the 
          <literal>
            javax.ejb.EntityBean
          </literal>
           interface, be defined as public, and 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. Refer to the examples and details in the section "
          <link xlink:href="ejb2_programmer_guide.html#ejb2.entity.desc">
            Developing Entity Beans
          </link>
          " of the JOnAS documentation.
      </para>
    </section>
    <section xml:id="cmp2.stddd">
      <info><title>Standard Deployment Descriptor</title></info>
        
      <para>
          The standard way to indicate to an EJB platform that an entity bean has container-managed persistence is to fill the 
          <literal>
            &lt;persistence-type&gt;
          </literal>
           tag of the deployment descriptor with the value "container," and to fill the 
          <literal>
            &lt;cmp-field&gt;
          </literal>
           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 
          <literal>
            &lt;cmr-field&gt;
          </literal>
           tags identifying the relationships. The CMP version (1.x or 2.x) should also be specified in the &lt;cmp-version&gt; tag. This is represented by the following lines in the deployment descriptor:
      </para>
      <screen>
    &lt;persistence-type&gt;container&lt;/persistence-type&gt;
    &lt;cmp-version&gt;1.x&lt;/cmp-version&gt;
    &lt;cmp-field&gt;
      &lt;field-name&gt;fieldOne&lt;/field-name&gt;
    &lt;/cmp-field&gt;
    &lt;cmp-field&gt;
      &lt;field-name&gt;fieldTwo&lt;/field-name&gt;
    &lt;/cmp-field&gt;</screen>
      <para>
          Note that for running CMP1.1-defined entity beans on an EJB2.0 platform, such as JOnAS 3.x, 
          you must introduce this
           &lt;cmp-version&gt; 
          element in your deployment descriptors, since the default cmp-version value (if not specified) is 2.x
          .
      </para>
      <para>
          Note that for CMP 2.0, the information defining the behaviour of the implementation of a 
          find&lt;method&gt;
           method is located in 
          the standard deployment descriptor
           as an EJB-QL query (this is not a JOnAS-specific information). For CMP 1.1, this information is located in the JOnAS-specific deployment descriptor as an SQL WHERE clause specified in a &lt;finder-method-jdbc-mapping&gt; element.
      </para>
      <para>
          Finder method example in CMP 2.0: for a 
          <literal>
            findLargeAccounts(double val)
          </literal>
           method defined on the Account entity bean of the JOnAS eb example.
      </para>
      <screen>
      &lt;query&gt;
        &lt;query-method&gt;
          &lt;method-name&gt;findLargeAccounts&lt;/method-name&gt;
          &lt;method-params&gt;
              &lt;method-param&gt;double&lt;/method-param&gt;
          &lt;/method-params&gt;
        &lt;/query-method&gt;
        &lt;ejb-ql&gt;SELECT OBJECT(o) FROM accountsample o WHERE o.balance &amp;gt; ?1&lt;/ejb-ql&gt;
      &lt;/query&gt;</screen>
    </section>
  </section>
  <section xml:id="cmp2.ejbql">
    <info><title>JOnAS EJBQL extension</title></info>
      
    <section xml:id="cmp2.ejbql.limit">
      <info><title>LIMIT clause</title></info>
        
      <para>
          The 
          LIMIT
           feature has been added to the standard EJBQL query language. This feature enables you to retrieve just a portion of the results generated by the rest of a query.
      </para>
      <para>
          The syntax of the 
          LIMIT
           clause is:
      </para>
      <screen>

    limit_clause ::= LIMIT limit_expression (, limit_expression )?
    limit_expression ::= integer_literal | input_parameter
      </screen>
      <para>
          The first 
          limit_expression
           corresponds to the 
          start_at
           range and the second one to the 
          size
           range.
      </para>
      <para>
          The 
          limit_clause
           is the last clause of the query:
      </para>
      <screen>

    ejbql ::= select_clause from_clause [where_clause] [orderby_clause] [limit_clause]
      </screen>
      <para>
          Example:
      </para>
      <screen>

    SELECT OBJECT(c) FROM jt2_Customer AS c ORDER BY c.id LIMIT ?1, 20
      </screen>
      <para>
          Note that this feature is currently not implemented on all the database types supported by JORM/MEDOR.
      </para>
    </section>
  </section>
  <section xml:id="cmp2.mapper">
    <info><title>JOnAS Database mappers</title></info>
      
    <para>
        For implementing the EJB 2.0 persistence (CMP2.0), JOnAS relies on the 
        <link xlink:href="http://www.objectweb.org/jorm/index.html">
          JORM
        </link>
         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, for which it makes use of adapters called "mappers." Thus, for each type 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 correct mapper.
    </para>
    <informaltable>
        <tgroup cols="3">
          <thead>
            <row>
              <entry>
                property name
              </entry>
              <entry>
                description
              </entry>
              <entry>
                possible values
              </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>
                datasource.mapper
              </entry>
              <entry>
                JORM database mapper
              </entry>
              <entry>
                <variablelist>
                  <varlistentry>
                    <term>
                      rdb
                    </term>
                  <listitem><para>
                    generic mapper (JDBC standard driver ...)
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.cloudscape
                    </term>
                  <listitem><para>
                    Cloudscape
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.db2
                    </term>
                  <listitem><para>
                    DB2
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.firebird
                    </term>
                  <listitem><para>
                    Firebird
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.hsql
                    </term>
                  <listitem><para>
                    HSQL
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.mckoi
                    </term>
                  <listitem><para>
                    McKoi Db
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.mysql
                    </term>
                  <listitem><para>
                    MySQL
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.oracle8
                    </term>
                  <listitem><para>
                    Oracle 8 and lesser versions
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.oracle
                    </term>
                  <listitem><para>
                    Oracle 9
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.postgres
                    </term>
                  <listitem><para>
                    PostgreSQL (&gt;= 7.2)
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.sapdb
                    </term>
                  <listitem><para>
                    Sap DB
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.sqlserver
                    </term>
                  <listitem><para>
                    MS Sql Server
                  </para></listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      rdb.sybase
                    </term>
                  <listitem><para>
                    Sybase
                  </para></listitem>
                  </varlistentry>
                </variablelist>
              </entry>
            </row>
          </tbody>
        </tgroup>
    </informaltable>
    <para>
        Contact the JOnAS team to obtain a mapper for other databases.
    </para>
    <para>
        The container code generated at deployment is now independent of the JORM mappers. Until JOnAS 4.1.4, the container code generated at deployment (GenIC or ejbjar ant task) was dependent on this mapper. It was possible to deploy (generate container code) a bean for several mappers in order to change the database (i.e. the DataSource file) without redeploying the bean. These mappers were specified as the 
        mappernames
         argument of the GenIC command or as the 
        mappernames
         attribute of the JOnAS ANT ejbjar task. The value was a comma-separated list of mapper names for which the container classes were generated. These mappernames options are now deprecated.
    </para>
  </section>
  <section xml:id="cmp2.jonasdd">
    <info><title>JOnAS Database Mapping (Specific Deployment Descriptor)</title></info>
      
    <para>
        The mapping to the database of entity beans and their relationships may be specified in the JOnAS-specific deployment descriptor, in 
        <literal>
          jonas-entity
        </literal>
         elements, and in 
        <literal>
          jonas-ejb-relation
        </literal>
         elements. Since JOnAS is able to generate the database mapping, all the elements of the JOnAS-specific deployment descriptor defined in this section (which are sub-elements of 
        <literal>
          jonas-entity
        </literal>
         or 
        <literal>
          jonas-ejb-relation
        </literal>
        ) are optional, except those for specifying the datasource and the initialization mode (i.e. the 
        <literal>
          jndi-name
        </literal>
         of 
        <literal>
          jdbc-mapping
        </literal>
         and 
        <literal>
          cleanup
        </literal>
        ). The default values of these mapping elements, provided in this section, define the JOnAS-generated database mapping.
    </para>
    <section xml:id="cmp2.jndi">
      <info><title>Specifying and Initializing the Database</title></info>
        
      <para>
          For specifying the database within which a CMP 2.0 entity bean is stored, the 
          <literal>
            jndi-name
          </literal>
           element of the 
          <literal>
            jdbc-mapping
          </literal>
           is necessary. This is the JNDI name of the DataSource representing the database storing the entity bean.
      </para>
      <screen>
    &lt;jdbc-mapping&gt;
      &lt;jndi-name&gt;jdbc_1&lt;/jndi-name&gt;
    &lt;/jdbc-mapping&gt;
            </screen>
      <para>
          For a CMP 2.0 entity bean, the JOnAS-specific deployment descriptor contains an additional element, 
          <literal>
            cleanup
          </literal>
          , to be specified before the 
          <literal>
            jdbc-mapping
          </literal>
           element, which can have one of the following values:
      </para>
      <variablelist>
          <varlistentry>
            <term>
              
                removedata
              
            </term>
            <listitem><para>
              at bean loading time, the content of the tables storing the bean data       is deleted
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>
              
                removeall
              
            </term>
            <listitem><para>
              at bean loading time, the tables storing the bean data are dropped       (if they exist) and created
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>
              
                none
              
            </term>
            <listitem><para>
              do nothing
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>
              
                create
              
            </term>
            <listitem><para>
              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.
            </para></listitem>
          </varlistentry>
      </variablelist>
      <para>
          It may be useful for testing purposes to delete the database data each time a bean is loaded. For this purpose, the part of the JOnAS-specific deployment descriptor related to the entity bean may look like the following:
      </para>
      <screen>
    &lt;cleanup&gt;removedata&lt;/cleanup&gt;
    &lt;jdbc-mapping&gt;
      &lt;jndi-name&gt;jdbc_1&lt;/jndi-name&gt;
    &lt;/jdbc-mapping&gt;
      </screen>
    </section>
    <section xml:id="ejb2.cmp2.fields">
      <info><title>CMP2 fields Mapping</title></info>
        
      <para>
          Mapping CMP fields in CMP2.0 is similar to that of CMP 1.1, but in CMP2.0 it is also possible to specify the SQL type of a column. Usually this SQL type is used if JOnAS creates the table (
          <literal>
            create
          </literal>
           value of the 
          <literal>
            cleanup
          </literal>
           element), and if the JORM default chosen SQL type is not appropriate.
      </para>
      <para>Standard Deployment Descriptor</para>
      <screen>
    .....
    &lt;entity&gt;
      &lt;ejb-name&gt;A&lt;/ejb-name&gt;
      .....
      &lt;cmp-field&gt;
        &lt;field-name&gt;idA&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;f&lt;/field-name&gt;
      &lt;/cmp-field&gt;
    .....
    &lt;/entity&gt;
    .....
      </screen>
      <table><info><title>Database Mapping for CMP2 Fields</title></info>
              
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                        t_A
                    </entry>
                    <entry>
                    </entry>
                  </row>
                  <row>
                    <entry>
                        c_idA
                    </entry>
                    <entry>
                        c_f
                    </entry>
                  </row>
                  <row>
                    <entry>
                      ...
                    </entry>
                    <entry>
                      ...
                    </entry>
                  </row>
                </tbody>
              </tgroup>
      </table>
      <para>JOnAS Deployment Descriptor</para>
      <screen>
    .....
    &lt;jonas-entity&gt;
      &lt;ejb-name&gt;A&lt;/ejb-name&gt;
      .....
      &lt;jdbc-mapping&gt;
        &lt;jndi-name&gt;jdbc_1&lt;/jndi-name&gt;
        &lt;jdbc-table-name&gt;t_A&lt;/jdbc-table-name&gt;
        &lt;cmp-field-jdbc-mapping&gt;
          &lt;field-name&gt;idA&lt;/field-name&gt;
          &lt;jdbc-field-name&gt;c_idA&lt;/jdbc-field-name&gt;
        &lt;/cmp-field-jdbc-mapping&gt;
        &lt;cmp-field-jdbc-mapping&gt;
          &lt;field-name&gt;f&lt;/field-name&gt;
          &lt;jdbc-field-name&gt;c_f&lt;/jdbc-field-name&gt;
          &lt;sql-type&gt;varchar(40)&lt;/sql-type&gt;
        &lt;/cmp-field-jdbc-mapping&gt;
      &lt;/jdbc-mapping&gt;
      .....
    &lt;/jonas-entity&gt;
    .....
      </screen>
      <table><info><title>Defaults values for JOnAS deployment descriptor</title></info>
	      
          <tgroup cols="2">
                <tbody>
                  <row>
                    <entry valign="top">
                      jndi-name
                    </entry>
                    <entry>
                      Mandatory
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      jdbc-table-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the 
                      upper-case
                       CMP2 abstract-schema-name,         or 
                         the CMP1 ejb-name,
                       suffixed by       
                      _
                      .
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      cmp-field-jdbc-mapping
                    </entry>
                    <entry>
                      Optional.
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      jdbc-field-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the field-name suffixed by 
                      _
                      . 
                      idA_
                       and 
                      f_ 
                      in the example.
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      sql-type
                    </entry>
                    <entry>
                      Optional.
                               Default value defined by JORM.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
      </table>
    </section>
    <section xml:id="cmp2.pks">
      <info><title>CMR fields Mapping to primary-key-fields (simple pk)</title></info>
        
      <section xml:id="cmp2.1-1-u-pks">
        <info><title>1-1 unidirectional relationships</title></info>
          
        <section>
          <info><title>Standard Deployment Descriptor</title></info>
            
          <screen>
    .....
    &lt;entity&gt;
      &lt;ejb-name&gt;A&lt;/ejb-name&gt;
      .....
      &lt;cmp-field&gt;
        &lt;field-name&gt;idA&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;primkey-field&gt;idA&lt;/primkey-field&gt;
      .....
    &lt;/entity&gt;
    .....
    &lt;entity&gt;
      &lt;ejb-name&gt;B&lt;/ejb-name&gt;
      .....
      &lt;cmp-field&gt;
        &lt;field-name&gt;idB&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;primkey-field&gt;idB&lt;/primkey-field&gt;
      .....
    &lt;/entity&gt;
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
          </screen>
        </section>
        <section xml:id="cmp2.11"><info><title>Database Mapping for 1-1 relationship</title></info>
          <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                              <entry>
                                
                                  cfk_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
          </informaltable>
          <para>
              There is a foreign key in the table of the bean that owns the CMR field.
          </para>
        </section>
        <section><info><title>JOnAS Deployment Descriptor</title></info>
            
          <screen>
    .....
    &lt;jonas-entity&gt;
      &lt;ejb-name&gt;A&lt;/ejb-name&gt;
      .....
      &lt;jdbc-mapping&gt;
        &lt;jndi-name&gt;jdbc_1&lt;/jndi-name&gt;
        &lt;jdbc-table-name&gt;t_A/jdbc-table-name&gt;
        &lt;cmp-field-jdbc-mapping&gt;
          &lt;field-name&gt;idA&lt;/field-name&gt;
          &lt;jdbc-field-name&gt;c_idA&lt;/jdbc-field-name&gt;
        &lt;/cmp-field-jdbc-mapping&gt;
      &lt;/jdbc-mapping&gt;
      .....
    &lt;/jonas-entity&gt;
    .....
    &lt;jonas-entity&gt;
      &lt;ejb-name&gt;B&lt;/ejb-name&gt;
      .....
      &lt;jdbc-mapping&gt;
        &lt;jndi-name&gt;jdbc_1&lt;/jndi-name&gt;
        &lt;jdbc-table-name&gt;t_B/jdbc-table-name&gt;
        &lt;cmp-field-jdbc-mapping&gt;
          &lt;field-name&gt;idB&lt;/field-name&gt;
          &lt;jdbc-field-name&gt;c_idB&lt;/jdbc-field-name&gt;
        &lt;/cmp-field-jdbc-mapping&gt;
      &lt;/jdbc-mapping&gt;
      .....
    &lt;/jonas-entity&gt;
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_idb&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
          </screen>
        <para>
              foreign-key-jdbc-name
               is the column name of the foreign key in the table of the source bean of the relationship-role. 
               In this example, where the destination bean has a primary-key-field, it is possible to deduce that this foreign-key-jdbc-name column is to be associated with the column of this primary-key-field in the table of the destination bean.
        </para>
        <para>
              Default values:
        </para>
        <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry valign="top">
                      jonas-ejb-relation
                    </entry>
                    <entry>
                      Optional
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      foreign-key-jdbc-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the abstract-schema-name of the destination bean,         suffixed by 
                      _
                      , and by its primary-key-field. 
                      B_idb
                       in the example.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
        </informaltable>
                
      </section>
    </section>
    <section xml:id="cmp2.1-1-b-pks"><info><title>1-1 bidirectional relationships</title></info>
          
          <para>
            Compared to 1-1 unidirectional relationships, there is a CMR field in both of the beans, thus making two types of mapping possible.
          </para>
          <section><info><title>Standard Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;a&lt;/cmr-field-name&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database Mapping</title></info>
            
            <para>
              Two mappings are possible. One of the tables may hold a foreign key.
            </para>
            <para>
              Case 1:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                              <entry>
                                
                                  cfk_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              Case 2:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                              <entry>
                                
                                  cfk_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <para>
              Case 1:
            </para>
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_idb&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              Case 2:
            </para>
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_ida&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              For the default mapping, the foreign key is in the table of the source bean of the first ejb-relationship-role of the ejb-relation. In the example, the default mapping corresponds to case 1, since the ejb-relationship-role 
              a2b
               is the first defined in the ejb-relation 
              a-b
              . Then, the default values are similar to those of the 1-1 unidirectional relationship.
            </para>
                
          </section>
        </section>
        <section xml:id="cmp2.1-n-u-pks"><info><title>1-N unidirectional relationships</title></info>
          
          <section><info><title>Standard Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
            &lt;cmr-field-type&gt;java.util.Collection&lt;/cmr-field-type&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database Mapping</title></info>
            
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                              <entry>
                                
                                  cfk_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              In this case, the foreign key must be in the table of the bean which is on the "many" side of the relationship (i.e. in the table of the source bean of the relationship role with multiplicity many), t_B.
            </para>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_ida&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              Default values:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry valign="top">
                      jonas-ejb-relation
                    </entry>
                    <entry>
                      Optional
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      foreign-key-jdbc-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the abstract-schema-name of the destination bean of         the "one" side of the relationship (i.e. the source bean of the         relationship role with multiplicity one), suffixed by 
                      _
                      , and         by its primary-key-field. 
                      A_ida
                       in the example.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
                
          </section>
        </section>
        <section xml:id="cmp2.1-n-b-pks"><info><title>1-N bidirectional relationships</title></info>
          
          <para>
            Similar to 1-N unidirectional relationships, but with a CMR field in each bean.
          </para>
          <section><info><title>Standard Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
            &lt;cmr-field-type&gt;java.util.Collection&lt;/cmr-field-type&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;a&lt;/cmr-field-name&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database mapping</title></info>
            
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                              <entry>
                                
                                  cfk_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              In this case, the foreign key must be in the table of the bean which is on the "many" side of the relationship (i.e. in the table of the source bean of the relationship role with multiplicity many), t_B.
            </para>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_ida&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              Default values:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry valign="top">
                      jonas-ejb-relation
                    </entry>
                    <entry>
                      Optional
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      foreign-key-jdbc-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the abstract-schema-name of the destination bean of         the "one" side of the relationship (i.e. the source bean of the         relationship role with multiplicity one), suffixed by 
                      _
                      , and         by its primary-key-field. 
                      A_ida
                       in the example.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
                
          </section>
        </section>
        <section xml:id="cmp2.n-1-u-pks"><info><title>N-1 unidirectional relationships</title></info>
          
          <para>
            Similar to 1-N unidirectional relationships, but the CMR field is defined on the "many" side of the relationship, i.e. on the (source bean of the) relationship role with multiplicity "many."
          </para>
          <section><info><title>Standard Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database mapping</title></info>
            
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                              <entry>
                                
                                  cfk_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              In this case, the foreign key must be in the table of the bean which is on the "many" side of the relationship (i.e. in table of the source bean of the relationship role with multiplicity many), t_A.
            </para>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_idb&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              Default values:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry valign="top">
                      jonas-ejb-relation
                    </entry>
                    <entry>
                      Optional
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      foreign-key-jdbc-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the abstract-schema-name of the destination bean of         the "one" side of the relationship (i.e. the source bean of the         relationship role with multiplicity one), suffixed by 
                      _
                      , and         by its primary-key-field. 
                      B_idb
                       in the example.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
                
          </section>
        </section>
        <section xml:id="cmp2.n-m-u-pks"><info><title>N-M unidirectional relationships</title></info>
          
          <section><info><title>Standard Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
            &lt;cmr-field-type&gt;java.util.Collection&lt;/cmr-field-type&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database mapping</title></info>
            
            <informaltable>
              <tgroup cols="3">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  tJoin_AB
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  cfk_idA
                                
                              </entry>
                              <entry>
                                
                                  cfk_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              In this case, there is a join table composed of the foreign keys of each entity bean table.
            </para>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jdbc-table-name&gt;tJoin_AB&lt;/jdbc-table-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_idb&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_ida&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              Default values
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry valign="top">
                      jonas-ejb-relation
                    </entry>
                    <entry>
                      Optional
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      jdbc-table-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is built from the abstract-schema-names of the beans,         separated by 
                      _
                      . 
                      A_B
                       in the example.
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      foreign-key-jdbc-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the abstract-schema-name of the destination bean,         suffixed by 
                      _
                      , and by its primary-key-field. 
                      B_idb
                       and 
                      A_ida
                       in the example.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
                
          </section>
        </section>
        <section xml:id="cmp2.n-m-b-pks"><info><title>N-M bidirectional relationships</title></info>
          
          <para>
            Similar to N-M unidirectional relationships, but a CMR field is defined for each bean.
          </para>
          <section><info><title>Standard deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
            &lt;cmr-field-type&gt;java.util.Collection&lt;/cmr-field-type&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;a&lt;/cmr-field-name&gt;
            &lt;cmr-field-type&gt;java.util.Collection&lt;/cmr-field-type&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database mapping</title></info>
            
            <informaltable>
              <tgroup cols="3">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idA
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="1">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  tJoin_AB
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  cfk_idA
                                
                              </entry>
                              <entry>
                                
                                  cfk_idB
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              In this case, there is a join table composed of the foreign keys of each entity bean table.
            </para>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jdbc-table-name&gt;tJoin_AB&lt;/jdbc-table-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_idb&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_ida&lt;/foreign-key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              Default values:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry valign="top">
                      jonas-ejb-relation
                    </entry>
                    <entry>
                      Optional
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      jdbc-table-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is built from the abstract-schema-names of the beans,         separated by 
                      _
                      . 
                      A_B
                       in the example.
                    </entry>
                  </row>
                  <row>
                    <entry valign="top">
                      foreign-key-jdbc-name
                    </entry>
                    <entry>
                      Optional.
                               Default value is the abstract-schema-name of the destination bean,         suffixed by 
                      _
                      , and by its primary-key-field. 
                      B_idb
                       and 
                      A_ida
                       in the example.
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
                
          </section>
        </section>
      </section>
      <section xml:id="cmp2.pkc"><info><title>CMR fields Mapping to composite primary-keys</title></info>
        
        <para>
          In the case of composite primary keys, the database mapping should provide the capability to specify which column of a foreign key corresponds to which column of the primary key. This is the only difference between relationships based on simple primary keys. For this reason, not all types of relationship are illustrated below.
        </para>
        <section xml:id="cmp2.1-1-b-pkc"><info><title>1-1 bidirectional relationships</title></info>
          
          <section><info><title>Standard Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;entity&gt;
      &lt;ejb-name&gt;A&lt;/ejb-name&gt;
      .....
      &lt;prim-key-class&gt;p.PkA&lt;/prim-key-class&gt;
      .....
      &lt;cmp-field&gt;
        &lt;field-name&gt;id1A&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;id2A&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      .....
    &lt;/entity&gt;
    .....
    &lt;entity&gt;
      &lt;ejb-name&gt;B&lt;/ejb-name&gt;
      .....
      &lt;prim-key-class&gt;p.PkB&lt;/prim-key-class&gt;
      .....
      &lt;cmp-field&gt;
        &lt;field-name&gt;id1B&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;id2B&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      .....
    &lt;/entity&gt;
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;One&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;a&lt;/cmr-field-name&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database mapping</title></info>
            
            <para>
              Two mappings are possible, one or another of the tables may hold the foreign key.
            </para>
            <para>
              Case 1:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="4">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                              <entry>
                              </entry>
                              <entry>
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_id1A
                                
                              </entry>
                              <entry>
                                
                                  c_id2A
                                
                              </entry>
                              <entry>
                                
                                  cfk_id1B
                                
                              </entry>
                              <entry>
                                
                                  cfk_id2B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_id1B
                                
                              </entry>
                              <entry>
                                
                                  c_id2B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              Case 2:
            </para>
            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_id1A
                                
                              </entry>
                              <entry>
                                
                                  c_id2A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="4">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                              <entry>
                              </entry>
                              <entry>
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_id1B
                                
                              </entry>
                              <entry>
                                
                                  c_id2B
                                
                              </entry>
                              <entry>
                                
                                  cfk_id1A
                                
                              </entry>
                              <entry>
                                
                                  cfk_id2A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <para>
              Case 1:
            </para>
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id1b&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id1b&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id2b&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id2b&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              Case 2:
            </para>
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id1a&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id1a&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id2a&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id2a&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
            <para>
              For the default mapping (values), the foreign key is in the table of the source bean of the first ejb-relationship-role of the ejb-relation. In the example, the default mapping corresponds to case 1, since the ejb-relationship-role a2b is the first defined in the ejb-relation a-b.
            </para>
                
          </section>
        </section>
        <section xml:id="cmp2.n-m-u-pkc"><info><title>N-M unidirectional relationships</title></info>
          
          <section><info><title>Standard Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;entity&gt;
      &lt;ejb-name&gt;A&lt;/ejb-name&gt;
      .....
      &lt;cmp-field&gt;
        &lt;field-name&gt;id1A&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;id2A&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      .....
    &lt;/entity&gt;
    .....
    &lt;entity&gt;
      &lt;ejb-name&gt;B&lt;/ejb-name&gt;
      .....
      &lt;cmp-field&gt;
        &lt;field-name&gt;id1B&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      &lt;cmp-field&gt;
        &lt;field-name&gt;id2B&lt;/field-name&gt;
      &lt;/cmp-field&gt;
      .....
    &lt;/entity&gt;
    .....
    &lt;relationships&gt;
      &lt;ejb-relation&gt;
        &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- A =&gt; B --&gt;
                &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;A&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
          &lt;cmr-field&gt;
            &lt;cmr-field-name&gt;b&lt;/cmr-field-name&gt;
            &lt;cmr-field-type&gt;java.util.Collection&lt;/cmr-field-type&gt;
          &lt;/cmr-field&gt;
        &lt;/ejb-relationship-role&gt;
        &lt;ejb-relationship-role&gt;
          &lt;!-- B =&gt; A --&gt;
          &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
          &lt;multiplicity&gt;Many&lt;/multiplicity&gt;
          &lt;relationship-role-source&gt;
            &lt;ejb-name&gt;B&lt;/ejb-name&gt;
          &lt;/relationship-role-source&gt;
        &lt;/ejb-relationship-role&gt;
      &lt;/ejb-relation&gt;
    &lt;/relationships&gt;
    .....
                </screen>
          </section>
          <section><info><title>Database mapping</title></info>
            
            <informaltable>
              <tgroup cols="3">
                <tbody>
                  <row>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_A
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_id1A
                                
                              </entry>
                              <entry>
                                
                                  c_id2A
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="2">
                          <tbody>
                            <row>
                              <entry>
                                
                                  t_B
                                
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  c_id1B
                                
                              </entry>
                              <entry>
                                
                                  c_id2B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                    <entry>
                      <informaltable>
                        <tgroup cols="4">
                          <tbody>
                            <row>
                              <entry>
                                
                                  tJoin_AB
                                
                              </entry>
                              <entry>
                              </entry>
                              <entry>
                              </entry>
                              <entry>
                              </entry>
                            </row>
                            <row>
                              <entry>
                                
                                  cfk_id1A
                                
                              </entry>
                              <entry>
                                
                                  cfk_id2A
                                
                              </entry>
                              <entry>
                                
                                  cfk_id1B
                                
                              </entry>
                              <entry>
                                
                                  cfk_id2B
                                
                              </entry>
                            </row>
                            <row>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                              <entry>
                                ...
                              </entry>
                            </row>
                          </tbody>
                        </tgroup>
                      </informaltable>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
            <para>
              In this case, there is a join table composed of the foreign keys of each entity bean table.
            </para>
          </section>
          <section><info><title>JOnAS Deployment Descriptor</title></info>
            
            <screen>
    .....
    &lt;jonas-ejb-relation&gt;
      &lt;ejb-relation-name&gt;a-b&lt;/ejb-relation-name&gt;
      &lt;jdbc-table-name&gt;tJoin_AB&lt;/jdbc-table-name&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;a2b&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id1b&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id1b&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id2b&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id2b&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
      &lt;jonas-ejb-relationship-role&gt;
        &lt;ejb-relationship-role-name&gt;b2a&lt;/ejb-relationship-role-name&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id1a&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id1a&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
        &lt;foreign-key-jdbc-mapping&gt;
          &lt;foreign-key-jdbc-name&gt;cfk_id2a&lt;/foreign-key-jdbc-name&gt;
          &lt;key-jdbc-name&gt;c_id2a&lt;/key-jdbc-name&gt;
        &lt;/foreign-key-jdbc-mapping&gt;
      &lt;/jonas-ejb-relationship-role&gt;
    &lt;/jonas-ejb-relation&gt;
    .....
                </screen>
          </section>
        </section>
      </section>
  </section>
</section>