omf_rc 6.0.2.pre.2 → 6.0.2

data/lib/omf_rc/resource_proxy/abstract_resource.rb

@@ -1,4 +1,8 @@
-#require 'omf_rc/deferred_process'
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'omf_rc/omf_error'
 require 'securerandom'
 require 'hashie'
@@ -24,11 +28,49 @@ class OmfRc::ResourceProxy::MPReceived < OML4R::MPBase
   param :mid, :type => :string # Unique ID this message
 end
 
+# @note Suppose you have read the {file:doc/DEVELOPERS.mkd DEVELOPERS GUIDE} which explains the basic the resource controller system.
+#
+# This is the abstract resource proxy class, which provides the base of all proxy implementations. When creating new resource instances, this abstract class will always be initialised first and then extended by one of the specific resource proxy modules.
+#
+# Instead of initialise abstract resource directly, use {OmfRc::ResourceFactory Resource Factory}'s methods.
+#
+# @example Creating resource using factory method
+#   OmfRc::ResourceFactory.create(:node, uid: 'node01')
+#
+# Proxy documentation has grouped FRCP API methods for your convenience.
+#
+# We follow a simple naming convention for request/configure properties.
+#
+#   request_xxx() indicates property 'xxx' can be requested using FRCP REQUEST message.
+#
+#   configure_xxx(value) indicates property 'xxx' can be configured with 'value' using FRCP CONFIGURE message.
+#
+# Currently official OMF RC gem contains following resource proxies:
+#
+# Representing physical/virtual machine
+# * {OmfRc::ResourceProxy::Node Node}
+#
+# Executing OML enabled application and monitor output
+# * {OmfRc::ResourceProxy::Application Application}
+#
+# Configuring network interfaces
+# * {OmfRc::ResourceProxy::Net Net}
+# * {OmfRc::ResourceProxy::Wlan Wlan}
+#
+# Installing packages
+# * {OmfRc::ResourceProxy::Package Package}
+#
+# Creating virtual machines
+# * {OmfRc::ResourceProxy::VirtualMachineFactory VirtualMachineFactory}
+# * {OmfRc::ResourceProxy::VirtualMachine VirtualMachine}
+#
+# @see OmfRc::ResourceFactory
+# @see OmfRc::ResourceProxyDSL
+#
 class OmfRc::ResourceProxy::AbstractResource
   include MonitorMixin
+  include OmfRc::ResourceProxyDSL
 
-  # Time to wait before shutting down event loop, wait for deleting pubsub topics
-  DISCONNECT_WAIT = 5
   # Time to wait before releasing resource, wait for deleting pubsub topics
   RELEASE_WAIT = 5
 
@@ -37,8 +79,6 @@ class OmfRc::ResourceProxy::AbstractResource
     create_children_resources: true
   }
 
-  # @!attribute property
-  #   @return [String] the resource's internal meta data storage
   attr_accessor :uid, :hrn, :type, :comm, :property, :certificate
   attr_reader :opts, :children, :membership, :creation_opts, :membership_topics
 
@@ -58,6 +98,8 @@ class OmfRc::ResourceProxy::AbstractResource
   # @option creation_opts [Boolean] :create_children_resources Immediately create 'known' children resources, such as interfaces on nodes
   #
   def initialize(type, opts = {}, creation_opts = {}, &creation_callback)
+    super()
+
     @opts = Hashie::Mash.new(opts)
     @creation_opts = Hashie::Mash.new(DEFAULT_CREATION_OPTS.merge(creation_opts))
 
@@ -66,12 +108,11 @@ class OmfRc::ResourceProxy::AbstractResource
     @hrn = @opts.hrn && @opts.hrn.to_s
 
     @children ||= []
-    @membership ||= []
+    @membership = []
     @topics = []
     @membership_topics ||= {}
 
-    @property = @opts.property || Hashie::Mash.new
-    @property.merge!(@opts.except([:uid, :hrn, :property, :instrument]))
+    @property = Hashie::Mash.new(@opts.property)
 
     OmfCommon.comm.subscribe(@uid) do |t|
       @topics << t
@@ -98,26 +139,30 @@ class OmfRc::ResourceProxy::AbstractResource
 
         t.inform(:creation_ok, cprops, copts)
 
-        t.on_message(nil, @uid) do |imsg|
+        t.on_message(@uid) do |imsg|
           process_omf_message(imsg, t)
         end
       end
     end
-
-    super()
+    configure_membership(@opts.membership) if @opts.membership
   end
 
-  # Return the public 'routable'  address for this resource
+  # Return the public 'routable' address for this resource or nil if not known yet.
   #
   def resource_address()
-    @topics[0].address
+    if t = @topics[0]
+      t.address
+    else
+      nil # TODO: should we raise Excaption
+    end
   end
 
+  # Get binding of current object, used for ERB eval
   def get_binding
     binding
   end
 
-  # Try to clean up pubsub topics, and wait for DISCONNECT_WAIT seconds, then shutdown event machine loop
+  # Disconnect using communicator
   def disconnect
     OmfCommon.comm.disconnect
   end
@@ -125,6 +170,7 @@ class OmfRc::ResourceProxy::AbstractResource
   # Create a new resource in the context of this resource. This resource becomes parent, and newly created resource becomes child
   #
   # @param (see #initialize)
+  # @return [AbstractResource] new resource has been created
   def create(type, opts = {}, creation_opts = {}, &creation_callback)
     unless request_supported_children_type.include?(type.to_sym)
       raise StandardError, "Resource #{type} is not designed to be created by #{self.type}"
@@ -132,9 +178,15 @@ class OmfRc::ResourceProxy::AbstractResource
 
     opts[:parent_certificate] = @certificate if @certificate
     opts[:parent] = self
-    before_create(type, opts) if respond_to? :before_create
+
+    call_hook(:before_create, self, type, opts)
+
     new_resource = OmfRc::ResourceFactory.create(type.to_sym, opts, creation_opts, &creation_callback)
-    after_create(new_resource) if respond_to? :after_create
+
+    new_props = opts.reject { |k| [:type, :name, :uid, :hrn, :property, :instrument].include?(k.to_sym) }
+    init_configure(new_resource, new_props)
+
+    call_hook(:after_create, self, new_resource)
 
     self.synchronize do
       children << new_resource
@@ -144,8 +196,7 @@ class OmfRc::ResourceProxy::AbstractResource
 
   # Release a child resource
   #
-  # @return [AbstractResource] Relsead child or nil if error
-  #
+  # @return [AbstractResource] Released child or nil if error
   def release(res_id)
     if (child = children.find { |v| v.uid.to_s == res_id.to_s })
       if child.release_self()
@@ -165,8 +216,7 @@ class OmfRc::ResourceProxy::AbstractResource
 
   # Release this resource. Should ONLY be called by parent resource.
   #
-  # Return true if successful
-  #
+  # @return [Boolean] true if successful
   def release_self
     # Release children resource recursively
     children.each do |c|
@@ -180,7 +230,9 @@ class OmfRc::ResourceProxy::AbstractResource
     return false unless children.empty?
 
     info "Releasing hrn: #{hrn}, uid: #{uid}"
-    self.before_release if self.respond_to? :before_release
+
+    call_hook(:before_release, self)
+
     props = {
       res_id: resource_address
     }
@@ -189,19 +241,24 @@ class OmfRc::ResourceProxy::AbstractResource
 
     # clean up topics
     @topics.each do |t|
-      t.unsubscribe
+      t.unsubscribe(@uid)
     end
 
     @membership_topics.each_value do |t|
       if t.respond_to? :delete_on_message_cbk_by_id
         t.delete_on_message_cbk_by_id(@uid)
       end
-      t.unsubscribe
+      t.unsubscribe(@uid)
     end
 
     true
   end
 
