Package org.omegazero.common.plugins

Class Plugin

java.lang.Object
org.omegazero.common.plugins.Plugin
public abstract class Plugin extends Object
Represents a plugin managed by a PluginManager.

Plugins are JAR files or directories containing class files. A plugin must have a file called plugin.cfg in its root directory, containing metadata about the plugin.

The metadata file is a list of key-value pairs. Each pair is separated by one or more newline characters. The key must consist only of alphanumeric characters, followed by a =, and the value, which has different character restrictions depending on the key. The following keys are defined:

keyMeaningRequiredAllowed characters
idThe unique ID of the pluginyesalphanumeric, -, _
nameThe name of the pluginnoalphanumeric, various special characters
versionA version stringnoalphanumeric, -, _, ., +
descriptionA descriptionnoany
mainClassThe main class of the pluginyesJava identifier characters
Other keys not listed in this table are stored and may be retrieved using getAdditionalOption(String).
Since:
2.2

  • Constructor Details

  • Method Details

    • loadClass

      protected abstract Plugin.LoadedClassFile loadClass(String relativePath) throws IOException
      Loads the file in this Plugin's root identified by the given path and stores its data and additional information in the returned LoadedClassFile.

      The file need not be a valid class file. If the file does not exist, null is returned.

      Parameters:
      relativePath - The relative file path
      Returns:
      The LoadedClassFile representing the file, or null if it does not exist
      Throws:
      IOException - If an IO error occurs
      Since:
      2.8
      See Also:

    • loadFile

      public byte[] loadFile(String relativePath) throws IOException
      Loads the file in this Plugin's root identified by the given path.

      If the file does not exist, null is returned.

      Parameters:
      relativePath - The relative file path
      Returns:
      The file content
      Throws:
      IOException - If an IO error occurs
      Since:
      2.8
      See Also:

    • init

      public void init()
      Loads the metadata file and main class of this Plugin.

    • initPluginConfig

      public void initPluginConfig(ConfigObject config)
      Applies the given config data to this plugin's object.

      First, ConfigObject.populateConfigurationOptions(Object) is called on this plugin's main class instance. Then, if a method with the ExtendedPluginConfiguration annotation and a single parameter of type ConfigObject is found, it is called with the given config.

      Parameters:
      config - The configuration data
      Throws:
      ConfigurationException - If the ExtendedPluginConfiguration method threw an exception
      ConfigurationException - If a value has the incorrect type, or the value of a required option is missing
      ConfigurationException - If a reflective operation fails
      UnsupportedOperationException - If a field type is unsupported
      Since:
      2.10

    • getId

      public String getId()
      The plugin ID is a string given in the plugin metadata file consisting only of upper- or lowercase letters and numbers.

      If a PluginManager is used to load multiple plugins, it will ensure that an ID is unique among all plugins.

      Returns:
      The unique ID of this plugin

    • getName

      public String getName()
      Returns the name of this plugin. If no name was set in the metadata file or init() was not called, a name will be inferred from the path given in the constructor.
      Returns:
      The name of this plugin

    • getVersion

      public String getVersion()
      Returns the version string set in the metadata file or null if none was set.
      Returns:
      The version string

    • getDescription

      public String getDescription()
      Returns a description provided in the metadata file or null if none was provided.
      Returns:
      The description

    • getAdditionalOption

      public String getAdditionalOption(String key)
      Returns the value of an unrecognized option in the metadata file.
      Parameters:
      key - The key
      Returns:
      The value

    • getMainClassType

      public Class<?> getMainClassType()
      Returns the type of the main class of this Plugin, loaded by the class loader passed in the constructor.
      Returns:
      The type
      Throws:
      IllegalStateException - If init() was not called successfully prior to calling this method

    • getMainClassInstance

      public Object getMainClassInstance()
      Returns the instance of the main class of this Plugin.
      Returns:
      The instance
      Throws:
      IllegalStateException - If init() was not called successfully prior to calling this method