rsence 2.0.0.10.pre → 2.0.0.11

data/lib/plugins/plugin_base.rb

@@ -0,0 +1,162 @@
+##   RSence
+ #   Copyright 2010 Riassence Inc.
+ #   http://riassence.com/
+ #
+ #   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
+  
+  
+  module Plugins
+    
+    # This module contains common functionality included in the {Plugin__ Plugin}, {GUIPlugin__ GUIPlugin} and the {Servlet__ Servlet} base classes.
+    #
+    # = Extension hooks for server events
+    # These methods are provided as the basic server event hooks:
+    # * {#init +#init+} -- Use instead of +initialize+
+    # * {#open +#open+} -- Extend to open objects
+    # * {#flush +#flush+} -- Extend to write the state and to flush buffers
+    # * {#close +#close+} -- Extend to close objects
+    #
+    # = Utility methods
+    # These are general utility methods not intended to be extended.
+    # * {#file_read +#file_read+} Use to read files
+    # * {#yaml_read +#yaml_read+} Use to read yaml data
+    # * {#file_write +#file_write+} Use to write files
+    # * {#bundle_path +#bundle_path+} Use for plugin bundle -specific paths
+    # * {#httime +#httime+} Use for HTTP date/time
+    #
+    # = See also
+    # * {file:PluginBundles Plugin Bundles} -- General information about the plugin bundle system
+    # * {Plugin__ Plugin} -- The Plugin base class
+    # * {Servlet__ Servlet} -- The Servlet base class
+    # * {GUIPlugin__ GUIPlugin} -- The GUIPlugin base class
+    module PluginBase
+      
+      # @private External accessor for @plugins
+      # @return [PluginManager] The PluginManager the instance belongs to.
+      attr_reader :plugins
+      
+      # Extend this method do any initial configuration instead of extending the +initialize+ constructor, which should *never* be done in plugins.
+      #
+      # It is called by the {PluginManager#register_bundle PluginManager} when the plugin has been constructed and registered.
+      #
+      # @return [nil]
+      def init
+      end
+      
+      # Extend to open objects like streams and database connections.
+      #
+      # It is called by the {PluginManager#update_bundles! PluginManager} after the {#init} method, when everything is constructed after all plugins are loaded.
+      #
+      # @return [nil]
+      def open
+      end
+      
+      # Extend to save your plugin state, write or flush any data that needs to be stored.
+      #
+      # It is called by the {PluginManager#unload_bundle PluginManager} before {#close}, but doesn't always mean a +close+ event is imminent.
+      #
+      # @return [nil]
+      def flush
+      end
+      
+      # Extend to close objects like streams and database connections.
+      #
+      # It is called by the {PluginManager#unload_bundle PluginManager} when the plugin is about to be destructed, so don't expect any events after it has been called.
+      #
+      # @return [nil]
+      def close
+      end
+      
+      # File reader utility
+      #
+      # Reads the contents of the file given in the +path+.
+      #
+      # @param [String] path The +path+ is relative to the bundle path by default, unless it starts with '/' or '..'; it's simply processed by {#bundle_path} before reading the file.
+      #
+      # @return [false] If there is no file, returns +false+
+      # @return [String] The contents of the file.
+      def file_read( path )
+        path = bundle_path( path )
+        return false unless File.exist?( path )
+        return File.read( path )
+      end
+      
+      # YAML reader utility
+      #
+      # Reads the contents of the YAML file given in the +path+ and returns as a parsed structure of the contents of the file.
+      #
+      # @param [String] path The +path+ is relative to the bundle path by default, unless it starts with '/' or '..'; it's simply processed by {#bundle_path} before reading the file.
+      #
+      # @return [false] If the is no file, returns +false+
+      # @return [Object] Any valid structure defined by the YAML file, parsed to a Ruby object.
+      def yaml_read( path )
+        file_data = file_read( path )
+        if not file_data
+          return false
+        else
+          return YAML.load( file_data )
+        end
+      end
+      
+      # Flie writer utility.
+      #
+      # Writes the contents of the +data+ into the file given in the +path+.
+      # @param [String] path The +path+ is relative to the bundle path by default, unless it starts with '/' or '..'; it's simply processed by {#bundle_path} before writing the file.
+      # @param [#to_s] data The data to write.
+      #
+      # @return [true,false] A success code of the operation (+false+ for failure and +true+ for success).
+      def file_write( path, data )
+        path = bundle_path( path )
+        begin
+          datafile = File.open( path, 'wb' )
+          datafile.write( data.to_s )
+          datafile.close
+          return true
+        rescue => e
+          warn "file_write error for path #{path} #{e}"
+          return false
+        end
+      end
+      alias file_save file_write
+      
+      # Path utility
+      #
+      # Makes a full, absolute path using the plugin bundle as the default path when a relative path is given. Returns just the bundle's local path, if no parameters given.
+      # 
+      # @param [String, false] path The path is relative to the bundle path by default, unless it starts with '/' or '..'.
+      # @param [String, false] prefix Alternative root path if +path+ is specified as a relative path.
+      # @param [String, false] suffix The file suffix, like the the extension.
+      #
+      # @return [String] Full absolute path.
+      def bundle_path( path=false, prefix=false, suffix=false )
+        return @path if not path
+        if suffix
+          path = "#{path}#{suffix}" unless path.end_with?(suffix)
+        end
+        if prefix
+          path = File.join( prefix, path )
+        end
+        path = File.expand_path( path, @path )
+        return path
+      end
+      
+      # Utility for returning the time in the HTTP RFC specification format, like:
+      #   !!!text
+      #   Sun, 04 Jul 2010 06:20:53 EEST
+      #
+      # @param [Time, false] time An Time object to format. Uses the current date/time by default.
+      #
+      # @return [String] The date/time formatted according to the HTTP RFC specification.
+      def httime(time=false)
+        time = Time.new unless time 
+        return time.gmtime.strftime('%a, %d %b %Y %H:%M:%S %Z')
+      end
+      
+    end
+  end
+end

