/* -*- 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 #include #include #include #include #include #include /** @file

This library can operate in two modes, application mode and direct mode.

Application Mode

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:

UNO_JAVA_JFW_VENDOR_SETTINGS
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.
UNO_JAVA_JFW_USER_DATA
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 "Documents and Settings" folder.The content of this file is an implementation detail and may change in the future.
UNO_JAVA_JFW_SHARED_DATA
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.

The values for these parameters must be file URLs and include the file name, for example:
file:///d:/MyApp/javavendors.xml
All files are XML files and must have the extension .xml.

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.

If shared Java settings are not supported by an application then it is not necessary to specify the bootstrap parameter UNO_JAVA_JFW_SHARED_DATA.

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.

Direct Mode

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.

Here are examples how regcomp could be invoked using bootstrap parameters:

regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" -register...

If UNO_JAVA_JFW_VENDOR_SETTINGS is not set then a plugin library must be specified. For example:

regcomp -env:UNO_JAVA_JFW_JREHOME=file:///d:/j2re1.4.2 -env:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" -register...

Additional parameters for the Java VM can be provided. For every parameter a separate bootstrap parameter must be specified. The names are UNO_JAVA_JFW_PARAMETER_X, where X is 1,2, .. n. For example:

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:"UNO_JAVA_JFW_CLASSPATH=d:\\solver\\bin\\classes.jar;d:\\solver\\bin\\jurt.jar" -register...

Here is a complete list of the bootstrap parameter for the direct mode:

UNO_JAVA_JFW_JREHOME
Specifies a file URL to a JRE installation.It must ALWAYS be specified in direct mode
UNO_JAVA_JFW_ENV_JREHOME
Setting this parameter, for example to "1" or "true", 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
UNO_JAVA_JFW_CLASSPATH
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.
UNO_JAVA_JFW_ENV_CLASSPATH
Setting this parameter,for example to "1" or "true", 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.
UNO_JAVA_JFW_PARAMETER_X
Specifies a parameter for the Java VM. The X is replaced by non-negative natural numbers starting with 1.

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.

What mode is used

The default mode is application mode. If at least one bootstrap parameter for the direct mode is provided then direct mode is used.

All settings made by this API are done for the current user if not mentioned differently.

*/ /** indicates that a JRE has an accessibility bridge installed.

The flag is used with JavaInfo::nFeatures.

*/ #define JFW_FEATURE_ACCESSBRIDGE 0x1l /** indicates that there must be an environment set up before the Java process runs.

Therefore, when a Java is selected in OO then the office must be restarted, so that the changes can take effect.

*/ #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).

Instances of this struct are created by the plug-in libraries which are used by this framework (jvmfwk/vendorplugin.h).

