JAL-3878 Create action and task interfaces.

diff --git a/src/jalview/ws2/actions/api/ActionI.java b/src/jalview/ws2/actions/api/ActionI.java
new file mode 100644 (file)
index 0000000..4b47e94
--- /dev/null
+++ b/src/jalview/ws2/actions/api/ActionI.java
@@ -0,0 +1,122 @@
+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);
+}

diff --git a/src/jalview/ws2/actions/api/TaskI.java b/src/jalview/ws2/actions/api/TaskI.java
new file mode 100644 (file)
index 0000000..3a3fcbb
--- /dev/null
+++ b/src/jalview/ws2/actions/api/TaskI.java
@@ -0,0 +1,43 @@
+package jalview.ws2.actions.api;
+
+import java.util.List;
+
+import jalview.viewmodel.AlignmentViewport;
+import jalview.ws2.api.JobStatus;
+import jalview.ws2.client.api.WebServiceJob;
+
+/**
+ * {@code TaskI} objects represent running services. Tasks are created by
+ * concrete implementations of {@link ActionI} and provide a view of the state
+ * of the underlying job(s).
+ * 
+ * @author mmwarowny
+ *
+ * @param <T>
+ *          task result type
+ */
+public interface TaskI<T>
+{
+  /**
+   * Get the current status of the task. The resultant status should be
+   * a combination of individual sub-job statuses. 
+   * 
+   * @return global status of 
+   */
+  JobStatus getStatus();
+
+  /**
+   * Get the current list of sub-jobs of that task.
+   *  
+   * @return sub-jobs
+   */
+  List<? extends WebServiceJob> getSubJobs();
+
+  /**
+   * Get the last result of the task or {@code null} if not present.
+   * Note that the result is subject to change for restartable tasks.
+   * 
+   * @return last task result
+   */
+  T getResult();
+}

diff --git a/src/jalview/ws2/api/WebService.java b/src/jalview/ws2/api/WebService.java
index 946b7ec..6de3acd 100644 (file)
--- a/src/jalview/ws2/api/WebService.java
+++ b/src/jalview/ws2/api/WebService.java
@@ -5,13 +5,13 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import jalview.ws.params.ParamDatastoreI;
-import jalview.ws2.actions.Action;
+import jalview.ws2.actions.api.ActionI;
 
 import static java.util.Objects.requireNonNull;
 
-public class WebService<T extends Action>
+public class WebService<T extends ActionI>
 {
-  public static class Builder<T extends Action>
+  public static class Builder<T extends ActionI>
   {
     private URL url;
 
@@ -137,7 +137,7 @@ public class WebService<T extends Action>
     this.actionClass = builder.actionClass;
   }
   
-  public static <T extends Action> Builder<T> newBuilder()
+  public static <T extends ActionI> Builder<T> newBuilder()
   {
     return new Builder<T>();
   }

diff --git a/src/jalview/ws2/common/CredentialType.java b/src/jalview/ws2/common/CredentialType.java
new file mode 100644 (file)
index 0000000..a9b87ee
--- /dev/null
+++ b/src/jalview/ws2/common/CredentialType.java
@@ -0,0 +1,6 @@
+package jalview.ws2.common;
+
+public enum CredentialType
+{
+  EMAIL, USERNAME, PASSWORD;
+}