2.5. Gas3 Code Generator

 Documentation Summary

 Page Summary

Granite Data Services comes with an AS3 bean generator for all externalized (see here) Java beans, with specific support for lazy-loaded EJB3 entities. This generator (named GAS3) is implemented by now as an Ant task, packaged as an Eclipse 3.2+ plugin.

Download org.granite.gas3_1.0.0.zip, unzip it in your Eclipse plugin directory and restart Eclipse.

After installation, you may use the gas3 Ant task in any target of an Ant build file. A working sample of gas3 usage is available in graniteds-ejb3-1.0.0.zip.

For example:

...
<target name="generate.as3">
    <gas3 outputdir="as3">
        <classpath>
            <pathelement location="classes"/>
        </classpath>
        <fileset dir="classes">
            <include name="test/granite/ejb3/entity/**/*.class"/>
        </fileset>
    </gas3>
</target>
...

As you can notice, gas3 generates AS3 beans for Java compiled classes. You may use multiple Ant filesets in order to specify for which EJB3 you want to generate AS3 beans. The classpath node is used for fileset class loading (you may reference extra jars or classes needed by your beans class loading).

The outputdir attribute lets you instruct gas3 in which directory AS3 beans will be generated (eg: ./as3). This path is relative to your current project directory and gas3 will create subdirectories for packages: AS3 beans will have the same package than Java EJB3 (same subdirectories as well).

For each EJB3 (say org.entity.MyEntity), gas3 will generates two AS3 beans:

1. org.entity.MyEntityBase.as: this bean mainly contains fields, getters, setters and IExternalizable methods (readExternal/writeExternal). This file is generated if it does not exist or if it is outdated.
2. org.entity.MyEntity.as: this bean inherits from the "Base" one and is only generated if it does not exist.

While you should not modify the "Base" file (since your modifications may be lost after another generation process), you may safely add your code to the inherited bean.

You may tell Gas3 to generate AS3 classes with a different package (and directory structure) than the corresponding Java classes one's.

<gas3 ...>
    <classpath .../>
    <fileset .../>

    <translator
        java="path.to.my.java.class"
        as3="path.to.my.as3.class" />
    <translator
        java="path.to.my.java.class.special"
        as3="otherpath.to.my.as3.class.special" />
  ...
</gas3>

Gas3 uses those translators with a "best match" principle: all java classes within the "path.to.my.java.class" package (subpackages as well) will be translated to "path.to.my.as3.class" while "path.to.my.java.class.special" will use a specific translation("otherpath.to.my.as3.class.special").

NOTE: If you use a special Java2As3 converter, you must take care of packages translations (see org.granite.generator.as3.DefaultJava2As3 implementation for details).

Gas3 generation relies on Groovy templates. You may plug your own templates by using one of the advanced options attributes below. For example, you could add a entitytemplate="/absolute/path/to/my/groovy/entityTemplate.gsp" attribute to the gas3 node. If you want to see the groovy code of the default templates, just unpack granite.generator.jar (in the lib directory of the plugin) and look for org/granite/generator/template/*[Base].gsp files.

Other gas3 node attributes give you more control over the generation process:

• uid: if you want your as3 to implements mx.core.IUID, you must tell the generator the name of the java field that contains this UID. By default, gas3 will search for a field named "uid". You may change this by adding a uid="myUid" attribute to the gas3 node. If gas3 does not find this uid, it will be silently ignored.
• java2as3class: you can plug your own org.granite.generator.as3.Java2As3 implementation in order to add support for custom types. For example if you have configured a custom Joda time converter (see Miscanellous Options), you may extend accordingly gas3 for this custom type: just extend the org.granite.generator.as3.DefaultJava2As3 class and return org.granite.generator.as3.As3Type.DATE when you encounter a Joda DateTime instance.
• entitytemplate and entitybasetemplate: templates used for classes annotated with @Entity or @MappedSuperclass.
• interfacetemplate and interfacebasetemplate: templates used for Java interfaces.
• generictemplate and genericbasetemplate: templates used for other Java classes (including @Embeddable).
• enumtemplate: template used for java.lang.Enum types.

For example:

...
<target name="generate.as3">
    <gas3
        outputdir="as3"
        uid="myUid"
        java2as3class="path.to.MyJava3As3Class"
        entitytemplate="/myEntityTemplate.gsp"
        entitybasetemplate="/myEntityBaseTemplate.gsp"
        interfacetemplate="/myInterfaceTemplate.gsp"
        interfacebasetemplate="/myInterfaceBaseTemplate.gsp"
        generictemplate="/myGenericTemplate.gsp"
        genericbasetemplate="/myGenericBaseTemplate.gsp">
        enumtemplate="/myEnumTemplate.gsp">
        <fileset dir="classes">
            <include name="test/granite/ejb3/entity/*.class"/>
        </fileset>
    </gas3>
</target>
...