rsence 2.0.0.0.pre

data/lib/http/request.rb

@@ -0,0 +1,69 @@
+#--
+##   Riassence Framework
+ #   Copyright 2008 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
+ ##
+ #++
+
+
+require 'rubygems'
+require 'rack'
+
+module RSence
+
+class Request < Rack::Request
+  attr_reader :header, :path, :query
+  def initialize(env)
+    @header = {
+      
+    }
+    super
+    env2header()
+    @path = path_info()
+    @query = params()
+  end
+  def unparsed_uri
+    return @header['request-uri']
+  end
+  def env2header
+    [ ['SERVER_NAME',           'server-name'],
+      ['HTTP_USER_AGENT',       'user-agent'],
+      ['HTTP_ACCEPT_ENCODING',  'accept-encoding'],
+      ['PATH_INFO',             'path-info'],
+      ['HTTP_HOST',             'host'],
+      ['HTTP_ACCEPT_LANGUAGE',  'accept-language'],
+      ['SERVER_PROTOCOL',       'server-protocol'],
+      ['REQUEST_PATH',          'request-path'],
+      ['HTTP_KEEP_ALIVE',       'keep-alive'],
+      ['SERVER_SOFTWARE',       'server-software'],
+      ['REMOTE_ADDR',           'remote-addr'],
+      ['HTTP_REFERER',          'referer'],
+      ['HTTP_VERSION',          'version'],
+      ['HTTP_ACCEPT_CHARSET',   'accept-charset'],
+      ['REQUEST_URI',           'request-uri'],
+      ['SERVER_PORT',           'server-port'],
+      ['QUERY_STRING',          'query-string'],
+      ['HTTP_ACCEPT',           'accept'],
+      ['REQUEST_METHOD',        'request-method'],
+      ['HTTP_CONNECTION',       'connection'],
+      ['HTTP_SOAPACTION',       'soapaction'],
+      ['HTTP_FORWARDED_HOST',   'forwarded-host']
+    ].each do |env_key,header_key|
+      if @env.has_key?(env_key)
+        @header[header_key] = @env[env_key]
+      end
+      if env_key.start_with?( 'HTTP_' )
+        x_env_key = "HTTP_X#{env_key[4..-1]}"
+        if @env.has_key?( x_env_key )
+          @header["x-#{header_key}"] = @env[ x_env_key ]
+        end
+      end
+    end
+  end
+end
+
+
+end

data/lib/http/response.rb

@@ -0,0 +1,63 @@
+#--
+##   Riassence Framework
+ #   Copyright 2008 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
+
+class ResponseBody < Array
+  def +(body_data)
+    self.push(body_data)
+  end
+end
+
+## Minimally WEBrick -compatible Response object.
+## Implements only the methods used by the framework.
+class Response
+  def initialize
+    @body = ResponseBody.new(1)
+    @body[0] = ''
+    @status = 200
+    @header = {
+      'Content-Type' => 'text/plain',
+      'Server' => 'Riassence Framework'
+    }
+  end
+  def body=(body_data)
+    @body = ResponseBody.new(1)
+    @body[0] = body_data
+  end
+  def body
+    @body.join
+  end
+  def content_type=(new_content_type)
+    @header['Content-Type'] = new_content_type
+  end
+  def content_type
+    @header['Content-Type']
+  end
+  def camelize( header_key )
+    header_key.capitalize.gsub(/\-([a-z])/) { '-'+$1.upcase }
+  end
+  def []=(header_key,header_val)
+    @header[camelize( header_key )] = header_val.to_s
+  end
+  def status=(new_val)
+    @status = new_val.to_i
+  end
+  def status
+    @status
+  end
+  def header
+    @header
+  end
+end
+
+end
+

data/lib/plugins/gui_plugin.rb

