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 Summary

Modifier and Type	Method and Description
StoragePlugins	bootstrapPlugins() When starting a new installation, called to load bootstrap plugins (configurations) that come "out-of-the-box."
void	close()
Set<Class<? extends StoragePluginConfig>>	configClasses() Return the set of known storage plugin configuration classes for which the user can create configs.
Class<? extends StoragePlugin>	connectorClassFor(Class<? extends StoragePluginConfig> configClass) Given a configuration class, return the corresponding connector (plugin) class.
StoragePlugin	create(String name, StoragePluginConfig pluginConfig) Create a connector instance given a named configuration.
StoragePlugin	get(String name) Retrieve an instance of the named connector with default configuration.
void	init() Initialize the locator.
Collection<StoragePlugin>	intrinsicPlugins() Enumerate the intrinsic plugins.
void	onUpgrade() If updatedPlugins() returned non-null, then the registry will call this method after successful update of the persistent store.
boolean	storable()
StoragePlugins	updatedPlugins() Identify plugins to be added to an existing system, typically on the first run after an upgrade.

Method Detail

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()