From 3ca762ec3e40f168e56bec3bb480f5240a986cf8 Mon Sep 17 00:00:00 2001 From: Joachim Lingner Date: Thu, 22 Apr 2004 11:52:40 +0000 Subject: #i20052# --- jvmfwk/inc/jvmfwk/framework.h | 688 ++++++++++++++++++++++++++++----------- jvmfwk/inc/jvmfwk/vendorplugin.h | 8 +- 2 files changed, 495 insertions(+), 201 deletions(-) (limited to 'jvmfwk/inc') 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. +

+ The flag is used with JavaInfo::nFeatures.

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

Therefore, when a Java is selected in OO then the office must be + restarted, so that the changes can take effect.

*/ #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). +

+ 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 rtl_allocateMemory (rtl/alloc.h). Therefore, the memory must + be freed by rtl_freeMemory. Also the contained members must be + freed particularly. + For convenience this API provides the function jfw_freeJavaInfo + which frees the objects properly.

+ */ struct _JavaInfo { + /** contains the vendor. + +

string must be the same as the one obtained from the + Java system property java.vendor. +

+ */ rtl_uString *sVendor; + /** contains the file URL to the installation directory. + */ rtl_uString *sLocation; + /** contains the version of this Java distribution. + +

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

+ */ rtl_uString *sVersion; + /** indicates supported special features. + +

For example, JFW_FEATURE_ACCESSBRIDGE indicates that + assistive technology tools are supported.

+ */ sal_uInt64 nFeatures; + /** indicates requirments for running the java runtime. + +

For example, it may be necessary to prepare the environment before + the runtime is created. That could mean, setting the + LD_LIBRARY_PATH + when nRequirements contains the flag + JFW_REQUIRE_NEEDRESTART

+ */ sal_uInt64 nRequirements; + /** contains data needed for the creation of the java runtime. + +

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.

+ */ sal_Sequence * arVendorData; }; typedef struct _JavaInfo JavaInfo; -/** frees the memory of a JavaInfo object. +/** frees the memory of a JavaInfo 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 JavaInfo objects for equality. + +

Two JavaInfo objects are said to be equal if the contained + members of the first JavaInfo are equal to their counterparts + in the second JavaInfo object. The equality of the + rtl_uString members is determined + by the respective comparison function (see + rtl::OUString::equals). + Similiarly the equality of the sal_Sequence is + also determined by a comparison + function (see rtl::ByteSequence::operator ==).

+

+ Both argument pointers must be valid.

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

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.

+

+ By determining if a VM is running, the user can be presented a message, + that the changed setting may not be effective immediately.

+ + @param bRunning + [out] sal_True - a VM is running.
+ sal_False - no VM is running. @return - JFW_E_NONE - JFW_E_INVALID_ARG; + JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG the parameter bRunning 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. +

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.

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

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

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

+ 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 jfw_getSelectedJRE returns this + information.

- The new - settings are effective immediatly. That is, jfw_useNewSettings does - not need to be called.

+ 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 + JavaInfo objects, + which are provided by the getJavaInfo functions of the plug-ins, are + examined for a suitable JRE. That is, the JavaInfo objects + from the list + obtained from the first plug-in, are examined. If no JavaInfo + object has the flag + JFW_FEATURE_ACCESSBRIDGE in the member nFeatures + then the + next plug-in is used to obtain a list of JavaInfo objects. + This goes on until a JavaInfo object was found which + represents a suitable JRE. Or neither plug-in provided such a + JavaInfo object. In that case the first + JavaInfo object from the first plug-in is used to determine + the JRE which is to be used.

- //ToDo algorith for selecting a JRE + If there is no need for the support of assistive technology tools then + the first JavaInfo 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.

@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 JavaInfo pointer, representing the selected JRE. + The caller has to free it by calling jfw_freeJavaInfo. The + JavaInfo is for informational purposes only. It is not + necessary to call jfw_setSelectedJRE afterwards.
+ ppInfocan be NULL. If *ppInfo is not null, then it is + overwritten, without attempting to free *ppInfo. @return - JFW_E_ERROR - JFW_E_CONFIGREADWRITE An error occurred while reading or writing the - configuration files.
- JFW_E_FORMAT_STORE
- JFW_E_NOPLUGIN A plug-in library could not be found.
- JFW_E_NOJAVAFOUND No Java was found that meets the requirements. + JFW_E_NONE function ran successfully.
+ JFW_E_ERROR an error occurred.
+ 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
+ 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. */ -javaFrameworkError SAL_CALL jfw_findAndSelectJava(JavaInfo **pInfo); +javaFrameworkError SAL_CALL jfw_findAndSelectJRE(JavaInfo **pInfo); + +/** provides information about all availabe JRE installations. + +

The function determines dynamically what JREs are available. It uses + the plug-in libraries to provide lists of available JavaInfo + objects where each object represents a JRE (see vendorplugin.h, + getAllJavaInfos). It also uses a list of paths, which have been registered + by jfw_addJRELocation or jfw_setJRELocations. + It is checked if the path still contains a valid JRE and if so the respective + JavaInfo object will be appended to the array unless there is + already an equal object.

+ + @param parInfo + [out] on returns it contains a pointer to an array of JavaInfo + pointers. + The caller must free the array with rtl_freeMemory and each + element of the array must be freed with jfw_freeJavaInfo. + @param pSize + [out] on return contains the size of array returned in parInfo. -/** provides information about all availabe Java installations. -

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

- */ + @return + JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG at least on of the parameters was NULL
+ JFW_E_ERROR an error occurred.
+ 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
+ JFW_E_NO_PLUGIN a plug-in library could not be found.
+*/ 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. + +

If the path belongs to a JRE installation then it returns the + respective JavaInfo object. The function uses the + getJavaInfoByPath function of the plug-ins to obtain the + JavaInfo object. Only if the JRE found at the specified location + meets the version requirements as specified in the javavendors.xml file a + JavaInfo object is returned.

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

+ The functions only checks if a JRE exists but does not modify any settings. + To make the found JRE the "selected JRE" one has + to call jfw_setSelectedJRE.

+ @param pPath - [in] + [in] a file URL to a directory. @param pInfo - [out] + [out] the JavaInfo object which represents a JRE found at the + location specified by pPath @return - JFW_E_NONE - JFW_E_ERROR - JFW_E_INVALID_ARG - JFW_E_NOT_RECOGNIZED - + JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG at least on of the parameters was NULL
+ JFW_E_ERROR an error occurred.
+ 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
+ JFW_E_NO_PLUGIN a plug-in library could not be found.
+ JFW_E_NOT_RECOGNIZED neither plug-in library could detect a JRE.
+ 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). + +

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 "selected Java" 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.

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

+ The function ultimately calls startJavaVirtualMachine from + the plug-in library.

- If there are neither user or global settings which contain data about - a JRE which is to be used, then the function returns - JFW_E_NO_SELECT.

+ The arOptions + 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 + java.lang.System.getProperties. 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.
+ 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 + jfw_setUserClassPath.

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

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

@param arOptions - Can be NULL + [in] the array containing additional start arguments or NULL. + @param nSize + [in] the size of the array arOptions. + @param ppVM + [out] the JavaVM pointer. + @param ppEnv + [out] the JNIenv 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.
+ JFW_E_NONE function ran successfully.
+ JFW_E_INVALID_ARG ppVM, ppEnv are NULL or + arOptions was NULL but nSize was greater 0.
+ JFW_E_ERROR an error occurred.
+ 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
+ JFW_E_NO_PLUGIN the plug-in library responsible for creating the VM + could not be found.
JFW_E_JAVA_DISABLED the use of Java is currently disabled.
- JFW_E_NO_SELECT javasettings.xml does not contain data about - JFW_E_RUNNIN_GJVM - a JRE which is to be used.
+ JFW_E_NO_SELECT there is no JRE selected yet.
+ JFW_E_RUNNIN_JVM there is already a VM running.
JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no - Java has been selected afterwards.
- JFW_E_NEED_RESTART In the current process a different Java has been selected + JRE has been selected afterwards.
+ 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.
+ process. Therefore the new JRE may not be used until the office was restarted.
*/ -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. -

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

