RequestFactory & AutoBeans

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This page is written against GWT 2.13.1 (released 2026-06-19), gwt-maven-plugin 1.3.0 (net.ltgt.gwt.maven), JDK 21 running the compiler with -sourceLevel 17, the Jakarta Servlet 6 server of the Bookshelf scenario (Jetty 12.1.10 through the Maven plugin) and Hibernate Validator 4.1.0.Final on the server, checked on 2026-10-09. RequestFactory touches every layer: the proxy interfaces and the RequestFactory interface are shared code (the compiler turns them into JavaScript and the server loads them as ordinary classes), the generated client and the Receiver callbacks are client code, the entities, services, locators and the servlet are server code, and two build steps are specific to it (an <inherits> line and an annotation processor). AutoBeans are shared code in the same way. Every output block was produced by running the examples: the real RequestFactory client and server in one JVM on JDK 21 (plain JUnit with InProcessRequestTransport), the servlet in Jetty on port 8935 driven with curl, and GWTTestCase tests in HtmlUnit for the generated client and the AutoBeans in a browser engine. Where a statement comes only from the Developer Guide or from the 2.13.1 source, the text says so.

RequestFactory is the data-oriented sibling of GWT-RPC: instead of calling remote methods on a service, the client manipulates proxies of server-side entities inside a request context, and only the changed properties travel to the server. It is old (it appeared with GWT 2.1) and the Developer Guide has not changed in a long time, so the page spends as much effort on what is stale and on how to decide whether to use it as on the API itself. The decision is in [status] and the comparison with the alternatives is in Choosing between GWT-RPC, RequestFactory and plain JSON for a GWT 2.13 application.

The idea in one example

The Bookshelf client below lists books together with their publisher, then changes the year of one of them. The proxies and the BookRequest context are the interfaces defined later on this page; nothing in this code knows about HTTP, JSON or the server classes.

public class BookshelfData {
  private final BookshelfRequestFactory factory = GWT.create(BookshelfRequestFactory.class);

  public BookshelfData(EventBus eventBus, RequestTransport transport) {
    factory.initialize(eventBus, transport);
  }

  public void load(int first, int max, final BooksCallback callback) {
    factory.bookRequest().findBookEntries(first, max).with("publisher").fire(
        new Receiver<List<BookProxy>>() {
          @Override
          public void onSuccess(List<BookProxy> books) {
            callback.onBooks(books);
          }

          @Override
          public void onFailure(ServerFailure error) {
            callback.onError(error.getMessage());
          }
        });
  }

  public void changeYear(BookProxy book, int year, final Runnable done) {
    BookRequest ctx = factory.bookRequest();
    BookProxy editable = ctx.edit(book);
    editable.setYear(year);
    ctx.persist().using(editable).fire(new Receiver<Void>() {
      @Override
      public void onSuccess(Void ignored) {
        done.run();
      }
    });
  }
}

Source: GWT — Request Factory: Using RequestFactory

Three things are different from GWT-RPC:

GWT.create(BookshelfRequestFactory.class) is called once; initialize(eventBus, transport) gives the factory an EventBus for entity-change events and a RequestTransport that does the HTTP.
Proxies received from the server are immutable. edit(book) returns an editable copy bound to the request context, and the setters record the change; the request that is fired afterwards carries only year.
.with("publisher") lists the relations to send back. RequestFactory never follows relations on its own.

The client code compiles to JavaScript. The same code, compiled with RequestFactorySource.create instead of GWT.create, also runs on a JVM, which is how the server side was tested for this page.

RequestFactory compared with the other options

The Developer Guide describes RequestFactory as an alternative to GWT-RPC for data-oriented services, built around entities (data with a persistent identity) and services. GWT-RPC uses remote methods as building blocks, similar to Java RMI; RequestFactory keeps track of modified objects and sends only the changes, which the guide describes as very lightweight payloads, and it uses its own servlet and its own JSON protocol. The table is a summary of the guide, of the 2.13.1 source and of what was measured here.

Table 1. Choosing between GWT-RPC, RequestFactory and plain JSON for a GWT 2.13 application
	GWT-RPC	RequestFactory	JSON over HTTP (`RequestBuilder`, `fetch`, AutoBeans)
Building block	A service interface with methods	An entity proxy, a request context and a service	A URL and a document
What the client holds	The same concrete serialisable classes as the server	Interfaces implemented by the framework, one per entity	Overlay types, JsInterop objects or AutoBeans
Server code	A servlet that implements the service interface	Plain entity and service classes, found through annotations	Any servlet, controller or JAX-RS resource
Changes	The whole object is sent back	Only changed properties are sent	Whatever you design
Batching	One call per request	Several contexts can be joined in one HTTP request (`append`)	Whatever you design
Validation	Your own code	JSR-303 on the server, violations returned to the `Receiver`	Your own code
Server-side requirement	`gwt-servlet(-jakarta)` and serialisation policy files	`gwt-servlet-jakarta` or `requestfactory-server(-jakarta)`, a JSR-303 API and the generated validation classes	Nothing from GWT
Used by a non-GWT client	Not realistic	The wire format is documented only in the source (`messages` package)	Yes
Status	Documented; see GWT-RPC for its Java 17 exception-serialisation issue	See [status]	Not tied to GWT

GWT-RPC and RequestBuilder, JSON & XML are the other halves of the comparison; the overview of all options is Client–Server Communication. This page does not repeat them.

Artifacts and setup

The RequestFactory artifacts live in their own group, org.gwtproject.web.bindery, not in org.gwtproject. All of them were published for 2.13.1 on 2026-06-19 (Maven Central metadata, checked 2026-10-09).

Table 2. RequestFactory artifacts on Maven Central (group `org.gwtproject.web.bindery`, version 2.13.1)
Artifact	What it contains
`requestfactory`	A pom that manages the versions of the others. The GWT bill of materials `org.gwtproject:gwt` imports it, so the other artifacts need no `<version>` in a project that imports the BOM
`requestfactory-client`	The compiled client and shared classes (the `shared` and `gwt.client` packages of `com.google.web.bindery.requestfactory`) and the AutoBean framework. The 2.13.1 jar holds class files only: the module descriptors and sources that the GWT compiler reads are in `gwt-user` (a `-sources` jar is also published)
`requestfactory-server`	The server side for `javax.servlet` containers: `com.google.web.bindery.requestfactory.server.RequestFactoryServlet`
`requestfactory-server-jakarta`	The same for `jakarta.servlet` containers: `com.google.web.bindery.requestfactory.server.jakarta.RequestFactoryServlet` (since 2.11.0)
`requestfactory-apt`	The annotation processor and the command-line `ValidationTool` that validate the interfaces and generate the server-side lookup class

gwt-servlet-jakarta (and gwt-servlet for javax) already contains the RequestFactory server classes, the shared classes and the AutoBean vm package, including RequestFactoryServlet, InProcessRequestTransport and AutoBeanFactorySource (listed in the 2.13.1 jars). A Bookshelf server that already depends on gwt-servlet-jakarta for GWT-RPC therefore needs only two more dependencies for RequestFactory: javax.validation:validation-api (managed by the GWT BOM at 1.0.0.GA) and requestfactory-apt on the annotation processor path. Adding requestfactory-server-jakarta on top of gwt-servlet-jakarta works but makes the Jetty Maven plugin print scanned from multiple locations warnings, because the two jars contain the same classes; pick one.

The server module of the Bookshelf therefore adds this to its existing gwt-servlet-jakarta dependency (the processor configuration is in the validation tool section):

<dependency>
  <groupId>javax.validation</groupId>
  <artifactId>validation-api</artifactId>
</dependency>
<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>4.1.0.Final</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>1.6.4</version>
  <scope>runtime</scope>
</dependency>

Source: GWT — Request Factory: Wiring

Hibernate Validator 4.1.0.Final is the provider Validation uses for the client; as a server provider here it is the only one that was tried. It needs slf4j-api: the 1.6.1 that it declares and a newer slf4j-simple mixed together failed with a NoSuchMethodError for org.slf4j.helpers.MessageFormatter.format, so keep the slf4j-api and the binding on one version. The Developer Guide’s list of jars (requestfactory-server.jar, validator-api-1.0.0.GA.jar, a JSR 303 validator) is the same set spelled for a hand-built WEB-INF/lib.

The module file

The compiler needs the RequestFactory module in the module that contains the proxies, and the AutoBean module if you use AutoBeans directly (RequestFactory inherits it itself).

<module>
  <inherits name="com.google.gwt.user.User" />
  <inherits name="com.google.web.bindery.requestfactory.RequestFactory" />
  <inherits name="com.google.web.bindery.autobean.AutoBean" />
  <source path="client" />
  <source path="shared" />
</module>

Source: GWT — Request Factory: Wiring, GWT — AutoBeans: Quickstart

RequestFactory.gwt.xml inherits Core, AutoBean, HTTP, LoggingDisabled and User, adds the gwt/client, gwt/ui/client and shared source paths and registers two generators: RequestFactoryGenerator for every type assignable to RequestFactory, and RequestFactoryEditorDriverGenerator for RequestFactoryEditorDriver (see the editors page). AutoBean.gwt.xml registers AutoBeanFactoryGenerator for every type assignable to AutoBeanFactory. Both are deferred-binding generators, which is why the factories are created with GWT.create.

The servlet

The Developer Guide registers com.google.web.bindery.requestfactory.server.RequestFactoryServlet. That class extends javax.servlet.http.HttpServlet and cannot run in a Servlet 5 or 6 container; since 2.11.0 the jakarta variant is the one to use there.

<servlet>
  <servlet-name>requestFactoryServlet</servlet-name>
  <servlet-class>com.google.web.bindery.requestfactory.server.jakarta.RequestFactoryServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>requestFactoryServlet</servlet-name>
  <url-pattern>/gwtRequest</url-pattern>
</servlet-mapping>

Source: GWT — Request Factory: Wiring

Table 3. The two servlet classes
	`javax`	`jakarta`
Class	`com.google.web.bindery.requestfactory.server.RequestFactoryServlet`	`com.google.web.bindery.requestfactory.server.jakarta.RequestFactoryServlet`
Superclass	`javax.servlet.http.HttpServlet`	`jakarta.servlet.http.HttpServlet`
Artifacts	`gwt-servlet`, `requestfactory-server`	`gwt-servlet-jakarta`, `requestfactory-server-jakarta`
Containers	Servlet 4 and earlier (Jetty 9, Tomcat 9)	Servlet 5 and 6 (Jetty 11 and later, Tomcat 10 and later, Spring Boot 3)

Everything else on the server (SimpleRequestProcessor, ServiceLayer, Locator, ServiceLocator, the validation) is shared by both variants. Only the jakarta class was run for this page (in Jetty 12.1.10). The javax class was inspected with javap in the 2.13.1 jars, not run in a javax container.

The servlet reads two optional init parameters, symbolMapsDirectory and symbolMapsResourcePath, to deobfuscate stack traces of server failures sent by the client logging (the Developer Guide shows WEB-INF/classes/symbolMaps/ and says the application must be compiled with -extras). The page on logging covers the symbol maps; see Logging, and Server Integration & Deployment covers the servlet container side. The servlet also exposes getThreadLocalRequest(), getThreadLocalResponse() and getThreadLocalServletContext(), which services use to reach the HTTP transaction (the Bookshelf example uses the request for an authorisation check).

The moving parts

sequenceDiagram participant P as Presenter participant F as BookshelfRequestFactory participant C as BookRequest context participant T as RequestTransport participant S as RequestFactoryServlet participant L as ServiceLayer and Deobfuscator participant E as BookEntity and services P->>F: bookRequest() F-->>P: new context P->>C: edit(proxy), setYear(2018) P->>C: persist().using(proxy).fire(receiver) C->>T: one JSON payload: invocations and changed properties T->>S: POST /gwtRequest S->>L: resolve operation token to a method L->>E: find the entity, apply the changes L->>E: validate with JSR 303 E-->>L: persist() runs on the domain object L-->>S: response: results, updated entities, violations S-->>T: JSON T-->>C: payload C-->>P: receiver.onSuccess, EntityProxyChange on the EventBus

Table 4. The types you meet, and where each one lives
Type	Layer	Role
`RequestFactory`	shared	Your interface; one method per service stub. Created with `GWT.create` (client) or `RequestFactorySource.create` (JVM) and initialised with an `EventBus` and optionally a `RequestTransport`
`RequestContext`	shared	A unit of work. It creates and edits proxies, accumulates the calls, and sends everything when `fire()` is called. `append(other)` joins another fresh context, so several services share one HTTP request
`Request<T>` and `InstanceRequest<P, T>`	shared	A call to a service method. `fire(Receiver)` sends it, `to(Receiver)` registers the receiver for a joined context, `with(String...)` names the relations to return. An `InstanceRequest` is for instance methods of an entity and gets its target through `using(proxy)`
`EntityProxy`	shared	Client view of an entity with identity: adds `stableId()`
`ValueProxy`	shared	Client view of a value object without identity or version
`@ProxyFor`, `@ProxyForName`	shared	Name the domain class a proxy stands for (and, optionally, its `Locator`); the `Name` variant takes a string
`@Service`, `@ServiceName`	shared	Name the class that implements a context’s methods (and, optionally, its `ServiceLocator`)
`@ExtraTypes`	shared	Adds proxy types that are not reachable from the signatures, for example subtypes
`Locator<T, I>`	server	Supplies `create`, `find`, `getId`, `getVersion` and the type information for entities that do not implement them themselves
`ServiceLocator`	server	Supplies the instance on which a service’s instance methods are invoked
`Receiver<V>`	client	Callback: `onSuccess`, `onFailure(ServerFailure)`, `onConstraintViolation(Set)`
`EntityProxyChange<P>`	client	Event on the `EventBus` when an entity is first seen or changes; carries a `WriteOperation`
`RequestTransport`, `DefaultRequestTransport`	client	Sends a string and returns a string; the default one POSTs to the host page base URL followed by `gwtRequest`
`RequestFactoryServlet`	server	Receives the payload, calls `SimpleRequestProcessor`
`ValidationTool`, `RfValidator`	build	Validate that the client interfaces match the domain classes and generate the lookup class the servlet needs

Proxies and the RequestFactory interface

An entity proxy is an interface that extends EntityProxy and names its domain class. Only the getters and setters the client needs have to be declared; the compiler checks that each has a match on the domain class.

@ProxyForName("com.example.bookshelf.server.rf.BookEntity")
public interface BookProxy extends EntityProxy {
  Long getId();
  Integer getVersion();
  String getTitle();
  void setTitle(String title);
  String getAuthor();
  void setAuthor(String author);
  int getYear();
  void setYear(int year);
  PublisherProxy getPublisher();
  void setPublisher(PublisherProxy publisher);
}

@ProxyForName("com.example.bookshelf.server.rf.Publisher")
public interface PublisherProxy extends ValueProxy {
  String getName();
  void setName(String name);
  String getCountry();
  void setCountry(String country);
}

Source: GWT — Request Factory: Entity Proxies, Value Proxies

@ProxyFor(BookEntity.class) is the form used in the Developer Guide. It needs the domain class on the classpath of whoever compiles the proxy. In the Bookshelf the proxies are in bookshelf-shared, which cannot see the classes of bookshelf-server, so they use @ProxyForName with the class name; the validation step (below) resolves the names on the server. The same applies to @Service and @ServiceName.

The Developer Guide’s rules, which the validation tool enforces at build time:

A proxy must map to a single domain type; every property of the proxy, including inherited ones, must exist on the domain type.
Proxies expose bean-style getters and setters only. Getters of proxy type return other proxies, never domain objects. Relations are not populated unless with("name") names them (dots reach nested properties, for example address.city).
getId() and getVersion() are optional on the proxy. Client code should prefer stableId(), whose EntityProxyId identifies the entity even before the server has assigned an id.
A ValueProxy need not expose an id or a version; it is copied by value (the guide’s example is an embedded address). A property whose type extends ValueProxy also has to be named in with() to be returned.
Types that may be used as properties and as request parameters and results are the transportable types: primitives and boxed primitives, String, Enum, BigInteger, BigDecimal, Date, entity and value proxies, and List, Set and Map of those.
Proxy types are available on the client when they are referenced from a context method, from another reachable proxy, are a proxy supertype of one, or are listed in @ExtraTypes on the factory, a context or a proxy.

The factory interface has one method per service stub:

public interface BookshelfRequestFactory extends RequestFactory {
  BookRequest bookRequest();

  ReviewRequest reviewRequest();
}

Source: GWT — Request Factory: RequestFactory Interface

RequestFactory also has find(EntityProxyId) (a request that loads one entity by its stable id), getEventBus(), getRequestTransport(), getHistoryToken(EntityProxyId) and getProxyId(String) (stable ids as strings, which fits History & Navigation and Places), and getSerializer(ProxyStore) for saving proxies locally. The last two were run: for the Bookshelf book with id 2 the history token and the serialised key were both IjIi@0@BOOK_PROXY_TYPE_TOKEN, a base64 JSON id, a strength digit and the type token, and deserialize(BookProxy.class, key) returned the proxy with the title "Effective Java".

The service side

A service stub extends RequestContext and names the server class that implements its methods.

@ServiceName("com.example.bookshelf.server.rf.BookEntity")
public interface BookRequest extends RequestContext {
  Request<Long> countBooks();

  Request<List<BookProxy>> findBookEntries(int firstResult, int maxResults);

  Request<BookProxy> findBook(Long id);

  InstanceRequest<BookProxy, Void> persist();

  InstanceRequest<BookProxy, Void> remove();
}

Source: GWT — Request Factory: RequestFactory Interface

The methods of the context do not return values; they return Request<T> objects whose fire(Receiver<T>) is the asynchronous call, like passing an AsyncCallback in GWT-RPC. The server class does not implement the context. It implements methods with the same names and arguments, mapped as follows (Developer Guide, confirmed by the run):

A method that returns Request<T> returns T on the server; proxy types become the domain types, so Request<List<BookProxy>> is List<BookEntity>.
Such a method is a static method of the service class, or an instance method of the object that a ServiceLocator returns.
A method that returns InstanceRequest<BookProxy, Void> is an instance method of the entity and takes no argument; the instance comes from using(proxy) on the client.
If the method is an instance method of a service (with a ServiceLocator) the proxy can instead be a normal argument.

An entity that implements its own persistence

The simplest server entity is a class with the four methods RequestFactory needs for every entity, plus the service methods. The persistence here is an in-memory BookStore; with JPA the service methods would use an EntityManager (see Spring Data JPA for the server side).

public class BookEntity {
  private Long id;
  private Integer version = 0;

  @NotNull
  @Size(min = 1, max = 200, message = "The title must have between 1 and 200 characters")
  private String title;
  @NotNull
  private String author;
  private int year;
  private Publisher publisher;

  public BookEntity() {}                                 // create

  public Long getId() { return id; }                     // getId
  public Integer getVersion() { return version; }       // getVersion

  public static BookEntity findBookEntity(Long id) {     // find: "find" + simple class name
    return BookStore.INSTANCE.find(id);
  }

  public static Long countBooks() { return BookStore.INSTANCE.count(); }

  public static List<BookEntity> findBookEntries(int firstResult, int maxResults) {
    return BookStore.INSTANCE.page(firstResult, maxResults);
  }

  public static BookEntity findBook(Long id) { return findBookEntity(id); }

  public void persist() { BookStore.INSTANCE.save(this); }

  public void remove() {
    requireRole("librarian");
    BookStore.INSTANCE.remove(id);
  }

  private static void requireRole(String role) {
    HttpServletRequest request = RequestFactoryServlet.getThreadLocalRequest();
    if (request == null || !request.isUserInRole(role)) {
      throw new SecurityException("Not allowed");
    }
  }
  // getters and setters omitted
}

Source: GWT — Request Factory: Implementing a service in an entity class

Table 5. The four methods RequestFactory needs for every entity, directly in the entity or in a `Locator`
Purpose	In the entity	In a `Locator<T, I>`
Create a new instance	A public no-argument constructor	`T create(Class<? extends T> clazz)`
Get the id	`id_type getId()`	`I getId(T domainObject)`
Find by id	A static method named "find" plus the simple class name, with the id as only parameter: `findBookEntity(Long)`	`T find(Class<? extends T> clazz, I id)`
Get the version	`Integer getVersion()` (any transportable type)	`Object getVersion(T domainObject)`

The Developer Guide table lists those four. The abstract Locator class in 2.13.1 also declares getDomainType() and getIdType(), which a concrete locator must implement, and a non-abstract isLive(T) that calls find. The version is how RequestFactory detects changes: the server answers each call with the entities whose version changed, and the client fires EntityProxyChange events for them. Measured: after persist() of the edited book the stored version went from 1 to 2, and the next load returned "version":2.

remove() checks the role on the server. The check is a servlet-container check on the thread-local request. Never rely on a client to hide a button: every service method that changes state or returns sensitive data needs its own server-side authorisation.

An entity without persistence code: Locator and ServiceLocator

When the domain class should stay free of persistence code, or several entities share one DAO, a Locator supplies the four methods and a ServiceLocator supplies the service instance. The Bookshelf ReviewEntity is such a class.

@ProxyForName(
    value = "com.example.bookshelf.server.rf.ReviewEntity",
    locator = "com.example.bookshelf.server.rf.ReviewLocator")
public interface ReviewProxy extends EntityProxy {
  Long getId();
  Long getBookId();
  void setBookId(Long bookId);
  int getStars();
  void setStars(int stars);
  String getComment();
  void setComment(String comment);
}

@ServiceName(
    value = "com.example.bookshelf.server.rf.ReviewService",
    locator = "com.example.bookshelf.server.rf.ReviewServiceLocator")
public interface ReviewRequest extends RequestContext {
  Request<List<ReviewProxy>> reviewsFor(Long bookId);

  Request<Void> save(ReviewProxy review);
}

public class ReviewLocator extends Locator<ReviewEntity, Long> {
  @Override public ReviewEntity create(Class<? extends ReviewEntity> clazz) { return new ReviewEntity(); }
  @Override public ReviewEntity find(Class<? extends ReviewEntity> clazz, Long id) { return ReviewService.REVIEWS.get(id); }
  @Override public Class<ReviewEntity> getDomainType() { return ReviewEntity.class; }
  @Override public Long getId(ReviewEntity domainObject) { return domainObject.getId(); }
  @Override public Class<Long> getIdType() { return Long.class; }
  @Override public Object getVersion(ReviewEntity domainObject) { return domainObject.getVersionNumber(); }
}

public class ReviewServiceLocator implements ServiceLocator {
  private static final ReviewService SERVICE = new ReviewService();

  @Override
  public Object getInstance(Class<?> clazz) {
    if (clazz != ReviewService.class) {
      throw new IllegalArgumentException("Unknown service");
    }
    return SERVICE;
  }
}

public class ReviewService {
  static final Map<Long, ReviewEntity> REVIEWS = new ConcurrentSkipListMap<>();

  public List<ReviewEntity> reviewsFor(Long bookId) { /* filter REVIEWS */ }

  public void save(ReviewEntity review) { /* validate stars 1..5, assign an id, store */ }
}

Source: GWT — Request Factory: Using Locator and ServiceLocator

The locator and the service locator need public no-argument constructors, and RequestFactory caches both and the service instance, so they must be thread-safe (Developer Guide). ValueLocator is a convenience subclass of Locator for value types: it fixes the identity methods to return null. Because the service is an instance, save(ReviewProxy) takes the proxy as an ordinary argument instead of using(). The run saved a review of book 1 and read it back; the ServiceLocator was used for both calls.

Calling it from the client

Creating, editing and persisting

BookRequest ctx = factory.bookRequest();
BookProxy book = ctx.create(BookProxy.class);        // a new, client-owned proxy
book.setTitle("Refactoring");
book.setAuthor("Martin Fowler");
book.setYear(1999);

PublisherProxy publisher = ctx.create(PublisherProxy.class);
publisher.setName("Addison-Wesley");
publisher.setCountry("US");
book.setPublisher(publisher);

ctx.persist().using(book).fire(new Receiver<Void>() {
  @Override
  public void onSuccess(Void ignored) { /* refresh the view */ }
});

Source: GWT — Request Factory: Using RequestFactory

Proxies are interfaces and have no constructor, so a new one is created with ctx.create(BookProxy.class) on the context that will send it. The entity and its publisher are created in the same context, so they travel together: RequestFactory sends the whole graph of one context in a single request. Whether the server saves the related object depends on the server code; the guide says the implementation of persist() is responsible for persisting related objects.

Objects that did not come from create must be made editable with edit(), in the context that will send them. The editable copy replaces the original, which can be discarded. Properties returned by the getters of an editable proxy are editable too.

What goes over the wire

The payload of the create above and of the edit that follows are shown below, as printed by the transport wrapper of the test. The type tokens and operation tokens are 28-character base64 digests derived from the interface and method names; they are replaced here by BOOK_PROXY_TYPE_TOKEN, PUBLISHER_PROXY_TYPE_TOKEN, PERSIST_OPERATION and FIND_BOOK_OPERATION.

>>> {"F":"com.example.bookshelf.shared.rf.BookshelfRequestFactory",
     "I":[{"P":[{"R":"1","C":1,"T":"BOOK_PROXY_TYPE_TOKEN"}],"O":"PERSIST_OPERATION"}],
     "O":[{"P":{"year":1999,"author":"Martin Fowler","publisher":{"R":"1","C":2,"T":"PUBLISHER_PROXY_TYPE_TOKEN"},"title":"Refactoring"},
           "R":"1","C":1,"T":"BOOK_PROXY_TYPE_TOKEN","O":"PERSIST"},
          {"P":{"country":"US","name":"Addison-Wesley"},"R":"1","C":2,"T":"PUBLISHER_PROXY_TYPE_TOKEN","O":"PERSIST"}]}
<<< {"S":[true],"I":[null],
     "O":[{"C":1,"S":"IjQi","T":"BOOK_PROXY_TYPE_TOKEN","V":"MS4w","O":"PERSIST"},
          {"R":"1","C":2,"T":"PUBLISHER_PROXY_TYPE_TOKEN"}]}

>>> {"F":"com.example.bookshelf.shared.rf.BookshelfRequestFactory",
     "I":[{"P":[{"S":"IjQi","T":"BOOK_PROXY_TYPE_TOKEN"}],"O":"PERSIST_OPERATION"}],
     "O":[{"P":{"year":2018},"S":"IjQi","T":"BOOK_PROXY_TYPE_TOKEN","V":"MS4w","O":"UPDATE"}]}
<<< {"S":[true],"I":[null],"O":[{"S":"IjQi","T":"BOOK_PROXY_TYPE_TOKEN","V":"Mi4w","O":"UPDATE"}]}

Source: GWT 2.13.1 source — requestfactory shared messages

The names are defined by annotated interfaces in the messages package, which are AutoBeans themselves:

Table 6. Keys of the request and response messages in 2.13.1
Key	Meaning
`F` in a request	The name of the `RequestFactory` interface
`I`	Invocations: one object per service call, with `O` the operation token, `P` the parameters, `R` the property references from `with()`. In a response, `I` holds the return value of each call
`O` at top level	Operations: the creates and edits of proxies, with `O` the write operation (`PERSIST` or `UPDATE`) and `P` the changed properties only
`T`, `C`, `S`, `V`, `Y`	Type token, client id, server id, version, synthetic id. `S` and `V` are base64 JSON strings: `IjQi` decodes to `"4"` and `MS4w` to `"1.0"`
`R` inside an id	Strength of the id: `"0"` persisted, `"1"` ephemeral (created by the client), `"2"` synthetic
`S` at top level of a response	A status per invocation: `true` or `false`
`X`	Violations (see below); also the exception type inside a failure object
`F` in a response	A general failure; inside a failure object `F` is the `fatal` flag and `M` the message

Two properties follow from the wire format. First, the edit sent "P":{"year":2018} only, not the other properties of the book: that is the delta behaviour the guide advertises, and the client test asserts it. Second, the server never calls a method by name. The operation token must be one the build-time validation recorded in the generated lookup class, so a request for any other method is rejected with No RequestContext for operation ... (see the pitfalls). That makes the payload a whitelist of the operations the interfaces declare, not a way to run arbitrary methods. It does not make it a substitute for authorisation.

Receivers, failures and violations

Receiver<V> is an abstract class. onSuccess is abstract; onFailure(ServerFailure) throws a RuntimeException for a fatal failure unless you override it; onConstraintViolation(Set<ConstraintViolation<?>>) is the current way to receive validation errors, and onViolation(Set<Violation>) and the Violation interface are deprecated in 2.13.1.

ctx.persist().using(book).fire(new Receiver<Void>() {
  @Override public void onSuccess(Void v) { /* ... */ }

  @Override public void onFailure(ServerFailure f) {
    showError(f.getMessage());                       // never f.getStackTraceString() in the UI
  }

  @Override public void onConstraintViolation(Set<ConstraintViolation<?>> violations) {
    for (ConstraintViolation<?> v : violations) {
      showFieldError(v.getPropertyPath().toString(), v.getMessage());
    }
  }
});

Source: GWT — Request Factory: Validating Entities

Measured outputs:

Table 7. Results of the failure cases in the Bookshelf run
Call	Outcome
`persist()` of a book with an empty title, Hibernate Validator on the server	`onConstraintViolation` called with `title -> The title must have between 1 and 200 characters`. The response has an `X` member with the path `title` and the message, and no `S` status: the method was not called
The same call with a `Receiver` that does not override `onConstraintViolation`	`com.google.web.bindery.event.shared.UmbrellaException: Exception caught: The call failed on the server due to a ConstraintViolation`: the default `onConstraintViolation` calls the deprecated `onViolation`, which calls `onFailure`, which throws because the failure is fatal
`remove()` without the `librarian` role	`onFailure` with `Server Error: Not allowed`, `isFatal()` true, no exception type and no stack trace. The HTTP status of the response was 200: the failure is inside the JSON
The same, with a servlet whose processor has a custom `ExceptionHandler` that returns `new ServerFailure("Server Error", null, null, false)`	`Server Error`, `isFatal()` false: no exception message reaches the browser and no exception is thrown by the default `onFailure`

The default handler (DefaultExceptionHandler) builds the message as "Server Error: " plus the exception message, so a message such as a SQL error or a path would be shown to the user. Provide an ExceptionHandler to new SimpleRequestProcessor(...) or to the servlet constructor RequestFactoryServlet(ExceptionHandler, ServiceLayerDecorator...) that logs the exception and returns a generic message.

Validation on the server

Before calling a method, RequestFactory validates the entities of the request with a JSR-303 (Bean Validation 1.0) provider found with Validation.byDefaultProvider().configure(). The relevant class is ReflectiveServiceLayer.

RequestFactory 2.13.1 uses the javax.validation namespace. A provider in the jakarta.validation namespace (Hibernate Validator 7 and later) is not seen by it; Validation describes how to keep constraints for both namespaces.
If no provider can be created, ValidationException is caught and logged at INFO ("Unable to initialize a JSR 303 Bean Validator") and no validation happens. Any other Error from the provider’s start-up is not caught.
The system property gwt.validation.ignoreXml=true makes the server skip validation.xml. With Hibernate Validator 4.1.0.Final on JDK 21 the start-up fails without it because the provider needs JAXB (see the pitfalls). Validation has the details of the property for compile, test and code server runs.

See Validation for the client-side validation framework and for sharing constraints, and Editors for RequestFactoryEditorDriver, which edits a proxy graph and shows the violations next to the fields.

Events, batching and saving proxies

Every time the client sees an entity for the first time or sees its version change, the factory fires an EntityProxyChange on the EventBus given to initialize. A handler registers per proxy type:

EntityProxyChange.registerForProxyType(factory.getEventBus(), BookProxy.class,
    new EntityProxyChange.Handler<BookProxy>() {
      @Override
      public void onProxyChange(EntityProxyChange<BookProxy> event) {
        refresh(event.getProxyId(), event.getWriteOperation());   // PERSIST, UPDATE or DELETE
      }
    });

