From 3ca762ec3e40f168e56bec3bb480f5240a986cf8 Mon Sep 17 00:00:00 2001
From: Joachim Lingner
+ The flag is used with JavaInfo::nFeatures. Therefore, when a Java is selected in OO then the office must be
+ restarted, so that the changes can take effect.
+ Instances of this struct are created by the plug-in libraries which are used by
+ this framework (jvmfwk/vendorplugin.h). The memory of the instances is created
+ by string must be the same as the one obtained from the
+ Java system property 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 For example, For example, it may be necessary to prepare the environment before
+ the runtime is created. That could mean, setting the
+ 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. Two
+ Both argument pointers must be valid. As long as the the office and the JREs only support one
+ Virtual Machine per process the Java settings, particulary the
+ selected Java, are not effective immediatly 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. Which JREs can be used is determined by the file javavendors.xml,
+ which contains version requirements, as well as information about available
+ plug-in libraries. Only these libraries are responsible for locating JRE
+ installations.
- The function uses the requirements from the file javavendors.xml.
- A JRE installation is only selected if it meets those requirements.
- Information about the selected Java are made persistent as user data so that
- subsequent calls to jfw_getSelectedJava returns this information.rtl_allocateMemory
(rtl/alloc.h). Therefore, the memory must
+ be freed by rtl_freeMemory
. Also the contained members must be
+ freed particularly.
+ For convenience this API provides the function jfw_freeJavaInfo
+ which frees the objects properly. java.vendor
.
+ java.version
.
+ JFW_FEATURE_ACCESSBRIDGE
indicates that
+ assistive technology tools are supported.LD_LIBRARY_PATH
+ when nRequirements
contains the flag
+ JFW_REQUIRE_NEEDRESTART
JavaInfo
object.
@param pInfo
The object which is to be freed. It can be NULL;
*/
void SAL_CALL jfw_freeJavaInfo(JavaInfo *pInfo);
-/**
- Both arguments must me valid JavaInfo*.
+
+/** compares two JavaInfo
objects for equality.
+
+ 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
+ rtl_uString
members is determined
+ by the respective comparison function (see
+ rtl::OUString::equals
).
+ Similiarly the equality of the sal_Sequence
is
+ also determined by a comparison
+ function (see rtl::ByteSequence::operator ==
).
+ sal_False - no VM is running.
@return
- JFW_E_NONE
- JFW_E_INVALID_ARG;
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG the parameter bRunning
was NULL.
*/
-javaFrameworkError SAL_CALL jfw_isJavaRunning(sal_Bool *bRunning);
+javaFrameworkError SAL_CALL jfw_isVMRunning(sal_Bool *bRunning);
+
+/** detects a suitable JRE and configures the framework to use it.
-/** Detects a suitable Java and configures the framework to use this Java.
+
- If the JRE represented by pInfo has the flag JFW_REQUIRE_NEEDRESTART - set in pInfo->nRequirements, then the function jfw_startJava will not - create a JVM until the office has been restarted.
+ A JRE installation is only selected if it meets the version requirements. + Information about the selected JRE are made persistent so that + subsequent calls tojfw_getSelectedJRE
returns this
+ information.
- The new - settings are effective immediatly. That is, jfw_useNewSettings does - not need to be called.
+ 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. When support + for assistive technology is required, then the lists of +JavaInfo
objects,
+ which are provided by the getJavaInfo
functions of the plug-ins, are
+ examined for a suitable JRE. That is, the JavaInfo
objects
+ from the list
+ obtained from the first plug-in, are examined. If no JavaInfo
+ object has the flag
+ JFW_FEATURE_ACCESSBRIDGE
in the member nFeatures
+ then the
+ next plug-in is used to obtain a list of JavaInfo
objects.
+ This goes on until a JavaInfo
object was found which
+ represents a suitable JRE. Or neither plug-in provided such a
+ JavaInfo
object. In that case the first
+ JavaInfo
object from the first plug-in is used to determine
+ the JRE which is to be used.
- //ToDo algorith for selecting a JRE
+ If there is no need for the support of assistive technology tools then
+ the first JavaInfo
object from the list obtained by the
+ first plug-in is used. If this plug-in does not find any JREs then the
+ next plug-in is used, and so on.
JavaInfo
pointer, representing the selected JRE.
+ The caller has to free it by calling jfw_freeJavaInfo. The
+ JavaInfo
is for informational purposes only. It is not
+ necessary to call jfw_setSelectedJRE
afterwards.
+ ppInfo
can be NULL. If *ppInfo
is not null, then it is
+ overwritten, without attempting to free *ppInfo
.
@return
- JFW_E_ERROR
- JFW_E_CONFIGREADWRITE An error occurred while reading or writing the
- configuration files.
- JFW_E_FORMAT_STORE
- JFW_E_NOPLUGIN A plug-in library could not be found.
- JFW_E_NOJAVAFOUND No Java was found that meets the requirements.
+ JFW_E_NONE function ran successfully.
+ JFW_E_ERROR an error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
+ JFW_E_NO_PLUGIN a plug-in library could not be found.
+ JFW_E_NO_JAVA_FOUND no JRE was found that meets the requirements.
*/
-javaFrameworkError SAL_CALL jfw_findAndSelectJava(JavaInfo **pInfo);
+javaFrameworkError SAL_CALL jfw_findAndSelectJRE(JavaInfo **pInfo);
+
+/** provides information about all availabe 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
or jfw_setJRELocations
.
+ 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 pointer to an array of JavaInfo
+ pointers.
+ The caller must free the array with rtl_freeMemory
and each
+ element of the array must be freed with jfw_freeJavaInfo
.
+ @param pSize
+ [out] on return contains the size of array returned in parInfo
.
-/** provides information about all availabe Java installations.
-
- It determines dynamically what JREs are available. It uses the plugin
- libraries to provide lists of available JREs (see vendorplugin.h,
- getAllJavaInfos). Also it uses a list of path, 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
- pparInfo. If the path for some reason is no JRE then the path will be
- removed from an internal list.
- */
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG at least on of the parameters was NULL
+ JFW_E_ERROR an error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
+ JFW_E_NO_PLUGIN a plug-in library could not be found.
+*/
javaFrameworkError SAL_CALL jfw_findAllJREs(
- JavaInfo ***pparInfo, sal_Int32 *pSize);
+ JavaInfo ***parInfo, sal_Int32 *pSize);
-/** determines if a path belongs to a Java installation.
+/** 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.
- If the path belongs to a Java installation then it returns the
- respective JavaInfo object. To make that JRE the "selected" JRE one has
- to call jfw_setJava and jfw_applyChanges.
-
+ 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]
+ [in] a file URL to a directory.
@param pInfo
- [out]
+ [out] the JavaInfo
object which represents a JRE found at the
+ location specified by pPath
@return
- JFW_E_NONE
- JFW_E_ERROR
- JFW_E_INVALID_ARG
- JFW_E_NOT_RECOGNIZED
-
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG at least on of the parameters was NULL
+ JFW_E_ERROR an error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
+ JFW_E_NO_PLUGIN a plug-in library could not be found.
+ 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
*/
javaFrameworkError SAL_CALL jfw_getJavaInfoByPath(
rtl_uString *pPath, JavaInfo **ppInfo);
-/** Starts a JVM.
+/** 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.
- Uses the information in the javasetttings.xml to start a JVM. The arOptions
- argument contains options, which shall be passed on to the JVM. These
- could be things, such as language settings which are currently obtained
- from the office's configuration in the JavaVirtualMachine service. The
- java.class.path property cannot be set this way.
+ The function ultimately calls startJavaVirtualMachine
from
+ the plug-in library.
- If there are neither user or global settings which contain data about
- a JRE which is to be used, then the function returns
- JFW_E_NO_SELECT
.
+ 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 the function was called successfully then calling it again will
- not create a new VM and JFW_E_RUNNING_JVM is returned. When at one time, one
- can have multiple VMs in one process than this function may allow to start
- a second VM.
-
+ 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 arOptions
- Can be NULL
+ [in] the array containing additional start arguments or NULL.
+ @param nSize
+ [in] the size of the array arOptions
.
+ @param ppVM
+ [out] the JavaVM
pointer.
+ @param ppEnv
+ [out] the JNIenv
pointer.
+
@return
- JFW_E_INVALID_ARG ppVM is NULL,
- JFW_E_CONFIG_READWRITE
- JFW_E_FORMAT_STORE
- JFW_E_NO_PLUGIN A plug-in library could not be found.
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG ppVM
, ppEnv
are NULL or
+ arOptions
was NULL but nSize
was greater 0.
+ JFW_E_ERROR an error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
+ JFW_E_NO_PLUGIN the plug-in library responsible for creating the VM
+ could not be found.
JFW_E_JAVA_DISABLED the use of Java is currently disabled.
- JFW_E_NO_SELECT javasettings.xml does not contain data about
- JFW_E_RUNNIN_GJVM
- a JRE which is to be used.
+ JFW_E_NO_SELECT there is no JRE selected yet.
+ JFW_E_RUNNIN_JVM there is already a VM running.
JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no
- Java has been selected afterwards.
- JFW_E_NEED_RESTART In the current process a different Java has been selected
+ 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. For example, setting the LD_LIBRARY_PATH. Therefore the new
- Java may not be created until office was restarted.
+ process. Therefore the new JRE may not be used until the office was restarted.
*/
-javaFrameworkError SAL_CALL jfw_startJava(JavaVMOption *arOptions,
- sal_Int32 cOptions, JavaVM **ppVM,
+javaFrameworkError SAL_CALL jfw_startVM(JavaVMOption *arOptions,
+ sal_Int32 nSize, JavaVM **ppVM,
JNIEnv **ppEnv);
-/** Configure the framework to use a particular Java.
-
- Called by options dialog if someone choose an entry from the list.
- It is not checked if the JRE represented by pInfo meets the requirements
- from the javavendors.xml file.
-
- If pInfo is NULL then the meaning is that no java will be selected. jfw_startJava
- will later return JFW_E_NO_SELECT.
+/** determines the JRE that is to be used.
+
+ When calling jfw_startVM
then a VM is startet 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.
- This setting will only become effective after calling jfw_applyChanges.
-
- If the JRE represented by pInfo has the flag JFW_REQUIRE_NEEDRESTART
- set in pInfo->nRequirements, then the function startJava will not
- create a JVM until the office has been restarted.
+ 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 Java
- installation. The caller must still free 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_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
-javaFrameworkError SAL_CALL jfw_setSelectedJava(JavaInfo const *pInfo);
+javaFrameworkError SAL_CALL jfw_setSelectedJRE(JavaInfo const *pInfo);
-/** Provides information about the currently selected Java installation.
-
- It is not guaranteed that the selected JRE does not change after a
- call to this function. However, it can be used by Java preparation tools
- which run prior to the office process and set up the necessary
- environment required by that JRE.
-
+/** provides information about the JRE that is to be used.
+
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.
+ function returns JFW_E_INVALID_SETTINGS
. This could happen during
+ a product patch. Then new version requirements may be introduces, so that
+ the currently selected JRE may not meet these requirements anymore.
- @param pInfo [out]
+ @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 overwrites the pointer. It is not attempted to free
+ the pointer.
@return
- JFW_E_NONE on success
-
- JFW_E_INVALIDARG, pInfo is a NULL pointer or a member of pInfo is
- invalid. For example, if pInfo->sVendor is not NULL because the member
- was not properly initialized, then it will be tried to release the string
- which will fail.
- JFW_E_CONFIG_READWRITE
- JFW_E_FORMAT_STORE
- JFW_E_NO_SELECT there is no Java selected yet.
- JFW_E_INVALID_SETTINGS
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG ppInfo
is a NULL.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
+
+ JFW_E_NO_SELECT there is no Java selected yet.
+ JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no
+ JRE has been selected afterwards.
*/
-javaFrameworkError SAL_CALL jfw_getSelectedJava(JavaInfo **pInfo);
+javaFrameworkError SAL_CALL jfw_getSelectedJRE(JavaInfo **ppInfo);
-/** sets the the "enabled" parameter.
-
- Used from option dialog.
- If bGlobal is true then this value is stored globally, that is
- the value is valid for all users unless they have made own settings.
- The user must have sufficient file access rights to modify the
- global settings.
-
- The new value comes only into effect after jfw_applyChanges is
- called.
+/** determines if Java can be used.
+
+ If bEnabled
is sal_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_ERROR An error occurred.E.g. the user has not sufficient rights.
- JFW_E_INVALIDARG
- JFW_E_JAVADISABLED
+ JFW_E_NONE function ran successfully.
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
javaFrameworkError SAL_CALL jfw_setEnabled(sal_Bool bEnabled);
-/** determines the value of the Java setting "enabled".
-
- The returned value in pbEnabled
has been taken from
- a snapshot of the internal data. The value may change later on.
-
- This function can be called from
- Java preparation tools, such as javaldx, which run prior to the
- office process. The status is usually only changed by the
- options dialog, where a user can enable or disable Java.
-
- If the function jfw_setEnabled has never been called before
- by the current user, then the value returned in pbEnabled
- is determined by global settings. If there are no global settings
- then the default is that Java is enabled.
+/** provides the information if Java can be used.
- @return
- JFW_E_NONE The function was successful.
- JFW_E_ERROR An error occurred.
- JFW_E_CONFIG_READWRITE Error during access of internal data store.
- JFW_E_FORMAT_STORE The structure of the internal data store is not
- as expected.
- JFW_E_INVALIDARG pbEnabled is NULL
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG pbEnabled is NULL
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
javaFrameworkError SAL_CALL jfw_getEnabled(sal_Bool *pbEnabled);
-/** sets options, such as debug options.
+/** determines parameters which are passed to VM during its creation.
- arOptions can be null if nSize is also 0.
+
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. It can be NULL if nSize is 0.
+ @param nSize
+ [i] the size of arArgs
@return
- JFW_E_INVALIDARG arOptions is NULL and nSize is not 0
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG arArgs is NULL and nSize is not 0
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
javaFrameworkError SAL_CALL jfw_setVMParameters(
- rtl_uString ** arParameters, sal_Int32 nSize);
-/**
- Caller needs to free the returned array with rtl_freeMemory. The
- containes rtl_uStrings must be released with rtl_uString_release.
+ rtl_uString ** arArgs, sal_Int32 nSize);
- @return
- JFW_E_NONE The function was successful.
+/** obtains the currently used start parameters.
+
+ The caller needs to free the returned array with
+ rtl_freeMemory
. The contained strings must be released with
+ rtl_uString_release
.
+
+
+ @param parParameters
+ [out] on returns contains a pointer to the array of the start arguments.
+ If *parParameters is not NULL then the value is overwritten.
+ @param pSize
+ [out] on return contains the size of array returned in
+ parParameters
+
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG parParameters or pSize are NULL
JFW_E_ERROR An error occurred.
- JFW_E_CONFIG_READWRITE Error during access of internal data store.
- JFW_E_FORMAT_STORE The structure of the internal data store is not
- as expected.
- JFW_E_INVALIDARG parOptions or pSize are NULL
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
javaFrameworkError SAL_CALL jfw_getVMParameters(
rtl_uString *** parParameters,
sal_Int32 * pSize);
-/**
- The argument pC must be a valid string. If the value is NULL then
- a JFW_E_INVALID_ARG is returned.
+/** 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.
+
+ @param pCP
+ [in] the user class path.
+
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG pCP is NULL.
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
javaFrameworkError SAL_CALL jfw_setUserClassPath(rtl_uString * pCP);
-/**
- returns an empty string if no user class path is set.
+/** 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. If *ppCP
was
+ not NULL then the value is overwritten. No attempt at freeing that string
+ is made.
+
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG ppCP is NULL.
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
javaFrameworkError SAL_CALL jfw_getUserClassPath(rtl_uString ** ppCP);
/** saves the location of a JRE.
-
- When jfw_findAllJREs is called then the paths added by this
+
+
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.
-
+ 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.
+ 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.
+ Adding a path that is already stored causes no error.
+
@param sLocation
- File URL to an directory which contains a JRE.
+ [in] file URL to a directory which contains a JRE.
+
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG sLocation is NULL.
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
+
+ @see jfw_setJRELocations
*/
javaFrameworkError SAL_CALL jfw_addJRELocation(rtl_uString * sLocation);
-/** stores an array containing paths to JRE installations.
+/** saves the locations of a number of JREs.
+
The function does not verify if the paths points to JRE. However,
it makes sure that every path is unique. That is, if the array
- contains string which are the same then only one is stored.
+ contains strings which are the same then only one is stored.
- If arLocations is NULL or arLocations has the length null
+ If arLocations
is NULL or it has the length null (nSize = 0)
then all previously stored paths are deleted. Otherwise,
the old values are overwritten.
+
+ @param arLocations
+ [in] array of paths to locations of JREs.
+
+ @param nSize
+ [in] the size of the array arLocations
+
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG arLocation is NULL and nSize is not null.
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
+
+ @see jfw_addJRELocations
*/
javaFrameworkError SAL_CALL jfw_setJRELocations(
rtl_uString ** arLocations, sal_Int32 nSize);
/** obtains an array containing paths to JRE installations.
+
It is not guaranteed that the returned paths represent
- a valid JRE. One can use jfw_getJavaInfoByPath to check this.
+ a valid JRE. One can use jfw_getJavaInfoByPath
to check this.
+
+ @param parLocations
+ [out] on return it contains the array of paths.
+ @param pSize
+ [out] on return it contains the size of the array parLocations
.
+
+ @return
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG parLocation is NULL or pSize is NULL.
+ JFW_E_ERROR An error occurred.
+ JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+ the internally used data store.
+ JFW_E_FORMAT_STORE the internally used data store has not the
+ expected format
*/
javaFrameworkError SAL_CALL jfw_getJRELocations(
rtl_uString *** parLocations, sal_Int32 * pSize);
-
+/** 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. Similiary 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 are not effected by jfw_lock
are
+ jfw_freeJavaInfo
and jfw_areEqualJavaInfo
.
+ */
void SAL_CALL jfw_lock();
+/** unlocks this API.
+
+
This function is called after jfw_lock
. It allows other
+ threads to use this API concurrently.
+*/
void SAL_CALL jfw_unlock();
diff --git a/jvmfwk/inc/jvmfwk/vendorplugin.h b/jvmfwk/inc/jvmfwk/vendorplugin.h
index bf2b4e33b7ee..8e5dd748075e 100644
--- a/jvmfwk/inc/jvmfwk/vendorplugin.h
+++ b/jvmfwk/inc/jvmfwk/vendorplugin.h
@@ -2,9 +2,9 @@
*
* $RCSfile: vendorplugin.h,v $
*
- * $Revision: 1.2 $
+ * $Revision: 1.3 $
*
- * last change: $Author: jl $ $Date: 2004-04-21 09:30:35 $
+ * last change: $Author: jl $ $Date: 2004-04-22 12:52:39 $
*
* The Contents of this file are made available subject to the terms of
* either of the following licenses
@@ -82,7 +82,7 @@ typedef enum
JFW_PLUGIN_E_ERROR,
JFW_PLUGIN_E_INVALID_ARG,
JFW_PLUGIN_E_WRONG_VERSION_FORMAT,
- JFW_PLUGIN_E_FAILED_REQUIREMENTS,
+ JFW_PLUGIN_E_FAILED_VERSION,
JFW_PLUGIN_E_NO_JRE
} javaPluginError;
@@ -114,7 +114,7 @@ javaPluginError getAllJavaInfos(
JFW_PLUGIN_E_ERROR
JFW_PLUGIN_E_INVALID_ARG
JFW_PLUGIN_E_WRONG_VERSION_FORMAT
- JFW_PLUGIN_E_FAILED_REQUIREMENTS
+ JFW_PLUGIN_E_FAILED_VERSION
JFW_PLUGIN_E_NO_JRE
*/
javaPluginError getJavaInfoByPath(
--
cgit