2. Gas3 Ant Task

 Documentation Summary

 Page Summary

Eclipse Integration

Download org.granite.gas3_1.2.0.zip, unzip it in your Eclipse plugin directory and restart Eclipse. The gas3 task should now be available in Eclipse and you may use it in your build.xml files launched by Eclipse.

Standalone Installation

Download org.granite.gas3_1.2.0.zip, unzip it somewhere, say in / or C:\ for Windows® users. You should now have a org.granite.gas3_1.2.0 directory at the root of your harddisk.

In your build.xml, you must declare the Gas3 AntTask as follows:

<taskdef name="gas3" classname="org.granite.generator.ant.AntJavaAs3Task"/>

To launch the build process with Gas3 targets, you should go to your source directory and type something like:

$ ant -lib /org.granite.gas3_1.2.0 -lib /org.granite.gas3_1.2.0/lib -f build.xml <gas3target>
...

Just replace <gas3target> with the accurate target name and make sure Ant is correctly set up; ANT_HOME variable and <ANT_HOME>/bin in your PATH environment variable.

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.2.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 EJB 3 you want to generate AS3 beans. The classpath node is used for fileset class loading, and 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 (e.g., ./as3). This path is relative to your current project directory and Gas3 will create subdirectories for packages. AS3 beans will have the same package as Java EJB 3, with the same subdirectories as well.

For each EJB 3 (say org.entity.MyEntity), Gas3 will generate 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 ones.

<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 these translators with a "best match" principle; all Java classes within the path.to.my.java.class package, and 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 in 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.

Here is the complete list of Gas3 node attributes:

• outputdir and baseoutputdir: We have already seen the outputdir attribute in basic usage. baseoutputdir lets you define a custom output directory for your "Base" generated files. The default is to use the same directory as specified by the outputdir attribute.
• uid: If you want your AS3 to implement 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.
• as3typefactory: You can plug your own org.granite.generator.as3.As3TypeFactory implementation in order to add support for custom types. For example, if you have configured a custom Joda time converter, you may extend Gas3 accordingly for this custom type. Just extend the org.granite.generator.as3.DefaultAs3TypeFactory class and return org.granite.generator.as3.As3Type.DATE when you encounter a Joda DateTime instance. See Type Conversions for a detailed example.
• tide: Should we use a Tide specific template instead of the standard base template used for entity beans (true or false, defaut is false). Setting this attribute has no effect if you use a custom entity base template. See below.
• entitytemplate and entitybasetemplate: Templates used for classes annotated with @Entity or @MappedSuperclass.
• interfacetemplate and interfacebasetemplate: Templates used for Java interfaces.
• beantemplate and beanbasetemplate: 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"
        baseoutputdir="base_as3"
        uid="myUidFieldName"
        as3typefactory="path.to.MyJava3As3Class"
        tide="true"
        entitytemplate="/myEntityTemplate.gsp"
        entitybasetemplate="/myEntityBaseTemplate.gsp"
        interfacetemplate="/myInterfaceTemplate.gsp"
        interfacebasetemplate="/myInterfaceBaseTemplate.gsp"
        beantemplate="/myBeanTemplate.gsp"
        beanbasetemplate="/myBeanBaseTemplate.gsp">
        enumtemplate="/myEnumTemplate.gsp">
        <classpath>
            <pathelement location="classes"/>
        </classpath>
        <fileset dir="classes">
            <include name="test/granite/ejb3/entity/**/*.class"/>
        </fileset>
    </gas3>
</target>
...

Note that when using a custom as3typefactory attribute, you must configure the classpath in order to make your custom class available to the Gas3 engine; either use the classpath attribute in the taskdef declaration or in the gas3 call.