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