include/jvmaccess/virtualmachine.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_JVMACCESS_VIRTUALMACHINE_HXX
  21 #define INCLUDED_JVMACCESS_VIRTUALMACHINE_HXX
  22
  23 #include <jvmaccess/jvmaccessdllapi.h>
  24 #include <rtl/ref.hxx>
  25 #include <salhelper/simplereferenceobject.hxx>
  26
  27 #if defined __clang__
  28 #pragma clang diagnostic push
  29 #pragma clang diagnostic ignored "-Wunknown-attributes"
  30 #endif
  31 #include <jni.h>
  32 #if defined __clang__
  33 #pragma clang diagnostic pop
  34 #endif
  35
  36 namespace jvmaccess
  37 {
  38 /** An encapsulating wrapper around a Java virtual machine.
  39  */
  40 class JVMACCESS_DLLPUBLIC VirtualMachine final : public salhelper::SimpleReferenceObject
  41 {
  42 public:
  43     /** A helper to attach a thread to a Java virtual machine.
  44
  45         @descr
  46         Upon construction of a guard the current thread is attached to the
  47         virtual machine, and upon destruction of the guard the thread is
  48         detached again.  For any one thread, multiple instances of this class
  49         may be used in a stack-like fashion (care is taken to only really
  50         detach the thread from the virtual machine upon destruction of the guard
  51         at the bottom of the stack).
  52      */
  53     class JVMACCESS_DLLPUBLIC AttachGuard
  54     {
  55     public:
  56         /** An exception indicating failure to create an AttachGuard.
  57          */
  58         class JVMACCESS_DLLPUBLIC CreationException final
  59         {
  60         public:
  61             CreationException();
  62
  63             CreationException(CreationException const&);
  64
  65             CreationException& operator=(CreationException const&);
  66         };
  67
  68         /** Attach the current thread to a virtual machine.
  69
  70             @param rMachine
  71             The virtual machine to attach to.  Must not be a null reference.
  72
  73             @exception CreationException
  74             Thrown in case attaching fails (due to a JNI problem).
  75          */
  76         explicit AttachGuard(rtl::Reference<VirtualMachine> xMachine);
  77
  78         /** Detach the current thread from the virtual machine again.
  79          */
  80         ~AttachGuard();
  81
  82         /** Get a JNI environment pointer for the current thread.
  83
  84             @return
  85             A valid JNI environment pointer.  Will never be null.
  86          */
  87         JNIEnv* getEnvironment() const { return m_pEnvironment; }
  88
  89     private:
  90         AttachGuard(AttachGuard const&) = delete;
  91         AttachGuard& operator=(AttachGuard const&) = delete;
  92
  93         rtl::Reference<VirtualMachine> m_xMachine;
  94         JNIEnv* m_pEnvironment;
  95         bool m_bDetach;
  96     };
  97
  98     /** Create a wrapper around a Java virtual machine.
  99
 100         @param pVm
 101         A JNI pointer to virtual machine.  Must not be null.
 102
 103         @param nVersion
 104         The JNI version of the virtual machine pointed to by pVm.  Must be at
 105         least JNI_VERSION_1_2.  This parameter should be of type jint, not int,
 106         but at least on some platforms the definition of jint changed from
 107         JDK 1.3 (long) to JDK 1.4 (int), so that the mangled C++ name of the
 108         constructor would depend on the JDK version used at compile time.
 109
 110         @param bDestroy
 111         Whether to destroy the virtual machine when destructing the wrapper
 112         (i.e., whether the wrapper owns the virtual machine pointed to by pVm).
 113
 114         @param pMainThreadEnv
 115         A valid JNI environment pointer for the current thread; must not be
 116         null.  The current thread must be "initially attached" to the virtual
 117         machine while this constructor is being called (i.e., it must be the
 118         thread that has called JNI_CreateJavaVM in case the virtual machine has
 119         been started via the JNI Invocation API, and it must not already have
 120         called DetachCurrentThread; or it must be executing native code called
 121         from a "primordial" virtual machine).  This environment pointer was
 122         formerly used to obtain a reference to the thread's current context
 123         class loader (java.lang.Thread.getCurrentClassLoader; if later a native
 124         thread was attached to the virtual machine, that thread's context class
 125         loader would be null, so the AttachGuard first of all set it to the
 126         saved value; this feature has been removed again for performance reasons
 127         and because the default context class loader is often not useful, so
 128         that code relying on a context class loader has to set one explicitly,
 129         anyway).  This parameter is currently unused (but may be used again in
 130         the future).
 131      */
 132     VirtualMachine(JavaVM* pVm, int nVersion, bool bDestroy, JNIEnv const* pMainThreadEnv);
 133
 134 private:
 135     VirtualMachine(VirtualMachine const&) = delete;
 136     VirtualMachine& operator=(VirtualMachine const&) = delete;
 137
 138     virtual ~VirtualMachine() override;
 139
 140     JNIEnv* attachThread(bool* pAttached) const;
 141
 142     void detachThread() const;
 143
 144     JavaVM* m_pVm;
 145     jint m_nVersion;
 146     bool m_bDestroy;
 147
 148     friend class AttachGuard; // to access attachThread, detachThread
 149 };
 150 }
 151
 152 #endif // INCLUDED_JVMACCESS_VIRTUALMACHINE_HXX
 153
 154 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */