Reviewers: rjrjr,
Description:
Resolve GWT issue 5361.
Document the GwtEvents associated with a RequestFactory.
Patch by: bobv
Review by: rjrjr
Please review this at http://gwt-code-reviews.appspot.com/988802/show
Affected files:
M
user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
M user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
Index:
user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
===================================================================
---
user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
(revision 9065)
+++
user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
(working copy)
@@ -25,9 +25,9 @@
import com.google.gwt.http.client.RequestException;
import com.google.gwt.http.client.Response;
import com.google.gwt.requestfactory.shared.RequestEvent;
+import com.google.gwt.requestfactory.shared.RequestEvent.State;
import com.google.gwt.requestfactory.shared.RequestFactory;
import com.google.gwt.requestfactory.shared.RequestTransport;
-import com.google.gwt.requestfactory.shared.RequestEvent.State;
import com.google.gwt.user.client.Window.Location;
import java.util.logging.Level;
@@ -36,6 +36,18 @@
/**
* An implementation of {...@link RequestTransport} that uses a
* {...@link RequestBuilder}.
+ * <p>
+ * This implementation will send {...@link RequestEvent} objects to the
+ * {...@link EventBus} passed into the constructor to provide indication of
+ * transport-level activity. When an HTTP request is sent, an event with a
+ * {...@link State#SENT} state and a {...@code null} {...@link Request} will be
posted.
+ * When an HTTP transport completes successfully, an event will be posted
with
+ * state {...@link State#RECEIVED} and the {...@link Request} object provided to
the
+ * internal {...@link RequestCallback#onResponseReceived()}. If an HTTP
transport
+ * fails (e.g. due to network malfunction), an event with state
+ * {...@link State#RECEIVED} and a {...@code null} {...@link Request} will be sent.
The
+ * success or failure of the HTTP transport is wholly independent from
whether
+ * or not the application payload was successfully executed by the server.
*/
public class DefaultRequestTransport implements RequestTransport {
Index: user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
===================================================================
--- user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
(revision 9065)
+++ user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
(working copy)
@@ -19,6 +19,27 @@
/**
* Marker interface for the RequestFactory code generator.
+ * <p>
+ * A RequestFactory implementation will post {...@link EntityProxyChange}
events to
+ * the {...@link EventBus} passed into the {...@link #initialize} method. The
events
+ * will have the following {...@link WriteOperation} associated with them in
the
+ * following circumstances:
+ * <ul>
+ * <li>{...@link WriteOperation#PERSIST} when an {...@link EntityProxy}
+ * {...@link RequestContext#create(Class) created} on the client is
successfully
+ * persisted in the server's backing store.</li>
+ * <li>{...@link WriteOperation#UPDATE} when changes due to an {...@link
EntityProxy}
+ * being {...@link RequestContext#edit(EntityProxy) edited} on the client are
+ * successfully persisted in the server's backing store.</li>
+ * <li>{...@link WriteOperation#DELETE} when an {...@entityproxy}
+ * reachable from a {...@link Request Request's} arguments becomes
irretrievable
+ * after executing the service method on the server.</li>
+ * </ul>
+ * <p>
+ * Other types of events may be posted to the {...@link EventBus} by other
services
+ * used by the RequestFactory.
+ *
+ * @see {...@link
com.google.gwt.requestfactory.client.DefaultRequestTransport}
*/
public interface RequestFactory {
String JSON_CONTENT_TYPE_UTF8 = "application/json; charset=utf-8";
@@ -83,6 +104,8 @@
/**
* Start this request factory with a user-provided transport.
+ * <p>
+ * The EventBus will receive the following events:
*/
void initialize(EventBus eventBus, RequestTransport transport);
}
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
