wee 0.10.0 → 2.0.0

data/lib/wee/application.rb

@@ -1,147 +1,85 @@
-# A Wee::Application manages all Wee::RequestHandler's of a single application,
-# where most of the time the request handlers are Wee::Session objects. It
-# dispatches the request to the correct handler by examining the request.
+require 'thread'
+require 'wee/id_generator'
+require 'wee/lru_cache'
 
-class Wee::Application
+module Wee
 
-  # The generator used for creating unique request handler id's.
-
-  attr_accessor :id_generator
-
-  # The maximum number of request handlers
-
-  attr_accessor :max_request_handlers
-
-  # Get or set the default request handler. The default request handler is used
-  # if no request handler id is given in a request. 
-
-  def default_request_handler(&block)
-    if block.nil?
-      @default_request_handler
-    else
-      @default_request_handler = block
-    end
-  end
-
-  # Creates a new application. The block is used to initialize the attributes:
   #
-  #   Wee::Application.new {|app|
-  #     app.default_request_handler { MySession.new } 
-  #     app.id_generator = Wee::SequentialIdGenerator.new
-  #     app.max_request_handlers = 1000 
-  #   }
+  # A Wee::Application manages all Session's of a single application.  It
+  # dispatches the request to the correct handler by examining the request.
+  #
+  class Application
 
-  def initialize(&block)
-    @request_handlers = Hash.new
-    block.call(self)
-    @id_generator ||= Wee::SequentialIdGenerator.new(rand(1_000_000))
-    if @default_request_handler.nil?
-      raise ArgumentError, "No default request handler specified"
+    class SessionCache < Wee::LRUCache
+      def garbage_collect
+        delete_if {|id, session| session.dead? }
+      end
     end
-    @mutex = Mutex.new
-
-    # start request-handler collecting thread
-    # run once every minute
-    @gc_thread = Thread.new {
-      sleep 60
-      @mutex.synchronize { garbage_collect_handlers }
-    }
-  end
-  
-  def handle_request(context)
-    request_handler_id = context.request.request_handler_id
-    request_handler = @mutex.synchronize { @request_handlers[request_handler_id] }
-
-    if request_handler_id.nil?
-
-      # No id was given -> check whether the maximum number of request-handlers
-      # limit is reached. if not, create new id and handler
-
-      request_handler = @default_request_handler.call 
-      insert_new_request_handler(request_handler)
-      context.request.request_handler_id = request_handler.id 
-      handle_request(context)
-      return
-
-    elsif request_handler.nil?
-
-      # A false request handler id was given. This might indicate that a
-      # request handler has expired. 
-
-      request_handler_expired(context)
-      return
-
-    elsif !request_handler.alive?
-
-      # The request_handler is not alive anymore.
-
-      request_handler_expired(context)
-      return
 
+    #
+    # Creates a new application. The block, when called, must
+    # return a new Session instance. 
+    #
+    #   Wee::Application.new { Wee::Session.new(root_component) }
+    #
+    def initialize(max_sessions=10_000, &block)
+      @session_factory = block || raise(ArgumentError)
+      @session_ids ||= Wee::IdGenerator::Secure.new
+      @sessions = SessionCache.new(max_sessions)
+      @mutex = Mutex.new
     end
 