*/ struct JavaInfo { /** contains the vendor.

string must be the same as the one obtained from the Java system property java.vendor.

*/ OUString sVendor; /** contains the file URL to the installation directory. */ OUString sLocation; /** contains the version of this Java distribution.

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 java.version.

*/ OUString sVersion; /** indicates supported special features.

For example, JFW_FEATURE_ACCESSBRIDGE indicates that assistive technology tools are supported.

*/ sal_uInt64 nFeatures; /** indicates requirements for running the java runtime.

For example, it may be necessary to prepare the environment before the runtime is created. That could mean, setting the LD_LIBRARY_PATH when nRequirements contains the flag JFW_REQUIRE_NEEDRESTART

*/ sal_uInt64 nRequirements; /** contains data needed for the creation of the java runtime.

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.

*/ rtl::ByteSequence arVendorData; }; /** compares two JavaInfo objects for equality.

Two JavaInfo objects are said to be equal if the contained members of the first JavaInfo are equal to their counterparts in the second JavaInfo object. The equality of the OUString members is determined by operator ==. Similarly the equality of the rtl::ByteSequence is also determined by a comparison function (see rtl::ByteSequence::operator ==).

Both argument pointers must be valid.

@param pInfoA the first argument. @param pInfoB the second argument which is compared with the first. @return true - both object represent the same JRE.
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.

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.

By determining if a VM is running, the user can be presented a message, that the changed setting may not be effective immediately.

@return true iff a VM is running. */ JVMFWK_DLLPUBLIC bool jfw_isVMRunning(); /** detects a suitable JRE and configures the framework to use it.

Which JREs can be used is determined by the file javavendors.xml, which contains version requirements.

JREs can be provided by different vendors. The function obtains information about JRE installations and checks if there is one among them that supports a set of features (currently only accessibility is possible). If none was found then it also uses a list of paths, which have been registered by jfw_addJRELocation to find JREs. Found JREs are examined in the same way.

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 jfw_getSelectedJRE returns this information.

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.

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.

When support for assistive technology is required, then the JavaInfo objects, which are provided by the getJavaInfo functions, are examined for a suitable JRE. That is, the JavaInfo object that refers to the JRE referred to by JAVA_HOME is examined. If it does not have the flag JFW_FEATURE_ACCESSBRIDGE in the member nFeatures then the objects that are related to the PATH variable are examined. If no suitable JavaInfo object is found, all JavaInfo objects - representing Java installations on the system -, are examined. As long as no JavaInfo object has the flag JFW_FEATURE_ACCESSBRIDGE in the member nFeatures, more JavaInfo objects are examined. This goes on until a JavaInfo object was found which represents a suitable JRE. Or no such JavaInfo object was found. In that case the first JavaInfo object that was detected by the algorithm described above is used to determine the JRE which is to be used.

If there is no need for the support of assistive technology tools then the first JavaInfo object that is detected by the algorithm as described above is used.

@param pInfo [out] a JavaInfo pointer, representing the selected JRE. The JavaInfo is for informational purposes only. It is not necessary to call jfw_setSelectedJRE afterwards.
pInfocan be NULL. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR an error occurred.
JFW_E_NO_JAVA_FOUND no JRE was found that meets the requirements.
JFW_E_DIRECT_MODE the function cannot be used in this mode.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met. */ JVMFWK_DLLPUBLIC javaFrameworkError jfw_findAndSelectJRE(std::unique_ptr *pInfo); /** provides information about all available JRE installations.

The function determines dynamically what JREs are available. It uses the plug-in libraries to provide lists of available JavaInfo objects where each object represents a JRE (see vendorplugin.h, getAllJavaInfos). It also uses a list of paths, which have been registered by jfw_addJRELocation. It is checked if the path still contains a valid JRE and if so the respective JavaInfo object will be appended to the array unless there is already an equal object.

@param parInfo [out] on returns it contains a vector of JavaInfo pointers. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR an error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met. */ JVMFWK_DLLPUBLIC javaFrameworkError jfw_findAllJREs( std::vector> *parInfo); /** determines if a path points to a Java installation.

If the path belongs to a JRE installation then it returns the respective JavaInfo object. The function uses the getJavaInfoByPath function of the plug-ins to obtain the JavaInfo object. Only if the JRE found at the specified location meets the version requirements as specified in the javavendors.xml file a JavaInfo object is returned.

The functions only checks if a JRE exists but does not modify any settings. To make the found JRE the "selected JRE" one has to call jfw_setSelectedJRE.

@param pPath [in] a file URL to a directory. @param ppInfo [out] the JavaInfo object which represents a JRE found at the location specified by pPath @return JFW_E_NONE function ran successfully.
JFW_E_ERROR an error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
JFW_E_NOT_RECOGNIZED neither plug-in library could detect a JRE.
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 *ppInfo); /** starts a Java Virtual Machine (JVM).

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 "selected Java" 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.

The function ultimately calls startJavaVirtualMachine from the plug-in library.

The arOptions 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 java.lang.System.getProperties. 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.
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 jfw_setUserClassPath.

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 LD_LIBRARY_PATH 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.

@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 JavaVM pointer. @param ppEnv [out] the JNIenv pointer. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR an error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
JFW_E_JAVA_DISABLED the use of Java is currently disabled.
JFW_E_NO_SELECT there is no JRE selected yet.
JFW_E_RUNNING_JVM there is already a VM running.
JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no JRE has been selected afterwards.
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.
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.
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 "Default Mode" is active. The JRE determined by JAVA_HOMEdoes not meet the version requirements. */ JVMFWK_DLLPUBLIC javaFrameworkError jfw_startVM( JavaInfo const * pInfo, std::vector const & arOptions, JavaVM ** ppVM, JNIEnv ** ppEnv); /** determines the JRE that is to be used.

When calling jfw_startVM then a VM is started from the JRE that is determined by this function.
It is not verified if the JRE represented by the JavaInfo argument meets the requirements as specified by the javavendors.xml file. However, usually one obtains the JavaInfo object from the functions jfw_findAllJREs or jfw_getJavaInfoByPath, which do verify the JREs and pass out only JavaInfo objects which comply with the version requirements.

If pInfo is NULL then the meaning is that no JRE will be selected. jfw_startVM will then return JFW_E_NO_SELECT.

@param pInfo [in] pointer to JavaInfo structure, containing data about a JRE. The caller must still free pInfo. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
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.

If no JRE is currently selected then ppInfo will contain NULL on return.
If the value of the element in the javavendors.xml file was changed since the time when the last Java was selected then this function returns JFW_E_INVALID_SETTINGS. 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.

In direct mode the function returns information about a JRE that was set by the bootstrap parameter UNO_JAVA_JFW_JREHOME.

@param ppInfo [out] on return it contains a pointer to a JavaInfo object that represents the currently selected JRE. When *ppInfo is not NULL then the function sets the pointer. @return JFW_E_NONE function ran successfully.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no JRE has been selected afterwards.
*/ JVMFWK_DLLPUBLIC javaFrameworkError jfw_getSelectedJRE(std::unique_ptr *ppInfo); /** determines if Java can be used.

If bEnabled is false then a call to jfw_startVM will result in an error with the errorcode JFW_E_JAVA_DISABLED

@param bEnabled [in] use of Java enabled/disabled. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
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.

That is if the user enabled or disabled the use of Java.

@return JFW_E_NONE function ran successfully.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
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.

The strings must be exactly as they are passed on the command line. For example, one could pass
-Xdebug
-Xrunjdw:transport=dt_socket,server=y,address=8000
in order to enable debugging support.

@param arParameters [in] contains the arguments. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
JFW_E_DIRECT_MODE the function cannot be used in this mode. */ JVMFWK_DLLPUBLIC javaFrameworkError jfw_setVMParameters( std::vector 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.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
JFW_E_DIRECT_MODE the function cannot be used in this mode. */ JVMFWK_DLLPUBLIC javaFrameworkError jfw_getVMParameters( std::vector * parParameters); /** sets the user class path.

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 pCP must be separated with a system dependent path separator.

@param pCP [in] the user class path. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
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.

The function returns an empty string if no user class path is set.

@param ppCP [out] contains the user class path on return. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
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.

When jfw_findAllJREs is called then the paths added by this function are evaluated. If the location still represents a JRE then a JavaInfo object is created which is returned along with all other JavaInfo objects by jfw_findAllJREs. If the location cannot be recognized then the location string is ignored.

A validation if sLocation points to a JRE is not performed. To do that one has to use jfw_getJavaInfoByPath.

Adding a path that is already stored causes no error.

@param sLocation [in] file URL to a directory which contains a JRE. @return JFW_E_NONE function ran successfully.
JFW_E_ERROR An error occurred.
JFW_E_CONFIGURATION mode was not properly set or their prerequisites were not met.
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.
JFW_E_ERROR an error occurred during execution.
*/ JVMFWK_DLLPUBLIC javaFrameworkError jfw_existJRE(const JavaInfo *pInfo, bool *exist); /** locks this API so that it cannot be used by other threads.

If a different thread called this function before then the current call is blocked until the other thread has called jfw_unlock(). 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 jfw_lock should be called. That is, jfw_startVM which uses the settings cannot be called before all settings have be made.

The only functions which is not effected by jfw_lock is jfw_areEqualJavaInfo. */ JVMFWK_DLLPUBLIC void jfw_lock(); /** unlocks this API.

This function is called after jfw_lock. It allows other threads to use this API concurrently.

*/ JVMFWK_DLLPUBLIC void jfw_unlock(); #endif /* vim:set shiftwidth=4 softtabstop=4 expandtab: */