index-group=Unrevised type=page status=published title=EJB 2.1 CMP EntityBeans (CMP2)
OpenEJB, the EJB Container for TomEE and Geronimo, does support all of EJB 1.1 to 3.1, including CMP2. The CMP2 implementation is actually done by adapting the CMP2 bean into a JPA Entity dynamically at deploy time. Appropriate subclasses, a JPA persistence.xml file and a mapping.xml file are generated at deployment time for the CMP2 EntityBeans and all the Entities will be then run on OpenJPA. This innovative code has been used as the sole CMP2 implementation in Geronimo for its J2EE 1.4, JavaEE 5 and JavaEE 6 certifications. The persistence.xml and mapping.xml files generated at deploy time can be saved to disk and included in the application, allowing you to: - gain finer control over persistence options - slowly convert individual entities from CMP2 to JPA Let's see an example. # Movies application The following is a basic EJB 2.1 application consisting of one CMP2 Entity. For those that are reading this example out of curiosity and are not familiar with CMP2 or EJB 2.x, each CMP2 Entity is composed of two parts - **A Home interface** which has data access methods like "find", "create", and "remove". This is essentially what people use `@Stateless` beans for today, but with difference that you do not need to supply the implementation of the interface -- the container will generate one for you. This is partly what inspired the creation of the OpenEJB-specific [Dynamic DAO](../dynamic-dao-implementation/README.html) feature. - **An abstract EntityBean class** which declares the persistent "properties" of the entity without actually declaring any fields. It is the container's job to implement the actual methods and create the appropriate fields. OpenEJB will implement this bean as a JPA `@Entity` bean. As such a CMP2 EntityBean is really just the description of a persistent object and the description of a data-access object. There is no actual code to write. The majority of work in CMP2 is done in the xml: - **ejb-jar.xml** mapping information, which describes the persistent properties of the entity and the queries for all *Home* find, create and remove methods. This information will be converted by OpenEJB into a JPA mapping.xml file. All queries in the cmp2 part of the ejb-jar.xml are converted into named queries in JPA and generally everything is converted to its JPA equivalent. ## CMP2 EntityBean, MovieBean package org.superbiz.cmp2; import javax.ejb.EntityBean; public abstract class MovieBean implements EntityBean { public MovieBean() { } public Integer ejbCreate(String director, String title, int year) { this.setDirector(director); this.setTitle(title); this.setYear(year); return null; } public abstract java.lang.Integer getId(); public abstract void setId(java.lang.Integer id); public abstract String getDirector(); public abstract void setDirector(String director); public abstract String getTitle(); public abstract void setTitle(String title); public abstract int getYear(); public abstract void setYear(int year); } ## CMP2 Home interface, Movies package org.superbiz.cmp2; import javax.ejb.CreateException; import javax.ejb.FinderException; import java.util.Collection; /** * @version $Revision$ $Date$ */ interface Movies extends javax.ejb.EJBLocalHome { Movie create(String director, String title, int year) throws CreateException; Movie findByPrimaryKey(Integer primarykey) throws FinderException; Collection<Movie> findAll() throws FinderException; Collection<Movie> findByDirector(String director) throws FinderException; } ## CMP2 mapping in ejb-jar.xml <ejb-jar> <enterprise-beans> <entity> <ejb-name>MovieBean</ejb-name> <local-home>org.superbiz.cmp2.Movies</local-home> <local>org.superbiz.cmp2.Movie</local> <ejb-class>org.superbiz.cmp2.MovieBean</ejb-class> <persistence-type>Container</persistence-type> <prim-key-class>java.lang.Integer</prim-key-class> <reentrant>false</reentrant> <cmp-version>2.x</cmp-version> <abstract-schema-name>MovieBean</abstract-schema-name> <cmp-field> <field-name>id</field-name> </cmp-field> <cmp-field> <field-name>director</field-name> </cmp-field> <cmp-field> <field-name>year</field-name> </cmp-field> <cmp-field> <field-name>title</field-name> </cmp-field> <primkey-field>id</primkey-field> <query> <query-method> <method-name>findByDirector</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </query-method> <ejb-ql>SELECT m FROM MovieBean m WHERE m.director = ?1</ejb-ql> </query> <query> <query-method> <method-name>findAll</method-name> <method-params/> </query-method> <ejb-ql>SELECT m FROM MovieBean as m</ejb-ql> </query> </entity> </enterprise-beans> </ejb-jar> ## openejb-jar.xml <openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1"> <enterprise-beans> <entity> <ejb-name>MovieBean</ejb-name> <key-generator xmlns="http://www.openejb.org/xml/ns/pkgen-2.1"> <uuid/> </key-generator> </entity> </enterprise-beans> </openejb-jar> ## MoviesTest package org.superbiz.cmp2; import junit.framework.TestCase; import javax.naming.Context; import javax.naming.InitialContext; import java.util.Collection; import java.util.Properties; /** * @version $Revision: 607077 $ $Date: 2007-12-27 06:55:23 -0800 (Thu, 27 Dec 2007) $ */ public class MoviesTest extends TestCase { public void test() throws Exception { Properties p = new Properties(); p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.LocalInitialContextFactory"); p.put("movieDatabase", "new://Resource?type=DataSource"); p.put("movieDatabase.JdbcDriver", "org.hsqldb.jdbcDriver"); p.put("movieDatabase.JdbcUrl", "jdbc:hsqldb:mem:moviedb"); p.put("movieDatabaseUnmanaged", "new://Resource?type=DataSource"); p.put("movieDatabaseUnmanaged.JdbcDriver", "org.hsqldb.jdbcDriver"); p.put("movieDatabaseUnmanaged.JdbcUrl", "jdbc:hsqldb:mem:moviedb"); p.put("movieDatabaseUnmanaged.JtaManaged", "false"); Context context = new InitialContext(p); Movies movies = (Movies) context.lookup("MovieBeanLocalHome"); movies.create("Quentin Tarantino", "Reservoir Dogs", 1992); movies.create("Joel Coen", "Fargo", 1996); movies.create("Joel Coen", "The Big Lebowski", 1998); Collection<Movie> list = movies.findAll(); assertEquals("Collection.size()", 3, list.size()); for (Movie movie : list) { movies.remove(movie.getPrimaryKey()); } assertEquals("Movies.findAll()", 0, movies.findAll().size()); } } # Running ------------------------------------------------------- T E S T S ------------------------------------------------------- Running org.superbiz.cmp2.MoviesTest Apache OpenEJB 4.0.0-beta-1 build: 20111002-04:06 http://tomee.apache.org/ INFO - openejb.home = /Users/dblevins/examples/simple-cmp2/target INFO - openejb.base = /Users/dblevins/examples/simple-cmp2/target INFO - Configuring Service(id=Default Security Service, type=SecurityService, provider-id=Default Security Service) INFO - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager) INFO - Configuring Service(id=movieDatabaseUnmanaged, type=Resource, provider-id=Default JDBC Database) INFO - Configuring Service(id=movieDatabase, type=Resource, provider-id=Default JDBC Database) INFO - Found EjbModule in classpath: /Users/dblevins/examples/simple-cmp2/target/classes INFO - Beginning load: /Users/dblevins/examples/simple-cmp2/target/classes INFO - Configuring enterprise application: /Users/dblevins/examples/simple-cmp2/target/classpath.ear INFO - Configuring Service(id=Default CMP Container, type=Container, provider-id=Default CMP Container) INFO - Auto-creating a container for bean MovieBean: Container(type=CMP_ENTITY, id=Default CMP Container) INFO - Configuring PersistenceUnit(name=cmp) INFO - Adjusting PersistenceUnit cmp <jta-data-source> to Resource ID 'movieDatabase' from 'null' INFO - Adjusting PersistenceUnit cmp <non-jta-data-source> to Resource ID 'movieDatabaseUnmanaged' from 'null' INFO - Enterprise application "/Users/dblevins/examples/simple-cmp2/target/classpath.ear" loaded. INFO - Assembling app: /Users/dblevins/examples/simple-cmp2/target/classpath.ear INFO - PersistenceUnit(name=cmp, provider=org.apache.openjpa.persistence.PersistenceProviderImpl) - provider time 160ms INFO - Jndi(name=MovieBeanLocalHome) --> Ejb(deployment-id=MovieBean) INFO - Jndi(name=global/classpath.ear/simple-cmp2/MovieBean!org.superbiz.cmp2.Movies) --> Ejb(deployment-id=MovieBean) INFO - Jndi(name=global/classpath.ear/simple-cmp2/MovieBean) --> Ejb(deployment-id=MovieBean) INFO - Created Ejb(deployment-id=MovieBean, ejb-name=MovieBean, container=Default CMP Container) INFO - Started Ejb(deployment-id=MovieBean, ejb-name=MovieBean, container=Default CMP Container) INFO - Deployed Application(path=/Users/dblevins/examples/simple-cmp2/target/classpath.ear) Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.919 sec Results : Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 # CMP2 to JPA As mentioned OpenEJB will implement the abstract CMP2 `EntityBean` as a JPA `@Entity`, create a `persistence.xml` file and convert all `ejb-jar.xml` mapping and queries to a JPA `entity-mappings.xml` file. Both of these files will be written to disk by setting the system property `openejb.descriptors.output` to `true`. In the testcase above, this can be done via the `InitialContext` parameters via code like this: Properties p = new Properties(); p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.LocalInitialContextFactory"); // setup the data sources as usual... // write the generated descriptors p.put("openejb.descriptors.output", "true"); Context context = new InitialContext(p); Below are the generated `persistence.xml` and `mapping.xml` files for our CMP2 `EntityBean` ## CMP2 to JPA generated persistence.xml file <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0"> <persistence-unit name="cmp" transaction-type="JTA"> <jta-data-source>movieDatabase</jta-data-source> <non-jta-data-source>movieDatabaseUnmanaged</non-jta-data-source> <mapping-file>META-INF/openejb-cmp-generated-orm.xml</mapping-file> <class>openejb.org.superbiz.cmp2.MovieBean</class> <properties> <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true, Indexes=false, IgnoreErrors=true)"/> <property name="openjpa.Log" value="DefaultLevel=INFO"/> </properties> </persistence-unit> </persistence> All of this `persitence.xml` can be changed, however the `persistence-unit` must have the `name` fixed to `cmp`. ## CMP2 to JPA generated mapping file Note that the `persistence.xml` above refers to this mappings file as `META-INF/openejb-cmp-generated-orm.xml`. It is possible to rename this file to whatever name you prefer, just make sure to update the `<mapping-file>` element of the `cmp` persistence unit accordingly. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" version="1.0"> <entity class="openejb.org.superbiz.cmp2.MovieBean" name="MovieBean"> <description>simple-cmp2#MovieBean</description> <table/> <named-query name="MovieBean.findByDirector(java.lang.String)"> <query>SELECT m FROM MovieBean m WHERE m.director = ?1</query> </named-query> <named-query name="MovieBean.findAll"> <query>SELECT m FROM MovieBean as m</query> </named-query> <attributes> <id name="id"> <generated-value strategy="IDENTITY"/> </id> <basic name="director"/> <basic name="year"/> <basic name="title"/> </attributes> </entity> </entity-mappings>