motel 0.2 → 0.3

data/README.rdoc

@@ -0,0 +1,35 @@
+== Motel - Movable Object Tracking Encopassing Locations
+
+Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+
+Motel is made available under the GNU AFFERO GENERAL PUBLIC LICENSE
+as published by the Free Software Foundation, either version 3
+of the License, or (at your option) any later version.
+
+=== Intro
+Motel is a simple framework for tracking 3d location written in Ruby.
+A simple server is provider which handles requests which the provided client
+can issue, altering heirarchies of locations and updating their coordinates
+and movement strategies.
+
+Each location is associated with a movement stategy which is used to move the location
+(eg update its coordinates) in accordance to a set of rules / variables specific to each
+strategy.
+
+Multiple clients can connect to a motel server simutaneously and query for locations and
+subscribe handlers to be invoked on updates.
+
+To install motel simply run:
+   gem install motel
+
+Source code is available via:
+   git clone http://github.com/movitto/motel
+
+=== Using
+Generate documentation via
+  rake rdoc
+
+Also see specs for detailed usage.
+
+=== Authors
+ Mohammed Morsi <movitto@yahoo.com>

data/Rakefile

@@ -0,0 +1,48 @@
+# motel project Rakefile
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+require 'rake/gempackagetask'
+
+
+GEM_NAME="motel"
+PKG_VERSION='0.3'
+SIMRPC_SPEC='conf/motel-schema.xml'
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Rake::RDocTask.new do |rd|
+    rd.main = "README.rdoc"
+    rd.rdoc_dir = "doc/site/api"
+    rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+end
+
+PKG_FILES = FileList['bin/**/*', 'conf/motel-schema.xml', 'lib/**/*.rb', 
+  'COPYING', 'LICENSE', 'Rakefile', 'README.rdoc', 'spec/**/*.rb' ]
+
+SPEC = Gem::Specification.new do |s|
+    s.name = GEM_NAME
+    s.version = PKG_VERSION
+    s.files = PKG_FILES
+
+    s.required_ruby_version = '>= 1.8.1'
+    s.required_rubygems_version = Gem::Requirement.new(">= 1.3.3")
+
+    s.author = "Mohammed Morsi"
+    s.email = "movitto@yahoo.com"
+    s.date = %q{2010-03-14}
+    s.description = %q{Motel is a library to track and move the locations of objects in a 3D environment.}
+    s.summary = %q{Motel is a library to track and move the locations of objects in a 3D environment.}
+    s.homepage = %q{http://morsi.org/projects/motel}
+end
+
+Rake::GemPackageTask.new(SPEC) do |pkg|
+    pkg.need_tar = true
+    pkg.need_zip = true
+end

data/bin/clients/simple/main.rb

@@ -0,0 +1,131 @@
+#!/usr/bin/ruby
+# A simple motel client executable
+# Executable to use the motel library to perform operations on
+# a remote location server, simply printing out results
+#
+# Flags: (see below)
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+CURRENT_DIR=File.dirname(__FILE__)
+$: << File.expand_path(CURRENT_DIR + "/../../../lib")
+
+require 'rubygems'
+require 'optparse'
+require 'motel'
+
+include Motel
+include Motel::MovementStrategies
+
+######################
+
+# TODO movement strategy support
+
+def main()
+    # command line parameters
+    schema_file = nil
+    location = {:parent_id => nil,
+                :x => nil,
+                :y => nil,
+                :z => nil}
+    request_target = nil
+
+    # setup cmd line options
+    opts = OptionParser.new do |opts|
+      opts.banner = "Usage: main.rb [command] [options]"
+
+      opts.on("-h", "--help", "Print this help message") do
+         puts opts
+         exit
+      end
+
+      opts.on("-s", "--schema [path]", "Motel Schema File") do |path|
+         schema_file = path
+      end
+
+      opts.separator ""
+      opts.separator "Commands:"
+      opts.on("-g", "--get", "get location specified by id")do
+        request_target = :get_location
+      end
+      opts.on("-c", "--create", "create location w/ id")do
+        request_target = :create_location
+      end
+      opts.on("-u", "--update", "update location specified by id w/ specified options")do
+        request_target = :update_location
+      end
+      opts.on("-b", "--subscribe", "subscribe to updates to location specified by id")do
+        request_target = :subscribe_to_location
+      end
+
+      opts.separator ""
+      opts.separator "Options:"
+      opts.on("-i", "--id [location_id]", "Target location id") do |id|
+        location[:id] = id
+      end
+      opts.on("-p", "--parent-id [location_id]", "Target parent location id") do |id|
+        location[:parent_id] = id
+      end
+      opts.on("-x", "--xcoordinate [coordinate]", "Target location x coordinate") do |x|
+        location[:x] = x
+      end
+      opts.on("-y", "--ycoordinate [coordinate]", "Target location y coordinate") do |y|
+        location[:y] = y
+      end
+      opts.on("-z", "--zcoordinate [coordinate]", "Target location z coordinate") do |z|
+        location[:z] = z
+      end
+
+    end
+
+    # parse cmd line
+    begin
+      opts.parse!(ARGV)
+    rescue OptionParser::InvalidOption => e
+      puts opts
+      puts e.to_s
+      exit
+    end
+
+    if request_target.nil? || location[:id].nil? || schema_file.nil? ||
+       request_target == :update && location[:x].nil? && location[:y].nil? && location[:z].nil? && location[:parent_id].nil?
+         puts opts
+         puts "must specify schema, a command to perform, a location id, and other required options"
+         exit
+    end
+
+    lid = location[:id]
+    location = Motel::Location.new :id => location[:id],
+                                   :parent_id => location[:parent_id],
+                                   :x => location[:x],
+                                   :y => location[:y],
+                                   :z => location[:z]
+    args = []
+    case(request_target)
+    when :get_location
+      args.push location.id
+    when :create_location
+      args.push location.id
+    when :update_location
+      args.push location
+    when :subscribe_to_location
+      args.push location.id
+    end
+
+    # FIXME need configurable amqp broker ip/port
+    client = Motel::Client.new :schema_file => schema_file
+    result = client.request request_target, *args
+
+    if request_target == :subscribe_to_location
+      client.on_location_received = lambda { |loc|
+         puts "location received:"
+         puts "#{loc}"
+      }
+      client.join
+    end
+
+    puts "server returned #{result}"
+end
+
+main()

data/bin/server/main.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/ruby
+# A motel server executable
+# Executable to use the motel library to track locations in
+# real time and provide network access to read/write location data.
+#
+# Flags:
+#  -h --help
+#  -s --simrpc-schema
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+CURRENT_DIR=File.dirname(__FILE__)
+$: << File.expand_path(CURRENT_DIR + "/../../lib")
+
+require 'rubygems'
+require 'optparse'
+require 'motel'
+
+include Motel
+include Motel::MovementStrategies
+
+######################
+
+
+def main()
+  schema_file = nil
+
+  # setup cmd line options
+  opts = OptionParser.new do |opts|
+    opts.on("-h", "--help", "Print help message") do
+       puts opts
+       exit
+    end
+    opts.on("-s", "--simrpc-schema [path]", "Motel Simrpc Schema File") do |path|
+       schema_file = path
+    end
+  end
+
+  # parse cmd line
+  begin
+    opts.parse!(ARGV)
+  rescue OptionParser::InvalidOption
+    puts opts
+    exit
+  end
+
+  if schema_file.nil? || ! File.exists?(schema_file)
+     puts "motel simrpc schema file required"
+     exit
+  end
+
+  # start location runner
+  Motel::Runner.instance.start :async => true
+
+  # start listening for requests / block
+  # FIXME need configurable amqp broker ip/port
+  server = Motel::Server.new(:schema_file => schema_file).join
+end
+
+main()

data/conf/motel-schema.xml

@@ -0,0 +1,72 @@
+<!-- The motel simrpc schema definition -->
+<schema>
+
+  <class name="MovementStrategy" desc="paramaterized algorithm through which a location is moved">
+    <member name="id" type="int" desc="MovementStrategy identifier" ignore_null="true" />
+    <member name="type" type="str" desc="MovementStrategy type"/>
+    <member name="step_delay" type="float" desc="MovementStrategy movement delay"/>
+  </class>
+
+  <class name="Stopped" desc="stopped movement strategy" inherits="MovementStrategy">
+  </class>
+
+  <class name="Linear" desc="linear movement strategy" inherits="MovementStrategy">
+    <member name="speed" type="float" desc="Speed which location is moving" />
+    <member name="direction_vector_x" type="float" desc="x component of Linear direction vector" />
+    <member name="direction_vector_y" type="float" desc="y component of Linear direction vector" />
+    <member name="direction_vector_z" type="float" desc="z component of Linear direction vector" />
+  </class>
+
+  <class name="Elliptical" desc="elliptical movement strategy" inherits="MovementStrategy">
+    <member name="speed" type="float" desc="Speed which location is moving" />
+    <member name="relative_to" type="float" desc="how location is relative to its parent" />
+    <member name="eccentricity" type="float" desc="eccentricity of elliptical orbit" />
+    <member name="semi_latus_rectum" type="float" desc="semi latus rectum of elliptical orbit" />
+    <member name="direction_major_x" type="float" desc="x component of Elliptical Major direction vector" />
+    <member name="direction_major_y" type="float" desc="y component of Elliptical Major direction vector" />
+    <member name="direction_major_z" type="float" desc="z component of Elliptical Major direction vector" />
+    <member name="direction_minor_x" type="float" desc="x component of Elliptical Minor direction vector" />
+    <member name="direction_minor_y" type="float" desc="y component of Elliptical Minor direction vector" />
+    <member name="direction_minor_z" type="float" desc="z component of Elliptical Minor direction vector" />
+  </class>
+
+  <class name="Location" desc="location in 3d space w/ coordiantes & movement strategy">
+    <member name="id" type="int" desc="Location identifier" ignore_null="true" />
+    <member name="x"  type="int" desc="x coordinate"/>
+    <member name="y"  type="int" desc="y coordinate"/>
+    <member name="z"  type="int" desc="z coordinate"/>
+    <member name="parent_id" type="int" desc="location id of parent, null if this is a root location" ignore_null="true" />
+    <member name="parent"    type="obj" associated="Location" desc="parent location"/>
+    <member name="children"  type="array" associated="Location" desc="children locations"/>
+    <member name="movement_strategy" type="obj" desc="associated movement strategy"/>
+    <member name="entity_id" type="int" desc="id of entity represented by this location" />
+    <member name="entity_type" type="str" desc="type of entity represented by this location" />
+  </class>
+
+  <method name="get_location" desc="get location from specified id">
+    <param name="location_id" type="int" desc="Location identifier"/>
+    <return_value name="location" type="obj" associated="Location" desc="Location corresponding to id or nil"/>
+  </method>
+
+  <method name="create_location" desc="create new location w/ specified id">
+    <param name="location_id" type="int" desc="Location identifier"/>
+    <return_value name="success" type="bool" desc="bool success"/>
+  </method>
+
+  <method name="update_location" desc="update running location w/ new location sharing the same id">
+    <param name="location" type="obj" associated="Location" desc="Location with new attributes and identifier of location to update"/>
+    <return_value name="success" type="bool" desc="bool success"/>
+  </method>
+
+  <!-- TODO delete_location -->
+
+  <method name="subscribe_to_location" desc="subscribe simrpc endpoint to updates to location of the specified id via the location_moved method">
+    <param name="location_id" type="int" desc="Location identifier"/>
+    <param name="node_id" type="str" desc="Node identifier which to update of location movements"/>
+    <return_value name="success" type="bool" desc="bool success"/>
+  </method>
+
+  <method name="location_moved" desc="inform simrpc endpoint that location was moved">
+    <param name="location" type="obj" associated="Location" desc="Location that was moved with new coordinates and original id"/>
+  </method>
+</schema>

data/lib/motel/common.rb

@@ -2,11 +2,44 @@
 #
 # Things that don't fit elsewhere
 #
-# Copyright (C) 2009 Mohammed Morsi <movitto@yahoo.com>
-# See COPYING for the License of this software
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+# include logger dependencies
+require 'logger'
 
 module Motel
 
+# Logger helper class
+class Logger
+  private
+    def self._instantiate_logger
+       unless defined? @@logger
+         # FIXME need configurable log_level, out-stream
+         @@log_level = ::Logger::FATAL
+         @@logger = ::Logger.new(STDOUT)
+         @@logger.level = @@log_level
+       end 
+    end 
+
+  public
+
+    def self.method_missing(method_id, *args)
+       _instantiate_logger
+       @@logger.send(method_id, args)
+    end 
+
+    def self.logger
+       _instantiate_logger
+       @@logger
+    end
+
+    def self.log_level=(level)
+      @@log_level = level
+    end
+end
+
+
 # generate a random id
 def gen_uuid
   ["%02x"*4, "%02x"*2, "%02x"*2, "%02x"*2, "%02x"*6].join("-") %
@@ -43,12 +76,3 @@ class Float
      return (self * 10 ** precision).round.to_f / (10 ** precision)
   end
 end
-
-# try to find key equal to method, returning value if found
-#class Hash  
-#  def method_missing(method, *params)  
-#    method = method.to_sym  
-#    return self[method] if self.keys.collect{ |k| k.to_sym }.include?(method)  
-#    super  
-#  end  
-#end

data/lib/motel/dsl.rb

@@ -0,0 +1,12 @@
+# Motel DSL
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+# establish client connection w/ specified args and invoke block w/ 
+# newly created client, returning it after block terminates
+def connect(args = {}, &block)
+   client = Motel::Client.new(args)
+   block.call client unless block.nil?
+   return client
+end

data/lib/motel/exceptions.rb

@@ -0,0 +1,14 @@
+# Exceptions used in the MOTEL project
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+module Motel
+
+class InvalidMovementStrategy  < RuntimeError
+   def initialize(msg)
+      super(msg)
+   end
+end
+
+end

data/lib/motel/location.rb

@@ -0,0 +1,100 @@
+# The Location entity
+#
+# Copyright (C) 2010 Mohammed Morsi <movitto@yahoo.com>
+# Licensed under the AGPLv3+ http://www.gnu.org/licenses/agpl.txt
+
+require 'motel/movement_strategy'
+
+module Motel
+
+# A Location defines an optional parent location and the x,y,z
+# cartesian  coordinates of the location relative to that parent.
+# If parent is not specified x,y,z are ignored and this location
+# is assumed to be the 'center' of the system to which it belongs
+# Also is related to a movable object defining the parameters
+# of the locations movement 
+class Location
+
+   # id of location and parent, and coordinates relative to that parent
+   attr_accessor :id, :x, :y, :z, :parent_id
+
+   # handle to parent location and array of children
+   attr_accessor :parent, :children
+
+   # movement strategy which location move in accordance to
+   attr_accessor :movement_strategy
+
+   # array of callbacks to be invoked on movement
+   attr_accessor :movement_callbacks
+
+   # a generic association which this location can belong to
+   attr_accessor :entity
+
+   def initialize(args = {})
+      # default to the stopped movement strategy
+      @movement_strategy = MovementStrategies::Stopped.instance
+      @movement_callbacks = []
+      @children = []
+
+      @id = args[:id] if args.has_key? :id
+      @parent_id = args[:parent_id] if args.has_key? :parent_id
+      @x = args[:x] if args.has_key? :x
+      @y = args[:y] if args.has_key? :y
+      @z = args[:z] if args.has_key? :z
+      @parent = args[:parent] if args.has_key? :parent
+      @parent.children.push self unless @parent.nil? || @parent.children.include?(self)
+      @movement_strategy = args[:movement_strategy] if args.has_key? :movement_strategy
+
+      @x = 0 if @x.nil?
+      @y = 0 if @y.nil?
+      @z = 0 if @z.nil?
+   end
+
+   # update this location's attributes to match other's set attributes
+   def update(location)
+      @x = location.x unless location.x.nil?
+      @y = location.y unless location.y.nil?
+      @z = location.z unless location.z.nil?
+      @movement_strategy = location.movement_strategy unless location.movement_strategy.nil?
+      @parent = location.parent unless location.parent.nil?
+      @parent_id = location.parent_id unless location.parent_id.nil?
+   end
+
+   # return this location's root location
+   def root
+     return self if parent.nil?
+     return parent.root
+   end
+
+   # traverse all chilren recursively, calling block for each
+   def traverse_descendants(&bl)
+      children.each { |child|
+         bl.call child
+         child.traverse_descendants &bl
+      }
+   end
+
+   # return sum of the x values of this location and all its parents,
+   # eg the absolute 'x' of the location
+   def total_x
+     return 0 if parent.nil?
+     return parent.total_x + x
+   end
+
+   # return sum of the y values of this location and all its parents
+   # eg the absolute 'y' of the location
+   def total_y
+     return 0 if parent.nil?
+     return parent.total_y + y
+   end
+
+   # return sum of the z values of this location and all its parents
+   # eg the absolute 'z' of the location
+   def total_z
+     return 0 if parent.nil?
+     return parent.total_z + z
+   end
+
+end
+
+end # module Motel