Merge "DeadObjectException: detail what error means" into main

core/java/android/os/DeadObjectException.java

@@ -19,8 +19,29 @@ import android.os.RemoteException;
 
 /**
  * The object you are calling has died, because its hosting process
- * no longer exists. This is also thrown for low-level binder
- * errors.
+ * no longer exists, or there has been a low-level binder error.
+ *
+ * If you get this exception from a system service, the error is
+ * usually nonrecoverable as the framework will restart. If you
+ * receive this error from an app, at a minimum, you should
+ * recover by resetting the connection. For instance, you should
+ * drop the binder, clean up associated state, and reset your
+ * connection to the service which through this error. In order
+ * to simplify your error recovery paths, you may also want to
+ * "simply" restart your process. However, this may not be an
+ * option if the service you are talking to is unreliable or
+ * crashes frequently.
+ *
+ * If this isn't from a service death and is instead from a
+ * low-level binder error, it will be from:
+ * - a oneway call queue filling up (too many oneway calls)
+ * - from the binder buffer being filled up, so that the transaction
+ *   is rejected.
+ *
+ * In these cases, more information about the error will be
+ * logged. However, there isn't a good way to differentiate
+ * this information at runtime. So, you should handle the
+ * error, as if the service died.
  */
 public class DeadObjectException extends RemoteException {
     public DeadObjectException() {

core/java/android/os/DeadSystemRuntimeException.java

@@ -19,10 +19,12 @@ package android.os;
 /**
  * Exception thrown when a call into system_server resulted in a
  * DeadObjectException, meaning that the system_server has died or
- * experienced a low-level binder error.  There's * nothing apps can
+ * experienced a low-level binder error.  There's nothing apps can
  * do at this point - the system will automatically restart - so
  * there's no point in catching this.
  *
+ * See {@link android.os.DeadObjectException}.
+ *
  * @hide
  */
 public class DeadSystemRuntimeException extends RuntimeException {