rsence 2.0.0.10.pre → 2.0.0.11

data/lib/daemon/daemon.rb

@@ -1,4 +1,3 @@
-#--
 ##   RSence
  #   Copyright 2008 Riassence Inc.
  #   http://riassence.com/
@@ -6,7 +5,7 @@
  #   You should have received a copy of the GNU General Public License along
  #   with this software package. If not, contact licensing@riassence.com
  ##
- #++
+
 
 # Use rubygems to load rack
 require 'rubygems'
@@ -14,22 +13,23 @@ require 'rubygems'
 # Transporter is the top-level handler for calls coming from the javascript COMM.Transporter.
 require 'transporter/transporter'
 
-## Broker routes requests to the correct handler
+# Broker routes requests to the correct handler
 require 'http/broker'
 
 
-module ::RSence
+module RSence
   
+  # @private  The process id of the launch process (usually the PID of the 'rsence' command)
   @@launch_pid = Process.pid
   
-  # Returns the pid of the process when starting up.
-  # PID is different for the forked child process(es)
+  # @private  Returns the pid of the process when starting up.
+  #   PID is different for the forked child process or processes
   def self.launch_pid
     return @@launch_pid
   end
 
-  # The Controller module handles the damonizing
-  # operations of the process referred to as +daemon+
+  # @private  The Controller module handles the daemonizing
+  #   operations of the process referred to as +daemon+
   module Daemon
   
     # Writes the process id to disk, the pid_fn method of the daemon contains
@@ -254,7 +254,7 @@ module ::RSence
   
   end
 
-  # Simple process control, constructed here and called from Daemon::Controller
+  # @private  Simple process control, constructed here and called from Daemon::Controller
   class HTTPDaemon
   
     # RSence top-level run handler. Almost identical to start.

data/lib/daemon/sigcomm.rb

@@ -1,4 +1,3 @@
-#--
 ##   RSence
  #   Copyright 2010 Riassence Inc.
  #   http://riassence.com/
@@ -6,12 +5,13 @@
  #   You should have received a copy of the GNU General Public License along
  #   with this software package. If not, contact licensing@riassence.com
  ##
- #++
 
-# RSence async signal communication handler, uses temporary files for communication.
-# Utilized by ARGVParser and Daemon.
+
 
 module RSence
+  
+  # @private RSence async signal communication handler, uses temporary files for communication.
+  #   Utilized by ARGVParser and Daemon.
   module SIGComm
     def self.delete_signal_response( pid_fn )
       sig_fn = pid_fn+'.response.'+signal

data/lib/http/broker.rb

@@ -1,4 +1,3 @@
-#--
 ##   RSence
  #   Copyright 2008 Riassence Inc.
  #   http://riassence.com/
@@ -6,11 +5,6 @@
  #   You should have received a copy of the GNU General Public License along
  #   with this software package. If not, contact licensing@riassence.com
  ##
- #++
-
-
-
-module RSence
 
 require 'rubygems'
 require 'rack'
@@ -21,12 +15,17 @@ require 'http/response'
 ## Minimally WEBrick -compatible request object
 require 'http/request'
 
-# Broker routes requests to the proper request processing instance.
-# It's the top-level http handler.
+
+module RSence
+
+
+# Broker sets up Rack and routes requests to the proper request processing instance.
 class Broker
   
-  # This method is called from Rack. The env is the Rack environment.
-  def call(env)
+  # This method is called from Rack.
+  # @param [Hash] env is the Rack environment.
+  # @return [Array(Number, Hash, String)] Rack-style response status, header, body
+  def call( env )
     sleep @@ping_sim if @@ping_sim
     unless @@transporter.online?
       puts "#{Time.now.strftime('%Y-%m-%d %H:%M:%S')} -- Server busy."
@@ -50,10 +49,9 @@ class Broker
   
   # Returns a dynamically created "REST Dispatcher" kind of class that has
   # request and response as instance variables and the rest of the Broker
-  # class as the superclass.
-  # It calls the method according to the http method.
-  # Called from #call
-  # Broker currently implements only get and post methods.
+  # class as the superclass. It calls the method according to the http method. Called from {#call}
+  # Broker currently implements only the {#get} and {#post} methods.
+  # @return [Broker] An instance of Broker with a {Request} instance as +@request+ and a {Response} instance as +@response+
   def dispatcher_class
     @dispatcher ||= Class.new(self.class) do
       attr_accessor :content_type
@@ -64,13 +62,14 @@ class Broker
     end
   end
   
-  # This method is used to create the Rack instance
-  # and set up itself accordingly.
-  # The transporter parameter is an instance of the Transporter class,
-  # which does all the actual delegation.
-  # The conf parameter contains a hash with at least the following:
-  #  :bind_address, :port, :rack_require
-  def self.start( transporter, conf )
+  # Creates the Rack instance and set up itself accordingly.
+  #
+  # @param [Transporter] transporter The single {Transporter} instance initialized by {HTTPDaemon}
+  # @param [Hash{Symbol => String}] conf Rack initialization settings
+  # @option conf [String] :bind_address ('127.0.0.1') The TCP/IP address or mask to bind to.
+  # @option conf [#to_i] :port ('8001') The TCP port to bind to.
+  # @option conf [String] :rack_require ('mongrel') The Rack handler to use.
+  def self.start( transporter, conf = {:bind_address => '127.0.0.1', :port => '8001', :rack_require => 'mongrel'} )
     
     host = conf[:bind_address]
     port = conf[:port]
@@ -115,21 +114,25 @@ class Broker
     
   end
   
+=begin
+  # Extends the receiver with SingletonMethods
   def self.included( receiver )
     receiver.extend( SingletonMethods )
   end
+=end
+  
   
-  # Generic 404 handler
+  # Generic 404 error handler. Just sets up response status, headers, body as a small "Page Not Found" html page
   def not_found
     puts "/404: #{@request.fullpath.inspect}" if RSence.args[:verbose]
     @response.status = 404
     err404 = '<html><head><title>404 - Page Not Found</title></head><body>404 - Page Not Found</body></html>'
-    @response['content-type'] = 'text/html; charset=UTF-8'
-    @response['content-length'] = err404.length.to_s
+    @response['Content-Type'] = 'text/html; charset=UTF-8'
+    @response['Content-Length'] = err404.length.to_s
     @response.body = err404
   end
   
-  ## Post requests are always xhr requests
+  # Routes POST requests to {Transporter#servlet}
   def post
     
     puts "post: #{@request.fullpath}" if RSence.args[:verbose]
@@ -138,7 +141,7 @@ class Broker
     
   end
   
-  ## Get requests are different, depending on the uri requested
+  # Routes GET requests to {Transporter#servlet}
   def get
     
     puts "get: #{@request.fullpath}" if RSence.args[:verbose]
@@ -147,7 +150,7 @@ class Broker
     
   end
   
-  ### -- Add more http methods here when we have some apps to test with, caldav implementation maybe? ++
+  ### -- Add more http methods here when we have some apps to test with CalDAV implementation maybe? ++
   
 end
 

data/lib/http/rackup.rb

@@ -1,4 +1,3 @@
-#--
 ##   RSence
  #   Copyright 2008 Riassence Inc.
  #   http://riassence.com/
@@ -6,7 +5,7 @@
  #   You should have received a copy of the GNU General Public License along
  #   with this software package. If not, contact licensing@riassence.com
  ##
- #++
+
 
 warn "Current RSence rackup Broker implementation does not work."
 warn "Please try again in a future revision."
@@ -47,7 +46,7 @@ module Broker
   @@transporter = Transporter.new
   
   def self.start
-    conf = ::RSence.config[:http_server][:latency]
+    conf = RSence.config[:http_server][:latency]
     if conf == 0
       @@ping_sim = false
     else

data/lib/http/request.rb

@@ -1,4 +1,3 @@
-#--
 ##   RSence
  #   Copyright 2008 Riassence Inc.
  #   http://riassence.com/
@@ -6,7 +5,7 @@
  #   You should have received a copy of the GNU General Public License along
  #   with this software package. If not, contact licensing@riassence.com
  ##
