oml4r 2.9.5 → 2.9.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d3d1eb545b9421f2879295e80e877f4f062c23d9
+  data.tar.gz: efdf663660b0bb02826371fe2a452b7a85575d99
+SHA512:
+  metadata.gz: 3df9d5505c1d71b4f0f789a1159dbe8b42a736a393edc13f2e7d94e69c382d8e5d365822f0c4ba8cb07164b6e6dbe36989ef132ea61b599621b5cfef1025aa32
+  data.tar.gz: 22de82d382d2fc8559629a8fd015bc65684d76ae1937f6937a092a2d0ff1b872df744594d00df124a156876648fad9d6674d243d63fef3a435591f640277cbd6

data/README.md

@@ -1,8 +1,8 @@
-OML4R: Native OML Implementation in Ruby			{#oml4rdoc}
+OML4R: Native OML Implementation in Ruby
 ========================================
 
 This is a simple client library for OML which does not use liboml2 and its
-filters, but connects directly to the server using the text protocol [oml-text].
+filters, but connects directly to the server using the text protocol [omsp].
 User can use this library to create ruby applications which can send
 measurement to the OML collection server. A simple example on how to use
 this library is attached at the end of this file. Another example can be
@@ -31,9 +31,9 @@ Usage
 
 ### Initialisation, Injection and Tear-down
 
-    OML4R::init(ARGV, 
+    OML4R::init(ARGV,
     	:appName => 'oml4rSimpleExample',
-    	:domain => 'foo', 
+    	:domain => 'foo',
     	:nodeID => 'n1',
     )
     MyMP.inject("hello", 13, 37.1)
@@ -59,11 +59,11 @@ this with the 'channel' abstraction.
       param :b_val, :type => :int32
     end
     
-    OML4R::init(ARGV, 
+    OML4R::init(ARGV,
       :appName => 'doubleAgent',
-      :domain => 'foo' 
+      :domain => 'foo'
     )
-    OML4R::create_channel(:archive, 'file:/tmp/archive.log')    
+    OML4R::create_channel(:archive, 'file:/tmp/archive.log')
 
 Setting the command line flag '--oml-collect' will define a ':default' channel. Any additional channels
 need to be declared with 'OML4R::create_channel' which takes two arguments, the name of the channel
@@ -76,7 +76,7 @@ Please note that by declaring a specific channel, every MP needs at least one ch
 
 See examples files oml4r-simple-example.rb and oml4r-wlanconfig.rb.
 
-[oml-text]: http://oml.mytestbed.net/projects/oml/wiki/Description_of_Text_protocol
+[omsp]: http://oml.mytestbed.net/projects/oml/wiki/OML_Measurement_Stream_Protocol_(OMSP)_Specification
 [oml4r-rubygem]: https://rubygems.org/gems/oml4r/
 
 License

data/lib/oml4r.rb

@@ -13,6 +13,8 @@
 # User can use this library to create ruby applications which can send
 # measurement to the OML collection server.
 #
+
+require 'set'
 require 'socket'
 require 'monitor'
 require 'thread'
@@ -20,6 +22,7 @@ require 'optparse'
 
 require 'oml4r/version'
 
+
 #
 # This is the OML4R module, which should be required by ruby applications
 # that want to collect measurements via OML
@@ -27,7 +30,7 @@ require 'oml4r/version'
 module OML4R
 
   DEF_SERVER_PORT = 3003
-  DEF_PROTOCOL = 3
+  DEF_PROTOCOL = 4
 
   # Overwrite the default logger
   #
@@ -51,9 +54,11 @@ module OML4R
     # Some Class variables
     @@defs = {}
     @@channels = {}
+    @@channelNames = {}
     @@frozen = false
     @@useOML = false
     @@start_time = nil
+    @@newDefs = Set[]
 
     # Execute a block for each defined MP
     def self.each_mp(&block)
@@ -71,6 +76,7 @@ module OML4R
         defs = @@defs[self] = {}
         defs[:p_def] = []
         defs[:seq_no] = 0
+        defs[:meta_no] = 0
       end
       defs
     end
@@ -81,10 +87,18 @@ module OML4R
     # opts add_prefix Add app name as prefix to table. Default: true
     #
     def self.name(name, opts = {})
+
+      # ok, lets add it then
       if opts[:add_prefix].nil?
         opts[:add_prefix] = true
       end
       __def__()[:name] = {:name => name, :opts => opts}
+
+      # if we're frozen remember to inject schema before measurements
+      if @@frozen
+        @@newDefs.add self
+      end
+
     end
 
     # Set the channel these measurements should be sent out on.
@@ -92,23 +106,20 @@ module OML4R
     # the channel defined by the command line arguments or environment variables.
     #
     def self.channel(channel, domain = :default)
-      (@@channels[self] ||= []) << [channel, domain]
+      (@@channelNames[self] ||= []) << [channel, domain]
     end
 
     # Set a metric for this MP
     # - name = name of the metric to set
     # - opts = a Hash with the options for this metric
-    #          Only supported option is :type = { :string | :int32 | :double }
+    #          Only supported option is :type = { :string | :int32 | :double | :bool }
     def self.param(name, opts = {})
       o = opts.dup
       o[:name] = name
       o[:type] ||= :string
-      case o[:type]
-      when :long
+      if :long == o[:type]
         OML4R.logger.warn ":long is deprecated use, :int32 instead"
         o[:type] = :int32
-      when :boolean
-        o[:type] = :int32  # TODO: Hopefully we can remove this soon
       end
       __def__()[:p_def] << o
       nil
@@ -119,8 +130,41 @@ module OML4R
     # - args = a list of arguments (comma separated) which correspond to the
     #          different values of the metrics for the measurement to inject
     def self.inject(*args)
+
       return unless @@useOML
 
+      # Do we need to send a schema update?
+      if @@newDefs.include? self
+        defs = @@defs[self]
+        mp_name_def = defs[:name]
+        mp_name = mp_name_def[:name]
+        pdefs = defs[:p_def]
+        defs[:types] = pdefs.map {|h| h[:type]}
+        # prepare the message header
+        a = []
+        a << Time.now - @@start_time
+        a << "0"
+        a << (defs[:meta_no] += 1)
+        a << "."
+        a << "schema"
+        msg = a.join("\t")
+        # Create the channels
+        names = @@channelNames[self] || []
+        chans = names.collect do |cname, domain|
+          [Channel[cname.to_sym, domain.to_sym]]
+        end
+        @@channels[self] = chans.empty? ? [[Channel[]]] : chans
+        # Now inject the schema
+        meta_ca = @@channels[OML4R::ExperimentMetadata][0]
+        channel = meta_ca[0]
+        schema_info = channel.build_schema(mp_name, mp_name_def[:opts][:add_prefix], pdefs)
+        channel.send_schema_update(msg + "\t" + schema_info[1])
+        @@channels[self].each do |ca|
+          ca << schema_info[0]
+        end
+        @@newDefs.delete self
+      end
+
       # Check that the list of values passed as argument matches the
       # definition of this Measurement Point
       defs = __def__()
@@ -138,10 +182,10 @@ module OML4R
         case types[i]
         when :string
           # Escape tabs and newlines
-          arg = arg.to_s.gsub("\n", "\\n").gsub("\t", "\\t")
-        when :boolean
-          # boolean
-          arg = arg ? 1 : 0
+          arg = arg.to_s.gsub("\\", "\\\\").gsub("\r", "\\r").gsub("\n", "\\n").gsub("\t", "\\t")
+        when :bool
+          # Convert boolean value to appropriate literal
+          arg = arg ? "True" : "False"
         when :blob
           arg = [arg].pack("m")
         end
@@ -157,6 +201,13 @@ module OML4R
       args
     end
 
+    # Inject measurement metadata from this Measurement Point to the
+    # OML Server.
+    # 
+    # def self.inject_metadata(key, value, fname)
+    #    MPBase::__inject_metadata__(@name, key, value, fname)
+    # end
+
     def self.start_time()
       @@start_time
     end
@@ -173,14 +224,14 @@ module OML4R
 
       # replace channel names with channel object
       self.each_mp do |klass, defs|
-        cna = @@channels[klass] || []
-        OML4R.logger.debug "'#{cna.inspect}', '#{klass}'"
-        ca = cna.collect do |cname, domain|
+        names = @@channelNames[klass] || []
+        OML4R.logger.debug "'#{names.inspect}', '#{klass}'"
+        chans = names.collect do |cname, domain|
           # return it in an array as we need to add the channel specific index
           [Channel[cname.to_sym, domain.to_sym]]
         end
-        OML4R.logger.debug "Using channels '#{ca.inspect}"
-        @@channels[klass] = ca.empty? ? [[Channel[]]] : ca
+        OML4R.logger.debug "Using channels '#{chans.inspect}"
+        @@channels[klass] = chans.empty? ? [[Channel[]]] : chans
       end
       @@start_time = start_time
     end
@@ -204,21 +255,17 @@ module OML4R
       unless (mp_name_def = defs[:name])
         raise MissingArgumentException.new "Missing 'name' declaration for '#{self}'"
       end
-      mp_name = mp_name_def[:name]
-      if !name_prefix.nil? && mp_name_def[:opts][:add_prefix]
-        mp_name = "#{name_prefix}_#{mp_name}"
-      end
 
+      # Build the schema
+      mp_name = mp_name_def[:name]
       @@channels[self].each do |ca|
         OML4R.logger.debug "Setting up channel '#{ca.inspect}"
-        index = ca[0].send_schema(mp_name, defs[:p_def])
-        ca << index
+        schema_info = ca[0].build_schema(mp_name, mp_name_def[:opts][:add_prefix], defs[:p_def])
+        ca << schema_info[0]
       end
     end
   end # class MPBase
 
-
-
   #
   # The Init method of OML4R
   # Ruby applications should call this method to initialise the OML4R module
@@ -238,8 +285,7 @@ module OML4R
   # param block = a block which defines the additional application-specific arguments
   #
   def self.init(argv, opts = {}, &block)
-    OML4R#{VERSION_STRING} [#{COPYRIGHT}")
-
+    OML4R.logger.info "V#{VERSION} #{COPYRIGHT}"
     if d = (ENV['OML_EXP_ID'] || opts[:expID])
       # NOTE: It is still too early to complain about that. We need to be sure
       # of the nomenclature before making user-visible changes.
@@ -270,6 +316,7 @@ module OML4R
     end
     opts[:collect] = ENV['OML_COLLECT'] || ENV['OML_SERVER'] || opts[:collect] || opts[:omlServer]
     noop = opts[:noop] || false
+    omlConfigFile = nil
 
     if argv
       # Create a new Parser for the command line
@@ -283,6 +330,7 @@ module OML4R
       op.on("--oml-protocol p", "Protocol number [#{OML4R::DEF_PROTOCOL}]") { |l| opts[:protocol] = l.to_i }
       op.on("--oml-log-level l", "Log level used (info: 1 .. debug: 0)") { |l| OML4R.logger.level = l.to_i }
       op.on("--oml-noop", "Do not collect measurements") { noop = true }
+      op.on("--oml-config file", "File holding OML configuration parameters") { |f| omlConfigFile = f }
       op.on("--oml-exp-id domain", "Obsolescent equivalent to --oml-domain domain") { |name|
         domain = name
         OML4R.logger.warn "Option --oml-exp-id is getting deprecated; please use '--oml-domain #{domain}' instead"
@@ -306,10 +354,25 @@ module OML4R
         # give the app a chance to fix missing parameters
         opts[:afterParse].call(opts)
       end
-      return if noop
-    end
-
-    unless opts[:nodeID]
+     return if noop
+     # Parameters in OML config file takes precedence
+     unless omlConfigFile.nil? 
+       f = File.open(omlConfigFile, 'r')
+       f.each_line do |l|
+         d = l[/.*experiment=["']([^["']]*)/,1]
+         opts[:domain] = d if d
+         d = l[/.*domain=["']([^["']]*)/,1]
+         opts[:domain] = d if d
+         i = l[/.*id=["']([^["']]*)/,1]
+         opts[:nodeID] = i if i
+         u = l[/.*url=["']([^["']]*)/,1]
+         opts[:omlCollectUri] = u if u
+       end
+       f.close
+     end
+    end
+ 
+   unless opts[:nodeID]
       begin
         # Create a default nodeID by concatinating the local hostname with the process ID
         hostname = nil
@@ -334,16 +397,12 @@ module OML4R
       raise MissingArgumentException.new 'OML4R: Missing values for parameters :domain (--oml-domain), :nodeID (--oml-id), or :appName (in code)!'
     end
 
-    unless opts[:create_default_channel] == false
-      # Set a default collection URI if nothing has been specified
-      unless opts[:omlCollectUri]
-        require 'time'
-        opts[:omlCollectUri] = "file:#{opts[:appName]}_#{Time.now.iso8601}"
-        #opts[:omlCollectUri] = "file:-"
-        OML4R.logger.info "Collection URI is #{opts[:omlCollectUri]}"
-      end
-      create_channel(:default, opts[:omlCollectUri])
-    end
+    # Set a default collection URI if nothing has been specified
+    opts[:omlCollectUri] ||= "file:#{opts[:appName]}_#{opts[:nodeID]}_#{opts[:domain]}_#{Time.now.strftime("%Y-%m-%dt%H.%M.%S%z")}"
+    opts[:omlCollectUri] = qualify_uri(opts[:omlCollectUri])
+    OML4R.logger.info "Collection URI is #{opts[:omlCollectUri]}"
+
+    create_channel(:default, opts[:omlCollectUri]) if opts[:omlCollectUri]
 
     # Handle the defined Measurement Points
     startTime = Time.now
@@ -351,6 +410,54 @@ module OML4R
     rest || []
   end
 
+  # Parse an underspecified URI into a fully-qualified one
+  # URIs are resolved as follows; the default is [tcp:]host[:port].
+  #  hostname		-> tcp:hostname:3003
+  #  hostname:3004	-> tcp:hostname:3004
+  #  tcp:hostname	-> tcp:hostname:3003
+  #  tcp:hostname:3004	-> tcp:hostname:3004
+  #  file:/P/A/T/H	-> file:/P/A/T/H
+  #
+  # @param uri [String] a potentially under-qualified collection URI
+  #
+  # @return [String] afully-qualified collection URI equivalent to uri
+  #
+  # @raise [OML4RException] in case of a parsing error
+  #
+  def self.qualify_uri(uri)
+    curi = uri.split(':')
+
+    # Defaults
+    scheme = 'tcp'
+    port = DEF_SERVER_PORT
+
+    if curi.length == 1
+      host = curi[0]
+
+    elsif curi.length == 2
+      if curi[0] == 'tcp'
+        scheme, host = curi
+
+      elsif  curi[0] == 'file'
+        scheme, host = curi
+        port = nil
+
+      else
+        host, port = curi
+      end
+
+    elsif curi.length >= 3
+      if curi.length > 3
+        OML4R.logger.warn "Parsing URI '#{uri}' as a triplet, ignoring later components"
+      end
+      scheme, host, port = curi
+
+    else
+      raise OML4RException.new "OML4R: Unable to parse URI '#{url}"
+    end
+    "#{scheme}:#{host}#{":#{port}" if port}"
+  end
+  
   def self.create_channel(name, url)
     Channel.create(name, url)
   end
@@ -363,19 +470,13 @@ module OML4R
   end
 
 
-
   #
-  # Measurement Point Class
-  # Ruby applications using this module should sub-class this MPBase class
-  # to define their own Measurement Point (see the example at the end of
-  # this file)
+  # Measurement Channel
   #
   class Channel
     @@channels = {}
     @@default_domain = nil
 
-
-
     def self.create(name, url, domain = :default)
       key = "#{name}:#{domain}"
       if channel = @@channels[key]
@@ -384,8 +485,36 @@ module OML4R
         end
         return channel
       end
-      #return self._create(key, domain, url)
-      return @@channels[key] = self.new(url, domain)
+      return self._create(key, domain, url)
+    end
+
+    def self._create(key, domain, url)
+      @@channels[key] = self.new(url, domain)
+    end
+
+    # Parse the given fully-qualified collection URI, and return a suitably connected objet
+    #
+    # Supported URIs are
+    #  tcp:host:port
+    #  file:/P/A/T/H
+    #
+    # @param fquri [String] a fully qualified collection URI
+    # @return [IO] an object suitably connected to the required URL
+    #
+    # @raise [OML4RException] in case of an unknown scheme
+    #
+    def self._connect(fquri)
+      scheme, host, port = fquri.split(':')
+      out = case scheme
+            when 'tcp'
+              out = TCPSocket.new(host, port)
+            when 'file'
+              # host is really a filename here
+              out = (host == '-' ? $stdout : File.open(host, "w+"))
+            else
+              raise OML4RException.new "OML4R: Unknown scheme '#{scheme}"
+            end
+      out
     end
 
     def self.[](name = :default, domain = :default)
@@ -438,22 +567,25 @@ module OML4R
       @url = url
     end
 
-    def send_schema(mp_name, pdefs) # defs[:p_def]
-      # Build the schema and send it
+    def build_schema(mp_name, add_prefix, pdefs)
       @index += 1
-      #line = ['schema:', @index, mp_name]
-      line = [@index, mp_name]
+      line = [@index, (!@@appName.nil? && add_prefix)? "#{@@appName}_#{mp_name}" : mp_name]
       pdefs.each do |d|
         line << "#{d[:name]}:#{d[:type]}"
       end
       msg = line.join(' ')
       @schemas << msg
-      @index
+      [@index, msg]
     end
 
     def send(msg)
       @queue.push msg
     end
+ 
+    def send_schema_update(msg)
+      @header_sent = true
+      @queue.push msg
+    end
 
     def init(nodeID, appName, startTime, protocol)
       @nodeID, @appName, @startTime, @protocol = nodeID, appName, startTime, protocol
@@ -469,7 +601,7 @@ module OML4R
     def initialize(url, domain)
       @domain = domain
       @url = url
-      @index = 0
+      @index = -1
       @schemas = []
       @header_sent = false
       @queue = Queue.new
@@ -499,26 +631,15 @@ module OML4R
       d = (@domain == :default) ? @@default_domain : @domain
       raise MissingArgumentException.new "Missing domain name" unless d
       case @protocol || OML4R::DEF_PROTOCOL
-      when 3
-        header << "experiment-id: #{d}"
-        header << "start_time: #{@startTime.tv_sec}"
+      when 4
+        header << "domain: #{d}"
+        header << "start-time: #{@startTime.tv_sec}"
         header << "sender-id: #{@nodeID}"
         header << "app-name: #{@appName}"
         @schemas.each do |s|
           header << "schema: #{s}"
         end
         header << ""
-      when 4
-        i = 0
-        header << ""
-        header << "0\t0\t#{i += 1}\t.\texperiment-id\t#{d}"
-        header << "0\t0\t#{i += 1}\t.\tstart_time\t#{@startTime.tv_sec}"
-        header << "0\t0\t#{i += 1}\t.\tsender-id\t#{@nodeID}"
-        header << "0\t0\t#{i += 1}\t.\tapp-name\t#{@appName}"
-        @schemas.each do |s|
-          header << "0\t0\t#{i += 1}\t.\tschema\t#{s}"
-        end
-
       else
         raise OML4RException.new "Unsupported protocol #{@protocol}"
       end
@@ -526,7 +647,6 @@ module OML4R
     end
 
     def start_runner
-      header_sent = false
       @runner = Thread.new do
         active = true
         begin
@@ -586,6 +706,16 @@ module OML4R
 
   end # Channel
 
+
+  # Hard-code "schema0" measurement point
+  class ExperimentMetadata < MPBase
+    name :_experiment_metadata, :add_prefix => false
+    param :subject, :type => :string
+    param :key, :type => :string
+    param :value, :type => :string    
+  end
+
+
   require 'logger'
 
   class Logger < ::Logger
@@ -601,7 +731,6 @@ module OML4R
     @@logger
   end
 
-
 end # module OML4R
 
 # vim: sw=2

data/lib/oml4r/version.rb

@@ -5,7 +5,7 @@
 # ------------------
 
 module OML4R
-  VERSION = "2.9.5"
+  VERSION = "2.9.6"
   VERSION_STRING = "OML4R Client V#{VERSION}"
   COPYRIGHT = "Copyright 2009-2013, NICTA"
 end

metadata

@@ -1,33 +1,22 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: oml4r
-version: !ruby/object:Gem::Version 
-  hash: 33
-  prerelease: 
-  segments: 
-  - 2
-  - 9
-  - 5
-  version: 2.9.5
+version: !ruby/object:Gem::Version
+  version: 2.9.6
 platform: ruby
-authors: 
+authors:
 - NICTA
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2013-09-02 00:00:00 Z
+date: 2013-10-09 00:00:00.000000000 Z
 dependencies: []
-
-description: Simple OML client library for Ruby
-email: 
+description: '["Simple OML client library for Ruby"]'
+email:
 - oml-user@lists.nicta.com.au
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - LICENSE.txt
@@ -47,38 +36,31 @@ files:
 - lib/oml4r/version.rb
 - oml4r.gemspec
 homepage: http://oml.mytestbed.net
-licenses: 
+licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
-summary: This is a simple client library for OML which does not use liboml2 and its filters, but connects directly to the server using the +text+ protocol.  User can use this library to create ruby applications which can send measurement to the OML collection server.
+specification_version: 4
+summary: '["This is a simple client library for OML which does not use liboml2 and
+  its filters, but connects directly to the server using the +text+ protocol.  User
+  can use this library to create ruby applications which can send measurement to the
+  OML collection server."]'
 test_files: []
-
 has_rdoc: