#i20052#

2 files changed, 151 insertions, 39 deletions

diff --git a/jvmfwk/inc/jvmfwk/framework.h b/jvmfwk/inc/jvmfwk/framework.h
index 73db8cdbfbf6..5af8cb814d49 100644
--- a/jvmfwk/inc/jvmfwk/framework.h
+++ b/jvmfwk/inc/jvmfwk/framework.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: framework.h,v $
  *
- *  $Revision: 1.8 $
+ *  $Revision: 1.9 $
  *
- *  last change: $Author: jl $ $Date: 2004-05-07 14:49:40 $
+ *  last change: $Author: jl $ $Date: 2004-05-21 15:07:05 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -71,9 +71,25 @@ extern "C" {
 #endif
 
 /** @file
+    <p>
+    This library currently has to operational modes. In office mode it
+    expects that it is located in the program directory and the javavendors.xml
+    file must be in the folder <office>/share/config. A Java Virtual Machine (JVM)
+    can only be created if a JRE has been selected. That is either
+    <code>jfw_setSelectedJRE</code> or <code>jfw_findAndSelectJRE</code> must have
+    run successfully.</p>
+    <p>
+    In &quot;default mode&quot; the framework uses the environment variables
+    <code>JAVA_HOME</code> and <code>CLASSPATH</code> to determine the JRE which
+    is to be used and the class path. If the JRE does not meet the version
+    requirements as specified by the javavendors.xml then jfw_startVM will return
+    JFW_E_FAILED_VERSION. It is expected that the javavendors.xml and the plug-in
+    libraries are located in the same folder as this library. In this mode no
+    settings are written nor read. The functions will return JFW_E_DEFAULT_MODE.
+    </p>
+
     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.
@@ -106,7 +122,8 @@ typedef enum
     JFW_E_NOT_RECOGNIZED,
     JFW_E_FAILED_VERSION,
     JFW_E_NO_JAVA_FOUND,
-    JFW_E_VM_CREATION_FAILED
+    JFW_E_VM_CREATION_FAILED,
+    JFW_E_DEFAULT_MODE
 } javaFrameworkError;
 
 /** an instance of this struct represents an installation of a Java
@@ -284,7 +301,8 @@ javaFrameworkError SAL_CALL jfw_isVMRunning(sal_Bool *bRunning);
     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.
+    JFW_E_NO_JAVA_FOUND no JRE was found that meets the requirements.</br>
+    JFW_E_DEFAULT_MODE because of this mode no settings are written.
  */
 javaFrameworkError SAL_CALL jfw_findAndSelectJRE(JavaInfo **pInfo);
 
@@ -419,6 +437,8 @@ javaFrameworkError SAL_CALL jfw_getJavaInfoByPath(
     JFW_REQUIRE_NEEDRESTART then this error is returned. </br>
     JFW_E_VM_CREATION_FAILED the creation of the JVM failed. The creation is performed
     by a plug-in library and not by this API.
+    JFW_E_FAILED_VERSION the &quot;Default Mode&quot; is active. The JRE determined by
+    <code>JAVA_HOME</code>does not meet the version requirements.
  */
 javaFrameworkError SAL_CALL jfw_startVM(JavaVMOption *arOptions,
                                  sal_Int32 nSize, JavaVM **ppVM,
@@ -450,6 +470,7 @@ javaFrameworkError SAL_CALL jfw_startVM(JavaVMOption *arOptions,
     the internally used data store. <br/>
     JFW_E_FORMAT_STORE the internally used data store has not the
     expected format<br/>
+    JFW_E_DEFAULT_MODE because of this mode no settings are written.
  */
 javaFrameworkError SAL_CALL jfw_setSelectedJRE(JavaInfo const *pInfo);
 
@@ -479,6 +500,7 @@ javaFrameworkError SAL_CALL jfw_setSelectedJRE(JavaInfo const *pInfo);
     expected format<br/>
     JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no
     JRE has been selected afterwards. <br/>
+    JFW_E_DEFAULT_MODE because of this mode no settings are read.
  */
 javaFrameworkError SAL_CALL jfw_getSelectedJRE(JavaInfo **ppInfo);
 
@@ -499,6 +521,7 @@ javaFrameworkError SAL_CALL jfw_getSelectedJRE(JavaInfo **ppInfo);
    the internally used data store. <br/>
    JFW_E_FORMAT_STORE the internally used data store has not the
    expected format<br/>
+   JFW_E_DEFAULT_MODE because of this mode no settings are written.
  */
 javaFrameworkError SAL_CALL jfw_setEnabled(sal_Bool bEnabled);
 
@@ -512,6 +535,7 @@ javaFrameworkError SAL_CALL jfw_setEnabled(sal_Bool bEnabled);
    the internally used data store. <br/>
    JFW_E_FORMAT_STORE the internally used data store has not the
    expected format<br/>
+   JFW_E_DEFAULT_MODE because of this mode no settings are read.
  */
 javaFrameworkError SAL_CALL jfw_getEnabled(sal_Bool *pbEnabled);
 
@@ -537,6 +561,7 @@ javaFrameworkError SAL_CALL jfw_getEnabled(sal_Bool *pbEnabled);
     the internally used data store. <br/>
     JFW_E_FORMAT_STORE the internally used data store has not the
     expected format<br/>
+    JFW_E_DEFAULT_MODE because of this mode no settings are written.
  */
 javaFrameworkError SAL_CALL jfw_setVMParameters(
     rtl_uString **  arArgs, sal_Int32 nSize);
@@ -563,6 +588,7 @@ javaFrameworkError SAL_CALL jfw_setVMParameters(
     the internally used data store. <br/>
     JFW_E_FORMAT_STORE the internally used data store has not the
     expected format<br/>
+    JFW_E_DEFAULT_MODE because of this mode no settings read.
  */
 javaFrameworkError SAL_CALL jfw_getVMParameters(
     rtl_uString *** parParameters,
@@ -585,7 +611,8 @@ javaFrameworkError SAL_CALL jfw_getVMParameters(
    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/>
+   expected format<br/></br>
+   JFW_E_DEFAULT_MODE because of this mode no settings are written.
  */
 javaFrameworkError SAL_CALL jfw_setUserClassPath(rtl_uString * pCP);
 /** provides the value of the current user class path.
@@ -606,6 +633,7 @@ javaFrameworkError SAL_CALL jfw_setUserClassPath(rtl_uString * pCP);
    the internally used data store. <br/>
    JFW_E_FORMAT_STORE the internally used data store has not the
    expected format<br/>
+   JFW_E_DEFAULT_MODE because of this mode no settings read.
  */
 javaFrameworkError SAL_CALL jfw_getUserClassPath(rtl_uString ** ppCP);
 
@@ -634,7 +662,8 @@ javaFrameworkError SAL_CALL jfw_getUserClassPath(rtl_uString ** ppCP);
     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/>
+    expected format</br>
+    JFW_E_DEFAULT_MODE because of this mode no settings are written.
 
     @see jfw_setJRELocations
  */
@@ -664,7 +693,8 @@ javaFrameworkError SAL_CALL jfw_addJRELocation(rtl_uString * sLocation);
     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/>
+    expected format</br>
+    JFW_E_DEFAULT_MODE because of this mode no settings are written.
 
     @see jfw_addJRELocations
  */
@@ -689,7 +719,8 @@ javaFrameworkError SAL_CALL jfw_setJRELocations(
     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/>
+    expected format</br>
+    JFW_E_DEFAULT_MODE because of this mode no settings are read.
  */
 javaFrameworkError SAL_CALL jfw_getJRELocations(
     rtl_uString *** parLocations, sal_Int32 * pSize);
diff --git a/jvmfwk/inc/jvmfwk/vendorplugin.h b/jvmfwk/inc/jvmfwk/vendorplugin.h
index a004f92f5fcf..6139d204a46f 100644
--- a/jvmfwk/inc/jvmfwk/vendorplugin.h
+++ b/jvmfwk/inc/jvmfwk/vendorplugin.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: vendorplugin.h,v $
  *
- *  $Revision: 1.8 $
+ *  $Revision: 1.9 $
  *
- *  last change: $Author: jl $ $Date: 2004-05-18 15:11:57 $
+ *  last change: $Author: jl $ $Date: 2004-05-21 15:07:06 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -74,8 +74,24 @@ extern "C" {
 
 /**
    @file
+   <p>
+   This API shall be implemented if one wants to support a Java Runtime
+   Environment (JRE) of a particular vendor. Because there is currently no
+   specification which rules the structure and location of JRE installations
+   and the format of version strings it is not possible to supply a general
+   implementation for all possible vendors. If an application determines exactly
+   what version a JRE must have then it relies on certain features and bug
+   fixes of that version. Because a version 1.4.2_1 from vendor X may contain
+   different fixes as the same version from vendor Y it is important to see
+   version an vendor as one entity. One without the other does not guarantee
+   the existence of a particular set of features or bug fixes. To keep the
+   API simple it was designed so that an implementation may act on behalf of
+   only ONE vendor. </p>
+   <p>
    Libraries which implement this interface will be dynamically loaded and
-   unloaded. Therefore do not keep global variables.
+   unloaded by the java framework (jvmfwk/framework.h). Therefore they must not
+   keep global variables.
+   </p>
  */
 
 typedef enum
@@ -97,14 +113,15 @@ typedef enum
     The function has parameters which determines which versions of the respective
     JREs are supported. A JRE which does not meet the version requirements will
     be ignored.</p>
-    The JavaInfo structurs returned in <code>parJavaInfo</code> should be ordered
+    The JavaInfo structures returned in <code>parJavaInfo</code> should be ordered
     according to their version. The one, representing a JRE with the highest
     version should be the first in the array. </p>
     <p>
-    The function allocates memory for an array and all the the JavaInfo objects returned
+    The function allocates memory for an array and all the JavaInfo objects returned
     in <code>parJavaInfo</code>. The caller must free each JavaInfo object by calling
-    <code>jfw_freeJavaInfo</code>. The array is to be freed by rtl_freeMemory.
-    In case an error occurred parJavaInfo does not to be freed.
+    <code>jfw_freeJavaInfo</code> (#include "jvmfwk/framework.h"). The array is to be
+    freed by rtl_freeMemory.
+    In case an error occurred <code>parJavaInfo</code> need not be freed.
     </p>
 
     @param sMinVersion
@@ -124,10 +141,14 @@ typedef enum
        <code>parJavaInfo</code>.
 
     @return
-    JFW_PLUGIN_E_NONE </br>
-    JFW_PLUGIN_E_ERROR </br>
-    JFW_PLUGIN_E_INVALID_ARG </br>
-    JFW_PLUGIN_E_WRONG_VERSION_FORMAT
+    JFW_PLUGIN_E_NONE the function ran successfully.</br>
+    JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
+    JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
+    <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
+    is NULL.</br>
+    JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in
+    <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
+    version strings.
  */
 javaPluginError jfw_plugin_getAllJavaInfos(
     rtl_uString *sMinVersion,
@@ -137,39 +158,99 @@ javaPluginError jfw_plugin_getAllJavaInfos(
     JavaInfo*** parJavaInfo,
     sal_Int32 *nSizeJavaInfo);
 
-/**
+/** obtains information for a JRE at a given location.
+   <p>
+   If the given location belongs to a JRE whoose vendor is supported by
+   this library and the JRE has a version which meets the requirements as
+   specified by <code>sMinVersion, sMaxVersion, arExcludeList</code> then
+   this function returns a JavaInfo object for this JRE.</p>
+
+   @param sLocation
+       [in] a file URL to the directory of the JRE.
+   @param sMinVersion
+       [in] represents the minimum version of a JRE. It can be NULL.
+   @param sMaxVersion
+       [in] represents the maximum version of a JRE. It can be NULL.
+   @param arExcludeList
+       [in] contains a list of &quot;bad&quot; versions. JREs which have one of these
+        versions must not be returned by this function. It can be NULL.
+   @param nSizeExcludeList
+       [in] the number of version strings contained in <code>arExcludeList</code>.
+   @param ppInfo
+       [out] if the function runs successfully then <code>ppInfo</code> contains
+        on return a pointer to a <code>JavaInfo</code> object.
+
    @return
-   JFW_PLUGIN_E_NONE
-    JFW_PLUGIN_E_ERROR
-    JFW_PLUGIN_E_INVALID_ARG
-    JFW_PLUGIN_E_WRONG_VERSION_FORMAT
-    JFW_PLUGIN_E_FAILED_VERSION
-    JFW_PLUGIN_E_NO_JRE
+   JFW_PLUGIN_E_NONE the function ran successfully.</br>
+   JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
+   JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
+    <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
+    is NULL.</br>
+   JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in
+    <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
+    version strings.
+   JFW_PLUGIN_E_FAILED_VERSION there is a JRE at the given location but it does not
+   meet the version requirements.
+   JFW_PLUGIN_E_NO_JRE no JRE could be detected at the given location. However, that
+   does not mean necessarily that there is no JRE. There could be a JRE but it has
+   a vendor which is not supported by this API implementation.
  */
 javaPluginError jfw_plugin_getJavaInfoByPath(
-    rtl_uString *path,
+    rtl_uString *sLocation,
     rtl_uString *sMinVersion,
     rtl_uString *sMaxVersion,
     rtl_uString * *arExcludeList,
-    sal_Int32  nLenList,
+    sal_Int32  nSizeExcludeList,
     JavaInfo ** ppInfo);
 
 /** starts a Java Virtual Machine.
     <p>
-    The function shall ensure, that the VM does not abort the process
+    The caller should provide all essential JavaVMOptions, such as the
+    class path (-Djava.class.path=xxx). It is assumed that the caller
+    knows what JRE is used. Hence the implementation does not need to check
+    the options for validity. If a user configured the application to
+    use specific options, such as -X..., then it is in his responsibility to
+    ensure that the application works properly. The function may add or modify
+    properties. For example, it may add to the class path property.
+    <p>
+    The function must ensure, that the VM does not abort the process
     during instantiation.</p>
-    @param
-    JFW_PLUGIN_E_NONE,
-    JFW_PLUGIN_E_ERROR,
-    JFW_PLUGIN_E_WRONG_VENDOR
-    JFW_PLUGIN_E_INVALID_ARG,
-    JFW_PLUGIN_E_VM_CREATION_FAILED
+    <p>
+    The function receives a <code>JavaInfo</code> object that was created
+    by the functions <code>jfw_plugin_getJavaInfoByPath</code> or
+    <code>jfw_plugin_getAllJavaInfos</code> from the same library. This can be
+    guaranteed if an application uses exactly one library for one vendor.
+    Therefore the functions which create the <code>JavaInfo</code> can store all
+    necessary information which are needed for starting the VM into that
+    structure. </p>
+
+    @param pInfo
+        [in] the JavaInfo object with information about the JRE.
+    @param arOptions
+        [in] the options which are passed into the JNI_CreateJavaVM function.
+        Can be NULL.
+    @param nSizeOptions
+        [in] the number of elements in <code>arOptions</code>.
+    @param ppVM
+        [out] the JavaVM pointer of the created VM.
+    @param ppEnv
+        [out] the JNIEnv pointer of the created VM.
 
+    @return
+    JFW_PLUGIN_E_NONE the function ran successfully.</br>
+    JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
+    JFW_PLUGIN_E_WRONG_VENDOR the <code>JavaInfo</code> object was not created
+    in by this library.</br>
+    JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
+    <code>pInfo</code> or , <code>ppVM</code> or <code>ppEnv</code> are NULL.
+    </br>
+    JFW_PLUGIN_E_VM_CREATION_FAILED a VM could not be created. The error was caused
+    by the JRE.
  */
 javaPluginError jfw_plugin_startJavaVirtualMachine(
-    const JavaInfo *info,
-    const JavaVMOption* options,
-    sal_Int32 cOptions,
+    const JavaInfo *pInfo,
+    const JavaVMOption *arOptions,
+    sal_Int32 nSizeOptions,
     JavaVM ** ppVM,
     JNIEnv ** ppEnv);