README.rdoc in t2-server-0.9.3 vs README.rdoc in t2-server-1.0.0

- old
+ new

@@ -2,12 +2,13 @@ Authors:: Robert Haines Contact:: mailto:support@mygrid.org.uk URL:: http://www.taverna.org.uk/ Licence:: BSD (See LICENCE or http://www.opensource.org/licenses/bsd-license.php) -Copyright:: (c) 2010-2012 The University of Manchester, UK +Copyright:: (c) 2010-2013 The University of Manchester, UK +{<img src="https://codeclimate.com/github/myGrid/t2-server-gem.png" />}[https://codeclimate.com/github/myGrid/t2-server-gem] == Synopsis This is a Ruby library to interface with the Taverna 2 Server REST API. @@ -23,41 +24,54 @@ https://rubygems.org/gems/t2-server You can also download the source code from here: https://github.com/myGrid/t2-server-gem -== Compatibility with Taverna Server versions +== Compatibility -From version 0.9.0 this library is compatible with Taverna Server 2.3 onwards. +After the release of version 1.0.0 this gem will follow the principles of +{Semantic Versioning}[http://semver.org/]. Until that point there may be +breaking changes to the API, although these will be kept to a minimum. + +=== Taverna Server + +Versions 0.9.x of this library are compatible with Taverna Server 2.3 and 2.4. It is not compatible with any earlier version of Taverna Server due to breaking -changes in its REST interface. We strongly encourage all users to upgrade to -the current version of Taverna Server, but if that is not possible right now -then please continue to use version 0.6.1 of this library for the time being. +changes in its REST interface. -This version of the library should be compatible with any Ruby code that you -may have already written against earlier versions but you may see some warnings -about API deprecations. These are clearly marked [DEPRECATION] and will appear -on your console output. Anything marked as deprecated will be removed in -version 1.0.0 (and are not guaranteed to continue working even until then) so -you are advised to update your code at your earliest convenience. +From version 1.0.0 this library is not guaranteed to be compatible with +Taverna Server 2.3. It might work but it is not supported, and may stop working +at any time. -== Compatibility with Ruby versions +Version 1.0.0 of this library saw the removal of older methods that were +previously deprecated. If your code no longer works with this version then +please re-test it with version 0.9.3 and check for deprecation messages before +reporting bugs. +We strongly encourage all users to upgrade to the current version of Taverna +Server, but if that is not possible right now then these are the recommended +version pairings: +* pre Taverna Server 2.3, use version 0.6.1 of the gem +* 2.3, use version 0.9.3 +* 2.4 and up, use version 1.0.0 + +=== Ruby + This library is known to work with the following versions of Ruby: -* 1.8.7 * +* 1.8.7 * 1.9.2 * 1.9.3 * -* jruby 1.6.4 (in Ruby 1.8 mode) +* 2.0.0 Those marked with an asterisk (*) are supported and bugs found against them will be fixed. Other versions may work but are not tested or supported. == Usage There are two entry points for the T2Server API: -* <tt>T2Server::Run</tt> - Use this for running single jobs on a server. -* <tt>T2Server::Server</tt> - Use this if you are providing a web interface to +* T2Server::Run - Use this for running single jobs on a server. +* T2Server::Server - Use this if you are providing a web interface to one or more Taverna 2 Server instances. In both cases the gem should be initialized by requiring the top level ruby file: require 't2-server' @@ -74,10 +88,13 @@ * <tt>:ca_file</tt> - A file to use as a Certificate Authority (CA) for self-signed server certificates. * <tt>:ca_path</tt> - Path or list of paths to directories of CA certificates. * <tt>:verify_peer</tt> - Use a CA to verify that the Taverna Server you are connecting to has a valid server certificate and that it is the correct one. * <tt>:client_certificate</tt> - A certificate to use for client certificate authentication. * <tt>:client_password</tt> - The password to unlock the private key of the client certificate. +* <tt>:ssl_version</tt> - The TLS/SSL version to use (<tt>:TLSv1</tt>, <tt>:SSLv23</tt> or <tt>:SSLv3</tt>) +* <tt>:open_timeout</tt> - The number of seconds to wait while opening a connection. +* <tt>:read_timeout</tt> - The number of seconds to wait while reading from a connection. And can be set like this for a standard https connection: conn_params = ConnectionParameters.new conn_params[:verify_peer] = true @@ -89,13 +106,14 @@ automatically. For convenience a number of standard sets of parameters have been defined. The above example is available as +DefaultConnectionParameters+. Others available are: -* +InsecureSSLConnectionParameters+ - to ignore SSL checks. +* +InsecureSSLConnectionParameters+ - to ignore SSL checks. <b>Not recommended!</b> * +CustomCASSLConnectionParameters+ - for custom (self-signed) CAs. * +ClientAuthSSLConnectionParameters+ - for client certificate authentication. +* +SSL3ConnectionParameters+ - uses SSLv3 as the default transport layer. See the rdoc for more details on these classes. === Authenticating to a Taverna Server @@ -104,11 +122,11 @@ credentials = T2Server::HttpBasic.new("username", "password") === Server API example -The Server constructor can yield the newly created object. Simple supply a URI +The Server constructor can yield the newly created object. Simply supply a URI and a set of connection parameters to connect to a server: T2Server::Server.new(uri, conn_params) do |server| ... end @@ -122,13 +140,16 @@ server.create_run(workflow, credentials) do |run| ... end -An individual run can be deleted with its own <tt>delete</tt> method (see below) -but all runs on a server can be deleted in one go: +The +workflow+ parameter can be the workflow itself, a filename or a File or +IO object. +An individual run can be deleted with its own <tt>delete</tt> method (see +below) but all runs on a server can be deleted in one go: + server.delete_all_runs(credentials) Note that you can only delete runs for which your credentials have delete authorization. See later for details. @@ -139,10 +160,13 @@ T2Server::Run.create(uri, workflow, credentials, conn_params) do |run| ... end +As before, the +workflow+ parameter can be the workflow itself, a filename or +a File or IO object. + Setting an input port to a run is very easy: run.input_port("port_name").value = 1 run.input_port("port_name").value = "Hello!" run.input_port("port_name").value = ["list", "of", "values"] @@ -162,28 +186,72 @@ Or just wait until the run has finished: run.wait -Then the outputs can be collected: +While a workflow is running it might produce notifications via the +{Interaction Service}[http://dev.mygrid.org.uk/wiki/display/taverna/Interaction+service]. +These can be polled with: + run.notifications + +If there are any new notifications that have not been responded to they will +be returned in a list to be processed. Notifications take the form of a Web +page to be displayed and the notification objects returned from the above call +hold a URI to that page. The following code prints those URIs to the console: + + run.notifications.each do |i| + puts i.uri + end + +When the workflow has finished executing then the outputs can be collected +into memory or saved to a file: + result = run.output_port("port_name").value + run.output_port("port_name").write_value_to_file("/path/to/value.txt") -If you have a lot of output you can grab the whole lot as a zip file: +Outputs can be queried as to their type, size (in bytes) or if they contain an +error message: - zip_data = run.zip_output + run.output_port("port_name").type + run.output_port("port_name").size + run.output_port("port_name").error? +If the output does hold an error then it can be found in the value of the +output as normal. + +If you have a lot of output you can grab the whole lot in a zip archive. This +can be downloaded into memory or saved directly to a file. + + zip_data = run.zip_output # download to memory + run.zip_output("/path/to/output.zip") # save to a file + Using baclava documents for setting inputs and collecting outputs is also supported: run.baclava_input = filename -But make sure you request baclava output *before* starting the run: +But make sure you request baclava output *before* starting the run. Baclava +output can be downloaded into memory or saved directly to a file. run.request_baclava_output run.start run.wait - output = run.baclava_output + output = run.baclava_output # download to memory + run.baclava_output("/path/to/output.baclava") # save to a file + +The log from Taverna Server can be downloaded in a similar way to zip files or +Baclava documents. + + log = run.log # download to memory + run.log("/path/to/log.txt") # save to a file + +When downloading outputs the underlying stream can be accessed by supplying a +block to the value, zip_output, baclava_output or log methods: + + run.output_port("port_name").value do |data| + print data + end A run can be deleted when no longer needed, like so: run.delete