By convention, you place generator classes in a rebind package; for the Dashboard, this resides under the org.gwtbook package. Just as with server-side code, you should avoid placing a generator under the client package for two reasons: It doesn’t naturally fit in that package; and you can use Java 1.5 and other constructs that aren’t possible in the client-side code (if you place your generator in the client package, then the GWT compiler automatically tries to compile it and complains about any non-GWT compliant code).

Let’s look at the basic structure of any generator, shown in listing 14.1.

Example 14.1. The template of a generator

This generator doesn’t do much, but it does show that all generators need to extend the basic Generator class and implement the generate() method . The inputs to the generate() method are all supplied by the compiler during the compilation process. These inputs include the context in which the generator executes; you can use that context to access classes, files, and properties. A TreeLogger is also supplied, which allows you to output your own logging information in the compilation logger. The final parameter is the name of the type that is being presented to the generator by the compiler.

At present, the result of the generate() method in listing 14.1 is the value null—which tells the compiler that the generator hasn’t created a new type and that it should use the original type passed in as the parameter. If you want to create a new type, then you need to provide the code to create that new type as well as return the name of this new type. You’ll do that now for the Dashboard example.

The generate() method takes as a String parameter the name of the input type. For the generator to be of any use, you need to access the type itself and not a reference to its name. Listing 14.2 shows how you do this.

Example 14.2. Accessing the TypeOracle and various type aspects within a GWT generator

GWT provides a TypeOracle class, an instance of which you can retrieve from the also-passed generatorContext object, which allows you to access information about the type. Once you have the TypeOracle, you can get a reference to the class through the getType() method . In the example, you have no nested classes to find; but if you do, you need to use the source name (with periods) rather than the binary name (with $).

This use of TypeOracle is fairly simple: to get access to one named type. It can also be used to examine the whole set of types and packages in the context that is being compiled through various methods with the words package and type in their names.

The returned type from the getType() method is a JType, which is one of a number of GWT classes that represent Java constructs. There are also GWT Java classes for packages, classes, methods, parameters, fields, and so on; you can use these objects to perform introspection on classes, as you’ll see later in this chapter. For now, you use a couple of methods in the JType class to retrieve the package name of the input class as well as its simple source name . Both of these pieces of data are then used in creating the fully qualified name of the class you’ll generate , which is the input class with the text Proxy appended to the class name. Any exceptions that are raised by your generator are handled at , where you output an error message to the current TreeLogger object.

In certain circumstances, such as with internationalization, you’d like to know the values of the properties in this context so that the correct binding to constants/messages can be performed. Access to these values is through the PropertyOracle object.

When the GWT system creates the bindings required for internationalization, the generator needs to know which locale the current context is all about in order to select the appropriate properties file (this is why the files must be named in the particular manner they have been). Similarly, for the Dashboard, you wish to know if you’re generating for the Internet or intranet version. In chapter 15, we’ll introduce a user-defined property called externalvisibility that you can set as either intranet or internet. If the context you’re compiling for has the externalvisibility property set as internet, then you only show public fields and methods in the About dialog; you determine that by looking in the PropertyOracle (see listing 14.3).

Example 14.3. Accessing the PropertyOracle and a property from within a GWT generator

You accessed information about types through the TypeOracle object, which you retrieved from the GeneratorContext object. Similarly, you access information about GWT properties through a PropertyOracle retrieved from the GeneratorContext object . Retrieving properties is slightly easier than class details because there is only one thing to look for. You use the getPropertyValue() method to get access to the value of the externalvisibility property.

Unlike other points in GWT where we discuss properties, in the generator case you’re only concerned with the value of a property in the particular context being compiled at that point. For example, when you set up the locale property in chapter 3, you gave two values—an English one and a Swedish one. When the generator executes the locale, the property has only one value: that of the locale currently in context. In hosted mode, that means the locale currently being used; when compiling for web mode, the generator is called multiple times, once for each locale being managed.

If you can’t find the property you’re looking for, this is handled by the catch statement . You can also keep track of what’s going on in your generators by implementing logging.

Logging in a generator is performed by writing log statements to the TreeLogger class that is passed to the generate() method. You can log either a message or an exception using the following template:

Logger.log(TreeLogger.LEVEL, message, exception)

Only one of the message or exception can be provided; the other should be left as the null object. Values of the LEVEL all come from the TreeLogger class and include the INFO and ERROR levels you’ve used in the Dashboard example as well as ALL, DEBUG, INFO, SPAM, NULL, TRACE, and WARN.

When you run the application in hosted mode, the generator is invoked whenever you create an instance of a DashboardComposite. The output in the hosted-mode window is shown in figure 14.3.

Figure 14.3. Output from the generator when running in hosted mode

In web mode, all of the compilation is performed at once to generate the numerous permutations of JavaScript code (see chapter 17 for details). Figure 14.4 shows the output produced when we compiled the code.

Figure 14.4. Output from the generator when preparing for web mode

Or, you can ask the compiler to use the TreeLogger by including the -treeLogger flag in the compile command (see chapter 2). Adding this flag means the output appears in hosted-mode style window, as shown in figure 14.5.

Figure 14.5. Output from the generator when preparing for web mode with the compile provided with the -treeLogger flag set

The log statements are added to your generator code, as shown in listing 14.4.

public String generate(TreeLogger logger,
                       GeneratorContext context,
                       String typeName)
       throws UnableToCompleteException {
   try{
      logger.log(TreeLogger.INFO, "Starting rewriting using:"+
                                   this.getClass().getSimpleName()+
                                    " for "+version+" version",
                                    null);
      // Other code
      logger.log(TreeLogger.INFO, "Completed rewriting", null);
      } catch ...
      }
}

You’re almost in a position to start writing your new functionality, but first you must get an object that represents the new type—the SourceWriter object.

You write your new type by printing lines of text to a SourceWriter object (which, unlike the other classes used in generators, can be found in the gwt-user.jar archive under the com.google.gwt.user.rebind package). The route to it is slightly convoluted and is shown in listing 14.5 as a separate method in the Dashboard Generator class.

Example 14.5. Creating the SourceWriter object

First, you try to create a standard Java PrintWriter object from the current GeneratorContext through the tryCreate() method using the new fully qualified class name as a parameter. If you fail to get a PrintWriter, it’s because the class you’re trying to create already exists . This isn’t unusual, particularly because at compilation time the generator is called many times; you may have created the necessary new type in a previous permutation.

Note that if the generated type is to be an interface rather than the default of a class, then you additionally call the makeInterface() method on the composer factory.

Let’s assume you’re applying the generator to the Clock component application. If the PrintWriter has been successfully created, then creates your new type, which resembles the following:

package org.gwtbook.client.ui.clock

public class ClockProxy{
}

At , you tell the new class to have some imports. Because you’re going to add a MenuItem and an associated Command, these are prime candidates to be included, as is the Window class, because you’re going to show an alert box with the Window.alert() method. Next, you tie the new type to the old type by setting its superclass . The class is now as follows:

import com.google.gwt.user.client.Command;
import com.google.gwt.user.client.Window;
import com.google.gwt.user.client.ui.MenuItem;
package org.gwtbook.client.ui.clock

public class ClockProxy extends Clock{
}

Finally, you create the SourceWriter from this ComposerFactory , which is subsequently used to create the methods in the new class.

Assuming the result of getting the SourceWriter isn’t null, you need to take the last result and provide your new functionality. You do this by adding new methods, overriding methods in the superclass, or manipulating the input class. New methods and fields are written out to the SourceWriter object. We’ll look at creating two methods: one that overrides the DashboardComponent’s getName() method, and another that creates the About menu item.

Overriding an existing method

To override an existing method, you write out the details to the SourceWriter, as shown in listing 14.6.

Example 14.6. Using a generator to override an existing method

You first write out a JavaDoc comment for the new method. Then, you write the method definition you want using calls to the println() method. Although you generally won’t see the new method definition written down, here you use the indent() and outdent() methods to structure your code—it’s useful to structure the code in a sensible way for those occasions where you make errors. In these circumstances, the compiler will direct you to the error, and in our experience it’s often due to forgetting to put the semicolon in at the end of the command you’re constructing. Look at this line of code, which could be written instead of in listing 14.6:

writer.println("return "" + className + """);

The syntax checker in Java won’t complain about this, because it’s valid Java. But when you try to use your new class, you get the error message shown in figure 14.6.

Figure 14.6. A common error when developing generators is to make a mistake in the code.

The error happens because you forgot to put a semicolon at the end of the code you’re generating, not because a semicolon is missing from the println() command. In this case, hosted mode tells you the error is in Line 9, and the next line in the error points you to the location of the temporary file containing Java code that has been generated, a segment of which is shown here:

The offending error line is marked , and you can see that a semicolon is indeed missing.

You can see in figure 14.6 that the compiler tells you where to find the generated class, but remember from chapter 3 that you can direct the compiler where to place these generated classes by using the -gen directory flag.

This method was easy to write. More complicated ones are possible, including those that include an element of introspection on the input class, as you can see in the method that creates the About menu dialog.

Creating a method that uses introspection

When it comes to manipulating the input class, we briefly mentioned earlier that GWT provides a set of classes that allow you to introspect an existing Java class. These are depicted in figure 14.7.

Figure 14.7. Classes that can be used in the generator to manipulate GWT Java classes

Note

It’s only possible to introspect a Java class at compile time—and that introspection has to use the GWT classes in figure 14.7 rather than the normal Java way.

You use these classes when it comes to manipulating the input class. The starting point for introspection is the JClassType object, which you obtain from the OracleType at the start of the generator’s generate() method. Once you have this object, you can start asking for the class’s methods using the JClassType.get-Methods() method or its field using JClassType.getFields() method. You can find out the modifiers of the type, such as whether it’s public or private, what type it subclasses or implements, its metadata, and various other aspects.

Return objects from methods in the JClassType class generally come from those classes shown in figure 14.7. For example, if you wanted to list all the methods of the requestedClass object you retrieved from the TypeOracle, you would write the following:

JMethod[] methods = requestedClass.getMethods();
for(int loop=0;loop<methods.length;loop++){
   writer.println(methods[loop].toString()+"
);
}

You use these introspection approaches in the generator to create the About menu option we’ve previously discussed. Listing 14.7 shows the code.

Example 14.7. Creating a new option menu using source code introspection

At , you use GWT’s version of introspection to get the fields and methods of the class. Next, you make the method call the overridden parent’s createOptionsMenu() method so you ensure that the MenuItem you’re adding always gets added as the last item in the list. You create a String object to hold the alert message , and at you start looping around the fields in the input class. You check at that you’re generating for the intranet version—or, if it’s the Internet version, whether the field is public. If either of those cases is true, then you add the details to the alert string.

You can see the complete generator in the downloadable code, which includes all this code plus more logging. The result of the generator, so far, on the Clock Dashboard component application for the intranet version is shown in listing 14.8.

Example 14.8. The generated version of the Clock class (ClockProxy)

package org.gwtbook.client.ui.clock;

import com.google.gwt.user.client.Window;
import com.google.gwt.user.client.Command;
import com.google.gwt.user.client.ui.MenuItem;

public class ClockProxy extends org.gwtbook.client.ui.clock.Clock {

  /**
   * Overides DashboardComposite getName() method
   */
  public String getName(){
    return "Clock";
  }

  public void createOptionsMenu(){
    super.createOptionsMenu();
    optionsMenuBar.addStyleName("submenu");
    optionsMenuBar.addItem("About", new Command() {
      public void execute(){
        String aboutMessage = "About the Dashboard Clock Widget
                               (intranet version)
";
        aboutMessage +="Info Created by a GWT Generator

";
        aboutMessage +="Number Fields: 4
";
        aboutMessage+="org.gwtbook.client.ui.clock.Clock.AlarmTimer
                       alarm
";
        aboutMessage+="private com.google.gwt.user.client.ui.Label
                       clockLabel
";
        aboutMessage+="private boolean local
";
        aboutMessage+="org.gwtbook.client.ui.clock.Clock.ClockTimer
                       clock
";
        aboutMessage +="
Number Methods: 2
";
        aboutMessage+="public java.util.Date getTime()
";
        aboutMessage+="public void createOptionsMenu()
";
        Window.alert(aboutMessage);
       }
     });
  }
}

