/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* * This file is part of the LibreOffice project. * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. * * This file incorporates work covered by the following license notice: * * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed * with this work for additional information regarding copyright * ownership. The ASF licenses this file to you under the Apache * License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0 . */ /** @HTML */ #ifndef INCLUDED_JVMFWK_VENDORPLUGIN_H #define INCLUDED_JVMFWK_VENDORPLUGIN_H #include "jvmfwkplugindllapi.h" #include "jvmfwk/framework.h" #include "rtl/ustring.h" #include "jni.h" #ifdef __cplusplus extern "C" { #endif /** @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. An implementation of this API may support multiple vendors.

Libraries which implement this interface will be dynamically loaded and unloaded by the java framework (jvmfwk/framework.h). Therefore they must not keep global variables.

*/ typedef enum { 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_WRONG_VENDOR, JFW_PLUGIN_E_VM_CREATION_FAILED } javaPluginError; /** obtains information about installations of Java Runtime Environments (JREs).

The function gathers information about available JREs which have the same vendor as determined by the sVendor parameter. Only information about those JREs which match the version requirements are returned. These requirements are specified by the parameters sMinVersion, sMaxVersion and arExcludeList.

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 JavaInfo objects returned in parJavaInfo. The caller must free each JavaInfo object by calling 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 sVendor [in] only JREs from this vendor are examined. This parameter always contains a vendor string. That is, the string it is not empty. @param sMinVersion [in] represents the minimum version of a JRE. The string can be empty but a null pointer is not allowed. @param sMaxVersion [in] represents the maximum version of a JRE. The string can be empty but a null pointer is not allowed. @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 parJavaInfo [out] if the function runs successfully then parJavaInfo contains on return an array of pointers to JavaInfo objects. @param nSizeJavaInfo [out] the number of JavaInfo pointers contained in parJavaInfo. @return 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 or NULL pointer were passed for at least on of the strings.
JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in sMinVersion,sMaxVersion,arExcludeList are not recognized as valid version strings. */ JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_getAllJavaInfos( rtl_uString *sVendor, rtl_uString *sMinVersion, rtl_uString *sMaxVersion, rtl_uString * * arExcludeList, sal_Int32 nSizeExcludeList, JavaInfo*** parJavaInfo, sal_Int32 *nSizeJavaInfo); /** obtains information for a JRE at a given location.

If the given location belongs to a JRE whoose vendor matches the sVendor argument and the JRE has a version which meets the requirements as specified by sMinVersion, sMaxVersion, arExcludeList then this function shall return a JavaInfo object for this JRE if this implementation supports this vendor.

@param sLocation [in] a file URL to the directory of the JRE. @param sVendor [in] a name of a vendor. This parameter always contains a vendor string. That is, the string it is not empty. @param sMinVersion [in] represents the minimum version of a JRE. @param sMaxVersion [in] represents the maximum version of a JRE. @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 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, NULL pointer were passed for at least on of the strings, sLocation is an empty string.
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. */ JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_getJavaInfoByPath( rtl_uString *sLocation, rtl_uString *sVendor, rtl_uString *sMinVersion, rtl_uString *sMaxVersion, rtl_uString * *arExcludeList, sal_Int32 nSizeExcludeList, JavaInfo ** ppInfo); /** starts a Java Virtual Machine.

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.

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 and the VM cannot be started.
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. */ JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_startJavaVirtualMachine( const JavaInfo *pInfo, const JavaVMOption *arOptions, sal_Int32 nSizeOptions, JavaVM ** ppVM, JNIEnv ** ppEnv); /** checks if the installation of the jre still exists. This function checks if the JRE described by pInfo still exists. The check must be very quick because it is called by javaldx (Linux, Solaris) at start up. @param pInfo [in] the JavaInfo object with information about the JRE. @param pp_exist [out] the parameter is set to either sal_True or sal_False. The value is only valid if the function returns JFW_E_NONE. @return JFW_PLUGIN_E_NONE the function ran successfully.
JFW_PLUGIN_E_ERROR an error occurred during execution.
JFW_PLUGIN_E_INVALID_ARG pInfo contains invalid data
*/ JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_existJRE(const JavaInfo *pInfo, sal_Bool *exist); #ifdef __cplusplus } #endif #endif /* vim:set shiftwidth=4 softtabstop=4 expandtab: */