Revision: 9069
Author: [email protected]
Date: Thu Oct 14 10:44:31 2010
Log: Resolve GWT issue 5361.
Document the GwtEvents associated with a RequestFactory.
Patch by: bobv
Review by: rjrjr
Review at http://gwt-code-reviews.appspot.com/988802
http://code.google.com/p/google-web-toolkit/source/detail?r=9069
Modified:
/trunk/user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
/trunk/user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
=======================================
---
/trunk/user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
Tue Oct 5 11:03:13 2010
+++
/trunk/user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
Thu Oct 14 10:44:31 2010
@@ -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 {
=======================================
---
/trunk/user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
Tue Oct 12 10:53:11 2010
+++
/trunk/user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
Thu Oct 14 10:44:31 2010
@@ -19,6 +19,33 @@
/**
* 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#UPDATE} when a previously-unseen
+ * {...@link EntityProxy} is reachable from the return value for a
+ * successfully-executed {...@link Request}.</li>
+ * <li>{...@link WriteOperation#UPDATE} when any property of an {...@link
EntityProxy}
+ * reachable from a {...@link Request Request's} arguments is seen to have
changed
+ * after executing the service method on the server.</li>
+ * <li>{...@link WriteOperation#DELETE} when an {...@link 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";
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
