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