- #++
+
 
 
 require 'rubygems'

data/lib/http/response.rb

@@ -1,4 +1,3 @@
-#--
 ##   RSence
  #   Copyright 2008 Riassence Inc.
  #   http://riassence.com/
@@ -6,22 +5,23 @@
  #   You should have received a copy of the GNU General Public License along
  #   with this software package. If not, contact licensing@riassence.com
  ##
- #++
+
 
 
 module RSence
   
-  # Simply adds the + method "operator" to an extended Array.
-  # Used for pushing http body data.
-  class ResponseBody < Array
-    def +(body_data)
-      self.push(body_data)
-    end
-  end
-
   # Classic WEBrick -compatible Response object for Rack.
   # Implements only the methods used by the framework.
   class Response
+    
+    # Adds the + method "operator" to an extended Array.
+    # Used for pushing http body data.
+    class ResponseBody < Array
+      def +(body_data)
+        self.push(body_data)
+      end
+    end
+
     def initialize
       @body = ResponseBody.new(1)
       @body[0] = ''

data/lib/plugins/dependencies.rb

@@ -6,6 +6,7 @@
  #   with this software package. If not, contact licensing@riassence.com
  ##
 
+
 module RSence
   
   # = Description:
@@ -126,7 +127,7 @@ module RSence
     # List of categories
     attr_reader :categories
     
-    # Adds the gategory +name+.
+    # Adds the category +name+.
     def add_category( name )
       @categories.push( name ) unless @categories.include?( name )
     end

data/lib/plugins/gui_plugin.rb

@@ -6,32 +6,31 @@
  #   with this software package. If not, contact licensing@riassence.com
  ##
 
-module ::RSence
+
+module RSence
   module Plugins
     
-    ## The GUIPlugin extends Plugin by automatically initializing an GUIParser
-    ## instance as @gui
-    ## It makes the include_js method public to enable automatic dependency
-    ## loading based on the dependencies item in the YAML gui declaration.
-    ## It also makes the @path public.
-    ## It inits the gui automatically.
-    ## Extend the gui_params method to define your own params for the gui data.
-    ##
-    ## HValues can be defined inside values.yaml at the root directory of
-    ## plugin. The HValues may be linked directly with methods on the values.yaml
-    ## as well.
-    ##
-    ## == Values.yaml
-    ## :valuename:    # name of the HValue
-    ##  :value: 2.56  # defined value
-    ##  :responders:  # methods responding to the value on ruby code upon change
-    ##    - :method: validate_convert_factor
-    ##
-    ##
-    ##
-    class GUIPluginTemplate < PluginTemplate
+    # The CUIPlugin__ is actually available as +GUIPlugin+ from plugin bundle code using the {RSence::Plugins::GUIPlugin} class mimic method.
+    #
+    # GUIPlugin extends {Plugin__ Plugin} by automatically initializing an {GUIParser} instance as +@gui+.
+    #
+    # Read {Plugin__ Plugin} for usage of the API, {file:ExampleGuiPlugin Example GUIPlugin} for an example of use and {file:PluginBundles Plugin Bundles} for overall information about plugin bundle usage.
+    #
+    # * It implements automatic dependency loading based on the dependencies item in the YAML gui declaration.
+    # * It inits the gui automatically.
+    #
+    # = User Interface -related hooks:
+    # * {#init_ui +#init_ui+} -- Extend to implement logic when the {MainPlugin} plugin has started the client. The {GUIPlugin__ +GUIPlugin+} class extends this method to automatically load and initialize the user interface from a +GUITree+ data structure defined in the +gui/main.yaml+ document in the bundle directory.
+    # * {#gui_params +#gui_params+} -- Extend to define your own params for the gui data.
+    #
+    class GUIPlugin__ < Plugin__
+      
+      # @private Class type identifier for the PluginManager.
+      # @return [:GUIPlugin]
       def self.bundle_type; :GUIPlugin; end
-  
+      
+      
+      # @private Placeholder for actual gui yaml file.
       @@default_yaml_src = <<-END
 type: GUITree
 version: 0.6
