src/doc/faq_cmp.xml

<?xml version="1.0"?>
<faqs>
    <super id="faq">FAQ</super>
    <super id="faq_cmp">CMP EntityBeans</super>
    <name>CMP EntityBeans</name>
<faq>
<question>What engine does OpenEJB use for CMP persistence?</question>
<answer id="jdo">
<p>
OpenEJB uses Castor JDO for CMP persistence.  The CMP config files are all 
Castor controlled files (www.castor.org). At the moment, most of the 
real juicy CMP configuration file information is at the Castor site. 
There is no difference between configuring a CMP EntityBean in OpenEJB 
than with any other Castor controlled java object, so anything you learn 
about Castor's config files will be applicable. 
</p>
</answer>
</faq>

<faq>
<question>What is the format for the CMP mapping files?</question>
<answer id="cmp.mapping">
<p>
The Castor JDO mapping file provides a mechanism for binding a CMP 
EntityBean deployed in OpenEJB to a relational database model. This is 
usually referred to as object-to-relational mapping (O/R mapping). O/R 
mapping bridges the gap between an object model and a relational model.
</p>                     

<p>
The format of these files is <a 
href="http://www.castor.org/jdo-mapping.html">documented here</a>
</p>

</answer>
</faq>

<faq>
<question>How are primary keys created for CMP EntityBeans?</question>
<answer id="cmp.mapping">
<p>
The KeyGenerator is responsible for creating the primary key of the 
records that are inserted by Castor.  
<a href="http://castor.exolab.org/key-generator.html">More information on 
that here</a>
</p>

</answer>
</faq>

<faq>
<question>How do I map my CMP finder methods?</question> 
<answer id="finders">
<p>
You can map your finder methods in the openejb-jar.xml that is created by 
the deploy tool.  Just grab the openejb-jar.xml file from the META-INF 
directory of your jar and add a 'query' declaration like the one below for 
all the CMP entities that need them. </p>

<p>
After the deployer is run for the first time, using your favourite 
editor edit openejb-jar.xml file and add your finder select statement
in openejb-jar.xml file.
</p>

<p>
Repackage your jar file.
</p>

<p>
If openejb is already running close currently running openejb instance
by telnet localhost 4200 and issuing the stop command and restart openejb.
</p>

<p>
Test your program by calling Runit.sh .
</p>

<p>
Whenever deployer is run again for your current application, it will overwrite
openejb-jar.xml file.
</p>

<p>
Say you had a home interface with the following finder method... 
</p>
<p>
<code-block>
package org.acme.employee;

...

public interface EmployeeHome extends EJBHome{
  
  ...
  
  public Employee findByLastName( String lastName ) 
         throws RemoteException, FinderException; 
         
}
</code-block>
</p>

<p>
... then that would require a 'query' declaration in your openejb-jar.xml 
file like this one ...
 
 </p>

<p>
<file name="META-INF/openejb-jar.xml"><![CDATA[  
<ejb-deployment ...
  <query>
    <query-method>
      <method-name>findByLastName</method-name>
      <method-params>
        <method-param>java.lang.String</method-param>
      </method-params>
    </query-method>
    <object-ql>
    SELECT o FROM org.acme.employee.EmployeeBean o WHERE o.lastname = $1 
    </object-ql>
  </query>
</ejb-deployment>
]]></file>
</p>

<p>
The 'query' element goes inside an 'ejb-deployment' element, right under 
any 'resource-link' elements that may be there already. 
</p>

</answer>
</faq>

<faq>
<question>Does OpenEJB support EJB-QL?</question>
<answer id="cmp.mapping">
<p>
No, EJB-QL is an EJB 2.0 CMP feature, so that syntax won't work 
with OpenEJB as the 2.0 spec isn't yet supported. However...
</p>

<p>
We do support OQL (Object Query Language), which is functionally identical.
</p>                     
</answer>
</faq>

<faq>
<question>What is the syntax of OQL?</question>
<answer id="cmp.mapping">
<p>
The syntax of the query statement must be Object Query Language (OQL) 
compatible as described in the ODMG 3.0 specification section 4.12.  OQL 
is nearly identical to EJB QL, so converting CMP beans from 1.1 to 2.0 
will be very easy. 
</p>

<p>
OQL itself is parsed by our persistence engine Castor, see this document 
for more details on writing OQL statements for use with OpenEJB and 
Castor. <a href="http://www.castor.org/oql.html">More information on 
that here</a>
 
</p>
</answer>
</faq>


</faqs>