jvmfwk/inc/vendorplugin.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 /** @HTML */
  21 #ifndef INCLUDED_JVMFWK_INC_VENDORPLUGIN_HXX
  22 #define INCLUDED_JVMFWK_INC_VENDORPLUGIN_HXX
  23
  24 #include <jvmfwk/framework.hxx>
  25 #include <rtl/ref.hxx>
  26 #include <rtl/ustring.h>
  27 #include "jni.h"
  28 #include <vector>
  29 #include <utility>
  30 #include "../source/elements.hxx"
  31 #include <vendorbase.hxx>
  32
  33 /**
  34    @file
  35    <p>
  36    This API shall be implemented if one wants to support a Java Runtime
  37    Environment (JRE) of a particular vendor. Because there is currently no
  38    specification which rules the structure and location of JRE installations
  39    and the format of version strings it is not possible to supply a general
  40    implementation for all possible vendors. If an application determines exactly
  41    what version a JRE must have then it relies on certain features and bug
  42    fixes of that version. Because a version 1.4.2_1 from vendor X may contain
  43    different fixes as the same version from vendor Y it is important to see
  44    version and vendor as one entity. One without the other does not guarantee
  45    the existence of a particular set of features or bug fixes. An implementation
  46    of this API may support multiple vendors. </p>
  47  */
  48
  49 enum class javaPluginError
  50 {
  51     NONE,
  52     Error,
  53     InvalidArg,
  54     WrongVersionFormat,
  55     FailedVersion,
  56     NoJre,
  57     WrongVendor,
  58     VmCreationFailed
  59 };
  60
  61
  62 /** obtains information about installations of Java Runtime Environments (JREs).
  63
  64     <p>The function gathers information about available JREs which have the same
  65     vendor as determined by the <code>sVendor</code> parameter. Only information
  66     about those JREs which match the version requirements are returned. These
  67     requirements are specified by the parameters <code>sMinVersion</code>,
  68     <code>sMaxVersion</code> and <code>arExcludeList</code>.
  69     </p>
  70     <p>
  71     The JavaInfo structures returned in <code>parJavaInfo</code> should be ordered
  72     according to their version. The one, representing a JRE with the highest
  73     version should be the first in the array. </p>
  74     <p>
  75     The function allocates memory for an array and all the JavaInfo objects returned
  76     in <code>parJavaInfo</code>. The caller must delete each JavaInfo object.
  77     The array is to be
  78     freed by rtl_freeMemory.
  79     In case an error occurred <code>parJavaInfo</code> need not be freed.
  80     </p>
  81     @param sVendor
  82         [in] only JREs from this vendor are examined. This parameter always contains
  83         a vendor string. That is, the string it is not empty.
  84     @param sMinVersion
  85         [in] represents the minimum version of a JRE. The string can be empty.
  86     @param sMaxVersion
  87         [in] represents the maximum version of a JRE. The string can be empty.
  88     @param arExcludeList
  89         [in] contains a list of &quot;bad&quot; versions. JREs which have one of these
  90         versions must not be returned by this function. It can be NULL.
  91     @param nSizeExcludeList
  92         [in] the number of version strings contained in <code>arExcludeList</code>.
  93     @param parJavaInfo
  94         [out] if the function runs successfully then <code>parJavaInfo</code> contains
  95         on return an array of pointers to <code>JavaInfo</code> objects.
  96     @param nSizeJavaInfo
  97        [out] the number of <code>JavaInfo</code> pointers contained in
  98        <code>parJavaInfo</code>.
  99
 100     @return
 101     javaPluginError::NONE the function ran successfully.</br>
 102     javaPluginError::Error an error occurred during execution.</br>
 103     javaPluginError::InvalidArg an argument was not valid. For example
 104     <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
 105     is NULL or NULL pointer were passed for at least on of the strings.</br>
 106     javaPluginError::WrongVersionFormat the version strings in
 107     <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
 108     version strings.
 109  */
 110 javaPluginError jfw_plugin_getAllJavaInfos(
 111     bool checkJavaHomeAndPath,
 112     OUString const& sVendor,
 113     OUString const& sMinVersion,
 114     OUString const& sMaxVersion,
 115     rtl_uString * * arExcludeList,
 116     sal_Int32  nSizeExcludeList,
 117     JavaInfo*** parJavaInfo,
 118     sal_Int32 *nSizeJavaInfo,
 119     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 120
 121 /** obtains information for a JRE at a given location.
 122
 123    <p>If the given location belongs to a JRE whoose vendor matches the
 124    sVendor argument and the JRE has a version which meets the requirements as
 125    specified by <code>sMinVersion, sMaxVersion, arExcludeList</code> then
 126    this function shall return a JavaInfo object for this JRE if this implementation
 127    supports this vendor.</p>
 128
 129    @param sLocation
 130        [in] a file URL to the directory of the JRE.
 131    @param sVendor
 132       [in] a name of a vendor. This parameter always contains
 133         a vendor string. That is, the string it is not empty.
 134    @param sMinVersion
 135        [in] represents the minimum version of a JRE.
 136    @param sMaxVersion
 137        [in] represents the maximum version of a JRE.
 138    @param arExcludeList
 139        [in] contains a list of &quot;bad&quot; versions. JREs which have one of these
 140         versions must not be returned by this function. It can be NULL.
 141    @param nSizeExcludeList
 142        [in] the number of version strings contained in <code>arExcludeList</code>.
 143    @param ppInfo
 144        [out] if the function runs successfully then <code>ppInfo</code> contains
 145         on return a pointer to a <code>JavaInfo</code> object.
 146
 147    @return
 148    javaPluginError::NONE the function ran successfully.</br>
 149    javaPluginError::Error an error occurred during execution.</br>
 150    javaPluginError::InvalidArg an argument was not valid. For example
 151     <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
 152     is NULL, NULL pointer were passed for at least on of the strings, sLocation
 153     is an empty string.</br>
 154    javaPluginError::WrongVersionFormat the version strings in
 155     <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
 156     version strings.
 157    javaPluginError::FailedVersion there is a JRE at the given location but it does not
 158    meet the version requirements.
 159    javaPluginError::NoJre no JRE could be detected at the given location. However, that
 160    does not mean necessarily that there is no JRE. There could be a JRE but it has
 161    a vendor which is not supported by this API implementation.
 162  */
 163 javaPluginError jfw_plugin_getJavaInfoByPath(
 164     OUString const& sLocation,
 165     OUString const& sVendor,
 166     OUString const& sMinVersion,
 167     OUString const& sMaxVersion,
 168     rtl_uString * *arExcludeList,
 169     sal_Int32  nSizeExcludeList,
 170     JavaInfo ** ppInfo);
 171
 172
 173 /** obtains information for a JRE referenced by the JAVA_HOME environment variable.
 174
 175    <p>If the JAVA_HOME environment variable is set and points to a JRE whoose vendor
 176    matches the requirements given by vecVendorInfos (i.e. it has a vendor that is
 177    given in vecVendorInfos and the version requirements for the vendor are met),
 178    then this function shall return a JavaInfo object for this JRE.</p>
 179
 180    @param vecVendorInfos
 181        [in] vector specifying the vendor and version requirements that the JRE must fulfill.
 182        The vector contains pairs of vendors and the respective version requirements
 183        for those vendors. The JRE must support the requirements of one given pair in the
 184        vector (i.e. it must be of one of the vendors and meet the version requirements
 185        - minVersion, maxVersion, excludeVersions - for that specific vendor).
 186    @param ppInfo
 187        [out] if the JAVA_HOME environment variable is set and points to a suitable
 188        JRE, then <code>ppInfo</code> contains
 189         on return a pointer to its <code>JavaInfo</code> object.
 190
 191    @return
 192    javaPluginError::NONE the function ran successfully.</br>
 193    javaPluginError::InvalidArg an argument was not valid, for example
 194     <code>ppInfo</code> is an invalid pointer.
 195    javaPluginError::NoJre no suitable JRE could be detected at the given location. However, that
 196    does not mean necessarily that there is no JRE. There could be a JRE but it has
 197    a vendor which is not supported by this API implementation or it does not
 198    meet the version requirements.
 199  */
 200 javaPluginError jfw_plugin_getJavaInfoFromJavaHome(
 201     std::vector<std::pair<OUString, jfw::VersionInfo>> const& vecVendorInfos,
 202     JavaInfo ** ppInfo,
 203     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 204
 205
 206 /** obtains information about installations of Java Runtime Environments (JREs)
 207     whose executable is in the PATH.
 208
 209     <p>The function gathers information about available JREs which are on the PATH
 210     (PATH environment variable) and meet the vendor and version requirements given by
 211     <code>vecVendorInfos</code> (i.e. they have a vendor that is given in
 212     <code>vecVendorInfos</code> and the version requirements for the vendor are met).
 213     </p>
 214     <p>
 215     The JavaInfo structures returned in <code>vecJavaInfosFromPath</code> should be ordered
 216     according to their occurrence in the PATH. The one that is the first one on the PATH
 217     is also the first element in the vector.</p>
 218     <p>
 219     The function allocates memory for all the JavaInfo objects returned
 220     in <code>vecJavaInfosFromPath</code>. The caller must delete each JavaInfo object.
 221     </p>
 222     @param vecVendorInfos
 223        [in] vector specifying the vendor and version requirements that the JRE must fulfill.
 224        The vector contains pairs of vendors and the respective version requirements
 225        for those vendors. The JRE must support the requirements of one given pair in the
 226        vector (i.e. it must be of one of the vendors and meet the version requirements
 227        - minVersion, maxVersion, excludeVersions - for that specific vendor).
 228     @param vecJavaInfosFromPath
 229         [out] if the function runs successfully then <code>vecJavaInfosFromPath</code>
 230         contains on return a vector of pointers to <code>JavaInfo</code> objects.
 231         On return of this function, <code>vecJavaInfosFromPath</code> references
 232         a newly created vector rather than the same vector as before with
 233         the <code>JavaInfo</code> objects inserted into the existing vector.
 234
 235     @return
 236     javaPluginError::NONE the function ran successfully and at least one JRE
 237     that meets the requirements was found.</br>
 238     javaPluginError::NoJre no JavaInfo that meets the version criteria was found
 239     when inspecting the PATH
 240  */
 241
 242 javaPluginError jfw_plugin_getJavaInfosFromPath(
 243     std::vector<std::pair<OUString, jfw::VersionInfo>> const& vecVendorInfos,
 244     std::vector<JavaInfo*> & vecJavaInfosFromPath,
 245     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 246
 247 /** starts a Java Virtual Machine.
 248
 249     <p>The caller should provide all essential JavaVMOptions, such as the
 250     class path (-Djava.class.path=xxx). It is assumed that the caller
 251     knows what JRE is used. Hence the implementation does not need to check
 252     the options for validity. If a user configured the application to
 253     use specific options, such as -X..., then it is in his responsibility to
 254     ensure that the application works properly. The function may add or modify
 255     properties. For example, it may add to the class path property.
 256     <p>
 257     The function must ensure, that the VM does not abort the process
 258     during instantiation.</p>
 259     <p>
 260     The function receives a <code>JavaInfo</code> object that was created
 261     by the functions <code>jfw_plugin_getJavaInfoByPath</code> or
 262     <code>jfw_plugin_getAllJavaInfos</code> from the same library. This can be
 263     guaranteed if an application uses exactly one library for one vendor.
 264     Therefore the functions which create the <code>JavaInfo</code> can store all
 265     necessary information which are needed for starting the VM into that
 266     structure. </p>
 267
 268     @param pInfo
 269         [in] the JavaInfo object with information about the JRE.
 270     @param arOptions
 271         [in] the options which are passed into the JNI_CreateJavaVM function.
 272         Can be NULL.
 273     @param nSizeOptions
 274         [in] the number of elements in <code>arOptions</code>.
 275     @param ppVM
 276         [out] the JavaVM pointer of the created VM.
 277     @param ppEnv
 278         [out] the JNIEnv pointer of the created VM.
 279
 280     @return
 281     javaPluginError::NONE the function ran successfully.</br>
 282     javaPluginError::Error an error occurred during execution.</br>
 283     javaPluginError::WrongVendor the <code>JavaInfo</code> object was not created
 284     in by this library and the VM cannot be started.</br>
 285     javaPluginError::InvalidArg an argument was not valid. For example
 286     <code>pInfo</code> or , <code>ppVM</code> or <code>ppEnv</code> are NULL.
 287     </br>
 288     JFW_PLUGIN_E_VM_CREATION_FAILED a VM could not be created. The error was caused
 289     by the JRE.
 290  */
 291 javaPluginError jfw_plugin_startJavaVirtualMachine(
 292     const JavaInfo *pInfo,
 293     const JavaVMOption *arOptions,
 294     sal_Int32 nSizeOptions,
 295     JavaVM ** ppVM,
 296     JNIEnv ** ppEnv);
 297
 298
 299 /** checks if the installation of the jre still exists.
 300
 301     This function checks if the JRE described by pInfo still
 302     exists. The check must be very quick because it is called by javaldx
 303     (Linux, Solaris) at start up.
 304
 305     @param pInfo
 306         [in]  the JavaInfo object with information about the JRE.
 307     @param pp_exist
 308         [out] the parameter is set to either sal_True or sal_False. The value is
 309         only valid if the function returns JFW_E_NONE.
 310
 311    @return
 312     javaPluginError::NONE the function ran successfully.</br>
 313     javaPluginError::Error an error occurred during execution.</br>
 314     javaPluginError::InvalidArg pInfo contains invalid data</br>
 315  */
 316 javaPluginError jfw_plugin_existJRE(const JavaInfo *pInfo, sal_Bool *exist);
 317
 318 #endif
 319
 320 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */