Package org.apache.drill.exec.store

Interface ConnectorLocator

All Known Implementing Classes:
ClassicConnectorLocator, SystemPluginLocator
public interface ConnectorLocator
Locates storage plugins. Allows multiple ways of finding plugins.

Terminology is a bit tortured. Drill overuses the term "plugin." Here we adopt the following conventions:

(storage) plugin
The user-visible concept of a storage plugin: a configuration with our without its corresponding connector instance. Either an instance of a storage plugin config class, or the same information serialized as JSON. Also, confusingly, "plugin" can also mean the config wrapped in an instance of the connector.

Connectors can be storable in the persistent store. All "normal" connectors have storable configurations. System plugins, however have a fixed config that is not storable.

Connectors can define bootstrap or upgrade plugin sets. "Normal" plugins usually provide bootstrap configs, system plugins do not.

This class instantiates a connector given a configuration and a name. The plugin registry caches the instance for the duration of the Drillbit run, or until the config changes.

  • Method Details

    • init

      void init()
      Initialize the locator. Must be called before the locator is used.

    • bootstrapPlugins

      StoragePlugins bootstrapPlugins() throws IOException
      When starting a new installation, called to load bootstrap plugins (configurations) that come "out-of-the-box."
      Returns:
      the set of bootstrap plugins, or null if this locator does not provide bootstrap plugins
      Throws:
      IOException

    • updatedPlugins

      StoragePlugins updatedPlugins()
      Identify plugins to be added to an existing system, typically on the first run after an upgrade.

      TODO: The current mechanism depends on deleting a file after the first run, which is unreliable. It won't, for example, correctly handle a restored ZK. A better mechanism would store a version number in the persistent store, and pass that version number into this method.

      Returns:
      the set of plugin configurations to refresh in the persistent store, or null if none to update
      Throws:
      IOException - for errors

    • onUpgrade

      void onUpgrade()
      If updatedPlugins() returned non-null, then the registry will call this method after successful update of the persistent store. This method can do any post-update cleanup, such as deleting the file mentioned above.

    • intrinsicPlugins

      Collection<StoragePlugin> intrinsicPlugins()
      Enumerate the intrinsic plugins. An intrinsic plugin is one which takes no configuration and which therefore cannot be disabled, and thus is always available. Example: Drill's system plugins. For an intrinsic plugin, the plugin name is also the name of the configuration.
      Returns:
      map of intrinsic plugins which require no configuration

    • get

      StoragePlugin get(String name)
      Retrieve an instance of the named connector with default configuration. Typically used for connectors with no configuration, such as system storage plugins.
      Parameters:
      name - the name of a connector class (not the name of a plugin (configuration)
      Returns:
      a plugin with default configuration, or null if this locator does not support such plugins

    • configClasses

      Set<Class<? extends StoragePluginConfig>> configClasses()
      Return the set of known storage plugin configuration classes for which the user can create configs. Excludes system plugin configs. Used to map config classes to this locator to create plugin instances.
      Returns:
      the unuordered set of storage plugin configuration classes available from this locator. Can be null if this locator offers only system plugins

    • create

      StoragePlugin create(String name, StoragePluginConfig pluginConfig) throws Exception
      Create a connector instance given a named configuration. The configuration and/or name is used to locate the connector class.
      Parameters:
      name - name of the storage plugin (configuration).
      pluginConfig - the deserialized Java configuration object.
      Returns:
      a connector of the proper class that matches the configuration or name, initialized with the configuration
      Throws:
      ExecutionSetupException - for all errors
      Exception

    • storable

      boolean storable()
      Returns:
      true if configs for this locator should be persisted, false if these are ad-hoc or otherwise per-run connectors

    • connectorClassFor

      Class<? extends StoragePlugin> connectorClassFor(Class<? extends StoragePluginConfig> configClass)
      Given a configuration class, return the corresponding connector (plugin) class.

    • close

      void close()