src/jalview/ws2/actions/api/ActionI.java

   1 package jalview.ws2.actions.api;
   2
   3 import java.util.EnumSet;
   4 import java.util.List;
   5
   6 import jalview.viewmodel.AlignmentViewport;
   7 import jalview.ws.params.ArgumentI;
   8 import jalview.ws2.api.Credentials;
   9 import jalview.ws2.common.CredentialType;
  10
  11 /**
  12  * {@code Action} object represents an executable action that the web service
  13  * can perform. Actions are factories for {@link TaskI} objects which are
  14  * created by {@link #perform} method. Actions are instantiated by
  15  * {@link WebServiceDiscovererI} from the service definition obtained from the
  16  * server and are added to and provided by the {@link WebService}.
  17  *
  18  * Majority of web services will have a single action only, however multiple
  19  * actions providing variation to job execution are possible e.g. align and
  20  * realign actions of ClustalO service.
  21  *
  22  * @author mmwarowny
  23  *
  24  * @param <T>
  25  *          task result type
  26  */
  27 public interface ActionI<T>
  28 {
  29   /**
  30    * Get the name of the action. Typically, it should be the same as the name of
  31    * the service.
  32    *
  33    * @return action name
  34    */
  35   String getName();
  36
  37   /**
  38    * Get the tooltip for the action which contains extra details about the
  39    * action.
  40    *
  41    * @return action tooltip
  42    */
  43   String getToolip();
  44
  45   /**
  46    * Get the subcategory this action belongs to. Can be used to group or
  47    * separate multiple actions.
  48    *
  49    * @return action subcategory
  50    */
  51   String getSubcategory();
  52
  53   /**
  54    * Get the minimum number of sequences this action requires to run or -1 for
  55    * no minimum. Actions may still run if the requirement is not met, but may
  56    * produce meaningless results.
  57    *
  58    * @return minimum required number of sequences
  59    */
  60   int getMinSequences();
  61
  62   /**
  63    * Get the maximum number of sequences this action requires to run or -1 for
  64    * no maximum. Actions may still run if the requirement is not met, but may
  65    * produce meaningless or incomplete results.
  66    *
  67    * @return maximum required number of sequences
  68    */
  69   int getMaxSequences();
  70
  71   /**
  72    * Return if this action allows protein sequences.
  73    *
  74    * @return {@code true} if protein sequences are allowed
  75    */
  76   boolean doAllowProtein();
  77
  78   /**
  79    * Return if this action allows nucleotide sequences.
  80    *
  81    * @return {@code true} if nucleotide sequences are allowed
  82    */
  83   boolean doAllowNucleotide();
  84
  85   /**
  86    * Get the set of credentials required to run the action.
  87    *
  88    * @return required credentials
  89    */
  90   EnumSet<CredentialType> getRequiredCredentials();
  91
  92   /**
  93    * Run the action, create and start a new task with provided viewport,
  94    * arguments and credentials and attach the handler to the task. The
  95    * implementations of this method are responsible for starting the task using
  96    * execution method appropriate for the action class.
  97    *
  98    * @param viewport
  99    *          current alignment viewport
 100    * @param args
 101    *          job parameters appropriate for the service
 102    * @param credentials
 103    *          optional user credentials
 104    * @param handler
 105    *          event handler attached to the new task
 106    * @return new running task
 107    */
 108   TaskI<T> perform(AlignmentViewport viewport, List<ArgumentI> args,
 109       Credentials credentials, TaskEventListener<T> handler);
 110
 111   /**
 112    * Return if the action is currently active for the given viewport. Active
 113    * actions refer to interactive services which are registered to run
 114    * repeatedly on viewport changes. This method has no use for one-shot
 115    * services and should always return {@code false} in that case.
 116    *
 117    * @param viewport
 118    *          viewport being checked for interactive services
 119    * @return if there are interactive services registered for viewport
 120    */
 121   boolean isActive(AlignmentViewport viewport);
 122 }