1/*
2 *  Copyright (c) 2015 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_MODULES_UTILITY_INCLUDE_JVM_ANDROID_H_
12#define WEBRTC_MODULES_UTILITY_INCLUDE_JVM_ANDROID_H_
13
14#include <jni.h>
15#include <string>
16
17#include "webrtc/base/scoped_ptr.h"
18#include "webrtc/base/thread_checker.h"
19#include "webrtc/modules/utility/include/helpers_android.h"
20
21namespace webrtc {
22
23// The JNI interface pointer (JNIEnv) is valid only in the current thread.
24// Should another thread need to access the Java VM, it must first call
25// AttachCurrentThread() to attach itself to the VM and obtain a JNI interface
26// pointer. The native thread remains attached to the VM until it calls
27// DetachCurrentThread() to detach.
28class AttachCurrentThreadIfNeeded {
29 public:
30  AttachCurrentThreadIfNeeded();
31  ~AttachCurrentThreadIfNeeded();
32
33 private:
34  rtc::ThreadChecker thread_checker_;
35  bool attached_;
36};
37
38// This class is created by the NativeRegistration class and is used to wrap
39// the actual Java object handle (jobject) on which we can call methods from
40// C++ in to Java. See example in JVM for more details.
41// TODO(henrika): extend support for type of function calls.
42class GlobalRef {
43 public:
44  GlobalRef(JNIEnv* jni, jobject object);
45  ~GlobalRef();
46
47  jboolean CallBooleanMethod(jmethodID methodID, ...);
48  jint CallIntMethod(jmethodID methodID, ...);
49  void CallVoidMethod(jmethodID methodID, ...);
50
51 private:
52  JNIEnv* const jni_;
53  const jobject j_object_;
54};
55
56// Wraps the jclass object on which we can call GetMethodId() functions to
57// query method IDs.
58class JavaClass {
59 public:
60  JavaClass(JNIEnv* jni, jclass clazz) : jni_(jni), j_class_(clazz) {}
61  ~JavaClass() {}
62
63  jmethodID GetMethodId(const char* name, const char* signature);
64  jmethodID GetStaticMethodId(const char* name, const char* signature);
65  jobject CallStaticObjectMethod(jmethodID methodID, ...);
66
67 protected:
68  JNIEnv* const jni_;
69  jclass const j_class_;
70};
71
72// Adds support of the NewObject factory method to the JavaClass class.
73// See example in JVM for more details on how to use it.
74class NativeRegistration : public JavaClass {
75 public:
76  NativeRegistration(JNIEnv* jni, jclass clazz);
77  ~NativeRegistration();
78
79  rtc::scoped_ptr<GlobalRef> NewObject(
80      const char* name, const char* signature, ...);
81
82 private:
83  JNIEnv* const jni_;
84};
85
86// This class is created by the JVM class and is used to expose methods that
87// needs the JNI interface pointer but its main purpose is to create a
88// NativeRegistration object given name of a Java class and a list of native
89// methods. See example in JVM for more details.
90class JNIEnvironment {
91 public:
92  explicit JNIEnvironment(JNIEnv* jni);
93  ~JNIEnvironment();
94
95  // Registers native methods with the Java class specified by |name|.
96  // Note that the class name must be one of the names in the static
97  // |loaded_classes| array defined in jvm_android.cc.
98  // This method must be called on the construction thread.
99  rtc::scoped_ptr<NativeRegistration> RegisterNatives(
100      const char* name, const JNINativeMethod *methods, int num_methods);
101
102  // Converts from Java string to std::string.
103  // This method must be called on the construction thread.
104  std::string JavaToStdString(const jstring& j_string);
105
106 private:
107  rtc::ThreadChecker thread_checker_;
108  JNIEnv* const jni_;
109};
110
111// Main class for working with Java from C++ using JNI in WebRTC.
112//
113// Example usage:
114//
115//   // At initialization (e.g. in JNI_OnLoad), call JVM::Initialize.
116//   JNIEnv* jni = ::base::android::AttachCurrentThread();
117//   JavaVM* jvm = NULL;
118//   jni->GetJavaVM(&jvm);
119//   jobject context = ::base::android::GetApplicationContext();
120//   webrtc::JVM::Initialize(jvm, context);
121//
122//   // Header (.h) file of example class called User.
123//   rtc::scoped_ptr<JNIEnvironment> env;
124//   rtc::scoped_ptr<NativeRegistration> reg;
125//   rtc::scoped_ptr<GlobalRef> obj;
126//
127//   // Construction (in .cc file) of User class.
128//   User::User() {
129//     // Calling thread must be attached to the JVM.
130//     env = JVM::GetInstance()->environment();
131//     reg = env->RegisterNatives("org/webrtc/WebRtcTest", ,);
132//     obj = reg->NewObject("<init>", ,);
133//   }
134//
135//   // Each User method can now use |reg| and |obj| and call Java functions
136//   // in WebRtcTest.java, e.g. boolean init() {}.
137//   bool User::Foo() {
138//     jmethodID id = reg->GetMethodId("init", "()Z");
139//     return obj->CallBooleanMethod(id);
140//   }
141//
142//   // And finally, e.g. in JNI_OnUnLoad, call JVM::Uninitialize.
143//   JVM::Uninitialize();
144class JVM {
145 public:
146  // Stores global handles to the Java VM interface and the application context.
147  // Should be called once on a thread that is attached to the JVM.
148  static void Initialize(JavaVM* jvm, jobject context);
149  // Clears handles stored in Initialize(). Must be called on same thread as
150  // Initialize().
151  static void Uninitialize();
152  // Gives access to the global Java VM interface pointer, which then can be
153  // used to create a valid JNIEnvironment object or to get a JavaClass object.
154  static JVM* GetInstance();
155
156  // Creates a JNIEnvironment object.
157  // This method returns a NULL pointer if AttachCurrentThread() has not been
158  // called successfully. Use the AttachCurrentThreadIfNeeded class if needed.
159  rtc::scoped_ptr<JNIEnvironment> environment();
160
161  // Returns a JavaClass object given class |name|.
162  // Note that the class name must be one of the names in the static
163  // |loaded_classes| array defined in jvm_android.cc.
164  // This method must be called on the construction thread.
165  JavaClass GetClass(const char* name);
166
167  // TODO(henrika): can we make these private?
168  JavaVM* jvm() const { return jvm_; }
169  jobject context() const { return context_; }
170
171 protected:
172  JVM(JavaVM* jvm, jobject context);
173  ~JVM();
174
175 private:
176  JNIEnv* jni() const { return GetEnv(jvm_); }
177
178  rtc::ThreadChecker thread_checker_;
179  JavaVM* const jvm_;
180  jobject context_;
181};
182
183}  // namespace webrtc
184
185#endif  // WEBRTC_MODULES_UTILITY_INCLUDE_JVM_ANDROID_H_
186