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 {
}
