t2-server 0.9.3 → 1.0.0

data/lib/t2-server/run-cache.rb

@@ -0,0 +1,99 @@
+# Copyright (c) 2010-2013 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
+
+# :stopdoc:
+module T2Server
+
+  class Server
+
+    # This class is used to cache Run objects in a Server so they don't need to
+    # be created so often. When manipulating this cache the user credentials
+    # should be passed in, or the global user ":all" will be used instead.
+    class RunCache
+
+      def initialize(server)
+        @server = server
+        @cache = {}
+      end
+
+      # Add a run, or runs, to the cache.
+      def add_run(runs, credentials = nil)
+        cache = user_cache(credentials)
+
+        [*runs].each do |run|
+          cache[run.id] = run
+        end
+      end
+
+      # This method adds all new runs (creating instances where required) in
+      # the list provided AND removes any runs no longer in the list.
+      def refresh_all!(run_list, credentials = nil)
+        cache = user_cache(credentials)
+
+        # Add new runs to the user cache.
+        run_list.each_key do |id|
+          if !cache.has_key? id
+            cache[id] = Run.create(@server, "", credentials, run_list[id])
+          end
+        end
+
+        # Clear out the expired runs.
+        if cache.length > run_list.length
+          cache.delete_if {|key, _| !run_list.member? key}
+        end
+
+        cache
+      end
+
+      # Delete all runs objects from the cache. This does not delete runs from
+      # the remote server - just their locally cached instances.
+      def clear!(credentials = nil)
+        user_cache(credentials).clear
+      end
+
+      # Get all the specified user's runs.
+      def runs(credentials = nil)
+        user_cache(credentials)
+      end
+
+      private
+
+      def user_cache(credentials)
+        user = credentials.nil? ? :all : credentials.username
+        @cache[user] ||= {}
+      end
+
+    end
+
+  end
+end
+# :startdoc:

data/lib/t2-server/run.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2012 The University of Manchester, UK.
+# Copyright (c) 2010-2013 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -59,43 +59,46 @@ module T2Server
     attr_reader :server
 
     # :stopdoc:
-    XPaths = {
+    XPATHS = {
       # Run XPath queries
-      :run_desc   => XML::Methods.xpath_compile("/nsr:runDescription"),
-      :dir        => XML::Methods.xpath_compile("//nss:dir"),
-      :file       => XML::Methods.xpath_compile("//nss:file"),
-      :expiry     => XML::Methods.xpath_compile("//nsr:expiry"),
-      :workflow   => XML::Methods.xpath_compile("//nsr:creationWorkflow"),
-      :status     => XML::Methods.xpath_compile("//nsr:status"),
-      :createtime => XML::Methods.xpath_compile("//nsr:createTime"),
-      :starttime  => XML::Methods.xpath_compile("//nsr:startTime"),
-      :finishtime => XML::Methods.xpath_compile("//nsr:finishTime"),
-      :wdir       => XML::Methods.xpath_compile("//nsr:workingDirectory"),
-      :inputs     => XML::Methods.xpath_compile("//nsr:inputs"),
-      :output     => XML::Methods.xpath_compile("//nsr:output"),
-      :securectx  => XML::Methods.xpath_compile("//nsr:securityContext"),
-      :listeners  => XML::Methods.xpath_compile("//nsr:listeners"),
-      :baclava    => XML::Methods.xpath_compile("//nsr:baclava"),
-      :inputexp   => XML::Methods.xpath_compile("//nsr:expected"),
+      :run_desc   => "/nsr:runDescription",
+      :dir        => "//nss:dir",
+      :file       => "//nss:file",
+      :expiry     => "//nsr:expiry",
+      :workflow   => "//nsr:creationWorkflow",
+      :status     => "//nsr:status",
+      :createtime => "//nsr:createTime",
+      :starttime  => "//nsr:startTime",
+      :finishtime => "//nsr:finishTime",
+      :wdir       => "//nsr:workingDirectory",
+      :inputs     => "//nsr:inputs",
+      :output     => "//nsr:output",
+      :securectx  => "//nsr:securityContext",
+      :listeners  => "//nsr:listeners",
+      :baclava    => "//nsr:baclava",
+      :inputexp   => "//nsr:expected",
+      :name       => "//nsr:name",
+      :feed       => "//nsr:interaction",
 
       # Port descriptions XPath queries
-      :port_in    => XML::Methods.xpath_compile("//port:input"),
-      :port_out   => XML::Methods.xpath_compile("//port:output"),
+      :port_in    => "//port:input",
+      :port_out   => "//port:output",
 
       # Run security XPath queries
-      :sec_creds  => XML::Methods.xpath_compile("//nsr:credentials"),
-      :sec_perms  => XML::Methods.xpath_compile("//nsr:permissions"),
-      :sec_trusts => XML::Methods.xpath_compile("//nsr:trusts"),
-      :sec_perm   =>
-       XML::Methods.xpath_compile("/nsr:permissionsDescriptor/nsr:permission"),
-      :sec_uname  => XML::Methods.xpath_compile("nsr:userName"),
-      :sec_uperm  => XML::Methods.xpath_compile("nsr:permission"),
-      :sec_cred   => XML::Methods.xpath_compile("/nsr:credential"),
-      :sec_suri   => XML::Methods.xpath_compile("nss:serviceURI"),
-      :sec_trust  =>
-       XML::Methods.xpath_compile("/nsr:trustedIdentities/nsr:trust")
+      :sec_creds  => "//nsr:credentials",
+      :sec_perms  => "//nsr:permissions",
+      :sec_trusts => "//nsr:trusts",
+      :sec_perm   => "/nsr:permissionsDescriptor/nsr:permission",
+      :sec_uname  => "nsr:userName",
+      :sec_uperm  => "nsr:permission",
+      :sec_cred   => "/nsr:credential",
+      :sec_suri   => "nss:serviceURI",
+      :sec_trust  => "/nsr:trustedIdentities/nsr:trust"
     }
 
+    @@xpaths = XML::XPathCache.instance
+    @@xpaths.register_xpaths XPATHS
+
     # The name to be used internally for retrieving results via baclava
     BACLAVA_FILE = "out.xml"
 
@@ -110,6 +113,9 @@ module T2Server
 
       @credentials = credentials
 
+      # Has this Run object been deleted from the server?
+      @deleted = false
+
       # The following three fields hold cached data about the run that is only
       # downloaded the first time it is requested.
       @run_doc = nil
@@ -119,6 +125,9 @@ module T2Server
       # initialize ports lists to nil as an empty list means no inputs/outputs
       @input_ports = nil
       @output_ports = nil
+
+      # The interaction reader to use for this run, if required.
+      @interaction_reader = nil
     end
     # :startdoc:
 
@@ -131,10 +140,10 @@ module T2Server
     # 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. User credentials and
-    # connection parameters can be supplied if required but are both optional.
-    # If _server_ is an instance of T2Server::Server then
+    # created instance of T2Server::Server. The _workflow_ may be supplied
+    # as a string in t2flow format, a filename or a File or IO object. User
+    # credentials and connection parameters can be supplied if required but
+    # are both optional. If _server_ is an instance of T2Server::Server then
     # _connection_parameters_ will be ignored.
     #
     # This method will _yield_ the newly created Run if a block is given.
@@ -154,36 +163,59 @@ module T2Server
         end
       end
 
-      if server.class != Server
-        server = Server.new(server, conn_params)
-      end
+      # If server is not a Server object, get one.
+      server = Server.new(server, conn_params) if server.class != Server
 
-      if uri.nil?
-        uri = server.initialize_run(workflow, credentials)
-      end
+      # If we are not given a URI to a run then we know we need to create one.
+      uri ||= server.initialize_run(workflow, credentials)
 
+      # Create the run object and yield it if necessary.
       run = new(server, uri, credentials)
       yield(run) if block_given?
       run
     end
 
-    # :stopdoc:
-    def uuid
-      warn "[DEPRECATION] 'uuid' is deprecated and will be removed in 1.0. " +
-        "Please use Run#id or Run#identifier instead."
-      @identifier
-    end
-    # :startdoc:
-
     # :call-seq:
-    #   owner -> String
+    #   owner -> string
     #
     # Get the username of the owner of this run. The owner is the user who
     # created the run on the server.
     def owner
-      @owner = _get_run_owner if @owner.nil?
+      @owner ||= _get_run_owner
+    end
 
-      @owner
+    # :call-seq:
+    #   name -> String
+    #
+    # Get the name of this run.
+    #
+    # Initially this name is derived by Taverna Server from the name
+    # annotation in the workflow file and the time at which the run was
+    # initialized. It can be set with the <tt>name=</tt> method.
+    #
+    # For Taverna Server versions prior to version 2.5.0 this is a no-op and
+    # the empty string is returned for consistency.
+    def name
+      return "" if links[:name].nil?
+      @server.read(links[:name], "text/plain", @credentials)
+    end
+
+    # :call-seq:
+    #   name = new_name -> bool
+    #
+    # Set the name of this run. +true+ is returned upon success. The maximum
+    # length of names supported by the server is 48 characters. Anything
+    # longer than 48 characters will be truncated before upload.
+    #
+    # Initially this name is derived by Taverna Server from the name
+    # annotation in the workflow file and the time at which the run was
+    # initialized.
+    #
+    # For Taverna Server versions prior to version 2.5.0 this is a no-op but
+    # +true+ is still returned for consistency.
+    def name=(name)
+      return true if links[:name].nil?
+      @server.update(links[:name], name[0...48], "text/plain", @credentials)
     end
 
     # :call-seq:
@@ -192,44 +224,27 @@ module T2Server
     # Delete this run from the server.
     def delete
       @server.delete(@uri, @credentials)
+      @deleted = true
     end
 
-    # :stopdoc:
-    def inputs
-      warn "[DEPRECATION] 'inputs' is deprecated and will be removed in 1.0."
-      links[:inputs]
-    end
-
-    def set_input(input, value)
-      warn "[DEPRECATION] 'Run#set_input' is deprecated and will be removed " +
-        "in 1.0. Input ports are set directly instead. The most direct " +
-        "replacement for this method is: 'Run#input_port(input).value = value'"
-
-      input_port(input).value = value
-    end
-
-    def set_input_file(input, filename)
-      warn "[DEPRECATION] 'Run#set_input_file' is deprecated and will be " +
-        "removed in 1.0. Input ports are set directly instead. The most " +
-        "direct replacement for this method is: " +
-        "'Run#input_port(input).remote_file = filename'"
-
-      input_port(input).remote_file = filename
+    # :call-seq:
+    #   deleted? -> true or false
+    #
+    # Has this run been deleted from the server?
+    def deleted?
+      @deleted
     end
-    # :startdoc:
 
     # :call-seq:
-    #   input_ports -> Hash
+    #   input_ports -> hash
     #
     # Return a hash (name, port) of all the input ports this run expects.
     def input_ports
-      @input_ports = _get_input_port_info if @input_ports.nil?
-
-      @input_ports
+      @input_ports ||= _get_input_port_info
     end
 
     # :call-seq:
-    #   input_port(port) -> Port
+    #   input_port(port) -> port
     #
     # Get _port_.
     def input_port(port)
@@ -237,12 +252,12 @@ module T2Server
     end
 
     # :call-seq:
-    #   output_ports -> Hash
+    #   output_ports -> hash
     #
     # Return a hash (name, port) of all the output ports this run has. Until
     # the run is finished this method will return _nil_.
     def output_ports
-      if finished? and @output_ports.nil?
+      if finished? && @output_ports.nil?
         @output_ports = _get_output_port_info
       end
 
@@ -250,34 +265,13 @@ module T2Server
     end
 
     # :call-seq:
-    #   output_port(port) -> Port
+    #   output_port(port) -> port
     #
     # Get output port _port_.
     def output_port(port)
       output_ports[port] if finished?
     end
 
-    # :stopdoc:
-    def get_output_ports
-      warn "[DEPRECATION] 'get_output_ports' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#output_ports' instead."
-      lists, items = _ls_ports("out")
-      items + lists
-    end
-
-    def get_output(output, refs=false)
-      warn "[DEPRECATION] 'get_output' is deprecated and will be removed " +
-        "in 1.0. Please use 'Run#output_port(port).values' instead."
-      _get_output(output, refs)
-    end
-
-    def get_output_refs(output)
-      warn "[DEPRECATION] 'get_output_refs' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#output_port(port).data' instead."
-      _get_output(output, true)
-    end
-    # :startdoc:
-
     # :call-seq:
     #   expiry -> string
     #
@@ -287,7 +281,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   expiry=(time) -> bool
+    #   expiry = time -> true or false
     #
     # Set the expiry time of this run to _time_. _time_ should either be a Time
     # object or something that the Time class can parse. If the value given
@@ -323,13 +317,15 @@ module T2Server
     # Get the status of this run. Status can be one of :initialized,
     # :running or :finished.
     def status
-      text_to_state(@server.read(links[:status], "text/plain", @credentials))
+      return :deleted if @deleted
+      Status.to_sym(@server.read(links[:status], "text/plain", @credentials))
     end
 
     # :call-seq:
-    #   start
+    #   start -> true or false
     #
-    # Start this run on the server.
+    # Start this run on the server. Returns true if the run was started, false
+    # otherwise.
     #
     # Raises RunStateError if the run is not in the :initialized state.
     def start
@@ -339,8 +335,12 @@ module T2Server
       # set all the inputs
       _check_and_set_inputs unless baclava_input?
 
-      @server.update(links[:status], state_to_text(:running), "text/plain",
-        @credentials)
+      begin
+        @server.update(links[:status], Status.to_text(:running), "text/plain",
+          @credentials)
+      rescue ServerAtCapacityError => sace
+        false
+      end
     end
 
     # :call-seq:
@@ -349,23 +349,11 @@ module T2Server
     # Wait (block) for this run to finish. How often (in seconds) the run is
     # tested for completion can be specified with check_interval.
     #
-    # Raises RunStateError if the run is still in the :initialised state.
-    def wait(*params)
+    # Raises RunStateError if the run is still in the :initialized state.
+    def wait(interval = 1)
       state = status
       raise RunStateError.new(state, :running) if state == :initialized
 
-      interval = 1
-      params.each do |param|
-        case param
-        when Hash
-          warn "[DEPRECATION] 'Run#wait(params={})' is deprecated and will " +
-            "be removed in 1.0. Please use Run#wait(check_interval) instead."
-          interval = param[:interval] || 1
-        when Integer
-          interval = param
-        end
-      end
-
       # wait
       until finished?
         sleep(interval)
@@ -373,7 +361,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   exitcode -> integer
+    #   exitcode -> fixnum
     #
     # Get the return code of the run. Zero indicates success.
     def exitcode
@@ -397,7 +385,32 @@ module T2Server
     end
 
     # :call-seq:
-    #   mkdir(dir) -> bool
+    #   log -> string
+    #   log(filename) -> fixnum
+    #   log(stream) -> fixnum
+    #   log {|chunk| ...}
+    #
+    # Get the internal Taverna Server log from this run.
+    #
+    # Calling this method with no parameters will simply return a text string.
+    # 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
+    # text 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.log do |chunk|
+    #     print chunk
+    #   end
+    def log(param = nil, &block)
+      raise ArgumentError,
+        'both a parameter and block given for baclava_output' if param && block
+
+      download_or_stream(param, links[:logfile], "text/plain", &block)
+    end
+
+    # :call-seq:
+    #   mkdir(dir) -> true or false
     #
     # Create a directory in the run's working directory on the server. This
     # could be used to store input data.
@@ -426,7 +439,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   upload_data(data, remote_name, remote_directory = "") -> bool
+    #   upload_data(data, remote_name, remote_directory = "") -> true or false
     #
     # Upload data to the server and store it in <tt>remote_file</tt>. The
     # remote directory to put this file in can also be specified, but if it is
@@ -436,19 +449,8 @@ module T2Server
       @server.upload_data(data, remote_name, location_uri, @credentials)
     end
 
-    # :stopdoc:
-    def upload_input_file(input, filename, params={})
-      warn "[DEPRECATION] 'Run#upload_input_file' is deprecated and will be " +
-        "removed in 1.0. Input ports are set directly instead. The most " +
-        "direct replacement for this method is: " +
-        "'Run#input_port(input).file = filename'"
-
-      input_port(input).file = filename
-    end
-    # :startdoc:
-
     # :call-seq:
-    #   baclava_input=(filename) -> bool
+    #   baclava_input = filename -> true or false
     #
     # Use a baclava file for the workflow inputs.
     def baclava_input=(filename)
@@ -463,22 +465,8 @@ module T2Server
       result
     end
 
-    # :stopdoc:
-    def upload_baclava_input(filename)
-      warn "[DEPRECATION] 'upload_baclava_input' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#baclava_input=' instead."
-      self.baclava_input = filename
-    end
-
-    def upload_baclava_file(filename)
-      warn "[DEPRECATION] 'upload_baclava_file' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#baclava_input=' instead."
-      self.baclava_input = filename
-    end
-    # :startdoc:
-
     # :call-seq:
-    #   request_baclava_output -> bool
+    #   request_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.
@@ -491,16 +479,8 @@ module T2Server
         @credentials)
     end
 
-    # :stopdoc:
-    def set_baclava_output(name="")
-      warn "[DEPRECATION] 'set_baclava_output' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#request_baclava_output' instead."
-      self.request_baclava_output
-    end
-    # :startdoc:
-
     # :call-seq:
-    #   baclava_input? -> bool
+    #   baclava_input? -> true or false
     #
     # Have the inputs to this run been set by a baclava document?
     def baclava_input?
@@ -508,7 +488,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   baclava_output? -> bool
+    #   baclava_output? -> true or false
     #
     # Has this run been set to return results in baclava format?
     def baclava_output?
@@ -517,43 +497,74 @@ module T2Server
 
     # :call-seq:
     #   baclava_output -> string
+    #   baclava_output(filename) -> fixnum
+    #   baclava_output(stream) -> fixnum
+    #   baclava_output {|chunk| ...}
     #
     # Get the outputs of this run in baclava format. This can only be done if
     # the output has been requested in baclava format by #set_baclava_output
     # before starting the run.
-    def baclava_output
+    #
+    # Calling this method with no parameters will simply return a blob of
+    # XML 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 XML 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.baclava_output do |chunk|
+    #     print chunk
+    #   end
+    #
+    # Raises RunStateError if the run has not finished running.
+    def baclava_output(param = nil, &block)
+      raise ArgumentError,
+        'both a parameter and block given for baclava_output' if param && block
+
       state = status
       raise RunStateError.new(state, :finished) if state != :finished
 
       raise AccessForbiddenError.new("baclava output") if !@baclava_out
 
       baclava_uri = Util.append_to_uri_path(links[:wdir], BACLAVA_FILE)
-      @server.read(baclava_uri, "*/*", @credentials)
+      download_or_stream(param, baclava_uri, "*/*", &block)
     end
 
-    # :stopdoc:
-    def get_baclava_output
-      warn "[DEPRECATION] 'get_baclava_output' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#baclava_output' instead."
-      baclava_output
-    end
-    # :startdoc:
-
     # :call-seq:
     #   zip_output -> binary blob
+    #   zip_output(filename) -> fixnum
+    #   zip_output(stream) -> fixnum
+    #   zip_output {|chunk| ...}
     #
     # Get the working directory of this run directly from the server in zip
     # format.
-    def zip_output
+    #
+    # 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 zip 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.zip_output do |chunk|
+    #     print chunk
+    #   end
+    #
+    # Raises RunStateError if the run has not finished running.
+    def zip_output(param = nil, port = "", &block)
+      raise ArgumentError,
+        "both a parameter and block given for zip_output" if param && block
+
       state = status
       raise RunStateError.new(state, :finished) if state != :finished
 
-      output_uri = Util.append_to_uri_path(links[:wdir], "out")
-      @server.read(output_uri, "application/zip", @credentials)
+      path = port.empty? ? "out" : "out/#{port}"
+      output_uri = Util.append_to_uri_path(links[:wdir], path)
+      download_or_stream(param, output_uri, "application/zip", &block)
     end
 
     # :call-seq:
-    #   initialized? -> bool
+    #   initialized? -> true or false
     #
     # Is this run in the :initialized state?
     def initialized?
@@ -561,7 +572,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   running? -> bool
+    #   running? -> true or false
     #
     # Is this run in the :running state?
     def running?
@@ -569,13 +580,28 @@ module T2Server
     end
 
     # :call-seq:
-    #   finished? -> bool
+    #   finished? -> true or false
     #
     # Is this run in the :finished state?
     def finished?
       status == :finished
     end
 
+    # :call-seq:
+    #   error? -> true or false
+    #
+    # Are there errors in this run's outputs? Returns false if the run is not
+    # finished yet.
+    def error?
+      return false unless finished?
+
+      output_ports.values.each do |output|
+        return true if output.error?
+      end
+
+      false
+    end
+
     # :call-seq:
     #   create_time -> string
     #
@@ -601,7 +627,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   owner? -> bool
+    #   owner? -> true or false
     #
     # Are the credentials being used to access this run those of the owner?
     # The owner of the run can give other users certain access rights to their
@@ -639,9 +665,9 @@ module T2Server
       doc = xml_document(@server.read(links[:sec_perms], "application/xml",
         @credentials))
 
-      xpath_find(doc, XPaths[:sec_perm]).each do |p|
-        user = xml_node_content(xpath_first(p, XPaths[:sec_uname]))
-        perm = xml_node_content(xpath_first(p, XPaths[:sec_uperm])).to_sym
+      xpath_find(doc, @@xpaths[:sec_perm]).each do |p|
+        user = xml_node_content(xpath_first(p, @@xpaths[:sec_uname]))
+        perm = xml_node_content(xpath_first(p, @@xpaths[:sec_uperm])).to_sym
         perms[user] = perm
       end
 
@@ -657,11 +683,11 @@ module T2Server
     def permission(username)
       return unless owner?
 
-      permissions[username]
+      permissions[username] || :none
     end
 
     # :call-seq:
-    #   revoke_permission(username) -> bool
+    #   revoke_permission(username) -> true or false
     #
     # Revoke whatever permissions that have been granted to the user. Only the
     # owner of a run may revoke permissions on it. +nil+ is returned if a user
@@ -729,7 +755,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   credentials -> Hash
+    #   credentials -> hash
     #
     # Return a hash (service_uri => credential_uri) of all the credentials
     # provided for this run. Only the owner of a run may query its credentials.
@@ -741,8 +767,8 @@ module T2Server
       doc = xml_document(@server.read(links[:sec_creds], "application/xml",
         @credentials))
 