@@ -0,0 +1,129 @@
+##   Riassence Framework
+ #   Copyright 2009 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
+ ##
+
+## 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 GUIPlugin < Plugin
+  
+  @@default_yaml_src = %{
+type: GUITree
+version: 0.5
+
+class: HApplication
+options:
+  label: "Dummy Application"
+}
+  
+  # Automatically initializes an GUIParser instance as @gui
+  def init
+    super
+    yaml_src = file_read( "gui/#{@name}.yaml" )
+    yaml_src = file_read( "gui/main.yaml" ) unless yaml_src
+    yaml_src = @@default_yaml_src unless yaml_src
+    @gui = GUIParser.new( self, yaml_src )
+    @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.
+  def gui_params( msg )
+    return {
+      :values => @gui.values( get_ses( msg ) )
+    }
+  end
+  
+  def install_client_pkgs
+    if @client_pkgs
+      warn "install_client_pkgs: called with @client_pkgs defined; returning"
+      return
+    end
+    @client_pkgs = yaml_read( 'client_pkgs.yaml' )
+    if @client_pkgs
+      if @client_pkgs.has_key?(:src_dirs)
+        @client_pkgs[:src_dirs].each do |src_dir|
+          src_dir = bundle_path( src_dir[2..-1] ) if src_dir.start_with?('./')
+          @plugins.client_pkg.add_src_dir( src_dir )
+        end
+      end
+      @plugins.client_pkg.add_packages(       @client_pkgs[:packages      ] ) if @client_pkgs.has_key?(:packages      )
+      @plugins.client_pkg.add_themes(         @client_pkgs[:theme_names   ] ) if @client_pkgs.has_key?(:theme_names   )
+      @plugins.client_pkg.add_gfx_formats(    @client_pkgs[:gfx_formats   ] ) if @client_pkgs.has_key?(:gfx_formats   )
+      @plugins.client_pkg.add_reserved_names( @client_pkgs[:reserved_names] ) if @client_pkgs.has_key?(:reserved_names)
+      @plugins.client_pkg.rebuild_client
+    end
+  end
+  
+  def uninstall_client_pkgs
+    if not @client_pkgs
+      warn "uninstall_client_pkgs: called without @client_pkgs defined"
+    else
+      if @client_pkgs.has_key?(:src_dirs)
+        @client_pkgs[:src_dirs].each do |src_dir|
+          src_dir = bundle_path( src_dir[2..-1] ) if src_dir.start_with?('./')
+          @plugins.client_pkg.del_src_dir( src_dir )
+        end
+      end
+      @plugins.client_pkg.del_reserved_names( @client_pkgs[:reserved_names] ) if @client_pkgs.has_key?(:reserved_names)
+      @plugins.client_pkg.del_gfx_formats(    @client_pkgs[:gfx_formats   ] ) if @client_pkgs.has_key?(:gfx_formats   )
+      @plugins.client_pkg.del_themes(         @client_pkgs[:theme_names   ] ) if @client_pkgs.has_key?(:theme_names   )
+      @plugins.client_pkg.del_packages(       @client_pkgs[:packages].keys  ) if @client_pkgs.has_key?(:packages      )
+      @plugins.client_pkg.rebuild_client
+    end
+    @client_pkgs = false
+  end
+  
+  def open
+    super
+    install_client_pkgs if File.exist? bundle_path( 'client_pkgs.yaml' )
+  end
+  
+  def close
+    super
+    uninstall_client_pkgs if @client_pkgs
+  end
+  
+  # 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
+  
+end
+
+

data/lib/plugins/guiparser.rb

@@ -0,0 +1,114 @@
+##   Riassence Framework
+ #   Copyright 2009 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
+ ##
+
+# This class automatically loads a YAML file from "gui" subdirectory of a plugin.
+# Extend your plugin from the GUIPlugin class instead of the Plugin class to make
+# this work automatically.
+# = Usage:
+# Initialize like this from inside a plugin method. This will load the "gui/my_gui.yaml" file.
+#   @gui = GUIParser.new( self, 'my_gui' )
+# To make the client render the contents of the yaml do this:
+#   ses = get_ses( msg )
+#   params = { :values => @gui.values( ses ) }
+#   @gui.init( msg, params )
+class GUIParser
+  
+  include ::RSence
+  
+  # Use this method to send the client all commands required to construct the GUI Tree using JSONRenderer.
+  # = Parameters
+  # +msg+::    The +Message+ instance +msg+ used all over the place.
+  # +params+:: An hash containing all parameters referred from the YAML file.
+  def init( msg, params )
+    gui_data = YAML.load( @yaml_src )
+    parse_gui( gui_data, params )
+    if gui_data.has_key?('dependencies')
+      @parent.include_js( msg, gui_data['dependencies'] )
+      gui_data.delete('dependencies')
+    end
+    if gui_data.has_key?('include')
+      gui_data['include'].each do | js_file |
+        js_src = @parent.read_js_once( msg, js_file )
+        msg.reply( js_src )
+      end
+    end
+    gui_name = @parent.name
+    msg.reply( "JSONRenderer.nu(#{gui_data.to_json});", true )
+  end
+  
+  # Use this method to extract all the value id's of the +ses+ hash.
+  def values( ses )
+    ids = {}
+    ses.each do | key, value |
+      if value.class == HValue
+        ids[ key ] = value.val_id
+      end
+    end
+    return ids
+  end
+  
+private
+
+  def json_fun( value )
+    JSON.parse( "[#{value}]" ).first
+  end
+  
+  # Parses the gui data using params. Called from +init+.
+  def parse_gui( gui_data, params )
+    data_class = gui_data.class
+    if data_class == Array
+      gui_data.each_with_index do | item, i |
+        gui_data[i] = parse_gui( item, params )
+      end
+    elsif data_class == Hash
+      gui_data.each do | key, value |
+        gui_data[key] = parse_gui( value, params )
+      end
+    elsif data_class == Symbol
+      sym_str = gui_data.to_s
+      if sym_str.include? '.'
+        sym_arr = sym_str.split('.')
+      else
+        sym_arr = [ sym_str ]
+      end
+      return get_params( sym_arr, params )
+    elsif data_class == String and gui_data.strip.start_with?('function(')
+      return @parent.plugins[:client_pkg].squeeze( "a="+json_fun( gui_data.to_json ) )[2..-1]
+    end
+    return gui_data
+  end
+  
+  # Searches the params hash for parameters whenever encountered a Symbol in the YAML.
+  def get_params( params_path, params )
+    item = params_path.shift
+    if params.class == Hash
+      has_str = params.has_key?( item )
+      has_sym = params.has_key?( item.to_sym )
+      item = item.to_sym if has_sym
+      if has_str or has_sym
+        if params_path.size == 0
+          return params[item]
+        else
+          return get_params( params_path, params[ item ] )
+        end
+      end
+    end
+    return ''
+  end
+  
+  # Loads the YAML file.
+  # = Parameters
+  # +parent+::    The Plugin instance called from, use +self+ when constructing in a Plugin method.
+  # +yaml_src+::  The YAML source template for the GUI
+  def initialize( parent, yaml_src )
+    @parent = parent
+    @yaml_src = yaml_src
+  end
+
+end
+

data/lib/plugins/plugin.rb

