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