base/android/jni_android.h

   1 // Copyright 2012 The Chromium Authors
   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_ANDROID_H_
   6 #define BASE_ANDROID_JNI_ANDROID_H_
   7
   8 #include <jni.h>
   9 #include <sys/types.h>
  10
  11 #include <atomic>
  12 #include <string>
  13
  14 #include "base/android/scoped_java_ref.h"
  15 #include "base/auto_reset.h"
  16 #include "base/base_export.h"
  17 #include "base/compiler_specific.h"
  18 #include "base/debug/debugging_buildflags.h"
  19 #include "base/debug/stack_trace.h"
  20
  21 namespace base {
  22 namespace android {
  23
  24 // Used to mark symbols to be exported in a shared library's symbol table.
  25 #define JNI_EXPORT __attribute__ ((visibility("default")))
  26
  27 // Contains the registration method information for initializing JNI bindings.
  28 struct RegistrationMethod {
  29   const char* name;
  30   bool (*func)(JNIEnv* env);
  31 };
  32
  33 // Attaches the current thread to the VM (if necessary) and return the JNIEnv*.
  34 BASE_EXPORT JNIEnv* AttachCurrentThread();
  35
  36 // Same to AttachCurrentThread except that thread name will be set to
  37 // |thread_name| if it is the first call. Otherwise, thread_name won't be
  38 // changed. AttachCurrentThread() doesn't regard underlying platform thread
  39 // name, but just resets it to "Thread-???". This function should be called
  40 // right after new thread is created if it is important to keep thread name.
  41 BASE_EXPORT JNIEnv* AttachCurrentThreadWithName(const std::string& thread_name);
  42
  43 // Detaches the current thread from VM if it is attached.
  44 BASE_EXPORT void DetachFromVM();
  45
  46 // Initializes the global JVM.
  47 BASE_EXPORT void InitVM(JavaVM* vm);
  48
  49 // Returns true if the global JVM has been initialized.
  50 BASE_EXPORT bool IsVMInitialized();
  51
  52 // Returns the global JVM, or nullptr if it has not been initialized.
  53 BASE_EXPORT JavaVM* GetVM();
  54
  55 // Do not allow any future native->java calls.
  56 // This is necessary in gtest DEATH_TESTS to prevent
  57 // GetJavaStackTraceIfPresent() from accessing a defunct JVM (due to fork()).
  58 // https://crbug.com/1484834
  59 BASE_EXPORT void DisableJvmForTesting();
  60
  61 // Initializes the global ClassLoader used by the GetClass and LazyGetClass
  62 // methods. This is needed because JNI will use the base ClassLoader when there
  63 // is no Java code on the stack. The base ClassLoader doesn't know about any of
  64 // the application classes and will fail to lookup anything other than system
  65 // classes.
  66 void InitGlobalClassLoader(JNIEnv* env);
  67
  68 // Finds the class named |class_name| and returns it.
  69 // Use this method instead of invoking directly the JNI FindClass method (to
  70 // prevent leaking local references).
  71 // This method triggers a fatal assertion if the class could not be found.
  72 // Use HasClass if you need to check whether the class exists.
  73 BASE_EXPORT ScopedJavaLocalRef<jclass> GetClass(JNIEnv* env,
  74                                                 const char* class_name,
  75                                                 const char* split_name);
  76 BASE_EXPORT ScopedJavaLocalRef<jclass> GetClass(JNIEnv* env,
  77                                                 const char* class_name);
  78
  79 // The method will initialize |atomic_class_id| to contain a global ref to the
  80 // class. And will return that ref on subsequent calls.  It's the caller's
  81 // responsibility to release the ref when it is no longer needed.
  82 // The caller is responsible to zero-initialize |atomic_method_id|.
  83 // It's fine to simultaneously call this on multiple threads referencing the
  84 // same |atomic_method_id|.
  85 BASE_EXPORT jclass LazyGetClass(JNIEnv* env,
  86                                 const char* class_name,
  87                                 const char* split_name,
  88                                 std::atomic<jclass>* atomic_class_id);
  89 BASE_EXPORT jclass LazyGetClass(
  90     JNIEnv* env,
  91     const char* class_name,
  92     std::atomic<jclass>* atomic_class_id);
  93
  94 // This class is a wrapper for JNIEnv Get(Static)MethodID.
  95 class BASE_EXPORT MethodID {
  96  public:
  97   enum Type {
  98     TYPE_STATIC,
  99     TYPE_INSTANCE,
 100   };
 101
 102   // Returns the method ID for the method with the specified name and signature.
 103   // This method triggers a fatal assertion if the method could not be found.
 104   template<Type type>
 105   static jmethodID Get(JNIEnv* env,
 106                        jclass clazz,
 107                        const char* method_name,
 108                        const char* jni_signature);
 109
 110   // The caller is responsible to zero-initialize |atomic_method_id|.
 111   // It's fine to simultaneously call this on multiple threads referencing the
 112   // same |atomic_method_id|.
 113   template<Type type>
 114   static jmethodID LazyGet(JNIEnv* env,
 115                            jclass clazz,
 116                            const char* method_name,
 117                            const char* jni_signature,
 118                            std::atomic<jmethodID>* atomic_method_id);
 119 };
 120
 121 // Returns true if an exception is pending in the provided JNIEnv*.
 122 BASE_EXPORT bool HasException(JNIEnv* env);
 123
 124 // If an exception is pending in the provided JNIEnv*, this function clears it
 125 // and returns true.
 126 BASE_EXPORT bool ClearException(JNIEnv* env);
 127
 128 // This function will call CHECK() macro if there's any pending exception.
 129 BASE_EXPORT void CheckException(JNIEnv* env);
 130
 131 // This returns a string representation of the java stack trace.
 132 BASE_EXPORT std::string GetJavaExceptionInfo(
 133     JNIEnv* env,
 134     const JavaRef<jthrowable>& throwable);
 135 // This returns a string representation of the java stack trace.
 136 BASE_EXPORT std::string GetJavaStackTraceIfPresent();
 137
 138 }  // namespace android
 139 }  // namespace base
 140
 141 #endif  // BASE_ANDROID_JNI_ANDROID_H_