Convert to Pure CMP

this wiki page already assumes you have some knowledge of how xdoclet works so that if you are trying to convert code you didn't write, you understand what's going on. for the most part however, most of these instructions fall along the lines of "cut-and-paste".

the tutorial uses examples directly out of the news code base, so feel free to check out the code.

notes

the following assumptions are in effect:

1) your database schema is using appropriate foreign key references into the core nukes database schema. ie: if you wish to link to user information w/in your module.

-

Step 1: build.xml modifications

  - added the following entry under the "configure" target, be sure to replace the property value with the jndi name for your module.

<property name="jndi-root" value="nukes/news"></property>

  - add the following fileset to the ejbdoclet task under the "generate-classes" target

  <fileset dir="${jboss.nukes.root}/../src/main/">
    <include name="org/jboss/nukes/core/ejb/BaseEJB.java"></include>
    <include name="org/jboss/nukes/core/ejb/UserEJB.java"></include>
    <include name="org/jboss/nukes/core/ejb/GroupEJB.java"></include>
    <include name="org/jboss/nukes/core/ejb/ProfileEJB.java"></include>
    <include name="org/jboss/nukes/core/ejb/PropertyDefaultValueEJB.java"></include>
    <include name="org/jboss/nukes/core/ejb/PropertyEJB.java"></include>
    <include name="org/jboss/nukes/core/ejb/PropertyValueEJB.java"></include>
  </fileset>

- replace the tasks to generate your interfaces. be sure to replace the "news" portion of the tag with your module's name. this is necessary so that xdoclet only generates classes for your modules code, yet includes the correct information in the deployment descriptors.

  <localinterface havingClassTag="nukes.news"></localinterface>
  <localhomeinterface havingClassTag="nukes.news"></localhomeinterface>

- optional step: the setup.xml file should be removed from each database directory under "resources" once it is confirmed the conversion works. loading initial data will be coverred later in this document.

Step 2: entity bean xdoclet modifications

add the following xdoclet snippets to the indicated areas of the class file

class level xdoclet

  @jboss.persistence
         create-table = "${nukes.create-table}"
         remove-table = "${nukes.remove-table}"
         pk-constraint = "${nukes.pk-constraint}"

primary key getter method

  @jboss.persistence
         not-null = "true"
         auto-increment = "true"
         dbindex = "true"
  @jboss.sql-type
         type = "${nukes.pk-sql-type}"
  @jboss.jdbc-type
         type = "${nukes.pk-jdbc-type}"

other getter methods

  it will be up to you to determine if the column in the database should be created with a "not-null" constraint and/or is indexed.

  not-null columns

  @jboss.persistence
         not-null = "true"

index columns

  @jboss.persistence
         dbindex = "true"

both

  @jboss.persistence
         not-null = "true"
         dbindex = "true"

foreign key columns

in order for tables to be properly created inside postgres, these additional tags must be added

  sql-type = "INTEGER"
  jdbc-type = "INTEGER"

the entire xdoclet snippet would look like this:

  @jboss.relation
         fk-column = "id"
         related-pk-field = "Id"
         sql-type = "INTEGER"
         jdbc-type = "INTEGER"

at this time, the ${nukes.pk-jdbc-type} value is defaulted to "INTEGER". if you wish to change that value for any tables w/in your module's schema AND you wish to utilize foreign keys, you must make sure the sql/jdbc-type values specified on your foreign key relation match those of the primary key definition.

in the case of postgres, the sql-type of the primary key field will be "SERIAL" (this is postgres auto-increment equivalent), so the foreign key sql-type should match whatever the jdbc-type is.

"textarea" columns

if you want to store "textarea" data inside the database (an example of this would be the news summary, or the news extended details), you must add the following:

  @jboss.sql-type
         type = "${nukes.text-sql-type}"
  @jboss.jdbc-type
         type = "VARCHAR"

Step 3: take it for a test spin!

once you've converted all your entity beans to use "pure" cmp, it's time to test it out. make sure you execute a "build clean" before you rebuild to ensure everything is generated correctly.

also be sure to drop any of the existing tables in the database so the tables are re-created on deployment.

-

Initial data loading

if you find that the setup.xml has entries for intitial data loading, you will need to add the following additional statements to the class level xdoclet

   @jboss.persistence
          post-table-create = "<your sql statements>"

complete example

   @jboss.persistence
          create-table = "${nukes.create-table}"
          remove-table = "${nukes.remove-table}"
          pk-constraint = "${nukes.pk-constraint}"
          post-table-create = "<your sql statements>"

-

Other items of interest

- if you are converting a module that has yet to be "officially" released, you are free to change table/column names to those that may make more sense.

- @ejb.persistence and @jboss.persistence tags only need to be specified on the getter methods of your ejb. it is not necessary to also specify the tags on the setter methods.