+  # @!macro group_request
+  #
+  # Return a list of child resources this resource can create
+  #
+  # @return [Array<Symbol>]
   def request_supported_children_type(*args)
     OmfRc::ResourceFactory.proxy_list.reject { |v| v == @type.to_s }.find_all do |k, v|
       (v.create_by && v.create_by.include?(@type.to_sym)) || v.create_by.nil?
@@ -210,6 +267,10 @@ class OmfRc::ResourceProxy::AbstractResource
 
   # Return a list of all properties can be requested and configured
   #
+  # @example
+  #   { request: [:ip_addr, :frequency], configure: [:ip_address] }
+  #
+  # @return [Hashie::Mash]
   def request_available_properties(*args)
     Hashie::Mash.new(request: [], configure: []).tap do |mash|
       methods.each do |m|
@@ -223,14 +284,11 @@ class OmfRc::ResourceProxy::AbstractResource
     uid
   end
 
+  # Make type accessible through pubsub interface
   def request_type(*args)
     type
   end
 
-  def configure_type(*args)
-    @type = type
-  end
-
   # Make hrn accessible through pubsub interface
   def request_hrn(*args)
     hrn
@@ -238,22 +296,28 @@ class OmfRc::ResourceProxy::AbstractResource
 
   alias_method :request_name, :request_hrn
   alias_method :name, :hrn
+  alias_method :name=, :hrn=
 
-  # Make hrn configurable through pubsub interface
-  def configure_hrn(hrn)
-    self.synchronize do
-      @hrn = hrn
-    end
-    @hrn
+  # Query resource's membership
+  def request_membership(*args)
+    @membership
   end
 
-  alias_method :configure_name, :configure_hrn
-  alias_method :name=, :hrn=
+  # Request child resources
+  #
+  # @return [Hashie::Mash] child resource mash with uid and hrn
+  def request_child_resources(*args)
+    #children.map { |c| Hashie::Mash.new({ uid: c.uid, name: c.hrn }) }
+    children.map { |c| c.to_hash }
+  end
+
+  # @!endgroup
+  #
+  # @!macro group_configure
 
   # Make resource part of the group topic, it will overwrite existing membership array
   #
-  # @param [String] name of group topic
-  # @param [Array] name of group topics
+  # @param [String|Array] args name of group topic/topics
   def configure_membership(*args)
     new_membership = [args[0]].flatten
 
@@ -272,7 +336,7 @@ class OmfRc::ResourceProxy::AbstractResource
               self.inform(:status, { membership: @membership }, t)
             end
 
-            t.on_message(nil, @uid) do |imsg|
+            t.on_message(@uid) do |imsg|
               process_omf_message(imsg, t)
             end
           end
@@ -282,22 +346,12 @@ class OmfRc::ResourceProxy::AbstractResource
     @membership
   end
 
-  # Query resource's membership
-  def request_membership(*args)
-    @membership
-  end
-
-  # Request child resources
-  # @return [Hashie::Mash] child resource mash with uid and hrn
-  def request_child_resources(*args)
-    #children.map { |c| Hashie::Mash.new({ uid: c.uid, name: c.hrn }) }
-    children.map { |c| c.to_hash }
-  end
+  # @!endgroup
 
   # Parse omf message and execute as instructed by the message
   #
-  # @param [OmfCommon::Message]
-  # @param [OmfCommon::Comm::Topic]
+  # @param [OmfCommon::Message] message FRCP message
+  # @param [OmfCommon::Comm::Topic] topic subscribed to
   def process_omf_message(message, topic)
     return unless check_guard(message)
 
@@ -317,6 +371,11 @@ class OmfRc::ResourceProxy::AbstractResource
     end
   end
 
+  # Execute operation based on the type of the message
+  #
+  # @param [OmfCommon::Message] message FRCP message
+  # @param [OmfRc::ResourceProxy::AbstractResource] obj resource object
+  # @param [OmfCommon::Comm::Topic] topic subscribed to
   def execute_omf_operation(message, obj, topic)
     begin
       response_h = handle_message(message, obj)
@@ -342,6 +401,9 @@ class OmfRc::ResourceProxy::AbstractResource
   end
 
   # Handling all messages, then delegate them to individual handler
+  #
+  # @param [OmfCommon::Message] message FRCP message
+  # @param [OmfRc::ResourceProxy::AbstractResource] obj resource object
   def handle_message(message, obj)
     response = message.create_inform_reply_message(nil, {}, src: resource_address)
     response.replyto replyto_address(obj, message.replyto)
@@ -350,7 +412,7 @@ class OmfRc::ResourceProxy::AbstractResource
     when :create
       handle_create_message(message, obj, response)
     when :request
-      response = handle_request_message(message, obj, response)
+      handle_request_message(message, obj, response)
     when :configure
       handle_configure_message(message, obj, response)
     when :release
@@ -366,45 +428,31 @@ class OmfRc::ResourceProxy::AbstractResource
     response
   end
 
+  # FRCP CREATE message handler
+  #
+  # @param [OmfCommon::Message] message FRCP message
+  # @param [OmfRc::ResourceProxy::AbstractResource] obj resource object
+  # @param [OmfCommon::Message] response initialised FRCP INFORM message object
   def handle_create_message(message, obj, response)
     new_name = message[:name] || message[:hrn]
-    mprops = message.properties.merge({ hrn: new_name })
-    exclude = [:type, :hrn, :name, :uid]
-    props = {}
-    copts = {}
-    mprops.each do |k, v|
-      if exclude.include?(k)
-        copts[k] = v
-      else
-        props[k] = v
-      end
-    end
-    new_obj = obj.create(message[:type], copts, &lambda do |new_obj|
+    msg_props = message.properties.merge({ hrn: new_name })
+
+    obj.create(message[:type], msg_props, &lambda do |new_obj|
       begin
         response[:res_id] = new_obj.resource_address
+        response[:uid] = new_obj.uid
 
-        props.each do |key, value|
-          method_name = "configure_#{key}"
-
-          if new_obj.respond_to? method_name
-            response[key] = new_obj.__send__(method_name, value)
-          elsif new_obj.respond_to? "request_#{key}"
-            # For read only props, they won't have "configure" method defined,
-            # we can still set them directly during this creation.
-            new_obj.property[key] = value
-            response[key] = value
+        msg_props.each do |key, value|
+          if new_obj.respond_to? "request_#{key}"
+            response[key] = new_obj.__send__("request_#{key}")
+          elsif new_obj.respond_to? key
+            response[key] = new_obj.__send__(key)
           end
         end
 
-        response[:hrn] = new_obj.hrn
-        response[:uid] = new_obj.uid
-        response[:type] = new_obj.type
 				if (cred = new_obj.certificate)
           response[:cert] = cred.to_pem_compact
         end
-
-        new_obj.after_initial_configured if new_obj.respond_to? :after_initial_configured
-
         # self here is the parent
         self.inform(:creation_ok, response)
       rescue  => ex
@@ -418,6 +466,11 @@ class OmfRc::ResourceProxy::AbstractResource
     end)
   end
 
+  # FRCP CONFIGURE message handler
+  #
+  # @param [OmfCommon::Message] message FRCP message
+  # @param [OmfRc::ResourceProxy::AbstractResource] obj resource object
+  # @param [OmfCommon::Message] response initialised FRCP INFORM message object
   def handle_configure_message(message, obj, response)
     message.each_property do |key, value|
       method_name =  "#{message.operation.to_s}_#{key}"
@@ -426,6 +479,11 @@ class OmfRc::ResourceProxy::AbstractResource
     end
   end
 
+  # FRCP REQUEST message handler
+  #
+  # @param [OmfCommon::Message] message FRCP message
+  # @param [OmfRc::ResourceProxy::AbstractResource] obj resource object
+  # @param [OmfCommon::Message] response initialised FRCP INFORM message object
   def handle_request_message(message, obj, response)
     request_props = if message.has_properties?
                       message.properties.keys.map(&:to_sym) & obj.request_available_properties.request
@@ -439,10 +497,13 @@ class OmfRc::ResourceProxy::AbstractResource
       value = obj.__send__(method_name)
       response[p_name] = value if value
     end
-
-    response
   end
 
+  # FRCP RELEASE message handler
+  #
+  # @param [OmfCommon::Message] message FRCP message
+  # @param [OmfRc::ResourceProxy::AbstractResource] obj resource object
+  # @param [OmfCommon::Message] response initialised FRCP INFORM message object
   def handle_release_message(message, obj, response)
     res_id = message.res_id
     released_obj = obj.release(res_id)
@@ -461,6 +522,15 @@ class OmfRc::ResourceProxy::AbstractResource
   # @param [String] topic Name of topic to send it. :ALL means to uid as well s all members
   #
   def inform(itype, inform_data, topic = nil)
+    inform_data = inform_data.dup # better make a copy
+    unless address = resource_address
+      OmfCommon.eventloop.after(1) do
+        # try again in a bit and see if address has been set by then
+        inform(itype, inform_data, topic = nil)
+      end
+      warn "INFORM message delayed as resource's address is not known yet"
+      return
+    end
     if topic == :ALL
       inform(itype, inform_data)
       membership_topics.each {|m| inform(itype, inform_data, m[1])}
@@ -472,7 +542,7 @@ class OmfRc::ResourceProxy::AbstractResource
       inform_data = Hashie::Mash.new(inform_data) if inform_data.class == Hash
       #idata = inform_data.dup
       idata = {
-        src: @topics.first.address,
+        src: address,
         type: self.type  # NOTE: Should we add the object's type as well???
       }
       message = OmfCommon::Message.create_inform_message(itype.to_s.upcase, inform_data, idata)
@@ -508,13 +578,18 @@ class OmfRc::ResourceProxy::AbstractResource
   end
 
   # Return a hash describing a reference to this object
-  def to_hash(options={})
+  #
+  # @return [Hash]
+  def to_hash
     { uid: @uid, address: resource_address() }
   end
 
   private
 
-  # Find resource object based on topic name
+  # To deal with FRCP messages published to a group topic, we need to find out what resources belongs to that topic.
+  #
+  # @param [String] name of the topic
+  # @return [Array<OmfRc::ResourceProxy::AbstractResource>]
   def objects_by_topic(name)
     if name == uid || membership.include?(name)
       objs = [self]
@@ -523,10 +598,18 @@ class OmfRc::ResourceProxy::AbstractResource
     end
   end
 
+  # Retrieve replyto address
+  #
+  # @param [OmfRc::ResourceProxy::AbstractResource] obj resource object
+  # @param [String] replyto address where reply should send to
   def replyto_address(obj, replyto = nil)
     replyto || obj.uid
   end
 
+  # Checking if current object met the condition set by message guard section
+  #
+  # @param [OmfCommon::Message] message FRCP message
+  # @return [Boolean]
   def check_guard(message)
     guard = message.guard
 
@@ -543,4 +626,22 @@ class OmfRc::ResourceProxy::AbstractResource
       end
     end
   end
+
+  # Used for setting properties came with FRCP CREATE message.
+  #
+  # @param [OmfRc::ResourceProxy::AbstractResource] res_ctx resource object it applies to
+  # @param [Hash] props a set of key value pair of properties configuration
+  def init_configure(res_ctx, props)
+    props.each do |key, value|
+      if res_ctx.respond_to? "configure_#{key}"
+        res_ctx.__send__("configure_#{key}", value)
+      elsif res_ctx.respond_to? "initialise_#{key}"
+        # For read only props, they won't have "configure" method defined,
+        # we can still set them directly during this creation.
+        res_ctx.__send__("initialise_#{key}", value)
+      end
+    end
+
+    call_hook(:after_initial_configured, res_ctx)
+  end
 end