1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* 3 * This file is part of the LibreOffice project. 4 * 5 * This Source Code Form is subject to the terms of the Mozilla Public 6 * License, v. 2.0. If a copy of the MPL was not distributed with this 7 * file, You can obtain one at http://mozilla.org/MPL/2.0/. 8 * 9 * This file incorporates work covered by the following license notice: 10 * 11 * Licensed to the Apache Software Foundation (ASF) under one or more 12 * contributor license agreements. See the NOTICE file distributed 13 * with this work for additional information regarding copyright 14 * ownership. The ASF licenses this file to you under the Apache 15 * License, Version 2.0 (the "License"); you may not use this file 16 * except in compliance with the License. You may obtain a copy of 17 * the License at http://www.apache.org/licenses/LICENSE-2.0 . 18 */ 19 20 /** @HTML */ 21 22 #ifndef INCLUDED_JVMFWK_FRAMEWORK_HXX 23 #define INCLUDED_JVMFWK_FRAMEWORK_HXX 24 25 #include <sal/config.h> 26 27 #include <memory> 28 #include <vector> 29 30 #include <jvmfwk/jvmfwkdllapi.hxx> 31 #include <rtl/byteseq.hxx> 32 #include <rtl/ustring.hxx> 33 #include <jni.h> 34 35 /** @file 36 <p>This library can operate in two modes, application mode and direct mode.</p> 37 38 39 <h2>Application Mode</h2> 40 In application mode the Java related settings are stored in files. 41 There are currently three files which need to be accessed. They are determined 42 by bootstrap parameters:</p> 43 <dl> 44 <dt>UNO_JAVA_JFW_VENDOR_SETTINGS</dt> 45 <dd>contains vendor and version information about JREs as well as the 46 location of plugin-libraries which are responsible for providing information 47 about these JREs as well as starting the VMs.</dd> 48 <dt>UNO_JAVA_JFW_USER_DATA</dt> 49 <dd>The file contains settings for a particular user. One can use the macro 50 $SYSUSERCONFIG in the URL which expands to a directory where the user's data are 51 kept. On UNIX this would be the home directory and on Windows some sub-directory 52 of the "Documents and Settings" folder.The content of this file is an 53 implementation detail and may change in the future.</dd> 54 <dt>UNO_JAVA_JFW_SHARED_DATA</dt> 55 <dd>The file contains settings valid for all users. If a user changes a setting 56 then it takes precedence over the setting from UNO_JAVA_JFW_SHARED_DATA. 57 The content of this file is an implementation detail and may change in the future.</dd> 58 </dl> 59 60 <p>The values for these parameters must be file URLs and include the file name, for 61 example:<br> 62 file:///d:/MyApp/javavendors.xml<br> 63 All files are XML files and must have the extension .xml.</p> 64 <p> 65 Modifying the shared settings is currently not supported by the framework. To provide 66 Java settings for all users one can run OOo and change the settings in the 67 options dialog. These settings are made persistent in the UNO_JAVA_JFW_USER_DATA. 68 The file can then be copied into the base installation. 69 Other users will use automatically these data but can override the settings in 70 the options dialog. This mechanism may change in the future. 71 </p> 72 <p>If shared Java settings are not supported by an application then it is not 73 necessary to specify the bootstrap parameter <code>UNO_JAVA_JFW_SHARED_DATA</code>. 74 </p> 75 76 <p>Setting the class path used by a Java VM should not be necessary. The locations 77 of Jar files should be known by a class loader. If a jar file depends on another 78 jar file then it can be referenced in the manifest file of the first jar. However, 79 a user may add jars to the class path by using this API. If it becomes necessary 80 to add files to the class path which is to be used by all users then one can use 81 the bootstrap parameter UNO_JAVA_JFW_CLASSPATH_URLS. The value contains of file URLs 82 which must be separated by spaces.</p> 83 84 85 <h2>Direct Mode</h2> 86 87 <p>The direct mode is intended for a scenario where no configuration files 88 are available and a Java VM shall be run. That is, 89 the files containing the user and shared settings are not specified by the 90 bootstrap parameters UNO_JAVA_JFW_SHARED_DATA and UNO_JAVA_JFW_USER_DATA. 91 For example, tools, such as regcomp, may use this framework in a build 92 environment. Then one would want to use settings which have been specified 93 by the build environment. The framework would automatically use the 94 current settings when they change in the environment. 95 </p> 96 97 <p> Here are examples how regcomp could be invoked using bootstrap parameters: 98 </p> 99 <p> 100 regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 101 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" 102 -register... 103 </p> 104 <p>If UNO_JAVA_JFW_VENDOR_SETTINGS is not set then a plugin library must be specified. For example:</p> 105 <p> 106 regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 107 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" 108 -register... 109 </p> 110 <p>Additional parameters for the Java VM can be provided. For every parameter 111 a separate bootstrap parameter must be specified. The names are 112 <code>UNO_JAVA_JFW_PARAMETER_X</code>, where X is 1,2, .. n. For example:</p> 113 <p> 114 regcomp -env:UNO_JAVA_JFW_PARAMETER_1=-Xdebug 115 -env:UNO_JAVA_JFW_PARAMETER_2=-Xrunjdwp:transport=dt_socket,server=y,address=8100 116 -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 117 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" 118 -register...</p> 119 <p> 120 Here is a complete list of the bootstrap parameter for the direct mode: 121 </p> 122 <dl> 123 <dt>UNO_JAVA_JFW_JREHOME</dt> 124 <dd>Specifies a file URL to a JRE installation.It must ALWAYS be specified 125 in direct mode</dd> 126 <dt>UNO_JAVA_JFW_ENV_JREHOME</dt> 127 <dd>Setting this parameter, for example to "1" or "true", 128 causes the framework to use the environment variable JAVA_HOME. It is expected 129 that JAVA_HOME contains a system path rather than a file URL. This parameter 130 and UNO_JAVA_JFW_JREHOME are mutually exclusive</dd> 131 <dt>UNO_JAVA_JFW_CLASSPATH</dt> 132 <dd>Contains the class path which is to be used by the VM. Special character, 133 such as '\','{','}','$' must be preceded with '\'. See documentation about the 134 bootstrap parameter.</dd> 135 <dt>UNO_JAVA_JFW_ENV_CLASSPATH</dt> 136 <dd>Setting this parameter,for example to "1" or "true", 137 causes the framework to use the 138 environment variable CLASSPATH. If this variable and UNO_JAVA_JFW_CLASSPATH are 139 set then the class path is composed from UNO_JAVA_JFW_CLASSPATH and the environment 140 variable CLASSPATH.</dd> 141 <dt>UNO_JAVA_JFW_PARAMETER_X</dt> 142 <dd>Specifies a parameter for the Java VM. The X is replaced by 143 non-negative natural numbers starting with 1.</dd> 144 </dl> 145 146 <p>A note about bootstrap parameters. The implementation of the bootstrap 147 parameter mechanism interprets the characters '\', '$', '{', '}' as 148 escape characters. That's why the Windows path contain double back-slashes. 149 One should also take into account that a console may have also special 150 escape characters.</p> 151 152 <h2>What mode is used</h2> 153 <p> 154 The default mode is application mode. If at least one bootstrap parameter 155 for the direct mode is provided then direct mode is used. </p> 156 157 <p> 158 All settings made by this API are done for the current user if not 159 mentioned differently.</p> 160 161 <h2>Other bootstrap variables</h2> 162 <dl> 163 <dt>JFW_PLUGIN_DO_NOT_CHECK_ACCESSIBILITY</dt> 164 <dd>This is an unofficial variable which was introduced to workaround external issues. 165 It may be removed in the future. By setting it to 1, the framework will not try to 166 find out if the system is configured to use accessibility tools or if a JRE has an 167 accessible bridge installed</dd> 168 <dt>JFW_PLUGIN_FORCE_ACCESSIBILITY</dt> 169 <dd>This is an unofficial variable which was introduced to workaround external issues. 170 It may be removed in the future. By setting it to 1, the framework will override a 171 platform's desire not to probe each java backend to determine if it has an accessibility 172 bridge installed. If the JFW_PLUGIN_DO_NOT_CHECK_ACCESSIBILITY is set this variable has 173 no effect, and is Unix specific.</dd> 174 </dl> 175 */ 176 177 /** indicates that a JRE has an accessibility bridge installed. 178 <p> 179 The flag is used with JavaInfo::nFeatures.</p> 180 */ 181 #define JFW_FEATURE_ACCESSBRIDGE 0x1l 182 /** indicates that there must be an environment set up before the Java process 183 runs. 184 <p>Therefore, when a Java is selected in OO then the office must be 185 restarted, so that the changes can take effect.</p> 186 */ 187 #define JFW_REQUIRE_NEEDRESTART 0x1l 188 189 /** error codes which are returned by functions of this API. 190 */ 191 enum javaFrameworkError 192 { 193 JFW_E_NONE, 194 JFW_E_ERROR, 195 JFW_E_NO_SELECT, 196 JFW_E_INVALID_SETTINGS, 197 JFW_E_NEED_RESTART, 198 JFW_E_RUNNING_JVM, 199 JFW_E_JAVA_DISABLED, 200 JFW_E_NOT_RECOGNIZED, 201 JFW_E_FAILED_VERSION, 202 JFW_E_NO_JAVA_FOUND, 203 JFW_E_VM_CREATION_FAILED, 204 JFW_E_CONFIGURATION, 205 JFW_E_DIRECT_MODE 206 }; 207 208 /** an instance of this struct represents an installation of a Java 209 Runtime Environment (JRE). 210 211 <p> 212 Instances of this struct are created by the plug-in libraries which are used by 213 this framework (jvmfwk/vendorplugin.h).</p> 214 */ 215 struct JavaInfo 216 { 217 /** contains the vendor. 218 219 <p>string must be the same as the one obtained from the 220 Java system property <code>java.vendor</code>. 221 </p> 222 */ 223 OUString sVendor; 224 /** contains the file URL to the installation directory. 225 */ 226 OUString sLocation; 227 /** contains the version of this Java distribution. 228 229 <p>The version string must adhere to the rules 230 about how a version string has to be formed. These rules may 231 be vendor-dependent. Essentially the strings must syntactically 232 equal the Java system property <code>java.version</code>. 233 </p> 234 */ 235 OUString sVersion; 236 /** indicates supported special features. 237 238 <p>For example, <code>JFW_FEATURE_ACCESSBRIDGE</code> indicates that 239 assistive technology tools are supported.</p> 240 */ 241 sal_uInt64 nFeatures; 242 /** indicates requirements for running the java runtime. 243 244 <p>For example, it may be necessary to prepare the environment before 245 the runtime is created. That could mean, setting the 246 <code>LD_LIBRARY_PATH</code> 247 when <code>nRequirements</code> contains the flag 248 <code>JFW_REQUIRE_NEEDRESTART</code></p> 249 */ 250 sal_uInt64 nRequirements; 251 /** contains data needed for the creation of the java runtime. 252 253 <p>There is no rule about the format and content of the sequence's 254 values. The plug-in libraries can put all data, necessary for 255 starting the java runtime into this sequence. </p> 256 */ 257 rtl::ByteSequence arVendorData; 258 }; 259 260 /** compares two <code>JavaInfo</code> objects for equality. 261 262 <p>Two <code>JavaInfo</code> objects are said to be equal if the contained 263 members of the first <code>JavaInfo</code> are equal to their counterparts 264 in the second <code>JavaInfo</code> object. The equality of the 265 <code>OUString</code> members is determined 266 by <code>operator ==</code>. 267 Similarly the equality of the <code>rtl::ByteSequence</code> is 268 also determined by a comparison 269 function (see <code>rtl::ByteSequence::operator ==</code>). </p> 270 <p> 271 Both argument pointers must be valid.</p> 272 @param pInfoA 273 the first argument. 274 @param pInfoB 275 the second argument which is compared with the first. 276 @return 277 true - both object represent the same JRE.</br> 278 false - the objects represent different JREs 279 */ 280 JVMFWK_DLLPUBLIC bool jfw_areEqualJavaInfo( 281 JavaInfo const * pInfoA,JavaInfo const * pInfoB); 282 283 /** determines if a Java Virtual Machine is already running. 284 285 <p>As long as the office and the JREs only support one 286 Virtual Machine per process the Java settings, particularly the 287 selected Java, are not effective immediately after changing when 288 a VM has already been running. That is, if a JRE A was used to start 289 a VM and then a JRE B is selected, then JRE B will only be used 290 after a restart of the office.</p> 291 <p> 292 By determining if a VM is running, the user can be presented a message, 293 that the changed setting may not be effective immediately.</p> 294 295 @return 296 true iff a VM is running. 297 */ 298 JVMFWK_DLLPUBLIC bool jfw_isVMRunning(); 299 300 /** detects a suitable JRE and configures the framework to use it. 301 302 <p>Which JREs can be used is determined by the file javavendors.xml, 303 which contains version requirements.</p> 304 <p> 305 JREs can be provided by different vendors. 306 The function obtains information about JRE installations and checks if 307 there is one among them that supports 308 a set of features (currently only accessibility is possible). If none was 309 found then it also uses a list of paths, which have been registered 310 by <code>jfw_addJRELocation</code> 311 to find JREs. Found JREs are examined in the same way.</p> 312 <p> 313 A JRE installation is only selected if it meets the version requirements. 314 Information about the selected JRE are made persistent so that 315 subsequent calls to <code>jfw_getSelectedJRE</code> returns this 316 information.</p> 317 <p> 318 While determining a proper JRE this function takes into account if a 319 user requires support for assistive technology tools. If user 320 need that support they have to set up their system accordingly.</p> 321 <p> 322 If the JAVA_HOME environment variable is set, this function prefers 323 the JRE which the variable refers to over other JREs. 324 If JAVA_HOME is not set or does not refer to a suitable JRE, 325 the PATH environment variable is inspected and the respective JREs 326 are checked for their suitability next.</p> 327 <p> 328 When support for assistive technology is required, then the 329 <code>JavaInfo</code> objects, 330 which are provided by the <code>getJavaInfo</code> functions, are 331 examined for a suitable JRE. 332 That is, the <code>JavaInfo</code> object that refers to the JRE referred to 333 by JAVA_HOME is examined. If it does not have the flag 334 <code>JFW_FEATURE_ACCESSBRIDGE</code> in the member <code>nFeatures</code> 335 then the <JavaInfo></code> objects that are related to the PATH variable 336 are examined. 337 If no suitable <code>JavaInfo</code> object is found, all <code>JavaInfo</code> 338 objects - representing Java installations on the system -, are examined. 339 As long as no <code>JavaInfo</code> object has the flag 340 <code>JFW_FEATURE_ACCESSBRIDGE</code> in the member <code>nFeatures</code>, more 341 <code>JavaInfo</code> objects are examined. 342 This goes on until a <code>JavaInfo</code> object was found which 343 represents a suitable JRE. Or no such <code>JavaInfo</code> object was found. 344 In that case the first <code>JavaInfo</code> object that was detected 345 by the algorithm described above is used to determine the JRE which is to be used.</p> 346 <p> 347 If there is no need for the support of assistive technology tools then 348 the first <code>JavaInfo</code> object that is detected by the algorithm 349 as described above is used.</p> 350 351 @param pInfo 352 [out] a <code>JavaInfo</code> pointer, representing the selected JRE. 353 The <code>JavaInfo</code> is for informational purposes only. It is not 354 necessary to call <code>jfw_setSelectedJRE</code> afterwards.<br/> 355 <code>pInfo</code>can be NULL. 356 357 @return 358 JFW_E_NONE function ran successfully.<br/> 359 JFW_E_ERROR an error occurred. <br/> 360 JFW_E_NO_JAVA_FOUND no JRE was found that meets the requirements.</br> 361 JFW_E_DIRECT_MODE the function cannot be used in this mode. </br> 362 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 363 were not met. 364 */ 365 JVMFWK_DLLPUBLIC javaFrameworkError jfw_findAndSelectJRE(std::unique_ptr<JavaInfo> *pInfo); 366 367 /** provides information about all available JRE installations. 368 369 <p>The function determines dynamically what JREs are available. It uses 370 the plug-in libraries to provide lists of available <code>JavaInfo</code> 371 objects where each object represents a JRE (see vendorplugin.h, 372 getAllJavaInfos). It also uses a list of paths, which have been registered 373 by <code>jfw_addJRELocation</code>. 374 It is checked if the path still contains a valid JRE and if so the respective 375 <code>JavaInfo</code> object will be appended to the array unless there is 376 already an equal object.</p> 377 378 @param parInfo 379 [out] on returns it contains a vector of <code>JavaInfo</code> pointers. 380 381 @return 382 JFW_E_NONE function ran successfully.<br/> 383 JFW_E_ERROR an error occurred. <br/> 384 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 385 were not met. 386 */ 387 JVMFWK_DLLPUBLIC javaFrameworkError jfw_findAllJREs( 388 std::vector<std::unique_ptr<JavaInfo>> *parInfo); 389 390 /** determines if a path points to a Java installation. 391 392 <p>If the path belongs to a JRE installation then it returns the 393 respective <code>JavaInfo</code> object. The function uses the 394 <code>getJavaInfoByPath</code> function of the plug-ins to obtain the 395 <code>JavaInfo</code> object. Only if the JRE found at the specified location 396 meets the version requirements as specified in the javavendors.xml file a 397 <code>JavaInfo</code> object is returned.<br/> 398 <p> 399 The functions only checks if a JRE exists but does not modify any settings. 400 To make the found JRE the "selected JRE" one has 401 to call <code>jfw_setSelectedJRE</code>.</p> 402 403 @param pPath 404 [in] a file URL to a directory. 405 @param ppInfo 406 [out] the <code>JavaInfo</code> object which represents a JRE found at the 407 location specified by <code>pPath</code> 408 409 @return 410 JFW_E_NONE function ran successfully.<br/> 411 JFW_E_ERROR an error occurred. <br/> 412 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 413 were not met.</br> 414 JFW_E_NOT_RECOGNIZED neither plug-in library could detect a JRE. <br/> 415 JFW_E_FAILED_VERSION a JRE was detected but if failed the version 416 requirements as determined by the javavendors.xml 417 */ 418 JVMFWK_DLLPUBLIC javaFrameworkError jfw_getJavaInfoByPath( 419 OUString const & pPath, std::unique_ptr<JavaInfo> *ppInfo); 420 421 422 /** starts a Java Virtual Machine (JVM). 423 424 <p>The function uses the current settings to start a JVM. The actual 425 start-up code, however, is provided by the plug-in libraries. The setting 426 of the "selected Java" contains the information as to what vendor 427 the respective JRE comes from. In the javavendors.xml there is a mapping of 428 vendor names to the respective plug-in libraries.</p> 429 <p> 430 The function ultimately calls <code>startJavaVirtualMachine</code> from 431 the plug-in library.</p> 432 <p> 433 The <code>arOptions</code> 434 argument contains start arguments which are passed in JavaVMOption structures 435 to the VM during its creation. These 436 could be things, such as language settings, proxy settings or any other 437 properties which shall be obtainable by 438 <code>java.lang.System.getProperties</code>. One can also pass options which 439 have a certain meaning to the runtime behaviour such as -ea or -X... However, 440 one must be sure that these options can be interpreted by the VM.<br/> 441 The class path cannot be set this way. The class path is internally composed by 442 the paths to archives in a certain directory, which is preconfigured in 443 the internal data store and the respective user setting (see 444 <code>jfw_setUserClassPath</code>.</p> 445 <p> 446 If a JRE was selected at runtime which was different from the previous 447 setting and that JRE needs a prepared environment, for example an adapted 448 <code>LD_LIBRARY_PATH</code> environment variable, then the VM will not be 449 created and JFW_E_NEED_RESTART error is returned. If a VM is already running 450 then a JFW_E_RUNNING_JVM is returned.</p> 451 452 @param pInfo 453 [in] optional pointer to a specific JRE; must be caller-freed if not NULL 454 @param arOptions 455 [in] the vector containing additional start arguments. 456 @param ppVM 457 [out] the <code>JavaVM</code> pointer. 458 @param ppEnv 459 [out] the <code>JNIenv</code> pointer. 460 461 @return 462 JFW_E_NONE function ran successfully.<br/> 463 JFW_E_ERROR an error occurred. <br/> 464 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 465 were not met.</br> 466 JFW_E_JAVA_DISABLED the use of Java is currently disabled. <br/> 467 JFW_E_NO_SELECT there is no JRE selected yet. <br/> 468 JFW_E_RUNNIN_JVM there is already a VM running.<br/> 469 JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no 470 JRE has been selected afterwards. <br/> 471 JFW_E_NEED_RESTART in the current process a different JRE has been selected 472 which needs a prepared environment, which has to be done before the office 473 process. Therefore the new JRE may not be used until the office was restarted.<br/> 474 JFW_E_NEED_RESTART is also returned when Java was disabled at the beginning and 475 then the user enabled it. If then the selected JRE has the requirement 476 JFW_REQUIRE_NEEDRESTART then this error is returned. </br> 477 JFW_E_VM_CREATION_FAILED the creation of the JVM failed. The creation is performed 478 by a plug-in library and not by this API. 479 JFW_E_FAILED_VERSION the "Default Mode" is active. The JRE determined by 480 <code>JAVA_HOME</code>does not meet the version requirements. 481 */ 482 JVMFWK_DLLPUBLIC javaFrameworkError jfw_startVM( 483 JavaInfo const * pInfo, std::vector<OUString> const & arOptions, 484 JavaVM ** ppVM, JNIEnv ** ppEnv); 485 486 /** determines the JRE that is to be used. 487 488 <p>When calling <code>jfw_startVM</code> then a VM is started from 489 the JRE that is determined by this function.<br/> 490 It is not verified if the JRE represented by the <code>JavaInfo</code> 491 argument meets the requirements as specified by the javavendors.xml file. 492 However, usually one obtains the <code>JavaInfo</code> object from the 493 functions <code>jfw_findAllJREs</code> or <code>jfw_getJavaInfoByPath</code>, 494 which do verify the JREs and pass out only <code>JavaInfo</code> objects 495 which comply with the version requirements.</p> 496 <p> 497 If <code>pInfo</code> is NULL then the meaning is that no JRE will be 498 selected. <code>jfw_startVM</code> will then return 499 <code>JFW_E_NO_SELECT</code>.</p> 500 501 @param pInfo 502 [in] pointer to <code>JavaInfo</code> structure, containing data about a 503 JRE. The caller must still free <code>pInfo</code>. 504 505 @return 506 JFW_E_NONE function ran successfully.<br/> 507 JFW_E_ERROR An error occurred.<br/> 508 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 509 were not met.<br/> 510 JFW_E_DIRECT_MODE the function cannot be used in this mode. 511 */ 512 JVMFWK_DLLPUBLIC javaFrameworkError jfw_setSelectedJRE(JavaInfo const *pInfo); 513 514 515 /** provides information about the JRE that is to be used. 516 517 <p>If no JRE is currently selected then <code>ppInfo</code> will contain 518 NULL on return.</br> 519 If the value of the element <updated> in the javavendors.xml file was 520 changed since the time when the last Java was selected then this 521 function returns <code>JFW_E_INVALID_SETTINGS</code>. This could happen during 522 a product patch. Then new version requirements may be introduced, so that 523 the currently selected JRE may not meet these requirements anymore. 524 </p> 525 <p>In direct mode the function returns information about a JRE that was 526 set by the bootstrap parameter UNO_JAVA_JFW_JREHOME. 527 </p> 528 @param ppInfo 529 [out] on return it contains a pointer to a <code>JavaInfo</code> object 530 that represents the currently selected JRE. When <code>*ppInfo</code> is not 531 NULL then the function sets the pointer. 532 533 @return 534 JFW_E_NONE function ran successfully.<br/> 535 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 536 were not met.<br/> 537 JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no 538 JRE has been selected afterwards. <br/> 539 */ 540 JVMFWK_DLLPUBLIC javaFrameworkError jfw_getSelectedJRE(std::unique_ptr<JavaInfo> *ppInfo); 541 542 543 /** determines if Java can be used. 544 545 <p>If <code>bEnabled</code> is <code>false</code> then a call 546 to jfw_startVM will result in an error with the errorcode 547 <code>JFW_E_JAVA_DISABLED</code></p> 548 549 @param bEnabled 550 [in] use of Java enabled/disabled. 551 552 @return 553 JFW_E_NONE function ran successfully.<br/> 554 JFW_E_ERROR An error occurred.<br/> 555 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 556 were not met.<br/> 557 JFW_E_DIRECT_MODE the function cannot be used in this mode. 558 */ 559 JVMFWK_DLLPUBLIC javaFrameworkError jfw_setEnabled(bool bEnabled); 560 561 /** provides the information if Java can be used. 562 563 <p>That is if the user enabled or disabled the use of Java. 564 </p> 565 566 @return 567 JFW_E_NONE function ran successfully.<br/> 568 JFW_E_ERROR An error occurred.<br/> 569 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 570 were not met.<br/> 571 JFW_E_DIRECT_MODE the function cannot be used in this mode. 572 */ 573 JVMFWK_DLLPUBLIC javaFrameworkError jfw_getEnabled(bool *pbEnabled); 574 575 /** determines parameters which are passed to VM during its creation. 576 577 <p>The strings must be exactly as they are passed on the command line. 578 For example, one could pass<br/> 579 -Xdebug <br/> 580 -Xrunjdw:transport=dt_socket,server=y,address=8000<br/> 581 in order to enable debugging support. 582 </p> 583 584 @param arParameters 585 [in] contains the arguments. 586 587 @return 588 JFW_E_NONE function ran successfully.<br/> 589 JFW_E_ERROR An error occurred.<br/> 590 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 591 were not met.<br/> 592 JFW_E_DIRECT_MODE the function cannot be used in this mode. 593 */ 594 JVMFWK_DLLPUBLIC javaFrameworkError jfw_setVMParameters( 595 std::vector<OUString> const & arArgs); 596 597 /** obtains the currently used start parameters. 598 599 @param parParameters 600 [out] on returns contains a pointer to the array of the start arguments. 601 602 @return 603 JFW_E_NONE function ran successfully.<br/> 604 JFW_E_ERROR An error occurred.<br/> 605 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 606 were not met.<br/> 607 JFW_E_DIRECT_MODE the function cannot be used in this mode. 608 */ 609 JVMFWK_DLLPUBLIC javaFrameworkError jfw_getVMParameters( 610 std::vector<OUString> * parParameters); 611 612 /** sets the user class path. 613 614 <p>When the VM is started then it is passed the class path. The 615 class path also contains the user class path set by this function. 616 The paths contained in <code>pCP</code> must be separated with a 617 system dependent path separator.</p> 618 619 @param pCP 620 [in] the user class path. 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 JVMFWK_DLLPUBLIC javaFrameworkError jfw_setUserClassPath(OUString const & pCP); 630 /** provides the value of the current user class path. 631 632 <p>The function returns an empty string if no user class path is set. 633 </p> 634 635 @param ppCP 636 [out] contains the user class path on return. 637 638 @return 639 JFW_E_NONE function ran successfully.<br/> 640 JFW_E_ERROR An error occurred.<br/> 641 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 642 were not met.<br/> 643 JFW_E_DIRECT_MODE the function cannot be used in this mode. 644 */ 645 JVMFWK_DLLPUBLIC javaFrameworkError jfw_getUserClassPath(OUString * ppCP); 646 647 /** saves the location of a JRE. 648 649 <p>When <code>jfw_findAllJREs</code> is called then the paths added by this 650 function are evaluated. If the location still represents a 651 JRE then a <code>JavaInfo</code> object is created which is returned along 652 with all other <code>JavaInfo</code> objects by 653 <code>jfw_findAllJREs</code>. If the location 654 cannot be recognized then the location string is ignored. </p> 655 <p> 656 A validation if <code>sLocation</code> points to a JRE is not 657 performed. To do that one has to use <code>jfw_getJavaInfoByPath</code>. 658 </p> 659 <p> 660 Adding a path that is already stored causes no error.</p> 661 662 @param sLocation 663 [in] file URL to a directory which contains a JRE. 664 665 @return 666 JFW_E_NONE function ran successfully.<br/> 667 JFW_E_ERROR An error occurred.<br/> 668 JFW_E_CONFIGURATION mode was not properly set or their prerequisites 669 were not met.<br/> 670 JFW_E_DIRECT_MODE the function cannot be used in this mode. 671 */ 672 JVMFWK_DLLPUBLIC javaFrameworkError jfw_addJRELocation( 673 OUString const & sLocation); 674 675 /** checks if the installation of the jre still exists. 676 677 This function checks if the JRE described by pInfo still 678 exists. The check must be very quick because it is called by javaldx 679 (Linux, Solaris) at start up. 680 681 @param pInfo 682 [in] the JavaInfo object with information about the JRE. 683 @param pp_exist 684 [out] the parameter is set to either true or false. The value is 685 only valid if the function returns JFW_E_NONE. 686 687 @return 688 JFW_E_NONE the function ran successfully.</br> 689 JFW_E_ERROR an error occurred during execution.</br> 690 */ 691 JVMFWK_DLLPUBLIC javaFrameworkError jfw_existJRE(const JavaInfo *pInfo, bool *exist); 692 693 694 /** locks this API so that it cannot be used by other threads. 695 696 <p>If a different thread called this function before then the 697 current call is blocked until the other thread has called 698 <code>jfw_unlock()</code>. The function should be called if one 699 needs an exact snapshot of the current settings. Then the settings 700 are retrieved one by one without risk that the settings may be changed 701 by a different thread. Similarity if one needs to make settings which 702 should become effective at the same time then <code>jfw_lock</code> 703 should be called. That is, <code>jfw_startVM</code> which uses the 704 settings cannot be called before all settings have be made.</p> 705 <p> 706 The only functions which is not effected by <code>jfw_lock</code> is 707 <code>jfw_areEqualJavaInfo</code>. 708 */ 709 JVMFWK_DLLPUBLIC void jfw_lock(); 710 711 /** unlocks this API. 712 713 <p>This function is called after <code>jfw_lock</code>. It allows other 714 threads to use this API concurrently.</p> 715 */ 716 JVMFWK_DLLPUBLIC void jfw_unlock(); 717 718 #endif 719 720 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ 721