package plugin11g;

import oracle.AWXML.AW;
import java.awt.Frame;
import java.sql.Connection;
import java.util.Map;

/**
 * On startup, Analytic Workspace Manager looks for classes that implement this
 * interface.
 * It then calls the isSupported method of those classes.
 * For objects in the Analytic Workspace Manager navigation tree that a plugin
 * supports, Analytic Workspace Manager calls the getMenu method and displays
 * on the right-click menu the value returned by method.
 * When a user selects the plugin from the menu, Analytic Workspace Manager
 * calls the handle method, which implements the actions of the plugin.
 * Finally, Analytic Workspace Manager calls the refreshTree method of the
 * plugin to find out if the plugin wants it to refresh the view of the
 * navigation tree to add any metadata objects that the plugin created.
 *
 * When Analytic Workspace Manager calls those methods, it passes them the
 * following objects:
 *
 * - For the conn parameter, it passes a java.sql.Connection object that
 *   represents the current connection of the Analytic Workspace Manager
 *   to the Oracle Database instance.
 * - For the type parameter, it passes a String that is a type classification
 *   that Analytic Workspace Manager assigns to the metadata object.
 * - For the obj parameter, it passes An Oracle OLAP metadata object, a
 *   String, or null.
 * - For the aw parameter, in a 10.2.0.3 session, it passes an AWXML.AW
 *   object.
 *   In an 11g session, it passes null as the value of this parameter.
 * - For the params parameter, in a 10.2.0.3 session it passes null.
 *   In an 11g session, it passes a Map. The Map has two key/object pairs:
 *   o The String "DATASOURCE" is the key for a java.sql.DataSource object.
 *   o The String "DATAPROVIDER" is the key for an
 *     oracle.olapi.metadata.mdm.MdmMetadataProvider object.
 *
 * As the parent parameter of the handle method, Analytic Workspace Manager
 * passes a Frame that the plugin can use as the parent Frame for graphical
 * user interface components.
 */
public interface AWMPlugin
{
  /**
   * Specifies the metadata objects that are supported by the plug-in.
   *
   * @param conn The Connection to an Oracle Database instance.
   * @param type A String that designates a type assigned by Analytic Workspace
   *             Manager.
   * @param obj An Oracle OLAP Java API metadata object, a String that Analytic
   *            Workspace Manager associates with the selected navigation tree
   *            object, or null.
   * @param aw For a 10g session, the current analytic workspace.
   *           For an 11g session, null.
   * @param params For an 10g session, null.
   *               For an 11g session, a Map that contains an
   *               MdmMetadataProvider and a DataSource.
   *
   * @return A boolean that is true if Analytic Workspace Manager should display
   *         the plug-in on the menu for the selected object or false if it
   *         should not.
   */
  boolean isSupported(Connection conn, String type, Object obj, AW aw,
                      Map params);

  /**
   * Gets the text to display for the plug-in on the right-click menu of the
   * selected object in the navigation tree.
   *
   * @param conn The Connection to an Oracle Database instance.
   * @param type A String that designates a type assigned by Analytic Workspace
   *             Manager.
   * @param obj An Oracle OLAP Java API metadata object, a String that Analytic
   *            Workspace Manager associates with the selected navigation tree
   *            object, or null.
   * @param aw For a 10g session, the current analytic workspace.
   *           For an 11g session, null.
   * @param params For an 10g session, null.
   *               For an 11g session, a Map that contains an
   *               MdmMetadataProvider and a DataSource.
   *
   * @return A String the contains the text that Analytic Workspace Manager
   *         displays on the right-click menu.
   */
  String getMenu(Connection conn, String type, Object obj, AW aw, Map params);

  /**
   * Specifies the actions to take when the user selects the plug-in from
   * the navigation tree right-click menu.
   *
   * @param parent A Frame that the plug-in can use as the parent for a
   *               graphical user interface.
   * @param conn The Connection to an Oracle Database instance.
   * @param type A String that designates a type assigned by Analytic Workspace
   *             Manager.
   * @param obj An Oracle OLAP Java API metadata object, a String that Analytic
   *            Workspace Manager associates with the selected navigation tree
   *            object, or null.
   * @param aw For an 11g session, Analytic Workspace Manager passes null
   *           for this parameter.
   * @param params For an 10g session, null.
   *               For an 11g session, a Map that contains an
   *               MdmMetadataProvider and a DataSource.
   */
  void handle(Frame parent, Connection conn, String type, Object obj, AW aw,
              Map params);

  /**
   * Specifies whether or not to refresh the navigation tree of Analytic
   * Workspace Manager.
   * If a plug-in creates new Oracle OLAP metadata objects, this method should
   * return true.
   *
   * @param conn The Connection to an Oracle Database instance.
   * @param type A String that designates a type assigned by Analytic Workspace
   *             Manager.
   * @param obj An Oracle OLAP Java API metadata object, a String that Analytic
   *            Workspace Manager associates with the selected navigation tree
   *            object, or null.
   * @param aw For an 11g session, Analytic Workspace Manager passes null
   *           for this parameter.
   * @param params For an 10g session, null.
   *               For an 11g session, a Map that contains an
   *               MdmMetadataProvider and a DataSource.
   *
   * @return A boolean that is true to have Analytic Workspace Manager refresh
   *         the navigation tree, or false otherwise.
   */
  boolean refreshTree(Connection conn, String type, Object obj, AW aw,
                      Map params);
}