/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.drill.exec.store;

import java.io.IOException;
import java.util.Collection;
import java.util.Set;

import org.apache.drill.common.exceptions.ExecutionSetupException;
import org.apache.drill.common.logical.StoragePluginConfig;
import org.apache.drill.exec.planner.logical.StoragePlugins;

/**
 * Locates storage plugins. Allows multiple ways of finding plugins.
 * <p>
 * Terminology is a bit tortured. Drill overuses the term "plugin."
 * Here we adopt the following conventions:
 * <dl>
 * <dt>(storage) plugin</dt>
 * <dd>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.
 * </dd>
 * <dl>
 * <p>
 * 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.
 * <p>
 * Connectors can define bootstrap or upgrade plugin sets. "Normal"
 * plugins usually provide bootstrap configs, system plugins do not.
 * <p>
 * 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.
 */
// TODO: Sort out error handling. Some method throw IOException, some
// throw unchecked exceptions.
public interface ConnectorLocator {

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

  /**
   * When starting a new installation, called to load bootstrap
   * plugins (configurations) that come "out-of-the-box."
   *
   * @return the set of bootstrap plugins, or {@code null} if this locator
   * does not provide bootstrap plugins
   * @throws IOException
   */
  StoragePlugins bootstrapPlugins() throws IOException;

  /**
   * Identify plugins to be added to an existing system, typically
   * on the first run after an upgrade.
   * <p>
   * 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.
   *
   * @return the set of plugin configurations to refresh in the
   * persistent store, or null if none to update
   * @throws IOException for errors
   */
  StoragePlugins updatedPlugins();

  /**
   * If {@code 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.
   */
  void onUpgrade();

  /**
   * 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.
   *
   * @return map of intrinsic plugins which require no configuration
   */
  Collection<StoragePlugin> intrinsicPlugins();

  /**
   * Retrieve an instance of the named connector with default configuration.
   * Typically used for connectors with no configuration, such as system
   * storage plugins.
   *
   * @param name the name of a <i>connector class</i> (not the name of
   * a plugin (configuration)
   * @return a plugin with default configuration, or null if this locator does
   * not support such plugins
   */
  StoragePlugin get(String name);

  /**
   * 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.
   *
   * @return the unuordered set of storage plugin configuration classes
   * available from this locator. Can be null if this locator offers
   * only system plugins
   */
  Set<Class<? extends StoragePluginConfig>> configClasses();

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

  /**
   * @return true if configs for this locator should be persisted, false if
   * these are ad-hoc or otherwise per-run connectors
   */
  boolean storable();

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

  void close();
}