@@ -41,8 +40,10 @@ options:
   label: "Dummy Application"
 
       END
-  
-      # Automatically initializes an GUIParser instance as @gui
+      
+      # In addition to {Plugin__#init Plugin#init}, also automatically initializes a {GUIParser} instance as +@gui+
+      #
+      # @return [nil]
       def init
         super
         yaml_src = file_read( "gui/#{@name}.yaml" )
@@ -52,16 +53,36 @@ options:
         @client_pkgs = false
       end
   
-      # Extend this method to return custom params to GUIParser#init.
-      # Called from init_ui.
-      # By default assigns the session values as :values to use for 
-      # valueObjId: ":values.my_value_name" in the YAML GUI file.
+      # Extend this method to return custom params to {GUIParser#init}.
+      #
+      # Called from {#init_ui}.
+      #
+      # By default assigns the session values as :values to use for +bind: :values.my_value_name+ in the YAML GUI file for client-side value bindings.
+      #
+      # @param [Message] msg The message is supplied by the system.
+      # 
+      # @return [Hash] Parameters for {GUIParser#init @gui#init}
+      #
+      # @example To provide extra parameters, do this:
+      #   def gui_params( msg )
+      #     params = super
+      #     params[:extra] = {
+      #       :foo => "Foo",       # use in the GUITree as :extra.foo
+      #       :num => 124334,      # use in the GUITree as :extra.num
+      #       :bar => {
+      #         :barbar => "Bar"   # use in the GUITree as :extra.bar.barbar
+      #       }
+      #       :arr => [1,2,4,8]    # use in the GUITree as :extra.arr
+      #     }
+      #     params[:more] = "More" # use in the GUITree as :more
+      #     return params
+      #   end
+      #
       def gui_params( msg )
-        return {
-          :values => @gui.values( get_ses( msg ) )
-        }
+        { :values => @gui.values( get_ses( msg ) ) }
       end
-  
+      
+      # @private Method that implements +client_pkgs.yaml+ loading
       def install_client_pkgs
         if @client_pkgs
           warn "install_client_pkgs: called with @client_pkgs defined; returning"
@@ -82,7 +103,8 @@ options:
           @plugins.client_pkg.rebuild_client
         end
       end
-  
+      
+      # @private Method that implements +client_pkgs.yaml+ unloading
       def uninstall_client_pkgs
         if not @client_pkgs
           warn "uninstall_client_pkgs: called without @client_pkgs defined"
@@ -101,33 +123,38 @@ options:
         end
         @client_pkgs = false
       end
-  
+      
+      # @private calls install_client_pkgs, if a 'client_pkgs.yaml' file is found
       def open
         super
         install_client_pkgs if File.exist? bundle_path( 'client_pkgs.yaml' )
       end
-  
+      
+      # @private calls uninstall_client_pkgs, if a 'client_pkgs.yaml' file was loaded
       def close
         super
         uninstall_client_pkgs if @client_pkgs
       end
-  
-      # Sends gui specification to the main plugin
+      
+      # @private Sends gui specification to the main plugin
       def spec_ui( msg )
         # TODO
       end
-  
-      # Automatically inits the UI using GUIParser#init.
-      # Passes on the return value of gui_params.
-      def init_ui( msg ); @gui.init( msg, gui_params( msg ) ); end
-  
-      # Automatically kills the UI using GUIParser#kill
-      def kill_ui( msg ); @gui.kill( msg ); end
-  
-      # Makes include_js public to enable calls to it from GUIParser
-      public :include_js, :read_js_once
-  
-      attr_reader :plugins
+      
+      # Automatically inits the UI using {GUIParser#init}
+      #
+      # @param [Message] msg The message is supplied by the system.
+      #
+      # @return [nil]
+      def init_ui( msg )
+        @gui.init( msg, gui_params( msg ) )
+      end
+      
+      # @private Automatically kills the UI using {GUIParser#kill}
+      def kill_ui( msg )
+        @gui.kill( msg )
+      end
+      
     end
   end
 end