-    request_handler.handle_request(context)
-
-  rescue => exn
-    context.response = Wee::ErrorResponse.new(exn) 
-  end
-
-  def insert_new_request_handler(request_handler)
-    @mutex.synchronize {
-      if @max_request_handlers != nil and @request_handlers.size >= @max_request_handlers
-        # limit reached -> remove non-alive handlers...
-        garbage_collect_handlers()
-
-        # ...and test again
-        if @request_handlers.size >= @max_request_handlers
-          # TODO: show a custom error message
-          raise "maximum number of request-handlers reached" 
+    #
+    # Garbage collect dead sessions
+    #
+    def cleanup_sessions
+      @mutex.synchronize { @sessions.garbage_collect }
+    end
+    
+    #
+    # Handles a web request
+    #
+    def call(env)
+      request = Wee::Request.new(env)
+
+      if request.session_id
+        session = @mutex.synchronize { @sessions[request.session_id] }
+        if session and session.alive?
+          session.call(env)
+        else
+          url = request.build_url(:session_id => nil, :page_id => nil)
+          Wee::RefreshResponse.new("Invalid or expired session", url).finish
         end
+      else
+        session = new_session()
+        url = request.build_url(:session_id => session.id, :page_id => nil)
+        Wee::RedirectResponse.new(url).finish
       end
-
-      request_handler.id = unique_request_handler_id()
-      request_handler.application = self
-      @request_handlers[request_handler.id] = request_handler
-    }
-  end
-
-  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-  # :section: Properties
-  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-  def properties() @__properties end
-  def properties=(props) @__properties = props end
-
-  # Returns an "owned" property for the given +klass+.
-
-  def get_property(prop, klass)
-    if self.properties
-      self.properties.fetch(klass, {})[prop]
-    else
-      nil
     end
-  end
-
-  private
 
-  # MUST be called while holding @mutex
+    protected
 
-  def unique_request_handler_id
-    id = @id_generator.next.to_s
-    raise "failed to create unique request handler id" if @request_handlers.include?(id)
-    return id
-  end
-
-  # MUST be called while holding @mutex
+    def new_session
+      session = @session_factory.call
+      session.application = self
+      insert_session(session)
+      return session
+    end
 
-  def garbage_collect_handlers
-    @request_handlers.delete_if {|id,rh| !rh.alive? }
-  end
+    def insert_session(session, retries=3)
+      retries.times do
+        @mutex.synchronize {
+          id = @session_ids.next
+          if @sessions[id].nil?
+            @sessions[id] = session 
+            session.id = id
+            return
+          end
+        }
+      end
+      raise
+    end
 
-  def request_handler_expired(context)
-    context.response = Wee::RefreshResponse.new("Invalid or expired request handler!",
-                       context.request.build_url(:request_handler_id => nil,
-                                                 :page_id => nil))
-  end
+  end # class Application
 
-end
+end # module Wee

data/lib/wee/call_answer.rb

@@ -0,0 +1,118 @@
+module Wee
+
+  #
+  # A Wee::AnswerDecoration is wrapped around a component that will call
+  # Component#answer. This makes it possible to use such components without the
+  # need to call them (Component#call), e.g. as child components of other
+  # components.
+  #
+  class AnswerDecoration < Decoration
+
+    #
+    # Used to unwind the component call chain in Component#answer.
+    #
+    class Answer < Exception
+      attr_reader :args
+      def initialize(args) @args = args end
+    end
+
+    attr_accessor :answer_callback
+
+    def initialize(&answer_callback)
+      super()
+      @answer_callback = answer_callback
+    end
+
+    #
+    # When a component answers, <tt>@answer_callback.call(answer)</tt>
+    # will be executed, where +answer+ is of class Answer which includes the
+    # arguments passed to Component#answer.
+    #
+    def process_callbacks(callbacks)
+      begin
+        super
+      rescue Answer => answer
+        # return to the calling component 
+        @answer_callback.call(answer)
+      end
+    end
+
+  end # class AnswerDecoration
+
+  module CallAnswerMixin
+
+    protected
+
+    #
+    # Call another component. The calling component is neither rendered nor are
+    # it's callbacks processed until the called component answers using method
+    # #answer. 
+    #
+    # [+component+]
+    #   The component to be called.
+    #
+    # [+return_callback+]
+    #   Is invoked when the called component answers.
+    #
+    # <b>How it works</b>
+    # 
+    # The component to be called is wrapped with an AnswerDecoration and a
+    # Delegate decoration. The latter is used to redirect to the called
+    # component. Once the decorations are installed, we end the processing of
+    # callbacks prematurely.
+    #
+    # When at a later point in time the called component invokes #answer, this
+    # will raise a AnswerDecoration::Answer exception which is catched by the
+    # AnswerDecoration we installed before calling this component, and as such,
+    # whose process_callbacks method was called before we gained control.
+    #
+    # The AnswerDecoration then invokes the <tt>answer_callback</tt> to cleanup
+    # the decorations we added during #call and finally passes control to the
+    # <tt>return_callback</tt>.
+    #
+    def call(component, &return_callback)
+      delegate = Wee::Delegate.new(component)
+      answer = Wee::AnswerDecoration.new {|answ|
+        remove_decoration(delegate)
+        component.remove_decoration(answer)       
+        return_callback.call(*answ.args) if return_callback
+      }
+      add_decoration(delegate)
+      component.add_decoration(answer)
+      session.send_response(nil)
+    end
+
+    #
+    # Similar to method #call, but using continuations.
+    #
+    def callcc(component)
+      delegate = Wee::Delegate.new(component)
+      answer = Wee::AnswerDecoration.new
+
+      add_decoration(delegate)
+      component.add_decoration(answer)
+
+      answ = Kernel.callcc {|cc|
+        answer.answer_callback = cc
+        session.send_response(nil)
+      }
+
+      remove_decoration(delegate)
+      component.remove_decoration(answer)
+      return *answ.args
+    end
+
+    #
+    # Return from a called component.
+    # 
+    # NOTE that #answer never returns.
+    #
+    # See #call for a detailed description of the call/answer mechanism.
+    #
+    def answer(*args)
+      raise AnswerDecoration::Answer.new(args)
+    end
+
+  end # module CallAnswerMixin
+
+end # module Wee

