trimurti 0.1

data/trimurti-0.1/lib/nist/trimurti/plugins.rb

@@ -0,0 +1,107 @@
+=begin rdoc
+This file includes code to find plugins, load them, and
+help integrate them into an application.
+
+For an overview and an example of use, see ReadMe.txt[link:files/ReadMe_txt.html].
+
+Author: A. Griesser
+=end
+
+require 'rbtree'
+  
+# An Array of Plugins::Spec instances.
+# The use of this global is optional:
+# see the documentation for file plugins.rb
+# for alternatives.
+$PLUGINS = Array.new
+
+module Plugins
+  
+  # Provides information an application can use to:
+  # * Initialize the plugin
+  # * Add the plugin to a menu
+  # * Describe the pugin in an "About..." dialog
+  # Intended to be passed to the application through the $PLUGINS global.
+  class Spec
+        # Identifies the plugin
+  	attr_accessor :name
+	# Who wrote the plugin
+	attr_accessor :author
+	# A String describing the plugin. Can be to be nil.
+	attr_accessor :description
+	# A Hash with:
+	# * keys are menu labels
+	# * values depend on the application in which the plugin is to be embedded
+	attr_accessor :actions
+	# A proc the application can use to initialize the plugin. can be nil.
+	attr_accessor :init_proc
+	# Name and Author are required Strings. Description can be nil.
+	# Actions must be a Hash, but it can be empty.
+	def initialize(name, author, description=nil, actions=RBTree.new, init_proc=nil)
+		self.name=name
+		self.author=author
+		self.description=description
+		self.actions=actions
+		self.init_proc=init_proc
+	end
+	# Calls the init_proc. Any arguments provided are passed on to the init_proc.
+	# Plugin developers need to know what arguments the appliction will use.
+	def init(*args)
+		init_proc.call(*args) if init_proc
+	end
+	# Returns a String representation of the plugin, suitable for use in an  "About..." dialog.
+	def to_s(str=String.new)
+		str << name << ' plugin written by ' << author << '.'
+		str << "\n" << description if description
+		str
+	end
+  end # Spec
+  
+  # Looks in all the $LOAD_PATH search roots for files matching pluginGlob.
+  # PluginGlob can be a String or an Array of Strings.
+  # Returns a possibly empty Array of paths local to one of the search roots. 
+  # Suffix defines extensions to remove: see File.basename
+  def find_on_load_path(pluginGlob, suffix='.*')
+    answer = []
+    case pluginGlob
+    when String
+      local_path = File.dirname(pluginGlob)
+      answer = $LOAD_PATH.collect {|root| 
+        sought = File.join(root, pluginGlob)
+        globMatches = Dir.glob(sought)
+        globMatches.collect {|f| File.join(local_path, File.basename(f, suffix)) }
+        }
+    when Array
+      answer = pluginGlob.collect {|relPath| plugin_dirs(relPath) }
+    else
+      raise "Incomprehensible argument to plugins (should be String or Array, was #{pluginGlob.class.name})"
+    end
+    answer.flatten.uniq.sort
+  end
+
+  # Loads (via 'require') all the plugins described by pluginGlob,
+  # so long as the plugin is in accessable from the $LOAD_PATH.
+  # Returns the Array of local paths to plugins (with extensions removed).
+  # PluginGlob can be a String or an Array of Strings.
+  # Takes an optional one-argument block, which is executed
+  # after every load.
+  def require_plugins(pluginGlob, io=STDOUT)
+    parts = find_on_load_path(pluginGlob)
+    io << "\n"
+    if parts.empty?
+      io << "\nDid not find any plugins matching #{pluginGlob.inspect}"
+      io.flush if io.respond_to?(:flush)
+      return parts
+    end
+    parts.each {|part|
+      io << "\nRequiring plugin: '#{part}'"
+      io.flush if io.respond_to?(:flush)
+      require part 
+      next unless block_given?
+      yield(self, part)
+      }
+    return parts
+  end
+  
+
+end # Plugins

data/trimurti-0.1/lib/nist/trimurti/queryByExample.rb

