udkapi/com/sun/star/java/XJavaVM.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XJavaVM.idl,v $
  10  * $Revision: 1.19 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_java_XJavaVM_idl__
  31 #define __com_sun_star_java_XJavaVM_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 //=============================================================================
  38
  39 module com {  module sun {  module star {  module java {
  40
  41 //=============================================================================
  42
  43 // DocMerge from xml: interface com::sun::star::java::XJavaVM
  44 /** must be implemented by the user of the XJavaVM.
  45
  46     @deprecated
  47     A UNO interface seems to be at the wrong abstraction level for this
  48     functionality (also, the C++ classes <code>jvmaccess::VirtualMachine</code>
  49     and <code>jvmaccess::UnoVirtualMachine</code> used by
  50     <member scope="com::sun::star::java">XJavaVM::getJavaVM</member> are not
  51     part of the public C++ UNO runtime API).  This should probably be replaced
  52     by an appropriate C/C++ API.
  53  */
  54 published interface XJavaVM: com::sun::star::uno::XInterface
  55 {
  56     //-------------------------------------------------------------------------
  57
  58     // DocMerge from xml: method com::sun::star::java::XJavaVM::getJavaVM
  59     /** returns the address of the Java Virtual Machine.
  60
  61         <p>If the VM is not already instantiated, it will be now.</p>
  62
  63         <p>If the <code>processID</code> is a normal 16-byte ID, the returned
  64         <atom>any</atom> contains a JNI <code>JavaVM</code> pointer as a
  65         <atom>long</atom> or <atom>hyper</atom> integer (depending on the
  66         platform).  If the <code>processID</code> does not match the current
  67         process, or if the VM cannot be instantiated for whatever reason, a
  68         <void/> <atom>any</atom> is returned.</p>
  69
  70         <p>If the <code>processID</code> has an additional 17th byte of
  71         value&nbsp;<code>0</code>, the returned <atom>any</atom> contains a
  72         non&ndash;reference-counted pointer to a (reference-counted) instance of
  73         the C++ <code>jvmaccess::VirtualMachine</code> class, always represented
  74         as a <atom>hyper</atom> integer.  The pointer is guaranteed to be valid
  75         as long as the reference to this
  76         <type scope="com::sun::star::java">XJavaVM</type> is valid (but the
  77         pointer should be converted into a reference-counted reference as soon
  78         as possible).  Again, if the first 16 bytes of the
  79         <code>processID</code> do not match the current process, or if the VM
  80         cannot be instantiated for whatever reason, a <void/> <atom>any</atom>
  81         is returned.</p>
  82
  83         <p>If the <code>processID</code> has an additional 17th byte of
  84         value&nbsp;<code>1</code>, the returned <atom>any</atom> contains a
  85         non&ndash;reference-counted pointer to a (reference-counted) instance of
  86         the C++ <code>jvmaccess::UnoVirtualMachine</code> class, always
  87         represented as a <atom>hyper</atom> integer.  The pointer is guaranteed
  88         to be valid as long as the reference to this
  89         <type scope="com::sun::star::java">XJavaVM</type> is valid.  Again, if
  90         the first 16 bytes of the <code>processID</code> do not match the
  91         current process, or if the VM cannot be instantiated for whatever
  92         reason, a <void/> <atom>any</atom> is returned.</p>
  93
  94         <p>The first form (returning a JNI <code>JavaVM</code> pointer) is
  95         mainly for backwards compatibility, new code should use the second form
  96         (returning a pointer to a <code>jvmaccess::VirtualMachine</code>) if it
  97         does not want to use the Java UNO environment, and it should use the
  98         third form (returning a pointer to a
  99         <code>jvmaccess::UnoVirtualMachine</code>) if it wants to use the Java
 100         UNO environment.  For example, one advantage of using
 101         <code>jvmaccess::VirtualMachine</code> instead of the raw
 102         <code>JavaVM</code> pointer is that whenever you attach a native thread
 103         to the Java virtual machine, that thread's context
 104         <code>ClassLoader</code> (see
 105         <code>java.lang.Thread.getContextClassLoader</code>) will automatically
 106         be set to a meaningful value.</p>
 107
 108         @param processID
 109         The process ID of the caller's process, possibly extended by a 17th byte
 110         of value <code>0</code> or&nbsp;<code>1</code>.
 111
 112         @return
 113         On success, the <atom>any</atom> contains a pointer represented as
 114         <atom>long</atom> or <atom>hyper</atom>, otherwise the <atom>any</atom>
 115         is <void/>.
 116      */
 117     any getJavaVM( [in] sequence<byte> processID );
 118
 119     //-------------------------------------------------------------------------
 120
 121     // DocMerge from xml: method com::sun::star::java::XJavaVM::isVMStarted
 122     /** returns <true/> if the VM is started successfully, otherwise <false/>.
 123      */
 124     boolean isVMStarted();
 125
 126     //-------------------------------------------------------------------------
 127
 128     // DocMerge from xml: method com::sun::star::java::XJavaVM::isVMEnabled
 129     /** Returns <true/> if the VM is enabled.
 130
 131         <p>It is only possible to get the VM, if this method return 0. </p>
 132      */
 133     boolean isVMEnabled();
 134
 135 };
 136
 137 //=============================================================================
 138
 139 }; }; }; };
 140
 141 /*=============================================================================
 142
 143 =============================================================================*/
 144 #endif