voruby 1.1.1 → 2.0.0

data/lib/voruby/adql/support.rb

@@ -0,0 +1,2 @@
+require 'rexml/document'
+require 'voruby/misc'

data/lib/voruby/misc.rb

@@ -0,0 +1,351 @@
+require 'ostruct'
+
+XSI_NAMESPACE = OpenStruct.new(:uri => 'http://www.w3.org/2001/XMLSchema-instance', :prefix => 'xsi')
+
+# A hash mapping module names to XML namespaces.
+NAMESPACES = {
+  'VORuby::STC::V1_10::Coords' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/STC/STCcoords/v1.10', :prefix => 'crd'),
+  'VORuby::STC::V1_10::Region' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/STC/STCregion/v1.10', :prefix => 'reg'),
+  'VORuby::STC::V1_10::STC' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/STC/stc-v1.10.xsd', :prefix => 'stc'),
+  'VORuby::STC::V1_30' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/STC/stc-v1.30.xsd', :prefix => 'stc'),
+  'VORuby::XLink::V1_2' => OpenStruct.new(:uri => 'http://www.w3.org/1999/xlink', :prefix => 'xlink'),
+  'VORuby::ADQL::V1_0' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/ADQL/v1.0', :prefix => 'adq'),
+  'VORuby::VOEvent::V1_1' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/VOEvent/v1.1', :prefix => 'voe'),
+  'VORuby::VOResource::V0_10' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/VOResource/v0.10', :prefix => 'vr'),
+  'VORuby::VORegistry::V0_3' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/VORegistry/v0.3', :prefix => 'vg'),
+  'VORuby::VODataService::V0_5' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/VODataService/v0.5', :prefix => 'vs'),
+  'VORuby::ConeSearch::V0_3' => OpenStruct.new(:uri => 'http://www.ivoa.net/xml/ConeSearch/v0.3', :prefix => 'cs')
+}
+
+# Raises an ArgumentError with the specified root message.
+def raise_argument_required_error(msg)
+  raise ArgumentError, "#{msg} required"
+end
+
+# Raises a TypeError if the given variable isn't of the expected class.
+def raise_type_mismatch_error(var, expected_klass)
+  raise TypeError, "invalid type #{var.class} for #{var.inspect}, expected #{expected_klass}" if !var.is_a?(expected_klass)
+end
+
+# An astract array which will only accept objects of a specified type,
+# and optionally enforce a size range.
+class TypedArray < Array
+  def self.restricted_to; nil end
+  def self.maximum_length; nil end
+  
+  def initialize(args)
+    check_members(args)
+    super(args)
+    check_length
+  end
+  
+  def []=(i, item)
+    check_members(item)
+    super(i, item)
+    check_length
+  end
+  
+  def <<(item)
+    check_members(item)
+    super(item)
+    check_length
+  end
+  
+  def replace(items)
+    check_members(items)
+    super(items)
+    check_length
+  end
+  
+  def insert(index, *items)
+    check_members(items)
+    super(index, *items)
+    check_length
+  end
+  
+  def clear
+    super
+    check_length
+  end
+  
+  def to_s
+    self.collect{ |item| item.to_s }.join(' ')
+  end
+  
+  protected
+  
+  def check_length  
+    if self.class.respond_to?(:maximum_length) and self.class.maximum_length
+      raise "#{self.size} > maximum length of #{self.class.maximum_length}" if self.size > self.class.maximum_length
+    end
+    
+    if self.class.respond_to?(:minimum_length) and self.class.minimum_length
+      raise "#{self.size} < minimum length of #{self.class.minimum_length}" if self.size < self.class.minimum_length
+    end
+  end
+  
+  def check_members(list)
+    list = [list] if !list.is_a?(Array)
+    
+    if self.class.respond_to?(:restricted_to) and self.class.restricted_to
+      list.each do |l|
+        raise TypeError, "invalid type #{l.class} for #{l.inspect}, expected #{self.class.restricted_to}" if !self.class.restricted_to.find{ |klass| l.is_a?(klass) }
+      end
+    end
+  end
+end
+
+# An abstract class that represents a set of possible choices.
+class Enumeration
+  def self.choices; nil end
+  
+  attr_reader :value
+  
+  def initialize(v)
+    self.value = v
+  end
+  
+  def value=(v)
+    if self.class.respond_to?(:choices) and self.class.choices and !self.class.choices.include?(v)
+      raise ArgumentError, "value was #{v}, but #{self.class.to_s.split('::').last} must be one of: #{self.class.choices.join(', ')}"
+    end
+    
+    @value = v
+  end
+  
+  def to_s
+    self.value.to_s
+  end
+  
+  def ==(v)
+    self.value == v.value
+  end
+end
+
+# Various utilities for dealing with Ruby classes and XML mappings.
+# Normally included in an existing module.
+module XMLUtilities
+  def element_from(xml)
+    xml.is_a?(REXML::Element) ? xml : REXML::Document.new(xml).root
+  end
+
+  def element_name_from(klass)
+    klass.respond_to?(:element_name) ? klass.element_name : klass.to_s.split('::').last
+  end
+  
+  def current_module
+    target = self.is_a?(Class) ? self : self.class
+    target.to_s.split('::')[0..-2].inject(Object){ |x, y| x.const_get(y) }
+  end
+
+  def find_classes_of_type(type, mod=nil)
+    mod ||= current_module
+    mod.constants.find_all{ |c|
+      obj = mod.const_get(c)
+      obj.is_a?(Class) and obj.allocate().is_a?(type)
+    }
+  end
+
+  def find_class_with_name(name, mod=nil)
+    mod ||= current_module
+    mod.const_get(
+      mod.constants.find { |c|
+        obj = mod.const_get(c)
+        obj.is_a?(Class) and name == element_name_from(obj)
+      }
+    )
+  end
+
+  def xpath_for(type, mod=nil)
+    mod ||= current_module
+    find_classes_of_type(type, mod).collect { |klass_name|
+      element_name_from(
+        klass_name.split('::').inject(Object){ |x, y| x.const_get(y) }
+      )
+    }
+  end
+  
+  def obj_ns(mod_name=nil)
+    mod_name ||= current_module.to_s
+    NAMESPACES[mod_name]
+  end
+
+  def find_elements(root, path, ns=nil)
+    ns ||= obj_ns
+    root.children.find_all{ |n|
+      n.respond_to?(:name) and path.include?(n.name) and n.namespace == ns.uri
+    }
+  end
+
+  def xml_to_obj(node, klass=nil, first_only=false, mod=nil)
+    raise 'xml node is required' if !node
+    
+    if klass # style 1 (as in STC): element name + substitution groups determines object
+      mod ||= current_module
+      objects = find_elements(node, xpath_for(klass, mod), obj_ns(mod.to_s)).collect{ |n| find_class_with_name(n.name, mod).from_xml(n) }
+      first_only ? objects.first : objects
+    else # style 2 (as in ADQL): xsi:type determines object
+      # find the xsi:type attribute
+      xsi_type_def = node.attributes.get_attribute_ns(XSI_NAMESPACE.uri, 'type')
+      raise "unable to find xsi:type attribute for #{node}" if !xsi_type_def
+
+      # extract its namespace prefix (if none is present, use the default)
+      # and the type name.
+      type_def = xsi_type_def.value.split(':')
+      type_ns_prefix = type_def.size == 2 ? type_def.first : nil
+      type_ns_uri = node.namespace(type_ns_prefix)
+      type_name = type_def.size == 2 ? type_def.last : type_def.first
+
+      # find the module that corresponds to the namespace prefix
+      ns_info = NAMESPACES.find { |key, value| value.uri == type_ns_uri }
+      raise "unable to find module corresponding to #{type_ns_uri}" if !ns_info
+      mod = ns_info.first.to_s.split('::').inject(Object){ |x, y| x.const_get(y) }
+
+      # search through the module for the class who's xml_type is equal
+      # to the type name
+      klass = mod.constants.find { |c|
+        obj = mod.const_get(c)
+        obj.is_a?(Class) and obj.respond_to?(:xml_type) and obj.respond_to?(:from_xml) and obj.xml_type == type_name
+      }.split('::').inject(Object){ |x, y| x.const_get(y) }
+      raise "unable to find class with an xml_type of #{type_name}" if !klass
+
+      # instantiate the class
+      klass.from_xml(node)
+    end
+  end
+
+  def collapse_namespaces(el, existing_namespaces=nil)
+     return if !el or !el.has_elements?
+
+     existing_namespaces ||= el.namespaces
+
+     el.children.each do |child|
+       child.namespaces.each do |prefix, uri|
+         child.delete_namespace(prefix) if existing_namespaces.has_key?(prefix)
+       end
+
+       collapse_namespaces(child, existing_namespaces.merge(child.namespaces))
+     end
+   end
+end
+
+# A mix-in that adds to a classes the ability to serialize
+# themselves to very basic XML.
+module SerializableToXml
+  def element(name=nil, ns=nil, options={})
+    name ||= element_name_from(self.class)
+    ns ||= obj_ns
+  
+    el = REXML::Element.new("#{ns.prefix}:#{name}")
+    el.add_namespace(ns.prefix, ns.uri)
+    
+    el.add_namespace(XSI_NAMESPACE.prefix, XSI_NAMESPACE.uri) if options[:include_xsi]
+    el.attributes["#{XSI_NAMESPACE.prefix}:type"] = "#{options[:prefix] || ns.prefix}:#{options[:type]}" if options[:type]
+    
+    el
+  end
+end
+
+# Basic IDREF
+class IdRef
+  include SerializableToXml
+
+  attr_reader :value
+
+  def initialize(ref)
+    self.value = ref
+  end
+
+  def value=(ref)
+    raise ArgumentError, "reference can't be blank" if !ref or ref.to_s.strip == ''
+    @value = ref.to_s
+  end
+
+  def to_s
+    self.value.to_s
+  end
+
+  def ==(id)
+    self.value == id.value
+  end
+
+  def to_xml(name=nil)
+    el = element(name)
+    el.text = self.value.to_s
+    el
+  end
+
+  def self.from_xml(xml)
+    self.new(element_from(xml).text)
+  end
+end
+
+# Basic ID
+class Id
+  attr_reader :value
+  
+  include SerializableToXml
+  
+  def initialize(ref)
+    self.value = ref
+  end
+
+  def value=(i)
+    raise ArgumentError, "ID can't be blank" if !i or i.to_s.strip == ''
+    @value = i.to_s
+  end
+
+  def to_s
+    self.value.to_s
+  end
+
+  def ==(id)
+    self.value == id.value
+  end
+
+  def to_xml(name=nil)
+    el = element(name)
+    el.text = self.value.to_s
+    el
+  end
+
+  def self.from_xml(xml)
+    self.new(element_from(xml).text)
+  end
+end
+
+# Regex-restricted string
+class RegexRestrictedString
+  attr_reader :value
+  
+  include SerializableToXml
+  
+  def initialize(s)
+    self.value = s
+  end
+  
+  def regex; /.*/ end
+  
+  def value=(s)
+    raise_argument_required_error('value') if !s
+    raise "#{s} does not match /#{self.regex.source}/" if !s.match(self.regex)
+    @value = s
+  end
+  
+  def ==(s)
+    self.value == s.value
+  end
+  
+  def to_s; self.value.to_s end
+  
+  def to_xml(name=nil, ns=nil)
+    el = element(name, ns)
+    el.text = self.value
+    el
+  end
+    
+  def self.from_xml(xml)
+    root = element_from(xml)
+    self.new(root.text)
+  end
+end