-      xpath_find(doc, XPaths[:sec_cred]).each do |c|
-        uri = URI.parse(xml_node_content(xpath_first(c, XPaths[:sec_suri])))
+      xpath_find(doc, @@xpaths[:sec_cred]).each do |c|
+        uri = URI.parse(xml_node_content(xpath_first(c, @@xpaths[:sec_suri])))
         cred_uri = URI.parse(xml_node_attribute(c, "href"))
         creds[uri] = cred_uri
       end
@@ -763,7 +789,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   delete_credential(service_uri) -> bool
+    #   delete_credential(service_uri) -> true or false
     #
     # Delete the credential that has been provided for the specified service.
     # Only the owner of a run may delete its credentials. +nil+ is returned if
@@ -775,7 +801,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   delete_all_credentials -> bool
+    #   delete_all_credentials -> true or false
     #
     # Delete all credentials associated with this workflow run. Only the owner
     # of a run may delete its credentials. +nil+ is returned if a user other
@@ -805,7 +831,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   trusts -> Array
+    #   trusts -> array
     #
     # Return a list of all the URIs of trusts that have been registered for
     # this run. At present there is no way to differentiate between trusts
@@ -819,7 +845,7 @@ module T2Server
       doc = xml_document(@server.read(links[:sec_trusts], "application/xml",
         @credentials))
 
-      xpath_find(doc, XPaths[:sec_trust]). each do |t|
+      xpath_find(doc, @@xpaths[:sec_trust]). each do |t|
         t_uris << URI.parse(xml_node_attribute(t, "href"))
       end
 
@@ -827,7 +853,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   delete_trust(URI) -> bool
+    #   delete_trust(URI) -> true or false
     #
     # Delete the trust with the provided URI. Only the owner of a run may
     # delete its trusts. +nil+ is returned if a user other than the owner uses
@@ -839,7 +865,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   delete_all_trusts -> bool
+    #   delete_all_trusts -> true or false
     #
     # Delete all trusted identities associated with this workflow run. Only
     # the owner of a run may delete its trusts. +nil+ is returned if a user
@@ -854,17 +880,76 @@ module T2Server
     # Outputs are represented as a directory structure with the eventual list
     # items (leaves) as files. This method (not part of the public API)
     # downloads a file from the run's working directory.
-    def download_output_data(uri, range = nil)
-      @server.read(uri, "application/octet-stream", range, @credentials)
+    def download_output_data(uri, range = nil, &block)
+      @server.read(uri, "application/octet-stream", range, @credentials,
+        &block)
+    end
+
+    # Read from the run's notification feed.
+    def read_notification_feed
+      @server.read(links[:feed], "application/atom+xml", @credentials)
+    end
+
+    # Write to the run's notification feed.
+    def write_notification(entry)
+      @server.create(links[:feed], entry, "application/atom+xml", @credentials)
+    end
+
+    # Read a file from the interactions directory for this run on the server.
+    def read_interaction_data(name)
+      uri = Util.append_to_uri_path(links[:feeddir], name)
+      @server.read(uri, "*/*", @credentials)
+    end
+
+    # Write a file to the interactions directory for this run on the server.
+    def write_interaction_data(name, data)
+      uri = Util.append_to_uri_path(links[:feeddir], name)
+      @server.update(uri, data, "*/*", @credentials)
+    end
+
+    # This is a slightly unpleasant hack to help proxy notification
+    # communications through a third party.
+    def notifications_uri
+      links[:feed] || ""
+    end
+
+    # This is a slightly unpleasant hack to help proxy interaction
+    # communications through a third party.
+    def interactions_uri
+      links[:feeddir] || ""
     end
     # :startdoc:
 
+    # :call-seq:
+    #   notifications(type = :new_requests) -> array
+    #
+    # Poll the server for notifications and return them in a list. Returns the
+    # empty list if there are none, or if the server does not support the
+    # Interaction Service.
+    #
+    # The +type+ parameter is used to select which types of notifications are
+    # returned as follows:
+    # * <tt>:requests</tt> - Interaction requests.
+    # * <tt>:replies</tt> - Interaction replies.
+    # * <tt>:new_requests</tt> - Interaction requests that are new since the
+    #   last time they were polled (default).
+    # * <tt>:all</tt> - All interaction requests and replies.
+    def notifications(type = :new_requests)
+      return [] if links[:feed].nil?
+
+      @interaction_reader ||= Interaction::Feed.new(self)
+
+      if type == :new_requests
+        @interaction_reader.new_requests
+      else
+        @interaction_reader.notifications(type)
+      end
+    end
+
     private
 
     def links
-      @links = _get_run_links if @links.nil?
-
-      @links
+      @links ||= _get_run_links
     end
 
     # Check each input to see if it requires a list input and call the
@@ -887,24 +972,18 @@ module T2Server
       input_ports.each_value do |port|
         next unless port.set?
 
