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 26 #if !defined INCLUDED_JVMFWK_FRAMEWORK_H 27 #define INCLUDED_JVMFWK_FRAMEWORK_H 28 29 #include "rtl/ustring.h" 30 #include "osl/mutex.h" 31 #include "jvmfwk/jvmfwkdllapi.h" 32 #ifdef SOLAR_JAVA 33 #include "jni.h" 34 #else 35 struct JavaVMOption; 36 struct JavaVM; 37 struct JNIEnv; 38 #endif 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** @file 45 <p>This library can operate in two modes, application mode and direct mode.</p> 46 47 48 <h2>Application Mode</h2> 49 In application mode the Java related settings are stored in files. 50 There are currently three files which need to be accessed. They are determined 51 by bootstrap parameters:</p> 52 <dl> 53 <dt>UNO_JAVA_JFW_VENDOR_SETTINGS</dt> 54 <dd>contains vendor and version information about JREs as well as the 55 location of plugin-libraries which are responsible for providing information 56 about these JREs as well as starting the VMs.</dd> 57 <dt>UNO_JAVA_JFW_USER_DATA</dt> 58 <dd>The file contains settings for a particular user. One can use the macro 59 $SYSUSERCONFIG in the URL which expands to a directory whery the user's data are 60 kept. On UNIX this would be the home directory and on Windows some sub-directory 61 of the "Documents and Settings" folder.The content of this file is an 62 implementation detail and may change in the future.</dd> 63 <dt>UNO_JAVA_JFW_SHARED_DATA</dt> 64 <dd>The file contains settings valid for all users. If a user changes a setting 65 then it takes precedence over the setting from UNO_JAVA_JFW_SHARED_DATA. 66 The content of this file is an implementation detail and may change in the future.</dd> 67 68 <dt>UNO_JAVA_JFW_INSTALL_DATA</dt> 69 <dd><b>DEPRECATED. Support for this variable will soon be removed.</b><br> 70 The file contains settings for all users. A user cannot override these settings. 71 When this parameter is provided then UNO_JAVA_JFW_SHARED_DATA and UNO_JAVA_JFW_USER_DATA 72 are irrelevant. This parameter is intended for use during the setup. For example, to 73 install extensions which contain java components. If there is already a file at this 74 location then it will be overwritten if it is too old. The period of validatity is per 75 default one hour. This value can be overridden by the bootstrap parameter 76 UNO_JAVA_JFW_INSTALL_EXPIRE (<b>DEPRECATED</b>). Setting this variable to 1000 means 77 the settings file is only valid for 1000 seconds. 78 79 <p>If one would not use UNO_JAVA_JFW_INSTALL_DATA during setup then most probably 80 a user installation directory would be created in the home directory of root. This is 81 because, java settings are determined and stored on behalf of the current user. In other 82 words UNO_JAVA_JFW_USER_DATA would be used which points into the user installation. 83 </p> 84 <p>UNO_JAVA_JFW_INSTALL_DATA could point into the shared installation, provided that 85 only people with root rights can install OOo. Then one has to take care that the 86 installer removes this file when uninstalling. 87 </p> 88 89 90 The content of this file is an implementation detail and may change in the future.</dd> 91 </dl> 92 93 <p>The values for these parameters must be file URLs and include the file name, for 94 example:<br> 95 file:///d:/MyApp/javavendors.xml<br> 96 All files are XML files and must have the extension .xml.</p> 97 <p> 98 Modifying the shared settings is currently not supported by the framework. To provide 99 Java settings for all users one can run OOo and change the settings in the 100 options dialog. These settings are made persistent in the UNO_JAVA_JFW_USER_DATA. 101 The file can then be copied into the base installation. 102 Other users will use automatically these data but can override the settings in 103 the options dialog. This mechanism may change in the future. 104 </p> 105 <p>If shared Java settings are not supported by an application then it is not 106 necessary to specify the bootstrap parameter <code>UNO_JAVA_JFW_SHARED_DATA</code>. 107 </p> 108 109 <p>Setting the class path used by a Java VM should not be necesarry. The locations 110 of Jar files should be knows by a class loader. If a jar file depends on another 111 jar file then it can be referenced in the manifest file of the first jar. However, 112 a user may add jars to the class path by using this API. If it becomes necessary 113 to add files to the class path which is to be used by all users then one can use 114 the bootrap parameter UNO_JAVA_JFW_CLASSPATH_URLS. The value contains of file URLs 115 which must be separated by spaces.</p> 116 117 118 <h2>Direct Mode</h2> 119 120 <p>The direct mode is intended for a scenario where no configuration files 121 are available and a Java VM shall be run. That is, 122 the files containing the user and shared settings are not specified by the 123 bootstrap parameters UNO_JAVA_JFW_SHARED_DATA and UNO_JAVA_JFW_USER_DATA. 124 For example, tools, such as regcomp, may use this framework in a build 125 environment. Then one would want to use settings which have been specified 126 by the build environment. The framework would automatically use the 127 current settings when they change in the environment. 128 </p> 129 130 <p> Here are examples how regcomp could be invoked using bootstrap parameters: 131 </p> 132 <p> 133 regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 134 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" 135 -register .... 136 </p> 137 <p>If UNO_JAVA_JFW_VENDOR_SETTINGS is not set then a plugin library must be specified. For example:</p> 138 <p> 139 regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 140 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" 141 -env:UNO_JAVA_JFW_PLUGIN=file:\\solver\\bin\\sunjavaplugin.dll -register .... 142 </p> 143 <p>Additionall parameters for the Java VM can be provided. For every parameter 144 a separate bootstrap parameter must be specified. The names are 145 <code>UNO_JAVA_JFW_PARAMETER_X</code>, where X is 1,2, .. n. For example:</p> 146 <p> 147 regcomp -env:UNO_JAVA_JFW_PARAMETER_1=-Xdebug 148 -env:UNO_JAVA_JFW_PARAMETER_2=-Xrunjdwp:transport=dt_socket,server=y,address=8100 149 -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 150 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" 151 -register ....</p> 152 <p> 153 Here is a complete list of the bootstrap parameter for the direct mode: 154 </p> 155 <dl> 156 <dt>UNO_JAVA_JFW_JREHOME</dt> 157 <dd>Specifies a file URL to a JRE installation.It must ALWAYS be specified 158 in direct mode</dd> 159 <dt>UNO_JAVA_JFW_ENV_JREHOME</dt> 160 <dd>Setting this parameter, for example to "1" or "true", 161 causes the framework to use the environment variable JAVA_HOME. It is expected 162 that JAVA_HOME contains a system path rather than a file URL. This parameter 163 and UNO_JAVA_JFW_JREHOME are mutually exclusive</dd> 164 <dt>UNO_JAVA_JFW_CLASSPATH</dt> 165 <dd>Contains the class path which is to be used by the VM. Special character, 166 such as '\','{','}','$' must be preceded with '\'. See documentation about the 167 bootstrap parameter.</dd> 168 <dt>UNO_JAVA_JFW_ENV_CLASSPATH</dt> 169 <dd>Setting this parameter,for example to "1" or "true", 170 causes the framework to use the 171 environment variable CLASSPATH. If this variable and UNO_JAVA_JFW_CLASSPATH are 172 set then the class path is composed from UNO_JAVA_JFW_CLASSPATH and the environment 173 variable CLASSPATH.</dd> 174 <dt>UNO_JAVA_JFW_PLUGIN</dt> 175 <dd>Specified a file URL to a plugin library. If this variable is provided 176 then a javavendors.xml is ignored. It must be provided if no 177 javavendors.xml is available.</dd> 178 <dt>UNO_JAVA_JFW_PARAMETER_X</dt> 179 <dd>Specifies a parameter for the Java VM. The X is replaced by 180 non-negative natural numbers starting with 1.</dd> 181 </dl> 182 183 <p>A note about bootstrap parameters. The implementation of the bootstrap 184 parameter mechanism interprets the characters '\', '$', '{', '}' as 185 escape characters. That's why the Windows path contains double back-slashes. 186 One should also take into account that a console may have also special 187 escape characters.</p> 188 189 <h2>What mode is used</h2> 190 <p> 191 The default mode is application mode. If at least one bootstrap parameter 192 for the direct mode is provided then direct mode is used. </p> 193 194 <p> 195 All settings made by this API are done for the current user if not 196 mentioned differently.</p> 197 198 <h2>Other bootstrap variables</h2> 199 <dl> 200 <dt>JFW_PLUGIN_DO_NOT_CHECK_ACCESSIBILITY</dt> 201 <dd>This is a unofficial variable which was introduced to workaround external issues. 202 It may be removed in the future. By setting it to 1, the framework will not try to 203 find out if the system is configured to use accessibility tools or if a JRE has an 204 accessibiliy bridge installed</dd> 205 </dl> 206 */ 207 208 /** indicates that a JRE has an accessibility bridge installed. 209 <p> 210 The flag is used with JavaInfo::nFeatures.</p> 211 */ 212 #define JFW_FEATURE_ACCESSBRIDGE 0x1l 213 /** indicates that there must be an environment set up before the Java process 214 runs. 215 <p>Therefore, when a Java is selected in OO then the office must be 216 restarted, so that the changes can take effect.</p> 217 */ 218 #define JFW_REQUIRE_NEEDRESTART 0x1l 219 220 /** error codes which are returned by functions of this API. 221 */ 222 typedef enum _javaFrameworkError 223 { 224 JFW_E_NONE, 225 JFW_E_ERROR, 226 JFW_E_INVALID_ARG, 227 JFW_E_NO_SELECT, 228 JFW_E_INVALID_SETTINGS, 229 JFW_E_NEED_RESTART, 230 JFW_E_RUNNING_JVM, 231 JFW_E_JAVA_DISABLED, 232 JFW_E_NO_PLUGIN, 233 JFW_E_NOT_RECOGNIZED, 234 JFW_E_FAILED_VERSION, 235 JFW_E_NO_JAVA_FOUND, 236 JFW_E_VM_CREATION_FAILED, 237 JFW_E_CONFIGURATION, 238 JFW_E_DIRECT_MODE 239 } javaFrameworkError; 240 241 /** an instance of this struct represents an installation of a Java 242 Runtime Environment (JRE). 243 244 <p> 245 Instances of this struct are created by the plug-in libraries which are used by 246 this framework (jvmfwk/vendorplugin.h). The memory of the instances is created 247 by <code>rtl_allocateMemory</code> (rtl/alloc.h). Therefore, the memory must 248 be freed by <code>rtl_freeMemory</code>. Also the contained members must be 249 freed particularly. 250 For convenience this API provides the function <code>jfw_freeJavaInfo</code> 251 which frees the objects properly. </p> 252 */ 253 struct _JavaInfo 254 { 255 /** contains the vendor. 256 257 <p>string must be the same as the one obtained from the 258 Java system property <code>java.vendor</code>. 259 </p> 260 */ 261 rtl_uString *sVendor; 262 /** contains the file URL to the installation directory. 263 */ 264 rtl_uString *sLocation; 265 /** contains the version of this Java distribution. 266 267 <p>The version string must adhere to the rules 268 about how a version string has to be formed. These rules may 269 be vendor-dependent. Essentially the strings must syntactically 270 equal the Java system property <code>java.version</code>. 271 </p> 272 */ 273 rtl_uString *sVersion; 274 /** indicates supported special features. 275 276 <p>For example, <code>JFW_FEATURE_ACCESSBRIDGE</code> indicates that 277 assistive technology tools are supported.</p> 278 */ 279 sal_uInt64 nFeatures; 280 /** indicates requirments for running the java runtime. 281 282 <p>For example, it may be necessary to prepare the environment before 283 the runtime is created. That could mean, setting the 284 <code>LD_LIBRARY_PATH</code> 285 when <code>nRequirements</code> contains the flag 286 <code>JFW_REQUIRE_NEEDRESTART</code></p> 287 */ 288 sal_uInt64 nRequirements; 289 /** contains data needed for the creation of the java runtime. 290 291 <p>There is no rule about the format and content of the sequence's 292 values. The plug-in libraries can put all data, necessary for 293 starting the java runtime into this sequence. </p> 294 */ 295 sal_Sequence * arVendorData; 296 }; 297 298 typedef struct _JavaInfo JavaInfo; 299 300 /** frees the memory of a <code>JavaInfo</code> object. 301 @param pInfo 302 The object which is to be freed. It can be NULL; 303 */ 304 JVMFWK_DLLPUBLIC void SAL_CALL jfw_freeJavaInfo(JavaInfo *pInfo); 305 306 307 /** compares two <code>JavaInfo</code> objects for equality. 308 309 <p>Two <code>JavaInfo</code> objects are said to be equal if the contained 310 members of the first <code>JavaInfo</code> are equal to their counterparts 311 in the second <code>JavaInfo</code> object. The equality of the 312 <code>rtl_uString</code> members is determined 313 by the respective comparison function (see 314 <code>rtl::OUString::equals</code>). 315 Similarly the equality of the <code>sal_Sequence</code> is 316 also determined by a comparison 317 function (see <code>rtl::ByteSequence::operator ==</code>). </p> 318 <p> 319 Both argument pointers must be valid.</p> 320 @param pInfoA 321 the first argument. 322 @param pInfoB 323 the second argument which is compared with the first. 324 @return 325 sal_True - both object represent the same JRE.</br> 326 sal_False - the objects represend different JREs 327 */ 328 JVMFWK_DLLPUBLIC sal_Bool SAL_CALL jfw_areEqualJavaInfo( 329 JavaInfo const * pInfoA,JavaInfo const * pInfoB); 330 331 /** determines if a Java Virtual Machine is already running. 332 333 <p>As long as the office and the JREs only support one 334 Virtual Machine per process the Java settings, particularly the 335 selected Java, are not effective immediately after changing when 336 a VM has already been running. That is, if a JRE A was used to start 337 a VM and then a JRE B is selected, then JRE B will only be used 338 after a restart of the office.</p> 339 <p> 340 By determining if a VM is running, the user can be presented a message, 341 that the changed setting may not be effective immediately.</p> 342 343 @param bRunning 344 [out] sal_True - a VM is running. <br/> 345 sal_False - no VM is running. 346 347 @return 348 JFW_E_NONE function ran successfully.<br/> 349 JFW_E_INVALID_ARG the parameter <code>bRunning</code> was NULL. 350 */ 351 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_isVMRunning(sal_Bool *bRunning); 352 353 /** detects a suitable JRE and configures the framework to use it. 354 355 <p>Which JREs can be used is determined by the file javavendors.xml, 356 which contains version requirements, as well as information about available 357 plug-in libraries. Only these libraries are responsible for locating JRE 358 installations.</p> 359 <p> 360 JREs can be provided by different vendors. In order to find the JREs of 361 a certain vendor a plug-in library must be provided. There must be only one 362 library for one vendor. The names of locations of those libraries have to 363 be put into the javavendors.xml file.<br/> 364 The function uses the plug-in libraries to obtain information about JRE 365 installation and checks if they there is one among them that supports 366 a set of features (currently only accessibility is possible). If none was 367 found then it also uses a list of paths, which have been registered 368 by <code>jfw_addJRELocation</code> or <code>jfw_setJRELocations</code> 369 to find JREs. Found JREs are examined in the same way.</p> 370 <p> 371 A JRE installation is only selected if it meets the version requirements. 372 Information about the selected JRE are made persistent so that 373 subsequent calls to <code>jfw_getSelectedJRE</code> returns this 374 information.</p> 375 <p> 376 While determining a proper JRE this function takes into account if a 377 user requires support for assistive technology tools. If user 378 need that support they have to set up their system accordingly. When support 379 for assistive technology is required, then the lists of 380 <code>JavaInfo</code> objects, 381 which are provided by the <code>getJavaInfo</code> functions of the plug-ins, are 382 examined for a suitable JRE. That is, the <code>JavaInfo</code> objects 383 from the list 384 obtained from the first plug-in, are examined. If no <code>JavaInfo</code> 385 object has the flag 386 <code>JFW_FEATURE_ACCESSBRIDGE</code> in the member <code>nFeatures</code> 387 then the 388 next plug-in is used to obtain a list of <code>JavaInfo</code> objects. 389 This goes on until a <code>JavaInfo</code> object was found which 390 represents a suitable JRE. Or neither plug-in provided such a 391 <code>JavaInfo</code> object. In that case the first 392 <code>JavaInfo</code> object from the first plug-in is used to determine 393 the JRE which is to be used.</p> 394 <p> 395 If there is no need for the support of assistive technology tools then 396 the first <code>JavaInfo</code> object from the list obtained by the 397 first plug-in is used. If this plug-in does not find any JREs then the 398 next plug-in is used, and so on.</p> 399 400 @param ppInfo 401 [out] a <code>JavaInfo</code> pointer, representing the selected JRE. 402 The caller has to free it by calling <code>jfw_freeJavaInfo<code>. The 403 <code>JavaInfo</code> is for informational purposes only. It is not 404 necessary to call <code>jfw_setSelectedJRE</code> afterwards.<br/> 405 <code>ppInfo</code>can be NULL. If <code>*ppInfo</code> is not null, then it is 406 overwritten, without attempting to free <code>*ppInfo</code>. 407 408 @return 409 JFW_E_NONE function ran successfully.<br/> 410 JFW_E_ERROR an error occurred. <br/> 411 JFW_E_NO_PLUGIN a plug-in library could not be found.<br/> 412 JFW_E_NO_JAVA_FOUND no JRE was found that meets the requirements.</br> 413 JFW_E_DIRECT_MODE the function cannot be used in this mode. </br> 414 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 415 were not met. 416 */ 417 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_findAndSelectJRE(JavaInfo **pInfo); 418 419 /** provides information about all available JRE installations. 420 421 <p>The function determines dynamically what JREs are available. It uses 422 the plug-in libraries to provide lists of available <code>JavaInfo</code> 423 objects where each object represents a JRE (see vendorplugin.h, 424 getAllJavaInfos). It also uses a list of paths, which have been registered 425 by <code>jfw_addJRELocation</code> or <code>jfw_setJRELocations</code>. 426 It is checked if the path still contains a valid JRE and if so the respective 427 <code>JavaInfo</code> object will be appended to the array unless there is 428 already an equal object.</p> 429 430 @param parInfo 431 [out] on returns it contains a pointer to an array of <code>JavaInfo</code> 432 pointers. 433 The caller must free the array with <code>rtl_freeMemory</code> and each 434 element of the array must be freed with <code>jfw_freeJavaInfo</code>. 435 @param pSize 436 [out] on return contains the size of array returned in <code>parInfo</code>. 437 438 @return 439 JFW_E_NONE function ran successfully.<br/> 440 JFW_E_INVALID_ARG at least on of the parameters was NULL<br/> 441 JFW_E_ERROR an error occurred. <br/> 442 JFW_E_NO_PLUGIN a plug-in library could not be found.<br/> 443 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 444 were not met. 445 */ 446 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_findAllJREs( 447 JavaInfo ***parInfo, sal_Int32 *pSize); 448 449 /** determines if a path points to a Java installation. 450 451 <p>If the path belongs to a JRE installation then it returns the 452 respective <code>JavaInfo</code> object. The function uses the 453 <code>getJavaInfoByPath</code> function of the plug-ins to obtain the 454 <code>JavaInfo</code> object. Only if the JRE found at the specified location 455 meets the version requirements as specified in the javavendors.xml file a 456 <code>JavaInfo</code> object is returned.<br/> 457 <p> 458 The functions only checks if a JRE exists but does not modify any settings. 459 To make the found JRE the "selected JRE" one has 460 to call <code>jfw_setSelectedJRE</code>.</p> 461 462 @param pPath 463 [in] a file URL to a directory. 464 @param pInfo 465 [out] the <code>JavaInfo</code> object which represents a JRE found at the 466 location specified by <code>pPath</code> 467 468 @return 469 JFW_E_NONE function ran successfully.<br/> 470 JFW_E_INVALID_ARG at least on of the parameters was NULL<br/> 471 JFW_E_ERROR an error occurred. <br/> 472 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 473 were not met.</br> 474 JFW_E_NO_PLUGIN a plug-in library could not be found.<br/> 475 JFW_E_NOT_RECOGNIZED neither plug-in library could detect a JRE. <br/> 476 JFW_E_FAILED_VERSION a JRE was detected but if failed the version 477 requirements as determined by the javavendors.xml 478 */ 479 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_getJavaInfoByPath( 480 rtl_uString *pPath, JavaInfo **ppInfo); 481 482 483 /** starts a Java Virtual Machine (JVM). 484 485 <p>The function uses the current settings to start a JVM. The actual 486 start-up code, however, is provided by the plug-in libraries. The setting 487 of the "selected Java" contains the information as to what vendor 488 the respective JRE comes from. In the javavendors.xml there is a mapping of 489 vendor names to the respective plug-in libraries.</p> 490 <p> 491 The function ultimately calls <code>startJavaVirtualMachine</code> from 492 the plug-in library.</p> 493 <p> 494 The <code>arOptions</code> 495 argument contains start arguments which are passed in JavaVMOption structures 496 to the VM during its creation. These 497 could be things, such as language settings, proxy settings or any other 498 properties which shall be obtainable by 499 <code>java.lang.System.getProperties</code>. One can also pass options which 500 have a certain meaning to the runtime behaviour such as -ea or -X... However, 501 one must be sure that these options can be interpreted by the VM.<br/> 502 The class path cannot be set this way. The class path is internally composed by 503 the paths to archives in a certain directory, which is preconfigured in 504 the internal data store and the respective user setting (see 505 <code>jfw_setUserClassPath</code>.</p> 506 <p> 507 If a JRE was selected at runtime which was different from the previous 508 setting and that JRE needs a prepared environment, for example an adapted 509 <code>LD_LIBRARY_PATH</code> environment variable, then the VM will not be 510 created and JFW_E_NEED_RESTART error is returned. If a VM is already running 511 then a JFW_E_RUNNING_JVM is returned.</p> 512 513 @param arOptions 514 [in] the array containing additional start arguments or NULL. 515 @param nSize 516 [in] the size of the array <code>arOptions</code>. 517 @param ppVM 518 [out] the <code>JavaVM</code> pointer. 519 @param ppEnv 520 [out] the <code>JNIenv</code> pointer. 521 522 @return 523 JFW_E_NONE function ran successfully.<br/> 524 JFW_E_INVALID_ARG <code>ppVM</code>, <code>ppEnv</code> are NULL or 525 <code>arOptions</code> was NULL but <code>nSize</code> was greater 0.<br/> 526 JFW_E_ERROR an error occurred. <br/> 527 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 528 were not met.</br> 529 JFW_E_NO_PLUGIN the plug-in library responsible for creating the VM 530 could not be found.<br/> 531 JFW_E_JAVA_DISABLED the use of Java is currently disabled. <br/> 532 JFW_E_NO_SELECT there is no JRE selected yet. <br/> 533 JFW_E_RUNNIN_JVM there is already a VM running.<br/> 534 JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no 535 JRE has been selected afterwards. <br/> 536 JFW_E_NEED_RESTART in the current process a different JRE has been selected 537 which needs a prepared environment, which has to be done before the office 538 process. Therefore the new JRE may not be used until the office was restarted.<br/> 539 JFW_E_NEED_RESTART is also returned when Java was disabled at the beginning and 540 then the user enabled it. If then the selected JRE has the requirement 541 JFW_REQUIRE_NEEDRESTART then this error is returned. </br> 542 JFW_E_VM_CREATION_FAILED the creation of the JVM failed. The creation is performed 543 by a plug-in library and not by this API. 544 JFW_E_FAILED_VERSION the "Default Mode" is active. The JRE determined by 545 <code>JAVA_HOME</code>does not meet the version requirements. 546 */ 547 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_startVM(JavaVMOption *arOptions, 548 sal_Int32 nSize, JavaVM **ppVM, 549 JNIEnv **ppEnv); 550 551 /** determines the JRE that is to be used. 552 553 <p>When calling <code>jfw_startVM</code> then a VM is startet from 554 the JRE that is determined by this function.<br/> 555 It is not verified if the JRE represented by the <code>JavaInfo</code> 556 argument meets the requirements as specified by the javavendors.xml file. 557 However, usually one obtains the <code>JavaInfo</code> object from the 558 functions <code>jfw_findAllJREs</code> or <code>jfw_getJavaInfoByPath</code>, 559 which do verify the JREs and pass out only <code>JavaInfo</code> objects 560 which comply with the version requirements.</p> 561 <p> 562 If <code>pInfo</code> is NULL then the meaning is that no JRE will be 563 selected. <code>jfw_startVM</code> will then return 564 <code>JFW_E_NO_SELECT</code>.</p> 565 566 @param pInfo 567 [in] pointer to <code>JavaInfo</code> structure, containing data about a 568 JRE. The caller must still free <code>pInfo</code>. 569 570 @return 571 JFW_E_NONE function ran successfully.<br/> 572 JFW_E_ERROR An error occurred.<br/> 573 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 574 were not met.<br/> 575 JFW_E_DIRECT_MODE the function cannot be used in this mode. 576 */ 577 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_setSelectedJRE(JavaInfo const *pInfo); 578 579 580 /** provides information about the JRE that is to be used. 581 582 <p>If no JRE is currently selected then <code>ppInfo</code> will contain 583 NULL on return.</br> 584 If the value of the element <updated> in the javavendors.xml file was 585 changed since the time when the last Java was selected then this 586 function returns <code>JFW_E_INVALID_SETTINGS</code>. This could happen during 587 a product patch. Then new version requirements may be introduced, so that 588 the currently selected JRE may not meet these requirements anymore. 589 </p> 590 <p>In direct mode the function returns information about a JRE that was 591 set by the bootstrap parameter UNO_JAVA_JFW_JREHOME. 592 </p> 593 @param ppInfo 594 [out] on return it contains a pointer to a <code>JavaInfo</code> object 595 that represents the currently selected JRE. When <code>*ppInfo</code> is not 596 NULL then the function overwrites the pointer. It is not attempted to free 597 the pointer. 598 599 @return 600 JFW_E_NONE function ran successfully.<br/> 601 JFW_E_INVALIDARG <code>ppInfo</code> is a NULL.<br/> 602 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 603 were not met.<br/> 604 JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no 605 JRE has been selected afterwards. <br/> 606 */ 607 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_getSelectedJRE(JavaInfo **ppInfo); 608 609 610 /** determines if Java can be used. 611 612 <p>If <code>bEnabled</code> is <code>sal_False</code> then a call 613 to jfw_startVM will result in an error with the errorcode 614 <code>JFW_E_JAVA_DISABLED</code></p> 615 616 @param bEnabled 617 [in] use of Java enabled/disabled. 618 619 @return 620 JFW_E_NONE function ran successfully.<br/> 621 JFW_E_ERROR An error occurred.<br/> 622 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 623 were not met.<br/> 624 JFW_E_DIRECT_MODE the function cannot be used in this mode. 625 */ 626 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_setEnabled(sal_Bool bEnabled); 627 628 /** provides the information if Java can be used. 629 630 <p>That is if the user enabled or disabled the use of Java. 631 </p> 632 633 @return 634 JFW_E_NONE function ran successfully.<br/> 635 JFW_E_INVALIDARG pbEnabled is NULL<br/> 636 JFW_E_ERROR An error occurred.<br/> 637 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 638 were not met.<br/> 639 JFW_E_DIRECT_MODE the function cannot be used in this mode. 640 */ 641 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_getEnabled(sal_Bool *pbEnabled); 642 643 /** determines parameters which are passed to VM during its creation. 644 645 <p>The strings must be exactly as they are passed on the command line. 646 For example, one could pass<br/> 647 -Xdebug <br/> 648 -Xrunjdw:transport=dt_socket,server=y,address=8000<br/> 649 in order to enable debugging support. 650 </p> 651 652 @param arParameters 653 [in] contains the arguments. It can be NULL if nSize is 0. 654 @param nSize 655 [i] the size of <code>arArgs</code> 656 657 @return 658 JFW_E_NONE function ran successfully.<br/> 659 JFW_E_INVALIDARG arArgs is NULL and nSize is not 0 660 JFW_E_ERROR An error occurred.<br/> 661 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 662 were not met.<br/> 663 JFW_E_DIRECT_MODE the function cannot be used in this mode. 664 */ 665 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_setVMParameters( 666 rtl_uString ** arArgs, sal_Int32 nSize); 667 668 /** obtains the currently used start parameters. 669 670 <p>The caller needs to free the returned array with 671 <code>rtl_freeMemory</code>. The contained strings must be released with 672 <code>rtl_uString_release</code>. 673 </p> 674 675 @param parParameters 676 [out] on returns contains a pointer to the array of the start arguments. 677 If *parParameters is not NULL then the value is overwritten. 678 @param pSize 679 [out] on return contains the size of array returned in 680 <code>parParameters</code> 681 682 @return 683 JFW_E_NONE function ran successfully.<br/> 684 JFW_E_INVALIDARG parParameters or pSize are NULL<br/> 685 JFW_E_ERROR An error occurred.<br/> 686 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 687 were not met.<br/> 688 JFW_E_DIRECT_MODE the function cannot be used in this mode. 689 */ 690 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_getVMParameters( 691 rtl_uString *** parParameters, 692 sal_Int32 * pSize); 693 694 /** sets the user class path. 695 696 <p>When the VM is started then it is passed the class path. The 697 class path also contains the user class path set by this function. 698 The paths contained in <code>pCP</code> must be separated with a 699 system dependent path separator.</p> 700 701 @param pCP 702 [in] the user class path. 703 704 @return 705 JFW_E_NONE function ran successfully.<br/> 706 JFW_E_INVALIDARG pCP is NULL.<br/> 707 JFW_E_ERROR An error occurred.<br/> 708 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 709 were not met.<br/> 710 JFW_E_DIRECT_MODE the function cannot be used in this mode. 711 */ 712 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_setUserClassPath(rtl_uString * pCP); 713 /** provides the value of the current user class path. 714 715 <p>The function returns an empty string if no user class path is set. 716 </p> 717 718 @param ppCP 719 [out] contains the user class path on return. If <code>*ppCP</code> was 720 not NULL then the value is overwritten. No attempt at freeing that string 721 is made. 722 723 @return 724 JFW_E_NONE function ran successfully.<br/> 725 JFW_E_INVALIDARG ppCP is NULL.<br/> 726 JFW_E_ERROR An error occurred.<br/> 727 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 728 were not met.<br/> 729 JFW_E_DIRECT_MODE the function cannot be used in this mode. 730 */ 731 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_getUserClassPath(rtl_uString ** ppCP); 732 733 /** saves the location of a JRE. 734 735 <p>When <code>jfw_findAllJREs</code> is called then the paths added by this 736 function are evaluated. If the location still represents a 737 JRE then a <code>JavaInfo</code> object is created which is returned along 738 with all other <code>JavaInfo</code> objects by 739 <code>jfw_findAllJREs</code>. If the location 740 cannot be recognized then the location string is ignored. </p> 741 <p> 742 A validation if <code>sLocation</code> points to a JRE is not 743 performed. To do that one has to use <code>jfw_getJavaInfoByPath</code>. 744 </p> 745 <p> 746 Adding a path that is already stored causes no error.</p> 747 748 @param sLocation 749 [in] file URL to a directory which contains a JRE. 750 751 @return 752 JFW_E_NONE function ran successfully.<br/> 753 JFW_E_INVALIDARG sLocation is NULL.<br/> 754 JFW_E_ERROR An error occurred.<br/> 755 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 756 were not met.<br/> 757 JFW_E_DIRECT_MODE the function cannot be used in this mode. 758 @see jfw_setJRELocations 759 */ 760 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_addJRELocation(rtl_uString * sLocation); 761 762 /** saves the locations of a number of JREs. 763 764 <p> 765 The function does not verify if the paths points to JRE. However, 766 it makes sure that every path is unique. That is, if the array 767 contains strings which are the same then only one is stored.</p> 768 <p> 769 If <code>arLocations</code> is NULL or it has the length null (nSize = 0) 770 then all previously stored paths are deleted. Otherwise, 771 the old values are overwritten.</p> 772 773 @param arLocations 774 [in] array of paths to locations of JREs. 775 776 @param nSize 777 [in] the size of the array <code>arLocations</code> 778 779 @return 780 JFW_E_NONE function ran successfully.<br/> 781 JFW_E_INVALIDARG arLocation is NULL and nSize is not null.<br/> 782 JFW_E_ERROR An error occurred.<br/> 783 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 784 were not met.<br/> 785 JFW_E_DIRECT_MODE the function cannot be used in this mode. 786 @see jfw_addJRELocations 787 */ 788 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_setJRELocations( 789 rtl_uString ** arLocations, sal_Int32 nSize); 790 /** obtains an array containing paths to JRE installations. 791 792 <p> 793 It is not guaranteed that the returned paths represent 794 a valid JRE. One can use <code>jfw_getJavaInfoByPath</code> to check this. 795 </p> 796 797 @param parLocations 798 [out] on return it contains the array of paths. 799 @param pSize 800 [out] on return it contains the size of the array <code>parLocations</code>. 801 802 @return 803 JFW_E_NONE function ran successfully.<br/> 804 JFW_E_INVALIDARG parLocation is NULL or pSize is NULL.<br/> 805 JFW_E_ERROR An error occurred.<br/> 806 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 807 were not met.<br/> 808 JFW_E_DIRECT_MODE the function cannot be used in this mode. 809 */ 810 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_getJRELocations( 811 rtl_uString *** parLocations, sal_Int32 * pSize); 812 813 814 /** checks if the installation of the jre still exists. 815 816 This function checks if the JRE described by pInfo still 817 exists. The check must be very quick because it is called by javaldx 818 (Linux, Solaris) at start up. 819 820 @param pInfo 821 [in] the JavaInfo object with information about the JRE. 822 @param pp_exist 823 [out] the parameter is set to either sal_True or sal_False. The value is 824 only valid if the function returns JFW_E_NONE. 825 826 @return 827 JFW_E_NONE the function ran successfully.</br> 828 JFW_E_ERROR an error occurred during execution.</br> 829 JFW_E_INVALID_ARG pInfo contains invalid data</br> 830 JFW_E_NO_PLUGIN a plug-in library could not be found.<br/> 831 */ 832 JVMFWK_DLLPUBLIC javaFrameworkError SAL_CALL jfw_existJRE(const JavaInfo *pInfo, sal_Bool *exist); 833 834 835 /** locks this API so that it cannot be used by other threads. 836 837 <p>If a different thread called this function before then the 838 current call is blocked until the other thread has called 839 <code>jfw_unlock()</code>. The function should be called if one 840 needs an exact snapshot of the current settings. Then the settings 841 are retrieved one by one without risk that the settings may be changed 842 by a different thread. Similiary if one needs to make settings which 843 should become effective at the same time then <code>jfw_lock</code> 844 should be called. That is, <code>jfw_startVM</code> which uses the 845 settings cannot be called before all settings have be made.</p> 846 <p> 847 The only functions which are not effected by <code>jfw_lock</code> are 848 <code>jfw_freeJavaInfo</code> and <code>jfw_areEqualJavaInfo</code>. 849 */ 850 JVMFWK_DLLPUBLIC void SAL_CALL jfw_lock(); 851 852 /** unlocks this API. 853 854 <p>This function is called after <code>jfw_lock</code>. It allows other 855 threads to use this API concurrently.</p> 856 */ 857 JVMFWK_DLLPUBLIC void SAL_CALL jfw_unlock(); 858 859 860 #ifdef __cplusplus 861 } 862 #endif 863 864 865 #endif 866