[Geronimo Wiki] Update of "Working with Enterprise JavaBeans" by AaronMulder

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Geronimo Wiki" for change notification.

The following page has been changed by AaronMulder:
http://wiki.apache.org/geronimo/Working_with_Enterprise_JavaBeans

------------------------------------------------------------------------------
  The following snippet illustrates a typical usage of the ''cmp-connection-factory element'', where the 
  out-of-the-box connection factory, and hence database, is used.
  
- '''Snippet #1 – Defining a connection factory'''
+ '''Snippet #1 – Defining a connection factory'''
  {{{
      ...
      <cmp-connection-factory>
@@ -45, +45 @@

    * the entity bean ''BeanA'' is mapped to the table ''A''; and
    * its field ''field1'' is mapped to the column ''a1''.
  
- '''Snippet #2 – Mapping an entity bean to a table and its fields to some table columns'''
+ '''Snippet #2 – Mapping an entity bean to a table and its fields to some table columns'''
  {{{
      ...
      <ejb-name>BeanA</ejb-name>
@@ -72, +72 @@

  The following code depicts how these two elements could be used to force ''field1'' to be marshalled into a 
  BLOB column.
  
- '''Snippet #3 – Controlling explicitly the storage of a CMP field'''
+ '''Snippet #3 – Controlling explicitly the storage of a CMP field'''
  {{{
      ...
      <cmp-field-mapping>
@@ -117, +117 @@

  table. These latter are mapped to the columns ''fka1'' and ''fka2'' of the underlying table of the entity 
  bean related to ''A'' via the CMR field ''b''.
  
- '''Snipper #4 – Mapping of an OTO relationship'''
+ '''Snipper #4 – Mapping of an OTO relationship'''
  {{{
      ...
      <relationships>
@@ -168, +168 @@

  
  == Auto-Generated Primary Key ==
  
+ Primary keys of entity beans can be auto-generated. This can save you the trouble of providing primary keys for entities in the create() call.  This feature may also used to deploy entity beans without 
+ a natural primary key, ''i.e.'' having a primary key class set to ''java.lang.Object''.  The configuration of auto-generated primary key entity beans requires the configuration 
+ of a ''key-generator'' element for each affected EJB.
- Primary keys of entity beans can be auto-generated. This feature is used to deploy entity beans without 
- a natural primary key, ''i.e.'' having a primary key class set to ''java.lang.Object''. Note that while 
- this mechanism is intended to be used exclusively for such entity beans, it may also be configured to 
- work with any entity beans.
  
- The configuration of auto-generated primary key entity beans requires the definition of a G''''''Bean 
- implementing the ''org.openejb.entity.cmp.pkgenerator.Primary''''''Key''''''Generator'' interface and the configuration 
- of an ''automatic-key-generation'' element identifying this same G''''''Bean.
+ The children of the key-generator element define the strategy to be used to auto-generate primary key instances. The provided strategies are:
+   * ''auto-increment-table'': use table generated primary keys (auto-generated on a table other than the entity table);
+   * ''sequence-table'': use a sequence table; and
+   * ''sql-generator'': use any SQL statements.
+   * ''custom-generator'': provide your own GBean implementing org.tranql.pkgenerator.!PrimaryKeyGenerator (elsewhere) and refer to it here
  
+ The following snippet shows how the ''key-generator'' element is to be configured:
- The G''''''Bean defines the strategy to be used to auto-generate primary key instances. The provided strategies 
- are defined in the ''org.openejb.entity.cmp.pkgenerator'' package and are:
-   * ''Auto''''''Increment''''''Table''''''Primary''''''Key''''''Generator''''''Wrapper'': use table generated primary keys;
-   * ''Sequence''''''Table''''''Primary''''''Key''''''Generator''''''Wrapper'': use a sequence table; and
-   * ''SQL''''''Primary''''''Key''''''Generator''''''Wrapper'': use any SQL statements.
  
- The following snippet shows how the ''automatic-key-generation'' element is to be configured to used the 
- primary key generator ''geronimo.server:role=CMPPKGenerator,name=Entity'', a G''''''Bean, which 
- creates ''java.lang.Integer'' instances.
- 
- '''Snippet #4 – Auto-generation of primary keys'''
+ '''Snippet #4 – Auto-generation of primary keys'''
  {{{
      ...
-     <automatic-key-generation>
+     <key-generator>
+       <sequence-table>
+         <table-name>SOME_TABLE</table-name>
+         <sequence-name>EJB_NAME</sequence-name>
+         <batch-size>10</batch-size>
+       </sequence-table>
+     <key-generator>
+     ...
+     <key-generator>
+       <auto-increment-table>
+         <sql>INSERT INTO SOME_OTHER_TABLE VALUES ()</sql>
+         <return-type>java.lang.Integer</return-type>
+       </auto-increment-table>
+     <key-generator>
+     ...
+     <key-generator>
+       <sql-generator>
+         <sql>SELECT MY_ORACLE_SEQ.NEXTVAL FROM DUAL</sql>
+         <return-type>java.lang.Integer</return-type>
+       </sql-generator>
+     <key-generator>
+     ...
+     <key-generator>
+       <custom-generator>
-         <generator-name>geronimo.server:role=CMPPKGenerator,name=Entity</generator-name>
+         <generator-name>geronimo.server:name=MyCustomGeneratorName</generator-name>
          <primary-key-class>java.lang.Integer</primary-key-class>
-     </automatic-key-generation>
-     ...
+       </custom-generator>
+     <key-generator>
  }}}
+ 
+ Note that Geronimo does not yet handle the case where the entity table itself has a primary key field that is automatically populated.
  
  === CMP with Unknown Primary Key ===