+        uri = Util.append_to_uri_path(links[:inputs], "input/#{port.name}")
         if port.file?
           # If we're using a local file upload it first then set the port to
           # use a remote file.
-          unless port.remote_file?
-            file = upload_file(port.file)
-            port.remote_file = file
-          end
+          port.remote_file = upload_file(port.file) unless port.remote_file?
 
-          xml_value = xml_text_node(port.file)
-          uri = Util.append_to_uri_path(links[:inputs], "input/#{port.name}")
-          @server.update(uri, XML::Fragments::RUNINPUTFILE % xml_value,
-            "application/xml", @credentials)
+          xml_value = XML::Fragments::RUNINPUTFILE % xml_text_node(port.file)
         else
-          xml_value = xml_text_node(port.value)
-          uri = Util.append_to_uri_path(links[:inputs], "input/#{port.name}")
-          @server.update(uri, XML::Fragments::RUNINPUTVALUE % xml_value,
-            "application/xml", @credentials)
+          xml_value = XML::Fragments::RUNINPUTVALUE % xml_text_node(port.value)
         end
+
+        @server.update(uri, xml_value, "application/xml", @credentials)
       end
     end
 
@@ -950,90 +1029,6 @@ module T2Server
       u.to_s
     end
 
-    # List a directory in the run's workspace on the server. If dir is left
-    # blank then / is listed. As there is no concept of changing into a
-    # directory (cd) in Taverna Server then all paths passed into _ls_ports
-    # should be full paths starting at "root". The contents of a directory are
-    # returned as a list of two lists, "lists" and "values" respectively.
-    def _ls_ports(dir="", top=true)
-      dir = Util.strip_path_slashes(dir)
-      uri = Util.append_to_uri_path(links[:wdir], dir)
-      dir_list = @server.read(uri, "*/*", @credentials)
-
-      # compile a list of directory entries stripping the
-      # directory name from the front of each filename
-      lists = []
-      values = []
-
-      doc = xml_document(dir_list)
-
-      xpath_find(doc, XPaths[:dir]).each do |e|
-        if top
-          lists << xml_node_content(e).split('/')[-1]
-        else
-          index = (xml_node_attribute(e, 'name').to_i - 1)
-          lists[index] = xml_node_content(e).split('/')[-1]
-        end
-      end
-
-      xpath_find(doc, XPaths[:file]).each do |e|
-        if top
-          values << xml_node_content(e).split('/')[-1]
-        else
-          index = (xml_node_attribute(e, 'name').to_i - 1)
-          values[index] = xml_node_content(e).split('/')[-1]
-        end
-      end
-
-      [lists, values]
-    end
-
-    def _get_output(output, refs=false, top=true)
-      output = Util.strip_path_slashes(output)
-
-      # if at the top level we need to check if the port represents a list
-      # or a singleton value
-      if top
-        lists, items = _ls_ports("out")
-        if items.include? output
-          if refs
-            return "#{@server.uri}/rest/runs/#{@identifier}/" +
-              "#{links[:wdir]}/out/#{output}"
-          else
-            out_uri = Util.append_to_uri_path(links[:wdir], "out/#{output}")
-            return @server.read(out_uri, "application/octet-stream",
-              @credentials)
-          end
-        end
-      end
-
-      # we're not at the top level so look at the contents of the output port
-      lists, items = _ls_ports("out/#{output}", false)
-
-      # build up lists of results
-      result = []
-
-      # for each list recurse into it and add the items to the result
-      lists.each do |list|
-        result << _get_output("#{output}/#{list}", refs, false)
-      end
-
-      # for each item, add it to the output list
-      items.each do |item|
-        if refs
-          result << "#{@server.uri}/rest/runs/#{@identifier}/" +
-            "#{links[:wdir]}/out/#{output}/#{item}"
-        else
-          out_uri = Util.append_to_uri_path(links[:wdir],
-            "out/#{output}/#{item}")
-          result << @server.read(out_uri, "application/octet-stream",
-            @credentials)
-        end
-      end
-
-      result
-    end
-
     def _get_input_port_info
       ports = {}
       port_desc = @server.read(links[:inputexp], "application/xml",
@@ -1041,7 +1036,7 @@ module T2Server
 
       doc = xml_document(port_desc)
 
-      xpath_find(doc, XPaths[:port_in]).each do |inp|
+      xpath_find(doc, @@xpaths[:port_in]).each do |inp|
         port = InputPort.new(self, inp)
         ports[port.name] = port
       end
@@ -1060,7 +1055,7 @@ module T2Server
 
       doc = xml_document(port_desc)
 
-      xpath_find(doc, XPaths[:port_out]).each do |out|
+      xpath_find(doc, @@xpaths[:port_out]).each do |out|
         port = OutputPort.new(self, out)
         ports[port.name] = port
       end
@@ -1080,32 +1075,31 @@ module T2Server
     def _get_run_owner
       doc = _get_run_description
 
-      xpath_attr(doc, XPaths[:run_desc], "owner")
+      xpath_attr(doc, @@xpaths[:run_desc], "owner")
     end
 
     def _get_run_links
       doc = _get_run_description
 
       # first parse out the basic stuff
-      links = {}
+      links = get_uris_from_doc(doc, [:expiry, :workflow, :status,
+        :createtime, :starttime, :finishtime, :wdir, :inputs, :output,
+        :securectx, :listeners, :name, :feed])
 
-      [:expiry, :workflow, :status, :createtime, :starttime, :finishtime,
-        :wdir, :inputs, :output, :securectx, :listeners].each do |key|
-          links[key] = URI.parse(xpath_attr(doc, XPaths[key], "href"))
-      end
+      # Working dir links
+      _get_wdir_links(links)
 
       # get inputs
       inputs = @server.read(links[:inputs], "application/xml",@credentials)
       doc = xml_document(inputs)
 
-      links[:baclava] = URI.parse(xpath_attr(doc, XPaths[:baclava], "href"))
-      links[:inputexp] = URI.parse(xpath_attr(doc, XPaths[:inputexp], "href"))
+      links.merge! get_uris_from_doc(doc, [:baclava, :inputexp])
 
       # set io properties
       links[:io]       = Util.append_to_uri_path(links[:listeners], "io")
-      links[:stdout]   = Util.append_to_uri_path(links[:io], "properties/stdout")
-      links[:stderr]   = Util.append_to_uri_path(links[:io], "properties/stderr")
-      links[:exitcode] = Util.append_to_uri_path(links[:io], "properties/exitcode")
+      [:stdout, :stderr, :exitcode].each do |res|
+        links[res] = Util.append_to_uri_path(links[:io], "properties/#{res}")
+      end
 
       # security properties - only available to the owner of a run
       if owner?
@@ -1113,39 +1107,62 @@ module T2Server
           @credentials)
         doc = xml_document(securectx)
 
