eric-adhearsion 0.7.999 → 0.8.0

data/lib/adhearsion/component_manager/spec_framework.rb

@@ -0,0 +1,24 @@
+require 'adhearsion/component_manager/component_tester'
+begin
+  require 'spec'
+rescue LoadError
+  abort 'You do not have the "rspec" gem installed! You must install it to continue.\n\nsudo gem install rspec\n\n'
+end
+
+begin
+  require 'rr'
+rescue LoadError
+  abort 'You do not have the "rr" gem installed! You must install it to continue.\n\nsudo gem install rr\n\n'  
+end
+
+module ComponentConfigurationSpecHelper
+  def mock_component_config_with(new_config)
+    Object.send(:remove_const, :COMPONENTS) rescue nil
+    Object.send(:const_set, :COMPONENTS, OpenStruct.new(new_config))
+  end
+end
+
+Spec::Runner.configure do |config|
+  config.mock_with :rr
+  config.include ComponentConfigurationSpecHelper
+end

data/lib/adhearsion/events_support.rb

@@ -0,0 +1,84 @@
+%w[theatre jicksta-theatre].each do |theatre_gem_name|
+  # Some older versions of the master branch required the theatre gem be installed. This is deprecation logic to inform the
+  # user to uninstall the gem if they happened to have used theatre in the past.
+  begin
+    gem theatre_gem_name
+  rescue LoadError
+    # Good. It should not be installed.
+  else
+    abort <<-MESSAGE
+It seems you have the "#{theatre_gem_name}" gem installed. As of Dec. 7th, 2008 Theatre has been rolled into Adhearsion
+and will be distributed with it.
+
+Please uninstall the gem by doing "sudo gem uninstall #{theatre_gem_name}".
+
+You will not need to install it again in the future. Sorry for the inconvenience.
+    MESSAGE
+  end
+end
+
+require 'theatre'
+
+
+module Adhearsion
+  module Events
+    
+    DEFAULT_FRAMEWORK_EVENT_NAMESPACES = %w[
+      /after_initialized
+      /shutdown
+      /asterisk/manager_interface
+      /asterisk/before_call
+      /asterisk/after_call
+      /asterisk/hungup_call
+      /asterisk/failed_call
+    ]
+    
+    class << self
+      
+      def framework_theatre
+        defined?(@@framework_theatre) ? @@framework_theatre : reinitialize_theatre!
+      end
+      
+      def trigger(*args)
+        framework_theatre.trigger(*args)
+      end
+      
+      def trigger_immediately(*args)
+        framework_theatre.trigger_immediately(*args)
+      end
+      
+      def reinitialize_theatre!
+        @@framework_theatre.gracefully_stop! if defined? @@framework_theatre
+      rescue
+        # Recover and reinitalize
+      ensure
+        # TODO: Extract number of threads to use from AHN_CONFIG
+        @@framework_theatre = Theatre::Theatre.new
+        DEFAULT_FRAMEWORK_EVENT_NAMESPACES.each do |namespace|
+          register_namespace_name namespace
+        end
+        return @@framework_theatre
+      end
+      
+      def register_namespace_name(name)
+        framework_theatre.register_namespace_name name
+      end
+      
+      def stop!
+        Events.trigger :shutdown
+        framework_theatre.graceful_stop!
+        framework_theatre.join
+      end
+      
+      def register_callback(namespace, block_arg=nil, &method_block)
+        raise ArgumentError, "Cannot supply two blocks!" if block_arg && block_given?
+        block = method_block || block_arg
+        raise ArgumentError, "Must supply a callback!" unless block
+        
+        framework_theatre.register_callback_at_namespace(namespace, block)
+      end
+      
+    end
+    
+  end
+end

data/lib/adhearsion/foundation/event_socket.rb

