t2-server 0.0.4 → 0.1.0

data/README.rdoc

@@ -1,7 +1,7 @@
 = Taverna[http://www.taverna.org.uk/] 2 Server Interaction Gem
 
 Authors::     Robert Haines
-Gem Version:: 0.0.4
+Gem Version:: 0.1.0
 API Version:: 2.2a1
 Contact::     mailto:rhaines@manchester.ac.uk
 URL::         http://taverna.sourceforge.net/
@@ -29,7 +29,14 @@ http://github.com/myGrid/t2-server-gem
 
 == Usage
 
-As well as the library there are also a couple of example scripts which
+There are two entry points for the T2Server API:
+* 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.
+
+See the rdoc for more information.
+
+As well as rdoc there are also a couple of example scripts which
 demonstrate good use of the T2Server API. These are available in the
 <tt>bin</tt> directory:
 * run_workflow

data/bin/delete_all_runs

@@ -62,4 +62,9 @@ if ARGV[0] == nil
 end
 
 # connect and delete them all!
-T2Server::Server.connect(ARGV[0]).delete_all_runs
+begin
+  T2Server::Server.connect(ARGV[0]).delete_all_runs
+rescue T2Server::T2ServerError => e
+  puts e
+  exit 1
+end

data/bin/run_workflow

@@ -47,8 +47,8 @@ def get_outputs(run, pout, dir="")
     if pout
       p data
     else
-      # remove leading slash
-      filename = "#{dir[1..-1]}/#{out}".gsub('/', '-')
+      # strip path and convert remove /'s for file output
+      filename = "#{dir.strip_path}/#{out}".gsub('/', '-')
       File.open(filename, "w") do |file|
         file.syswrite(data)
       end
@@ -106,11 +106,17 @@ else
   wkf = IO.read(wkf_file)
 end
 
-# create run and set inputs
-run = T2Server::Run.create(uri, wkf)
+# create run
+begin
+  run = T2Server::Run.create(uri, wkf)
+rescue T2Server::T2ServerError => e
+  puts e
+  exit 1
+end
 puts "Created run with uuid: #{run.uuid}"
 puts "Created at #{run.create_time}"
 
+# set inputs
 inputs.each do |input, value|
   puts "Set input '#{input}' to #{value}"
   run.set_input(input, value)
@@ -126,12 +132,15 @@ puts "Finished at #{run.finish_time}"
 # get outputs
 stdout = run.stdout
 stderr = run.stderr
-puts "Exitcode: #{run.exitcode}"
-if stdout != "" then puts "Stdout:\n          #{stdout}" end
-if stderr != "" then puts "Stderr:\n          #{stderr}" end
+exitcd = run.exitcode
+puts "Exitcode: #{exitcd}"
+if stdout != "" then puts "Stdout:\n#{stdout}" end
+if stderr != "" then puts "Stderr:\n#{stderr}" end
 
-puts "Outputs:"
-get_outputs(run, print_output)
+if exitcd == 0
+  puts "Outputs:"
+  get_outputs(run, print_output)
+end
 
 # delete run
 run.delete

data/bin/server_info

@@ -62,14 +62,19 @@ if uri == nil
 end
 
 # connect to server and output information
-server = T2Server::Server.connect(uri)
-print "     Server: #{uri}\n"
-print "  Run limit: #{server.run_limit}\n"
-runs = server.runs
-print "No. of runs: #{runs.length}\n"
-if runs.length > 0
-  print "   Run list: #{runs[0].uuid} - #{runs[0].expiry}\n"
-  runs[1..-1].each do |run|
-    print "             #{run.uuid} - #{run.expiry}\n"
+begin
+  server = T2Server::Server.connect(uri)
+  print "     Server: #{uri}\n"
+  print "  Run limit: #{server.run_limit}\n"
+  runs = server.runs
+  print "No. of runs: #{runs.length}\n"
+  if runs.length > 0
+    print "   Run list: #{runs[0].uuid} - #{runs[0].expiry}\n"
+    runs[1..-1].each do |run|
+      print "             #{run.uuid} - #{run.expiry}\n"
+    end
   end
+rescue T2Server::T2ServerError => e
+  puts e
+  exit 1
 end

data/lib/t2server.rb

@@ -31,10 +31,41 @@
 # Author: Robert Haines
 
 require 't2server/xml'
+require 't2server/exceptions'
 require 't2server/server'
 require 't2server/run'
 
+# This is a Ruby library to interface with the Taverna 2 Server REST API.
+#
+# There are two API entry points:
+# * T2Server::Run - Use this for running single jobs on a server.
+# * T2Server::Server - Use this if you are providing a web interface to a
+#   Taverna 2 Server instance.
 module T2Server
+  # The version of this library
   GEM_VERSION = "0.0.4"
+  # The version of the Taverna 2 Server API that this library can interface with
   API_VERSION = "2.2a1"
 end
+
+# Add methods to the String class to operate on file paths.
+class String
+  # :call-seq:
+  #   str.strip_path -> string
+  #
+  # Returns a new String with one leading and one trailing slash
+  # removed from the ends of _str_ (if present).
+  def strip_path
+    self.gsub(/^\//, "").chomp("/")
+  end
+
+  # :call-seq:
+  #   str.strip_path! -> str or nil
+  #
+  # Modifies _str_ in place as described for String#strip_path,
+  # returning _str_, or returning +nil+ if no modifications were made. 
+  def strip_path!
+    g = self.gsub!(/^\//, "")
+    self.chomp!("/") || g
+  end
+end

data/lib/t2server/exceptions.rb

@@ -0,0 +1,153 @@
+# Copyright (c) 2010, 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
+
+require 'net/http'
+
+module T2Server
+  # An internal module to collect all the exceptions that we
+  # can't really do anything about ourselves, such as
+  # timeouts and lost connections. This is further wrapped
+  # and exposed in the API as T2Server::ConnectionError below.
+  module InternalHTTPError  #:nodoc:
+  end
+
+  # These are the HTTP errors we want to catch.
+  # Add the above exception as an ancestor to them all.
+  [
+    EOFError,
+    SocketError,
+    Timeout::Error,
+    Errno::EINVAL,
+    Errno::ETIMEDOUT,
+    Errno::ECONNRESET,
+    Errno::ECONNREFUSED,
+    Net::HTTPBadResponse,
+    Net::HTTPHeaderSyntaxError,
+    Net::ProtocolError
+  ].each {|err| err.send(:include, InternalHTTPError)}
+
+  # This is a superclass for all T2Server exceptions. It is provided as a
+  # useful catch-all for all the internally raised/thrown exceptions.
+  class T2ServerError < RuntimeError
+  end
+
+  # Raised when there is an error with the connection to the server in some
+  # way. This could be due to the server not accepting the connection, the
+  # connection being dropped unexpectedly or a timeout of some sort.
+  class ConnectionError < T2ServerError
+    attr_reader :cause
+
+    # Create a new ConnectionError with the specified cause. The cause to be
+    # passed in should be the exception object that caused the connection
+    # error.
+    def initialize(cause)
+      @cause = cause
+      super "Connection error (#{@cause.class.name}): #{@cause.message}"
+    end
+  end
+
+  # Raised when there is an unexpected response from the server. This does
+  # not necessarily indicate a problem with the server.
+  class UnexpectedServerResponse < T2ServerError
+
+    # Create a new UnexpectedServerResponse with the specified unexpected
+    # response. The response to be passed in is that which was returned by a
+    # call to Net::HTTP#request.
+    def initialize(response)
+      body = "\n#{response.body}" if response.body
+      super "Unexpected server response: #{response.code}\n#{response.error!}#{body}"
+    end
+  end
+
+  # Raised when the run that is being operated on cannot be found. If the
+  # expectation is that the run exists then it could have been destroyed by
+  # a timeout or another user.
+  class RunNotFoundError < T2ServerError
+    attr_reader :uuid
+
+    # Create a new RunNotFoundError with the specified UUID.
+    def initialize(uuid)
+      @uuid = uuid
+      super "Could not find run #{@uuid}"
+    end
+  end
+
+  # Indicates that the attribute that the user is trying to read/change does
+  # not exist. The attribute could be a server or run attribute.
+  class AttributeNotFoundError < T2ServerError
+    attr_reader :path
+
+    # Create a new AttributeNotFoundError with the path to the erroneous
+    # attribute.
+    def initialize(path)
+      @path = path
+      super "Could not find attribute at #{@path}"
+    end
+  end
+
+  # The server is at capacity and cannot accept anymore runs at this time.
+  class ServerAtCapacityError < T2ServerError
+    attr_reader :limit
+
+    # Create a new ServerAtCapacityError with the specified limit for
+    # information.
+    def initialize(limit)
+      @limit = limit
+      super "The server is already running its configured limit of concurrent workflows (#{@limit})"
+    end
+  end
+
+  # Access to the entity (run or attribute) is denied. The credentials
+  # supplied are not sufficient or the server does not allow the operation.
+  class AccessForbiddenError < T2ServerError
+    attr_reader :path
+
+    # Create a new AccessForbiddenError with the path to the restricted
+    # attribute.
+    def initialize(path)
+      @path = path
+      super "Access to #{@path} is forbidden. Either you do not have the required credentials or the server does not allow the requested operation"
+    end
+  end
+
+  # Raised if an operation is performed on a run when it is in the wrong
+  # state. Trying to start a run if it is the finished state would cause this
+  # exception to be raised.
+  class RunStateError < T2ServerError
+
+    # Create a new RunStateError specifying both the current state and that
+    # which is needed to run the operation.
+    def initialize(current, need)
+      super "The run is in the wrong state (#{current}); it should be '#{need}' to perform that action"
+    end
+  end
+end

data/lib/t2server/run.rb

@@ -34,19 +34,29 @@ require 'rexml/document'
 include REXML
 
 module T2Server
-  
+
+  # An interface for easily running jobs on a Taverna 2 Server with minimal
+  # setup and configuration required.
+  #
+  # A run can be in one of three states:
+  # * Initialized: The run has been accepted by the server. It may not yet be
+  #   ready to run though as its input port may not have been set.
+  # * Running: The run is being run by the server.
+  # * Finished: The run has finished running and its outputs are available for
+  #   download.
   class Run
-    
+    private_class_method :new
+    attr_reader :uuid
+
+    # :stopdoc:
     STATE = {
       :initialized => "Initialized",
       :running     => "Operating",
       :finished    => "Finished",
       :stopped     => "Stopped"
     }
-    
-    private_class_method :new
-    attr_reader :uuid
-    
+
+    # New is private but rdoc does not get it right! Hence :stopdoc: section.
     def initialize(server, uuid)
       @server = server
       @uuid = uuid
@@ -56,7 +66,16 @@ module T2Server
       @links = get_attributes(@server.get_run_attribute(uuid, ""))
       #@links.each {|key, val| puts "#{key}: #{val}"}
     end
+    # :startdoc:
 
+    # :call-seq:
+    #   Run.create(server, workflow) -> run
+    #
+    # Create a new run in the +Initialized+ state. The run will be created on
+    # the server with address supplied by _server_. This can either be a
+    # String of the form <tt>http://example.com:8888/blah</tt> or an already
+    # created instance of T2Server::Server. The _workflow_ must also be
+    # supplied as a string in t2flow or scufl format.
     def Run.create(server, workflow, uuid="")
       if server.class == String
         server = Server.connect(server)
@@ -67,55 +86,130 @@ module T2Server
         new(server, uuid)
       end
     end
-    
+
+    # :call-seq:
+    #   run.delete
+    #
+    # Delete this run from the server.
     def delete
       @server.delete_run uuid
     end
-    
+
+    # :call-seq:
+    #   run.inputs -> string
+    #
+    # Return the path to the input ports of this run on the server.
     def inputs
       @links[:inputs]
     end
-    
+
+    # :call-seq:
+    #   run.set_input(input, value) -> bool
+    #
+    # Set the workflow input port _input_ to _value_.
+    #
+    # Raises RunStateError if the run is not in the +Initialized+ state.
     def set_input(input, value)
+      state = status
+      raise RunStateError.new(state, STATE[:initialized]) if state != STATE[:initialized]
+
       @server.set_run_input(self, input, value)
     end
-    
+
+    # :call-seq:
+    #   run.set_input_file(input, filename) -> bool
+    #
+    # Set the workflow input port _input_ to use the file at _filename_ as its
+    # input data.
+    #
+    # Raises RunStateError if the run is not in the +Initialized+ state.
     def set_input_file(input, filename)
+      state = status
+      raise RunStateError.new(state, STATE[:initialized]) if state != STATE[:initialized]
+
       @server.set_run_input_file(self, input, filename)
     end
-    
+
+    # :call-seq:
+    #   run.get_output(output) -> string
+    #
+    # Return the value of the workflow output port _output_.
+    #
+    # Raises RunStateError if the run is not in the +Finished+ state.
     def get_output(output, type="text/plain")
-      return unless finished?   ### raise exception?
+      state = status
+      raise RunStateError.new(state, STATE[:finished]) if state != STATE[:finished]
+
+      output.strip_path!
       doc = @server.get_run_attribute(@uuid, "#{@links[:wdir]}/out/#{output}")
       doc
     end
-    
+
+    # :call-seq:
+    #   run.expiry -> string
+    #
+    # Return the expiry time of this run. It is formatted as an ISO-8601
+    # timestamp.
     def expiry
       @server.get_run_attribute(@uuid, @links[:expiry])
     end
-    
+
+    # :call-seq:
+    #   run.expiry=(time) -> bool
+    #
+    # Set the expiry time of this run to _time_. The format of _time_ should
+    # be an ISO-8601 timestamp.
     def expiry=(date)
       @server.set_run_attribute(@uuid, @links[:expiry], date)
     end
 
+    # :call-seq:
+    #   run.workflow -> string
+    #
+    # Get the workflow that this run represents.
     def workflow
       if @workflow == ""
         @workflow = @server.get_run_attribute(@uuid, @links[:workflow])
       end
       @workflow
     end
-    
+
+    # :call-seq:
+    #   run.status -> string
+    #
+    # Get the status of this run.
     def status
       @server.get_run_attribute(@uuid, @links[:status])
     end
-    
+
+    # :call-seq:
+    #   run.start
+    #
+    # Start this run on the server.
+    #
+    # Raises RunStateError if the run is not in the +Initialized+ state.
     def start
+      state = status
+      raise RunStateError.new(state, STATE[:initialized]) if state != STATE[:initialized]
+
       @server.set_run_attribute(@uuid, @links[:status], STATE[:running])
     end
-    
+
+    # :call-seq:
+    #   run.wait(params={})
+    #
+    # Wait (block) for this run to finish. Possible values that can be passed
+    # in via _params_ are:
+    # * :interval - How often (in seconds) to test for run completion.
+    #   Default +1+.
+    # * :progress - Print a dot (.) each interval to show that something is
+    #   actually happening. Default +false+.
+    #
+    # Raises RunStateError if the run is not in the +Running+ state.
     def wait(params={})
-      return unless running?
-      
+      state = status
+      raise RunStateError.new(state, STATE[:running]) if state != STATE[:running]
+
       interval = params[:interval] || 1
       progress = params[:progress] || false
       keepalive = params[:keepalive] || false ### TODO maybe move out of params
@@ -132,42 +226,108 @@ module T2Server
       # tidy up output if there is any
       puts if progress
     end
-    
+
+    # :call-seq:
+    #   run.exitcode -> integer
+    #
+    # Get the return code of the run. Zero indicates success.
     def exitcode
       @server.get_run_attribute(@uuid, @links[:exitcode]).to_i
     end
-    
+
+    # :call-seq:
+    #   run.stdout -> string
+    #
+    # Get anything that the run printed to the standard out stream.
     def stdout
       @server.get_run_attribute(@uuid, @links[:stdout])
     end
-    
+
+    # :call-seq:
+    #   run.stderr -> string
+    #
+    # Get anything that the run printed to the standard error stream.
     def stderr
       @server.get_run_attribute(@uuid, @links[:stderr])
     end
-    
+
+    # :call-seq:
+    #   run.mkdir(dir) -> bool
+    #
+    # Create a directory in the run's working directory on the server. This
+    # could be used to store input data.
     def mkdir(dir)
-      @server.make_run_dir(@uuid, @links[:wdir], dir)
+      dir.strip_path!
+      if dir.include? ?/
+        # if a path is given then separate the leaf from the
+        # end and add the rest of the path to the wdir link
+        leaf = dir.split("/")[-1]
+        path = dir[0...-(leaf.length + 1)]
+        @server.make_run_dir(@uuid, "#{@links[:wdir]}/#{path}", leaf)
+      else
+        @server.make_run_dir(@uuid, @links[:wdir], dir)
+      end
     end
-    
+
+    # :call-seq:
+    #   run.upload_file(filename, params={}) -> string
+    #
+    # Upload a file, with name _filename_, to the server. Possible values that
+    # can be passed in via _params_ are:
+    # * :dir - The directory to upload to. If this is not left blank the
+    #   corresponding directory will need to have been created by Run#mkdir.
+    # * :rename - Save the file on the server with a different name.
+    #
+    # The name of the file on the server is returned.
     def upload_file(filename, params={})
       location = params[:dir] || ""
       location = "#{@links[:wdir]}/#{location}"
       rename = params[:rename] || ""
       @server.upload_run_file(@uuid, filename, location, rename)
     end
-    
+
+    # :call-seq:
+    #   run.upload_input_file(input, filename, params={}) -> string
+    #
+    # Upload a file, with name _filename_, to the server and set it as the
+    # input data for input port _input_. Possible values that can be passed
+    # in via _params_ are:
+    # * :dir - The directory to upload to. If this is not left blank the
+    #   corresponding directory will need to have been created by Run#mkdir.
+    # * :rename - Save the file on the server with a different name.
+    #
+    # The name of the file on the server is returned.
+    #
+    # Raises RunStateError if the run is not in the +Initialized+ state.
     def upload_input_file(input, filename, params={})
+      state = status
+      raise RunStateError.new(state, STATE[:initialized]) if state != STATE[:initialized]
+
       file = upload_file(filename, params)
       set_input_file(input, file)
     end
-    
+
+    # :call-seq:
+    #   run.upload_baclava_file(filename) -> bool
+    #
+    # Upload a baclava file to be used for the workflow inputs.
     def upload_baclava_file(filename)
+      state = status
+      raise RunStateError.new(state, STATE[:initialized]) if state != STATE[:initialized]
+
       @baclava = true
       rename = upload_file(filename)
       @server.set_run_attribute(@uuid, @links[:baclava], rename)
     end
 
+    # :call-seq:
+    #   run.ls(dir="") -> [[dirs], [objects]]
+    #
+    # List a directory in the run's workspace on the server. If _dir_ is left
+    # blank then / is listed. The contents of a directory are returned as a
+    # list of two lists, directories and "objects" respectively.
     def ls(dir="")
+      dir.strip_path!
       dir_list = @server.get_run_attribute(@uuid, "#{@links[:wdir]}/#{dir}")
       doc = Document.new(dir_list)
 
@@ -180,26 +340,50 @@ module T2Server
       [dirs, files]
     end
 
+    # :call-seq:
+    #   run.initialized? -> bool
+    #
+    # Is this run in the +Initialized+ state?
     def initialized?
       status == STATE[:initialized]
     end
-    
+
+    # :call-seq:
+    #   run.running? -> bool
+    #
+    # Is this run in the +Running+ state?
     def running?
       status == STATE[:running]
     end
-    
+
+    # :call-seq:
+    #   run.finished? -> bool
+    #
+    # Is this run in the +Finished+ state?
     def finished?
       status == STATE[:finished]
     end
-    
+
+    # :call-seq:
+    #   run.create_time -> string
+    #
+    # Get the creation time of this run formatted as an ISO-8601 timestamp.
     def create_time
       @server.get_run_attribute(@uuid, @links[:createtime])
     end
-    
+
+    # :call-seq:
+    #   run.start_time -> string
+    #
+    # Get the start time of this run formatted as an ISO-8601 timestamp.
     def start_time
       @server.get_run_attribute(@uuid, @links[:starttime])
     end
 
+    # :call-seq:
+    #   run.finish_time -> string
+    #
+    # Get the finish time of this run formatted as an ISO-8601 timestamp.
     def finish_time
       @server.get_run_attribute(@uuid, @links[:finishtime])
     end