Package de.xima.fc.plugin

Class PluginHelper

java.lang.Object
de.xima.fc.plugin.PluginHelper
public class PluginHelper extends Object
Author:
XIMA MEDIA GmbH

  • Constructor Details

    • PluginHelper

      public PluginHelper()

  • Method Details

    • checkPluginVersion

      public static EPluginCompatibility checkPluginVersion(PluginManifest manifest)

    • createDefaultPluginConfig

      public static byte[] createDefaultPluginConfig(PluginRuntime runtime) throws IOException
      Creates the default plugin configuration data for a given plugin runtime, suitable for IFileEntity.setNewData(byte[]).
      Parameters:
      runtime - Plugin runtime to process.
      Returns:
      The default properties data, suitable for IFileEntity.setNewData(byte[]).
      Throws:
      IOException - When the data could not be created.

    • createDefaultPluginConfig

      public static byte[] createDefaultPluginConfig(List<? extends IExtendedParameterModel> parameters) throws IOException
      Parameters:
      parameters - Parameter schema from the plugin.
      Returns:
      The default properties data, suitable for IFileEntity.setNewData(byte[]).
      Throws:
      IOException - When the data could not be created.

    • checkPluginVersion

      public static EPluginCompatibility checkPluginVersion(String requiredFCVersionStr)

    • getPluginManifest

      public static PluginManifest getPluginManifest(PluginRuntime pluginRuntime)
      Reads the manifest from the JAR file of the given plugin runtime. Requires that the plugin has a JAR file and is not system-managed.
      Parameters:
      pluginRuntime - Plugin runtime to process.
      Returns:
      The manifest, or null when no manifest was found.

    • getPluginManifest

      public static PluginManifest getPluginManifest(InputStream inputStream)
      Retrieves the plugin manifest for a given plugin JAR file.
      Parameters:
      inputStream - Input stream for a plugin JAR file.
      Returns:
      The plugin manifest, or null if it could not be read.
      Since:
      8.0.0

    • readParameterModels

      public static <M extends IExtendedParameterModel> List<M> readParameterModels(PluginRuntime runtime, Locale locale, com.alibaba.fastjson.util.BiFunction<String,String,M> modelFactory)
      Creates the parameter models for a plugin. The saved properties are taken from the plugin runtime. Use readParameterModels(PluginRuntime, Properties, Locale, BiFunction) if you wish to pass a custom set of parameters.

      Each parameter model represents a known configuration property with a schema, i.e. whether the property is required etc. This method merges all properties defined by the plugin with all existing, persisted properties of the plugin.

      Type Parameters:
      M - Type of the parameter model to return.
      Parameters:
      runtime - Plugin runtime from which to read the current, saved properties.
      locale - Locale for extracting the pre-defined configuration parameters. Their display name and description require localization.
      modelFactory - Factory for creating new parameter model instances. The first argument is name of the property, the second argument is its value.
      Returns:
      The merged list with all configuration properties.

    • readParameterModels

      public static <M extends IExtendedParameterModel> List<M> readParameterModels(PluginRuntime runtime, Properties persistedProperties, Locale locale, com.alibaba.fastjson.util.BiFunction<String,String,M> modelFactory)
      Creates the parameter models for a plugin. Each parameter model represents a known configuration property with a schema, i.e. whether the property is required etc. This method merges all properties defined by the plugin with all existing, persisted properties of the plugin.
      Type Parameters:
      M - Type of the parameter model to return.
      Parameters:
      runtime - Plugin runtime from which to read the current, saved properties.
      persistedProperties - The persisted or saved properties of the plugin, such as from a properties file or from the database.
      locale - Locale for extracting the pre-defined configuration parameters. Their display name and description require localization.
      modelFactory - Factory for creating new parameter model instances. The first argument is name of the property, the second argument is its value.
      Returns:
      The merged list with all configuration properties.

    • readBundleConfigParams

      public static Map<String,IBundleConfigParam> readBundleConfigParams(List<IBundleProperties> bundleProps, IPluginResourceHelper resourceHelper, Locale locale)
      Given a set of bundle property instances from a plugin, reads and returns all configuration parameters from that plugin. When a bundle property instance fails to return a set of configuration parameters, that instance is ignored.
      Parameters:
      bundleProps - Bundle properties to process.
      resourceHelper - Resource helper to pass on to each instance.
      locale - Locale to pass on to each instance.
      Returns:
      A map with all available configuration parameters.

    • readParameterModels

      public static <M extends IExtendedParameterModel> List<M> readParameterModels(Map<String,IBundleConfigParam> preDefinedProperties, org.apache.commons.configuration2.Configuration persistedProperties, com.alibaba.fastjson.util.BiFunction<String,String,M> modelFactory)
      Creates the parameter models for a plugin. Each parameter model represents a known configuration property with a schema, i.e. whether the property is required etc. This method merges all properties defined by the plugin with all existing, persisted properties of the plugin.
      Type Parameters:
      M - Type of the parameter model to return.
      Parameters:
      preDefinedProperties - Pre-defined properties as provided by the plugin.
      persistedProperties - Persisted or saved properties for the plugin, such as from an external configuration file or from the database.
      modelFactory - Factory for creating new parameter model instances. The first argument is name of the property, the second argument is its value.
      Returns:
      The merged list with all configuration properties.

    • readParameterModels

      public static <M extends IExtendedParameterModel> List<M> readParameterModels(Map<String,IBundleConfigParam> preDefinedProperties, Properties persistedProperties, com.alibaba.fastjson.util.BiFunction<String,String,M> modelFactory)
      Creates the parameter models for a plugin. Each parameter model represents a known configuration property with a schema, i.e. whether the property is required etc. This method merges all properties defined by the plugin with all existing, persisted properties of the plugin.
      Type Parameters:
      M - Type of the parameter model to return.
      Parameters:
      preDefinedProperties - Pre-defined properties as provided by the plugin.
      persistedProperties - Persisted or saved properties for the plugin, such as from an external configuration file or from the database.
      modelFactory - Factory for creating new parameter model instances. The first argument is name of the property, the second argument is its value.
      Returns:
      The merged list with all configuration properties.

    • validateConfigurationAgainstBundlePropertiesSchema

      public static IPluginInitializeValidationResult validateConfigurationAgainstBundlePropertiesSchema(List<? extends IExtendedParameterModel> properties, Locale locale)
      Validates the properties against the schema defined by a bundle properties instance. All required fields must have a value.
      Parameters:
      properties - Plugin properties with the schema to validate against.
      locale - Locale for localizing error messages.
      Returns:
      Whether the parameters are valid. If they are invalid, a list of error messages will also be available.

    • createTempRuntime

      public static Closable<PluginRuntime> createTempRuntime(Path jarFile, String name, String scopeKey, String runtimeKey, boolean instantiate) throws IOException
      Creates a temporary runtime that can be used e.g. for validation. When the returned item is closed, the temp runtime is cleaned up, but the given source file is not deleted.
      Parameters:
      jarFile - JAR file with the plugin.
      name - Name of the plugin JAR, such as the file name.
      scopeKey - Scope key of the plugin.
      runtimeKey - Runtime key of the plugin.
      instantiate - If true, instantiates all contained plugins and adds them to the runtime.
      Returns:
      A temporary plugin runtime for the given JAR file.
      Throws:
      IOException - When the temporary runtime could not be created.

    • createTempRuntime

      public static Closable<PluginRuntime> createTempRuntime(IThrowingSupplier<InputStream> data, String name, String scopeKey, String runtimeKey, boolean instantiate) throws IOException
      Creates a temporary runtime that can be used e.g. for validation. When the returned item is closed, the temporary runtime and any created temporary files are cleaned up.
      Parameters:
      data - Opens an input stream to the data with the JAR file. The supplied input stream will be closed.
      name - Name of the plugin JAR, such as the file name.
      scopeKey - Scope key of the plugin.
      runtimeKey - Runtime key of the plugin.
      instantiate - If true, instantiates all contained plugins and adds them to the runtime.
      Returns:
      A temporary plugin runtime for the given JAR file.
      Throws:
      IOException - When the temporary runtime could not be created.

    • createTempRuntime

      public static Closable<PluginRuntime> createTempRuntime(InputStream input, String name, String scopeKey, String runtimeKey, boolean instantiate) throws IOException
      Creates a temporary runtime that can be used e.g. for validation. When the returned item is closed, the temporary runtime and any created temporary files are cleaned up.
      Parameters:
      input - Input stream to the data with the JAR file. The input stream will NOT be closed.
      name - Name of the plugin JAR, such as the file name.
      scopeKey - Scope key of the plugin.
      runtimeKey - Runtime key of the plugin.
      instantiate - If true, instantiates all contained plugins and adds them to the runtime.
      Returns:
      A temporary plugin runtime for the given JAR file.
      Throws:
      IOException - When the temporary runtime could not be created.

    • validateConfiguration

      public static List<IPluginInitializeValidationResult> validateConfiguration(PluginRuntime runtime, Locale locale)
      Validates the configuration of the given plugin bundle against all available validation checks.

      This method reads the saved properties from the plugin runtime. Use the method with an explicit properties argument if you wish to provide a different set of properties.

      Parameters:
      runtime - Plugin runtime for the plugin bundle. Usually this will be a temporary runtime, as plugins should not be put into service if validation fails.
      locale - Locale for locale-sensitive operations, such as constructing validation error messages.
      Returns:
      A list of validation results, with one result for each plugin.
      See Also:

    • validateConfiguration

      public static List<IPluginInitializeValidationResult> validateConfiguration(PluginRuntime runtime, Properties properties, Locale locale)
      Validates the configuration of the given plugin bundle against all available validation checks, using a specified set of saved plugin properties.
      Parameters:
      runtime - Plugin runtime for the plugin bundle. Usually this will be a temporary runtime, as plugins should not be put into service if validation fails.
      properties - Configured plugin properties against which to validate.
      locale - Locale for locale-sensitive operations, such as constructing validation error messages.
      Returns:
      A list of validation results, with one result for each plugin.
      See Also:

    • validateConfigurationAgainstValidationCallback

      public static List<IPluginInitializeValidationResult> validateConfigurationAgainstValidationCallback(PluginRuntime runtime, Locale locale)
      Validates the configuration of the given plugin bundle via IFCPlugin#validateConfigurationData.

      This method read the properties from the plugin runtime. Use the method with an explicit properties argument if you wish to provide a different set of properties.

      Parameters:
      runtime - Plugin runtime for the plugin bundle. Usually this will be a temporary runtime, as plugins should not be put into service if validation fails.
      locale - Locale for locale-sensitive operations, such as constructing validation error messages.
      Returns:
      A list of validation results, with one result for each plugin.

    • validateConfigurationAgainstValidationCallback

      public static List<IPluginInitializeValidationResult> validateConfigurationAgainstValidationCallback(PluginRuntime runtime, Properties properties, Locale locale)
      Validates the configuration of the given plugin bundle via IFCPlugin#validateConfigurationData.
      Parameters:
      runtime - Plugin runtime for the plugin bundle. Usually this will be a temporary runtime, as plugins should not be put into service if validation fails.
      properties - Properties representing the plugin configuration that are to be validated.
      locale - Locale for locale-sensitive operations, such as constructing validation error messages.
      Returns:
      A list of validation results, with one result for each plugin.

    • getPluginManifest

      public static PluginManifest getPluginManifest(Path jarFile)
      Retrieves the plugin manifest for a given plugin JAR file.
      Parameters:
      jarFile - Plugin JAR file to process.
      Returns:
      The plugin manifest, or null if it could not be read.

    • getPluginManifest

      public static PluginManifest getPluginManifest(File jarFile)
      Retrieves the plugin manifest for a given plugin JAR file.
      Parameters:
      jarFile - Plugin JAR file to process.
      Returns:
      The plugin manifest, or null if it could not be read.

    • registerPlugin

      public static <T extends IFCPlugin> T registerPlugin(boolean install, boolean initialize, PluginRuntime prtm, Class<T> clazz) throws InstantiationException, IllegalAccessException, FCPluginException
      Throws:
      InstantiationException
      IllegalAccessException
      FCPluginException

    • canPluginBeRegistered

      public static <T extends IFCPlugin> boolean canPluginBeRegistered(PluginRuntime prtm, Class<T> pluginClass)
      Type Parameters:
      T - type of the plugin
      Parameters:
      prtm - A plugin runtime to check.
      pluginClass - Class to check
      Returns:
      whether or not the given plugin class can be registered in the given plugin scope

    • isSystemScope

      public static boolean isSystemScope(String scopeKey)
      Whether the given scope key represents the system scope.
      Parameters:
      scopeKey - A scope key to check.
      Returns:
      true if the scope key refers to the system scope, false if it refers to any client scope.

    • isPluginJar

      public static boolean isPluginJar(File file)
      Tests if the given file is a jar and contains formcycle-plugins of the type IFCPlugin
      Parameters:
      file - File
      Returns:
      true if the file is an jar containing an IFCPlugin-implementation, false otherwise

    • isUnpacked

      public static boolean isUnpacked(org.reflections.Reflections reflections)
      Parameters:
      reflections - Reflections to check, as created by createReflections(File).
      Returns:
      true the class path of the reflections is made of unpacked class files, true if the classpath was constructed directly from a JAR file.

    • getBundleProperties

      public static List<IBundleProperties> getBundleProperties(org.reflections.Reflections reflect)
      Method to load IBundleProperties from the given Reflections
      Parameters:
      reflect - Reflections
      Returns:
      IBundleProperties

    • createReflections

      public static org.reflections.Reflections createReflections(File file) throws IOException
      Creates reflections for the given file if it is an jar
      Parameters:
      file - The JAR file with the from the plugin.
      Returns:
      A reflections instance for scanning the plugin for classes and resources.
      Throws:
      MalformedURLException - if the file URL is malformed
      IOException - If the JAR file was not unpacked yet and unpacking failed.

    • getAllPlugins

      public static List<? extends Class<? extends IFCPlugin>> getAllPlugins(org.reflections.Reflections reflect)

    • getAllPlugins

      public static List<? extends Class<? extends IFCPlugin>> getAllPlugins(PluginRuntime pluginRuntime)

    • hasRemotePlugins

      public static boolean hasRemotePlugins(org.reflections.Reflections reflect)

    • hasServerTypeAnnotation

      public static boolean hasServerTypeAnnotation(org.reflections.Reflections reflections)
      Checks for FcServerType annotation inside a given Reflections object.
      Parameters:
      reflections - Reflection data obtained from scanning the classes.
      Returns:
      true if any FcServerType annotation was found, otherwise false

    • getDisplayName

      public static String getDisplayName(IFCPlugin plugin, Locale locale)
      Returns the display name of the plugin if it is not null. Otherwise returns the plugin name.
      Parameters:
      plugin - IFCPlugin to get display name for
      locale - Locale to get display name for
      Returns:
      plugin display name or plugin name if plugin display name is null

    • createPluginErrorProtocolEntry

      public static void createPluginErrorProtocolEntry(PluginRuntime pluginRuntime, DefaultPluginLifecycleData lifecycleData, Throwable error, boolean install, boolean initialize)

    • isPluginNotAllowedOnServer

      public static boolean isPluginNotAllowedOnServer(EFcServerType serverType, EPluginServerRestrictionType serverRestrictionType)

    • removeJarFileCacheEntries

      @Deprecated public static void removeJarFileCacheEntries(JarFile jarToDelete)
      Deprecated.

    • getScopeKey

      @Deprecated public static String getScopeKey(Mandant man)
      Deprecated.

    • getPluginFolder

      @Deprecated public static File getPluginFolder(PluginRuntime runtime)
      Deprecated.

    • getPluginFolder

      @Deprecated public static File getPluginFolder(String scopeKey, String runtimeKey)
      Deprecated.

    • getPluginPropertiesFile

      @Deprecated public static File getPluginPropertiesFile(PluginRuntime rtm)
      Deprecated.

    • getPluginPropertiesFile

      @Deprecated public static File getPluginPropertiesFile(String scopeKey, String runtimeKey)
      Deprecated.

    • getPluginMetaFile

      @Deprecated public static File getPluginMetaFile(PluginRuntime rtm)
      Deprecated.

    • getPluginMetaFile

      @Deprecated public static File getPluginMetaFile(String scopeKey, String runtimeKey)
      Deprecated.

    • getPluginJarFile

      @Deprecated public static File getPluginJarFile(PluginRuntime rtm)
      Deprecated.

    • getPluginJarFile

      @Deprecated public static File getPluginJarFile(String scopeKey, String runtimeKey)
      Deprecated.

    • savePluginProperties

      @Deprecated public static void savePluginProperties(PluginRuntime rtm, Properties props) throws IOException
      Deprecated.
      Throws:
      IOException

    • savePluginProperties

      @Deprecated public static void savePluginProperties(String scopeKey, String runtimeKey, Properties props) throws IOException
      Deprecated.
      Throws:
      IOException

    • getPluginProperties

      @Deprecated public static de.xima.cmn.props.FileBasedPropertiesConfiguration getPluginProperties(PluginRuntime rtm)
      Deprecated.

    • getPluginProperties

      @Deprecated public static de.xima.cmn.props.FileBasedPropertiesConfiguration getPluginProperties(String scopeKey, String runtimeKey)
      Deprecated.