@@ -0,0 +1,81 @@
+
+# For an overview and an example of use, see ReadMe.txt[link:files/ReadMe_txt.html].
+#
+# Author: A. Griesser
+
+require 'nist/common/rubyToolsDay'
+require 'nist/common/guid'
+
+# This module lets you find objects with specified attributes. To perform a query:
+# 1. Instantate an 'example' object of the class you are looking for
+# 2. Set (to the query values) whatever attributes you are querying on.
+# 3. Call query, passing the example as the argument.
+# If you only want a single result, you can instad call retrieve instead.
+#
+# UNDER CONSTRUCTION.
+#
+# Room for improvement:
+# * Queries are not aware of the inheritance hierarchy.
+# * Performance not tested: may not scale well (depends on Rinda implementation).
+# * None of these methods are thread safe.
+module QueryByExample
+include Vishnu
+
+
+# attribute_values(shouldSort=false, answer=Array.new, ignoredVars=nil, onlyVars=nil)
+
+# Creates and stores into the repository a record corresponding to the argument
+def create(thing)
+end
+
+# Returns an Array of repository records that match 'thing'.
+# (empty if not matches). If deRef is true, instead returns the
+# array of objects described by the records.
+def retrieve(thing, deRef=true)
+end
+
+# Returns the registered object with the specified qbeID
+# (nil if there is no such object).
+def find(qbeID)
+end
+
+# Update the repository record corresponding to the argument.
+# Returns a Boolean, true if successful. If there is no
+# corresponding record, returns the result of evaluating 
+# an optional block. The optional block may add the argument
+# to the repository, may raise an exception, or just return
+# something. If the optional block is not present, returns false.
+def update(thing)
+end
+
+# Remove from the repository the record corresponding to 'thing'
+# Returns the record. If deRef is true, instead returns the object
+# described by the record. Silently returns nil if there is no record
+# corresponding to 'thing'.
+def delete(thing, deRef=true)
+end
+
+end # QueryByExample
+
+
+class Object
+# Literals resolve to themselves. All objects are literals,
+# unless they are instances of the class used to represent ids.
+# The ID classes should override this method by including QBE_ID.
+def resolve_within(container)
+    self
+end
+end
+
+# Mix this into classes that can act like ids.
+module QBE_ID
+# Since this is an id rather than a literal,
+# look up (in the container) the thing to which this correspondes.
+def resolve_within(container)
+    container.find(self)
+end
+end
+
+class GUID
+include QBE_ID
+end # GIUD

data/trimurti-0.1/lib/nist/trimurti/trimurti.rb