It’s not only methods that you can extend; you can also read and react to tags in the class’s comments or methods. You did this when you created an ImageBundle in chapter 4, where the path to the image was stored as a tag in the method’s comment. Let’s look at how you can use this mechanism to create the Dashboard components’ This App. Demonstrates menu item.

Getting information from tags in comments

When you created an ImageBundle in chapter 4, you created an interface that included definitions such as this:

/**
* @gwt.resource org/gwtbook/public/ToolbarImages/ChangeEvents.png
*/
AbstractImagePrototype ChangeEvents();

The tag @gwt.resource defines the location of the image that should be included in the ImageBundle. GWT’s image bundle generator will ensure that this identified image is included in the bundle.

In the Dashboard, you use a similar approach to extract information in the class’s comment to display to the user when they click the This App. Demonstrates menu item. Listing 14.9 provides an overview of the Clock class.

Example 14.9. Clock class definition showing comment displayed as the This App. Demonstrates menu item

In the Dashboard generator, you extract the comment for the class and wrap it up to be displayed when the user clicks the This App. Demonstrates menu item, as shown in figure 14.8.

Figure 14.8. Comment displayed when the user clicks the This App. Demonstrates menu item

You ensure that the text you want displayed from the comment starts with a specific tag—in this case, @dashboard.description. Then, in the generator, you write some code that extracts this text from the class’s metadata. For the Dashboard, this code is shown in listing 14.10.

Example 14.10. Generator code that extracts the metadata value from the class

First, you get a reference to the class’s metadata, which is tagged with the tag @dashboard.description . With the reference established, you either extract all the text related to the tag or create default text . The next step is to wrap the newAppDescription variable into some code that creates a display similar to figure 14.8.

There is one final step to take before you use your newly generated class: You have to return its name to the compiler.

The final task that the generator needs to perform is to return the name of the class the compiler should use. In listing 14.1, you saw that the compiler uses the input class if you return the null value. For the DashboardGenerator, you always return a class name, which is the name of the proxy class that either the generator just generated or was generated in the past.

To use the generated class in your code, you must use GWT’s deferred-binding approach to allow the compiler to generate the code for you. Fortunately, there isn’t much difference between normal Java object creation and GWT’s deferred-binding approach, except that you can’t pass parameters into the deferred approach. To create an object this way, write the following code:

DashboardComposite newObject =
    (DashboardComposite)GWT.create(Calculator.class);

Here you use the GWT.create() method, which is in the com.google.gwt.core.client package, to create a new object of the Calculator.class type. The parameter must be a class literal; and, frustratingly, you can’t use a variable in its place. This last fact explains why in the Dashboard.java code you’ll find the same code shown in listing 14.11 repeated for each Dashboard application.

Example 14.11. Creating an instance of the Server Status Dashboard application through deferred binding

If the panel hasn’t already been created , then you use the deferred binding approach to create a new instance of the appropriate DashboardComposite ; place it in its own panel , which is set to automatically display when created; and add it to your list of panels . In the case where the panel already exists, you make the old panel visible . (This means only one instance of a Dashboard application is ever in the Dashboard at a time.)

With this generator in place and the Dashboard.gwt.xml file updated, you register the generator as follows:

<generate-with
      class="org.gwtbook.rebind.DashboardCompositeGenerator">
   <when-type-assignable
          class="org.gwtbook.client.ui.DashboardComposite"/>
</generate-with>

Then, every class you have that extends the DashboardComposite class will be passed to this generator and have a new About menu item stamped on it, as well as have its class name added as the title bar of the window it sits in. In our discussion, we briefly touched on some properties the generator can access—in this case, the externalvisibility property. GWT properties such as this are another way to alter what is displayed to the user.