#i20052#

5 files changed, 521 insertions, 223 deletions

diff --git a/jvmfwk/inc/jvmfwk/framework.h b/jvmfwk/inc/jvmfwk/framework.h
index aa91a172cf5a..e52cebc4cd7e 100644
--- a/jvmfwk/inc/jvmfwk/framework.h
+++ b/jvmfwk/inc/jvmfwk/framework.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: framework.h,v $
  *
- *  $Revision: 1.3 $
+ *  $Revision: 1.4 $
  *
- *  last change: $Author: jl $ $Date: 2004-04-21 12:16:18 $
+ *  last change: $Author: jl $ $Date: 2004-04-22 12:52:38 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -15,8 +15,7 @@
  *  Sun Microsystems Inc., October, 2000
  *
  *  GNU Lesser General Public License Version 2.1
- *  =============================================
- *  Copyright 2000 by Sun Microsystems, Inc.
+ *   *  Copyright 2000 by Sun Microsystems, Inc.
  *  901 San Antonio Road, Palo Alto, CA 94303, USA
  *
  *  This library is free software; you can redistribute it and/or
@@ -35,8 +34,7 @@
  *
  *
  *  Sun Industry Standards Source License Version 1.1
- *  =================================================
- *  The contents of this file are subject to the Sun Industry Standards
+ *   *  The contents of this file are subject to the Sun Industry Standards
  *  Source License Version 1.1 (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.openoffice.org/license.html.
@@ -59,6 +57,8 @@
  *
  ************************************************************************/
 
+/** @HTML */
+
 #if !defined INCLUDED_JVMFWK_FRAMEWORK_H
 #define INCLUDED_JVMFWK_FRAMEWORK_H
 
@@ -70,13 +70,26 @@
 extern "C" {
 #endif
 
+/** @file
+    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.
+    <p>
+    The flag is used with JavaInfo::nFeatures.</p>
+ */
 #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.
+/** 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.
+ */
 typedef enum
 {
     JFW_E_NONE,
@@ -91,324 +104,605 @@ typedef enum
     JFW_E_FORMAT_STORE,
     JFW_E_NO_PLUGIN,
     JFW_E_NOT_RECOGNIZED,
+    JFW_E_FAILED_VERSION,
     JFW_E_NO_JAVA_FOUND
 } javaFrameworkError;
 
+/** 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). The memory of the instances is created
+    by <code>rtl_allocateMemory</code> (rtl/alloc.h). Therefore, the memory must
+    be freed by <code>rtl_freeMemory</code>. Also the contained members must be
+    freed particularly.
+    For convenience this API provides the function <code>jfw_freeJavaInfo</code>
+    which frees the objects properly. </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>
+     */
     rtl_uString *sVendor;
+    /** contains the file URL to the installation directory.
+    */
     rtl_uString *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>
+    */
     rtl_uString *sVersion;
+    /** indicates supported special features.
+
+        <p>For example, <code>JFW_FEATURE_ACCESSBRIDGE</code> indicates that
+        assistive technology tools are supported.</p>
+     */
     sal_uInt64 nFeatures;
+    /** indicates requirments 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>
+     */
     sal_Sequence * arVendorData;
 };
 
 typedef struct _JavaInfo JavaInfo;
 
-/** frees the memory of a JavaInfo object.
+/** frees the memory of a <code>JavaInfo</code> 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 <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>rtl_uString</code> members is determined
+   by the respective comparison function (see
+   <code>rtl::OUString::equals</code>).
+   Similiarly the equality of the <code>sal_Sequence</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
+   sal_True - both object represent the same JRE.</br>
+   sal_False - the objects represend different JREs
  */
 sal_Bool SAL_CALL jfw_areEqualJavaInfo(
     JavaInfo const * pInfoA,JavaInfo const * pInfoB);
-/** When a Java is already running and a user changes the Java configuration
-    in the options dialog then the user must be informed that the new
-    settings come into effect after re-starting the office. The options dialog
-    can use this function to find out if the user needs to be informed.
-    If one day multiple JVMs can exist in one process, then this function may
-    be obsolete.
+
+/** determines if a Java Virtual Machine is already running.
+
+    <p>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.</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>
+
+    @param bRunning
+    [out] sal_True - a VM is running. <br/>
+    sal_False - no VM is running.
 
     @return
-    JFW_E_NONE
-    JFW_E_INVALID_ARG;
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_INVALID_ARG the parameter <code>bRunning</code> 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.
+    <p>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.</p>
     <p>
-    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.</p>
+    JREs can be provided by different vendors. In order to find the JREs of
+    a certain vendor a plug-in library must be provided. There must be only one
+    library for one vendor. The names of locations of those libraries have to
+    be put into the javavendors.xml file.</p>
     <p>
-    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.</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>
-    The new
-    settings are effective immediatly. That is, jfw_useNewSettings does
-    not need to be called.</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. When support
+    for assistive technology is required, then the lists of
+    <code>JavaInfo</code> objects,
+    which are provided by the <code>getJavaInfo</code> functions of the plug-ins, are
+    examined for a suitable JRE. That is, the <code>JavaInfo</code> objects
+    from the list
+    obtained from the first plug-in, are examined. If no <code>JavaInfo</code>
+    object has the flag
+    <code>JFW_FEATURE_ACCESSBRIDGE</code> in the member <code>nFeatures</code>
+    then the
+    next plug-in is used to obtain a list of <code>JavaInfo</code> objects.
+    This goes on until a <code>JavaInfo</code> object was found which
+    represents a suitable JRE. Or neither plug-in provided such a
+    <code>JavaInfo</code> object. In that case the first
+    <code>JavaInfo</code> object from the first plug-in is used to determine
+    the JRE which is to be used.</p>
     <p>
-    //ToDo algorith for selecting a JRE
+    If there is no need for the support of assistive technology tools then
+    the first <code>JavaInfo</code> 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.</p>
 
     @param ppInfo
-    [out] The function returns a JavaInfo pointer.
-    It can be NULL. If *pInfo is not null, then it is overwritten, without
-    attempting to free pInfo.
+    [out] a <code>JavaInfo</code> pointer, representing the selected JRE.
+    The caller has to free it by calling <code>jfw_freeJavaInfo<code>. The
+    <code>JavaInfo</code> is for informational purposes only. It is not
+    necessary to call <code>jfw_setSelectedJRE</code> afterwards.<br/>
+    <code>ppInfo</code>can be NULL. If <code>*ppInfo</code> is not null, then it is
+    overwritten, without attempting to free <code>*ppInfo</code>.
 
     @return
-    JFW_E_ERROR
-    JFW_E_CONFIGREADWRITE An error occurred while reading or writing the
-    configuration files. <br/>
-    JFW_E_FORMAT_STORE <br/>
-    JFW_E_NOPLUGIN A plug-in library could not be found. <br/>
-    JFW_E_NOJAVAFOUND No Java was found that meets the requirements.
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_ERROR an error occurred. <br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
+    JFW_E_NO_PLUGIN a plug-in library could not be found.<br/>
+    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.
+
+    <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> or <code>jfw_setJRELocations</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 pointer to an array of <code>JavaInfo</code>
+    pointers.
+    The caller must free the array with <code>rtl_freeMemory</code> and each
+    element of the array must be freed with <code>jfw_freeJavaInfo</code>.
+    @param pSize
+    [out] on return contains the size of array returned in <code>parInfo</code>.
 
-/** provides information about all availabe Java installations.
-    <p>
-    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.</p>
- */
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_INVALID_ARG at least on of the parameters was NULL<br/>
+    JFW_E_ERROR an error occurred. <br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
+    JFW_E_NO_PLUGIN a plug-in library could not be found.<br/>
+*/
 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.
+
+   <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>
-   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.
-   </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]
+   [in] a file URL to a directory.
    @param pInfo
-   [out]
+   [out] the <code>JavaInfo</code> object which represents a JRE found at the
+   location specified by <code>pPath</code>
 
    @return
-   JFW_E_NONE
-   JFW_E_ERROR
-   JFW_E_INVALID_ARG
-   JFW_E_NOT_RECOGNIZED
-
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_INVALID_ARG at least on of the parameters was NULL<br/>
+   JFW_E_ERROR an error occurred. <br/>
+   JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+   the internally used data store. <br/>
+   JFW_E_FORMAT_STORE the internally used data store has not the
+   expected format<br/>
+   JFW_E_NO_PLUGIN a plug-in library could not be found.<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
  */
 javaFrameworkError SAL_CALL jfw_getJavaInfoByPath(
     rtl_uString *pPath, JavaInfo **ppInfo);
 
 
-/** Starts a JVM.
+/** 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>
-    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.    </p>
+    The function ultimately calls <code>startJavaVirtualMachine</code> from
+    the plug-in library.</p>
     <p>
-    If there are neither user or global settings which contain data about
-    a JRE which is to be used, then the function returns
-    <code>JFW_E_NO_SELECT</code>.</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 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.</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 arOptions
-    Can be NULL
+    [in] the array containing additional start arguments or NULL.
+    @param nSize
+    [in] the size of the array <code>arOptions</code>.
+    @param ppVM
+    [out] the <code>JavaVM</code> pointer.
+    @param ppEnv
+    [out] the <code>JNIenv</code> 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. <br/>
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_INVALID_ARG <code>ppVM</code>, <code>ppEnv</code> are NULL or
+    <code>arOptions</code> was NULL but <code>nSize</code> was greater 0.<br/>
+    JFW_E_ERROR an error occurred. <br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
+    JFW_E_NO_PLUGIN the plug-in library responsible for creating the VM
+    could not be found.<br/>
     JFW_E_JAVA_DISABLED the use of Java is currently disabled. <br/>
-    JFW_E_NO_SELECT javasettings.xml does not contain data about
-    JFW_E_RUNNIN_GJVM
-    a JRE which is to be used.<br/>
+    JFW_E_NO_SELECT there is no JRE selected yet. <br/>
+    JFW_E_RUNNIN_JVM there is already a VM running.<br/>
     JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no
-    Java has been selected afterwards. <br/>
-    JFW_E_NEED_RESTART In the current process a different Java has been selected
+    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. For example, setting the LD_LIBRARY_PATH. Therefore the new
-    Java may not be created until office was restarted.<br/>
+    process. Therefore the new JRE may not be used until the office was restarted.<br/>
  */
-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.
-    <p>
-    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. </p>
-    <p>
-    If pInfo is NULL then the meaning is that no java will be selected. jfw_startJava
-    will later return JFW_E_NO_SELECT. </p>
+/** determines the JRE that is to be used.
+
+    <p>When calling <code>jfw_startVM</code> then a VM is startet 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>
-    This setting will only become effective after calling jfw_applyChanges.
-    </p>
-    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.</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 JavaInfo structure, containing data about Java
-      installation. The caller must still free 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_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
  */
-javaFrameworkError SAL_CALL jfw_setSelectedJava(JavaInfo const *pInfo);
+javaFrameworkError SAL_CALL jfw_setSelectedJRE(JavaInfo const *pInfo);
 
 
-/** Provides information about the currently selected Java installation.
-    <p>
-    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.
-    </p>
+/** provides information about the JRE that is to be used.
+
     <p>
     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 JFW_E_INVALID_SETTINGS.
+    function returns <code>JFW_E_INVALID_SETTINGS</code>. 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.
     </p>
-    @param pInfo [out]
+    @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 overwrites the pointer. It is not attempted to free
+    the pointer.
 
     @return
-    JFW_E_NONE on success <br/>
-
-    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. <br/>
-    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.<br/>
+    JFW_E_INVALIDARG <code>ppInfo</code> is a NULL.<br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
+
+    JFW_E_NO_SELECT there is no Java selected yet.<br/>
+    JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no
+    JRE has been selected afterwards. <br/>
  */
-javaFrameworkError SAL_CALL jfw_getSelectedJava(JavaInfo **pInfo);
+javaFrameworkError SAL_CALL jfw_getSelectedJRE(JavaInfo **ppInfo);
 
 
-/** sets the the &quot;enabled&quot parameter.
-    <p>
-   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.</p>
-   <p>
-   The new value comes only into effect after jfw_applyChanges is
-   called.</p>
+/** determines if Java can be used.
+
+   <p>If <code>bEnabled</code> is <code>sal_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_ERROR An error occurred.E.g. the user has not sufficient rights.
-   JFW_E_INVALIDARG
-   JFW_E_JAVADISABLED
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+   the internally used data store. <br/>
+   JFW_E_FORMAT_STORE the internally used data store has not the
+   expected format<br/>
  */
 javaFrameworkError SAL_CALL jfw_setEnabled(sal_Bool bEnabled);
 
-/** determines the value of the Java setting &quot;enabled&quot;.
-    <p>
-    The returned value in <code>pbEnabled</code> has been taken from
-    a snapshot of the internal data. The value may change later on.</p>
-    <p>
-    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. </p>
-    <p>
-    If the function jfw_setEnabled has never been called before
-    by the current user, then the value returned in <code>pbEnabled</code>
-    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.<br/>
-    JFW_E_ERROR An error occurred.<br/>
-    JFW_E_CONFIG_READWRITE Error during access of internal data store.<br/>
-    JFW_E_FORMAT_STORE The structure of the internal data store is not
-    as expected. <br/>
-    JFW_E_INVALIDARG pbEnabled is NULL<br/>
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_INVALIDARG pbEnabled is NULL<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+   the internally used data store. <br/>
+   JFW_E_FORMAT_STORE the internally used data store has not the
+   expected format<br/>
  */
 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.
+    <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. It can be NULL if nSize is 0.
+    @param nSize
+    [i] the size of <code>arArgs</code>
 
     @return
-    JFW_E_INVALIDARG arOptions is NULL and nSize is not 0
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_INVALIDARG arArgs is NULL and nSize is not 0
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
  */
 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.<br/>
+/** obtains the currently used start parameters.
+
+    <p>The caller needs to free the returned array with
+    <code>rtl_freeMemory</code>. The contained strings must be released with
+    <code>rtl_uString_release</code>.
+    </p>
+
+    @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
+    <code>parParameters</code>
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_INVALIDARG parParameters or pSize are  NULL<br/>
     JFW_E_ERROR An error occurred.<br/>
-    JFW_E_CONFIG_READWRITE Error during access of internal data store.<br/>
-    JFW_E_FORMAT_STORE The structure of the internal data store is not
-    as expected. <br/>
-    JFW_E_INVALIDARG parOptions or pSize are  NULL<br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
  */
 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.
+
+   <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.</p>
+
+   @param pCP
+   [in] the user class path.
+
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_INVALIDARG pCP is NULL.<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+   the internally used data store. <br/>
+   JFW_E_FORMAT_STORE the internally used data store has not the
+   expected format<br/>
  */
 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.
+
+   <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. If <code>*ppCP</code> was
+   not NULL then the value is overwritten. No attempt at freeing that string
+   is made.
+
+   @return
+   JFW_E_NONE function ran successfully.<br/>
+   JFW_E_INVALIDARG ppCP is NULL.<br/>
+   JFW_E_ERROR An error occurred.<br/>
+   JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+   the internally used data store. <br/>
+   JFW_E_FORMAT_STORE the internally used data store has not the
+   expected format<br/>
  */
 javaFrameworkError SAL_CALL jfw_getUserClassPath(rtl_uString ** ppCP);
 
 /** saves the location of a JRE.
-    <p>
-    When jfw_findAllJREs is called then the paths added by this
+
+    <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 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.
-    </p>
+    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 jfw_getJavaInfoByPath.
+    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.
+    Adding a path that is already stored causes no error.</p>
+
     @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.<br/>
+    JFW_E_INVALIDARG sLocation is NULL.<br/>
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
+
+    @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.
+
     <p>
     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.</p>
+    contains strings which are the same then only one is stored.</p>
     <p>
-    If arLocations is NULL or arLocations has the length null
+    If <code>arLocations</code> is NULL or it has the length null (nSize = 0)
     then all previously stored paths are deleted. Otherwise,
     the old values are overwritten.</p>
+
+    @param arLocations
+    [in] array of paths to locations of JREs.
+
+    @param nSize
+    [in] the size of the array <code>arLocations</code>
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_INVALIDARG arLocation is NULL and nSize is not null.<br/>
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
+
+    @see jfw_addJRELocations
  */
 javaFrameworkError SAL_CALL jfw_setJRELocations(
     rtl_uString ** arLocations, sal_Int32 nSize);
 /** obtains an array containing paths to JRE installations.
+
     <p>
     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 <code>jfw_getJavaInfoByPath</code> to check this.
     </p>
+
+    @param parLocations
+    [out] on return it contains the array of paths.
+    @param pSize
+    [out] on return it contains the size of the array <code>parLocations</code>.
+
+    @return
+    JFW_E_NONE function ran successfully.<br/>
+    JFW_E_INVALIDARG parLocation is NULL or pSize is NULL.<br/>
+    JFW_E_ERROR An error occurred.<br/>
+    JFW_E_CONFIG_READWRITE an error occurred while reading or writing to
+    the internally used data store. <br/>
+    JFW_E_FORMAT_STORE the internally used data store has not the
+    expected format<br/>
  */
 javaFrameworkError SAL_CALL jfw_getJRELocations(
     rtl_uString *** parLocations, sal_Int32 * pSize);
 