Source: GWT — Request Factory: Implementing a service in an entity class

In the run, loading book 2 and then persisting a change to it produced two events, both UPDATE BookProxy: the first when the entity was first received, the second when its version changed.

Two contexts can be sent together with append. The run sent countBooks() and reviewsFor(1L) of two services in one HTTP request:

BookRequest books = factory.bookRequest();
ReviewRequest reviews = books.append(factory.reviewRequest());
books.countBooks().to(countReceiver);
reviews.reviewsFor(1L).to(reviewsReceiver);
books.fire();

>>> {"F":"com.example.bookshelf.shared.rf.BookshelfRequestFactory","I":[{"O":"COUNT_BOOKS_OPERATION"},{"P":["1"],"O":"REVIEWS_FOR_OPERATION"}]}
<<< {"S":[true,true],"I":["3",[]]}

Source: GWT — RequestContext (Javadoc)

RequestBatcher (in requestfactory.gwt.client) automates this: get() returns the open context and schedules the fire at the end of the current event loop turn. Request.fire() on a context that is already in flight throws IllegalStateException: A request is already in progress.

Transport, security and CSRF

DefaultRequestTransport POSTs the payload with RequestBuilder to the host page base URL followed by gwtRequest, with Content-Type: application/json; charset=utf-8 and two extra headers (pageurl and the permutation strong name). Change the URL with setRequestUrl, or replace the transport, which is also how to add headers.

The servlet insists on the content type: a request with Content-Type: text/plain returned HTTP 500 with jakarta.servlet.ServletException: Content-Type was 'text/plain'. Expected 'application/json'. A cross-site HTML form cannot set that content type, and a cross-site script needs a CORS preflight to send it, which is a useful barrier but not a CSRF defence you should rely on alone (CORS explains the preflight). GWT’s RPC token mechanism (RpcToken, XsrfProtectedService) does not apply to RequestFactory; XSRF, RPC & Server Security describes the RPC side.

The Bookshelf adds a per-session token that the page gives to the client (for example in a dynamic host page) and that a filter checks on every POST to /gwtRequest:

public class CsrfRequestTransport extends DefaultRequestTransport {
  private final String token;

  public CsrfRequestTransport(String token) { this.token = token; }

  @Override
  protected void configureRequestBuilder(RequestBuilder builder) {
    super.configureRequestBuilder(builder);
    builder.setHeader("X-Bookshelf-Csrf", token);
  }
}

// server: servlet filter mapped to /gwtRequest and /csrf
String sent = request.getHeader("X-Bookshelf-Csrf");
if (sent == null || !MessageDigest.isEqual(sent.getBytes(), token.getBytes())) {
  response.sendError(HttpServletResponse.SC_FORBIDDEN);
  return;
}
chain.doFilter(req, resp);

Source: GWT — DefaultRequestTransport (Javadoc)

The filter is application code, not part of GWT. Measured: GET /csrf with a new session returned a 32-character token and a JSESSIONID cookie; a POST without the header returned 403; with the header it returned 200 and the JSON response. The token is the one placeholder-style value used here; the real one is random per session.

Other points for a RequestFactory endpoint:

Authentication and authorisation belong on the server. Protect /gwtRequest with the container’s security constraints or a filter, and check roles in the service methods as remove() does. The proxies tell the client what may be requested, not what may be done.
Expose only what the client needs. The proxy is the whitelist of properties the client can read and write, and every property of it travels whenever the entity is returned. The Developer Guide’s own EmployeeProxy declares getPassword(); do not copy that. Keep password hashes, internal flags and other users' data out of proxies, and never map a JPA entity directly to a proxy without choosing its properties.
No built-in limit on the request. In the run a 2 MB body was handed to the processor and failed only because its factory name (x) could not be resolved (HTTP 500, Could not locate class x in the log). Set a body-size limit in the container or a filter. An open GitHub issue, gwtproject/gwt#10385 (opened 2026-07-31, labelled NeedsInfo and still under discussion on 2026-10-09), reports that SimpleRequestProcessor applies no bound to the number of operations and invocations in one request; until that is settled, limit the size at the edge.
Exception messages reach the browser (see the previous section).
Log what you need on the server and keep stack traces out of the response, which is the default.

The validation tool: requestfactory-apt

The server finds out what the client interfaces mean from a class that is generated at build time, not by reflection over the proxies. The class is called <RequestFactory interface>DeobfuscatorBuilder (for the Bookshelf, com.example.bookshelf.shared.rf.BookshelfRequestFactoryDeobfuscatorBuilder) and is produced by RfValidator, the annotation processor in requestfactory-apt. It checks that every proxy property and every context method has a counterpart on the domain classes and the services, then writes the lookup of operation tokens, type tokens and the client-to-domain mapping. If the class does not exist at run time the server cannot process any request.

The Developer Guide does not mention it. The 2.4.0 release notes mention a "RequestFactoryInterfaceValidator" that is not enabled by default and point to a wiki page; the usage text of the tool still prints an address of that wiki on the retired code.google.com project hosting, which now redirects to the Google Code Archive.

There are two ways to run it.

As an annotation processor in the module that sees both the interfaces and the domain classes. The Bookshelf interfaces are in bookshelf-shared but the domain classes are in bookshelf-server, so the processor runs when bookshelf-server compiles, with the rootOverride option naming the factory to scan (the processor otherwise scans only the sources of the compilation):

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>org.gwtproject.web.bindery</groupId>
        <artifactId>requestfactory-apt</artifactId>
        <version>2.13.1</version>
      </path>
    </annotationProcessorPaths>
    <compilerArgs>
      <arg>-ArootOverride=com.example.bookshelf.shared.rf.BookshelfRequestFactory</arg>
    </compilerArgs>
  </configuration>
</plugin>

Source: GWT 2.13.1 source — RfValidator.java

The processor’s supported options are rootOverride (a comma-separated list of binary names), suppressErrors, suppressWarnings and verbose. After the build the generated class was in target/classes and in target/test-classes (the test compilation runs the processor too).

As a command-line tool on compiled classes. ValidationTool takes an output directory or jar and the factory names:

java -cp requestfactory-apt-2.13.1.jar:requestfactory-client-2.13.1.jar:bookshelf-server/target/classes:bookshelf-shared/target/classes:validation-api-1.0.0.GA.jar \
  com.google.web.bindery.requestfactory.apt.ValidationTool /tmp/rf-validated.jar \
  com.example.bookshelf.shared.rf.BookshelfRequestFactory

It exited with 0 and the jar contained BookshelfRequestFactoryDeobfuscatorBuilder.class. With -client as first argument it generates the ...DeobfuscatorBuilderLite class, for clients that run on a JVM without the domain classes. The tool needs a JDK, not a JRE.

Source: GWT — ValidationTool (Javadoc)

What the validation reports, measured by adding a bad property and bad methods to the Bookshelf interfaces:

[ERROR] Could not find domain method similar to java.lang.String missing()
[ERROR] Could not find domain method similar to java.lang.Long countBooks(java.lang.String)
[ERROR] Could not find domain method similar to java.lang.String getIsbn()
[ERROR] Domain type com.example.bookshelf.server.rf.Publisher does not have a getId() method
[ERROR] Domain type com.example.bookshelf.server.rf.Publisher does not have a getVersion() method

The last two appear when PublisherProxy is changed from ValueProxy to EntityProxy: an entity needs an id and a version on the domain type. The processor failed the Maven build for the server module, so the mismatch is found at build time, not by the first user.