data/lib/plugins/plugin_plugins.rb

@@ -6,65 +6,71 @@
  #   with this software package. If not, contact licensing@riassence.com
  ##
 
-module ::RSence
+
+module RSence
+  
+  
   module Plugins
     
-    # Interface to enable plugins under a plugin.
-    # Just include this in your subclass of Plugin.
-    # The plugins loaded using this system are isolated from other plugins.
-    # To address them from this plugin, use @plugin_plugins instead of
-    # @plugins to address them.
+    
+    # Include this module in your subclass of {Plugin__ Plugin} to enable sub-plugin bundles in another plugin bundle.
+    #
+    # The plugins loaded using this system are isolated from system-wide plugins.
+    #
+    # To address them from this plugin, use +@plugin_plugins+ instead of +@plugins+ to access them.
+    #
+    # Install your sub-plugins into a directory named +plugins+ inside your plugin bundle.
     module PluginPlugins
       
-      # Extended init, delegates calls to the sub-plugins.
+      # Extended {#init}, delegates calls to the sub-plugins.
       def init
         super
         @plugin_plugins = RSence::PluginManager.new( [ bundle_path('plugins') ] )
       end
       
-      # Extended open, delegates calls to the sub-plugins.
+      # Extended {#open}, delegates calls to the sub-plugins.
       def open
         super
         @plugin_plugins.delegate(:open)
       end
       
-      # Extended close, delegates calls to the sub-plugins.
+      # Extended {#close}, delegates calls to the sub-plugins.
       def close
         super
         @plugin_plugins.delegate(:close)
       end
       
-      # Extended flush, delegates calls to the sub-plugins.
+      # Extended {#flush}, delegates calls to the sub-plugins.
       def flush
         super
         @plugin_plugins.delegate(:flush)
       end
       
-      # Extended idle, delegates calls to the sub-plugins.
+      # Extended {#idle}, delegates calls to the sub-plugins.
       def idle( msg )
         super
         @plugin_plugins.delegate(:idle,msg)
       end
       
-      # Extended init_ses, delegates calls to the sub-plugins.
+      # Extended {#init_ses}, delegates calls to the sub-plugins.
       def init_ses( msg )
         super
         @plugin_plugins.delegate(:init_ses,msg)
       end
       
-      # Extended restore_ses, delegates calls to the sub-plugins.
+      # Extended {#restore_ses}, delegates calls to the sub-plugins.
       def restore_ses( msg )
         super
         @plugin_plugins.delegate(:restore_ses,msg)
       end
       
-      # Extended cloned_target, delegates calls to the sub-plugins.
+      # Extended {#cloned_target}, delegates calls to the sub-plugins.
       def cloned_target( msg, source_session )
         super
         @plugin_plugins.delegate(:cloned_target,msg,source_session)
       end
       
-      # Extended cloned_source, delegates calls to the sub-plugins.
+      # Extended {#cloned_source}, delegates calls to the sub-plugins.
       def cloned_source( msg, target_session )
         super
         @plugin_plugins.delegate(:cloned_source,msg,target_session)

data/lib/plugins/plugin_sqlite_db.rb

@@ -6,16 +6,26 @@
  #   with this software package. If not, contact licensing@riassence.com
  ##
 
-module ::RSence
+
+module RSence
+  
+  
   module Plugins
-    # Include this module in your plugin class to automatically
-    # create and connect/disconnect an sqlite database.
-    # The plugin instance will have a @db Sequel object referring
-    # to the sqlite database automatically created
+    
+    
+    # Include this module in your plugin class to automatically create, update and connect/disconnect a sqlite database file.
+    #
+    # The Plugin instances including this module will have a +@db+ Sequel[http://sequel.rubyforge.org/] object referring to the sqlite database automatically created.
+    #
     module PluginSqliteDB
       
-      # First calls superclass, then creates database if it doesn't exist.
-      # Then calls init_db_tables.
+      # Extends {Plugin__#init Plugin#init} to specify +@db_path+ as the name of the bundle with a +.db+ suffix in the project environment +db+ path.
+      #
+      # Calls {#create_db_tables} (extend with your own method), if no database is found (typically on the first run in an environment)
+      #
+      # @example If your plugin bundle is named +my_app+, a +db/my_app.db+ database is created under your project environment.
+      #
+      # @return [nil]
       def init
         super
         db_dir = File.join( RSence.args[:env_path], 'db' )
@@ -27,43 +37,58 @@ module ::RSence
         end
       end
       
-      # Automatically opens the database connection, then calls update_db.
+      # Extends {PluginBase#open PluginBase#open} to open the sqlite database from +@db_path+ as a +@db+ instance variable.
+      #
+      # Calls {#update_db} (extend with your own method) after the database object is created.
+      #
+      # @return [nil]
       def open
         @db = Sequel.sqlite( @db_path )
         update_db
         super
       end
       
-      # Automatically closes (disconnects) the database. Calls flush_db before closing.
+      # Extends {PluginBase#close PluginBase#close} to close (disconnect) the database object.
+      #
+      # Calls {#flush_db} (extend with your own method) before closing the database object.
+      #
+      # @return [nil]
       def close
         flush_db
         @db.disconnect
         super
       end
       
-      # Extend this method to do something immediately after the @db object is assigned.
+      # Extend this method to do something immediately after the +@db+ object is created.
+      #
       # An usage scenario would be updating some tables or deleting some junk rows.
+      #
+      # @return [nil]
       def update_db
       end
       
-      # Extend this method to do something immediately before the @db object is disconnected.
+      # Extend this method to do something immediately before the +@db+ object is disconnected.
+      #
       # An usage scenario would be deleting some junk rows or writing some pending data in memory into the database.
+      #
+      # @return [nil]
       def flush_db
       end
       
       # Extend this method to define tables or initial data for the tables.
       # It's called once, when the database is created.
       #
-      # NOTE: In a future reversion, tables might be defined from a configuration file.
-      #
-      # = Usage:
-      #   @db.create_table :my_table do
-      #     primary_key :id
-      #     String :my_text_column
+      # @example Creates a table named +:my_table+ and inserts one row.
+      #   def create_db_tables
+      #     @db.create_table :my_table do
+      #       primary_key :id
+      #       String :my_text_column
+      #     end
+      #     my_table = @db[:my_table]
+      #     my_table.insert(:my_text_column => 'Some text')
       #   end
