From dfe71dabee5e3ff50f1903792f9c3b86613531da Mon Sep 17 00:00:00 2001
From: Joachim Lingner
+ 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
+ In "default mode" the framework uses the environment variables
+
+ 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.
+ jfw_setSelectedJRE
or jfw_findAndSelectJRE
must have
+ run successfully.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.
+
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_HOME
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.
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
+
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.
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.
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.
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