@SkipInterfaceValidation (on a method, type or package) excludes a declaration from the check; use it sparingly because it removes the guarantee. A GitHub issue reports that the processor fails with Java records in client code (gwtproject/gwt#10114, opened 2025-04-11, still open on 2026-10-09).

The Bookshelf worked example

The scratch application is the three-module Bookshelf of Project Structure & Modules with the files below added.

Table 8. Files of the RequestFactory example
File	Content
`bookshelf-shared/.../shared/rf/`	`BookshelfRequestFactory`, `BookRequest`, `BookProxy`, `PublisherProxy`, `ReviewRequest`, `ReviewProxy`
`bookshelf-server/.../server/rf/`	`BookEntity`, `Publisher`, `BookStore`, `ReviewEntity`, `ReviewLocator`, `ReviewService`, `ReviewServiceLocator`, `RfCsrfFilter`
`bookshelf-client/.../client/rf/`	`BookshelfData`, `CsrfRequestTransport`
`bookshelf-client/src/main/module.gwt.xml`	The two `<inherits>` lines for RequestFactory and AutoBean
`bookshelf-server/pom.xml`	`validation-api`, Hibernate Validator 4.1.0.Final and `slf4j` at runtime, `requestfactory-apt` on the processor path
`bookshelf-server/src/main/webapp/WEB-INF/web.xml`	The filter and the `jakarta` servlet mapped to `/gwtRequest` (and `/csrf` for the token)
`bookshelf-server/src/test/.../BookRequestFactoryTest.java`	Eight JUnit tests running the real client and server in one JVM
`bookshelf-client/src/test/.../RfGwtTest.java`	`GWTTestCase` tests that run the generated client in HtmlUnit against canned replies

The commands used, from the root of the scratch application (JDK 21):

# server tests: the real client and server in one JVM, plus the AutoBean tests
mvn -B -pl bookshelf-server -am test -Dtest='BookRequestFactoryTest,AutoBeanJvmTest' \
    -Dsurefire.failIfNoSpecifiedTests=false -DargLine="-Dgwt.validation.ignoreXml=true"

# generated client and AutoBeans in HtmlUnit, then the full production compile
mvn -B -pl bookshelf-client -am verify -Dtest=RfGwtTest -Dsurefire.failIfNoSpecifiedTests=false

# the servlet on port 8935 (the property is for the Maven JVM that runs Jetty)
MAVEN_OPTS="-Dgwt.validation.ignoreXml=true" mvn -B -pl bookshelf-server -am -Denv=dev \
    -DskipTests package jetty:run -Djetty.http.port=8935

Source: gwt-maven-plugin documentation

Results: 17 server-side tests passed (9 AutoBean, 8 RequestFactory), the 3 GWTTestCase tests passed, and the 6-permutation production compile of the whole application succeeded.

The server-side tests use no HTTP:

RequestTransport inner =
    new InProcessRequestTransport(new SimpleRequestProcessor(ServiceLayer.create()));
BookshelfRequestFactory rf = RequestFactorySource.create(BookshelfRequestFactory.class);
rf.initialize(new SimpleEventBus(), inner);

Source: GWT — RequestFactorySource (Javadoc)

The client test replaces the transport by one that records what the generated client sends and answers with a payload that the real servlet returned:

static class Replay implements RequestTransport {
  final List<String> sent = new ArrayList<String>();
  final List<String> replies = new ArrayList<String>();

  @Override
  public void send(String payload, TransportReceiver receiver) {
    sent.add(payload);
    receiver.onTransportSuccess(replies.remove(0));
  }
}

Source: GWT — RequestTransport.send (Javadoc)

In HtmlUnit the generated client sent the payload below for load(0, 1, ...) and, after changeYear, a payload containing "P":{"year":2018}. The operation and type tokens computed by the generated JavaScript client were identical to those the JVM client and the server computed; the key order differs only in that the browser writes "O" before "P".

{"F":"com.example.bookshelf.shared.rf.BookshelfRequestFactory","I":[{"O":"FIND_BOOK_ENTRIES_OPERATION","P":[0,1],"R":["publisher"]}]}

The HTTP side was driven with curl against Jetty:

TOKEN=$(curl -s -c cookies.txt http://localhost:8935/csrf)
curl -s -b cookies.txt -H 'Content-Type: application/json; charset=utf-8' -H "X-Bookshelf-Csrf: $TOKEN" \
  -d '{"F":"com.example.bookshelf.shared.rf.BookshelfRequestFactory","I":[{"P":[0,2],"O":"FIND_BOOK_ENTRIES_OPERATION"}]}' \
  http://localhost:8935/gwtRequest

Source: GWT — Request Factory: Wiring

The response was HTTP 200, Content-Type: application/json;charset=utf-8, with the two first books. A second persist and the validation failure behaved as in the in-process tests. The full application (6 permutations) also compiled with RequestFactory and AutoBeans inherited.

AutoBeans

AutoBeans are the framework RequestFactory is built on, and they are useful on their own: the Developer Guide describes them as automatically generated implementations of bean-like interfaces plus a low-level serialisation mechanism for them. The goals it lists are less boilerplate in model-rich applications, easy encoding to JSON, support code for common operations on data-model objects, and use in non-GWT code such as a server. Its non-goals are non-DAG data structures and object-identity semantics.

Interfaces, a factory and the codex

public interface BookMeta {
  String getTitle();
  void setTitle(String title);

  List<String> getAuthors();
  void setAuthors(List<String> authors);

  @PropertyName("first_published")
  int getFirstPublished();
  @PropertyName("first_published")
  void setFirstPublished(int year);

  PublisherMeta getPublisher();
  void setPublisher(PublisherMeta publisher);

  Map<String, String> getTags();
  void setTags(Map<String, String> tags);
}

public interface PublisherMeta {
  String getName();
  void setName(String name);
  String getCity();
  void setCity(String city);
}

public interface MetaFactory extends AutoBeanFactory {
  AutoBean<BookMeta> bookMeta();
  AutoBean<PublisherMeta> publisherMeta();
  AutoBean<PublisherMeta> publisherMeta(PublisherMeta toWrap);   // wraps an existing object
}

MetaFactory factory = GWT.create(MetaFactory.class);              // JVM: AutoBeanFactorySource.create(MetaFactory.class)

AutoBean<BookMeta> bean = AutoBeanCodex.decode(factory, BookMeta.class, json);
BookMeta book = bean.as();                                        // the interface shim
book.setTitle("Clean Code, 2nd draft");
String out = AutoBeanCodex.encode(bean).getPayload();            // back to JSON

Source: GWT — AutoBeans: Quickstart

Input and output of the run (JVM; the same encode in the browser engine produced the same members in a different order):

{"title":"Clean Code","authors":["Robert C. Martin"],"first_published":2008,"publisher":{"name":"Prentice Hall","city":"Upper Saddle River"},"tags":{"genre":"programming"},"unknown":true}
{"publisher":{"city":"Upper Saddle River","name":"Prentice Hall"},"title":"Clean Code, 2nd draft","first_published":2008,"authors":["Robert C. Martin"],"tags":{"genre":"programming"}}

Unknown members of the input ("unknown":true) are ignored on decode and not written again (they remain visible through a Splittable). The name of a property in JSON is the Java Beans name, with @PropertyName overriding it on a getter, a setter, a method parameter or an enum constant.

Table 9. The AutoBean API in 2.13.1
Type	What it does
`AutoBean<T>`	The controller of a bean. `as()` returns the interface shim, `getType()`, `getFactory()`, `accept(AutoBeanVisitor)`, `getTag`/`setTag`, `isFrozen`/`setFrozen`, `isWrapper`/`unwrap`. The shim is separate so that the controller’s methods cannot clash with a bean’s own method names
`AutoBeanFactory`	Interface with methods that return `AutoBean<Foo>`; may take one argument to wrap an existing object. `create(Class)` and `create(Class, delegate)` take the type at run time. Only the factory is created with `GWT.create` or `AutoBeanFactorySource.create`
`@AutoBeanFactory.Category`, `@AutoBeanFactory.NoWrap`	A category implements non-property methods; `NoWrap` disables the automatic wrapping of reference values returned by a delegate
`AutoBeanCodex`	`decode(factory, type, String or Splittable)`, `decodeInto(Splittable, AutoBean)`, `encode(AutoBean)` returning a `Splittable`
`Splittable`	The wire value: backed by a `JavaScriptObject` on the client and, on the JVM, by a JSON class bundled in GWT (`com.google.gwt.thirdparty.json`; the guide says `org.json`). `getPayload()`, `get`, `getPropertyKeys`, `asString`/`asNumber`/`asBoolean`, `isKeyed`/`isIndexed`, `deepCopy`
`AutoBeanUtils`	`getAutoBean(shim)`, `diff(a, b)`, `deepEquals(a, b)`, `getAllProperties(bean)`
`AutoBeanVisitor`	Reflection-like traversal: `visit`, `visitValueProperty`, `visitReferenceProperty`, `visitCollectionProperty`, `visitMapProperty` and the `endVisit` counterparts, each given a `PropertyContext`
`AutoBeanFactorySource`	JVM only: `create(Class<F>)`. Replaces `GWT.create` in server code and plain unit tests

The property types the Developer Guide allows are primitives and boxed primitives, BigInteger, BigDecimal, java.util.Date, enums, String, other bean interfaces, and List, Set and Map of those.

What the run showed

frozen: java.lang.IllegalStateException: The AutoBean has been frozen
tag: cache, in payload? false
clone: java.lang.UnsupportedOperationException
isWrapper=true pojo.name=Pearson unwrap==pojo true json={"city":"Upper Saddle River","name":"Pearson"}
after unwrap: java.lang.IllegalStateException: The AutoBean has been unwrapped
splittable: kind=book title=Clean Code keys=[publisher, title, first_published, authors, tags, unknown]
category: Book: Refactoring
diff: {publisher={"city":"Upper Saddle River","name":"Prentice Hall"}, title=Clean Code 2, first_published=2009, tags=...SplittableSimpleMap@23bb8443}
all: [publisher, title, first_published, authors, tags]
ref publisher -> PublisherMeta
value name=Prentice Hall (String)
collection authors of String
map tags String->String

setFrozen(true) makes every setter throw IllegalStateException: The AutoBean has been frozen. Proxies received from RequestFactory are frozen in the same way until edit().
Tags are metadata kept beside the bean (setTag/getTag); they are not part of the JSON.
clone(boolean) is deprecated with no replacement and throws UnsupportedOperationException, although the Developer Guide still lists it. Copy by encoding and decoding, or with decodeInto.
Wrapping (factory.publisherMeta(pojo)) makes the AutoBean a controller around an existing object: a setter on the shim changed the POJO. After unwrap() the AutoBean is unusable.
Splittable properties delay decoding. The envelope Shelf has a Splittable payload; the receiver reads kind, picks the factory for the payload and calls AutoBeanCodex.decode(factory, BookMeta.class, payload).
Categories give implementations to methods that are not getters or setters. A bean with such a method needs the factory annotated @Category(DescribableCategory.class), and the category has a public static method of the same name with the AutoBean as extra first parameter. According to the guide, a category may also declare a method named __intercept(AutoBean<?>, T) that sees the return value of every non-void method, and RequestFactory uses it to make proxies returned from an editable object editable (this was not run here).
AutoBeanVisitor visited the reference property, then the value properties of the nested bean, then the collection and the map, with the element and key types.
diff is shallow and compares references. It reported publisher and tags as changed although only title and first_published were; in the browser engine it printed [publisher, title, tags]. Compare nested values yourself or use deepEquals.
deepEquals differs between the JVM and the browser engine for maps. Two beans decoded from the same JSON with a Map property were deepEquals false on the JVM and true in HtmlUnit; with only value, list or nested-bean properties it was true in both. Do not depend on it for maps.

Errors on bad input

JVM:     java.lang.RuntimeException: Could not parse payload
Browser: java.lang.IllegalArgumentException: Error parsing JSON: SyntaxError: Empty JSON string
JVM:     java.lang.NullPointerException: Cannot invoke "java.lang.Double.doubleValue()" because "this.number" is null   (for "first_published":"abc")
Browser: 0   (the same input)

Decoding is not strict: a string where a number is expected gave a NullPointerException on the JVM and 0 in the browser engine, both without a message that names the property. Validate untrusted JSON (size, depth, ranges) before relying on the decoded values, and wrap decoding in a try/catch (RuntimeException).

Where AutoBeans fit

Option Good for Costs

Option	Good for	Costs
AutoBeans	Typed JSON on both client and server with one set of interfaces; shared models; RequestFactory	Generated code per factory and type; interfaces cannot have extra fields; limited error messages (above)
Overlay types or JsInterop native types	Reading a JSON document without copying it	Client only; no server counterpart; see RequestBuilder, JSON & XML
`JSON.parse` plus `@JsType(isNative = true)` DTOs	Small payloads and J2CL-friendly code	Client only
A server JSON library (Jackson, Gson) with GWT-compatible DTOs	The server side of a REST API	The client needs another mechanism; see REST & JSON Libraries

AutoBeans

Typed JSON on both client and server with one set of interfaces; shared models; RequestFactory

Generated code per factory and type; interfaces cannot have extra fields; limited error messages (above)

Overlay types or JsInterop native types

Reading a JSON document without copying it

Client only; no server counterpart; see RequestBuilder, JSON & XML

JSON.parse plus @JsType(isNative = true) DTOs

Small payloads and J2CL-friendly code

Client only

A server JSON library (Jackson, Gson) with GWT-compatible DTOs

The server side of a REST API

The client needs another mechanism; see REST & JSON Libraries

RequestBuilder, JSON & XML describes JsonUtils, JSONParser, overlay types and JsInterop DTOs, and REST & JSON Libraries describes the libraries that generate the client; AutoBeans are the option that needs only GWT.

Pitfalls

Table 10. Common problems with RequestFactory and AutoBeans, with the messages that were reproduced
Symptom	Cause	Fix
Server: `java.lang.RuntimeException: The RequestFactory ValidationTool must be run for the com.example.bookshelf.shared.rf.BookshelfRequestFactory RequestFactory type` on the first request	The `...DeobfuscatorBuilder` class was never generated (annotation processor not on the path, or run in a module that cannot see the factory)	Add `requestfactory-apt` to `annotationProcessorPaths` of the module with the domain classes and `-ArootOverride=<factory>`, or run `ValidationTool`
Build: `Could not find domain method similar to java.lang.String getIsbn()`	The proxy declares a property that the domain class has no getter for	Add the property to the domain class or remove it from the proxy
Build: `Could not find domain method similar to java.lang.Long countBooks(java.lang.String)`	A context method has no static or instance method with the same name and parameters (domain types in place of proxies)	Add the server method with the mapped signature
Build: `Domain type com.example.bookshelf.server.rf.Publisher does not have a getId() method`	An `EntityProxy` was mapped to a class without `getId()` and `getVersion()` (or a `Locator`)	Make it a `ValueProxy`, or add the methods or a locator
Server log: `com.google.web.bindery.requestfactory.server.UnexpectedException: Could not find static method with a single parameter of a key type`	The entity has no finder named "find" plus its simple class name (`findBookEntity(Long)`); `findBook` is only the service method	Add the finder or a `Locator`
GWT compile: `No source code is available for type com.google.web.bindery.requestfactory.shared.RequestContext; did you forget to inherit a required module?`	The module with the shared sources does not inherit `com.google.web.bindery.requestfactory.RequestFactory`	Add the `<inherits>` line (and `com.google.web.bindery.autobean.AutoBean` for AutoBeans)
Jetty: `java.lang.ClassNotFoundException: com.google.web.bindery.requestfactory.server.RequestFactoryServlet` followed by `jakarta.servlet.UnavailableException: Class loading error for holder requestFactoryServlet`	The `javax` servlet class named in `web.xml` (as in the Developer Guide) with only `gwt-servlet-jakarta` on the classpath; the `javax` class could not run in this container anyway	Use `com.google.web.bindery.requestfactory.server.jakarta.RequestFactoryServlet`
Jetty plugin warnings: `com.google.gwt.thirdparty.guava.common.annotations.Beta scanned from multiple locations`	`gwt-servlet-jakarta` and `requestfactory-server-jakarta` both on the classpath	Keep one of them
HTTP 500, `jakarta.servlet.ServletException: Content-Type was 'text/plain'. Expected 'application/json'.`	A client or test posts with another content type	Send `application/json; charset=utf-8`, as `DefaultRequestTransport` does
HTTP 500 and the log `No RequestContext for operation AAAAAAAAAAAAAAAAAAAAAAAAAAA=`	The operation token is not in the generated lookup (an old client, a different interface version, or a request that was not built by RequestFactory)	Redeploy client and server together; the token changes when names change
Server start-up: `java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException` from `ReflectiveServiceLayer`	Hibernate Validator 4.1 reads `validation.xml` with JAXB, which is not in JDK 11 and later	`-Dgwt.validation.ignoreXml=true` on the server JVM, or a provider that does not need JAXB
`UmbrellaException: Exception caught: The call failed on the server due to a ConstraintViolation` in the browser	The `Receiver` does not override `onConstraintViolation` and the failure is fatal	Override `onConstraintViolation` (not the deprecated `onViolation`)
`java.lang.IllegalStateException: The AutoBean has been frozen` when calling a setter	The proxy came from the server and was not passed to `edit()`	Call `ctx.edit(proxy)` and change the copy
`java.lang.IllegalStateException: A request is already in progress`	`fire()` was called twice on one context	Create a new context per request
`java.lang.IllegalArgumentException: Attempting to edit an EntityProxy previously edited by another RequestContext`	A proxy created or edited in one context was used in another	Edit or create the proxy in the context that will send it
The browser shows `Server Error: <exception message>`	`DefaultExceptionHandler` copies the message of every exception	Provide an `ExceptionHandler` that returns a generic message
`java.lang.UnsupportedOperationException` from `AutoBean.clone`	The method is deprecated with no replacement	Encode and decode, or use `decodeInto`

Maintenance status and when not to start new code with it

What is verified (2026-10-09):

Published and built. The 2.13.1 BOM imports the requestfactory pom; requestfactory-client has been released for every version from 2.10.0 to 2.13.1 under org.gwtproject.web.bindery (Maven Central metadata, last updated 2026-06-19), the -server, -server-jakarta and -apt jars of 2.13.1 were downloaded and inspected, and the Jakarta artifacts were added in 2.11.0. The 2.12.0 release notes list the removal of the RequestFactoryJarExtractor class from the release jars.
Not deprecated. RequestFactory, RequestContext, EntityProxy, ValueProxy, Locator and the annotations carry no @Deprecated in the 2.13.1 source. The deprecated members are Receiver.onViolation, Violation, RequestFactoryEditorDriver.setViolations, AutoBean.clone and ValueCodex.decode(Class, String).
No official notice. The Developer Guide page, the release notes and the roadmap contain no statement that RequestFactory is deprecated or in maintenance mode, and none was found elsewhere on gwtproject.org. The roadmap does not mention it at all. This page therefore does not claim any official status.
Activity is housekeeping and small fixes. Eleven commits touched the requestfactory source directory between 2024-01-01 and 2026-10-09: formatting, Checkstyle, Javadoc, the Java 17 language level (2026-06-24), removal of deprecated or internal types, and making jaxb optional for the validation tests. Fixes in the AutoBean code in that period are for Java 21 (a List<Integer> property in ProxyAutoBean, 2024-01-31), a bytecode size limit in initializeEnumMap() (2024-07-16), and thread-safe date parsing in StringQuoter (gwtproject/gwt#10322, 2026-06-25). The last change to SimpleRequestProcessor.java that GitHub lists is from 2013-10-18.
Open issues. Among others: #10385 (no bound on operations and invocations), #10114 (requestfactory-apt fails with records), #9686 (the JSR-303 layer on Java 9 and later, opened 2020) and #9289 (default methods on proxies).
The Developer Guide is old. It describes the 2.1 design, still shows javax and the onViolation callback, says "in future articles" about cell widgets and Editors, and does not mention the build-time validation.

What is not verified: there is no statement from the GWT steering committee on the future of RequestFactory, and this page does not repeat the common claim that it is in maintenance mode.

An opinion, not an official position, but each point follows from the facts above:

Do not start new code with it unless you need its model. The model (entities with identity, deltas, EntityProxyChange events, joined contexts) is what you would be buying. If you need only to read and write JSON, GWT-RPC (for a GWT-only client and server) or plain JSON over HTTP with a typed client (for a client that other consumers share) is simpler, and a JSON API can be used by tools, tests and non-GWT clients.
It binds you to GWT on the server. The protocol is a private format whose only specification is the source, and the servlet is not a place for a Spring Boot or Quarkus controller; a REST backend can be reused, a RequestFactoryServlet cannot.
It binds you to old validation. JSR-303 in the javax namespace is what 2.13.1 reads; the rest of the Java ecosystem has moved to jakarta.validation.
The tooling is brittle. A forgotten annotation processor fails at the first request, not at the build, and a records issue is open.
The documentation is thin. Anything beyond the Developer Guide is found in the source.
Keep it where it already runs. An existing application that works needs no urgent change; plan a replacement when the model no longer fits or when the validation namespace or the servlet container forces the issue.

Use RequestFactory for a new project only when most of this is true: the application is GWT-only on both sides, the data is naturally a graph of entities with versions, you will use the EventBus change events and joined contexts, the team already knows it, and a documented REST API is not a requirement. Otherwise use the options on Client–Server Communication, GWT-RPC, RequestBuilder, JSON & XML and REST & JSON Libraries.

Where older material is outdated

GWT in Action (Manning, 2007) was written for GWT 1.3 and 1.4. RequestFactory appeared with GWT 2.1 (the Developer Guide calls it the heart of the "Bindery" features of 2.1, and the 2.1.0 release candidate notes already list fixes for it) and the AutoBeans guide refers to 2.1.1 and 2.2, so the book has no coverage of either (its extracted text contains neither name); its data-transfer chapters concern GWT-RPC, which is what the first edition recommends.
The Developer Guide’s web.xml uses the javax servlet class; for Servlet 5 or 6 use the jakarta class (since 2.11.0).
The guide’s dependency list names requestfactory-server.jar and a validator-api-1.0.0.GA.jar; in Maven the artifacts are org.gwtproject.web.bindery:requestfactory-server(-jakarta) or gwt-servlet(-jakarta), and javax.validation:validation-api.
The guide uses Receiver.onViolation; use onConstraintViolation.
The guide’s Locator table lists four methods; the abstract class also requires getDomainType() and getIdType().
The AutoBeans guide lists clone(); it throws UnsupportedOperationException and is deprecated. It says that AutoBeanFactorySource was called AutoBeanFactoryMagic in 2.1.1 and 2.2 (its text mentions AutoBeanMagicSource, which is a slip); the class in 2.13.1 is AutoBeanFactorySource.
The tool’s own usage text points to a wiki page on the retired code.google.com hosting (now in the Google Code Archive).

What changed recently

2.1.0 (RC1 notes): the first RequestFactory fixes; 2.1.1: a service layer added to RequestFactory (#5111).
2.4.0: polymorphism (#5367), service inheritance on the client (#6234), RequestFactoryEditorDriver work (#6081), more compact type tokens (#5394), and the interface validation tooling.
2.6.0 (RC1 notes): Map support, enums as type parameters, EntityProxyId as a request parameter. 2.7.0 (RC1 notes): better handling of overridden methods and generics, @SkipInterfaceValidation on context methods.
2.11.0 (2024-01-09): requestfactory-server-jakarta and gwt-servlet-jakarta.
2.12.0: RequestFactoryJarExtractor no longer included in release jars.
2.13.0 (2026-02-11): JAXB and xml-apis optional when gwt.validation.ignoreXml is set (Validation).
2.13.1 (2026-06-19): latest release.

RequestFactory & AutoBeans

The idea in one example

RequestFactory compared with the other options

Artifacts and setup

The module file

The servlet

The moving parts

Proxies and the RequestFactory interface

The service side

An entity that implements its own persistence

An entity without persistence code: Locator and ServiceLocator

Calling it from the client

Creating, editing and persisting

What goes over the wire

Receivers, failures and violations

Validation on the server

Events, batching and saving proxies

Transport, security and CSRF

The validation tool: requestfactory-apt

The Bookshelf worked example

AutoBeans

Interfaces, a factory and the codex

What the run showed

Errors on bad input

Where AutoBeans fit

Pitfalls

Maintenance status and when not to start new code with it

Where older material is outdated

What changed recently

References