include/jvmfwk/vendorplugin.h

   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_VENDORPLUGIN_H
  22 #define INCLUDED_JVMFWK_VENDORPLUGIN_H
  23
  24 #include "jvmfwkplugindllapi.h"
  25 #include "jvmfwk/framework.h"
  26 #include "rtl/ustring.h"
  27 #include "jni.h"
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33
  34 /**
  35    @file
  36    <p>
  37    This API shall be implemented if one wants to support a Java Runtime
  38    Environment (JRE) of a particular vendor. Because there is currently no
  39    specification which rules the structure and location of JRE installations
  40    and the format of version strings it is not possible to supply a general
  41    implementation for all possible vendors. If an application determines exactly
  42    what version a JRE must have then it relies on certain features and bug
  43    fixes of that version. Because a version 1.4.2_1 from vendor X may contain
  44    different fixes as the same version from vendor Y it is important to see
  45    version an vendor as one entity. One without the other does not guarantee
  46    the existence of a particular set of features or bug fixes. An implementation
  47    of this API may support multiple vendors. </p>
  48    <p>
  49    Libraries which implement this interface will be dynamically loaded and
  50    unloaded by the java framework (jvmfwk/framework.h). Therefore they must not
  51    keep global variables.
  52    </p>
  53  */
  54
  55 typedef enum
  56 {
  57     JFW_PLUGIN_E_NONE,
  58     JFW_PLUGIN_E_ERROR,
  59     JFW_PLUGIN_E_INVALID_ARG,
  60     JFW_PLUGIN_E_WRONG_VERSION_FORMAT,
  61     JFW_PLUGIN_E_FAILED_VERSION,
  62     JFW_PLUGIN_E_NO_JRE,
  63     JFW_PLUGIN_E_WRONG_VENDOR,
  64     JFW_PLUGIN_E_VM_CREATION_FAILED
  65 } javaPluginError;
  66
  67
  68
  69 /** obtains information about installations of Java Runtime Environments (JREs).
  70
  71     <p>The function gathers information about available JREs which have the same
  72     vendor as determined by the <code>sVendor</code> parameter. Only information
  73     about those JREs which match the version requirements are returned. These
  74     requirements are specified by the parameters <code>sMinVersion</code>,
  75     <code>sMaxVersion</code> and <code>arExcludeList</code>.
  76     </p>
  77     <p>
  78     The JavaInfo structures returned in <code>parJavaInfo</code> should be ordered
  79     according to their version. The one, representing a JRE with the highest
  80     version should be the first in the array. </p>
  81     <p>
  82     The function allocates memory for an array and all the JavaInfo objects returned
  83     in <code>parJavaInfo</code>. The caller must free each JavaInfo object by calling
  84     <code>jfw_freeJavaInfo</code> (#include "jvmfwk/framework.h"). The array is to be
  85     freed by rtl_freeMemory.
  86     In case an error occurred <code>parJavaInfo</code> need not be freed.
  87     </p>
  88     @param sVendor
  89         [in] only JREs from this vendor are examined. This parameter always contains
  90         a vendor string. That is, the string it is not empty.
  91     @param sMinVersion
  92         [in] represents the minimum version of a JRE. The string can be empty but
  93         a null pointer is not allowed.
  94     @param sMaxVersion
  95         [in] represents the maximum version of a JRE. The string can be empty but
  96         a null pointer is not allowed.
  97     @param arExcludeList
  98         [in] contains a list of &quot;bad&quot; versions. JREs which have one of these
  99         versions must not be returned by this function. It can be NULL.
 100     @param nSizeExcludeList
 101         [in] the number of version strings contained in <code>arExcludeList</code>.
 102     @param parJavaInfo
 103         [out] if the function runs successfully then <code>parJavaInfo</code> contains
 104         on return an array of pointers to <code>JavaInfo</code> objects.
 105     @param nSizeJavaInfo
 106        [out] the number of <code>JavaInfo</code> pointers contained in
 107        <code>parJavaInfo</code>.
 108
 109     @return
 110     JFW_PLUGIN_E_NONE the function ran successfully.</br>
 111     JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 112     JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
 113     <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
 114     is NULL or NULL pointer were passed for at least on of the strings.</br>
 115     JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in
 116     <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
 117     version strings.
 118  */
 119 JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_getAllJavaInfos(
 120     rtl_uString *sVendor,
 121     rtl_uString *sMinVersion,
 122     rtl_uString *sMaxVersion,
 123     rtl_uString * * arExcludeList,
 124     sal_Int32  nSizeExcludeList,
 125     JavaInfo*** parJavaInfo,
 126     sal_Int32 *nSizeJavaInfo);
 127
 128 /** obtains information for a JRE at a given location.
 129
 130    <p>If the given location belongs to a JRE whoose vendor matches the
 131    sVendor argument and the JRE has a version which meets the requirements as
 132    specified by <code>sMinVersion, sMaxVersion, arExcludeList</code> then
 133    this function shall return a JavaInfo object for this JRE if this implementation
 134    supports this vendor.</p>
 135
 136    @param sLocation
 137        [in] a file URL to the directory of the JRE.
 138    @param sVendor
 139       [in] a name of a vendor. This parameter always contains
 140         a vendor string. That is, the string it is not empty.
 141    @param sMinVersion
 142        [in] represents the minimum version of a JRE.
 143    @param sMaxVersion
 144        [in] represents the maximum version of a JRE.
 145    @param arExcludeList
 146        [in] contains a list of &quot;bad&quot; versions. JREs which have one of these
 147         versions must not be returned by this function. It can be NULL.
 148    @param nSizeExcludeList
 149        [in] the number of version strings contained in <code>arExcludeList</code>.
 150    @param ppInfo
 151        [out] if the function runs successfully then <code>ppInfo</code> contains
 152         on return a pointer to a <code>JavaInfo</code> object.
 153
 154    @return
 155    JFW_PLUGIN_E_NONE the function ran successfully.</br>
 156    JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 157    JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
 158     <code>nSizeExcludeList</code> is greater null but <code>arExcludeList</code>
 159     is NULL, NULL pointer were passed for at least on of the strings, sLocation
 160     is an empty string.</br>
 161    JFW_PLUGIN_E_WRONG_VERSION_FORMAT the version strings in
 162     <code>sMinVersion,sMaxVersion,arExcludeList</code> are not recognized as valid
 163     version strings.
 164    JFW_PLUGIN_E_FAILED_VERSION there is a JRE at the given location but it does not
 165    meet the version requirements.
 166    JFW_PLUGIN_E_NO_JRE no JRE could be detected at the given location. However, that
 167    does not mean necessarily that there is no JRE. There could be a JRE but it has
 168    a vendor which is not supported by this API implementation.
 169  */
 170 JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_getJavaInfoByPath(
 171     rtl_uString *sLocation,
 172     rtl_uString *sVendor,
 173     rtl_uString *sMinVersion,
 174     rtl_uString *sMaxVersion,
 175     rtl_uString * *arExcludeList,
 176     sal_Int32  nSizeExcludeList,
 177     JavaInfo ** ppInfo);
 178
 179 /** starts a Java Virtual Machine.
 180
 181     <p>The caller should provide all essential JavaVMOptions, such as the
 182     class path (-Djava.class.path=xxx). It is assumed that the caller
 183     knows what JRE is used. Hence the implementation does not need to check
 184     the options for validity. If a user configured the application to
 185     use specific options, such as -X..., then it is in his responsibility to
 186     ensure that the application works properly. The function may add or modify
 187     properties. For example, it may add to the class path property.
 188     <p>
 189     The function must ensure, that the VM does not abort the process
 190     during instantiation.</p>
 191     <p>
 192     The function receives a <code>JavaInfo</code> object that was created
 193     by the functions <code>jfw_plugin_getJavaInfoByPath</code> or
 194     <code>jfw_plugin_getAllJavaInfos</code> from the same library. This can be
 195     guaranteed if an application uses exactly one library for one vendor.
 196     Therefore the functions which create the <code>JavaInfo</code> can store all
 197     necessary information which are needed for starting the VM into that
 198     structure. </p>
 199
 200     @param pInfo
 201         [in] the JavaInfo object with information about the JRE.
 202     @param arOptions
 203         [in] the options which are passed into the JNI_CreateJavaVM function.
 204         Can be NULL.
 205     @param nSizeOptions
 206         [in] the number of elements in <code>arOptions</code>.
 207     @param ppVM
 208         [out] the JavaVM pointer of the created VM.
 209     @param ppEnv
 210         [out] the JNIEnv pointer of the created VM.
 211
 212     @return
 213     JFW_PLUGIN_E_NONE the function ran successfully.</br>
 214     JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 215     JFW_PLUGIN_E_WRONG_VENDOR the <code>JavaInfo</code> object was not created
 216     in by this library and the VM cannot be started.</br>
 217     JFW_PLUGIN_E_INVALID_ARG an argument was not valid. For example
 218     <code>pInfo</code> or , <code>ppVM</code> or <code>ppEnv</code> are NULL.
 219     </br>
 220     JFW_PLUGIN_E_VM_CREATION_FAILED a VM could not be created. The error was caused
 221     by the JRE.
 222  */
 223 JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_startJavaVirtualMachine(
 224     const JavaInfo *pInfo,
 225     const JavaVMOption *arOptions,
 226     sal_Int32 nSizeOptions,
 227     JavaVM ** ppVM,
 228     JNIEnv ** ppEnv);
 229
 230
 231
 232 /** checks if the installation of the jre still exists.
 233
 234     This function checks if the JRE described by pInfo still
 235     exists. The check must be very quick because it is called by javaldx
 236     (Linux, Solaris) at start up.
 237
 238     @param pInfo
 239         [in]  the JavaInfo object with information about the JRE.
 240     @param pp_exist
 241         [out] the parameter is set to either sal_True or sal_False. The value is
 242         only valid if the function returns JFW_E_NONE.
 243
 244    @return
 245     JFW_PLUGIN_E_NONE the function ran successfully.</br>
 246     JFW_PLUGIN_E_ERROR an error occurred during execution.</br>
 247     JFW_PLUGIN_E_INVALID_ARG pInfo contains invalid data</br>
 248  */
 249 JVMFWK_PLUGIN_DLLPUBLIC javaPluginError jfw_plugin_existJRE(const JavaInfo *pInfo, sal_Bool *exist);
 250
 251 #ifdef __cplusplus
 252 }
 253 #endif
 254
 255
 256 #endif
 257
 258 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */