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