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 #include <jni.h>
  28
  29 namespace jvmaccess {
  30
  31 /** An encapsulating wrapper around a Java virtual machine.
  32  */
  33 class JVMACCESS_DLLPUBLIC VirtualMachine: public salhelper::SimpleReferenceObject
  34 {
  35 public:
  36     /** A helper to attach a thread to a Java virtual machine.
  37
  38         @descr
  39         Upon construction of a guard the current thread is attached to the
  40         virtual machine, and upon destruction of the guard the thread is
  41         detached again.  For any one thread, multiple instances of this class
  42         may be used in a stack-like fashion (care is taken to only really
  43         detach the thread from the virtual machine upon destruction of the guard
  44         at the bottom of the stack).
  45      */
  46     class JVMACCESS_DLLPUBLIC AttachGuard
  47     {
  48     public:
  49         /** An exception indicating failure to create an AttachGuard.
  50          */
  51         class JVMACCESS_DLLPUBLIC CreationException final
  52         {
  53         public:
  54             CreationException();
  55
  56             CreationException(CreationException const &);
  57
  58             ~CreationException();
  59
  60             CreationException & operator =(CreationException const &);
  61         };
  62
  63         /** Attach the current thread to a virtual machine.
  64
  65             @param rMachine
  66             The virtual machine to attach to.  Must not be a null reference.
  67
  68             @exception CreationException
  69             Thrown in case attaching fails (due to a JNI problem).
  70          */
  71         explicit AttachGuard(rtl::Reference< VirtualMachine > const & rMachine);
  72
  73         /** Detach the current thread from the virtual machine again.
  74          */
  75         ~AttachGuard();
  76
  77         /** Get a JNI environment pointer for the current thread.
  78
  79             @return
  80             A valid JNI environment pointer.  Will never be null.
  81          */
  82         JNIEnv * getEnvironment() const { return m_pEnvironment; }
  83
  84     private:
  85         AttachGuard(AttachGuard const &) = delete;
  86         AttachGuard& operator =(AttachGuard const &) = delete;
  87
  88         rtl::Reference< VirtualMachine > m_xMachine;
  89         JNIEnv * m_pEnvironment;
  90         bool m_bDetach;
  91     };
  92
  93     /** Create a wrapper around a Java virtual machine.
  94
  95         @param pVm
  96         A JNI pointer to virtual machine.  Must not be null.
  97
  98         @param nVersion
  99         The JNI version of the virtual machine pointed to by pVm.  Must be at
 100         least JNI_VERSION_1_2.  This parameter should be of type jint, not int,
 101         but at least on some platforms the definition of jint changed from
 102         JDK 1.3 (long) to JDK 1.4 (int), so that the mangled C++ name of the
 103         constructor would depend on the JDK version used at compile time.
 104
 105         @param bDestroy
 106         Whether to destroy the virtual machine when destructing the wrapper
 107         (i.e., whether the wrapper owns the virtual machine pointed to by pVm).
 108
 109         @param pMainThreadEnv
 110         A valid JNI environment pointer for the current thread; must not be
 111         null.  The current thread must be "initially attached" to the virtual
 112         machine while this constructor is being called (i.e., it must be the
 113         thread that has called JNI_CreateJavaVM in case the virtual machine has
 114         been started via the JNI Invocation API, and it must not already have
 115         called DetachCurrentThread; or it must be executing native code called
 116         from a "primordial" virtual machine).  This environment pointer was
 117         formerly used to obtain a reference to the thread's current context
 118         class loader (java.lang.Thread.getCurrentClassLoader; if later a native
 119         thread was attached to the virtual machine, that thread's context class
 120         loader would be null, so the AttachGuard first of all set it to the
 121         saved value; this feature has been removed again for performance reasons
 122         and because the default context class loader is often not useful, so
 123         that code relying on a context class loader has to set one explicitly,
 124         anyway).  This parameter is currently unused (but may be used again in
 125         the future).
 126      */
 127     VirtualMachine(JavaVM * pVm, int nVersion, bool bDestroy,
 128                    JNIEnv const * pMainThreadEnv);
 129
 130 private:
 131     VirtualMachine(VirtualMachine const &) = delete;
 132     VirtualMachine& operator =(VirtualMachine const & ) = delete;
 133
 134     virtual ~VirtualMachine() override;
 135
 136     JNIEnv * attachThread(bool * pAttached) const;
 137
 138     void detachThread() const;
 139
 140     JavaVM * m_pVm;
 141     jint m_nVersion;
 142     bool m_bDestroy;
 143
 144     friend class AttachGuard; // to access attachThread, detachThread
 145 };
 146
 147 }
 148
 149 #endif // INCLUDED_JVMACCESS_VIRTUALMACHINE_HXX
 150
 151 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */