t2-server 1.0.0 → 1.1.0

data/.gitignore

@@ -0,0 +1,8 @@
+*~
+pkg/
+html/
+.buildpath
+.project
+.idea
+.rvmrc
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+cache: bundler
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0

data/CHANGES.rdoc

@@ -1,5 +1,29 @@
 = Changes log for the T2 Ruby Gem
 
+== Version 1.1.0
+
+* Remove hirb as a runtime dependency.
+* t2-server-admin: Minor fix for readability.
+* Add a gem version badge from badge.fury.io.
+* Use bundler and stop using jeweler.
+* Update dependencies.
+* Add travis configuration.
+* Separate out the version code from the main include file.
+* If in travis, don't wait for a server address.
+* Update note about SemVer in readme.
+* Add travis badge and update ruby testing info.
+* Refactor out rexml and nokogiri xml support.
+* Setup rubygems and bundler in the main require file.
+* t2-run-workflow: Fix baclava output option.
+* Fix error in exception caused by chunked response.
+* Add provenance capture and retrieval functionality.
+* Can now toggle provenance generation on and off.
+* Implement a comparable version class.
+* Restrict provenance functionality to correct server versions.
+* Remove Server#version_components from the docs.
+* Tighten ratom version and move libxml-ruby to runtime list.
+* Align baclava output method names with the prov ones.
+
 == Version 1.0.0
 
 * Remove deprecated methods.

data/Gemfile

@@ -0,0 +1,35 @@
+# Copyright (c) 2014 The University of Manchester, UK.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#  * Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+#  * Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+#  * Neither the names of The University of Manchester nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# Author: Robert Haines
+
+source "https://rubygems.org"
+
+gemspec

data/LICENCE.rdoc

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2013 The University of Manchester, UK.
+Copyright (c) 2010-2014 The University of Manchester, UK.
 
 All rights reserved.
 

data/README.rdoc

@@ -4,9 +4,11 @@ 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-2013 The University of Manchester, UK
+Copyright::   (c) 2010-2014 The University of Manchester, UK
 
