base/android/jni_generator/sample_for_tests.h

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_
   6 #define BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_
   7
   8 #include <jni.h>
   9 #include <map>
  10 #include <string>
  11
  12 #include "base/android/jni_android.h"
  13 #include "base/basictypes.h"
  14
  15 namespace base {
  16 namespace android {
  17
  18 // This file is used to:
  19 // - document the best practices and guidelines on JNI usage.
  20 // - ensure sample_for_tests_jni.h compiles and the functions declared in it
  21 // as expected.
  22 //
  23 // Methods are called directly from Java (except RegisterJNI). More
  24 // documentation in SampleForTests.java
  25 //
  26 // For C++ to access Java methods:
  27 // - GYP Build must be configured to generate bindings:
  28 //  # ...
  29 //  'targets': [
  30 //    {
  31 //      # An example target that will rely on JNI:
  32 //      'target_name': 'foo',
  33 //      'type': '<(component)',
  34 //      # ... normal sources, defines, deps.
  35 //      #     For each jni generated .java -> .h header file in foo_jni_headers
  36 //      #     target there will be a single .cc file here that includes it.
  37 //      #
  38 //      # Add deps for JNI:
  39 //      'conditions': [
  40 //        ['OS == "android"', {
  41 //          'dependencies': [
  42 //            'foo_java',
  43 //            'foo_jni_headers',
  44 //          ],
  45 //        }],
  46 //      ],
  47 //    },
  48 //  ],
  49 //  # ...
  50 //  # Create targets for JNI:
  51 //  'conditions': [
  52 //    ['OS == "android"', {
  53 //      'targets': [
  54 //        {
  55 //          'target_name': 'foo_jni_headers',
  56 //          'type': 'none',
  57 //          'sources': [
  58 //            'java/src/org/chromium/example/jni_generator/SampleForTests.java',
  59 //          ],
  60 //          'variables': {
  61 //            'jni_gen_package': 'foo',
  62 //          },
  63 //          'includes': [ '../../../build/jni_generator.gypi' ],
  64 //        },
  65 //        {
  66 //          'target_name': 'foo_java',
  67 //          'type': 'none',
  68 //          'dependencies': [
  69 //            '../../../base/base.gyp:base',
  70 //          ],
  71 //          'variables': {
  72 //            'java_in_dir': 'java',
  73 //          },
  74 //          'includes': [ '../../../build/java.gypi' ],
  75 //        },
  76 //      ],
  77 //    }],
  78 //  ],
  79 //
  80 // - GN Build must be configured to generate bindings:
  81 //  # Add import at top of file:
  82 //  if (is_android) {
  83 //    import("//build/config/android/rules.gni")  # For generate_jni().
  84 //  }
  85 //  # ...
  86 //  # An example target that will rely on JNI:
  87 //  component("foo") {
  88 //    # ... normal sources, defines, deps.
  89 //    #     For each jni generated .java -> .h header file in jni_headers
  90 //    #     target there will be a single .cc file here that includes it.
  91 //    #
  92 //    # Add a dep for JNI:
  93 //    if (is_android) {
  94 //      deps += [ ":foo_jni" ]
  95 //    }
  96 //  }
  97 //  # ...
  98 //  # Create target for JNI:
  99 //  if (is_android) {
 100 //    generate_jni("jni_headers") {
 101 //      sources = [
 102 //        "java/src/org/chromium/example/jni_generator/SampleForTests.java",
 103 //      ]
 104 //      jni_package = "foo"
 105 //    }
 106 //    android_library("java") {
 107 //      java_files = [
 108 //        "java/src/org/chromium/example/jni_generator/SampleForTests.java",
 109 //        "java/src/org/chromium/example/jni_generator/NonJniFile.java",
 110 //      ]
 111 //    }
 112 //  }
 113 //
 114 // For C++ methods to be exposed to Java:
 115 // - The generated RegisterNativesImpl method must be called, this is typically
 116 //   done by having a static RegisterJNI method in the C++ class.
 117 // - The RegisterJNI method is added to a module's collection of register
 118 //   methods, such as: example_jni_registrar.h/cc files which call
 119 //   base::android::RegisterNativeMethods.
 120 //   An example_jni_registstrar.cc:
 121 //
 122 //     namespace {
 123 //     const base::android::RegistrationMethod kRegisteredMethods[] = {
 124 //         // Initial string is for debugging only.
 125 //         { "ExampleName", base::ExampleNameAndroid::RegisterJNI },
 126 //         { "ExampleName2", base::ExampleName2Android::RegisterJNI },
 127 //     };
 128 //     }  // namespace
 129 //
 130 //     bool RegisterModuleNameJni(JNIEnv* env) {
 131 //       return RegisterNativeMethods(env, kRegisteredMethods,
 132 //                                    arraysize(kRegisteredMethods));
 133 //     }
 134 //
 135 //  - Each module's RegisterModuleNameJni must be called by a larger module,
 136 //    or application during startup.
 137 //
 138 class CPPClass {
 139  public:
 140   CPPClass();
 141   ~CPPClass();
 142
 143   // Register C++ methods exposed to Java using JNI.
 144   static bool RegisterJNI(JNIEnv* env);
 145
 146   // Java @CalledByNative methods implicitly available to C++ via the _jni.h
 147   // file included in the .cc file.
 148
 149   class InnerClass {
 150    public:
 151     jdouble MethodOtherP0(JNIEnv* env, jobject caller);
 152   };
 153
 154   void Destroy(JNIEnv* env, jobject caller);
 155
 156   jint Method(JNIEnv* env, jobject caller);
 157
 158   void AddStructB(JNIEnv* env, jobject caller, jobject structb);
 159
 160   void IterateAndDoSomethingWithStructB(JNIEnv* env, jobject caller);
 161
 162   base::android::ScopedJavaLocalRef<jstring> ReturnAString(
 163       JNIEnv* env, jobject caller);
 164
 165  private:
 166   std::map<long, std::string> map_;
 167
 168   DISALLOW_COPY_AND_ASSIGN(CPPClass);
 169 };
 170
 171 }  // namespace android
 172 }  // namespace base
 173
 174 #endif  // BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_