You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@taverna.apache.org by st...@apache.org on 2018/01/04 14:59:34 UTC
[9/9] incubator-taverna-server git commit: (At least some) Javadoc
(At least some) Javadoc
Project: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/commit/e593ab8e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/tree/e593ab8e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/diff/e593ab8e
Branch: refs/heads/master
Commit: e593ab8ea202a1ed1a2156e9b6c14748392d5776
Parents: 885940f
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Thu Jan 4 14:59:11 2018 +0000
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Thu Jan 4 14:59:11 2018 +0000
----------------------------------------------------------------------
.../taverna/server/client/TavernaServer.java | 71 +++++++++++++++++---
.../client/TavernaServerConnectionFactory.java | 29 ++++++++
2 files changed, 89 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/blob/e593ab8e/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServer.java
----------------------------------------------------------------------
diff --git a/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServer.java b/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServer.java
index 0cb8e6a..932347c 100644
--- a/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServer.java
+++ b/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServer.java
@@ -35,6 +35,20 @@ import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.filter.HTTPBasicAuthFilter;
+/**
+ * Client connection to a Taverna Server.
+ * <p>
+ * To construct a {@link TavernaServer}, use
+ * {@link TavernaServerConnectionFactory}.
+ * <p>
+ * This class provides the general information from the server, e.g.
+ * {@link #getCapabilities()} and {@link #getPermittedWorkflows()}.
+ * <p>
+ * Use {@link #getExistingRuns()} to list existing {@link Run}s, or use
+ * {@link #createWorkflowRun(File)} and friends to create a new run.
+ *
+ * @see TavernaServerConnectionFactory
+ */
public class TavernaServer extends Connected {
final Root root;
private final URI location;
@@ -67,8 +81,7 @@ public class TavernaServer extends Connected {
}
public List<Capability> getCapabilities() {
- return root.policy().capabilities().getAsCapabilitiesXml()
- .getCapability();
+ return root.policy().capabilities().getAsCapabilitiesXml().getCapability();
}
public int getRunLimit() {
@@ -80,8 +93,7 @@ public class TavernaServer extends Connected {
}
public List<String> getPermittedWorkflows() {
- return root.policy().permittedWorkflows().getAsPermittedWorkflowsXml()
- .getWorkflow();
+ return root.policy().permittedWorkflows().getAsPermittedWorkflowsXml().getWorkflow();
}
public List<Run> getExistingRuns() {
@@ -104,21 +116,56 @@ public class TavernaServer extends Connected {
return null;
}
+ /**
+ * Create a new Run by uploading the bytes of a t2flow workflow definition.
+ * <p>
+ * The returned {@link Run} be configured (e.g. with
+ * {@link Run#setInput(String, String)}) before invoking it
+ * with {@link Run#start()}.
+ *
+ * @param t2flowBytes Content of workflow definition file to upload, should be in the format <code>application/vnd.taverna.t2flow+xml</code>
+ * @return A {@link Run} that is {@link Status#Initialized}
+ * @throws ClientException If client configuration failed, e.g. AuthorizationException
+ * @throws ServerException If the server refuses upload (e.g. because only {@link #getPermittedWorkflows()} are allowed)
+ */
public Run createWorkflowRun(byte[] t2flowBytes) throws ClientException, ServerException {
- return response2run(root.runs().postVndTavernaT2flowXmlAsOctetStream(
- t2flowBytes, ClientResponse.class));
- }
-
+ return response2run(root.runs().postVndTavernaT2flowXmlAsOctetStream(t2flowBytes, ClientResponse.class));
+ }
+
+ /**
+ * Create a new Run by uploading a local t2flow workflow definition File.
+ * <p>
+ * The returned {@link Run} be configured (e.g. with
+ * {@link Run#setInput(String, String)}) before invoking it
+ * with {@link Run#start()}.
+ *
+ * @param t2flowFile File of workflow to upload, typically with the extension <code>.t2flow</code>
+ * @return A {@link Run} that is {@link Status#Initialized}
+ * @throws IOException If the file can't be read or a network error occurs
+ * @throws ClientException If client configuration failed, e.g. AuthorizationException
+ * @throws ServerException If the server refuses upload (e.g. because only {@link #getPermittedWorkflows()} are allowed)
+ */
public Run createWorkflowRun(File t2flowFile) throws IOException, ClientException, ServerException {
return createWorkflowRun(readAllBytes(t2flowFile.toPath()));
}
+ /**
+ * Create a new Run by referencing an external t2flow workflow definition URI.
+ * <p>
+ * The returned {@link Run} be configured (e.g. with
+ * {@link Run#setInput(String, String)}) before invoking it
+ * with {@link Run#start()}.
+ *
+ * @param t2flowUri URI of workflow to run, should have content-type <code>application/vnd.taverna.t2flow+xml</code>
+ * @return A {@link Run} that is {@link Status#Initialized}
+ * @throws ClientException If client configuration failed, e.g. AuthorizationException
+ * @throws ServerException If the server refuses the URI (e.g. it could not be retrieved)
+ */
+
public Run createWorkflowRun(URI t2flowUri) throws ClientException, ServerException {
- return response2run(root.runs().postTextUriListAsOctetStream(
- t2flowUri.toString(), ClientResponse.class));
+ return response2run(root.runs().postTextUriListAsOctetStream(t2flowUri.toString(), ClientResponse.class));
}
-
public static class ClientException extends Exception {
private static final long serialVersionUID = 1L;
@@ -126,6 +173,7 @@ public class TavernaServer extends Connected {
super(msg, cause);
}
}
+
public static class AuthorizationException extends ClientException {
private static final long serialVersionUID = 1L;
@@ -133,6 +181,7 @@ public class TavernaServer extends Connected {
super(msg, cause);
}
}
+
static class ServerException extends Exception {
private static final long serialVersionUID = 1L;
http://git-wip-us.apache.org/repos/asf/incubator-taverna-server/blob/e593ab8e/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServerConnectionFactory.java
----------------------------------------------------------------------
diff --git a/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServerConnectionFactory.java b/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServerConnectionFactory.java
index 1d1bf9d..4d876aa 100644
--- a/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServerConnectionFactory.java
+++ b/taverna-server-client/src/main/java/org/apache/taverna/server/client/TavernaServerConnectionFactory.java
@@ -20,9 +20,28 @@ import java.net.URI;
import java.util.HashMap;
import java.util.Map;
+/**
+ * Connect to a Taverna Server.
+ * <p>
+ * To create a connected {@link TavernaServer} instance,use
+ * {@link #connectNoAuth(URI)} for anonymous connection, or
+ * {@link #connectAuth(URI, String, String)}) for authenticated access.
+ *
+ */
public class TavernaServerConnectionFactory {
private Map<URI, TavernaServer> cache = new HashMap<>();
+ /**
+ * Connect to the Taverna Server without authentication.
+ * <p>
+ * The connection will be anonymous, but can later be made authenticated using
+ * {@link TavernaServer#upgradeToAuth(String, String)}.
+ *
+ * @param uri
+ * URI of Taverna Server REST endpoint, e.g.
+ * <code>http://localhost:8080/taverna-server/rest</code>
+ * @return A configured {@link TavernaServer} instance
+ */
public synchronized TavernaServer connectNoAuth(URI uri) {
TavernaServer conn = cache.get(uri);
if (conn == null)
@@ -30,6 +49,16 @@ public class TavernaServerConnectionFactory {
return conn;
}
+ /**
+ * Connect to the Taverna Server with the given authentication.
+ *
+ * @param uri
+ * URI of Taverna Server REST endpoint, e.g.
+ * <code>http://localhost:8080/taverna-server/rest</code>
+ * @param username Username
+ * @param password Password
+ * @return A configured {@link TavernaServer} instance
+ */
public TavernaServer connectAuth(URI uri, String username, String password) {
TavernaServer conn = new TavernaServer(uri, username, password);
// Force a check of the credentials by getting the server version