Google Web Toolkit
Search Google Code:

# Serializable Types

Method parameters and return types must be serializable, which means they must conform to certain restrictions. GWT tries really hard to make serialization as painless as possible, so while the rules regarding serialization are subtle, in practice the behavior becomes intuitive very quickly.

A type is serializable and can be used in a service interface if it

- is primitive, such as `char`, `byte`, `short`, `int`, `long`, `boolean`, `float`, or `double`;
- is `String`, `Date`, or a primitive wrapper such as `Character`, `Byte`, `Short`, `Integer`, `Long`, `Boolean`, `Float`, or `Double`;
- is an array of serializable types (including other serializable arrays);
- is a serializable user-defined class; or
- has at least one serializable subclass

## Serializable User-defined Classes

A user-defined class is serializable if

1. it is assignable to IsSerializable or Serializable, either because it directly implements one of these interfaces or because it derives from a superclass that does
2. all non-`final`, non-`transient` instance fields are themselves serializable, and
3. it has a `public` default (zero argument) constructor

The `transient` keyword is honored, so values in transient fields are not exchanged during RPCs. Fields that are declared `final` are also not exchanged during RPCs, so they should generally be marked `transient` as well.

## Polymorphism

GWT RPC supports polymorphic parameters and return types. To make the best use of polymorphism, however, you should still try to be as specific as your design allows when defining service interfaces. Increased specificity allows the compiler to do a better job of removing unnecessary code when it optimizes your application for size reduction.

## Type Arguments

Collection classes such as `java.util.Set` and `java.util.List` are tricky because they operate in terms of `Object` instances. To make collections serializable, you should specify the particular type of objects they are expected to contain. This requires you to use the special Javadoc annotation `@gwt.typeArgs`. Defining an item type for a collection means that you will ensure that the collection only ever contains objects of that item type or a subclass thereof. This hint is necessary so that the GWT proxy generator can create efficient code. Adding an object to a collection that violates its asserted item type will lead to undefined behavior.

To annotate fields of collection type in a serializable user-defined class:

    public class MyClass implements IsSerializable {
      /**
       * This field is a Set that must always contain Strings.
       *
       * @gwt.typeArgs <java.lang.String>
       */
      public Set setOfStrings;

      /**
       * This field is a Map that must always contain Strings as its keys and
       * values.
       *
       * @gwt.typeArgs <java.lang.String,java.lang.String>
       */
      public Map mapOfStringToString;

      /**
       * Default Constructor. The Default Constructor's explicit declaration
       * is required for a serializable class.
       */
      public MyClass() {
      }
    }

Note that there is no need to specify the name of the field in the `@gwt.typeArgs` declaration since it can be inferred.

Similarly, to annotate parameters and return types:

    public interface MyService extends RemoteService {
      /**
       * The first annotation indicates that the parameter named 'c' is a List
       * that will only contain Integer objects. The second annotation
       * indicates that the returned List will only contain String objects
       * (notice there is no need for a name, since it is a return value).
       *
       * @gwt.typeArgs c <java.lang.Integer>
       * @gwt.typeArgs <java.lang.String>
       */
      List reverseListAndConvertToStrings(List c);
    }

Note that parameter annotations must include the name of the parameter they are annotating in addition to the collection item type, while return type annotations do not.
Tip
Although the terminology is very similar, GWT's concept of "serializable" is different than serialization based on the standard Java interface `Serializable`. All references to serialization are referring to the GWT concept as defined above.