1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 /** @HTML */ 25 #if !defined INCLUDED_JVMFWK_VENDORPLUGIN_H 26 #define INCLUDED_JVMFWK_VENDORPLUGIN_H 27 28 #include "jvmfwk/framework.h" 29 #include "jvmfwk/jvmfwkdllapi.h" 30 #include "rtl/ustring.h" 31 #ifdef SOLAR_JAVA 32 #include "jni.h" 33 #endif 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 40 /** 41 @file 42 <p> 43 This API shall be implemented if one wants to support a Java Runtime 44 Environment (JRE) of a particular vendor. Because there is currently no 45 specification which rules the structure and location of JRE installations 46 and the format of version strings it is not possible to supply a general 47 implementation for all possible vendors. If an application determines exactly 48 what version a JRE must have then it relies on certain features and bug 49 fixes of that version. Because a version 1.4.2_1 from vendor X may contain 50 different fixes as the same version from vendor Y it is important to see 51 version an vendor as one entity. One without the other does not guarantee 52 the existence of a particular set of features or bug fixes. An implementation 53 of this API may support multiple vendors. </p> 54 <p> 55 Libraries which implement this interface will be dynamically loaded and 56 unloaded by the java framework (jvmfwk/framework.h). Therefore they must not 57 keep global variables. 58 </p> 59 */ 60 61 typedef enum 62 { 63 JFW_PLUGIN_E_NONE, 64 JFW_PLUGIN_E_ERROR, 65 JFW_PLUGIN_E_INVALID_ARG, 66 JFW_PLUGIN_E_WRONG_VERSION_FORMAT, 67 JFW_PLUGIN_E_FAILED_VERSION, 68 JFW_PLUGIN_E_NO_JRE, 69 JFW_PLUGIN_E_WRONG_VENDOR, 70 JFW_PLUGIN_E_VM_CREATION_FAILED 71 } javaPluginError; 72 73 74 75 /** obtains information about installations of Java Runtime Environments (JREs). 76 77 <p>The function gathers information about available JREs which have the same 78 vendor as determined by the <code>sVendor</code> parameter. Only information 79 about those JREs which match the version requirements are returned. These 80 requirements are specified by the parameters <code>sMinVersion</code>, 81 <code>sMaxVersion</code> and <code>arExcludeList</code>. 82 </p> 83 <p> 84 The JavaInfo structures returned in <code>parJavaInfo</code> should be ordered 85 according to their version. The one, representing a JRE with the highest 86 version should be the first in the array. </p> 87 <p> 88 The function allocates memory for an array and all the JavaInfo objects returned 89 in <code>parJavaInfo</code>. The caller must free each JavaInfo object by calling 90 <code>jfw_freeJavaInfo</code> (#include "jvmfwk/framework.h"). The array is to be 91 freed by rtl_freeMemory. 92 In case an error occurred <code>parJavaInfo</code> need not be freed. 93 </p> 94 @param sVendor 95 [in] only JREs from this vendor are examined. This parameter always contains 96 a vendor string. That is, the string it is not empty. 97 @param sMinVersion 98 [in] represents the minimum version of a JRE. The string can be empty but 99 a null pointer is not allowed. 100 @param sMaxVersion 101 [in] represents the maximum version of a JRE. The string can be empty but 102 a null pointer is not allowed. 103 @param arExcludeList 104 [in] contains a list of "bad" versions. JREs which have one of these 105 versions must not be returned by this function. It can be NULL. 106 @param nSizeExcludeList 107 [in] the number of version strings contained in <code>arExcludeList</code>. 108 @param parJavaInfo 109 [out] if the function runs successfully then <code>parJavaInfo</code> contains 110 on return an array of pointers to <code>JavaInfo</code> objects. 111 @param nSizeJavaInfo 112 [out] the number of <code>JavaInfo</code> pointers contained in 113 <code>parJavaInfo</code>. 114 115 @return 116 JFW_PLUGIN_E_NONE the function ran successfully.</br> 117 JFW_PLUGIN_E_ERROR an error occurred during execution.</br> 118 JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example 119 <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code> 120 is NULL or NULL pointer were passed for at least on of the strings.</br> 121 JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in 122 <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid 123 version strings. 124 */ 125 JVMFWK_DLLPUBLIC javaPluginError jfw_plugin_getAllJavaInfos( 126 rtl_uString *sVendor, 127 rtl_uString *sMinVersion, 128 rtl_uString *sMaxVersion, 129 rtl_uString * * arExcludeList, 130 sal_Int32 nSizeExcludeList, 131 JavaInfo*** parJavaInfo, 132 sal_Int32 *nSizeJavaInfo); 133 134 /** obtains information for a JRE at a given location. 135 136 <p>If the given location belongs to a JRE whoose vendor matches the 137 sVendor argument and the JRE has a version which meets the requirements as 138 specified by <code>sMinVersion, sMaxVersion, arExcludeList</code> then 139 this function shall return a JavaInfo object for this JRE if this implementation 140 supports this vendor.</p> 141 142 @param sLocation 143 [in] a file URL to the directory of the JRE. 144 @param sVendor 145 [in] a name of a vendor. This parameter always contains 146 a vendor string. That is, the string it is not empty. 147 @param sMinVersion 148 [in] represents the minimum version of a JRE. 149 @param sMaxVersion 150 [in] represents the maximum version of a JRE. 151 @param arExcludeList 152 [in] contains a list of "bad" versions. JREs which have one of these 153 versions must not be returned by this function. It can be NULL. 154 @param nSizeExcludeList 155 [in] the number of version strings contained in <code>arExcludeList</code>. 156 @param ppInfo 157 [out] if the function runs successfully then <code>ppInfo</code> contains 158 on return a pointer to a <code>JavaInfo</code> object. 159 160 @return 161 JFW_PLUGIN_E_NONE the function ran successfully.</br> 162 JFW_PLUGIN_E_ERROR an error occurred during execution.</br> 163 JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example 164 <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code> 165 is NULL, NULL pointer were passed for at least on of the strings, sLocation 166 is an empty string.</br> 167 JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in 168 <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid 169 version strings. 170 JFW_PLUGIN_E_FAILED_VERSION there is a JRE at the given location but it does not 171 meet the version requirements. 172 JFW_PLUGIN_E_NO_JRE no JRE could be detected at the given location. However, that 173 does not mean necessarily that there is no JRE. There could be a JRE but it has 174 a vendor which is not supported by this API implementation. 175 */ 176 JVMFWK_DLLPUBLIC javaPluginError jfw_plugin_getJavaInfoByPath( 177 rtl_uString *sLocation, 178 rtl_uString *sVendor, 179 rtl_uString *sMinVersion, 180 rtl_uString *sMaxVersion, 181 rtl_uString * *arExcludeList, 182 sal_Int32 nSizeExcludeList, 183 JavaInfo ** ppInfo); 184 185 /** starts a Java Virtual Machine. 186 187 <p>The caller should provide all essential JavaVMOptions, such as the 188 class path (-Djava.class.path=xxx). It is assumed that the caller 189 knows what JRE is used. Hence the implementation does not need to check 190 the options for validity. If a user configured the application to 191 use specific options, such as -X..., then it is in his responsibility to 192 ensure that the application works properly. The function may add or modify 193 properties. For example, it may add to the class path property. 194 <p> 195 The function must ensure, that the VM does not abort the process 196 during instantiation.</p> 197 <p> 198 The function receives a <code>JavaInfo</code> object that was created 199 by the functions <code>jfw_plugin_getJavaInfoByPath</code> or 200 <code>jfw_plugin_getAllJavaInfos</code> from the same library. This can be 201 guaranteed if an application uses exactly one library for one vendor. 202 Therefore the functions which create the <code>JavaInfo</code> can store all 203 necessary information which are needed for starting the VM into that 204 structure. </p> 205 206 @param pInfo 207 [in] the JavaInfo object with information about the JRE. 208 @param arOptions 209 [in] the options which are passed into the JNI_CreateJavaVM function. 210 Can be NULL. 211 @param nSizeOptions 212 [in] the number of elements in <code>arOptions</code>. 213 @param ppVM 214 [out] the JavaVM pointer of the created VM. 215 @param ppEnv 216 [out] the JNIEnv pointer of the created VM. 217 218 @return 219 JFW_PLUGIN_E_NONE the function ran successfully.</br> 220 JFW_PLUGIN_E_ERROR an error occurred during execution.</br> 221 JFW_PLUGIN_E_WRONG_VENDOR the <code>JavaInfo</code> object was not created 222 in by this library and the VM cannot be started.</br> 223 JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example 224 <code>pInfo</code> or , <code>ppVM</code> or <code>ppEnv</code> are NULL. 225 </br> 226 JFW_PLUGIN_E_VM_CREATION_FAILED a VM could not be created. The error was caused 227 by the JRE. 228 */ 229 JVMFWK_DLLPUBLIC javaPluginError jfw_plugin_startJavaVirtualMachine( 230 const JavaInfo *pInfo, 231 const JavaVMOption *arOptions, 232 sal_Int32 nSizeOptions, 233 JavaVM ** ppVM, 234 JNIEnv ** ppEnv); 235 236 237 238 /** checks if the installation of the jre still exists. 239 240 This function checks if the JRE described by pInfo still 241 exists. The check must be very quick because it is called by javaldx 242 (Linux, Solaris) at start up. 243 244 @param pInfo 245 [in] the JavaInfo object with information about the JRE. 246 @param pp_exist 247 [out] the parameter is set to either sal_True or sal_False. The value is 248 only valid if the function returns JFW_E_NONE. 249 250 @return 251 JFW_PLUGIN_E_NONE the function ran successfully.</br> 252 JFW_PLUGIN_E_ERROR an error occurred during execution.</br> 253 JFW_PLUGIN_E_INVALID_ARG pInfo contains invalid data</br> 254 */ 255 JVMFWK_DLLPUBLIC javaPluginError jfw_plugin_existJRE(const JavaInfo *pInfo, sal_Bool *exist); 256 257 #ifdef __cplusplus 258 } 259 #endif 260 261 262 #endif 263