Welcome to JaxMe!

- A Framework for Java/XML binding based on SAX2 -

JaxMe's BeanWriter

One of JaxMe's source generators is the BeanWriter, which creates J2EE conformant entity beans for EJB (Enterprise JavaBeans) with BMP (Bean Managed Persistence) or stateless session beans. In this documents we'll discuss the BeanWriter's details.

The BeanWriter's usage.
Some notes on the rationale.

The BeanWriter's usage

The BeanWriter is used just like any other SourceWriter:

    java -classpath xerces.jar;jaxme.jar de.ispsoft.jaxme.generator.Main
      --schemaReader=de.ispsoft.jaxme.generator.XsdJdbcSchemaReader
      --sourceWriter=de.ispsoft.jaxme.generator.JavaSourceWriter
      --sourceWriter=de.ispsoft.jaxme.generator.BeanWriter
      examples/session/schema.xsd

When running this example, you will find that some additional files are being generated in the directory de/ispsoft/jaxme/examples/session besides the usual ClsSession, ClsSessionHandler and ClsSessionManager:

File name	Description
ClsSessionHome.java	The entity beans home interface.
ClsSessionRemote.java	The entity beans remote interface.
ClsSessionBean.java	The actual entity bean class.
ejb-jar.xml	A default deployment descriptor. (In the directory META-INF)

The BeanWriter has created an entity bean, because the structure was specified by reading a table definition. In other words, because data can not only be read, but also inserted, updated or deleted. If the structure would be specified with a JaxMe view, then it would have created a session bean instead. The session bean could only read data.

The BeanWriter's target is a compromise between performance and encapsulation. It is best used with the following in mind:

The encapsulated XML document is treated as a "value object". That means, rather than lots of setXXX() and getXXX() methods, by default the only methods for accessing data are void create(JMAnyElement pElement), void update(JMAnyElement pElement) and JMAnyElement getXML(). They are in fact bulk accessors.

          <Order id="34767" custno="3489" state="created">
            <Details> ... </Details>
          </Order>

The above order might have a state of "created", "accepted" and "delivered". Typical business rules for an update() method could be, that

The create() method must set the state to "created".
The bulk accessor update() may change the "Details" section only and only if the state is "created".
There is an additional method setState(String) for changing the state from "created" to "accepted" or from "accepted" to "delivered".

To ensure a proper workflow, one would manually derive a subclass from the automatically generated bean class. This subclass would overwrite the methods create() and update() and add methods getState() and setState().

The "frontend" session bean can be created by using a JaxMe view.
The concept of entity beans depends on a primary key. The primary key is unknown to XML Schema. As of this writing, the primary key is only supported by the XsdJdbcSchemaReader. This will change in the near future. Likewise, neither a composed primary key nor a mapping of primary key type and/or value are supported. This will also change in the near future.

Find methods

Generated entity beans should have proper findXXX() methods. For example, if you have an entity bean for your address list, then it should have methods like

      findByName(String pName);
      findByZip(String pZip);

and so on. You can specify these find methods together with the specification of the mapped tables, see the section on Find methods in the generated manager for details.

Session beans, that are generated from JaxMe views, can have similar methods, which are called listXXX() methods. They are specified as list methods in the JaxMe view definition.

Compatibility with EJB 1.1

By default the BeanWriter creates sources as specified by EJB 2.0. However, in a few cases these are incompatible with EJB 1.1. In particular the constructor new EJBException(msg, exception) is not available in EJB 1.1.

If you specify the option ejb11compatible, then this behaviour changes. For example, the command line to run JaxMe might look like this:

    java -classpath xerces.jar;jaxme.jar de.ispsoft.jaxme.generator.Main
      --schemaReader=de.ispsoft.jaxme.generator.XsdJdbcSchemaReader
      --sourceWriter=de.ispsoft.jaxme.generator.JavaSourceWriter
      --sourceWriter=de.ispsoft.jaxme.generator.BeanWriter
      --option=ejb11compatible=true
      examples/session/schema.xsd