@@ -0,0 +1,203 @@
+##
+# EventSocket is a small abstraction of TCPSocket which causes it to behave much like an EventMachine Connection object for
+# the sake of better testability. The EventMachine Connection paradigm (as well as other networking libraries such as the 
+# Objective-C HTTP library) uses callbacks to signal different stages of a socket's lifecycle. 
+#
+# A handler can be registered in one of two ways: through registrations on an object yielded by the constructor or 
+# pre-defined on the object given as a constructor parameter. Below is an example definition which uses the block way:
+#
+#   EventSocket.new do |handler|
+#     def handler.receive_data(data)
+#       # Do something here
+#     end
+#     def handler.disconnected
+#       # Do something here
+#     end
+#     def handler.connected
+#       # Do something here
+#     end
+#   end
+#
+# Note: this is also a valid way of defining block callbacks:
+#
+#   EventSocket.new do |handler|
+#     handler.receive_data { |data| do_something }
+#     handler.disconnected { do_something }
+#     handler.connected    { do_something }
+#   end
+#
+# and here is an example of using a handler object:
+#
+#   class MyCallbackHandler
+#     def receive_data(data) end
+#     def connected() end
+#     def disconnected() end
+#   end
+#   EventSocket.new(MyCallbackHandler.new)
+#
+# If you wish to ask the EventSocket what state it is in, you can call the Thread-safe EventSocket#state method. The 
+# supported states are:
+#
+#  - :new
+#  - :connected
+#  - :stopped
+#  - :connection_dropped
+#
+# Note: the EventSocket's state will be changed before these callbacks are executed. For example, if your "connected" 
+# callback queried its own EventSocket for its state, it will have already transitioned to the connected() state.
+#
+# Warning: If an exception occurs in your EventSocket callbacks, they will be "eaten" and never bubbled up the call stack. 
+# You should always wrap your callbacks in a begin/rescue clause and handle exceptions explicitly.
+#
+require "thread"
+require "socket"
+
+class EventSocket
+
+  class << self
+    
+    ##
+    # Creates and returns a connected EventSocket instance.
+    #
+    def connect(*args, &block)
+      instance = new(*args, &block)
+      instance.connect!
+      instance
+    end
+  end
+
+  MAX_CHUNK_SIZE = 256 * 1024
+  
+  def initialize(host, port, handler=nil, &block)
+    raise ArgumentError, "Cannot supply both a handler object and a block" if handler && block_given?
+    raise ArgumentError, "Must supply either a handler object or a block" if !handler && !block_given?
+    
+    @state_lock = Mutex.new
+    @host  = host
+    @port  = port
+    
+    @state = :new
+    @handler = handler || new_handler_from_block(&block)
+  end
+  
+  def state
+    @state_lock.synchronize { @state }
+  end
+  
+  def connect!
+    @state_lock.synchronize do
+      if @state.equal? :connected
+        raise ConnectionError, "Already connected!"
+      else
+        @socket = TCPSocket.new(@host, @port)
+        @state  = :connected
+      end
+    end
+    @handler.connected rescue nil
+    @reader_thread = spawn_reader_thread
+    self
+  rescue => error
+    @state = :failed
+    raise error
+  end
+  
+  ##
+  # Thread-safe implementation of write.
+  #
+  # @param [String] data Data to write
+  #
+  def send_data(data)
+    # Note: TCPSocket#write is intrinsically Thread-safe
+    @socket.write data
+  rescue
+    connection_dropped!
+  end
+    ##
+  # Disconnects this EventSocket and sets the state to :stopped
+  #
+  def disconnect!
+    @state_lock.synchronize do
+      @socket.close rescue nil
+      @state = :stopped
+    end
+  end
+  
+  ##
+  # Joins the Thread which reads data off the socket.
+  #
+  def join
+    @state_lock.synchronize do
+      if @state.equal? :connected
+        @reader_thread.join
+      else
+        nil
+      end
+    end
+  end
+  
+  def receive_data(data)
+    @handler.receive_data(data)
+  end
+  
+  protected
+  
+  def connection_dropped!
+    @state_lock.synchronize do
+      unless @state.equal? :connection_dropped
+        @state = :connection_dropped
+        @handler.disconnected
+      end
+    end
+  end
+  
+  def spawn_reader_thread
+    Thread.new(&method(:reader_loop))
+  end
+  
+  def reader_loop
+    until state.equal? :stopped
+      data = @socket.readpartial(MAX_CHUNK_SIZE)
+      @handler.receive_data data
+    end
+  rescue EOFError
+    connection_dropped!
+  end
+
+  def new_handler_from_block(&handler_block)
+    handler = Object.new
+    handler.metaclass.send :attr_accessor, :set_callbacks
+    handler.set_callbacks = {:receive_data => false, :disconnected => false, :connected => false }
+    
+    def handler.receive_data(&block)
+      self.metaclass.send(:remove_method, :receive_data)
+      self.metaclass.send(:define_method, :receive_data) { |data| block.call data }
+      set_callbacks[:receive_data] = true
+    end
+    def handler.connected(&block)
+      self.metaclass.send(:remove_method, :connected)
+      self.metaclass.send(:define_method, :connected) { block.call }
+      set_callbacks[:connected] = true
+    end
+    def handler.disconnected(&block)
+      self.metaclass.send(:remove_method, :disconnected)
+      self.metaclass.send(:define_method, :disconnected) { block.call }
+      set_callbacks[:disconnected] = true
+    end
+    
+    def handler.singleton_method_added(name)
+      set_callbacks[name.to_sym] = true
+    end
+    
+    yield handler
+    
+    handler.set_callbacks.each_pair do |callback_name,was_set|
+      handler.send(callback_name) {} unless was_set
+    end
+    
+    handler
+    
+  end
+
+  class ConnectionError < Exception; end
+  
+end

