package jalview.ws2.actions.api;

import java.util.EnumSet;
import java.util.List;

import jalview.viewmodel.AlignmentViewport;
import jalview.ws.params.ArgumentI;
import jalview.ws2.api.Credentials;
import jalview.ws2.common.CredentialType;

/**
 * {@code Action} object represents an executable action that the web service
 * can perform. Actions are factories for {@link TaskI} objects which are
 * created by {@link #perform} method. Actions are instantiated by
 * {@link WebServiceDiscovererI} from the service definition obtained from the
 * server and are added to and provided by the {@link WebService}.
 * 
 * Majority of web services will have a single action only, however multiple
 * actions providing variation to job execution are possible e.g. align and
 * realign actions of ClustalO service.
 * 
 * @author mmwarowny
 *
 * @param <T>
 *          task result type
 */
public interface ActionI<T>
{
  /**
   * Get the name of the action. Typically, it should be the same as the name of
   * the service.
   * 
   * @return action name
   */
  String getName();

  /**
   * Get the tooltip for the action which contains extra details about the
   * action.
   * 
   * @return action tooltip
   */
  String getToolip();

  /**
   * Get the subcategory this action belongs to. Can be used to group or
   * separate multiple actions.
   * 
   * @return action subcategory
   */
  String getSubcategory();

  /**
   * Get the minimum number of sequences this action requires to run or -1 for
   * no minimum. Actions may still run if the requirement is not met, but may
   * produce meaningless results.
   * 
   * @return minimum required number of sequences
   */
  int getMinSequences();

  /**
   * Get the maximum number of sequences this action requires to run or -1 for
   * no maximum. Actions may still run if the requirement is not met, but may
   * produce meaningless or incomplete results.
   * 
   * @return maximum required number of sequences
   */
  int getMaxSequences();

  /**
   * Return if this action allows protein sequences.
   * 
   * @return {@code true} if protein sequences are allowed
   */
  boolean doAllowProtein();

  /**
   * Return if this action allows nucleotide sequences.
   * 
   * @return {@code true} if nucleotide sequences are allowed
   */
  boolean doAllowNucleotide();

  /**
   * Get the set of credentials required to run the action.
   * 
   * @return required credentials
   */
  EnumSet<CredentialType> getRequiredCredentials();

  /**
   * Run the action, create and start a new task with provided viewport,
   * arguments and credentials and attach the handler to the task. The
   * implementations of this method are responsible for starting the task using
   * execution method appropriate for the action class.
   * 
   * @param viewport
   *          current alignment viewport
   * @param args
   *          job parameters appropriate for the service
   * @param credentials
   *          optional user credentials
   * @param handler
   *          event handler attached to the new task
   * @return new running task
   */
  TaskI<T> perform(AlignmentViewport viewport, List<ArgumentI> args,
      Credentials credentials, TaskEventListener<T> handler);

  /**
   * Return if the action is currently active for the given viewport. Active
   * actions refer to interactive services which are registered to run
   * repeatedly on viewport changes. This method has no use for one-shot
   * services and should always return {@code false} in that case.
   * 
   * @param viewport
   *          viewport being checked for interactive services
   * @return if there are interactive services registered for viewport
   */
  boolean isActive(AlignmentViewport viewport);
}