Document toolboxDocument toolbox

Making a Project available as a GWT Client-Side Module

Introduction

In order to use source code from one maven project in the GWT Client-side code of another maven project, the source code of the dependent project must be bundled correctly or the GWT compile will fail.  This guide shows how to setup a maven project such that source code from the project can be used as a dependency in GWT client-side code.  For example, we want to be able to use all of our auto-generated POJOs from the lib-auto-generated project in the portal's client-side code.

Reminder: All code used in the GWT client must compatible with the GWT client compiler.  The GWT compiler will translate all client-side java code into Javascript so many Java packages such as java.io and java.net are not compatible.

Including source files in the .jar

The source code (.java) of any GWT client-side dependency must be available to the GWT compiler (it compiles .java files into javascript).  This means all of the java source file must be bundled into the dependent jar file.  In the above example, we induced the source files in the lib-auto-generated.jar file by adding the following to the lib-auto-generated pom.xml file:

    <build>
        <resources>
            <resource>
                <!-- This will add the source files to the jar, which is needed for GWT compile. -->
                <directory>src/main/java</directory>
            </resource>
            <resource>
                <!-- We also want the resources directory added -->
                <directory>src/main/resources</directory>
            </resource>
            <resource>
                <!-- This will add all of the auto-generated sources files, which is needed for GWT compile. -->
                <directory>target/auto-generated-pojos</directory>
            </resource>
        </resources>
     ....
	</build>

Compile the dependent project (mvn clean install) and make sure all of the dependent source files can be found in the resulting dependant .jar.

Creating a gwt.xml Module file

The next ingredient we will need in the dependent project is a gwt.xml module file.  This file defines what code is included in a GWT module.  Later we will show how to add this module as a dependencies in client-side code.  In the case of the lib-auto-generated project we wanted to make sure all code in the following project could be used in GWT client-side code:

org.sagebionetworks.repo.model

This dictates how the gwt.xml module file must be created and more importantly where it must appear in the jar.  In the case of the lib-auto-generated project we created the following module file:

/lib-auto-generated/src/main/resources/org/sagebionetworks/repo/synpaseDTOs.gwt.xml

Since we told maven to include the 'src/main/resoure' directory in the pom, this file will be placed in the .jar in the following location:

lib-auto-generated-<version>.jar\org\sagebionetworks\repo\synpaseDTOs.gwt.xml

It turns out where this file appears in the jar file is very important.  If it is in the wrong spot, it simply will not work (it took a lot of trial and error to figure this out!).  In our case, since we wanted our GWT module to include everything in the 'org.sagebionetworks.repo.model' package.  Therefore, our module xml file need to be in one directory shy of this package (\org\sagebionetworks\repo).

The contents of the synapseDTOs.gwt.xml module file are as follows:

<module>
    <!-- Specify the paths for translatable code -->
    <source path="model" />
    <inherits name="com.google.gwt.junit.JUnit" />
    <inherits name="org.sagebionetworks.SchemaToPojoLib" />
</module>

The first thing to point out is the path="model".  The GWT compiler will know to include all source file in jar file under 'org/sagebionetworks/repo/model' by combining the path of the gwt.xml file with the path property in the file!  I am not sure why they made this so complicated but this seems to be the only combination of file path and property path that produces a working module.  If there is a simpler way to do this then please update this document.

Inheriting the GWT Module

Once our GWT module is setup correct, we can now add it as a dependency in the in another maven project.  In our above example we want to use the lib-auto-generated module called 'synapseDTOs' in the portal.  This is done by editing the protal's gwt.xml file:

/portal/src/main/resources/org/sagebionetworks/web/Portal.gwt.xml

We added the following line:

<?xml version="1.0" encoding="UTF-8"?>
<module rename-to='Portal'>
...
    <inherits name="org.sagebionetworks.repo.synpaseDTOs"/>
...
</module>

The auto-generated POJOs are now available to the portal client-side code!