-      #   my_table = @db[:my_table]
-      #   my_table.insert(:my_text_column => 'Some text')
-      # 
+      #
+      # @return [nil]
       def create_db_tables
       end
       

data/lib/plugins/pluginmanager.rb

@@ -5,18 +5,19 @@
  #   You should have received a copy of the GNU General Public License along
  #   with this software package. If not, contact licensing@riassence.com
  ##
+
+ 
 require 'plugins/plugins'
 require 'plugins/dependencies'
 
 module RSence
   
-  ## = Abstract
   ## PluginManager is the service that loads and provides method delegation
   ## amongst its plugin bundles.
   ##
   ## = Usage
-  ## plugin_paths = [ 'plugins', '/home/me/rsence/plugins' ]
-  ## myPluginManager = RSence::PluginManager.new( plugin_paths )
+  ##  plugin_paths = [ 'plugins', '/home/me/rsence/plugins' ]
+  ##  myPluginManager = RSence::PluginManager.new( plugin_paths )
   ##
   class PluginManager
     
@@ -258,7 +259,7 @@ module RSence
         
         # Dependency, by default the system category (built-in plugins).
         # A nil ( "~" in yaml ) value means no dependencies.
-        :depends_on     => :system,
+        :depends_on     => [ :system ],
         
         # Optional, name of category. The built-in plugins are :system
         :category       => nil,
@@ -304,7 +305,7 @@ module RSence
         end
       end
       
-      # Extra information, not overrideable in info.yaml
+      # Extra information, not override-able in info.yaml
       
       # Path of bundle
       info[:path] = bundle_path
@@ -502,16 +503,19 @@ module RSence
         to_unload.push( name ) if not found_map.has_key?( name )
       end
       to_unload.each do |name|
+        next if @deps.category?( name )
         puts "Unloading #{name.inspect}"
         unload_bundle( name )
       end
       to_reload.each do |name|
+        next if @deps.category?( name )
         puts "Unloading #{name.inspect}"
         unload_order = unload_bundle( name )
         to_load += unload_order
       end
       info_map = {}
       to_load.each do |name|
+        next unless found_map.has_key? name
         info_map[name] = bundle_info( *found_map[name] )
       end
       no_deps = {}
@@ -524,6 +528,7 @@ module RSence
       end
       to_open = []
       @deps.list.each do |name|
+        next if @deps.category?( name )
         next unless to_load.include?( name )
         info = info_map[name]
         if to_reload.include?( name )

data/lib/plugins/plugins.rb

@@ -6,8 +6,16 @@
  #   with this software package. If not, contact licensing@riassence.com
  ##
 
-# Contains the PluginUtil module which has common methods for the bundle classes
-require 'plugins/plugin_util'
+
+module RSence
+  
+  # Namespace for plugin classes and modules
+  module Plugins
+  end
+end
+
+# Contains the PluginBase module which has common methods for the bundle classes
+require 'plugins/plugin_base'
 
 # guiparser.rb contains the Yaml serializer for gui trees.
 # It uses JSONRenderer on the client to build user interfaces.
@@ -20,15 +28,22 @@ require 'plugins/plugin_sqlite_db'
 # Interface for plugins in a plugin bundle
 require 'plugins/plugin_plugins'
 
-module ::RSence
+
+# Templates for the main plugin classes.
+require 'plugins/plugin'
+require 'plugins/gui_plugin'
+require 'plugins/servlet'
+
+
+module RSence
+  
   module Plugins
     
-    require 'plugins/plugin'
-    
-    # The PluginMaker mimic class creates the Plugin class from PluginTemplate
-    def self.PluginMaker
+    # Creates the runtime Plugin class from Plugin__
+    # @return [Plugin__]
+    def self.Plugin
       lambda do |ns|
-        klass = Class.new( PluginTemplate ) do
+        klass = Class.new( Plugin__ ) do
           def self.ns=(ns)
             define_method( :bundle_info ) do
               ns.bundle_info
@@ -40,12 +55,12 @@ module ::RSence
       end
     end
     
-    require 'plugins/gui_plugin'
     