data/lib/adhearsion/foundation/future_resource.rb

@@ -0,0 +1,36 @@
+require "thread"
+
+class FutureResource
+  
+  def initialize
+    @resource_lock          = Monitor.new
+    @resource_value_blocker = @resource_lock.new_cond
+  end
+  
+  def set_yet?
+    @resource_lock.synchronize { defined? @resource }
+  end
+  
+  def resource
+    @resource_lock.synchronize do
+      @resource_value_blocker.wait unless defined? @resource
+      @resource
+    end
+  end
+  
+  def resource=(resource)
+    @resource_lock.synchronize do
+      raise ResourceAlreadySetException if defined? @resource
+      @resource = resource
+      @resource_value_blocker.broadcast
+      @resource_value_blocker = nil # Don't really need it anymore.
+    end
+  end
+  
+  class ResourceAlreadySetException < Exception
+    def initialize
+      super "Cannot set this resource twice!"
+    end
+  end
+  
+end

data/lib/adhearsion/foundation/numeric.rb

@@ -0,0 +1,13 @@
+class Numeric
+  
+  def digit()
+    ahn_log.deprecation 'Please do not use Fixnum#digit() and Fixnum#digits() in the future! These will be deprecated soon'
+    self
+  end
+  
+  def digits()
+    ahn_log.deprecation 'Please do not use Fixnum#digit() and Fixnum#digits() in the future! These will be deprecated soon'
+    self
+  end
+  
+end

data/lib/adhearsion/foundation/pseudo_guid.rb

@@ -0,0 +1,10 @@
+module PseudoGuidGenerator
+  ##
+  # Generates a new 128-bit Globally Unique Identifier. It is a "pseudo" in that it does not adhere to the RFC which mandates
+  # that a certain section be reserved for a fragment of the NIC MAC address.
+  def new_guid(separator="-")
+    [8,4,4,4,12].map { |segment_length| String.random(segment_length) }.join(separator)
+  end
+end
+
+include PseudoGuidGenerator

data/lib/adhearsion/{core_extensions → foundation}/relationship_properties.rb

@@ -1,5 +1,6 @@
 class Module
   
+  ##
   # In OOP, relationships between classes should be treated as *properties* of those classes. Often, in a complex OO 
   # architecture, you'll end up with many relationships that intermingle in monolithic ways, blunting the effectiveness of
   # subclassing.
@@ -31,6 +32,7 @@ class Module
   # class HybridAutomobile < Automobile
   #   relationship :battery => HybridBattery
   # end
+  #
   def relationships(relationship_mapping)
     relationship_mapping.each_pair do |class_name, class_object|
       define_method(class_name) { class_object } 

data/lib/adhearsion/foundation/string.rb

@@ -0,0 +1,26 @@
+class String
+  
+  def unindent
+    gsub(/^\s*/,'')
+  end
+  
+  def unindent!
+    gsub!(/^\s*/,'')
+  end
+  
+  def self.random_char
+    case random_digit = rand(62)
+      when  0...10 : random_digit.to_s
+      when 10...36 : (random_digit + 55).chr
+      when 36...62 : (random_digit + 61).chr
+    end
+  end
+
+  def self.random(length_of_string=8)
+    Array.new(length_of_string) { random_char }.join
+  end
+  
+  def nameify() downcase.gsub(/[^\w]/, '') end
+  def nameify!() replace nameify end
+    
+end

data/lib/adhearsion/foundation/synchronized_hash.rb

@@ -0,0 +1,96 @@
+##
+# Implementation of a Thread-safe Hash. Works by delegating methods to a Hash behind-the-scenes after obtaining an exclusive # lock. Use exactly as you would a normal Hash.
+#
+class SynchronizedHash
+  
+  def self.atomically_delegate(method_name)
+    class_eval(<<-RUBY, __FILE__, __LINE__)
+      def #{method_name}(*args, &block)
+        @lock.synchronize do
+          @delegate.send(#{method_name.inspect}, *args, &block)
+        end
+      end
+    RUBY
+  end
+  
+  # Hash-related methods
+  
+  atomically_delegate :[]
+  atomically_delegate :[]=
+  atomically_delegate :all?
+  atomically_delegate :any?
+  atomically_delegate :clear
+  atomically_delegate :collect
+  atomically_delegate :default
+  atomically_delegate :default=
+  atomically_delegate :delete
+  atomically_delegate :delete_if
+  atomically_delegate :detect
+  atomically_delegate :each
+  atomically_delegate :each_key
+  atomically_delegate :each_pair
+  atomically_delegate :each_value
+  atomically_delegate :each_with_index
+  atomically_delegate :empty?
+  atomically_delegate :entries
+  atomically_delegate :fetch
+  atomically_delegate :find
+  atomically_delegate :find_all
+  atomically_delegate :grep
+  atomically_delegate :has_key?
+  atomically_delegate :has_value?
+  atomically_delegate :include?
+  atomically_delegate :index
+  atomically_delegate :indexes
+  atomically_delegate :indices
+  atomically_delegate :inject
+  atomically_delegate :invert
+  atomically_delegate :key?
+  atomically_delegate :keys
+  atomically_delegate :length
+  atomically_delegate :map
+  atomically_delegate :max
+  atomically_delegate :member?
+  atomically_delegate :merge
+  atomically_delegate :merge!
+  atomically_delegate :min
+  atomically_delegate :partition
+  atomically_delegate :rehash
+  atomically_delegate :reject
+  atomically_delegate :reject!
+  atomically_delegate :replace
+  atomically_delegate :select
+  atomically_delegate :shift
+  atomically_delegate :size
+  atomically_delegate :sort
+  atomically_delegate :sort_by
+  atomically_delegate :store
+  atomically_delegate :to_hash
+  atomically_delegate :update
+  atomically_delegate :value?
+  atomically_delegate :values
+  atomically_delegate :values_at
+  atomically_delegate :zip
+  
+  # Object-related methods
+  
+  atomically_delegate :inspect
+  atomically_delegate :to_s
+  atomically_delegate :marshal_dump
+  
+  def initialize(*args, &block)
+    @delegate = Hash.new(*args, &block)
+    @lock     = Mutex.new
+  end
+  
+  ##
+  # If you need to do many operations atomically (a la transaction), you can call this method and access the yielded Hash
+  # which can be safely modified for the duration of your block.
+  #
+  # @yield [Hash] the Hash on which you can safely operate during your block.
+  #
+  def with_lock(&block)
+    @lock.synchronize { yield @delegate }
+  end
+  
+end