com.github.bjoernpetersen.jmusicbot.Plugin Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of musicbot Show documentation
Core library of MusicBot, which plays music from various providers.
There is a newer version: 0.25.0
package com.github.bjoernpetersen.jmusicbot;

import com.github.bjoernpetersen.jmusicbot.config.Config;
import com.github.bjoernpetersen.jmusicbot.config.Config.Entry;
import com.github.bjoernpetersen.jmusicbot.platform.Platform;
import com.github.bjoernpetersen.jmusicbot.platform.Support;
import com.github.zafarkhaja.semver.Version;
import java.io.Closeable;
import java.util.List;
import javax.annotation.Nonnull;

/**
 * Base interface for all plugins. Usually this interface won't be directly implemented, but
 * extended first. Extending interfaces should define a "initialize(InitStateWriter, ...)
 * throws InitializationException" method, which acts as the counterpart to {@link
 * #close()}.
 *
 * Lifecycle:
  {@link #initializeConfigEntries(Config)}
 initialize(...)
 * {@link #close()}
 {@link #destructConfigEntries()}
 
 Note: a
 * successful call to one of the initialization methods guarantees that the respective destruction
 * method will be called in the future.
 */
public interface Plugin extends Closeable {

  /**
   * Initializes the config entries for this plugin.
   *
   * This method should only return config entries introduced by this plugin. If config entries
   * from {@link Config#getDefaults()} are used, they should be excluded from the returned
   * list.
   *
   * If the plugin wants prevent a config entry from being viewed/edited by the user, it can omit
   * it in this list.
   *
   * @param config the config to use
   * @return a list of all config entries relevant only to this plugin.
   */
  @Nonnull
  List initializeConfigEntries(@Nonnull Config config);

  /**
   * Destruct and dereference all entries initialized in {@link #initializeConfigEntries(Config)}.
   */
  void destructConfigEntries();

  /**
   * Gets the config entries which are not configured properly. Might be called multiple times.

   *
   * This will be called between {@link #initializeConfigEntries(Config)} and initialize(...).
   *
   * Note: Config.StringEntry.isNullOrError() might be helpful here.
   *
   * @return a list of config entries
   */
  @Nonnull
  List getMissingConfigEntries();

  /**
   * An arbitrary, human readable name for this plugin.
   *
   * @return a name
   */
  @Nonnull
  String getReadableName();

  /**
   * Indicates whether the specified Platform is supported.
   *
   * If the Platform is Platform.UNKNOWN, this method should return Support.MAYBE.
   *
   * @param platform the current Platform
   * @return the support for the specified platform
   */
  @Nonnull
  Support getSupport(@Nonnull Platform platform);

  /**
   * Gets the minimum supported version of MusicBot.
   *
   * @return a version
   */
  @Nonnull
  default Version getMinSupportedVersion() {
    return MusicBot.getVersion();
  }

  /**
   * Gets the maximum supported version of MusicBot.
   *
   * @return a version of MusicBot
   */
  @Nonnull
  default Version getMaxSupportedVersion() {
    Version version = MusicBot.getVersion();
    if (getMinSupportedVersion().greaterThan(version)) {
      return getMinSupportedVersion();
    } else {
      return version;
    }
  }

  /**
   * The state of a plugin.
   */
  enum State {

    /**
     * The plugin is inactive. Duh.
     */
    INACTIVE,
    /**
     * {@link Plugin#initializeConfigEntries(Config)} has been called, but the initialize method hasn't been.
     */
    CONFIG,
    /**
     * The plugin is fully configured and initialized.
     */
    ACTIVE
  }
}