diff options
author | Joachim Lingner <jl@openoffice.org> | 2004-05-21 14:07:06 +0000 |
---|---|---|
committer | Joachim Lingner <jl@openoffice.org> | 2004-05-21 14:07:06 +0000 |
commit | dfe71dabee5e3ff50f1903792f9c3b86613531da (patch) | |
tree | d837a585bd4eccb60414514e3589677ed6c84c49 /jvmfwk | |
parent | #i20052# (diff) | |
download | core-dfe71dabee5e3ff50f1903792f9c3b86613531da.tar.gz core-dfe71dabee5e3ff50f1903792f9c3b86613531da.zip |
#i20052#
Diffstat (limited to 'jvmfwk')
-rw-r--r-- | jvmfwk/inc/jvmfwk/framework.h | 49 | ||||
-rw-r--r-- | jvmfwk/inc/jvmfwk/vendorplugin.h | 141 |
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 "default mode" 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 "Default Mode" 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 "bad" 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); |