org.apache.drill.exec.store

Interface StoragePluginRegistry

All Superinterfaces:

AutoCloseable, Iterable<Map.Entry<String,StoragePlugin>>

All Known Implementing Classes:

StoragePluginRegistryImpl

public interface StoragePluginRegistry
extends Iterable<Map.Entry<String,StoragePlugin>>, AutoCloseable

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	StoragePluginRegistry.PluginEncodingException Indicates an error when decoding a plugin from JSON.
static class	StoragePluginRegistry.PluginException
static class	StoragePluginRegistry.PluginFilter
static class	StoragePluginRegistry.PluginNotFoundException Indicates the requested plugin was not found.

Field Summary

Fields

Modifier and Type	Field and Description
static String	PSTORE_NAME

Method Summary

Modifier and Type	Method and Description
Set<String>	availablePlugins() Returns the set of available plugin names.
StoragePluginConfig	copyConfig(StoragePluginConfig config) Copy the given storage plugin config so it may be modified.
StoragePluginConfig	copyConfig(String name) Copy a stored config so that it can be modified.
StoragePluginConfig	decode(String json) Return a config decoded from JSON.
Map<String,StoragePluginConfig>	enabledConfigs() Returns a copy of the set of enabled stored plugin configurations.
String	encode(StoragePluginConfig config)
String	encode(String name) Return a config encoded as JSON.
StoragePluginConfig	getDefinedConfig(String name) Retrieve an available configuration.
FormatPlugin	getFormatPlugin(StoragePluginConfig storageConfig, FormatPluginConfig formatConfig) Deprecated. use resolveFormat(StoragePluginConfig, FormatPluginConfig, Class) which provides type safety. Retained for compatibility with older plugins
FormatPlugin	getFormatPluginByConfig(StoragePluginConfig storageConfig, FormatPluginConfig formatConfig) Get the Format plugin for the FileSystemPlugin associated with the provided storage config and format config.
StoragePlugin	getPlugin(StoragePluginConfig config) Deprecated. use resolve(StoragePluginConfig, Class) which provides type safety. Retained for compatibility with older plugins
StoragePlugin	getPlugin(String name) Get a plugin by name.
StoragePlugin	getPluginByConfig(StoragePluginConfig config) Get a plugin by configuration.
SchemaFactory	getSchemaFactory() Get the Schema factory associated with this storage plugin registry.
StoragePluginConfig	getStoredConfig(String name) Return a plugin from persistent storage.
void	init() Initialize the storage plugin registry.
com.fasterxml.jackson.databind.ObjectMapper	mapper() Object mapper to read/write the JSON form of a plugin.
void	put(String name, StoragePluginConfig config) Store a plugin by name and configuration.
void	putFormatPlugin(String pluginName, String formatName, FormatPluginConfig formatConfig) Safe way to add or remove a format plugin config from a stored file system configuration.
void	putJson(String name, String json) Put a storage plugin config from JSON.
void	remove(String name) Remove a plugin by name
<T extends StoragePlugin> T	resolve(StoragePluginConfig storageConfig, Class<T> desired)
<T extends FormatPlugin> T	resolveFormat(StoragePluginConfig storageConfig, FormatPluginConfig formatConfig, Class<T> desired) Resolve a storage plugin given a storage plugin config.
void	setEnabled(String name, boolean enabled) Set the plugin to the requested enabled state.
Map<String,StoragePluginConfig>	storedConfigs() Returns a set of all stored plugin configurations, directly from the persistent store.
Map<String,StoragePluginConfig>	storedConfigs(StoragePluginRegistry.PluginFilter filter) Return a possibly-filtered set of plugins from the persistent store.
void	validatedPut(String name, StoragePluginConfig config) Like put(String, StoragePluginConfig), but forces instantiation of the plugin to verify that the configuration is valid at this moment in time.

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Methods inherited from interface java.lang.AutoCloseable

close

Field Detail

PSTORE_NAME

static final String PSTORE_NAME

See Also:

Constant Field Values

Method Detail

init

void init()

Initialize the storage plugin registry. Must be called before the registry is used.

put

void put(String name,
         StoragePluginConfig config)
  throws StoragePluginRegistry.PluginException

Store a plugin by name and configuration. If the plugin already exists, update the plugin. This form directly updates persistent storage. The in-memory cache is updated on the next refresh. This form will accept an invalid plugin, which will be disabled upon refresh. Since Drill is distributed, and plugins work with external systems, the external system can become invalid at any moment (not just when pugins are updated), so the model used for put() mimics normal runtime operation.

Parameters:

name - The name of the plugin

config - The plugin configuration

Throws:

StoragePluginRegistry.PluginException - if plugin cannot be created

validatedPut

void validatedPut(String name,
                  StoragePluginConfig config)
           throws StoragePluginRegistry.PluginException

Like put(String, StoragePluginConfig), but forces instantiation of the plugin to verify that the configuration is valid at this moment in time.

Throws:

StoragePluginRegistry.PluginException

setEnabled

void setEnabled(String name,
                boolean enabled)
         throws StoragePluginRegistry.PluginException

Set the plugin to the requested enabled state. Does nothing if the plugin is already in the requested state. If a formerly enabled plugin is disabled, moves the plugin from the in-memory cache to the ephemeral store. If a formerly disabled plugin is enabled, verifies that the plugin can be instantiated as for #verifiedPut().

Use this method when changing state. Do not obtain the config and change the state directly, doing so will make the plugin config inconsistent with the internal state.

Parameters:

name - name of the plugin

enabled - true to enable the plugin, false to disable

Throws:

StoragePluginRegistry.PluginNotFoundException - if the plugin is not found

StoragePluginRegistry.PluginException - if the plugin name is not valid or if enabling a plugin and the plugin is not valid

getPlugin

StoragePlugin getPlugin(String name)
                 throws StoragePluginRegistry.PluginException,
                        UserException

Get a plugin by name. Create it based on the PStore saved definition if it doesn't exist.

Parameters:

name - The name of the plugin

Returns:

The StoragePlugin instance.

Throws:

StoragePluginRegistry.PluginException - if plugin cannot be obtained

UserException

getPluginByConfig

StoragePlugin getPluginByConfig(StoragePluginConfig config)
                         throws StoragePluginRegistry.PluginException

Get a plugin by configuration. If it doesn't exist, create it.

Parameters:

config - The configuration for the plugin.

Returns:

The StoragePlugin instance.

Throws:

StoragePluginRegistry.PluginException - if plugin cannot be obtained

getPlugin

@Deprecated
StoragePlugin getPlugin(StoragePluginConfig config)
                             throws ExecutionSetupException

Deprecated. use resolve(StoragePluginConfig, Class) which provides type safety. Retained for compatibility with older plugins

Throws:

ExecutionSetupException

getStoredConfig

StoragePluginConfig getStoredConfig(String name)

Return a plugin from persistent storage. Returns both enabled and disabled stored plugins, but does not return system plugins. Use this to obtain a plugin for editing (rather than for planning or executing a query.)

encode

String encode(String name)
       throws StoragePluginRegistry.PluginException

Return a config encoded as JSON.

Throws:

StoragePluginRegistry.PluginException - if the plugin is undefined

encode

String encode(StoragePluginConfig config)

decode

StoragePluginConfig decode(String json)
                    throws StoragePluginRegistry.PluginEncodingException

Return a config decoded from JSON.

Throws:

StoragePluginRegistry.PluginEncodingException - if the JSON is invalid

putJson

void putJson(String name,
             String json)
      throws StoragePluginRegistry.PluginException

Put a storage plugin config from JSON. Validates the JSON and the resulting storage plugin. Use this form for JSON received from the UI or other external source.

Throws:

IOException - if the JSON is invalid

StoragePluginRegistry.PluginException - if the underlying validatedPut(String, StoragePluginConfig) fails

copyConfig

StoragePluginConfig copyConfig(String name)
                        throws StoragePluginRegistry.PluginException

Copy a stored config so that it can be modified.

Never modify a config stored in the registry! Configs are keyed by name and value; getting a config, then modifying it, will cause the value maps to become out of sync.

Parameters:

name - name of the storage plugin config to copy

Returns:

a copy of the config

Throws:

StoragePluginRegistry.PluginException - if the name is undefined

copyConfig

StoragePluginConfig copyConfig(StoragePluginConfig config)

Copy the given storage plugin config so it may be modified.

Parameters:

config - the storage plugin config to copy

Returns:

the copy

getDefinedConfig

StoragePluginConfig getDefinedConfig(String name)

Retrieve an available configuration. Returns enabled stored plugins and system plugins. These configs are those that can be used to plan a query.

remove

void remove(String name)
     throws StoragePluginRegistry.PluginException

Remove a plugin by name

Parameters:

name - The name of the storage plugin to remove

Throws:

StoragePluginRegistry.PluginException

storedConfigs

Map<String,StoragePluginConfig> storedConfigs()

Returns a set of all stored plugin configurations, directly from the persistent store. Note: the actual configs may reside in the cache; make a copy before making any changes.

Returns:

map of stored plugin configurations

storedConfigs

Map<String,StoragePluginConfig> storedConfigs(StoragePluginRegistry.PluginFilter filter)

Return a possibly-filtered set of plugins from the persistent store.

enabledConfigs

Map<String,StoragePluginConfig> enabledConfigs()

Returns a copy of the set of enabled stored plugin configurations. The registry is refreshed against the persistent store prior to building the map.

Returns:

map of enabled, stored plugin configurations

availablePlugins

Set<String> availablePlugins()

Returns the set of available plugin names. Includes system plugins and enabled stored plugins.

putFormatPlugin

void putFormatPlugin(String pluginName,
                     String formatName,
                     FormatPluginConfig formatConfig)
              throws StoragePluginRegistry.PluginException

Safe way to add or remove a format plugin config from a stored file system configuration. Makes a copy of the config, adds/removes the format plugin, and updates the persistent store with the copy.

Parameters:

pluginName - name of the file system storage plugin config to modify

formatName - name of the format plugin to modify

formatConfig - if null, removes the plugin, if non-null updates the format plugin config with this value

Throws:

StoragePluginRegistry.PluginException - if the storage plugin is undefined or is not a file format plugin

getFormatPluginByConfig

FormatPlugin getFormatPluginByConfig(StoragePluginConfig storageConfig,
                                     FormatPluginConfig formatConfig)
                              throws StoragePluginRegistry.PluginException

Get the Format plugin for the FileSystemPlugin associated with the provided storage config and format config.

Parameters:

storageConfig - The storage config for the associated FileSystemPlugin

formatConfig - The format config for the associated FormatPlugin

Returns:

A FormatPlugin instance

Throws:

StoragePluginRegistry.PluginException - if plugin cannot be obtained

getFormatPlugin

@Deprecated
FormatPlugin getFormatPlugin(StoragePluginConfig storageConfig,
                                         FormatPluginConfig formatConfig)
                                  throws ExecutionSetupException

Deprecated. use resolveFormat(StoragePluginConfig, FormatPluginConfig, Class) which provides type safety. Retained for compatibility with older plugins

Throws:

ExecutionSetupException

getSchemaFactory

SchemaFactory getSchemaFactory()

Get the Schema factory associated with this storage plugin registry.

Returns:

A SchemaFactory that can register the schemas associated with this plugin registry.

mapper

com.fasterxml.jackson.databind.ObjectMapper mapper()

Object mapper to read/write the JSON form of a plugin. config.

resolve

<T extends StoragePlugin> T resolve(StoragePluginConfig storageConfig,
                                    Class<T> desired)

resolveFormat

<T extends FormatPlugin> T resolveFormat(StoragePluginConfig storageConfig,
                                         FormatPluginConfig formatConfig,
                                         Class<T> desired)

Resolve a storage plugin given a storage plugin config. Call from within a file storage plugin to resolve the plugin.

Type Parameters:

T - the required type of the plugin

Parameters:

storageConfig - storage plugin config

formatConfig - format plugin config

desired - desired target class

Returns:

the storage plugin

Throws:

IllegalStateException - if the plugin is unknown or of the wrong format - errors which should never occur in normal operation