PluginConfigurer.java

/*
 * Copyright © 2015 Cask Data, Inc.
 *
 * Licensed 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 co.cask.cdap.api.plugin;

import co.cask.cdap.api.DatasetConfigurer;

import javax.annotation.Nullable;

/**
 * This interface provides methods to register plugin usage in a CDAP Program. The registered plugins will be
 * available at the runtime of the Program.
 */
public interface PluginConfigurer extends DatasetConfigurer {
  /**
   * Adds a Plugin usage to the Application and create a new instance.
   * The Plugin will be accessible at execution time via the {@link PluginContext}.
   *
   * @param pluginType plugin type name
   * @param pluginName plugin name
   * @param pluginId an unique identifier for this usage. The same id is used to get the plugin at execution time.
   * @param properties properties for the plugin. The same set of properties will be used to instantiate the plugin
   *                   instance at execution time
   * @param <T> type of the plugin class
   * @return A new instance of the plugin class or {@code null} if no plugin was found
   * @throws IllegalArgumentException if the pluginId has been used already
   */
  @Nullable
  <T> T usePlugin(String pluginType, String pluginName, String pluginId, PluginProperties properties);

  /**
   * Adds a Plugin usage to the Application and create a new instance.
   * The Plugin will be accessible at execution time via the {@link PluginContext}.
   *
   * @param pluginType plugin type name
   * @param pluginName plugin name
   * @param pluginId an unique identifier for this usage. The same id is used to get the plugin at execution time.
   * @param properties properties for the plugin. The same set of properties will be used to instantiate the plugin
   *                   instance at execution time
   * @param selector for selecting which plugin to use
   * @param <T> type of the plugin class
   * @return A new instance of the plugin class or {@code null} if no plugin was found
   * @throws IllegalArgumentException if the pluginId has been used already
   */
  @Nullable
  <T> T usePlugin(String pluginType, String pluginName,
                  String pluginId, PluginProperties properties, PluginSelector selector);

  /**
   * Adds a Plugin usage to the Application.
   * The Plugin will be accessible at execution time via the {@link PluginContext}.
   *
   * @param pluginType plugin type name
   * @param pluginName plugin name
   * @param pluginId an unique identifier for this usage. The same id is used to get the plugin at execution time.
   * @param properties properties for the plugin. The same set of properties will be used to instantiate the plugin
   *                   instance at execution time
   * @param <T> type of the plugin class
   * @return A {@link Class} for the plugin class or {@code null} if no plugin was found
   * @throws IllegalArgumentException if the pluginId has been used already
   */
  @Nullable
  <T> Class<T> usePluginClass(String pluginType, String pluginName, String pluginId, PluginProperties properties);

  /**
   * Adds a Plugin usage to the Application.
   * The Plugin will be accessible at execution time via the {@link PluginContext}.
   *
   * @param pluginType plugin type name
   * @param pluginName plugin name
   * @param pluginId an unique identifier for this usage. The same id is used to get the plugin at execution time.
   * @param properties properties for the plugin. The same set of properties will be used to instantiate the plugin
   *                   instance at execution time
   * @param selector for selecting which plugin to use
   * @param <T> type of the plugin class
   * @return A {@link Class} for the plugin class or {@code null} if no plugin was found
   * @throws IllegalArgumentException if the pluginId has been used already
   */
  @Nullable
  <T> Class<T> usePluginClass(String pluginType, String pluginName,
                              String pluginId, PluginProperties properties, PluginSelector selector);
}