-

- If pInfo is NULL then the meaning is that no java will be selected. jfw_startJava - will later return JFW_E_NO_SELECT.

+/** determines the JRE that is to be used. + +

When calling jfw_startVM then a VM is startet from + the JRE that is determined by this function.
+ It is not verified if the JRE represented by the JavaInfo + argument meets the requirements as specified by the javavendors.xml file. + However, usually one obtains the JavaInfo object from the + functions jfw_findAllJREs or jfw_getJavaInfoByPath, + which do verify the JREs and pass out only JavaInfo objects + which comply with the version requirements.

- This setting will only become effective after calling jfw_applyChanges. -

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

+ If pInfo is NULL then the meaning is that no JRE will be + selected. jfw_startVM will then return + JFW_E_NO_SELECT.

@param pInfo - [in] pointer to JavaInfo structure, containing data about Java - installation. The caller must still free pInfo. + [in] pointer to JavaInfo structure, containing data about a + JRE. The caller must still free pInfo. + + @return + JFW_E_NONE function ran successfully.
+ JFW_E_ERROR An error occurred.
+ 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
*/ -javaFrameworkError SAL_CALL jfw_setSelectedJava(JavaInfo const *pInfo); +javaFrameworkError SAL_CALL jfw_setSelectedJRE(JavaInfo const *pInfo); -/** Provides information about the currently selected Java installation. -

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

+/** provides information about the JRE that is to be used. +

If the value of the element 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 JFW_E_INVALID_SETTINGS. 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.

- @param pInfo [out] + @param ppInfo + [out] on return it contains a pointer to a JavaInfo object + that represents the currently selected JRE. When *ppInfo is not + NULL then the function overwrites the pointer. It is not attempted to free + the pointer. @return - JFW_E_NONE on success
- - 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.
- 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.
+ JFW_E_INVALIDARG ppInfo is a NULL.
+ 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
+ + JFW_E_NO_SELECT there is no Java selected yet.
+ JFW_E_INVALID_SETTINGS the javavendors.xml has been changed and no + JRE has been selected afterwards.
*/ -javaFrameworkError SAL_CALL jfw_getSelectedJava(JavaInfo **pInfo); +javaFrameworkError SAL_CALL jfw_getSelectedJRE(JavaInfo **ppInfo); -/** sets the the "enabled" parameter. -

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

-

- The new value comes only into effect after jfw_applyChanges is - called.

+/** determines if Java can be used. + +

If bEnabled is sal_False then a call + to jfw_startVM will result in an error with the errorcode + JFW_E_JAVA_DISABLED

+ + @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.
+ JFW_E_ERROR An error occurred.
+ 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
*/ javaFrameworkError SAL_CALL jfw_setEnabled(sal_Bool bEnabled); -/** determines the value of the Java setting "enabled". -

- The returned value in pbEnabled has been taken from - a snapshot of the internal data. The value may change later on.

-

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

-

- If the function jfw_setEnabled has never been called before - by the current user, then the value returned in pbEnabled - 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.
- JFW_E_ERROR An error occurred.
- JFW_E_CONFIG_READWRITE Error during access of internal data store.
- JFW_E_FORMAT_STORE The structure of the internal data store is not - as expected.
- JFW_E_INVALIDARG pbEnabled is NULL
+ @return + JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG pbEnabled is NULL
+ JFW_E_ERROR An error occurred.
+ 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
*/ 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. +

The strings must be exactly as they are passed on the command line. + For example, one could pass
+ -Xdebug
+ -Xrunjdw:transport=dt_socket,server=y,address=8000
+ in order to enable debugging support. +

