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 <rtl/ustring.hxx>
  25 #include <jni.h>
  26
  27 #include <memory>
  28 #include <vector>
  29
  30 namespace jfw_plugin { class VendorBase; }
  31 namespace rtl { template <class reference_type> class Reference; }
  32
  33 struct JavaInfo;
  34
  35 namespace jfw { class VendorSettings; }
  36
  37 /**
  38    @file
  39    <p>
  40    This API shall be implemented if one wants to support a Java Runtime
  41    Environment (JRE) of a particular vendor. Because there is currently no
  42    specification which rules the structure and location of JRE installations
  43    and the format of version strings it is not possible to supply a general
  44    implementation for all possible vendors. If an application determines exactly
  45    what version a JRE must have then it relies on certain features and bug
  46    fixes of that version. Because a version 1.4.2_1 from vendor X may contain
  47    different fixes as the same version from vendor Y it is important to see
  48    version and vendor as one entity. One without the other does not guarantee
  49    the existence of a particular set of features or bug fixes. An implementation
  50    of this API may support multiple vendors. </p>
  51  */
  52
  53 enum class javaPluginError
  54 {
  55     NONE,
  56     Error,
  57     InvalidArg,
  58     WrongVersionFormat,
  59     FailedVersion,
  60     NoJre,
  61     WrongArch,
  62     VmCreationFailed
  63 };
  64
  65
  66 /** obtains information about installations of Java Runtime Environments (JREs).
  67
  68     <p>The function gathers information about available JREs. Only information
  69     about those JREs which match the version requirements are returned. These
  70     requirements are specified by the parameter <code>vendorSettings</code>.
  71     </p>
  72     <p>
  73     The JavaInfo structures returned in <code>parJavaInfo</code> should be ordered
  74     according to their version. The one, representing a JRE with the highest
  75     version should be the first in the array. </p>
  76     @param parJavaInfo
  77         [out] if the function runs successfully then <code>parJavaInfo</code> contains
  78         on return a vector of pointers to <code>JavaInfo</code> objects.
  79
  80     @return
  81     javaPluginError::NONE the function ran successfully.</br>
  82     javaPluginError::Error an error occurred during execution.</br>
  83     javaPluginError::WrongVersionFormat the version strings in
  84     <code>vendorSettings</code> are not recognized as valid
  85     version strings.
  86  */
  87 javaPluginError jfw_plugin_getAllJavaInfos(
  88     bool checkJavaHomeAndPath,
  89     jfw::VendorSettings const & vendorSettings,
  90     std::vector<std::unique_ptr<JavaInfo>> * parJavaInfo,
  91     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
  92
  93 /** obtains information for a JRE at a given location.
  94
  95    <p>If the given location belongs to a JRE
  96    and the JRE has a version which meets the requirements as
  97    specified by <code>vendorSettings</code> then
  98    this function shall return a JavaInfo object for this JRE.</p>
  99
 100    @param sLocation
 101        [in] a file URL to the directory of the JRE.
 102    @param ppInfo
 103        [out] if the function runs successfully then <code>ppInfo</code> contains
 104         on return a pointer to a <code>JavaInfo</code> object.
 105
 106    @return
 107    javaPluginError::NONE the function ran successfully.</br>
 108    javaPluginError::Error an error occurred during execution.</br>
 109    javaPluginError::InvalidArg an argument was not valid. For example, sLocation
 110     is an empty string.</br>
 111    javaPluginError::FailedVersion there is a JRE at the given location but it does not
 112    meet the version requirements.
 113    javaPluginError::NoJre no JRE could be detected at the given location.
 114  */
 115 javaPluginError jfw_plugin_getJavaInfoByPath(
 116     OUString const& sLocation,
 117     jfw::VendorSettings const & vendorSettings,
 118     std::unique_ptr<JavaInfo> * ppInfo);
 119
 120
 121 /** obtains information for a JRE referenced by the JAVA_HOME environment variable.
 122
 123    <p>If the JAVA_HOME environment variable is set and points to a JRE that
 124    matches the requirements given by vendorSettings (i.e.
 125    the version requirements, if any, for the vendor are met),
 126    then this function shall return a JavaInfo object for this JRE.</p>
 127
 128    @param ppInfo
 129        [out] if the JAVA_HOME environment variable is set and points to a suitable
 130        JRE, then <code>ppInfo</code> contains
 131         on return a pointer to its <code>JavaInfo</code> object.
 132
 133    @return
 134    javaPluginError::NONE the function ran successfully.</br>
 135    javaPluginError::NoJre no suitable JRE could be detected at the given location. However, that
 136    does not mean necessarily that there is no JRE. There could be a JRE but
 137    it does not
 138    meet the version requirements.
 139  */
 140 javaPluginError jfw_plugin_getJavaInfoFromJavaHome(
 141     jfw::VendorSettings const & vendorSettings,
 142     std::unique_ptr<JavaInfo> * ppInfo,
 143     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 144
 145
 146 /** obtains information about installations of Java Runtime Environments (JREs)
 147     whose executable is in the PATH.
 148
 149     <p>The function gathers information about available JREs which are on the PATH
 150     (PATH environment variable) and meet the version requirements given by
 151     <code>vendorSettings</code> (i.e.
 152     the version requirements, if any, for the vendor are met).
 153     </p>
 154     <p>
 155     The JavaInfo structures returned in <code>vecJavaInfosFromPath</code> should be ordered
 156     according to their occurrence in the PATH. The one that is the first one on the PATH
 157     is also the first element in the vector.</p>
 158     @param vecJavaInfosFromPath
 159         [out] if the function runs successfully then <code>vecJavaInfosFromPath</code>
 160         contains on return a vector of pointers to <code>JavaInfo</code> objects.
 161         On return of this function, <code>vecJavaInfosFromPath</code> references
 162         a newly created vector rather than the same vector as before with
 163         the <code>JavaInfo</code> objects inserted into the existing vector.
 164
 165     @return
 166     javaPluginError::NONE the function ran successfully and at least one JRE
 167     that meets the requirements was found.</br>
 168     javaPluginError::NoJre no JavaInfo that meets the version criteria was found
 169     when inspecting the PATH
 170  */
 171
 172 javaPluginError jfw_plugin_getJavaInfosFromPath(
 173     jfw::VendorSettings const & vendorSettings,
 174     std::vector<std::unique_ptr<JavaInfo>> & vecJavaInfosFromPath,
 175     std::vector<rtl::Reference<jfw_plugin::VendorBase>> & infos);
 176
 177 /** starts a Java Virtual Machine.
 178
 179     <p>The caller should provide all essential JavaVMOptions, such as the
 180     class path (-Djava.class.path=xxx). It is assumed that the caller
 181     knows what JRE is used. Hence the implementation does not need to check
 182     the options for validity. If a user configured the application to
 183     use specific options, such as -X..., then it is in his responsibility to
 184     ensure that the application works properly. The function may add or modify
 185     properties. For example, it may add to the class path property.
 186     <p>
 187     The function must ensure, that the VM does not abort the process
 188     during instantiation.</p>
 189     <p>
 190     The function receives a <code>JavaInfo</code> object that was created
 191     by the functions <code>jfw_plugin_getJavaInfoByPath</code> or
 192     <code>jfw_plugin_getAllJavaInfos</code> from the same library. This can be
 193     guaranteed if an application uses exactly one library for one vendor.
 194     Therefore the functions which create the <code>JavaInfo</code> can store all
 195     necessary information which are needed for starting the VM into that
 196     structure. </p>
 197
 198     @param pInfo
 199         [in] the JavaInfo object with information about the JRE.
 200     @param arOptions
 201         [in] the options which are passed into the JNI_CreateJavaVM function.
 202         Can be NULL.
 203     @param nSizeOptions
 204         [in] the number of elements in <code>arOptions</code>.
 205     @param ppVM
 206         [out] the JavaVM pointer of the created VM.
 207     @param ppEnv
 208         [out] the JNIEnv pointer of the created VM.
 209
 210     @return
 211     javaPluginError::NONE the function ran successfully.</br>
 212     javaPluginError::Error an error occurred during execution.</br>
 213     JFW_PLUGIN_E_VM_CREATION_FAILED a VM could not be created. The error was caused
 214     by the JRE.
 215  */
 216 javaPluginError jfw_plugin_startJavaVirtualMachine(
 217     const JavaInfo *pInfo,
 218     const JavaVMOption *arOptions,
 219     sal_Int32 nSizeOptions,
 220     JavaVM ** ppVM,
 221     JNIEnv ** ppEnv);
 222
 223
 224 /** checks if the installation of the jre still exists.
 225
 226     This function checks if the JRE described by pInfo still
 227     exists. The check must be very quick because it is called by javaldx
 228     (Linux, Solaris) at start up.
 229
 230     @param pInfo
 231         [in]  the JavaInfo object with information about the JRE.
 232     @param pp_exist
 233         [out] the parameter is set to either sal_True or sal_False. The value is
 234         only valid if the function returns JFW_E_NONE.
 235
 236    @return
 237     javaPluginError::NONE the function ran successfully.</br>
 238     javaPluginError::Error an error occurred during execution.</br>
 239     javaPluginError::InvalidArg pInfo contains invalid data</br>
 240  */
 241 javaPluginError jfw_plugin_existJRE(const JavaInfo *pInfo, bool *exist);
 242
 243 #endif
 244
 245 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */