Reviewers: rjrjr,
Description:
Add some missing docs for RPC utility class.
Patch by: bobv
Review by: rjrjr
Please review this at http://gwt-code-reviews.appspot.com/1207801/show
Affected files:
M user/src/com/google/gwt/user/server/rpc/RPC.java
Index: user/src/com/google/gwt/user/server/rpc/RPC.java
===================================================================
--- user/src/com/google/gwt/user/server/rpc/RPC.java (revision 9400)
+++ user/src/com/google/gwt/user/server/rpc/RPC.java (working copy)
@@ -49,7 +49,9 @@
* <h3>Advanced Example</h3> The following example shows a more advanced
way of
* using this class to create an adapter between GWT RPC entities and
POJOs.
*
- * {...@example
com.google.gwt.examples.rpc.server.AdvancedExample#doPost(javax.servlet.http.HttpServletRequest,
javax.servlet.http.HttpServletResponse)}
+ * {...@example
+ *
com.google.gwt.examples.rpc.server.AdvancedExample#doPost(javax.servlet.http.
+ * HttpServletRequest, javax.servlet.http.HttpServletResponse)}
*/
public final class RPC {
@@ -241,7 +243,7 @@
// Read the RPC token
rpcToken = (RpcToken)
streamReader.deserializeValue(RpcToken.class);
}
-
+
// Read the name of the RemoteService interface
String serviceIntfName = maybeDeobfuscate(streamReader,
streamReader.readString());
@@ -369,6 +371,37 @@
AbstractSerializationStream.DEFAULT_FLAGS);
}
+ /**
+ * Returns a string that encodes an exception. If method is not
+ * <code>null</code>, it is an error if the exception is not in the
method's
+ * list of checked exceptions.
+ *
+ * <p>
+ * If the serializationPolicy parameter is not <code>null</code>, it is
used
+ * to determine what types can be encoded as part of this response. If
this
+ * parameter is <code>null</code>, then only subtypes of
+ * {...@link com.google.gwt.user.client.rpc.IsSerializable IsSerializable}
or
+ * types which have custom field serializers may be encoded.
+ * </p>
+ *
+ * @param serviceMethod the method that threw the exception, may be
+ * <code>null</code>
+ * @param cause the {...@link Throwable} that was thrown
+ * @param serializationPolicy determines the serialization policy to be
used
+ * @param flags a bitmask of the flag constants defined in
+ * {...@link
com.google.gwt.user.client.rpc.impl.AbstractSerializationStream}
+ * . The choice of flags is determined by the options with
which the
+ * client was compiled and any optional features in use. In
+ * particular, the use of elided type names or RpcTokens by the
+ * client will require a flag value.
+ * @return a string that encodes the exception
+ *
+ * @throws NullPointerException if the the cause or the
serializationPolicy
+ * are <code>null</code>
+ * @throws SerializationException if the result cannot be serialized
+ * @throws UnexpectedException if the result was an unexpected exception
(a
+ * checked exception not declared in the serviceMethod's
signature)
+ */
public static String encodeResponseForFailure(Method serviceMethod,
Throwable cause, SerializationPolicy serializationPolicy, int flags)
throws SerializationException {
@@ -442,6 +475,36 @@
AbstractSerializationStream.DEFAULT_FLAGS);
}
+ /**
+ * Returns a string that encodes the object. It is an error to try to
encode
+ * an object that is not assignable to the service method's return type.
+ *
+ * <p>
+ * If the serializationPolicy parameter is not <code>null</code>, it is
used
+ * to determine what types can be encoded as part of this response. If
this
+ * parameter is <code>null</code>, then only subtypes of
+ * {...@link com.google.gwt.user.client.rpc.IsSerializable IsSerializable}
or
+ * types which have custom field serializers may be encoded.
+ * </p>
+ *
+ * @param serviceMethod the method whose result we are encoding
+ * @param object the instance that we wish to encode
+ * @param serializationPolicy determines the serialization policy to be
used
+ * @param flags a bitmask of the flag constants defined in
+ * {...@link
com.google.gwt.user.client.rpc.impl.AbstractSerializationStream}
+ * . The choice of flags is determined by the options with
which the
+ * client was compiled and any optional features in use. In
+ * particular, the use of elided type names or RpcTokens by the
+ * client will require a flag value.
+ * @return a string that encodes the object, if the object is compatible
with
+ * the service method's declared return type
+ *
+ * @throws IllegalArgumentException if the result is not assignable to
the
+ * service method's return type
+ * @throws NullPointerException if the serviceMethod or the
+ * serializationPolicy are <code>null</code>
+ * @throws SerializationException if the result cannot be serialized
+ */
public static String encodeResponseForSuccess(Method serviceMethod,
Object object, SerializationPolicy serializationPolicy, int flags)
throws SerializationException {
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
