summaryrefslogtreecommitdiffstats
path: root/include/jvmfwk
diff options
context:
space:
mode:
Diffstat (limited to 'include/jvmfwk')
-rw-r--r--include/jvmfwk/framework.hxx671
-rw-r--r--include/jvmfwk/jvmfwkdllapi.hxx23
2 files changed, 694 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: */
diff --git a/include/jvmfwk/jvmfwkdllapi.hxx b/include/jvmfwk/jvmfwkdllapi.hxx
new file mode 100644
index 000000000..bd59abb74
--- /dev/null
+++ b/include/jvmfwk/jvmfwkdllapi.hxx
@@ -0,0 +1,23 @@
+/* -*- 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/.
+ */
+
+#ifndef INCLUDED_JVMFWK_JVMFWKDLLAPI_HXX
+#define INCLUDED_JVMFWK_JVMFWKDLLAPI_HXX
+
+#include <sal/types.h>
+
+#if defined JVMFWK_DLLIMPLEMENTATION
+#define JVMFWK_DLLPUBLIC SAL_DLLPUBLIC_EXPORT
+#else
+#define JVMFWK_DLLPUBLIC SAL_DLLPUBLIC_IMPORT
+#endif
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */