Howto

Welcome to BeanGen, the enterprise java bean generator and openEJB configurator that makes j2ee look like a piece of cake :-)

Usage

So you want to try it out... well it's very easy, first download a binary version, (if you want you can download the source directly from CVS and compile it yourself), however in this howto i'm assuming you have a binary jar file

Now you can execute it like this:

    java -jar beangen-<version>.jar input_file.txt output_file.jar

don't forget that output is a jar file so don't use other extension than

    jar

Right now you have always to use the two parameters, if you don't you'll have problems because beangen will try to use some hardcoded path's (used in development).

Ok, you can run it but you don't have a input file... i'll explain how to generate one in the next step...

Input File Format

XML file format is great and takes alot to write a simple file, so... i don't use it :-P I'll support XML files in a later version but it's not implemented at the present.

You may be asking... so how do i write my input file? quite easy! You have only 11 commands, every line that start's with a

    #

is a comment. Now about the commands...

    CONFIG:[CATALINA|OPENEJB]:<path>

This is a setup command, it informs where's your tomcat or openejb installed. You should have two of these commands per file. Don't forget that

    :

is the special character that separates the fields. No there's no escape sequence for now, there will be later...

    PROJECT:<unix_name>:<Project Full Name>

This command is used for documentation and war file generation only. There should only be one per file. unix_name is a single word that identifies your project, project full name you should have already found what it means...

    LAZY_LOADING:COLLECTIONS:FIELDS:FKS

If you want lazy loading (cache of data) as defined at sun's best practices for ejb's your should tell what you want to cache. Right now it can cache Collections, Fields and Foreign Keys. If you don't one of these to be cached just remove it from the list

    RESOURCE:DATASOURCE:<unix_name>:<jndi path>:<sql server>:<key generator>

You define here the resources you want to make available in our project, right now only DATASOURCES are supported. For information about key generator, server types see www.castor.org

    ENTITY:[CMP|BMP]:<table name>:<java name>:<java package>

Simple isn't it? Define an entity bean you can choose CMP or BMP (BMP not tested as CMP)

        JNDI-BASEPATH:<path>

For each entity you should define one of these commands. You need to inform where you want this bean inside JNDI. (Optional)

        DESCRIPTION:<string>

This description will be used to document your bean, if you need to write big comments, just write lot's of these commands inside an entity and they will be appended with each other. (optional)

        AUTHOR:<string>

Your name, just for javadocs. (Optional)

        FIELD:<type>:<db field name>:<java name>:[null|not null]:[ro|rw]:[pk|fk]

You need to define as many as you want for each entity. the read/write option and pk/fk option are optional if you don't need them. You should have a pk field for every entity. The field types supported are the same supported by castor, see www.castor.org

Complex keys (keys composed with more than one field aren't supported yet...

        RESOURCE-LINK:<name from resources above>

Where can we get the database? this will tell the bean wich resource to use.

        COLLECTION:1-*:<entity name>

In this release only one to many and one to one relationships are supported. one to one are automatically found because of fk keywork in field command, one to many have to be defined this way.

Input File Sample

So you know the commands but want to see them in action? ok, this is the Titan example:

CONFIG:CATALINA:c:/jakarta-tomcat
CONFIG:OPENEJB:c:/openejb-1.0

# Define the project name
PROJECT:titan:Titan Vacances

# Enable Lazy loading (not fully functional)
LAZY_LOADING:COLLECTIONS:FIELDS:FKS

# Define a global DataSource Resource
RESOURCE:DATASOURCE:dbserver:jdbc/titan:mysql:IDENTITY

# define a CMP entity bean
ENTITY:CMP:CABIN:cabin:com.titan.j2ee

  # inside jndi, this bean will be located under titan folder (optional)
  JNDI-BASEPATH:titan

  DESCRIPTION:Define a Cabin Object...

  AUTHOR:Paulo Lopes

  FIELD:integer:CABIN_ID:id:not null:ro:pk
  FIELD:integer:SHIP_ID:ship:null:rw:fk
  FIELD:integer:CABIN_BED_COUNT:bedCount:null
  # i changed char(30) to varchar
  FIELD:varchar:CABIN_NAME:name:not null
  FIELD:integer:CABIN_DECK_LEVEL:deckLevel:null

  # this bean will have a datasource resource
  RESOURCE-LINK:dbserver

ENTITY:CMP:SHIP:ship:com.titan.j2ee

  JNDI-BASEPATH:titan

  AUTHOR:Paulo Lopes

  # I don't like BigDecimal... so i'll trick Castor
  FIELD:integer:SHIP_ID:id:not null:ro:pk
  FIELD:varchar:SHIP_NAME:name:null
  FIELD:integer:SHIP_CAPACITY:capacity:null
  FIELD:double:SHIP_TONNAGE:tonnage:null

  RESOURCE-LINK:dbserver
  # define collections here...
  COLLECTION:1-*:cabin

The latest input file sample is here
Reference site

The X marks the spot...