-    # The GUIPluginMaker mimic class creates the GUIPlugin class from GUIPluginTemplate
-    def self.GUIPluginMaker
+    # Creates the runtime GUIPlugin class from GUIPlugin__
+    # @return [GUIPlugin__]
+    def self.GUIPlugin
       lambda do |ns|
-        klass = Class.new( GUIPluginTemplate ) do
+        klass = Class.new( GUIPlugin__ ) do
           def self.ns=(ns)
             define_method( :bundle_info ) do
               ns.bundle_info
@@ -57,12 +72,12 @@ module ::RSence
       end
     end
     
-    require 'plugins/servlet'
     
-    # The ServletMaker mimic class creates the Servlet class from ServletTemplate
-    def self.ServletMaker
+    # Creates the runtime Servlet class from Servlet__
+    # @return [Servlet__]
+    def self.Servlet
       lambda do |ns|
-        klass = Class.new( ServletTemplate ) do
+        klass = Class.new( Servlet__ ) do
           def self.ns=(ns)
             define_method( :bundle_info ) do
               ns.bundle_info
@@ -74,31 +89,48 @@ module ::RSence
       end
     end
     
-    # Loads bundle according to the +params+ hash.
-    # Some essential params:
-    #  :src_path    => '/path/of/the_plugin/the_plugin.rb'
-    #  :bundle_path => '/path/of/the_plugin'
-    #  :bundle_name => :the_plugin
+    # Loads bundle in an anonymous module with special environment options.
+    # @param [Hash] params
+    # @option params [String] :src_path ('/path/of/the_plugin/the_plugin.rb') The ruby source file to read.
+    # @option params [String] :bundle_path ('/path/of/the_plugin') The plugin bundle directory path.
+    # @option params [String] :bundle_name (:the_plugin) The name of the plugin as it will be registered.
+    # @return [Module] Isolated, anonymous module containing the evaluated source code of +src_path+
     def self.bundle_loader( params )
-      src_path = params[:src_path]
       begin
         mod = Module.new do |m|
           if RUBY_VERSION.to_f >= 1.9
-            m.define_singleton_method( :bundle_path ) do
-              params[:bundle_path]
+            m.define_singleton_method( :_bundle_path ) do
+              params[ :bundle_path ]
+            end
+          else
+            m.module_eval( <<-END
+            def self._bundle_path; #{params[:bundle_path].inspect}; end
+            END
+            )
+          end
+          
+          # Makes a full path using the plugin bundle as the 'local path'.
+          # The (optional) +prefix+ is a subdirectory in the bundle,
+          # the +suffix+ is the file extension.
+          def self.bundle_path( path=false, prefix=false, suffix=false )
+            return _bundle_path if not path
+            if suffix
+              path = "#{path}#{suffix}" unless path.end_with?(suffix)
+            end
+            if prefix
+              path = File.join( prefix, path )
             end
+            path = File.expand_path( path, _bundle_path )
+            return path
           end
           def self.inspect; "#<module BundleWrapper of #{@@bundle_name}}>"; end
           def self.const_missing( name )
             if name == :Servlet
-              return Plugins.ServletMaker.call( self )
-            elsif name == :ServletPlugin
-              warn "'ServletPlugin' is deprecated, use 'Servlet' instead."
-              return Plugins.ServletMaker.call( self )
+              return Plugins.Servlet.call( self )
             elsif name == :Plugin
-              return Plugins.PluginMaker.call( self )
+              return Plugins.Plugin.call( self )
             elsif name == :GUIPlugin
-              return Plugins.GUIPluginMaker.call( self )
+              return Plugins.GUIPlugin.call( self )
             else
               warn "Known const missing: #{name.inspect}"
               super
@@ -106,12 +138,14 @@ module ::RSence
           end
           plugin_src = params[:src]
           unless RUBY_VERSION.to_f >= 1.9
-            plugin_src = "bundle_path = #{params[:bundle_path].inspect}\n\n" + plugin_src
+            plugin_src = "_bundle_path = #{params[:bundle_path].inspect};" + plugin_src
           end
           m.module_eval( plugin_src )
         end
         return mod
       rescue => e
+        src_path = params[:src_path]
+        src_path = "<undefined src_path>" if src_path == nil
         params[:plugin_manager].plugin_error(
           e,
           'BundleLoaderError',