@@ -0,0 +1,652 @@
+##   Riassence Framework
+ #   Copyright 2006 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
+ ##
+
+## = Abstract
+## The Plugin class is the base class for extending server logic.
+## A single Plugin instance serves the requests of all sessions,
+## which makes them very cpu and memory efficient compared to systems,
+## where the server classes are constructed and destructed for each
+## request.
+##
+## Plugins are designed to be contained in a plugin directory bundle and
+## to be loaded by the +PluginManager+, which is also responsible for
+## delegating the events and other calls throughout the system.
+##
+## == Anatomy of a plugin bundle
+## The plugin bundle contains all data needed to run the plugin. Design
+## your plugin without any hard-coded paths, remember that it's intended
+## to be deployed by "dropping" the whole plugin into one of the server's
+## plugins directories.
+##
+## The +PluginManager+ looks for such bundles and evaluates them into an
+## anonymous +Module+ namespace. The content of the ruby source file
+## is then responsible for including its libraries, constructing an
+## instance of itself and registering itself as a part of the system.
+##
+## It's advised to use the +GUIPlugin+ class for plugins that handle
+## user interfaces. Usage of the +Plugin+ bundle is advised to use
+## for plugins that provide extra functionality, value responders
+## and other utilities that supplement the user interface.
+##
+## You must call the +#register+ method after the class is constructed.
+## Otherwise, the class is not connected to the system and just discarded
+## and then garbage collected.
+##
+## == Messages
+## As a side effect of having single instances of plugins serve the requests
+## of all sessions, the request/response/session messaging is implemented
+## as messaging objects. These objects contain or delegate all the necessary
+## hooks required by the complete request/response cycle.
+##
+## The naming convention of the +Message+ instance is +msg+ and it's
+## given as the first parameter of methods needing it.
+##
+## Use +msg.ses_id+ to identify the session's serial number and +msg.user_id+
+## to identify the user's identity.
+##
+## Use the +msg.session+ +Hash+ to store any persistent data
+## associated with the user's session, preferably using the name of the
+## plugin or its registered name as the primary key entry in the Hash.
+## The session data is persistent; it's stored in the session database
+## by +SessionStorage+ automatically.
+##
+## The +msg+ instance also provides access to the +Request+ and +Response+
+## objects as +msg.request+ and +msg.response+, respectively.
+##
+## Use the +msg.run+ method to call other plugins.
+##
+## To append js source code to be evaluated in the client, use the +msg.reply+
+## call. The +msg.console+ call appends messages to the browser's js console.
+##
+##
+## == Session -related event methods
+## The +#get_ses+ method returns (or creates and returns) the entry in
+## the session based on the name your plugin is registered as. It's advised
+## to use this call instead of manually managing +msg.session+ in most cases.
+##
+## The +#idle+ method is called each time a client performs a data
+## synchronization or "idle poll" request.
+##
+## The +#init_ses+ method is called once in the same request a new session
+## is created. A new session is created, when a user enters accesses the
+## server the first time, or the first time after the previous session is 
+## expired.
+##
+## The +#init_ui+ method is called by the "main" plugin after the client has
+## booted successfully. The +GUIPlugin+ class extends this method to
+## automatically load and initialize the user interface from a data structure.
+##
+## The +#restore_ses+ method is called once in the same request an old
+## session is restored. A session is restored, when the user returns to
+## the page or reloads the page before the session is expired.
+##
+## === When the server is configured to restore previous sessions (default):
+## If the user accesses the same page using the same browser (in different
+## tabs or windows), only the most recently restored one is valid, while 
+## the previous ones are immediately invalidated.
+## If your application is intended to support several sessions per browser,
+## enable session cloning in the configuration file.
+##
+## === When the server is configured to restore and clone previous sessions:
+## When sessions are cloned, the previous session is not invalidated and
+## exists until timing out as a result of the web browser window being closed
+## or client computer losing network connectivity for a certain (configurable)
+## time frame.
+##
+## The +#cloned_target+ method is like +#restore_ses+, but called when 
+## the session is a clone of a previous session.
+##
+## The +#cloned_source+ method is called on the next request of the previous
+## session after it has been cloned.
+##
+## == Server event methods
+## Extend the +#init+ method to invoke constructor functionality that
+## depends on the plugin to be constructed and registered as a part of
+## the system.
+##
+## Extend the +#open+, +#flush+ and +#close+ methods to open, flush and close
+## streams or other similar functionality.
+##
+## == Data handling
+## The data exchange system exists to support bi-directional
+## data synchronization between the browser and the plugin. The values
+## are stored in the session as +HValue+ instances.
+##
+## Values support Hashes, Arrays, Strings, Numbers, Booleans and
+## combinations of them. The data is automatically converted between
+## ruby objects (server) and json objects (client).
+##
+## Each instance may be bound to plugin methods that are used as
+## value change notification responders.
+##
+## When a method is bound to the value, the method is called as an
+## event notification whenever the client has changed the value and
+## synchronizes it to the server. The responders act as validators
+## by default.
+##
+## Values are also bound in the client to classes implementing the
+## HValueResponder interface, like any derivate of HControl. See the
+## client documentation for instructions about using them.
+##
+## To define a value responder method, it needs to respond to exactly
+## two parameters: the +Message+ instance +msg+ and the HValue object
+## (in that order). The method's return value must be either +true+
+## or +false+. When the method returns +false+, the change is discarded
+## and the previously server-set value is sent back to the client.
+##
+## A minimal value responder method is defined like this:
+##
+##    def my_value_responder( msg, my_value )
+##      return true
+##    end
+##
+## To access the content of the value, use the +HValue#data+ attribute.
+##
+##    def int_between_100_and_200( msg, value )
+##      data = value.data.to_i
+##      return ( data >= 100 and data <= 200 )
+##    end
+##
+## To change the content of the value, use the +HValue#set+ method.
+##
+##    def int_between_100_and_200( msg, value )
+##      data = value.data.to_i
+##      value.set( msg, 100 ) if data < 100
+##      value.set( msg, 200 ) if data > 200
+##      return true
+##    end
+##
+## == Defining values
+## The simplest and recommended way of defining the values is to define
+## the value configuration file +values.yaml+. Its configuration is then
+## applied to sessions automatically.
+##
+## 
+## === Syntax reference of the contents of a +values.yaml+ file:
+##
+##    # The name of the value (:value_name).
+##    # A hash key in the yaml syntax
+##    :value_name:
+##      
+##      # All of these keys are optional!
+##      
+##      # Default value, a string "Foo" here.
+##      # Defaults to 0
+##      :value: Foo
+##      
+##      # A plugin method to call to define the default value
+##      # instead of the one defined in :value
+##      :value_call:
+##        :plugin: plugin_name # defaults to the plugin where defined
+##        
+##        # Mandatory; name of the method to call
+##        :method: method_name
+##        
+##        # Optional, list of parameter values for the :method
+##        :args:
+##          # three parameters: 1, 'foo', 3
+##          - 1
+##          - foo
+##          - 3
+##        
+##        # When false, doesn't pass the msg as the first parameter.
+##        # Defaults to true
+##        :uses_msg: true
+##      
+##      # Restore the default, when the session is restored; defaults to false
+##      :restore_default: false
+##      
+##      # List of value responder methods to bind.
+##      :responders:
+##        - 
+##          # name of plugin to call, defaults to the plugin where defined:
+##          :plugin: plugin_name
+##          
+##          # mandatory, name of the method to call
+##          :method: method_name
+##        
+##        # Another responder, this one using the same plugin where defined:
+##        - :method: another_method
+##    
+##    # Another value, this one just defining the defaults
+##    # by supplying an empty Hash:
+##    # (value: 0, default restored, no responders or calls)
+##    :value_with_defaults: {}
+##    
+##    # This value defines a Number (123) and doesn't restore
+##    # the default, when restoring the session.
+##    :one_two_three:
+##      :value: 123
+##      :restore_default: false
+##    
+##    # This value gets a random string and specifies a responder,
+##    # that ensures it's unique, if changed in the client.
+##    :random_unique_string:
+##      :value_call:
+##        :method:   get_unique_random_string
+##        :uses_msg: false
+##      :responders:
+##        - :method: ensure_unique_random_string
+##
+## = Examples
+## More examples are available in the repository;
+## http://svn.rsence.org/contrib/plugins
+## ..as well as the standard "main" plugin in the "plugins" directory.
+## 
+## 
+## == A minimal Plugin bundle
+## The minimal active plugin bundle (named "name_of_plugin")
+## is defined like this:
+##
+##    [dir] name_of_plugin
+##      |
+##      +---[file] name_of_plugin.rb
+##
+## This sample Plugin doesn't do anything except construct itself and
+## respond as 'name_of_plugin'.
+##
+##    Plugin.new.register('name_of_plugin')
+##
+## However, this is not very useful in itself, so you'll need to extend
+## its functionality to do anything useful.
+##
+## == A simple Plugin extension
+## This plugin logs session events to the logs/session_log file.
+##
+##    [dir] ses_logger
+##      |
+##      +---[file] ses_logger.rb
+##      |
+##      +---[dir] logs
+##            |
+##            +---[file] session_log
+##
+## == Contents of "ses_logger.rb"
+##
+##    class SessionLogger < Plugin
+##      def init
+##        super
+##        @logfile = false
+##      end
+##      def open
+##        log_path = compose_plugin_path( 'session_log', 'logs' )
+##        @logfile = File.open( log_path, 'a' )
+##      end
+##      def close
+##        @logfile.close if @logfile
+##        @logfile = false
+##      end
+##      def flush
+##        @logfile.flush if @logfile
+##      end
+##      def init_ses( msg )
+##        super
+##        @logfile.write( "#{Time.new} -- Session id #{msg.ses_id} was created.\n" )
+##      end
+##      def restore_ses( msg )
+##        super
+##        @logfile.write( "#{Time.new} -- Session id #{msg.ses_id} was restored.\n" )
+##      end
+##      def idle( msg )
+##        @logfile.write( "#{Time.new} -- Client of session id #{msg.ses_id} connected.\n" )
+##      end
+##    end
+##    SessionLogger.new.register( 'ses_logger' )
+##
+class Plugin
+  
+  include PluginUtil
+  
+  # The +names+ is a list of (usually just one) names the plugin is registered under.
+  attr_reader :name, :path, :info, :inited
+  
+  # The constructor should not take any parameters. In most cases, it's better
+  # to extend the +#init+ method, because it's called after the plugin is set up.
+  def initialize
+    @inited  = false
+    @info    = @@bundle_info
+    @name    = @@bundle_name
+    @path    = @@bundle_path
+    @plugins = @@plugin_manager
+    register unless @info[:inits_self]
+  end
+  
+  # Extend this method to do any initial tasks before other methods are called.
+  # By default init_values is called to load the +values.yaml+ configuration file.
+  def init
+    @values = init_values
+  end
+  
+  # Extend this method to do any tasks every time the client makes a request.
+  def idle( msg )
+  end
+  
+  # Extend this method to invoke actions, when a new session is created.
+  # By default +#init_ses_values+ is called to initialize values defined in the 
+  # +values.yaml+ configuration file.
+  def init_ses( msg )
+    init_ses_values( msg )
+  end
+  
+  # Extend this method to invoke actions, when a previous session is restored.
+  # By default +#restore_ses_values+ is called to perform actions on values as
+  # defined in the +values.yaml+ configuration file.
+  def restore_ses( msg )
+    restore_ses_values( msg )
+  end
+  
+  # Extend this method to invoke actions, when the session
+  # is a clone of another session. It's called once, just
+  # before +#restore_ses+ is called.
+  #
+  # A session is cloned, when a user opens a another browser
+  # window or tab, while the previous session is still active.
+  #
+  # The +source_ses+ is the actual previous session object, which
+  # was used as the source of the clone.
+  def cloned_target( msg, source_session )
+  end
+  
+  # Extend this method to invoke actions, when the session
+  # has been cloned to another session. It's called once, just
+  # before +#restore_ses+ is called on the first request after
+  # the cloning happened.
+  #
+  # A session is cloned, when a user opens a another browser
+  # window or tab, while the previous session is still active.
+  #
+  # The +target_ses+ is the actual cloned session object, which
+  # is a copy of the current session.
+  def cloned_source( msg, target_sessions )
+  end
+  
+  # This method must be called to register the plugin instance
+  # into the system. Otherwise, it's subject to destruction
+  # and garbage collection. Use the +name+ parameter to 
+  # give the (unique) name of your plugin.
+  def register( name=false )
+    if @inited
+      @plugins.register_alias( @name, name )
+    else
+      if name
+        name = name.to_s
+      else
+        name = @name
+      end
+      @plugins.register_bundle( self, name )
+      @inited = true
+    end
+  end
+  
+private
+  
+  # This method looks looks for a file called "values.yaml"
+  # in the plugin's bundle directory
+  #.
+  # If this file is found, it loads it for initial value definitions.
+  #
+  # These definitions are accessible as the +@values+ attribute.
+  def init_values
+    values_path = compose_plugin_path( 'values.yaml' )
+    return yaml_read( values_path )
+  end
+  
+  # Returns all the names your plugin respond to.
+  # def name
+  #   return @names.first
+  # end
+  
+  
+  # Returns or creates a new session hash for the plugin.
+  #
+  # Uses the first name registered for the plugin and converts it to a symbol.
+  def get_ses( msg )
+    name_sym = name.to_sym
+    unless msg.session.has_key?( name_sym )
+      msg.session[ name_sym ] = {}
+    end
+    return msg.session[ name_sym ]
+  end
+  
+  # Returns the source code of the javascript file +name+ in the 'js'
+  # subdirectory of the plugin bundle.
+  def read_js( js_name )
+    file_read( compose_plugin_path( js_name, 'js', '.js' ) )
+  end
+  
+  # Deprecated name of +#read_js+
+  alias require_js read_js
+  
+  # Like +#read_js+, but reads the file only once per session.
+  #
+  # Returns the contents of the file on the first call,
+  # an empty string on the subsequent calls.
+  #
+  # Returns false otherwise.
+  def read_js_once( msg, js_name )
+    ses = msg.session
+    if not ses.has_key?(:deps)
+      ses[:deps] = []
+    end
+    path = compose_plugin_path( js_name, 'js', '.js' )
+    unless ses[:deps].include?( path )
+      ses[:deps].push( path )
+      return file_read( path )
+    else
+      return ''
+    end
+  end
+  
+  # Deprecated name of +#read_js_once+
+  alias require_js_once read_js_once
+  
+  # Creates a new instance of HValue, assigns it as +value_name+ into the
+  # session and uses the +value_properties+ Hash to define the default
+  # value and value responders.
+  #
+  # This method is invoked automatically, when handling the properties
+  # of the +values.yaml+ configuration file of a new session.
+  #
+  # It's invoked by +#init_ses+ via +#init_ses_values+.
+  #
+  # Structure of +value_properties+, all top-level items are optional:
+  #
+  #   {
+  #     # Default value; defaults to 0
+  #     :value => 'foo',
+  #     
+  #     # A plugin method to call to define the default value instead of the one defined in :value
+  #     :value_call => {
+  #       :plugin => 'plugin_name', # defaults to the plugin where defined
+  #       :method => 'method_name', # mandatory; name of the method to call
+  #       :args => [ 1, 'foo', 3 ], # optional, list of parameter values for the :method
+  #       :uses_msg => true         # defaults to true; when false, doesn't pass the msg as the first parameter
+  #     },
+  #     
+  #     # Restore the default, when the session is restored; defaults to false
+  #     :restore_default => false,
+  #     
+  #     # List of value responder methods to bind.
+  #     :responders => [
+  #        {
+  #          :plugin => 'plugin_name', # defaults to the plugin where defined
+  #          :method => 'method_name'  # mandatory, name of the method to call
+  #        },
+  #        # You can supply as many responders as you like:
+  #        { :plugin => 'another_plugin', :method => 'another_method' }
+  #     ]
+  #   }
+  #
+  def init_ses_value( msg, value_name, value_properties )
+    ses = get_ses( msg )
+    if value_properties.has_key?(:value_call)
+      default_value = init_value_call( msg, value_properties[:value_call] )
+    elsif value_properties.has_key?(:value)
+      default_value = value_properties[:value]
+    else
+      default_value = 0
+    end
+    ses[value_name] = HValue.new( msg, default_value )
+    if value_properties.has_key?(:responders)
+      value_properties[:responders].each do |responder|
+        if responder.has_key?(:plugin)
+          responder_plugin = responder[:plugin]
+        else
+          responder_plugin = @name
+        end
+        if responder.has_key?(:method)
+          ses[value_name].bind( responder_plugin, responder[:method] )
+        end
+      end
+    end
+  end
+  
+  # Initializes session values, if the contents of the +values.yaml+ 
+  # file is defined in the bundle directory and loaded in +#init_values+.
+  def init_ses_values( msg )
+    return unless @values
+    @values.each do | value_name, value_properties |
+      init_ses_value( msg, value_name, value_properties )
+    end
+  end
+  
+  # Returns a value based on the :method and :plugin members of the
+  # +value_call+ hash.
+  #
+  # The call is made via msg.run if the method is not defined in
+  # the local plugin bundle.
+  #
+  # This method is called from +#init_ses_value+.
+  #
+  # Structure of the +value_call+ Hash:
+  #   { :plugin => 'plugin_name', # defaults to the plugin where defined
+  #     :method => 'method_name', # mandatory; name of the method to call
+  #     :args => [ 1, 'foo', 3 ], # optional, list of parameter values for the :method
+  #     :uses_msg => true         # defaults to true; when false, doesn't pass the msg as the first parameter
+  #   }
+  def init_value_call( msg, value_call )
+    value_call_method = value_call[:method]
+    if value_call.has_key?(:plugin)
+      value_call_plugin = value_call[:plugin]
+    else
+      value_call_plugin = false
+    end
+    if value_call.has_key?(:args)
+      if value_call.has_key?(:uses_msg) and value_call[:uses_msg] != false
+        if value_call_plugin
+          return msg.run( value_call_plugin, value_call_method, msg, *value_call[:args] )
+        else
+          return self.method( value_call_method ).call( msg, *value_call[:args] )
+        end
+      else
+        if value_call_plugin
+          return msg.run( value_call_plugin, value_call_method, *value_call[:args] )
+        else
+          return self.method( value_call_method ).call( *value_call[:args] )
+        end
+      end
+    else
+      if value_call.has_key?(:uses_msg) and value_call[:uses_msg] != false
+        if value_call_plugin
+          return msg.run( value_call_plugin, value_call_method, msg )
+        else
+          return self.method( value_call_method ).call( msg )
+        end
+      else
+        if value_call_plugin
+          return msg.run( value_call_plugin, value_call_method )
+        else
+          return self.method( value_call_method ).call( )
+        end
+      end
+    end
+  end
+  
+  # Restores session values to default, unless specified otherwise.
+  #
+  # Called from +#restore_ses+
+  def restore_ses_values( msg )
+    return unless @values
+    ses = get_ses( msg )
+    @values.each do | value_name, value_properties |
+      if ses.has_key?( value_name ) and ses[ value_name ].class == HValue
+        unless value_properties[:restore_default] == false
+          if value_properties.has_key?(:value_call)
+            default_value = init_value_call( msg, value_properties[:value_call] )
+          elsif value_properties.has_key?(:value)
+            default_value = value_properties[:value]
+          else
+            default_value = 0
+          end
+          ses[value_name].set( msg, default_value )
+        end
+      else
+        init_ses_value( msg, value_name, value_properties )
+      end
+    end
+  end
+  
+  # Extracts +HValue+ references as javascript from the session Hash.
+  # The +ses+ parameter is used for supplying a hash with the +HValue+
+  # instances. It's optional and defaults to the current plugin node in
+  # the active session.
+  # 
+  # The return value is a string representing a js object similar to
+  # the ruby Hash +ses+.
+  # 
+  # Sample usage:
+  #
+  #   values_js( msg, msg.session[:main] )
+  #
+  def values_js( msg, ses=false )
+    # backwards-compatible with pre-1.3 behaviour
+    ses = msg if msg.class == Hash
+    # gets the session automatically, if false
+    ses = get_ses( msg ) unless ses
+    js_references = []
+    ses.each_key do |key_name|
+      if ses[key_name].class == HValue
+        js_references.push( "#{key_name.to_s}:HVM.values['#{ses[key_name].val_id}']" )
+      end
+    end
+    return "{#{js_references.join(',')}}"
+  end
+  
+  # Deprecated name of +#values_js+
+  alias extract_hvalues_from_hash values_js
+  
+  # Tells the js client framework to load a list of dependency packages.
+  # It keeps track of what's loaded, so nothing library loaded twice.
+  #
+  # The +dependencies+ parameter is an Array of dependencies.
+  #
+  # Sample usage:
+  #
+  #   include_js( msg, [ 'default_theme', 'controls', 'lists', 'datetime' ] )
+  #
+  def include_js( msg, dependencies=[] )
+    ses = msg.session
+    # check, if the session has a dependency array
+    if not ses.has_key?( :deps )
+      # make an array of dependencies for this session, if not already done
+      ses[:deps] = []
+    end
+    dependencies = [dependencies] if dependencies.class == String
+    # Check the required dependencies until everything is loaded.
+    dependencies.each do |dependency|
+      unless ses[:deps].include?( dependency )
+        ses[:deps].push( dependency )
+        msg.reply(%{jsLoader.load("#{dependency}");})
+      end
+    end
+  end
+  
+  
+end
+
+