Update JNI docs/examples.

Bug: 683256
Change-Id: I3371e15bb4b0396c56ab4a4963c0c820d33674cf
Reviewed-on: https://chromium-review.googlesource.com/590495
Commit-Queue: Eric Stevenson <estevenson@chromium.org>
Reviewed-by: Andrew Grieve <agrieve@chromium.org>
Cr-Commit-Position: refs/heads/master@{#491511}

BUILD.gn

@@ -284,6 +284,7 @@ group("gn_all") {
   if (is_android) {
     deps += [
       "//base:base_junit_tests",
+      "//base/android/jni_generator:jni_generator_tests",
       "//base/android/linker:chromium_android_linker",
       "//build/android/gyp/test:hello_world",
       "//build/android/gyp/test:hello_world",

base/BUILD.gn

@@ -2301,7 +2301,6 @@ test("base_unittests") {
     deps += [
       ":base_java",
       ":base_java_unittest_support",
-      "//base/android/jni_generator:jni_generator_tests",
       "//base/test:test_support_java",
     ]
   }

base/android/jni_generator/BUILD.gn

@@ -2,6 +2,7 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+import("//base/android/jni_generator/jni_exception_list.gni")
 import("//build/config/android/rules.gni")
 import("//testing/test.gni")
 
@@ -38,13 +39,9 @@ android_library("jni_sample_java") {
   ]
 }
 
-# This executable doesn't actually run, but at least serves to test that
-# generated bindings compile properly.
-executable("jni_generator_tests") {
+source_set("jni_sample_native_side") {
   deps = [
-    ":jni_generator_py_tests",
     ":jni_sample_header",
-    ":jni_sample_java",
     "//base",
   ]
   sources = [
@@ -52,3 +49,39 @@ executable("jni_generator_tests") {
     "sample_for_tests.h",
   ]
 }
+
+shared_library("jni_sample_lib") {
+  sources = [
+    "sample_entry_point.cc",
+  ]
+
+  deps = [
+    ":jni_sample_native_side",
+    ":sample_jni_registration",
+    "//base",
+  ]
+}
+
+android_apk("sample_jni_apk") {
+  apk_name = "SampleJni"
+  android_manifest = "//build/android/AndroidManifest.xml"
+  deps = [
+    ":jni_sample_java",
+    "//base:base_java",
+  ]
+  shared_libraries = [ ":jni_sample_lib" ]
+}
+
+generate_jni_registration("sample_jni_registration") {
+  target = ":sample_jni_apk"
+  output = "$target_gen_dir/${target_name}.h"
+  exception_files = jni_exception_files
+}
+
+# Serves to test that generated bindings compile properly.
+group("jni_generator_tests") {
+  deps = [
+    ":jni_generator_py_tests",
+    ":sample_jni_apk",
+  ]
+}

base/android/jni_generator/java/src/org/chromium/example/jni_generator/SampleForTests.java

@@ -22,6 +22,8 @@ import java.util.List;
 // The C++ counter-part is sample_for_tests.cc.
 // jni_generator/BUILD.gn has a jni_generator_tests target that will:
 //   * Generate a header file for the JNI bindings based on this file.
+//   * Generate a header file containing registration methods required to use C++ methods from this
+//     file.
 //   * Compile sample_for_tests.cc using the generated header file.
 //   * link a native executable to prove the generated header + cc file are self-contained.
 // All comments are informational only, and are ignored by the jni generator.

base/android/jni_generator/sample_entry_point.cc

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "base/android/jni_android.h"
+#include "base/android/jni_generator/sample_jni_registration.h"
+#include "base/android/jni_utils.h"
+
+// This is called by the VM when the shared library is first loaded.
+JNI_EXPORT jint JNI_OnLoad(JavaVM* vm, void* reserved) {
+  // By default, all JNI methods are registered. However, since render processes
+  // don't need very much Java code, we enable selective JNI registration on the
+  // Java side and only register a subset of JNI methods.
+  base::android::InitVM(vm);
+  JNIEnv* env = base::android::AttachCurrentThread();
+
+  if (!base::android::IsSelectiveJniRegistrationEnabled(env)) {
+    if (!RegisterNonMainDexNatives(env)) {
+      return -1;
+    }
+  }
+
+  if (!RegisterMainDexNatives(env)) {
+    return -1;
+  }
+  return JNI_VERSION_1_4;
+}

base/android/jni_generator/sample_for_tests.cc

@@ -35,10 +35,6 @@ CPPClass::~CPPClass() {
 }
 
 // static
-bool CPPClass::RegisterJNI(JNIEnv* env) {
-  return RegisterNativesImpl(env);  // Generated in SampleForTests_jni.h
-}
-
 void CPPClass::Destroy(JNIEnv* env, const JavaParamRef<jobject>& caller) {
   delete this;
 }

base/android/jni_generator/sample_for_tests.h

@@ -19,8 +19,9 @@ namespace android {
 // - ensure sample_for_tests_jni.h compiles and the functions declared in it
 // as expected.
 //
-// Methods are called directly from Java (except RegisterJNI). More
-// documentation in SampleForTests.java
+// Methods are called directly from Java. More documentation in
+// SampleForTests.java. See BUILD.gn for the build rules necessary for JNI
+// to be used in an APK.
 //
 // For C++ to access Java methods:
 // - GN Build must be configured to generate bindings:
@@ -56,39 +57,26 @@ namespace android {
 //      ]
 //    }
 //  }
+// The build rules above are generally that that's needed when adding new
+// JNI methods/files. For a full GN example, see
+// base/android/jni_generator/BUILD.gn
 //
 // For C++ methods to be exposed to Java:
-// - The generated RegisterNativesImpl method must be called, this is typically
-//   done by having a static RegisterJNI method in the C++ class.
-// - The RegisterJNI method is added to a module's collection of register
-//   methods, such as: example_jni_registrar.h/cc files which call
-//   base::android::RegisterNativeMethods.
-//   An example_jni_registstrar.cc:
-//
-//     namespace {
-//     const base::android::RegistrationMethod kRegisteredMethods[] = {
-//         // Initial string is for debugging only.
-//         { "ExampleName", base::ExampleNameAndroid::RegisterJNI },
-//         { "ExampleName2", base::ExampleName2Android::RegisterJNI },
-//     };
-//     }  // namespace
-//
-//     bool RegisterModuleNameJni(JNIEnv* env) {
-//       return RegisterNativeMethods(env, kRegisteredMethods,
-//                                    arraysize(kRegisteredMethods));
-//     }
-//
-//  - Each module's RegisterModuleNameJni must be called by a larger module,
-//    or application during startup.
+// - The Java class must be part of an android_apk target that depends on
+//   a generate_jni_registration target. This generate_jni_registration target
+//   automatically generates all necessary registration functions. The
+//   generated header file exposes two functions that should be called when a
+//   library is first loaded:
+//     1) RegisterMainDexNatives()
+//       - Registers all methods that are used outside the browser process
+//     2) RegisterNonMainDexNatives()
+//       - Registers all methods used in the browser process
 //
 class CPPClass {
  public:
   CPPClass();
   ~CPPClass();
 
-  // Register C++ methods exposed to Java using JNI.
-  static bool RegisterJNI(JNIEnv* env);
-
   // Java @CalledByNative methods implicitly available to C++ via the _jni.h
   // file included in the .cc file.