Update the javadoc and DeveloperGuide to reflect the latest RPC changes. Patch by: mmendez Review by: scottb (desk check) git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@1122 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/doc/src/com/google/gwt/doc/DeveloperGuide.java b/doc/src/com/google/gwt/doc/DeveloperGuide.java index ed70edb..4609919 100644 --- a/doc/src/com/google/gwt/doc/DeveloperGuide.java +++ b/doc/src/com/google/gwt/doc/DeveloperGuide.java
@@ -21,6 +21,7 @@ import com.google.gwt.junit.client.GWTTestCase; import com.google.gwt.user.client.ImageBundle; import com.google.gwt.user.client.rpc.AsyncCallback; +import com.google.gwt.user.client.rpc.IncompatibleRemoteServiceException; import com.google.gwt.user.client.rpc.IsSerializable; import com.google.gwt.user.client.rpc.RemoteService; import com.google.gwt.user.client.rpc.ServiceDefTarget; @@ -38,6 +39,7 @@ import com.google.gwt.user.client.ui.Widget; import com.google.gwt.user.server.rpc.RemoteServiceServlet; +import java.io.Serializable; import java.util.List; import java.util.Map; import java.util.Set; @@ -1138,7 +1140,8 @@ * * <tr class='gallery-link'> * <td><a href='com.google.gwt.user.client.ui.PushButton.html'>PushButton</a></td> - * <td><a href='com.google.gwt.user.client.ui.ToggleButton.html'>ToggleButton</a></td> + * <td><a + * href='com.google.gwt.user.client.ui.ToggleButton.html'>ToggleButton</a></td> * </tr> * * <tr class='gallery'> @@ -1230,8 +1233,10 @@ * </tr> * * <tr class='gallery-link'> - * <td><a href='com.google.gwt.user.client.ui.VerticalSplitPanel.html'>VerticalSplitPanel</a></td> - * <td><a href='com.google.gwt.user.client.ui.HorizontalSplitPanel.html'>HorizontalSplitPanel</a></td> + * <td><a + * href='com.google.gwt.user.client.ui.VerticalSplitPanel.html'>VerticalSplitPanel</a></td> + * <td><a + * href='com.google.gwt.user.client.ui.HorizontalSplitPanel.html'>HorizontalSplitPanel</a></td> * </tr> * * <tr class='gallery'> @@ -1250,8 +1255,10 @@ * </tr> * * <tr class='gallery-link'> - * <td><a href='com.google.gwt.user.client.ui.RichTextArea.html'>RichTextArea</a></td> - * <td><a href='com.google.gwt.user.client.ui.DisclosurePanel.html'>DisclosurePanel</a></td> + * <td><a + * href='com.google.gwt.user.client.ui.RichTextArea.html'>RichTextArea</a></td> + * <td><a + * href='com.google.gwt.user.client.ui.DisclosurePanel.html'>DisclosurePanel</a></td> * </tr> * * <tr class='gallery'> @@ -2184,13 +2191,12 @@ * A user-defined class is serializable if * <ol> * <li>it is assignable to - * {@link com.google.gwt.user.client.rpc.IsSerializable}, either because it - * directly implements the interface or because it derives from a superclass - * that does</li> - * <li>all non-<code>transient</code> fields are themselves - * serializable, and</li> - * <li>it explicitly defines a default constructor, which is a constructor - * that is declared to be public and takes no arguments</li> + * {@link com.google.gwt.user.client.rpc.IsSerializable} or + * {@link java.io.Serializable}, either because it directly implements one + * of these interfaces or because it derives from a superclass that does</li> + * <li>all non-<code>final</code>, non-<code>transient</code> + * instance fields are themselves serializable, and</li> + * <li>it has a <code>public</code> default (zero argument) constructor</li> * </ol> * * The <code>transient</code> keyword is honored, so values in transient @@ -2247,7 +2253,7 @@ * Java interface * <code><a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/Serializable.html">Serializable</a></code>. * All references to serialization are referring to the GWT concept as - * defined below. + * defined above. */ public static class SerializableTypes { @@ -2311,6 +2317,7 @@ * specified in the service interface. * * <h2>Unexpected Exceptions</h2> + * <h3>InvocationException</h3> * An RPC may not reach the * {@link DeveloperGuide.RemoteProcedureCalls.ImplementingServices service implementation} * at all. This can happen for many reasons: the network may be @@ -2333,6 +2340,23 @@ * application code. * </p> * + * <h3>IncompatibleRemoteServiceException</h3> + * <p> + * Another type of failure can be caused by an incompatibility between the + * client and the server. This most commonly occurs when a change to a + * {@link DeveloperGuide.RemoteProcedureCalls.ImplementingServices service implementation} + * is deployed to a server but out-of-date clients are still active. For + * more details please see + * {@link com.google.gwt.user.client.rpc.IncompatibleRemoteServiceException IncompatibleRemoteServiceException}. + * </p> + * + * <p> + * When the client code receives an + * {@link com.google.gwt.user.client.rpc.IncompatibleRemoteServiceException IncompatibleRemoteServiceException}, + * it should ultimately attempt to refresh the browser in order to pick up + * the latest client. + * </p> + * * @title Handling Exceptions * @synopsis Handle exceptions due to failed calls or thrown from the * server.
diff --git a/user/src/com/google/gwt/user/client/rpc/IsSerializable.java b/user/src/com/google/gwt/user/client/rpc/IsSerializable.java index efe3593..d9c9009 100644 --- a/user/src/com/google/gwt/user/client/rpc/IsSerializable.java +++ b/user/src/com/google/gwt/user/client/rpc/IsSerializable.java
@@ -17,10 +17,7 @@ /** * Marker interface indicating that a type is intended to be used with a - * {@link RemoteService}. Do not confuse this interface with - * {@link Serializable java.io.Serializable}, which is included in the GWT JRE - * Emulation Library for source compatibility only and which will not by itself - * make a class usable with a {@link RemoteService}. + * {@link RemoteService}. */ public interface IsSerializable { }
diff --git a/user/super/com/google/gwt/emul/java/io/Serializable.java b/user/super/com/google/gwt/emul/java/io/Serializable.java index 2410cb8..3f8a471 100644 --- a/user/super/com/google/gwt/emul/java/io/Serializable.java +++ b/user/super/com/google/gwt/emul/java/io/Serializable.java
@@ -15,10 +15,12 @@ */ package java.io; +import com.google.gwt.user.client.rpc.IsSerializable; + /** - * Provided for source compatibility only; implementing - * <code>java.io.Serializable</code> is not a substitute for - * {@link IsSerializable} for use with a {@link RemoteService}. + * Provided for interoperability; RPC treats this interface synonimously with + * {@link com.google.gwt.user.client.rpc.IsSerializable IsSerializable}. + * The Java serialization protocol is explicitly not supported. */ public interface Serializable { }