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