Starting with GWT 2.4, RequestFactory interfaces must be validated before they can be used by the RequestFactory server code or JVM-based clients. This document explains the mechanisms for validating those interfaces.

• Overview
• Annotation Processor
• javac builds
• IDE configuration
• Eclipse
• ValidationTool
• Maven builds

Overview

ERRATA This page incorrectly guides you to find requestfactory-apt.jar in the GWT_TOOLS directory. Instead, Developers should find the requestfactory-apt.jar that came with their distribution. GWT contributors should use the appropriately dated jar in GWT_TOOLS (at this writing requestfactory-apt-2011-08-18.jar), or build their own via ant requestfactory. Note also that the screen shots are aimed at GWT contributors.

The RequestFactory annotation processor will validate the RequestFactory interface declarations and ensure that the mapping of proxy properties and context methods to their domain types is valid. The manner in which the errors are reported depends on the method by which the annotation processor is invoked.

In addition to validating the interfaces, the annotation processor also generates additional Java types which embed pre-computed metadata that is required by the RequestFactory server components. Users of RequestFactorySource must also run the annotation processor in order to provide the client code with obfuscated type token mappings. In the client-only case, the server domain types are not required.

If the validation process is not completed, a runtime error message will be generated:

The RequestFactory ValidationTool must be run for the com.example.shared.MyRequestFactory RequestFactory type

Annotation Processor

It most convenient for both the shared RequestFactory interfaces and their server domain counterparts to be available on the sourcepath or classpath during the compilation process. If this is not practical, see the ValidationTool section for information on post-processing pre-compiled shared interfaces and domain types as part of a deployment process.

javac builds

Users using javac to compile their entire project at once need only to include the requestfactory-apt.jar on the build classpath. The compiler will automatically load the annotation processor from the JAR file. The shared proxy interfaces must be included in the list of java files being compiled.

IDE configuration

Eclipse

Open the project properties dialog and navigate to Java Compiler -> Annotation Processing. Ensure that annotation processing is enabled -- by default it is not.

Add the requestfactory-apt.jar to the factory path.

The project will need to be rebuilt, but once this is done, any RequestFactory validation errors or warnings will be displayed in the editor upon saving:

ValidationTool

Not all build processes are amenable to compiling the shared proxy interfaces and the domain types at the same time. Cases where the ProxyForName and ServiceName annotation are used are typical of this build configuration. In these cases, it is possible to post-process pre-compiled shared and domain types using the RequestFactory ValidationTool.

To run the ValidationTool it is necessary to have the shared interfaces and domain types available on the classpath. The binary names of the RequestFactory interfaces are provided to the tool as well as an output location, which may be a directory or a jar file. The tool will produce one or more class files that contain precomputed metadata that will be used by the RequestFactory server code.

#!/bin/sh
java \
  -cp requestfactory-apt.jar:requestfactory-server.jar:your-shared-classes.jar:your-server-classes.jar \
  com.google.web.bindery.requestfactory.apt.ValidationTool \
  /path/to/output.jar \
  com.example.shared.MyRequestFactory \
  com.example.shared.AnotherRequestFactory

An optional client-only mode will produce the metadata required by RequestFactorySource clients using only the shared interfaces. This mode is activated by adding a -client flag before the output location.

Maven builds

Use the following recipe to run the ValidationTool. If you are using Maven with Google Plugin for Eclipse (see WorkingWithMaven), you do not need to configure Eclipse with the requestfactory-apt.jar as described above. The ValidationTool will be invoked via the POM instead.

      <!-- requestfactory-apt runs an annotation processor (APT) to
           instrument its service interfaces so that
           RequestFactoryServer can decode client requests. Normally
           you would just have a dependency on requestfactory-apt
           with <scope>provided</scope>, but that won't work in
           eclipse due to m2e bug
           https://bugs.eclipse.org/bugs/show_bug.cgi?id=335036 -->
      <plugin>
        <groupId>org.bsc.maven</groupId>
        <artifactId>maven-processor-plugin</artifactId>
        <version>2.0.5</version>
        <executions>
          <execution>
            <id>process</id>
            <goals>
              <goal>process</goal>
            </goals>
            <phase>generate-sources</phase>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>com.google.web.bindery</groupId>
            <artifactId>requestfactory-apt</artifactId>
            <version>${gwtVersion}</version>
          </dependency>
        </dependencies>
      </plugin>

      <!-- Google Plugin for Eclipse (GPE) won't see the source
           generated above by requestfactory-apt unless it is exposed
           as an additional source dir-->
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>1.7</version>
        <executions>
          <execution>
            <id>add-source</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>add-source</goal>
            </goals>
            <configuration>
              <sources>
                <source>${project.build.directory}/generated-sources/apt</source>
              </sources>
            </configuration>
          </execution>
        </executions>
      </plugin>

In order for the build-helper-maven-plugin to work, you must also install the buildhelper connector. This should happen automatically when you import a project that requires it. If not, you'll see an error in the POM. To install it, go to Window > Preferences > Discovery > Open Catalog and install the buildhelper connector, then re-import the project from scratch.

In Eclipse 3.7 (Indigo), the following additional POM snippet is needed:

    <pluginManagement>
      <plugins>
        <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
        <plugin>
          <groupId>org.eclipse.m2e</groupId>
          <artifactId>lifecycle-mapping</artifactId>
          <version>1.0.0</version>
          <configuration>
            <lifecycleMappingMetadata>
              <pluginExecutions>
                <pluginExecution>
                  <pluginExecutionFilter>
                    <groupId>org.bsc.maven</groupId>
                    <artifactId>maven-processor-plugin</artifactId>
                    <versionRange>[2.0.5,)</versionRange>
                    <goals>
                      <goal>process</goal>
                    </goals>
                  </pluginExecutionFilter>
                  <action>
                    <execute />
                  </action>
                </pluginExecution>
              </pluginExecutions>
            </lifecycleMappingMetadata>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>