t2-server 0.9.3 → 1.0.0

data/lib/t2-server/server.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.
 #
@@ -32,6 +32,7 @@
 
 require 'base64'
 require 'uri'
+require 't2-server/run-cache'
 
 module T2Server
 
@@ -45,21 +46,22 @@ module T2Server
     # endpoints.
     REST_ENDPOINT = "rest/"
 
-    XPaths = {
+    XPATHS = {
       # Server top-level XPath queries
-      :server   => XML::Methods.xpath_compile("//nsr:serverDescription"),
-      :policy   => XML::Methods.xpath_compile("//nsr:policy"),
-      :run      => XML::Methods.xpath_compile("//nsr:run"),
-      :runs     => XML::Methods.xpath_compile("//nsr:runs"),
+      :server   => "//nsr:serverDescription",
+      :policy   => "//nsr:policy",
+      :run      => "//nsr:run",
+      :runs     => "//nsr:runs",
 
       # Server policy XPath queries
-      :runlimit => XML::Methods.xpath_compile("//nsr:runLimit"),
-      :permwkf  => XML::Methods.xpath_compile("//nsr:permittedWorkflows"),
-      :permlstn => XML::Methods.xpath_compile("//nsr:permittedListeners"),
-      :permlstt => XML::Methods.xpath_compile("//nsr:permittedListenerTypes"),
-      :notify   =>
-        XML::Methods.xpath_compile("//nsr:enabledNotificationFabrics")
+      :runlimit      => "//nsr:runLimit",
+      :permworkflows => "//nsr:permittedWorkflows",
+      :permlisteners => "//nsr:permittedListenerTypes",
+      :notifications => "//nsr:enabledNotificationFabrics"
     }
+
+    @@xpaths = XML::XPathCache.instance
+    @@xpaths.register_xpaths XPATHS
     # :startdoc:
 
     # :call-seq:
@@ -72,16 +74,9 @@ module T2Server
     #
     # It will _yield_ itself if a block is given.
     def initialize(uri, params = nil)
-      # we want to use URIs here but strings can be passed in
-      unless uri.is_a? URI
-        uri = URI.parse(Util.strip_path_slashes(uri))
-      end
-
-      # strip username and password from the URI if present
-      if uri.user != nil
-        uri = URI::HTTP.new(uri.scheme, nil, uri.host, uri.port, nil,
-        uri.path, nil, nil, nil);
-      end
+      # Convert strings to URIs and strip any credentials that have been given
+      # in the URI. We do not want to store credentials in this class.
+      uri, creds = Util.strip_uri_credentials(uri)
 
       # setup connection
       @connection = ConnectionFactory.connect(uri, params)
@@ -93,20 +88,12 @@ module T2Server
       @version_components = nil
       @links = nil
 
-      # initialize run object cache
-      @runs = {}
+      # Initialize the run object cache.
+      @run_cache = RunCache.new(self)
 
       yield(self) if block_given?
     end
 
-    # :stopdoc:
-    def Server.connect(uri, username="", password="")
-      warn "[DEPRECATION] 'Server#connect' is deprecated and will be " +
-        "removed in 1.0."
-      new(uri)
-    end
-    # :startdoc:
-
     # :call-seq:
     #   administrator(credentials = nil) -> Administrator
     #   administrator(credentials = nil) {|admin| ...}
@@ -126,47 +113,61 @@ module T2Server
     #
     # Create a run on this server using the specified _workflow_.
     # This method will _yield_ the newly created Run if a block is given.
+    #
+    # The _workflow_ parameter may be the workflow itself, a file name or a
+    # File or IO object.
     def create_run(workflow, credentials = nil)
-      id = initialize_run(workflow, credentials)
-      run = Run.create(self, "", credentials, id)
+      uri = initialize_run(workflow, credentials)
+      run = Run.create(self, "", credentials, uri)
 
-      # cache newly created run object - this must be done per user
-      user = credentials.nil? ? :all : credentials.username
-      @runs[user] = {} unless @runs[user]
-      @runs[user][id] = run
+      # Add the newly created run object to the user's run cache
+      @run_cache.add_run(run, credentials)
 
       yield(run) if block_given?
       run
     end
 
-    # :call-seq:
-    #   initialize_run(workflow, credentials = nil) -> string
+    # :stopdoc:
+    # Create a run on this server using the specified _workflow_ and return
+    # the URI to it.
     #
-    # Create a run on this server using the specified _workflow_ but do not
-    # return it as a Run instance. Return its identifier instead.
+    # We need to catch AccessForbiddenError here to be compatible with Server
+    # versions pre 2.4.2. When we no longer support them we can remove the
+    # rescue clause of this method.
     def initialize_run(workflow, credentials = nil)
-      # set up the run object cache - this must be done per user
-      user = credentials.nil? ? :all : credentials.username
-      @runs[user] = {} unless @runs[user]
+      # If workflow is a String, it might be a filename! If so, stream it.
+      if (workflow.instance_of? String) && (File.file? workflow)
+        return File.open(workflow, "r") do |file|
+          create(links[:runs], file, "application/vnd.taverna.t2flow+xml",
+            credentials)
+        end
+      end
 
-      @connection.POST(links[:runs], workflow,
-        "application/vnd.taverna.t2flow+xml", credentials)
+      # If we get here then workflow could either be a String containing a
+      # workflow or a File or IO object.
+      create(links[:runs], workflow, "application/vnd.taverna.t2flow+xml",
+        credentials)
+    rescue AccessForbiddenError => afe
+      (major, minor, patch) = version_components
+      if minor == 4 && patch >= 2
+        # Need to re-raise as it's a real error for later versions.
+        raise afe
+      else
+        raise ServerAtCapacityError.new
+      end
     end
+    # :startdoc:
 
     # :call-seq:
-    #   version -> String
+    #   version -> string
     #
     # The version string of the remote Taverna Server.
     def version
-      if @version.nil?
-        @version = _get_version
-      end
-
-      @version
+      @version ||= _get_version
     end
 
     # :call-seq:
-    #   version_components -> Array
+    #   version_components -> array
     #
     # An array of the major, minor and patch version components of the remote
     # Taverna Server.
@@ -188,7 +189,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   run_limit(credentials = nil) -> num
+    #   run_limit(credentials = nil) -> fixnum
     #
     # The maximum number of runs that this server will allow at any one time.
     # Runs in any state (+Initialized+, +Running+ and +Finished+) are counted
@@ -213,26 +214,6 @@ module T2Server
       get_runs(credentials)[identifier]
     end
 
-    # :stopdoc:
-    def delete_run(run, credentials = nil)
-      warn "[DEPRECATION] 'Server#delete_run' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#delete' to delete a run."
-
-      # get the identifier from the run if that is what is passed in
-      if run.instance_of? Run
-        run = run.identifier
-      end
-
-      run_uri = Util.append_to_uri_path(links[:runs], run)
-      if delete(run_uri, credentials)
-        # delete cached run object - this must be done per user
-        user = credentials.nil? ? :all : credentials.username
-        @runs[user].delete(run) if @runs[user]
-        true
-      end
-    end
-    # :startdoc:
-
     # :call-seq:
     #   delete_all_runs(credentials = nil)
     #
@@ -240,56 +221,31 @@ module T2Server
     # only those runs that the provided credentials have permission to delete
     # will be deleted.
     def delete_all_runs(credentials = nil)
-      # first refresh run list
+      # Refresh run list, delete everything, clear the user's run cache.
       runs(credentials).each {|run| run.delete}
+      @run_cache.clear!(credentials)
     end
 
     # :stopdoc:
-    def set_run_input(run, input, value, credentials = nil)
-      warn "[DEPRECATION] 'Server#set_run_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'"
-
-      # get the run from the identifier if that is what is passed in
-      if not run.instance_of? Run
-        run = run(run, credentials)
-      end
-
-      run.input_port(input).value = value
-    end
-
-    def set_run_input_file(run, input, filename, credentials = nil)
-      warn "[DEPRECATION] 'Server#set_run_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'"
-
-      # get the run from the identifier if that is what is passed in
-      if not run.instance_of? Run
-        run = run(run, credentials)
-      end
-
-      run.input_port(input).remote_file = filename
-    end
-
     def mkdir(uri, dir, credentials = nil)
       @connection.POST(uri, XML::Fragments::MKDIR % dir, "application/xml",
         credentials)
     end
 
-    def make_run_dir(run, root, dir, credentials = nil)
-      warn "[DEPRECATION] 'Server#make_run_dir' is deprecated and will be " +
-        "removed in 1.0. Please use 'Run#mkdir' instead."
-
-      create_dir(run, root, dir, credentials)
-    end
-
     def upload_file(filename, uri, remote_name, credentials = nil)
-      contents = IO.read(filename)
+      # Different Server versions support different upload methods
+      (major, minor, patch) = version_components
+
       remote_name = filename.split('/')[-1] if remote_name == ""
 
-      upload_data(contents, remote_name, uri, credentials)
+      if minor == 4 && patch >= 1
+        File.open(filename, "rb") do |file|
+          upload_data(file, remote_name, uri, credentials)
+        end
+      else
+        contents = IO.read(filename)
+        upload_data(contents, remote_name, uri, credentials)
+      end
     end
 
     def upload_data(data, remote_name, uri, credentials = nil)
@@ -307,14 +263,6 @@ module T2Server
       end
     end
 
-    def upload_run_file(run, filename, location, rename, credentials = nil)
-      warn "[DEPRECATION] 'Server#upload_run_file' is deprecated and will " +
-        "be removed in 1.0. Please use 'Run#upload_file' or " +
-        "'Run#input_port(input).file = filename' instead."
-
-      upload_file(run, filename, location, rename, credentials)
-    end
-
     def is_resource_writable?(uri, credentials = nil)
       headers = @connection.OPTIONS(uri, credentials)
       headers["allow"][0].split(",").include? "PUT"
@@ -324,7 +272,7 @@ module T2Server
       @connection.POST(uri, value, type, credentials)
     end
 
-    def read(uri, type, *rest)
+    def read(uri, type, *rest, &block)
       credentials = nil
       range = nil
 
@@ -340,7 +288,7 @@ module T2Server
       end
 
       begin
-        @connection.GET(uri, type, range, credentials)
+        @connection.GET(uri, type, range, credentials, &block)
       rescue ConnectionRedirectError => cre
         # We've been redirected so save the new connection object with the new
         # server URI and try again with the new URI.
@@ -350,21 +298,51 @@ module T2Server
       end
     end
 
+    # An internal helper to write streamed data directly to another stream.
+    # The number of bytes written to the stream is returned. The stream passed
+    # in may be anything that provides a +write+ method; instances of IO and
+    # File, for example.
+    def read_to_stream(stream, uri, type, *rest)
+      raise ArgumentError,
+        "Stream passed in must provide a write method" unless
+          stream.respond_to? :write
+
+      bytes = 0
+
+      read(uri, type, *rest) do |chunk|
+        bytes += stream.write(chunk)
+      end
+
+      bytes
+    end
+
+    # An internal helper to write streamed data straight to a file.
+    def read_to_file(filename, uri, type, *rest)
+      File.open(filename, "wb") do |file|
+        read_to_stream(file, uri, type, *rest)
+      end
+    end
+
     def update(uri, value, type, credentials = nil)
       @connection.PUT(uri, value, type, credentials)
     end
 
     def delete(uri, credentials = nil)
       @connection.DELETE(uri, credentials)
+    rescue AttributeNotFoundError => ane
+      # Ignore this. Delete is idempotent so deleting something that has
+      # already been deleted, or is for some other reason not there, should
+      # happen silently. Return true here because when deleting it's enough to
+      # know that it's no longer there rather than whether it was deleted
+      # *this time* or not.
+      true
     end
     # :startdoc:
 
     private
 
     def links
-      @links = _get_server_links if @links.nil?
-
-      @links
+      @links ||= _get_server_links
     end
 
     def _get_server_description
@@ -378,15 +356,14 @@ module T2Server
 
     def _get_version
       doc = _get_server_description
-      version = xpath_attr(doc, XPaths[:server], "serverVersion")
+      version = xpath_attr(doc, @@xpaths[:server], "serverVersion")
       if version == nil
         raise RuntimeError.new("Taverna Servers prior to version 2.3 " +
           "are no longer supported.")
       else
-        # Remove SNAPSHOT tag if it's there.
-        if version.end_with? "-SNAPSHOT"
-          version.gsub!("-SNAPSHOT", "")
-        end
+        # Remove extra version tags if present.
+        version.gsub!("-SNAPSHOT", "")
+        version.gsub!(/alpha[0-9]*/, "")
 
         # Add .0 if we only have a major and minor component.
         if version.split(".").length == 2
@@ -399,23 +376,11 @@ module T2Server
 
     def _get_server_links
       doc = _get_server_description
-      links = {}
-      links[:runs] = URI.parse(xpath_attr(doc, XPaths[:runs], "href"))
+      links = get_uris_from_doc(doc, [:runs, :policy])
 
-      links[:policy] = URI.parse(xpath_attr(doc, XPaths[:policy], "href"))
       doc = xml_document(read(links[:policy], "application/xml"))
-
-      links[:permlisteners] =
-        URI.parse(xpath_attr(doc, XPaths[:permlstt], "href"))
-      links[:notifications] =
-        URI.parse(xpath_attr(doc, XPaths[:notify], "href"))
-
-      links[:runlimit]      =
-        URI.parse(xpath_attr(doc, XPaths[:runlimit], "href"))
-      links[:permworkflows] =
-        URI.parse(xpath_attr(doc, XPaths[:permwkf], "href"))
-
-      links
+      links.merge get_uris_from_doc(doc,
+        [:permlisteners, :notifications, :runlimit, :permworkflows])
     end
 
     def get_runs(credentials = nil)
@@ -425,29 +390,15 @@ module T2Server
 
       # get list of run identifiers
       run_list = {}
-      xpath_find(doc, XPaths[:run]).each do |run|
+      xpath_find(doc, @@xpaths[:run]).each do |run|
         uri = URI.parse(xml_node_attribute(run, "href"))
         id = xml_node_content(run)
         run_list[id] = uri
       end
 
-      # cache run objects - this must be done per user
-      user = credentials.nil? ? :all : credentials.username
-      @runs[user] = {} unless @runs[user]
-
-      # add new runs to the user cache
-      run_list.each_key do |id|
-        if !@runs[user].has_key? id
-          @runs[user][id] = Run.create(self, "", credentials, run_list[id])
-        end
-      end
-
-      # clear out the expired runs
-      if @runs[user].length > run_list.length
-        @runs[user].delete_if {|key, val| !run_list.member? key}
-      end
-
-      @runs[user]
+      # Refresh the user's cache and return the runs in it.
+      @run_cache.refresh_all!(run_list, credentials)
     end
+
   end
 end

data/lib/t2-server/util.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.
 #
@@ -30,23 +30,25 @@
 #
 # Author: Robert Haines
 
+# :stopdoc:
+# This comment is needed to stop the above licence from being included in the
+# documentation multiple times. Sigh.
 module T2Server
+# :startdoc:
 
   # This module contains various utility methods that the library uses
   # internally.
   module Util
 
     # :call-seq:
-    #   Util.strip_uri_credentials(uri) -> URI, Credentials
+    #   Util.strip_uri_credentials(uri) -> URI, HttpBasic
     #
     # Strip user credentials from an address in URI or String format and return
-    # a tuple of the URI minus the credentials and a T2Server::Credentials
+    # a tuple of the URI minus the credentials and a T2Server::HttpBasic
     # object.
     def self.strip_uri_credentials(uri)
       # we want to use URIs here but strings can be passed in
-      unless uri.is_a? URI
-        uri = URI.parse(Util.strip_path_slashes(uri))
-      end
+      uri = URI.parse(Util.strip_path_slashes(uri)) unless uri.is_a? URI
 
       creds = nil
 
@@ -62,7 +64,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   Util.strip_path_slashes(path) -> String
+    #   Util.strip_path_slashes(path) -> string
     #
     # Returns a new String with one leading and one trailing slash
     # removed from the ends of _path_ (if present).
@@ -95,8 +97,8 @@ module T2Server
       new_uri
     end
 
-    # :call_seq:
-    #   Util.get_path_leaf_from_uri(uri) -> String
+    # :call-seq:
+    #   Util.get_path_leaf_from_uri(uri) -> string
     #
     # Get the final component from the path of a URI. This method returns the
     # empty string (not _nil_ ) if the URI does not have a path.