data/lib/wee/callback.rb

@@ -0,0 +1,88 @@
+module Wee
+
+  class CallbackRegistry
+    def initialize(prefix="")
+      @prefix = prefix
+      @next_id = 0
+      @callbacks = {}    # {callback_id1 => callback1, callback_id2 => callback2}
+      @triggered = nil
+      @obj_map = {}      # obj => [callback_id1, callback_id2, ...]
+    end
+
+    def register(object, callback)
+      id = @next_id
+      @next_id += 1
+      @callbacks[id] = callback
+      (@obj_map[object] ||= []) << id
+      return "#{@prefix}#{id}"
+    end
+
+    def unregister(object)
+      if arr = @obj_map.delete(object)
+        arr.each {|id| @callbacks.delete(id) }
+      end
+    end
+
+    #
+    # NOTE that if fields named "xxx" and "xxx.yyy" occur, the value of 
+    # @fields['xxx'] is { nil => ..., 'yyy' => ... }. This is required
+    # to make image buttons work correctly.
+    #
+    def prepare_triggered(ids_and_values)
+      @triggered = {}
+      ids_and_values.each do |id, value|
+        if id =~ /^#{@prefix}(\d+)([.](.*))?$/
+          id, suffix = Integer($1), $3
+          next unless @callbacks[id]
+
+          if @triggered[id].kind_of?(Hash)
+            @triggered[id][suffix] = value
+          elsif suffix
+            @triggered[id] = {nil => @triggered[id], suffix => value}
+          else
+            @triggered[id] = value
+          end
+        end
+      end
+    end
+
+    def reset_triggered
+      @triggered = nil
+    end
+
+    def each_triggered(object)
+      if ary = @obj_map[object]
+        ary.each do |id|
+          yield @callbacks[id], @triggered[id] if @triggered.has_key?(id)
+        end
+      end
+    end
+
+  end # class CallbackRegistry
+
+  class Callbacks
+    attr_reader :input_callbacks
+    attr_reader :action_callbacks
+
+    def initialize
+      @input_callbacks = CallbackRegistry.new("")
+      @action_callbacks = CallbackRegistry.new("a")
+    end
+
+    def unregister(object)
+      @input_callbacks.unregister(object)
+      @action_callbacks.unregister(object)
+    end
+
+    def with_triggered(ids_and_values)
+      @input_callbacks.prepare_triggered(ids_and_values)
+      @action_callbacks.prepare_triggered(ids_and_values)
+      yield
+    ensure
+      @input_callbacks.reset_triggered
+      @action_callbacks.reset_triggered
+    end
+
+  end # class Callbacks
+
+end # module Wee

data/lib/wee/component.rb

@@ -0,0 +1,141 @@
+require 'wee/presenter'
+require 'wee/decoration'
+require 'wee/call_answer'
+
+module Wee
+
+  #
+  # The base class of all components. You should at least overwrite method
+  # #render in your own subclasses.
+  #
+  class Component < Presenter
+
+    #
+    # Initializes a newly created component.
+    #
+    # Call this method from your own components' <i>initialize</i> method using
+    # +super+, before setting up anything else! 
+    #
+    def initialize() # :notnew:
+      @decoration = self
+      @children = nil
+    end
+
+    #
+    # This method renders the content of the component.
+    #
+    # *OVERWRITE* this method in your own component classes to implement the
+    # view. By default this method does nothing!
+    #
+    # [+r+]
+    #    An instance of class <tt>renderer_class()</tt>
+    #
+    def render(r)
+    end
+
+    #
+    # Process and invoke all callbacks specified for this component and all of
+    # it's child components. 
+    #
+    def process_callbacks(callbacks)
+      callbacks.input_callbacks.each_triggered(self) do |callback, value|
+        callback.call(value)
+      end
+
+      # process callbacks of all children
+      each_child do |child|
+        child.decoration.process_callbacks(callbacks)
+      end
+
+      callbacks.action_callbacks.each_triggered(self) do |callback, value|
+        callback.call
+        session.send_response(nil) # prematurely end callback processing
+      end
+    end
+
+    #
+    # Take snapshots of objects that should correctly be backtracked.
+    #
+    # Backtracking means that you can go back in time of the components' state.
+    # Therefore it is neccessary to take snapshots of those objects that want to
+    # participate in backtracking. Taking snapshots of the whole component tree
+    # would be too expensive and unflexible. Note that methods
+    # <i>take_snapshot</i> and <i>restore_snapshot</i> are called for those
+    # objects to take the snapshot (they behave like <i>marshal_dump</i> and
+    # <i>marshal_load</i>). Overwrite them if you want to define special
+    # behaviour. 
+    #
+    # For example if you dynamically add children to your component, you might
+    # want to backtrack the children array: 
+    #
+    #   def backtrack(state)
+    #     super
+    #     backtrack_children(state)
+    #   end
+    #
+    # By default only the decoration chain is backtracked. This is
+    # required to correctly backtrack called components. To disable
+    # backtracking of the decorations, change method
+    # Component#backtrack_decoration to a no-operation:
+    #
+    #   def backtrack_decoration(state)
+    #     # nothing here
+    #   end
+    #
+    # [+state+]
+    #    An object of class State
+    #
+    def backtrack(state)
+      backtrack_decoration(state)
+      each_child do |child|
+        child.decoration.backtrack(state)
+      end
+    end
+
+    protected
+
+    def backtrack_decoration(state)
+      state.add_ivar(self, :@decoration, @decoration)
+    end
+
+    def backtrack_children(state)
+      state.add_ivar(self, :@children, (@children and @children.dup))
+    end
+
+    #
+    # Iterates over all direct child components. 
+    #
+    def each_child(&block)
+      @children.each(&block) if @children
+    end
+
+    #
+    # Add a child to the component. Example:
+    # 
+    #   class YourComponent < Wee::Component
+    #     def initialize
+    #       super()
+    #       add_child ChildComponent.new
+    #     end
+    #   end
+    #
+    # If you dynamically add child components to a component at run-time (not in
+    # initialize), then you should consider to backtrack the children array (of
+    # course only if you want backtracking at all): 
+    #   
+    #   def backtrack(state)
+    #     super
+    #     state.add(self.children)
+    #   end
+    #
+    def add_child(child)
+      (@children ||= []) << child
+      child
+    end
+
+    include Wee::DecorationMixin
+    include Wee::CallAnswerMixin
+
+  end # class Component
+
+end # module Wee