@@ -0,0 +1,433 @@
+
+# For an overview and an example of use, see ReadMe.txt[link:files/ReadMe_txt.html].
+#
+# Author: A. Griesser
+
+require 'nist/common/log'
+require 'nist/trimurti/plugins'
+require 'nist/trimurti/linda'
+require 'yaml' 
+require 'test/unit/assertions'
+
+
+class Asserter
+    include Test::Unit::Assertions
+end
+ASSERTER = Asserter.new
+
+class Symbol
+  # Receiver specifies API
+  def to_service_spec; [nil, nil, self]; end
+  # Receiver specifies name
+  def to_component_spec; [self.to_s, nil]; end
+end
+
+class String
+  # Receiver specifies name
+  def to_service_spec; [self, nil, nil]; end
+  # Receiver specifies name
+  def to_component_spec; [self, nil]; end
+end
+
+class Array
+  # Must be [name, host, symbol]
+  def to_service_spec
+    ASSERTER.assert_equal(3, size, 'Service spec must be in form: [name, host, symbol] (see Brahma#service)')
+    self
+  end
+  # Must be [name, host]
+  def to_component_spec
+    ASSERTER.assert_equal(2, size, 'Component spec must be in form: [name, host] (see Brahma#component)')
+    self
+  end
+end
+
+
+# ######################################################################
+
+# Vishnu preserves registries of components and services.
+module Vishnu
+  
+attr_accessor :linda
+
+def initialize(is_local=true)
+  self.linda = Linda.new(is_local)
+end
+
+# Returns a String, the name of the computer the method executes on.
+def gethostname
+  linda.gethostname
+end
+
+# Register 'thing' of specified type under specified name
+def register(type, name, thing, *more)
+  linda.put(type, name, thing, *more)
+end
+
+# Register a component. 'provides' is an Array of Symbols specifying service APIs provided.
+# Needs is a Hash with:
+# * Key is a Symbol, the setter for a service the componnent requires
+# * Value responds to to_service_spec (it specifies some other component)
+# Component definition Tuples look like this:
+#    [:component, name, component, hostname, provides, needs, life_cycle]
+def register_component(name, component, provides, needs={}, life_cycle={})
+  ASSERTER.assert_kind_of(Array, provides, "The 'provides' argument to Linda#register_component must be an Array")
+  ASSERTER.assert_kind_of(Hash, needs, "The 'needs' argument to Linda#register_component must be a Hash")
+  ASSERTER.assert_kind_of(Hash, life_cycle, "The 'life_cycle' argument to Linda#register_component must be a Hash")
+	component = _create(life_cycle) unless component
+  register(:component, name, component, gethostname, provides, needs, life_cycle)
+end
+
+# Register a service provider.
+# Provides is an Array of Symbols, each naming a service offered by the provider. 
+# Service tuples look like this:
+#    [:service, name, provider, hostname, symbol]
+def register_service(name, provider, provides)
+  provides.each {|symbol|
+      # For alternative implementation, see task :rinda_register_simplified in Ambrose
+      # This is not compatable: tuple fields are different.
+      register(:service, name, provider, gethostname, symbol)
+      }
+  # Ok to terminate (server state has been updated)
+end
+
+# Appends registered components to the argument, which can be a String or IO.
+# Returns the argument.
+def show_components(io=STDOUT)
+  tuples = component_tuples
+  return io << "\nNo components are registered. "  unless tuples
+  io << "\nAll registered components (Name, host, provides, needs, life_cycle):"
+  tuples.each {|tuple|
+    io << "\n\t#{tuple[1].inspect}\t#{tuple[3].inspect}\t#{tuple[4].inspect}\t#{tuple[5].inspect}\t#{tuple[6].inspect}"
+    }
+  io << "\n"
+end
+  
+# Appends registered services to the argument, which can be a String or IO.
+# Returns the argument.
+def show_services(io=STDOUT)
+  tuples = service_tuples
+  return io << "\nNo services are registered. "  unless tuples
+  io << "\nAll registered services (name, host, provides):"
+  tuples.each {|tuple|
+    io << "\n\t#{tuple[1].inspect}\t#{tuple[3].inspect}\t#{tuple[4].inspect}"
+    }
+  io << "\n"
+end
+
+# Finds Tuples describing components.  
+# Arguments can be:
+# * nil if you don't care what the value should be
+# * A Regexp if you want to select a matching pattern.
+# This returns a (possibly empty) Array of matching Tuples
+def component_tuples(name=nil, host=nil)
+  linda.rd_all(:component, name, nil, host, nil, nil, nil)
+end
+
+# Find a Tuple describing a component. 
+# arguments can be:
+# * nil if you don't care what the value is
+# * A Regexp if you want to select a matching pattern.
+# This returns:
+# * a Tuple describing a matching component (the local host is prefered)
+# * nil if there is no matching tuple
+def component_tuple(name=nil, host=nil, symbol=nil)
+  h = host || gethostname
+  tuples = component_tuples(name, h)
+  tuples = component_tuples(name, nil) if tuples.empty? && !host
+  return nil unless tuples
+  tuples[0]
+end
+
+# Find a specific component. 
+# arguments can be:
+# * nil if you don't care what the value is
+# * A Regexp if you want to select a matching pattern.
+# This returns:
+# * a component with a matching Tuple (the local host is prefered)
+# * nil if there is no matching tuple
+def component(name=nil, host=nil)
+  tuple = component_tuple(name, host)
+  return nil unless tuple
+  tuple[2]
+end
+
+# Finds Tuples describing services.  
+# Arguments can be:
+# * nil if you don't care what the value should be
+# * A Regexp if you want to select a matching pattern.
+# This returns a (possibly empty) Array of matching Tuples
+def service_tuples(name=nil, host=nil, symbol=nil )
+  linda.rd_all(:service, name, nil, host, symbol)
+end
+
+# Find a Tuple describing a service. 
+# arguments can be:
+# * nil if you don't care what the value is
+# * A Regexp if you want to select a matching pattern.
+# This returns:
+# * a Tuple describing a matching provider (the local host is prefered)
+# * nil if there is no matching tuple
+def service_tuple(name=nil, host=nil, symbol=nil)
+  h = host || gethostname
+  tuples = service_tuples(name, h, symbol )
+  tuples = service_tuples(name, nil, symbol ) if tuples.empty? && !host
+  return nil unless tuples
+  tuples[0]
+end
+
+# Find a specific service. 
+# arguments can be:
+# * nil if you don't care what the value is
+# * A Regexp if you want to select a matching pattern.
+# This returns:
+# * a provider with a matching Tuple (the local host is prefered)
+# * nil if there is no matching tuple
+# Usually only the symbol is necessary: the other arguments are
+# present for consistency with other methods (and those rare
+# times when you really do need to specify them).
+def service(name=nil, host=nil, symbol=nil)
+  tuple = service_tuple(name, host, symbol)
+  return nil unless tuple
+  tuple[2]
+end
+
+
+# Execute the code String (which may contain a 'component' local),
+# returning the result of this evaluation. Returns nil if the
+# code string is nil.
+def apply(code, component)
+  return nil unless code
+  eval(code)
+end
+
+# For each component, apply the life_cycle[selector] code.
+def life_cycle(selector)
+  tuples = component_tuples
+  problems = Array.new
+  tuples.each {|tuple|
+    component = tuple[2]
+    life_cyc = tuple[6]
+    begin
+    apply(life_cyc[selector], component)
+    rescue
+        problems << $!
+    end
+    }
+    return if problems.empty?
+    raise "Problems connecting components: #{problems.join(', ')}"
+end
+
+
+# Gets the :create code from the life_cycle_hash, and executes it.
+# Fails if unable to create component.
+def _create(life_cycle_hash)
+  fail 'Can not create component: no life_cycle Hash' unless life_cycle_hash
+  instantiation_code = life_cycle_hash[:create]
+	fail 'Can not create component: life_cycle Hash is missing :create.' unless instantiation_code
+	apply(instantiation_code, nil)
+end
+
+end # Vishnu
+
+# ######################################################################
+
+# Brahma creates applications from components and services.
+module Brahma
+include Vishnu
+
+# Register the services of specified component.
+# Each service shares the name of its component.
+def register_component_services(componentTuple)
+  name = componentTuple[1]
+  component = componentTuple[2]
+  provided = componentTuple[4]
+  register_service(name, component, provided)
+end
+
+# Register the services of every previously registered component
+def register_services
+  component_tuples.each {|tuple|
+    register_component_services(tuple)
+    }
+end
+
+# For each component, get the services it needs, and set them.
+def connect_services
+  tuples = component_tuples
+  problems = Array.new
+  tuples.each {|tuple|
+    name = tuple[1]
+    component = tuple[2]
+    needs = tuple[5]
+    needs.each {|setter, svc_api|
+      provider = service(*svc_api.to_service_spec)
+      unless provider
+        problems << "Component <#{name}> needs, but couldn't find, service #{svc_api.inspect}"
+        next
+      end
+      err = _connect(component, name, setter, provider)
+      problems << err if err
+      }
+    }
+    return if problems.empty?
+		joint = "\n"
+    fail "Problem(s) (#{problems.size.to_s}) connecting components: \n#{problems.join(joint)}"
+end
+
+# For each component, evaluate the life_cycle[:start] code.
+def start_components
+  life_cycle(:start)
+end
+
+# Assembles the application from registered components by:
+# * Registering all the services provided by the components
+# * Connecting service consumers to service providers.
+# * Starting the components
+def assemble
+	register_services
+	connect_services
+	start_components
+end
+
+# Returns nil if successful, an error String if a problem occured.
+def _connect(component, name, setter, provider)
+  component.send(setter, provider )
+  return nil
+rescue
+  return "Error providing service to <#{name}> using <#{setter}>: #{$!}"
+end
+
+# Registers components described in a YAML file. 
+# Does not register the services contained in the components, and
+# does not hook together the service providers and consumers.
+# Source can be
+# * A String naming a file containing a YAML serialization (if isFilename=true)
+# * A String containing a YAML serialization (if isFilename=false)
+# * An IO streaming over a YAML serialization (if isFilename=false)
+# In any case, the YAML serialization must contain an Array of ComponentSpec instances.
+def from_yaml(source, isFilename=true)
+  source = File.open(source) if isFilename
+  specs = YAML.load(source) 
+  errors = specs.collect {|spec| create_registered_component(spec) }
+  errors.flatten!
+  errors.compact!
+  return if errors.empty?
+  sep = "\n"
+  raise "Error(s) creating or registering components: #{errors.join(sep)}"
+end
+
+
+
+# Creates component:
+# * Uses 'require' to load any necessary source
+# * Executes life_cycle[:create] code
+# * Sets compSpec.component
+def create_component(componentSpec)
+  componentSpec.require_source
+	answer = _create(componentSpec.life_cycle)
+  raise "Attempt to instantiate component resulted in nil: #{componentSpec.inspect}" unless answer
+  componentSpec.component= answer
+  answer
+end
+
+# Creates and registers component:
+# * Uses 'require' to load any necessary source
+# * Executes life_cycle[:create] code
+# * Sets compSpec.component
+# * Registers the component
+# Returns nil or an error String.
+def create_registered_component(compSpec)
+  create_component(compSpec)
+  register_component(compSpec.name, compSpec.component, compSpec.provides, compSpec.needs, compSpec.life_cycle )
+  return nil
+  rescue
+    return "Error creating component #{compSpec.inspect}: #{$!}"
+end 
+
+end # Brahma
+
+# ######################################################################
+
+# Shiva shuts down and destroys (in an orderly fashion) applications 
+# built from components and services.
+module Shiva
+
+def stop_components
+  life_cycle(:stop)
+end
+
+def destroy_components(stop=true)
+  stop_components if stop
+  life_cycle(:destroy)
+end
+
+end # Shiva
+
+# ######################################################################
+
+# A class that provides all the functionality of Vishnu, Brahma, and Shiva,
+# for use when mixins are not required. The behaviors are available on both instance
+# side, and the class side (through a lazy-initialized default_instance).
+class Trimurti
+include Plugins
+include Brahma
+include Shiva
+
+@@default_instance=nil
+def self.default_instance; @@default_instance || @@default_instance=self.new; end
+def self.default_instance=(inst); @@default_instance=inst; end
+
+forward_reflect_except(:default_instance, Trimurti)
+
+end # Trimurti
+
+# ######################################################################
+
+
+# Describes a Component that can be managed by Vishnu/Brahma.
+# Can be unmarshalled by Yaml to register a Component.
+class ComponentSpec
+ 
+# A String identifying the instance 
+attr_accessor :name
+
+# Not marshalled
+attr_accessor :component
+
+# An Array of file names that are loaded by 'require' before instantiation
+attr_accessor :required_source
+
+# A Hash that specifies how to manage the component's life cycle. Only the 
+# :create key is required.
+# * Keys are Symbols that specify life cycle events. The following keys are valid:
+#      * :create  - Instantiate the component
+#      * :start   - Activate all services
+#      * :stop    - Turn off all services
+#      * :destroy - Discard references to other components
+# * Values are Strings that specify behaviors that is to occur at life cyle events.
+attr_accessor :life_cycle
+
+# An Array of Symbols, each naming a collection of methods provided by the instance
+attr_accessor :provides
+
+# A Hash that describes how to provided necessary services to the instance:
+# * Key is a name of a method (on the component) that takes one argument (the service provider)
+# * Value is either:
+#   * a Symbol that identifies the required API
+#   * an Array containing the 3 arguments to Brahman#service
+attr_accessor :needs
+
+# Load (via 'require') all the source code needed by the component.
+def require_source
+  required_source.each {|src| 
+    print "\nComponentSpec #{name} is requiring #{src} "; STDOUT.flush
+    require src 
+    }
+end
+
+def to_yaml_properties 
+  ['@name', '@required_source', '@provides', '@needs', '@life_cycle']
+end
+
+end # ComponentSpec