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