+ + @param arParameters + [in] contains the arguments. It can be NULL if nSize is 0. + @param nSize + [i] the size of arArgs @return - JFW_E_INVALIDARG arOptions is NULL and nSize is not 0 + JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG arArgs is NULL and nSize is not 0 + JFW_E_ERROR An error occurred.
+ 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
*/ 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.
+/** obtains the currently used start parameters. + +

The caller needs to free the returned array with + rtl_freeMemory. The contained strings must be released with + rtl_uString_release. +

+ + @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 + parParameters + + @return + JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG parParameters or pSize are NULL
JFW_E_ERROR An error occurred.
- JFW_E_CONFIG_READWRITE Error during access of internal data store.
- JFW_E_FORMAT_STORE The structure of the internal data store is not - as expected.
- JFW_E_INVALIDARG parOptions or pSize are NULL
+ 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
*/ 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. + +

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.

+ + @param pCP + [in] the user class path. + + @return + JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG pCP is NULL.
+ JFW_E_ERROR An error occurred.
+ 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
*/ 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. + +

The function returns an empty string if no user class path is set. +

+ + @param ppCP + [out] contains the user class path on return. If *ppCP was + not NULL then the value is overwritten. No attempt at freeing that string + is made. + + @return + JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG ppCP is NULL.
+ JFW_E_ERROR An error occurred.
+ 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
*/ javaFrameworkError SAL_CALL jfw_getUserClassPath(rtl_uString ** ppCP); /** saves the location of a JRE. -

- When jfw_findAllJREs is called then the paths added by this + +

When jfw_findAllJREs 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. -

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

- A validation if sLocation points to a JRE is not - performed. To do that one has to use jfw_getJavaInfoByPath. + A validation if sLocation points to a JRE is not + performed. To do that one has to use jfw_getJavaInfoByPath.

- Adding a path that is already stored causes no error. + Adding a path that is already stored causes no error.

+ @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.
+ JFW_E_INVALIDARG sLocation is NULL.
+ JFW_E_ERROR An error occurred.
+ 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
+ + @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. +

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.

+ contains strings which are the same then only one is stored.

- If arLocations is NULL or arLocations has the length null + If arLocations is NULL or it has the length null (nSize = 0) then all previously stored paths are deleted. Otherwise, the old values are overwritten.

+ + @param arLocations + [in] array of paths to locations of JREs. + + @param nSize + [in] the size of the array arLocations + + @return + JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG arLocation is NULL and nSize is not null.
+ JFW_E_ERROR An error occurred.
+ 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
+ + @see jfw_addJRELocations */ javaFrameworkError SAL_CALL jfw_setJRELocations( rtl_uString ** arLocations, sal_Int32 nSize); /** obtains an array containing paths to JRE installations. +

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 jfw_getJavaInfoByPath to check this.

+ + @param parLocations + [out] on return it contains the array of paths. + @param pSize + [out] on return it contains the size of the array parLocations. + + @return + JFW_E_NONE function ran successfully.
+ JFW_E_INVALIDARG parLocation is NULL or pSize is NULL.
+ JFW_E_ERROR An error occurred.
+ 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
*/ javaFrameworkError SAL_CALL jfw_getJRELocations( rtl_uString *** parLocations, sal_Int32 * pSize); - +/** locks this API so that it cannot be used by other threads. + +

If a different thread called this function before then the + current call is blocked until the other thread has called + jfw_unlock(). 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 jfw_lock + should be called. That is, jfw_startVM which uses the + settings cannot be called before all settings have be made.

+

+ The only functions which are not effected by jfw_lock are + jfw_freeJavaInfo and jfw_areEqualJavaInfo. + */ void SAL_CALL jfw_lock(); +/** unlocks this API. + +

This function is called after jfw_lock. It allows other + threads to use this API concurrently.

+*/ 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( -- cgit