From dfe71dabee5e3ff50f1903792f9c3b86613531da Mon Sep 17 00:00:00 2001 From: Joachim Lingner Date: Fri, 21 May 2004 14:07:06 +0000 Subject: #i20052# --- jvmfwk/inc/jvmfwk/framework.h | 49 +++++++++++--- jvmfwk/inc/jvmfwk/vendorplugin.h | 141 ++++++++++++++++++++++++++++++--------- 2 files changed, 151 insertions(+), 39 deletions(-) (limited to 'jvmfwk/inc') 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 +

+ 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 /share/config. A Java Virtual Machine (JVM) + can only be created if a JRE has been selected. That is either + jfw_setSelectedJRE or jfw_findAndSelectJRE must have + run successfully.

+

+ In "default mode" the framework uses the environment variables + JAVA_HOME and CLASSPATH 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. +

+ 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
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. + JFW_E_NO_JAVA_FOUND no JRE was found that meets the requirements.
+ 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.
JFW_E_VM_CREATION_FAILED the creation of the JVM failed. The creation is performed by a plug-in library and not by this API. + JFW_E_FAILED_VERSION the "Default Mode" is active. The JRE determined by + JAVA_HOMEdoes not meet the version requirements. */ 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.
JFW_E_FORMAT_STORE the internally used data store has not the expected format
+ 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
JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no JRE has been selected afterwards.
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the expected format
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the expected format
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the expected format
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the expected format
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the - expected format
+ expected format

+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the expected format
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the - expected format
+ expected format
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the - expected format
+ expected format
+ 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.
JFW_E_FORMAT_STORE the internally used data store has not the - expected format
+ expected format
+ 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 +

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

+

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

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

- The JavaInfo structurs returned in parJavaInfo should be ordered + The JavaInfo structures returned in parJavaInfo should be ordered according to their version. The one, representing a JRE with the highest version should be the first in the array.

- 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 parJavaInfo. The caller must free each JavaInfo object by calling - jfw_freeJavaInfo. The array is to be freed by rtl_freeMemory. - In case an error occurred parJavaInfo does not to be freed. + jfw_freeJavaInfo (#include "jvmfwk/framework.h"). The array is to be + freed by rtl_freeMemory. + In case an error occurred parJavaInfo need not be freed.

@param sMinVersion @@ -124,10 +141,14 @@ typedef enum parJavaInfo. @return - JFW_PLUGIN_E_NONE
- JFW_PLUGIN_E_ERROR
- JFW_PLUGIN_E_INVALID_ARG
- JFW_PLUGIN_E_WRONG_VERSION_FORMAT + JFW_PLUGIN_E_NONE the function ran successfully.
+ JFW_PLUGIN_E_ERROR an error occurred during execution.
+ JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example + nSizeExcludeList is greater null but arExcludeList + is NULL.
+ JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in + sMinVersion,sMaxVersion,arExcludeList 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. +

+ 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 sMinVersion, sMaxVersion, arExcludeList then + this function returns a JavaInfo object for this JRE.

+ + @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 arExcludeList. + @param ppInfo + [out] if the function runs successfully then ppInfo contains + on return a pointer to a JavaInfo 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.
+ JFW_PLUGIN_E_ERROR an error occurred during execution.
+ JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example + nSizeExcludeList is greater null but arExcludeList + is NULL.
+ JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in + sMinVersion,sMaxVersion,arExcludeList 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.

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

+ The function must ensure, that the VM does not abort the process during instantiation.

- @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 +

+ The function receives a JavaInfo object that was created + by the functions jfw_plugin_getJavaInfoByPath or + jfw_plugin_getAllJavaInfos from the same library. This can be + guaranteed if an application uses exactly one library for one vendor. + Therefore the functions which create the JavaInfo can store all + necessary information which are needed for starting the VM into that + structure.

+ + @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 arOptions. + @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.
+ JFW_PLUGIN_E_ERROR an error occurred during execution.
+ JFW_PLUGIN_E_WRONG_VENDOR the JavaInfo object was not created + in by this library.
+ JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example + pInfo or , ppVM or ppEnv are NULL. +
+ 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); -- cgit