+{<img src="https://badge.fury.io/rb/t2-server.png" alt="Gem Version" />}[http://badge.fury.io/rb/t2-server]
 {<img src="https://codeclimate.com/github/myGrid/t2-server-gem.png" />}[https://codeclimate.com/github/myGrid/t2-server-gem]
+{<img src="https://travis-ci.org/myGrid/t2-server-gem.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/myGrid/t2-server-gem]
 
 == Synopsis
 
@@ -28,9 +30,7 @@ https://github.com/myGrid/t2-server-gem
 
 == Compatibility
 
-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.
+This gem uses {Semantic Versioning}[http://semver.org/].
 
 === Taverna Server
 
@@ -52,18 +52,24 @@ 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
+* 2.4 and up, use version 1.0.0 and up.
 
 === Ruby
 
 This library is known to work with the following versions of Ruby:
-* 1.8.7
 * 1.9.2
-* 1.9.3 *
-* 2.0.0
+* 1.9.3 +*
+* 2.0.0 +*
+* 2.1.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.
+Those marked with an asterisk (*) are fully supported and bugs found against
+them will be fixed. Other versions may work but are not tested or supported.
+
+Those marked with a plus (+) are tested in
+{https://travis-ci.org/myGrid/t2-server-gem}[Travis].
+
+Ruby 1.8.7 is no longer supported as it reached its end of life at the end of
+June 2013.
 
 == Usage
 
@@ -233,12 +239,29 @@ supported:
 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.generate_baclava_output
   run.start
   run.wait
   output = run.baclava_output                    # download to memory
   run.baclava_output("/path/to/output.baclava")  # save to a file
 
+Later versions of Taverna Server can generate a complete provenance log of a
+workflow run in {Taverna-PROV}[https://github.com/myGrid/taverna-prov] format.
+The generation of provenance data must be requested *before* starting the run.
+
+  run.generate_provenance
+  run.start
+  ...
+  provenance = run.provenance                # download to memory
+  run.provenance("/path/to/provenance.zip")  # save to a file
+
+The resultant provenance bundle is a zip file containing all input, output and
+intermediate values as separate files, along with the provenance of
+the workflow run. The bundle is based on the
+{Research Object Bundle specification}[http://wf4ever.github.io/ro/bundle/],
+and complies with the
+{W3C PROV-O provenance specification}[http://www.w3.org/TR/prov-o/].
+
 The log from Taverna Server can be downloaded in a similar way to zip files or
 Baclava documents.
 
@@ -246,7 +269,7 @@ Baclava documents.
   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:
+block to the value, zip_output, provenance, baclava_output or log methods:
 
   run.output_port("port_name").value do |data|
     print data

data/Rakefile

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2013 The University of Manchester, UK.
+# Copyright (c) 2010-2014 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -30,49 +30,12 @@
 #
 # Author: Robert Haines
 
-require 'rubygems'
-require 'rake'
-require 'rake/clean'
-require 'rake/tasklib'
-require 'rdoc/task'
-require 'jeweler'
-
-# we need to add lib to the path because we're not installed yet!
-$LOAD_PATH.unshift File.join(File.dirname(__FILE__), "lib")
-require 't2-server'
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rdoc/task"
 
 task :default => [:test]
 
-Jeweler::Tasks.new do |s|
-  s.name             = "t2-server"
-  s.version          = T2Server::Version::STRING
-  s.authors          = ["Robert Haines", "Finn Bacall"]
-  s.email            = ["support@mygrid.org.uk"]
-  s.homepage         = "http://www.taverna.org.uk/"
-  s.platform         = Gem::Platform::RUBY
-  s.summary          = "Support for interacting with Taverna 2 Server."
-  s.description      = "This gem provides access to the Taverna 2 Server " +
-                         "REST interface from Ruby."
-  s.require_path     = "lib"
-  s.bindir           = "bin"
-  s.executables      = ["t2-delete-runs", "t2-run-workflow", "t2-server-info",
-                          "t2-get-output", "t2-server-admin"]
-  s.test_file        = "test/ts_t2server.rb"
-  s.has_rdoc         = true
-  s.extra_rdoc_files = ["README.rdoc", "LICENCE.rdoc", "CHANGES.rdoc"]
-  s.rdoc_options     = ["-N", "--tab-width=2", "--main=README.rdoc"]
-  s.add_development_dependency('rake', '~> 0.9.2')
-  s.add_development_dependency('libxml-ruby', '>= 1.1.4')
-  s.add_development_dependency('nokogiri', '>= 1.5.0')
-  s.add_development_dependency('rdoc', '>= 3.9.4')
-  s.add_development_dependency('jeweler', '~> 1.8.3')
-  s.add_development_dependency('launchy', '~> 2.2.0')
-  s.add_runtime_dependency('net-http-persistent', '~> 2.6')
-  s.add_runtime_dependency('taverna-baclava', '~> 1.0.0')
-  s.add_runtime_dependency('ratom', '~> 0.8.2')
-  s.add_runtime_dependency('hirb', '>= 0.4.0')
-end
-
 # This test task does not use the standard Rake::TestTask class as we need to
 # be able to supply an argument to the test. This is so that the test can be
 # run with a server address from a CI server. The equivalent TestTask would be

data/bin/t2-run-workflow

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-# Copyright (c) 2010-2013 The University of Manchester, UK.
+# Copyright (c) 2010-2014 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -86,13 +86,19 @@ conn_params, creds = register_options("Usage: t2-run-workflow [options] "\
       user, pass = cred.chomp.split(':', 2)
       options[:screds] << [uri, user, pass]
   end
+  opt.on("-P [FILE]", "--provenance", "Generate provenance for the run and "\
+    "save it to a file. A filename may be specified or 'provenance.zip' "\
+    "will be used. Getting outputs in baclava format overrides this "\
+    "option.") do |val|
+      options[:provenance] = (val || "provenance.zip").chomp
+    end
   opt.on("-b BACLAVA", "--baclava-in=BACLAVA", "Set baclava file for input "\
     "port values") do |val|
       inputs[:baclava] = val
   end
-  opt.on("-o", "--baclava-out=BACLAVA", "Return outputs in baclava format."\
+  opt.on("-o [FILE]", "--baclava-out", "Return outputs in baclava format."\
     " A filename may be specified or 'out.xml' is used") do |val|
-      options[:baclava_out] = val.chomp
+      options[:baclava_out] = (val || "out.xml").chomp
   end
   opt.on("-n", "--no-wait", "Do not wait for workflow to finish, return "\
     "once it has started running") do |val|
@@ -189,6 +195,9 @@ begin
       run.add_password_credential(list[0], list[1], list[2])
     end
 
+    # generate provenance?
+    run.generate_provenance if options[:provenance]
+
     # output baclava?
     run.request_baclava_output if options[:baclava_out]
 
@@ -250,6 +259,12 @@ begin
           end
         end
       end
+
+      if options[:provenance]
+        run.provenance(options[:provenance])
+        puts "Provenance file written to '#{options[:provenance]}'"
+      end
+
     end
 
     # delete run?

data/bin/t2-server-admin

@@ -33,7 +33,6 @@
 
 require 'rubygems'
 require 't2-server-cli'
-require 'hirb'
 
 include T2Server::CLI
 
@@ -58,6 +57,17 @@ conn_params, creds = register_options("Usage: t2-server-admin [options] " +
   end
 end
 
+if options[:list]
+  begin
+    require 'hirb'
+  rescue LoadError
+    puts "\n****\nTo list administrative resources in your terminal the "\
+      "hirb gem must be installed:\n\n$ gem install hirb\n\nThis information "\
+      "will not be shown this time, sorry.\n****\n\n"
+    options[:list] = false
+  end
+end
+
 # get runs and server address from the arguments
 resources = []
 address = ""
@@ -84,7 +94,7 @@ begin
   server.administrator(creds) do |admin|
     # list and exit?
     if options[:list]
-      puts (Hirb::Helpers::ObjectTable.render admin.resources.values,
+      puts Hirb::Helpers::ObjectTable.render(admin.resources.values,
               :fields=>[:name, :writable?],
               :headers=>{:name => 'Resource name', :writable? => 'Access'},
               :filters=>{:writable? => :access},

data/bin/t2-server-info

@@ -33,7 +33,6 @@
 
 require 'rubygems'
 require 't2-server-cli'
-require 'hirb'
 
 include T2Server::CLI
 
@@ -51,6 +50,17 @@ conn_params, creds = register_options("Usage: t2-server-info [options] " +
   end
 end
 
+if options[:list] > 0
+  begin
+    require 'hirb'
+  rescue LoadError
+    puts "\n****\nTo tabulate run information in your terminal the hirb gem "\
+      "must be installed:\n\n$ gem install hirb\n\nRun information will not "\
+      "be shown this time, sorry.\n****\n\n"
+    options[:list] = 0
+  end
+end
+
 # read and check server address and credentials
 uri, creds = parse_address(ARGV.shift, creds)
 

data/lib/t2-server.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2013 The University of Manchester, UK.
+# Copyright (c) 2010-2014 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -30,9 +30,12 @@
 #
 # Author: Robert Haines
 
-require 'yaml'
+require 'rubygems'
+require 'bundler/setup'
+
+require 't2-server/version'
 require 't2-server/util'
-require 't2-server/xml/xml'
+require 't2-server/xml'
 require 't2-server/exceptions'
 require 't2-server/net/credentials'
 require 't2-server/net/connection'
@@ -50,14 +53,4 @@ require 't2-server/admin'
 # * T2Server::Server - Use this if you are providing a web interface to a
 #   Taverna 2 Server instance.
 module T2Server
-
-  # Library version information.
-  module Version
-    # Version information in a Hash
-    INFO = YAML.load_file(File.join(File.dirname(__FILE__), "..",
-      "version.yml"))
-
-    # Version number as a String
-    STRING = [:major, :minor, :patch].map {|d| INFO[d]}.compact.join('.')
-  end
 end

data/lib/t2-server/exceptions.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2012 The University of Manchester, UK.
+# Copyright (c) 2010-2014 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -104,7 +104,8 @@ module T2Server
       @method = method
       @path = path
       @code = response.code
-      @body = response.body.empty? ? "<none>" : "#{response.body}"
+      @body = response.body.to_s
+      @body = @body.empty? ? "<none>" : "#{response.body}"
       message = "Unexpected server response:\n  Method: #{@method}\n  Path: "\
         "#{@path}\n  Code: #{@code}\n  Body: #{@body}"
       super message

data/lib/t2-server/interaction.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2013 The University of Manchester, UK.
+# Copyright (c) 2010-2014 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -30,7 +30,6 @@
 #
 # Author: Robert Haines
 
-require 'rubygems'
 require 'atom'
 require 'uri'
 

data/lib/t2-server/run.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2013 The University of Manchester, UK.
+# Copyright (c) 2010-2014 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -32,7 +32,6 @@
 
 require 'base64'
 require 'time'
-require 'rubygems'
 require 'taverna-baclava'
 
 module T2Server
@@ -79,6 +78,8 @@ module T2Server
       :inputexp   => "//nsr:expected",
       :name       => "//nsr:name",
       :feed       => "//nsr:interaction",
+      :gen_prov   => "//nsr:generate-provenance",
+      :run_bundle => "//nsr:run-bundle",
 
       # Port descriptions XPath queries
       :port_in    => "//port:input",
@@ -110,6 +111,7 @@ module T2Server
       @workflow = ""
       @baclava_in = false
       @baclava_out = false
+      @provenance = false
 
       @credentials = credentials
 
@@ -466,11 +468,11 @@ module T2Server
     end
 
     # :call-seq:
-    #   request_baclava_output -> true or false
+    #   generate_baclava_output -> true or false
     #
     # Set the server to save the outputs of this run in baclava format. This
     # must be done before the run is started.
-    def request_baclava_output
+    def generate_baclava_output
       return if @baclava_out
       state = status
       raise RunStateError.new(state, :initialized) if state != :initialized
@@ -479,6 +481,16 @@ module T2Server
         @credentials)
     end
 
+    # :stopdoc:
+    def request_baclava_output
+      warn "[DEPRECATED] Run#request_baclava_output is deprecated and will "\
+        "be removed in the next major release. Please use "\
+        "Run#generate_baclava_output instead."
+
+      generate_baclava_output
+    end
+    # :startdoc:
+
     # :call-seq:
     #   baclava_input? -> true or false
     #
@@ -488,13 +500,23 @@ module T2Server
     end
 
     # :call-seq:
-    #   baclava_output? -> true or false
+    #   generate_baclava_output? -> true or false
     #
     # Has this run been set to return results in baclava format?
-    def baclava_output?
+    def generate_baclava_output?
       @baclava_out
     end
 
+    # :stopdoc:
+    def baclava_output?
+      warn "[DEPRECATED] Run#baclava_output? is deprecated and will be "\
+        "removed in the next major release. Please use "\
+        "Run#generate_baclava_output? instead."
+
+      generate_baclava_output?
+    end
+    # :startdoc:
+
     # :call-seq:
     #   baclava_output -> string
     #   baclava_output(filename) -> fixnum
@@ -530,6 +552,66 @@ module T2Server
       download_or_stream(param, baclava_uri, "*/*", &block)
     end
 
+    # :call-seq:
+    #   generate_provenance(toggle = true) -> true or false
+    #
+    # Toggle the generation of provenance for this run on or off. This must be
+    # done before the run is started. Once the run has completed provenance
+    # can be retrieved with Run#provenance.
+    #
+    # Requesting baclava output for a run will override this setting.
+    def generate_provenance(toggle = true)
+      return @provenance if @provenance == toggle || links[:gen_prov].nil?
+      state = status
+      raise RunStateError.new(state, :initialized) if state != :initialized
+
+      result = @server.update(links[:gen_prov], toggle.to_s, "text/plain",
+        @credentials)
+
+      # If changing the setting worked then return the new setting, otherwise
+      # return the old one.
+      @provenance = result ? toggle : @provenance
+    end
+
+    # :call-seq:
+    #   generate_provenance? -> true or false
+    #
+    # Has this run been set to generate provenance output?
+    def generate_provenance?
+      @provenance
+    end
+
+    # :call-seq:
+    #   provenance -> binary blob
+    #   provenance(filename) -> fixnum
+    #   provenance(stream) -> fixnum
+    #   provenance {|chunk| ...}
+    #
+    # Get the provenance of this run from the server in zip format.
+    #
+    # Calling this method with no parameters will simply return a blob of
+    # zipped data. Providing a filename will stream the data directly to that
+    # file and return the number of bytes written. Passing in an object that
+    # has a +write+ method (for example, an instance of File or IO) will
+    # stream the data directly to that object and return the number of bytes
+    # that were streamed. Passing in a block will allow access to the
+    # underlying data stream:
+    #   run.provenance do |chunk|
+    #     print chunk
+    #   end
+    #
+    # Raises RunStateError if the run has not finished running.
+    def provenance(param = nil, &block)
+      raise ArgumentError,
+        'both a parameter and block given for provenance' if param && block
+
+      state = status
+      raise RunStateError.new(state, :finished) if state != :finished
+
+      raise AccessForbiddenError.new("provenance") unless @provenance
+      download_or_stream(param, links[:run_bundle], "*/*", &block)
+    end
+
     # :call-seq:
     #   zip_output -> binary blob
     #   zip_output(filename) -> fixnum
@@ -1084,7 +1166,7 @@ module T2Server
       # first parse out the basic stuff
       links = get_uris_from_doc(doc, [:expiry, :workflow, :status,
         :createtime, :starttime, :finishtime, :wdir, :inputs, :output,
-        :securectx, :listeners, :name, :feed])
+        :securectx, :listeners, :name, :feed, :gen_prov, :run_bundle])
 
       # Working dir links
       _get_wdir_links(links)