t2-server 0.9.3 → 1.0.0

data/lib/t2-server/net/credentials.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2010, 2011 The University of Manchester, UK.
+# Copyright (c) 2010-2012 The University of Manchester, UK.
 #
 # All rights reserved.
 #
@@ -30,23 +30,33 @@
 #
 # 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 class serves as a base class for concrete HTTP credential systems.
+  #
+  # Instances of this class cannot be used to authenticate a connection;
+  # please use HttpBasic instead.
   class HttpCredentials
     # The username held by these credentials.
     attr_reader :username
 
+    # :stopdoc:
     # Create a set of credentials with the supplied username and password.
     def initialize(username, password)
       @username = username
       @password = password
     end
+    # :startdoc:
 
     # :call-seq:
-    #   to_s
+    #   to_s -> string
     #
-    # Return the username held by these credentials.
+    # Return a String representation of these credentials. Just the username
+    # is returned; the password is kept hidden.
     def to_s
       @username
     end
@@ -55,7 +65,7 @@ module T2Server
     @@to_s = Kernel.instance_method(:to_s)
 
     # :call-seq:
-    #   inspect
+    #   inspect -> string
     #
     # Override the Kernel#inspect method so that the password is not exposed
     # when it is called.
@@ -64,21 +74,27 @@ module T2Server
     end
   end
 
-  # A class representing HTTP Basic credentials.
+  # A class representing HTTP Basic credentials. Use this class to
+  # authenticate operations on a Taverna Server that require it.
+  #
+  # See also Util.strip_uri_credentials.
   class HttpBasic < HttpCredentials
 
-    # Create a set of credentials with the supplied username and password.
+    # :call-seq:
+    #   new(username, password) -> HttpBasic
+    #
+    # Create a set of basic credentials using the supplied username and
+    # password.
     def initialize(username, password)
       super(username, password)
     end
 
-    # :call-seq:
-    #   authenticate(request)
-    #
+    # :stopdoc:
     # Authenticate the supplied HTTP request with the credentials held within
     # this class.
     def authenticate(request)
       request.basic_auth @username, @password
     end
+    # :startdoc:
   end
 end

data/lib/t2-server/net/parameters.rb

@@ -39,11 +39,14 @@ module T2Server
   # stored.
   #
   # The parameters that can be set are:
-  # * :ca_file
-  # * :ca_path
-  # * :verify_peer
-  # * :client_certificate
-  # * :client_password
+  # * :ca_file - A file with the correct CA chain to verify the remote server.
+  # * :ca_path - A directory containing the CA files for server verification.
+  # * :verify_peer - Use peer verification? (true or false).
+  # * :client_certificate - File with the client's certificate and private key.
+  # * :client_password - The password to unlock the client's private key.
+  # * :ssl_version - The TLS/SSL version to use (:TLSv1, :SSLv23 or :SSLv3).
+  # * :open_timeout - The number of seconds to wait while opening a connection.
+  # * :read_timeout - The number of seconds to wait while reading from a connection.
   # All others will be ignored. Any parameters not set will return +nil+ when
   # queried.
   class ConnectionParameters
@@ -53,7 +56,10 @@ module T2Server
       :ca_path,
       :verify_peer,
       :client_certificate,
-      :client_password
+      :client_password,
+      :ssl_version,
+      :open_timeout,
+      :read_timeout
     ]
     # :startdoc:
 
@@ -98,6 +104,15 @@ module T2Server
     end
   end
 
+  # Connection parameters that specify the use of SSL version 3.
+  class SSL3ConnectionParameters < DefaultConnectionParameters
+    # Create connection parameters that specify the use of SSL version 3.
+    def initialize
+      super
+      self[:ssl_version] = :SSLv3
+    end
+  end
+
   # Connection parameters that simplify setting up verification of servers with
   # "self-signed" or non-standard certificates.
   class CustomCASSLConnectionParameters < DefaultConnectionParameters

data/lib/t2-server/port.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,7 +30,11 @@
 #
 # 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:
 
   # Base class of InputPort and OutputPort
   class Port
@@ -91,7 +95,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   file? -> bool
+    #   file? -> true or false
     #
     # Is this port's data being supplied by a file? The file could be local or
     # remote (already on the server) for this to return true.
@@ -100,7 +104,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   remote_file? -> bool
+    #   remote_file? -> true or false
     #
     # Is this port's data being supplied by a remote (one that is already on
     # the server) file?
@@ -135,7 +139,7 @@ module T2Server
     end
 
     # :call-seq:
-    #   baclava? -> bool
+    #   baclava? -> true or false
     #
     # Has this port been set via a baclava document?
     def baclava?
@@ -143,11 +147,11 @@ module T2Server
     end
 
     # :call-seq:
-    #   set? -> bool
+    #   set? -> true or false
     #
     # Has this port been set?
     def set?
-      !value.nil? or file? or baclava?
+      !value.nil? || file? || baclava?
     end
   end
 
@@ -173,13 +177,28 @@ module T2Server
     # :startdoc:
 
     # :call-seq:
-    #   error? -> bool
+    #   error? -> true or false
     #
     # Is there an error associated with this output port?
     def error?
       @error
     end
 
+    # :call-seq:
+    #   empty? -> true or false
+    #
+    # Is this output port empty?
+    #
+    # Note that if the output port holds a list then it is not considered
+    # empty, even if that list is empty. This is because the port itself is
+    # not empty, there is a list there! A separate test should be performed to
+    # see if that list is empty or not.
+    def empty?
+      # Funnily enough, an empty list does *not* make a port empty!
+      return false if @structure.instance_of? Array
+      @structure.empty?
+    end
+
     # :call-seq:
     #   [int] -> obj
     #
@@ -195,20 +214,27 @@ module T2Server
     end
 
     # :call-seq:
-    #   value -> obj
-    #   value(range) -> obj
-    #   value -> Array
-    #
-    # For singleton outputs get the value (or part of it). For list outputs
-    # get all the values in an Array structure that mirrors the structure of
-    # the output port. To get part of a value from a list use
-    # 'port[].value(range)'.
-    def value(range = nil)
+    #   value -> binary blob
+    #   value(range) -> binary blob
+    #   value {|chunk| ...}
+    #   value(range) {|chunk| ...}
+    #   value -> array
+    #
+    # For singleton outputs download or stream the data (or part of it) held
+    # by the output port. Please see the documentation for PortValue#value for
+    # full details.
+    #
+    # For list outputs all data values are downloaded into memory and returned
+    # in an Array structure that mirrors the structure of the output port. Do
+    # not use this form if the output port has large amounts of data! To get
+    # part of a value from a list use something like:
+    #   run.output_port("port_name")[0].value(0..100)
+    def value(range = nil, &block)
       if depth == 0
         if range.nil?
-          @structure.value
+          @structure.value(&block)
         else
-          @structure.value(range)
+          @structure.value(range, &block)
         end
       else
         @values = strip(:value) if @values.nil?
@@ -217,8 +243,55 @@ module T2Server
     end
 
     # :call-seq:
-    #   reference -> String
-    #   reference -> Array
+    #   stream_value(stream) -> fixnum
+    #   stream_value(stream, range) -> fixnum
+    #
+    # Stream a singleton port value directly to another stream and return the
+    # number of bytes written. If a range is supplied then only that range of
+    # data is streamed from the server. The stream passed in may be anything
+    # that provides a +write+ method; instances of IO and File, for example.
+    # No data is cached by this method.
+    #
+    # To stream parts of a list port, use PortValue#stream_value on the list
+    # item directly:
+    #   run.output_port("port_name")[0].stream_value(stream)
+    def stream_value(stream, range = nil)
+      return 0 unless depth == 0
+      raise ArgumentError,
+        "Stream passed in must provide a write method" unless
+          stream.respond_to? :write
+
+      if range.nil?
+        @structure.stream_value(stream)
+      else
+        @structure.stream_value(stream, range)
+      end
+    end
+
+    # :call-seq:
+    #   write_value_to_file(filename) -> fixnum
+    #   write_value_to_file(filename, range) -> fixnum
+    #
+    # Stream a singleton port value to a file and return the number of bytes
+    # written. If a range is supplied then only that range of data is
+    # downloaded from the server.
+    #
+    # To save parts of a list port to a file, use
+    # PortValue#write_value_to_file on the list item directly:
+    #   run.output_port("port_name")[0].write_value_to_file
+    def write_value_to_file(filename, range = nil)
+      return 0 unless depth == 0
+
+      if range.nil?
+        @structure.write_value_to_file(filename)
+      else
+        @structure.write_value_to_file(filename, range)
+      end
+    end
+
+    # :call-seq:
+    #   reference -> string
+    #   reference -> array
     #
     # Get URI references to the data values of this output port as strings.
     #
@@ -226,50 +299,35 @@ module T2Server
     # uris is returned. For an individual reference from a list use
     # 'port[].reference'.
     def reference
-      @refs = strip(:reference) if @refs.nil?
-      @refs
+      @refs ||= strip(:reference)
     end
 
     # :call-seq:
-    #   type -> String
-    #   type -> Array
+    #   type -> string
+    #   type -> array
     #
     # Get the mime type of the data value in this output port.
     #
     # For a singleton output a single type is returned. For lists an array of
     # types is returned. For an individual type from a list use 'port[].type'.
     def type
-      @types = strip(:type) if @types.nil?
-      @types
+      @types ||= strip(:type)
     end
 
     # :call-seq:
-    #   size -> int
-    #   size -> Array
+    #   size -> fixnum
+    #   size -> array
     #
     # Get the data size of the data value in this output port.
     #
     # For a singleton output a single size is returned. For lists an array of
     # sizes is returned. For an individual size from a list use 'port[].size'.
     def size
-      @sizes = strip(:size) if @sizes.nil?
-      @sizes
-    end
-
-    # :call-seq:
-    #   error -> String
-    #
-    # Get the error message (if there is one) of this output port.
-    #
-    # This method is only for use on outputs of depth 0. For other depths use
-    # 'port[].error'
-    def error
-      return nil unless depth == 0
-      @structure.error
+      @sizes ||= strip(:size)
     end
 
     # :call-seq:
-    #   total_size -> int
+    #   total_size -> fixnum
     #
     # Return the total data size of all the data in this output port.
     def total_size
@@ -282,9 +340,42 @@ module T2Server
       end
     end
 
+    # :call-seq:
+    #   zip -> binary blob
+    #   zip(filename) -> fixnum
+    #   zip(stream) -> fixnum
+    #   zip {|chunk| ...}
+    #
+    # Get the data in this output port directly from the server in zip format.
+    #
+    # This method does not work with singleton ports. Taverna Server cannot
+    # currently return zip files of singleton ports on their own. If you wish
+    # to get a singleton port in a zip file then you can use Run#zip_output
+    # which will return all outputs in a single file.
+    #
+    # If this method is called on a singleton port it will return +nil+ and
+    # streaming from it will return nothing.
+    #
+    # 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:
+    #   port.zip do |chunk|
+    #     print chunk
+    #   end
+    #
+    # Raises RunStateError if the run has not finished running.
+    def zip(param = nil, &block)
+      return nil if depth == 0
+      @run.zip_output(param, name, &block)
+    end
+
     # :stopdoc:
-    def download(uri, range = nil)
-      @run.download_output_data(uri, range)
+    def download(uri, range = nil, &block)
+      @run.download_output_data(uri, range, &block)
     end
     # :startdoc:
 
@@ -301,14 +392,15 @@ module T2Server
         return data
       when 'value'
         return PortValue.new(self, xml_node_attribute(node, 'href'), false,
-          xml_node_attribute(node, 'contentType'),
-          xml_node_attribute(node, 'contentByteLength').to_i)
+          xml_node_attribute(node, 'contentByteLength').to_i,
+          xml_node_attribute(node, 'contentType'))
       when 'error'
         @error = true
-        return PortValue.new(self, xml_node_attribute(node, 'href'), true)
+        return PortValue.new(self, xml_node_attribute(node, 'href'), true,
+          xml_node_attribute(node, 'errorByteLength').to_i)
       when 'absent'
         if current_depth == @depth
-          return PortValue.new(self, "", false, "application/x-empty")
+          return PortValue.new(self, "", false, 0, "application/x-empty")
         else
           return []
         end
@@ -345,95 +437,116 @@ module T2Server
     # The size (in bytes) of the port value.
     attr_reader :size
 
+    # The mime-type we use for an error value.
+    ERROR_TYPE = "application/x-error"
+
+    # The mime-type we use for an empty value. Note that an empty value is not
+    # simply an empty string. It is the complete absence of a value.
+    EMPTY_TYPE = "application/x-empty"
+
     # :stopdoc:
-    def initialize(port, ref, error, type = "", size = 0)
+    def initialize(port, ref, error, size, type = "")
       @port = port
       @reference = URI.parse(ref)
-      @type = type
+      @type = (error ? ERROR_TYPE : type)
       @size = size
-      @value = nil
-      @vgot = nil
-      @error = nil
-
-      if error
-        @error = @port.download(@reference)
-        @type = "error"
-      end
+      @error = error
     end
     # :startdoc:
 
     # :call-seq:
-    #   value -> obj
-    #   value(range) -> obj
-    #
-    # Return the value of this port. It is downloaded from the server if it
-    # has not already been retrieved. If a range is specified then just that
-    # portion of the value is downloaded and returned. If no range is specified
-    # then the whole value is downloaded and returned.
-    #
-    # All downloaded data is cached and not downloaded a second time if the
-    # same or similar ranges are requested.
-    def value(range = 0...@size)
-      return nil if error?
-      return "" if @type == "application/x-empty"
-      return @value if range == :debug
-
-      # check that the range provided is sensible
+    #   value -> binary blob
+    #   value(range) -> binary blob
+    #   value {|chunk| ...}
+    #   value(range) {|chunk| ...}
+    #
+    # Get the value of this port from the server.
+    #
+    # If no parameters are supplied then this method will simply download and
+    # return all the data.
+    #
+    # Passing in a block will allow access to the underlying data stream so
+    # the data is not stored in memory:
+    #   run.output_port("port") do |chunk|
+    #     print chunk
+    #   end
+    #
+    # In both cases supplying a Range will download and return the data in
+    # that range.
+    #
+    # This method does not cache any data.
+    #
+    # If this port is an error then this value will be the error message.
+    def value(range = 0...@size, &block)
+      # The following block is a workaround for Taverna Server versions prior
+      # to 2.4.1 and can be removed when support for those versions is no
+      # longer required.
+      if error? && @size == 0
+        value = @port.download(@reference)
+        @size = value.size
+        range = 0...@size if range.min.nil?
+        return value[range]
+      end
+
+      return "" if @type == EMPTY_TYPE
+
+      # Check that the range provided is sensible
       range = 0..range.max if range.min < 0
       range = range.min...@size if range.max >= @size
 
-      need = fill(@vgot, range)
-      case need.length
-      when 0
-        # we already have all the data we need, just return the right bit.
-        # @vgot cannot be nil here and must fully encompass range.
-        ret_range = (range.min - @vgot.min)..(range.max - @vgot.min)
-        @value[ret_range]
-      when 1
-        # we either have some data, at one end of range or either side of it,
-        # or none. @vgot can be nil here.
-        # In both cases we download what we need.
-        new_data = @port.download(@reference, need[0])
-        if @vgot.nil?
-          # this is the only data we have, return it all.
-          @vgot = range
-          @value = new_data
-        else
-          # add the new data to the correct end of the data we have, then
-          # return the range requested.
-          if range.max <= @vgot.max
-            @vgot = range.min..@vgot.max
-            @value = new_data + @value
-            @value[0..range.max]
-          else
-            @vgot = @vgot.min..range.max
-            @value = @value + new_data
-            @value[(range.min - @vgot.min)..@vgot.max]
-          end
-        end
-      when 2
-        # we definitely have some data and it is in the middle of the
-        # range requested. @vgot cannot be nil here.
-        @vgot = range
-        @value = @port.download(@reference, need[0]) + @value +
-          @port.download(@reference, need[1])
+      @port.download(@reference, range, &block)
+    end
+
+    # :call-seq:
+    #   stream_value(stream) -> fixnum
+    #   stream_value(stream, range) -> fixnum
+    #
+    # Stream this port value directly into another stream. The stream passed
+    # in may be anything that provides a +write+ method; instances of IO and
+    # File, for example. No data is cached by this method.
+    #
+    # The number of bytes written to the stream is returned.
+    def stream_value(stream, range = 0...@size)
+      raise ArgumentError,
+        "Stream passed in must provide a write method" unless
+          stream.respond_to? :write
+
+      bytes = 0
+
+      value(range) do |chunk|
+        bytes += stream.write(chunk)
       end
+
+      bytes
     end
 
     # :call-seq:
-    #   error? -> bool
+    #   write_value_to_file(filename) -> fixnum
+    #   write_value_to_file(filename, range) -> fixnum
+    #
+    # Stream this port value directly to a file. If a range is supplied then
+    # just that range of data is downloaded from the server. No data is cached
+    # by this method.
+    def write_value_to_file(filename, range = 0...@size)
+      File.open(filename, "wb") do |file|
+        stream_value(file, range)
+      end
+    end
+
+    # :call-seq:
+    #   error? -> true or false
     #
     # Does this port represent an error?
     def error?
-      !@error.nil?
+      @error
     end
 
     # :call-seq:
-    #   error -> string
+    #   empty? -> true or false
     #
-    # Return the error message for this value, or _nil_ if it is not an error.
-    def error
-      @error
+    # Is this port value empty?
+    def empty?
+      @type == EMPTY_TYPE
     end
 
     # Used within #inspect, below to help override the built in version.
@@ -450,29 +563,5 @@ module T2Server
       }
     end
 
-    private
-    def fill(got, want)
-      return [want] if got.nil?
-
-      if got.member? want.min
-        if got.member? want.max
-          return []
-        else
-          return [(got.max + 1)..want.max]
-        end
-      else
-        if got.member? want.max
-          return [want.min..(got.min - 1)]
-        else
-          if want.max < got.min
-            return [want.min..(got.min - 1)]
-          elsif want.min > got.max
-            return [(got.max + 1)..want.max]
-          else
-            return [want.min..(got.min - 1), (got.max + 1)..want.max]
-          end
-        end
-      end
-    end
   end
 end