Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 671 insertions, 0 deletions

diff --git a/include/jvmfwk/framework.hxx b/include/jvmfwk/framework.hxx
new file mode 100644
index 000000000..8f7eb8a2a
--- /dev/null
+++ b/include/jvmfwk/framework.hxx
@@ -0,0 +1,671 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+/** @HTML */
+
+#ifndef INCLUDED_JVMFWK_FRAMEWORK_HXX
+#define INCLUDED_JVMFWK_FRAMEWORK_HXX
+
+#include <sal/config.h>
+
+#include <memory>
+#include <vector>
+
+#include <jvmfwk/jvmfwkdllapi.hxx>
+#include <rtl/byteseq.hxx>
+#include <rtl/ustring.hxx>
+#if defined __clang__
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wunknown-attributes"
+#endif
+#include <jni.h>
+#if defined __clang__
+#pragma clang diagnostic pop
+#endif
+
+/** @file
+    <p>This library can operate in two modes, application mode and direct mode.</p>
+
+
+    <h2>Application Mode</h2>
+    In application mode the Java related settings are stored in files.
+    There are currently three files which need to be accessed. They are determined
+    by bootstrap parameters:</p>
+    <dl>
+    <dt>UNO_JAVA_JFW_VENDOR_SETTINGS</dt>
+    <dd>contains vendor and version information about JREs as well as the
+    location of plugin-libraries which are responsible for providing information
+    about these JREs as well as starting the VMs.</dd>
+    <dt>UNO_JAVA_JFW_USER_DATA</dt>
+    <dd>The file contains settings for a particular user. One can use the macro
+    $SYSUSERCONFIG in the URL which expands to a directory where the user's data are
+    kept. On UNIX this would be the home directory and on Windows some sub-directory
+    of the &quot;Documents and Settings&quot; folder.The content of this file is an
+    implementation detail and may change in the future.</dd>
+    <dt>UNO_JAVA_JFW_SHARED_DATA</dt>
+    <dd>The file contains settings valid for all users. If a user changes a setting
+    then it takes precedence over the setting from UNO_JAVA_JFW_SHARED_DATA.
+    The content of this file is an implementation detail and may change in the future.</dd>
+    </dl>
+
+    <p>The values for these parameters must be file URLs and include the file name, for
+    example:<br>
+    file:///d:/MyApp/javavendors.xml<br>
+    All files are XML files and must have the extension .xml.</p>
+    <p>
+    Modifying the shared settings is currently not supported by the framework. To provide
+    Java settings for all users one can run OOo and change the settings in the
+    options dialog. These settings are made persistent in the UNO_JAVA_JFW_USER_DATA.
+    The file can then be copied into the base installation.
+    Other users will use automatically these data but can override the settings in
+    the options dialog. This mechanism may change in the future.
+    </p>
+    <p>If shared Java settings are not supported by an application then it is not
+    necessary to specify the bootstrap parameter <code>UNO_JAVA_JFW_SHARED_DATA</code>.
+    </p>
+
+    <p>Setting the class path used by a Java VM should not be necessary. The locations
+    of Jar files should be known by a class loader. If a jar file depends on another
+    jar file then it can be referenced in the manifest file of the first jar. However,
+    a user may add jars to the class path by using this API. If it becomes necessary
+    to add files to the class path which is to be used by all users then one can use
+    the bootstrap parameter UNO_JAVA_JFW_CLASSPATH_URLS. The value contains of file URLs
+    which must be separated by spaces.</p>
+
+
+    <h2>Direct Mode</h2>
+
+    <p>The direct mode is intended for a scenario where no configuration files
+    are available and a Java VM  shall be run. That is,
+    the files containing the user and shared settings are not specified by the
+    bootstrap parameters UNO_JAVA_JFW_SHARED_DATA and UNO_JAVA_JFW_USER_DATA.
+    For example, tools, such as regcomp, may use this  framework in a build
+    environment. Then one would want to use settings which have been specified
+    by the build environment. The framework would automatically use the
+    current settings when they change in the environment.
+    </p>
+
+    <p> Here are examples how regcomp could be invoked using bootstrap parameters:
+    </p>
+    <p>
+    regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2
+    -env:&quot;UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\libreoffice.jar&quot;
+    -register...
+    </p>
+    <p>If UNO_JAVA_JFW_VENDOR_SETTINGS is not set then a plugin library must be specified. For example:</p>
+    <p>
+    regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2
+    -env:&quot;UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\libreoffice.jar&quot;
+    -register...
+    </p>
+    <p>Additional parameters for the Java VM can be provided. For every parameter
+    a separate bootstrap parameter must be specified. The names are
+    <code>UNO_JAVA_JFW_PARAMETER_X</code>, where X is 1,2, .. n. For example:</p>
+    <p>
+    regcomp -env:UNO_JAVA_JFW_PARAMETER_1=-Xdebug
+    -env:UNO_JAVA_JFW_PARAMETER_2=-Xrunjdwp:transport=dt_socket,server=y,address=8100
+    -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2
+    -env:&quot;UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\libreoffice.jar&quot;
+    -register...</p>
+    <p>
+    Here is a complete list of the bootstrap parameter for the direct mode:
+    </p>
+    <dl>
+    <dt>UNO_JAVA_JFW_JREHOME</dt>
+    <dd>Specifies a file URL to a JRE installation.It must ALWAYS be specified
+    in direct mode</dd>
+    <dt>UNO_JAVA_JFW_ENV_JREHOME</dt>
+    <dd>Setting this parameter, for example to &quot;1&quot; or &quot;true&quot;,
+    causes the framework to use the environment variable JAVA_HOME. It is expected
+    that JAVA_HOME contains a system path rather than a file URL. This parameter
+    and UNO_JAVA_JFW_JREHOME are mutually exclusive</dd>
+    <dt>UNO_JAVA_JFW_CLASSPATH</dt>
+    <dd>Contains the class path which is to be used by the VM. Special character,
+    such as '\','{','}','$' must be preceded with '\'. See documentation about the
+    bootstrap parameter.</dd>
+    <dt>UNO_JAVA_JFW_ENV_CLASSPATH</dt>
+    <dd>Setting this parameter,for example to &quot;1&quot; or &quot;true&quot;,
+    causes the framework to use the
+    environment variable CLASSPATH. If this variable and UNO_JAVA_JFW_CLASSPATH are
+    set then the class path is composed from UNO_JAVA_JFW_CLASSPATH and the environment
+    variable CLASSPATH.</dd>
+    <dt>UNO_JAVA_JFW_PARAMETER_X</dt>
+    <dd>Specifies a parameter for the Java VM. The X is replaced by
+    non-negative natural numbers starting with 1.</dd>
+    </dl>
+
+    <p>A note about bootstrap parameters. The implementation of the bootstrap
+    parameter mechanism interprets the characters '\', '$', '{', '}' as
+    escape characters. That's why the Windows path contain double back-slashes.
+    One should also take into account that a console may have also special
+    escape characters.</p>
+
+    <h2>What mode is used</h2>
+    <p>
+    The default mode is application mode. If at least one bootstrap parameter
+    for the direct mode is provided then direct mode is used. </p>
+
+    <p>
+    All settings made by this API are done for the current user if not
+    mentioned differently.</p>
+*/
+
+/** indicates that there must be an environment set up before the Java process
+    runs.
+    <p>Therefore, when a Java is selected in OO then the office must be
+    restarted, so that the changes can take effect.</p>
+ */
+#define JFW_REQUIRE_NEEDRESTART 0x1l
+
+/** error codes which are returned by functions of this API.
+ */
+enum javaFrameworkError
+{
+    JFW_E_NONE,
+    JFW_E_ERROR,
+    JFW_E_NO_SELECT,
+    JFW_E_INVALID_SETTINGS,
+    JFW_E_NEED_RESTART,
+    JFW_E_RUNNING_JVM,
+    JFW_E_JAVA_DISABLED,
+    JFW_E_NOT_RECOGNIZED,
+    JFW_E_FAILED_VERSION,
+    JFW_E_NO_JAVA_FOUND,
+    JFW_E_VM_CREATION_FAILED,
+    JFW_E_CONFIGURATION,
+    JFW_E_DIRECT_MODE
+};
+
+/** an instance of this struct represents an installation of a Java
+    Runtime Environment (JRE).
+
+    <p>
+    Instances of this struct are created by the plug-in libraries which are used by
+    this framework (jvmfwk/vendorplugin.h).</p>
+ */
+struct JavaInfo
+{
+    /** contains the vendor.
+
+        <p>string must be the same as the one obtained from the
+        Java system property <code>java.vendor</code>.
+        </p>
+     */
+    OUString sVendor;
+    /** contains the file URL to the installation directory.
+    */
+    OUString sLocation;
+    /** contains the version of this Java distribution.
+
+        <p>The version string  must adhere to the rules
+        about how a version string has to be formed. These rules may
+        be vendor-dependent. Essentially the strings must syntactically
+        equal the Java system property <code>java.version</code>.
+        </p>
+    */
+    OUString sVersion;
+    /** indicates requirements for running the java runtime.
+
+        <p>For example, it may be necessary to prepare the environment before
+        the runtime is created. That could mean, setting the
+        <code>LD_LIBRARY_PATH</code>
+        when <code>nRequirements</code> contains the flag
+        <code>JFW_REQUIRE_NEEDRESTART</code></p>
+     */
+    sal_uInt64 nRequirements;
+    /** contains data needed for the creation of the java runtime.
+
+        <p>There is no rule about the format and content of the sequence's
+        values. The plug-in libraries can put all data, necessary for
+        starting the java runtime into this sequence. </p>
+     */
+    rtl::ByteSequence arVendorData;
+};
+
+/** compares two <code>JavaInfo</code> objects for equality.
+
+   <p>Two <code>JavaInfo</code> objects are said to be equal if the contained
+   members of the first <code>JavaInfo</code> are equal to their counterparts
+   in the second <code>JavaInfo</code> object. The equality of the
+   <code>OUString</code> members is determined
+   by <code>operator ==</code>.
+   Similarly the equality of the <code>rtl::ByteSequence</code> is
+   also determined by a comparison
+   function (see <code>rtl::ByteSequence::operator ==</code>). </p>
+   <p>
+   Both argument pointers  must be valid.</p>
+   @param pInfoA
+   the first argument.
+   @param pInfoB
+   the second argument which is compared with the first.
+   @return
+   true - both object represent the same JRE.</br>
+   false - the objects represent different JREs
+ */
+JVMFWK_DLLPUBLIC bool jfw_areEqualJavaInfo(JavaInfo const* pInfoA, JavaInfo const* pInfoB);
+
+/** determines if a Java Virtual Machine is already running.
+
+    <p>As long as the office and the JREs only support one
+    Virtual Machine per process the Java settings, particularly the
+    selected Java, are not effective immediately after changing when
+    a VM has already been running. That is, if a JRE A was used to start
+    a VM and then a JRE B is selected, then JRE B will only be used
+    after a restart of the office.</p>
+    <p>
+    By determining if a VM is running, the user can be presented a message,
+    that the changed setting may not be effective immediately.</p>
+
+    @return
+    true iff a VM is running.
+*/
+JVMFWK_DLLPUBLIC bool jfw_isVMRunning();
+
+/** detects a suitable JRE and configures the framework to use it.
+
+    <p>Which JREs can be used is determined by the file javavendors.xml,
+    which contains version requirements.</p>
+    <p>
+    JREs can be provided by different vendors.
+    The function obtains information about JRE installations. If none was
+    found then it also uses a list of paths, which have been registered
+    by <code>jfw_addJRELocation</code>
+    to find JREs. Found JREs are examined in the same way.</p>
+    <p>
+    A JRE installation is only selected if it meets the version requirements.
+    Information about the selected JRE are made persistent so that
+    subsequent calls to <code>jfw_getSelectedJRE</code> returns this
+    information.</p>
+    <p>
+    While determining a proper JRE this function takes into account if a
+    user requires support for assistive technology tools. If user
+    need that support they have to set up their system accordingly.</p>
+    <p>
+    If the JAVA_HOME environment variable is set, this function prefers
+    the JRE which the variable refers to over other JREs.
+    If JAVA_HOME is not set or does not refer to a suitable JRE,
+    the PATH environment variable is inspected and the respective JREs
+    are checked for their suitability next.</p>
+    <p>
+    The first <code>JavaInfo</code> object that is detected by the algorithm
+    as described above is used.</p>
+
+    @param pInfo
+    [out] a <code>JavaInfo</code> pointer, representing the selected JRE.
+    The <code>JavaInfo</code> is for informational purposes only. It is not
+    necessary to call <code>jfw_setSelectedJRE</code> afterwards.<br/>
+    <code>pInfo</code>can be NULL.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR an error occurred. <br/>
+    JFW_E_NO_JAVA_FOUND no JRE was found that meets the requirements.</br>
+    JFW_E_DIRECT_MODE the function cannot be used in this mode. </br>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_findAndSelectJRE(std::unique_ptr<JavaInfo>* pInfo);
+
+/** provides information about all available JRE installations.
+
+    <p>The function determines dynamically what JREs are available. It uses
+    the plug-in libraries to provide lists of available <code>JavaInfo</code>
+    objects where each object represents a JRE (see vendorplugin.h,
+    getAllJavaInfos). It also uses a list of paths, which have been registered
+    by <code>jfw_addJRELocation</code>.
+    It is checked if the path still contains a valid JRE and if so the respective
+    <code>JavaInfo</code> object will be appended to the array unless there is
+    already an equal object.</p>
+
+    @param parInfo
+    [out] on returns it contains a vector of <code>JavaInfo</code> pointers.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR an error occurred. <br/>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.
+*/
+JVMFWK_DLLPUBLIC javaFrameworkError
+jfw_findAllJREs(std::vector<std::unique_ptr<JavaInfo>>* parInfo);
+
+/** determines if a path points to a Java installation.
+
+   <p>If the path belongs to a JRE installation then it returns the
+   respective <code>JavaInfo</code> object. The function uses the
+   <code>getJavaInfoByPath</code> function of the plug-ins to obtain the
+   <code>JavaInfo</code> object. Only if the JRE found at the specified location
+   meets the version requirements as specified in the javavendors.xml file a
+   <code>JavaInfo</code> object is returned.<br/>
+   <p>
+   The functions only checks if a JRE exists but does not modify any settings.
+   To make the found JRE the &quot;selected JRE&quot; one has
+   to call <code>jfw_setSelectedJRE</code>.</p>
+
+   @param pPath
+   [in] a file URL to a directory.
+   @param ppInfo
+   [out] the <code>JavaInfo</code> object which represents a JRE found at the
+   location specified by <code>pPath</code>
+
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_ERROR an error occurred. <br/>
+   JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+   were not met.</br>
+   JFW_E_NOT_RECOGNIZED neither plug-in library could detect a JRE. <br/>
+   JFW_E_FAILED_VERSION a JRE was detected but if failed the version
+   requirements as determined by the javavendors.xml
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_getJavaInfoByPath(OUString const& pPath,
+                                                          std::unique_ptr<JavaInfo>* ppInfo);
+
+/** starts a Java Virtual Machine (JVM).
+
+    <p>The function uses the current settings to start a JVM. The actual
+    start-up code, however, is provided by the plug-in libraries. The setting
+    of the &quot;selected Java&quot; contains the information as to what vendor
+    the respective JRE comes from. In the javavendors.xml there is a mapping of
+    vendor names to the respective plug-in libraries.</p>
+    <p>
+    The function ultimately calls <code>startJavaVirtualMachine</code> from
+    the plug-in library.</p>
+    <p>
+    The <code>arOptions</code>
+    argument contains start arguments which are passed in JavaVMOption structures
+    to the VM during its creation. These
+    could be things, such as language settings, proxy settings or any other
+    properties which shall be obtainable by
+    <code>java.lang.System.getProperties</code>. One can also pass options which
+    have a certain meaning to the runtime behaviour such as -ea or -X... However,
+    one must be sure that these options can be interpreted by the VM.<br/>
+    The class path cannot be set this way. The class path is internally composed by
+    the paths to archives in a certain directory, which is preconfigured in
+    the internal data store and the respective user setting (see
+    <code>jfw_setUserClassPath</code>.</p>
+    <p>
+    If a JRE was selected at runtime which was different from the previous
+    setting and that JRE needs a prepared environment, for example an adapted
+    <code>LD_LIBRARY_PATH</code> environment variable, then the VM will not be
+    created and JFW_E_NEED_RESTART error is returned. If a VM is already running
+    then a JFW_E_RUNNING_JVM is returned.</p>
+
+    @param pInfo
+    [in] optional pointer to a specific JRE; must be caller-freed if not NULL
+    @param arOptions
+    [in] the vector containing additional start arguments.
+    @param ppVM
+    [out] the <code>JavaVM</code> pointer.
+    @param ppEnv
+    [out] the <code>JNIenv</code> pointer.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR an error occurred. <br/>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.</br>
+    JFW_E_JAVA_DISABLED the use of Java is currently disabled. <br/>
+    JFW_E_NO_SELECT there is no JRE selected yet. <br/>
+    JFW_E_RUNNING_JVM there is already a VM running.<br/>
+    JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no
+    JRE has been selected afterwards. <br/>
+    JFW_E_NEED_RESTART in the current process a different JRE has been selected
+    which needs a prepared environment, which has to be done before the office
+    process. Therefore the new JRE may not be used until the office was restarted.<br/>
+    JFW_E_NEED_RESTART is also returned when Java was disabled at the beginning and
+    then the user enabled it. If then the selected  JRE has the requirement
+    JFW_REQUIRE_NEEDRESTART then this error is returned. </br>
+    JFW_E_VM_CREATION_FAILED the creation of the JVM failed. The creation is performed
+    by a plug-in library and not by this API.
+    JFW_E_FAILED_VERSION the &quot;Default Mode&quot; is active. The JRE determined by
+    <code>JAVA_HOME</code>does not meet the version requirements.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_startVM(JavaInfo const* pInfo,
+                                                std::vector<OUString> const& arOptions,
+                                                JavaVM** ppVM, JNIEnv** ppEnv);
+
+/** determines the JRE that is to be used.
+
+    <p>When calling <code>jfw_startVM</code> then a VM is started from
+    the JRE that is determined by this function.<br/>
+    It is not verified if the JRE represented by the <code>JavaInfo</code>
+    argument meets the requirements as specified by the javavendors.xml file.
+    However, usually one obtains the <code>JavaInfo</code> object from the
+    functions <code>jfw_findAllJREs</code> or <code>jfw_getJavaInfoByPath</code>,
+    which do verify the JREs and pass out only <code>JavaInfo</code> objects
+    which comply with the version requirements.</p>
+    <p>
+    If <code>pInfo</code> is NULL then the meaning is that no JRE will be
+    selected. <code>jfw_startVM</code> will then return
+    <code>JFW_E_NO_SELECT</code>.</p>
+
+    @param pInfo
+      [in] pointer to <code>JavaInfo</code> structure, containing data about a
+      JRE. The caller must still free <code>pInfo</code>.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+    JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_setSelectedJRE(JavaInfo const* pInfo);
+
+/** provides information about the JRE that is to be used.
+
+    <p>If no JRE is currently selected then <code>ppInfo</code> will contain
+    NULL on return.</br>
+    If the value of the element <updated> in the javavendors.xml file was
+    changed since the time when the last Java was selected then this
+    function returns <code>JFW_E_INVALID_SETTINGS</code>. This could happen during
+    a product patch. Then new version requirements may be introduced, so that
+    the currently selected JRE may not meet these requirements anymore.
+    </p>
+    <p>In direct mode the function returns information about a JRE that was
+    set by the bootstrap parameter UNO_JAVA_JFW_JREHOME.
+    </p>
+    @param ppInfo
+    [out] on return it contains a pointer to a <code>JavaInfo</code> object
+    that represents the currently selected JRE. When <code>*ppInfo</code> is not
+    NULL then the function sets the pointer.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+    JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no
+    JRE has been selected afterwards. <br/>
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_getSelectedJRE(std::unique_ptr<JavaInfo>* ppInfo);
+
+/** determines if Java can be used.
+
+   <p>If <code>bEnabled</code> is <code>false</code> then a call
+   to jfw_startVM will result in an error with the errorcode
+   <code>JFW_E_JAVA_DISABLED</code></p>
+
+   @param bEnabled
+   [in] use of Java enabled/disabled.
+
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+   JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_setEnabled(bool bEnabled);
+
+/** provides the information if Java can be used.
+
+    <p>That is if the user enabled or disabled the use of Java.
+    </p>
+
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+    JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_getEnabled(bool* pbEnabled);
+
+/** determines parameters which are passed to VM during its creation.
+
+    <p>The strings must be exactly as they are passed on the command line.
+    For example, one could pass<br/>
+    -Xdebug <br/>
+    -Xrunjdw:transport=dt_socket,server=y,address=8000<br/>
+    in order to enable debugging support.
+    </p>
+
+    @param arParameters
+    [in] contains the arguments.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+    JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_setVMParameters(std::vector<OUString> const& arArgs);
+
+/** obtains the currently used start parameters.
+
+    @param parParameters
+    [out] on returns contains a pointer to the array of the start arguments.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+    JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_getVMParameters(std::vector<OUString>* parParameters);
+
+/** sets the user class path.
+
+   <p>When the VM is started then it is passed the class path. The
+   class path also contains the user class path set by this function.
+   The paths contained in <code>pCP</code> must be separated with a
+   system dependent path separator.</p>
+
+   @param pCP
+   [in] the user class path.
+
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+   JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_setUserClassPath(OUString const& pCP);
+/** provides the value of the current user class path.
+
+   <p>The function returns an empty string if no user class path is set.
+   </p>
+
+   @param ppCP
+   [out] contains the user class path on return.
+
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+   JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_getUserClassPath(OUString* ppCP);
+
+/** saves the location of a JRE.
+
+    <p>When <code>jfw_findAllJREs</code> is called then the paths added by this
+    function are evaluated. If the location still represents a
+    JRE then a <code>JavaInfo</code> object is created which is returned along
+    with all other <code>JavaInfo</code> objects by
+    <code>jfw_findAllJREs</code>. If the location
+    cannot be recognized then the location string is ignored. </p>
+    <p>
+    A validation if <code>sLocation</code> points to a JRE is not
+    performed. To do that one has to use <code>jfw_getJavaInfoByPath</code>.
+    </p>
+    <p>
+    Adding a path that is already stored causes no error.</p>
+
+    @param sLocation
+    [in] file URL to a directory which contains a JRE.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIGURATION mode was not properly set or their prerequisites
+    were not met.<br/>
+    JFW_E_DIRECT_MODE the function cannot be used in this mode.
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_addJRELocation(OUString const& sLocation);
+
+/** checks if the installation of the jre still exists.
+
+    This function checks if the JRE described by pInfo still
+    exists. The check must be very quick because it is called by javaldx
+    (Linux, Solaris) at start up.
+
+    @param pInfo
+        [in]  the JavaInfo object with information about the JRE.
+    @param pp_exist
+        [out] the parameter is set to either true or false. The value is
+        only valid if the function returns JFW_E_NONE.
+
+   @return
+    JFW_E_NONE the function ran successfully.</br>
+    JFW_E_ERROR an error occurred during execution.</br>
+ */
+JVMFWK_DLLPUBLIC javaFrameworkError jfw_existJRE(const JavaInfo* pInfo, bool* exist);
+
+/** locks this API so that it cannot be used by other threads.
+
+    <p>If a different thread called this function before then the
+    current call is blocked until the other thread has called
+    <code>jfw_unlock()</code>. The function should be called if one
+    needs an exact snapshot of the current settings. Then the settings
+    are retrieved one by one without risk that the settings may be changed
+    by a different thread. Similarity if one needs to make settings which
+    should become effective at the same time then <code>jfw_lock</code>
+    should be called. That is, <code>jfw_startVM</code> which uses the
+    settings cannot be called before all settings have be made.</p>
+    <p>
+    The only functions which is not effected by <code>jfw_lock</code> is
+    <code>jfw_areEqualJavaInfo</code>.
+ */
+JVMFWK_DLLPUBLIC void jfw_lock();
+
+/** unlocks this API.
+
+    <p>This function is called after <code>jfw_lock</code>. It allows other
+    threads to use this API concurrently.</p>
+*/
+JVMFWK_DLLPUBLIC void jfw_unlock();
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */