// Copyright (c) 2012 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. #ifndef BASE_ANDROID_SCOPED_JAVA_REF_H_ #define BASE_ANDROID_SCOPED_JAVA_REF_H_ #include #include #include #include #include "base/base_export.h" #include "base/check_op.h" #include "base/memory/raw_ptr.h" namespace base { namespace android { // Creates a new local reference frame, in which at least a given number of // local references can be created. Note that local references already created // in previous local frames are still valid in the current local frame. class BASE_EXPORT ScopedJavaLocalFrame { public: explicit ScopedJavaLocalFrame(JNIEnv* env); ScopedJavaLocalFrame(JNIEnv* env, int capacity); ScopedJavaLocalFrame(const ScopedJavaLocalFrame&) = delete; ScopedJavaLocalFrame& operator=(const ScopedJavaLocalFrame&) = delete; ~ScopedJavaLocalFrame(); private: // This class is only good for use on the thread it was created on so // it's safe to cache the non-threadsafe JNIEnv* inside this object. raw_ptr env_; }; // Forward declare the generic java reference template class. template class JavaRef; // Template specialization of JavaRef, which acts as the base class for all // other JavaRef<> template types. This allows you to e.g. pass // ScopedJavaLocalRef into a function taking const JavaRef& template <> class BASE_EXPORT JavaRef { public: // Initializes a null reference. constexpr JavaRef() {} // Allow nullptr to be converted to JavaRef. This avoids having to declare an // empty JavaRef just to pass null to a function, and makes C++ "nullptr" and // Java "null" equivalent. constexpr JavaRef(std::nullptr_t) {} JavaRef(const JavaRef&) = delete; JavaRef& operator=(const JavaRef&) = delete; // Public to allow destruction of null JavaRef objects. ~JavaRef() {} // TODO(torne): maybe rename this to get() for consistency with unique_ptr // once there's fewer unnecessary uses of it in the codebase. jobject obj() const { return obj_; } explicit operator bool() const { return obj_ != nullptr; } // Deprecated. Just use bool conversion. // TODO(torne): replace usage and remove this. bool is_null() const { return obj_ == nullptr; } protected: // Takes ownership of the |obj| reference passed; requires it to be a local // reference type. #if DCHECK_IS_ON() // Implementation contains a DCHECK; implement out-of-line when DCHECK_IS_ON. JavaRef(JNIEnv* env, jobject obj); #else JavaRef(JNIEnv* env, jobject obj) : obj_(obj) {} #endif // Used for move semantics. obj_ must have been released first if non-null. void steal(JavaRef&& other) { obj_ = other.obj_; other.obj_ = nullptr; } // The following are implementation detail convenience methods, for // use by the sub-classes. JNIEnv* SetNewLocalRef(JNIEnv* env, jobject obj); void SetNewGlobalRef(JNIEnv* env, jobject obj); void ResetLocalRef(JNIEnv* env); void ResetGlobalRef(); jobject ReleaseInternal(); private: jobject obj_ = nullptr; }; // Forward declare the object array reader for the convenience function. template class JavaObjectArrayReader; // Generic base class for ScopedJavaLocalRef and ScopedJavaGlobalRef. Useful // for allowing functions to accept a reference without having to mandate // whether it is a local or global type. template class JavaRef : public JavaRef { public: constexpr JavaRef() {} constexpr JavaRef(std::nullptr_t) {} JavaRef(const JavaRef&) = delete; JavaRef& operator=(const JavaRef&) = delete; ~JavaRef() {} T obj() const { return static_cast(JavaRef::obj()); } // Get a JavaObjectArrayReader for the array pointed to by this reference. // Only defined for JavaRef. // You must pass the type of the array elements (usually jobject) as the // template parameter. template ::value>> JavaObjectArrayReader ReadElements() const { return JavaObjectArrayReader(*this); } protected: JavaRef(JNIEnv* env, T obj) : JavaRef(env, obj) {} }; // Holds a local reference to a JNI method parameter. // Method parameters should not be deleted, and so this class exists purely to // wrap them as a JavaRef in the JNI binding generator. Do not create // instances manually. template class JavaParamRef : public JavaRef { public: // Assumes that |obj| is a parameter passed to a JNI method from Java. // Does not assume ownership as parameters should not be deleted. JavaParamRef(JNIEnv* env, T obj) : JavaRef(env, obj) {} // Allow nullptr to be converted to JavaParamRef. Some unit tests call JNI // methods directly from C++ and pass null for objects which are not actually // used by the implementation (e.g. the caller object); allow this to keep // working. JavaParamRef(std::nullptr_t) {} JavaParamRef(const JavaParamRef&) = delete; JavaParamRef& operator=(const JavaParamRef&) = delete; ~JavaParamRef() {} // TODO(torne): remove this cast once we're using JavaRef consistently. // http://crbug.com/506850 operator T() const { return JavaRef::obj(); } }; // Holds a local reference to a Java object. The local reference is scoped // to the lifetime of this object. // Instances of this class may hold onto any JNIEnv passed into it until // destroyed. Therefore, since a JNIEnv is only suitable for use on a single // thread, objects of this class must be created, used, and destroyed, on a // single thread. // Therefore, this class should only be used as a stack-based object and from a // single thread. If you wish to have the reference outlive the current // callstack (e.g. as a class member) or you wish to pass it across threads, // use a ScopedJavaGlobalRef instead. template class ScopedJavaLocalRef : public JavaRef { public: // Take ownership of a bare jobject. This does not create a new reference. // This should only be used by JNI helper functions, or in cases where code // must call JNIEnv methods directly. static ScopedJavaLocalRef Adopt(JNIEnv* env, T obj) { return ScopedJavaLocalRef(env, obj); } constexpr ScopedJavaLocalRef() {} constexpr ScopedJavaLocalRef(std::nullptr_t) {} // Copy constructor. This is required in addition to the copy conversion // constructor below. ScopedJavaLocalRef(const ScopedJavaLocalRef& other) : env_(other.env_) { JavaRef::SetNewLocalRef(env_, other.obj()); } // Copy conversion constructor. template ::value>> ScopedJavaLocalRef(const ScopedJavaLocalRef& other) : env_(other.env_) { JavaRef::SetNewLocalRef(env_, other.obj()); } // Move constructor. This is required in addition to the move conversion // constructor below. ScopedJavaLocalRef(ScopedJavaLocalRef&& other) : env_(other.env_) { JavaRef::steal(std::move(other)); } // Move conversion constructor. template ::value>> ScopedJavaLocalRef(ScopedJavaLocalRef&& other) : env_(other.env_) { JavaRef::steal(std::move(other)); } // Constructor for other JavaRef types. explicit ScopedJavaLocalRef(const JavaRef& other) { Reset(other); } // Assumes that |obj| is a local reference to a Java object and takes // ownership of this local reference. // TODO(torne): make legitimate uses call Adopt() instead, and make this // private. ScopedJavaLocalRef(JNIEnv* env, T obj) : JavaRef(env, obj), env_(env) {} ~ScopedJavaLocalRef() { Reset(); } // Null assignment, for disambiguation. ScopedJavaLocalRef& operator=(std::nullptr_t) { Reset(); return *this; } // Copy assignment. ScopedJavaLocalRef& operator=(const ScopedJavaLocalRef& other) { Reset(other); return *this; } // Copy conversion assignment. template ::value>> ScopedJavaLocalRef& operator=(const ScopedJavaLocalRef& other) { Reset(other); return *this; } // Move assignment. template ::value>> ScopedJavaLocalRef& operator=(ScopedJavaLocalRef&& other) { env_ = other.env_; Reset(); JavaRef::steal(std::move(other)); return *this; } // Assignment for other JavaRef types. ScopedJavaLocalRef& operator=(const JavaRef& other) { Reset(other); return *this; } void Reset() { JavaRef::ResetLocalRef(env_); } template ::value>> void Reset(const ScopedJavaLocalRef& other) { // We can copy over env_ here as |other| instance must be from the same // thread as |this| local ref. (See class comment for multi-threading // limitations, and alternatives). env_ = JavaRef::SetNewLocalRef(other.env_, other.obj()); } void Reset(const JavaRef& other) { // If |env_| was not yet set (is still null) it will be attached to the // current thread in SetNewLocalRef(). env_ = JavaRef::SetNewLocalRef(env_, other.obj()); } // Releases the local reference to the caller. The caller *must* delete the // local reference when it is done with it. Note that calling a Java method // is *not* a transfer of ownership and Release() should not be used. T Release() { return static_cast(JavaRef::ReleaseInternal()); } private: // This class is only good for use on the thread it was created on so // it's safe to cache the non-threadsafe JNIEnv* inside this object. raw_ptr env_ = nullptr; // Prevent ScopedJavaLocalRef(JNIEnv*, T obj) from being used to take // ownership of a JavaParamRef's underlying object - parameters are not // allowed to be deleted and so should not be owned by ScopedJavaLocalRef. // TODO(torne): this can be removed once JavaParamRef no longer has an // implicit conversion back to T. ScopedJavaLocalRef(JNIEnv* env, const JavaParamRef& other); // Friend required to get env_ from conversions. template friend class ScopedJavaLocalRef; // Avoids JavaObjectArrayReader having to accept and store its own env. template friend class JavaObjectArrayReader; }; // Holds a global reference to a Java object. The global reference is scoped // to the lifetime of this object. This class does not hold onto any JNIEnv* // passed to it, hence it is safe to use across threads (within the constraints // imposed by the underlying Java object that it references). template class ScopedJavaGlobalRef : public JavaRef { public: constexpr ScopedJavaGlobalRef() {} constexpr ScopedJavaGlobalRef(std::nullptr_t) {} // Copy constructor. This is required in addition to the copy conversion // constructor below. ScopedJavaGlobalRef(const ScopedJavaGlobalRef& other) { Reset(other); } // Copy conversion constructor. template ::value>> ScopedJavaGlobalRef(const ScopedJavaGlobalRef& other) { Reset(other); } // Move constructor. This is required in addition to the move conversion // constructor below. ScopedJavaGlobalRef(ScopedJavaGlobalRef&& other) { JavaRef::steal(std::move(other)); } // Move conversion constructor. template ::value>> ScopedJavaGlobalRef(ScopedJavaGlobalRef&& other) { JavaRef::steal(std::move(other)); } // Conversion constructor for other JavaRef types. explicit ScopedJavaGlobalRef(const JavaRef& other) { Reset(other); } // Create a new global reference to the object. // Deprecated. Don't use bare jobjects; use a JavaRef as the input. ScopedJavaGlobalRef(JNIEnv* env, T obj) { Reset(env, obj); } ~ScopedJavaGlobalRef() { Reset(); } // Null assignment, for disambiguation. ScopedJavaGlobalRef& operator=(std::nullptr_t) { Reset(); return *this; } // Copy assignment. ScopedJavaGlobalRef& operator=(const ScopedJavaGlobalRef& other) { Reset(other); return *this; } // Copy conversion assignment. template ::value>> ScopedJavaGlobalRef& operator=(const ScopedJavaGlobalRef& other) { Reset(other); return *this; } // Move assignment. template ::value>> ScopedJavaGlobalRef& operator=(ScopedJavaGlobalRef&& other) { Reset(); JavaRef::steal(std::move(other)); return *this; } // Assignment for other JavaRef types. ScopedJavaGlobalRef& operator=(const JavaRef& other) { Reset(other); return *this; } void Reset() { JavaRef::ResetGlobalRef(); } template ::value>> void Reset(const ScopedJavaGlobalRef& other) { Reset(nullptr, other.obj()); } void Reset(const JavaRef& other) { Reset(nullptr, other.obj()); } // Deprecated. You can just use Reset(const JavaRef&). void Reset(JNIEnv* env, const JavaParamRef& other) { Reset(env, other.obj()); } // Deprecated. Don't use bare jobjects; use a JavaRef as the input. void Reset(JNIEnv* env, T obj) { JavaRef::SetNewGlobalRef(env, obj); } // Releases the global reference to the caller. The caller *must* delete the // global reference when it is done with it. Note that calling a Java method // is *not* a transfer of ownership and Release() should not be used. T Release() { return static_cast(JavaRef::ReleaseInternal()); } }; // Wrapper for a jobjectArray which supports input iteration, allowing Java // arrays to be iterated over with a range-based for loop, or used with // functions that accept input iterators. // // The iterator returns each object in the array in turn, wrapped in a // ScopedJavaLocalRef. T will usually be jobject, but if you know that the // array contains a more specific type (such as jstring) you can use that // instead. This does not check the type at runtime! // // The wrapper holds a local reference to the array and only queries the size of // the array once, so must only be used as a stack-based object from the current // thread. // // Note that this does *not* update the contents of the array if you mutate the // returned ScopedJavaLocalRef. template class JavaObjectArrayReader { public: class iterator { public: // We can only be an input iterator, as all richer iterator types must // implement the multipass guarantee (always returning the same object for // the same iterator position), which is not practical when returning // temporary objects. using iterator_category = std::input_iterator_tag; using difference_type = ptrdiff_t; using value_type = ScopedJavaLocalRef; // It doesn't make sense to return a reference type as the iterator creates // temporary wrapper objects when dereferenced. Fortunately, it's not // required that input iterators actually use references, and defining it // as value_type is valid. using reference = value_type; // This exists to make operator-> work as expected: its return value must // resolve to an actual pointer (otherwise the compiler just keeps calling // operator-> on the return value until it does), so we need an extra level // of indirection. This is sometimes called an "arrow proxy" or similar, and // this version is adapted from base/value_iterators.h. class pointer { public: explicit pointer(const reference& ref) : ref_(ref) {} pointer(const pointer& ptr) = default; pointer& operator=(const pointer& ptr) = delete; reference* operator->() { return &ref_; } private: reference ref_; }; iterator(const iterator&) = default; ~iterator() = default; iterator& operator=(const iterator&) = default; bool operator==(const iterator& other) const { DCHECK(reader_ == other.reader_); return i_ == other.i_; } bool operator!=(const iterator& other) const { DCHECK(reader_ == other.reader_); return i_ != other.i_; } reference operator*() const { DCHECK(i_ < reader_->size_); // JNIEnv functions return unowned local references; take ownership with // Adopt so that ~ScopedJavaLocalRef will release it automatically later. return value_type::Adopt( reader_->array_.env_, static_cast(reader_->array_.env_->GetObjectArrayElement( reader_->array_.obj(), i_))); } pointer operator->() const { return pointer(operator*()); } iterator& operator++() { DCHECK(i_ < reader_->size_); ++i_; return *this; } iterator operator++(int) { iterator old = *this; ++*this; return old; } private: iterator(const JavaObjectArrayReader* reader, jsize i) : reader_(reader), i_(i) {} raw_ptr> reader_; jsize i_; friend JavaObjectArrayReader; }; JavaObjectArrayReader(const JavaRef& array) : array_(array) { size_ = array_.env_->GetArrayLength(array_.obj()); } // Copy constructor to allow returning it from JavaRef::ReadElements(). JavaObjectArrayReader(const JavaObjectArrayReader& other) = default; // Assignment operator for consistency with copy constructor. JavaObjectArrayReader& operator=(const JavaObjectArrayReader& other) = default; // Allow move constructor and assignment since this owns a local ref. JavaObjectArrayReader(JavaObjectArrayReader&& other) = default; JavaObjectArrayReader& operator=(JavaObjectArrayReader&& other) = default; bool empty() const { return size_ == 0; } jsize size() const { return size_; } iterator begin() const { return iterator(this, 0); } iterator end() const { return iterator(this, size_); } private: ScopedJavaLocalRef array_; jsize size_; friend iterator; }; } // namespace android } // namespace base #endif // BASE_ANDROID_SCOPED_JAVA_REF_H_