data/lib/voruby/misc/connection_monitor.rb

@@ -0,0 +1,97 @@
+module VORuby
+  module Misc
+    
+    # Monitors (by way of "pinging") a URL.
+    #  monitor = ConnectionMonitor.new('http://www.noao.edu/')
+    #  monitor.on_success = Proc.new{ |pinger, monitor|
+    #    puts "#{monitor.url} is awake!"
+    #  }
+    #  monitor.on_failure = Proc.new{ |pinger, monitor|
+    #    puts "Connection to #{monitor.url} failed: #{pinger.exception}"
+    #  }
+    #
+    #  monitor.start
+    #    => http://www.noao.edu/ is awake!           # Wait 10 minutes...
+    #    => http://www.noao.edu/ is awake!           # Wait 10 minutes...
+    #    => Connection to http://www.noao.edu/ failed: some error message  # Uh oh! Something happened...
+    class ConnectionMonitor
+      require 'loader'
+      require 'net/ping'
+      
+      # The Net::PingHTTP object doing the actual pinging.
+      attr_reader :pinger
+      # The URL being pinged.
+      attr_reader :url
+      # The amount of time to wait (in seconds) before timing out a connection.
+      attr_reader :timeout
+      
+      # The frequency (in seconds) at which to poll.
+      attr_accessor :polling_freq
+      # A Proc triggered when a ping fails.  Takes the Net::PingHTTP object and the monitor itself.
+      attr_accessor :on_failure
+      # A Proc triggered when a ping succeeds.  Takes the Net::PingHTTP object and the monitor itself.
+      attr_accessor :on_success
+      # A Proc triggered when the monitor is interrupted (i.e via Ctrl-C)
+      attr_accessor :on_interrupt
+  
+      # Place a monitor on the specified URL.
+      # By default the URL will be "pinged" every 600 seconds
+      # and will timeout if it doesn't receive a response
+      # within 5 seconds.
+      def initialize(url, polling_freq=600, timeout=5)
+        @pinger = Net::Ping::HTTP.new(url)
+    
+        self.polling_freq = polling_freq
+        self.url = url
+        self.timeout = timeout
+    
+        @interrupted = false
+    
+        self.on_failure = Proc.new{ |pinger, monitor|
+          puts "Connection to #{monitor.url} failed: #{pinger.exception}."
+        }
+        self.on_success = Proc.new{ |pinger, monitor| }
+        self.on_interrupt = Proc.new{ @interrupted = true }
+    
+        trap("INT"){ self.on_interrupt.call }
+      end
+  
+      # Set the URL to monitor.
+      def url=(url)
+        @url = url
+        @pinger.host = url
+        @pinger.port = URI.parse(url).port
+      end
+  
+      # Set the timeout for the monitor.
+      def timeout=(s)
+        @timeout = s
+        @pinger.timeout = s
+      end
+  
+      # Start monitoring, but do so in a thread.
+      def start_threaded
+        @t = Thread.new { start }
+        @t.run
+      end
+  
+      # Start monitoring.
+      def start
+        while true
+          return if @interrupted
+    
+          pinger.ping ? on_success.call(pinger, self): on_failure.call(pinger, self)
+          sleep(polling_freq)
+        end
+      end
+      
+      # Stop monitoring.
+      def stop
+        self.on_interrupt.call
+      end
+
+    end
+    
+  end
+end
+