From: Mateusz Warowny Date: Thu, 17 Feb 2022 15:45:52 +0000 (+0100) Subject: JAL-3878 Create action and task interfaces. X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=0e57ef3caba774a70d099e7d6f9a0674d92d666b;p=jalview.git 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 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 + * task result type + */ +public interface ActionI +{ + /** + * 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 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 perform(AlignmentViewport viewport, List args, + Credentials credentials, TaskEventListener 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 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 + * task result type + */ +public interface TaskI +{ + /** + * 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 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 --- 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 +public class WebService { - public static class Builder + public static class Builder { private URL url; @@ -137,7 +137,7 @@ public class WebService this.actionClass = builder.actionClass; } - public static Builder newBuilder() + public static Builder newBuilder() { return new Builder(); } diff --git a/src/jalview/ws2/common/CredentialType.java b/src/jalview/ws2/common/CredentialType.java new file mode 100644 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; +}