Allow 'userInfo' for native promise.reject + add native error stack s…

…upport (facebook#20940)

Summary:
As mentioned [here](react-native-community/releases#34 (comment)), Android is missing native Promise reject with a `userInfo` `WritableMap` support and also `nativeStack` support (which addresses `TODO(8850038)`). This PR adds Android support for both of these.

React Native on iOS ([here](https://github.com/facebook/react-native/blob/master/React/Base/RCTUtils.m#L433)) and Windows ([here](microsoft/react-native-windows#732)) already support this so this is a relatively minor addition to bring Android in line with the other platforms. (JS support is also [here](https://github.com/facebook/react-native/blob/master/Libraries/BatchedBridge/NativeModules.js#L145-L148))

Existing methods remain unchanged other than general cleanup of variable names (`e -> throwable`) and adding code comments/docs.

Additionally, the `ShareTestModule` implementation of Promise (SimplePromise) was updated to reflect these changes - other line changes in this file are from formatting in Android Studio - if this is an issue let me know.

 - Currently inconsistent with other platforms.
 - Blocking a couple of issues over at [invertase/react-native-firebase](https://github.com/invertase/react-native-firebase) - save for re-writing everything to Promise resolve only - which is no small change and isn't a great solution either.
Pull Request resolved: facebook#20940

Differential Revision: D13412527

Pulled By: cpojer

fbshipit-source-id: 2ca6c5f3db9ff2c2986b02edda80bc73432f66d3

ReactAndroid/src/main/java/com/facebook/react/bridge/BUCK

@@ -22,6 +22,7 @@ rn_android_library(
     proguard_config = "reactnative.pro",
     provided_deps = [
         react_native_dep("third-party/android/support/v4:lib-support-v4"),
+        react_native_dep("third-party/android/support-annotations:android-support-annotations"),
     ],
     required_for_source_only_abi = True,
     visibility = [

ReactAndroid/src/main/java/com/facebook/react/bridge/Promise.java

@@ -7,48 +7,119 @@
 
 package com.facebook.react.bridge;
 
+import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
-/**
+/*
  * Interface that represents a JavaScript Promise which can be passed to the native module as a
  * method parameter.
  *
- * Methods annotated with {@link ReactMethod} that use {@link Promise} as type of the last parameter
+ * Methods annotated with {@link ReactMethod} that use a {@link Promise} as the last parameter
  * will be marked as "promise" and will return a promise when invoked from JavaScript.
  */
 public interface Promise {
 
   /**
-   * Successfully resolve the Promise.
+   * Successfully resolve the Promise with an optional value.
+   *
+   * @param value Object
    */
   void resolve(@Nullable Object value);
 
   /**
-   * Report an error which wasn't caused by an exception.
+   * Report an error without an exception using a custom code and error message.
+   *
+   * @param code    String
+   * @param message String
    */
   void reject(String code, String message);
 
   /**
-   * Report an exception.
+   * Report an exception with a custom code.
+   *
+   * @param code      String
+   * @param throwable Throwable
    */
-  void reject(String code, Throwable e);
+  void reject(String code, Throwable throwable);
 
   /**
-   * Report an exception with a custom error message.
+   * Report an exception with a custom code and error message.
+   *
+   * @param code      String
+   * @param message   String
+   * @param throwable Throwable
    */
-  void reject(String code, String message, Throwable e);
+  void reject(String code, String message, Throwable throwable);
+
 
   /**
-   * Report an error which wasn't caused by an exception.
-   * @deprecated Prefer passing a module-specific error code to JS.
-   *             Using this method will pass the error code "EUNSPECIFIED".
+   * Report an exception, with default error code.
+   * Useful in catch-all scenarios where it's unclear why the error occurred.
+   *
+   * @param throwable Throwable
    */
-  @Deprecated
-  void reject(String message);
+  void reject(Throwable throwable);
+
+  /* ---------------------------
+   *  With userInfo WritableMap
+   * --------------------------- */
 
   /**
-   * Report an exception, with default error code.
+   * Report an exception, with default error code, with userInfo.
    * Useful in catch-all scenarios where it's unclear why the error occurred.
+   *
+   * @param throwable Throwable
+   * @param userInfo  WritableMap
+   */
+  void reject(Throwable throwable, WritableMap userInfo);
+
+  /**
+   * Reject with a code and userInfo WritableMap.
+   *
+   * @param code     String
+   * @param userInfo WritableMap
    */
-  void reject(Throwable reason);
+  void reject(String code, @Nonnull WritableMap userInfo);
+
+  /**
+   * Report an exception with a custom code and userInfo.
+   *
+   * @param code      String
+   * @param throwable Throwable
+   * @param userInfo  WritableMap
+   */
+  void reject(String code, Throwable throwable, WritableMap userInfo);
+
+  /**
+   * Report an error with a custom code, error message and userInfo,
+   * an error not caused by an exception.
+   *
+   * @param code     String
+   * @param message  String
+   * @param userInfo WritableMap
+   */
+  void reject(String code, String message, @Nonnull WritableMap userInfo);
+
+  /**
+   * Report an exception with a custom code, error message and userInfo.
+   *
+   * @param code      String
+   * @param message   String
+   * @param throwable Throwable
+   * @param userInfo  WritableMap
+   */
+  void reject(String code, String message, Throwable throwable, WritableMap userInfo);
+
+  /* ------------
+   *  Deprecated
+   * ------------ */
+
+  /**
+   * Report an error which wasn't caused by an exception.
+   *
+   * @deprecated Prefer passing a module-specific error code to JS.
+   * Using this method will pass the error code "EUNSPECIFIED".
+   */
+  @Deprecated
+  void reject(String message);
 }