-        [:sec_creds, :sec_perms, :sec_trusts].each do |key|
-          #links[key] = "#{links[:securectx]}/" + xpath_attr(doc, XPaths[key],
-          #  "href").split('/')[-1]
-          links[key] = Util.append_to_uri_path(links[:securectx],
-            xpath_attr(doc, XPaths[key], "href").split('/')[-1])
-        end
+        links.merge! get_uris_from_doc(doc,
+          [:sec_creds, :sec_perms, :sec_trusts])
       end
 
       links
     end
 
-    # :stopdoc:
-    STATE2TEXT = {
-      :initialized => "Initialized",
-      :running     => "Operating",
-      :finished    => "Finished",
-      :stopped     => "Stopped"
-    }
+    def _get_wdir_links(links)
+      # Logs directory
+      links[:logdir] = Util.append_to_uri_path(links[:wdir], "logs")
 
-    TEXT2STATE = {
-      "Initialized" => :initialized,
-      "Operating"   => :running,
-      "Finished"    => :finished,
-      "Stopped"     => :stopped
-    }
-    # :startdoc:
+      # Log file
+      links[:logfile] = Util.append_to_uri_path(links[:logdir], "detail.log")
 
-    def state_to_text(state)
-      STATE2TEXT[state.to_sym]
+      # Interaction working directory, if we have a feed.
+      unless links[:feed].nil?
+        links[:feeddir] = Util.append_to_uri_path(links[:wdir], "interactions")
+      end
     end
 
-    def text_to_state(text)
-      TEXT2STATE[text]
+    def download_or_stream(param, uri, type, &block)
+      if param.respond_to? :write
+        @server.read_to_stream(param, uri, type, @credentials)
+      elsif param.instance_of? String
+        @server.read_to_file(param, uri, type, @credentials)
+      else
+        @server.read(uri, type, @credentials, &block)
+      end
     end
+
+    # :stopdoc:
+    class Status
+      STATE2TEXT = {
+        :initialized => "Initialized",
+        :running     => "Operating",
+        :finished    => "Finished",
+        :stopped     => "Stopped",
+        :deleted     => "Deleted"
+      }
+
+      TEXT2STATE = {
+        "Initialized" => :initialized,
+        "Operating"   => :running,
+        "Finished"    => :finished,
+        "Stopped"     => :stopped
+      }
+
+      def Status.to_text(state)
+        STATE2TEXT[state.to_sym]
+      end
+
+      def Status.to_sym(text)
+        TEXT2STATE[text]
+      end
+    end
+    # :startdoc:
+
   end
 end