-
+/** 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. Similiary 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 are not effected by <code>jfw_lock</code> are
+    <code>jfw_freeJavaInfo</code> and <code>jfw_areEqualJavaInfo</code>.
+ */
 void SAL_CALL 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>
+*/
 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(
diff --git a/jvmfwk/plugins/sunmajor/pluginlib/sunjavaplugin.cxx b/jvmfwk/plugins/sunmajor/pluginlib/sunjavaplugin.cxx
index 90e497b190b9..ff5c501b297c 100644
--- a/jvmfwk/plugins/sunmajor/pluginlib/sunjavaplugin.cxx
+++ b/jvmfwk/plugins/sunmajor/pluginlib/sunjavaplugin.cxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: sunjavaplugin.cxx,v $
  *
- *  $Revision: 1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: jl $ $Date: 2004-04-19 15:36:12 $
+ *  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
@@ -210,7 +210,7 @@ javaPluginError getJavaInfoByPath(
                 stoc_javadetect::JavaInfo::compareVersions(
                     sVersion, sTheMinVersion);
             if (nRes < 0)
-                return JFW_PLUGIN_E_FAILED_REQUIREMENTS;
+                return JFW_PLUGIN_E_FAILED_VERSION;
         }
 
         rtl::OUString sTheMaxVersion((rtl_uString*) sMaxVersion);
@@ -220,7 +220,7 @@ javaPluginError getJavaInfoByPath(
                 stoc_javadetect::JavaInfo::compareVersions(
                     sVersion, sTheMaxVersion);
             if (nRes > 0)
-                return JFW_PLUGIN_E_FAILED_REQUIREMENTS;
+                return JFW_PLUGIN_E_FAILED_VERSION;
         }
 
         if (arExcludeList > 0)
@@ -232,7 +232,7 @@ javaPluginError getJavaInfoByPath(
                     stoc_javadetect::JavaInfo::compareVersions(
                         sVersion, sExVer);
                 if (nRes == 0)
-                    return JFW_PLUGIN_E_FAILED_REQUIREMENTS;
+                    return JFW_PLUGIN_E_FAILED_VERSION;
             }
         }
 
diff --git a/jvmfwk/source/framework.cxx b/jvmfwk/source/framework.cxx
index d482719891b4..1bfdd41dfd22 100644
--- a/jvmfwk/source/framework.cxx
+++ b/jvmfwk/source/framework.cxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: framework.cxx,v $
  *
- *  $Revision: 1.3 $
+ *  $Revision: 1.4 $
  *
- *  last change: $Author: jl $ $Date: 2004-04-21 12:16:19 $
+ *  last change: $Author: jl $ $Date: 2004-04-22 12:52:40 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -227,7 +227,7 @@ javaFrameworkError SAL_CALL jfw_findAllJREs(JavaInfo ***pparInfo, sal_Int32 *pSi
                 & pInfo);
             if (plerr == JFW_PLUGIN_E_NO_JRE)
                 continue;
-            if (plerr == JFW_PLUGIN_E_FAILED_REQUIREMENTS)
+            if (plerr == JFW_PLUGIN_E_FAILED_VERSION)
                 continue;
             else if (plerr !=JFW_PLUGIN_E_NONE)
             {   //delete JavaInfo objects
@@ -276,7 +276,7 @@ javaFrameworkError SAL_CALL jfw_findAllJREs(JavaInfo ***pparInfo, sal_Int32 *pSi
     return errcode;
 }
 
-javaFrameworkError SAL_CALL jfw_startJava(JavaVMOption *arOptions, sal_Int32 cOptions,
+javaFrameworkError SAL_CALL jfw_startVM(JavaVMOption *arOptions, sal_Int32 cOptions,
                                  JavaVM **ppVM, JNIEnv **ppEnv)
 {
     osl::MutexGuard guard(jfw::getFwkMutex());
@@ -414,7 +414,7 @@ javaFrameworkError SAL_CALL jfw_startJava(JavaVMOption *arOptions, sal_Int32 cOp
 }
 
 
-javaFrameworkError SAL_CALL jfw_findAndSelectJava(JavaInfo **pInfo)
+javaFrameworkError SAL_CALL jfw_findAndSelectJRE(JavaInfo **pInfo)
 {
     osl::MutexGuard guard(jfw::getFwkMutex());
     javaFrameworkError errcode = JFW_E_NONE;
@@ -583,7 +583,7 @@ void SAL_CALL jfw_freeJavaInfo(JavaInfo *pInfo)
     rtl_freeMemory(pInfo);
 }
 
-javaFrameworkError SAL_CALL jfw_getSelectedJava(JavaInfo **ppInfo)
+javaFrameworkError SAL_CALL jfw_getSelectedJRE(JavaInfo **ppInfo)
 {
     osl::MutexGuard guard(jfw::getFwkMutex());
     javaFrameworkError errcode = JFW_E_NONE;
@@ -610,7 +610,7 @@ javaFrameworkError SAL_CALL jfw_getSelectedJava(JavaInfo **ppInfo)
     return errcode;
 }
 
-javaFrameworkError SAL_CALL jfw_isJavaRunning(sal_Bool *bRunning)
+javaFrameworkError SAL_CALL jfw_isVMRunning(sal_Bool *bRunning)
 {
     osl::MutexGuard guard(jfw::getFwkMutex());
     if (bRunning == NULL)
@@ -629,8 +629,6 @@ javaFrameworkError SAL_CALL jfw_getJavaInfoByPath(
     if (pPath == NULL || ppInfo == NULL)
         return JFW_E_INVALID_ARG;
     javaFrameworkError errcode = JFW_E_NONE;
-//        sal_Int64 nFeatureFlags = 0L;
-//    jfw::CJavaInfo aCurrentInfo;
     //Prepare the xml document and context
     rtl::OString sSettingsPath = jfw::getVendorSettingsPath();
      jfw::CXmlDocPtr doc = xmlParseFile(sSettingsPath.getStr());
@@ -691,19 +689,25 @@ javaFrameworkError SAL_CALL jfw_getJavaInfoByPath(
             *ppInfo = pInfo;
             break;
         }
-        else if(plerr == JFW_PLUGIN_E_FAILED_REQUIREMENTS)
+        else if(plerr == JFW_PLUGIN_E_FAILED_VERSION)
         {//found JRE but it has the wrong version
             *ppInfo = NULL;
+            errcode = JFW_E_FAILED_VERSION;
             break;
         }
+        else if (plerr = JFW_PLUGIN_E_NO_JRE)
+        {// plugin does not recognize this path as belonging to JRE
+            continue;
+        }
+        OSL_ASSERT(0);
     }
-    if (*ppInfo == NULL)
+    if (*ppInfo == NULL && errcode != JFW_E_FAILED_VERSION)
         errcode = JFW_E_NOT_RECOGNIZED;
     return errcode;
 }
 
 
-javaFrameworkError SAL_CALL jfw_setSelectedJava(JavaInfo const *pInfo)
+javaFrameworkError SAL_CALL jfw_setSelectedJRE(JavaInfo const *pInfo)
 {
     osl::MutexGuard guard(jfw::getFwkMutex());
     javaFrameworkError errcode = JFW_E_NONE;
diff --git a/jvmfwk/source/framework.map b/jvmfwk/source/framework.map
index 2aa0331eb441..2ce5d22b61dc 100644
--- a/jvmfwk/source/framework.map
+++ b/jvmfwk/source/framework.map
@@ -4,12 +4,12 @@ UDK_3_0_0 {
     jfw_freeJavaInfo;
     jfw_areEqualJavaInfo;
     jfw_findAllJREs;
-    jfw_findAndSelectJava;
-    jfw_startJava;
-    jfw_isJavaRunning;
+    jfw_findAndSelectJRE;
+    jfw_startVM;
+    jfw_isVMRunning;
     jfw_getJavaInfoByPath;
-    jfw_setSelectedJava;
-    jfw_getSelectedJava;
+    jfw_setSelectedJRE;
+    jfw_getSelectedJRE;
     jfw_setEnabled;
     jfw_getEnabled;
     jfw_setVMParameters;