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.h>
  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 typedef enum
  50 {
  51     JFW_PLUGIN_E_NONE,
  52     JFW_PLUGIN_E_ERROR,
  53     JFW_PLUGIN_E_INVALID_ARG,
  54     JFW_PLUGIN_E_WRONG_VERSION_FORMAT,
  55     JFW_PLUGIN_E_FAILED_VERSION,
  56     JFW_PLUGIN_E_NO_JRE,
  57     JFW_PLUGIN_E_WRONG_VENDOR,
  58     JFW_PLUGIN_E_VM_CREATION_FAILED
  59 } javaPluginError;
  60
  61
  62
  63 /** obtains information about installations of Java Runtime Environments (JREs).
  64
  65     <p>The function gathers information about available JREs which have the same
  66     vendor as determined by the <code>sVendor</code> parameter. Only information
  67     about those JREs which match the version requirements are returned. These
  68     requirements are specified by the parameters <code>sMinVersion</code>,
  69     <code>sMaxVersion</code> and <code>arExcludeList</code>.
  70     </p>
  71     <p>
  72     The JavaInfo structures returned in <code>parJavaInfo</code> should be ordered
  73     according to their version. The one, representing a JRE with the highest
  74     version should be the first in the array. </p>
  75     <p>
  76     The function allocates memory for an array and all the JavaInfo objects returned
  77     in <code>parJavaInfo</code>. The caller must free each JavaInfo object by calling
  78     <code>jfw_freeJavaInfo</code> (#include "jvmfwk/framework.h"). The array is to be
  79     freed by rtl_freeMemory.
  80     In case an error occurred <code>parJavaInfo</code> need not be freed.
  81     </p>
  82     @param sVendor
  83         [in] only JREs from this vendor are examined. This parameter always contains
  84         a vendor string. That is, the string it is not empty.
  85     @param sMinVersion
  86         [in] represents the minimum version of a JRE. The string can be empty.
  87     @param sMaxVersion
  88         [in] represents the maximum version of a JRE. The string can be empty.
  89     @param arExcludeList
  90         [in] contains a list of &quot;bad&quot; versions. JREs which have one of these
  91         versions must not be returned by this function. It can be NULL.
  92     @param nSizeExcludeList
  93         [in] the number of version strings contained in <code>arExcludeList</code>.
  94     @param parJavaInfo
  95         [out] if the function runs successfully then <code>parJavaInfo</code> contains
  96         on return an array of pointers to <code>JavaInfo</code> objects.
  97     @param nSizeJavaInfo
  98        [out] the number of <code>JavaInfo</code> pointers contained in
  99        <code>parJavaInfo</code>.
 100
 101     @return
 102     JFW_PLUGIN_E_NONE the function ran successfully.</br>
 103     JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 104     JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
 105     <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
 106     is NULL or NULL pointer were passed for at least on of the strings.</br>
 107     JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in
 108     <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
 109     version strings.
 110  */
 111 javaPluginError jfw_plugin_getAllJavaInfos(
 112     bool checkJavaHomeAndPath,
 113     OUString const& sVendor,
 114     OUString const& sMinVersion,
 115     OUString const& sMaxVersion,
 116     rtl_uString * * arExcludeList,
 117     sal_Int32  nSizeExcludeList,
 118     JavaInfo*** parJavaInfo,
 119     sal_Int32 *nSizeJavaInfo,
 120     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 121
 122 /** obtains information for a JRE at a given location.
 123
 124    <p>If the given location belongs to a JRE whoose vendor matches the
 125    sVendor argument and the JRE has a version which meets the requirements as
 126    specified by <code>sMinVersion, sMaxVersion, arExcludeList</code> then
 127    this function shall return a JavaInfo object for this JRE if this implementation
 128    supports this vendor.</p>
 129
 130    @param sLocation
 131        [in] a file URL to the directory of the JRE.
 132    @param sVendor
 133       [in] a name of a vendor. This parameter always contains
 134         a vendor string. That is, the string it is not empty.
 135    @param sMinVersion
 136        [in] represents the minimum version of a JRE.
 137    @param sMaxVersion
 138        [in] represents the maximum version of a JRE.
 139    @param arExcludeList
 140        [in] contains a list of &quot;bad&quot; versions. JREs which have one of these
 141         versions must not be returned by this function. It can be NULL.
 142    @param nSizeExcludeList
 143        [in] the number of version strings contained in <code>arExcludeList</code>.
 144    @param ppInfo
 145        [out] if the function runs successfully then <code>ppInfo</code> contains
 146         on return a pointer to a <code>JavaInfo</code> object.
 147
 148    @return
 149    JFW_PLUGIN_E_NONE the function ran successfully.</br>
 150    JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 151    JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
 152     <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
 153     is NULL, NULL pointer were passed for at least on of the strings, sLocation
 154     is an empty string.</br>
 155    JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in
 156     <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
 157     version strings.
 158    JFW_PLUGIN_E_FAILED_VERSION there is a JRE at the given location but it does not
 159    meet the version requirements.
 160    JFW_PLUGIN_E_NO_JRE no JRE could be detected at the given location. However, that
 161    does not mean necessarily that there is no JRE. There could be a JRE but it has
 162    a vendor which is not supported by this API implementation.
 163  */
 164 javaPluginError jfw_plugin_getJavaInfoByPath(
 165     OUString const& sLocation,
 166     OUString const& sVendor,
 167     OUString const& sMinVersion,
 168     OUString const& sMaxVersion,
 169     rtl_uString * *arExcludeList,
 170     sal_Int32  nSizeExcludeList,
 171     JavaInfo ** ppInfo);
 172
 173
 174
 175 /** obtains information for a JRE referenced by the JAVA_HOME environment variable.
 176
 177    <p>If the JAVA_HOME environment variable is set and points to a JRE whoose vendor
 178    matches the requirements given by vecVendorInfos (i.e. it has a vendor that is
 179    given in vecVendorInfos and the version requirements for the vendor are met),
 180    then this function shall return a JavaInfo object for this JRE.</p>
 181
 182    @param vecVendorInfos
 183        [in] vector specifying the vendor and version requirements that the JRE must fulfill.
 184        The vector contains pairs of vendors and the respective version requirements
 185        for those vendors. The JRE must support the requirements of one given pair in the
 186        vector (i.e. it must be of one of the vendors and meet the version requirements
 187        - minVersion, maxVersion, excludeVersions - for that specific vendor).
 188    @param ppInfo
 189        [out] if the JAVA_HOME environment variable is set and points to a suitable
 190        JRE, then then <code>ppInfo</code> contains
 191         on return a pointer to its <code>JavaInfo</code> object.
 192
 193    @return
 194    JFW_PLUGIN_E_NONE the function ran successfully.</br>
 195    JFW_PLUGIN_E_INVALID_ARG an argument was not valid, for example
 196     <code>ppInfo</code> is an invalid pointer.
 197    JFW_PLUGIN_E_NO_JRE no suitable JRE could be detected at the given location. However, that
 198    does not mean necessarily that there is no JRE. There could be a JRE but it has
 199    a vendor which is not supported by this API implementation or it does not
 200    meet the version requirements.
 201  */
 202 javaPluginError jfw_plugin_getJavaInfoFromJavaHome(
 203     std::vector<std::pair<OUString, jfw::VersionInfo>> const& vecVendorInfos,
 204     JavaInfo ** ppInfo,
 205     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 206
 207
 208 /** obtains information about installations of Java Runtime Environments (JREs)
 209     whose executable is in the PATH.
 210
 211     <p>The function gathers information about available JREs which are on the PATH
 212     (PATH environment variable) and meet the vendor and version requirements given by
 213     <code>vecVendorInfos</code> (i.e. they have a vendor that is given in
 214     <code>vecVendorInfos</code> and the version requirements for the vendor are met).
 215     </p>
 216     <p>
 217     The JavaInfo structures returned in <code>vecJavaInfosFromPath</code> should be ordered
 218     according to their occurrence in the PATH. The one that is the first one on the PATH
 219     is also the first element in the vector.</p>
 220     <p>
 221     The function allocates memory for all the JavaInfo objects returned
 222     in <code>vecJavaInfosFromPath</code>. The caller must free each JavaInfo object by calling
 223     <code>jfw_freeJavaInfo</code> (#include "jvmfwk/framework.h").
 224     </p>
 225     @param vecVendorInfos
 226        [in] vector specifying the vendor and version requirements that the JRE must fulfill.
 227        The vector contains pairs of vendors and the respective version requirements
 228        for those vendors. The JRE must support the requirements of one given pair in the
 229        vector (i.e. it must be of one of the vendors and meet the version requirements
 230        - minVersion, maxVersion, excludeVersions - for that specific vendor).
 231     @param vecJavaInfosFromPath
 232         [out] if the function runs successfully then <code>vecJavaInfosFromPath</code>
 233         contains on return a vector of pointers to <code>JavaInfo</code> objects.
 234         On return of this function, <code>vecJavaInfosFromPath</code> references
 235         a newly created vector rather than the same vector as before with
 236         the <code>JavaInfo</code> objects inserted into the existing vector.
 237
 238     @return
 239     JFW_PLUGIN_E_NONE the function ran successfully and at least one JRE
 240     that meets the requirements was found.</br>
 241     JFW_PLUGIN_E_NO_JRE no JavaInfo that meets the version criteria was found
 242     when inspecting the PATH
 243  */
 244
 245 javaPluginError jfw_plugin_getJavaInfosFromPath(
 246     std::vector<std::pair<OUString, jfw::VersionInfo>> const& vecVendorInfos,
 247     std::vector<JavaInfo*> & vecJavaInfosFromPath,
 248     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 249
 250 /** starts a Java Virtual Machine.
 251
 252     <p>The caller should provide all essential JavaVMOptions, such as the
 253     class path (-Djava.class.path=xxx). It is assumed that the caller
 254     knows what JRE is used. Hence the implementation does not need to check
 255     the options for validity. If a user configured the application to
 256     use specific options, such as -X..., then it is in his responsibility to
 257     ensure that the application works properly. The function may add or modify
 258     properties. For example, it may add to the class path property.
 259     <p>
 260     The function must ensure, that the VM does not abort the process
 261     during instantiation.</p>
 262     <p>
 263     The function receives a <code>JavaInfo</code> object that was created
 264     by the functions <code>jfw_plugin_getJavaInfoByPath</code> or
 265     <code>jfw_plugin_getAllJavaInfos</code> from the same library. This can be
 266     guaranteed if an application uses exactly one library for one vendor.
 267     Therefore the functions which create the <code>JavaInfo</code> can store all
 268     necessary information which are needed for starting the VM into that
 269     structure. </p>
 270
 271     @param pInfo
 272         [in] the JavaInfo object with information about the JRE.
 273     @param arOptions
 274         [in] the options which are passed into the JNI_CreateJavaVM function.
 275         Can be NULL.
 276     @param nSizeOptions
 277         [in] the number of elements in <code>arOptions</code>.
 278     @param ppVM
 279         [out] the JavaVM pointer of the created VM.
 280     @param ppEnv
 281         [out] the JNIEnv pointer of the created VM.
 282
 283     @return
 284     JFW_PLUGIN_E_NONE the function ran successfully.</br>
 285     JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 286     JFW_PLUGIN_E_WRONG_VENDOR the <code>JavaInfo</code> object was not created
 287     in by this library and the VM cannot be started.</br>
 288     JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
 289     <code>pInfo</code> or , <code>ppVM</code> or <code>ppEnv</code> are NULL.
 290     </br>
 291     JFW_PLUGIN_E_VM_CREATION_FAILED a VM could not be created. The error was caused
 292     by the JRE.
 293  */
 294 javaPluginError jfw_plugin_startJavaVirtualMachine(
 295     const JavaInfo *pInfo,
 296     const JavaVMOption *arOptions,
 297     sal_Int32 nSizeOptions,
 298     JavaVM ** ppVM,
 299     JNIEnv ** ppEnv);
 300
 301
 302
 303 /** checks if the installation of the jre still exists.
 304
 305     This function checks if the JRE described by pInfo still
 306     exists. The check must be very quick because it is called by javaldx
 307     (Linux, Solaris) at start up.
 308
 309     @param pInfo
 310         [in]  the JavaInfo object with information about the JRE.
 311     @param pp_exist
 312         [out] the parameter is set to either sal_True or sal_False. The value is
 313         only valid if the function returns JFW_E_NONE.
 314
 315    @return
 316     JFW_PLUGIN_E_NONE the function ran successfully.</br>
 317     JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 318     JFW_PLUGIN_E_INVALID_ARG pInfo contains invalid data</br>
 319  */
 320 javaPluginError jfw_plugin_existJRE(const JavaInfo *pInfo, sal_Bool *exist);
 321
 322 #endif
 323
 324 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */