ap4r 0.3.2 → 0.3.3

data/rails_plugin/ap4r/lib/ap4r_client.rb

@@ -0,0 +1,132 @@
+# Author:: Kiwamu Kato
+# Copyright:: Copyright (c) 2007 Future Architect Inc.
+# Licence:: MIT Licence
+
+require 'forwardable'
+require 'async_helper'
+
+module Ap4r #:nodoc:
+
+  # This +Client+ is the Rails plugin for asynchronous processing.
+  # Asynchronous logics are called via various protocols, such as XML-RPC,
+  # SOAP, HTTP POST, and more. Now default protocol is HTTP POST.
+  #
+  # Examples: The part of calling next asynchronous logics in a controller in the HelloWorld Sample.
+  #
+  #     req = WorldRequest.new([:world_id => 1, :message => "World"})
+  #     ap4r.async_to({:controller => 'async_world', :action => 'execute'},
+  #                   {:world_id => 1, :message => "World"},
+  #                   {:dispatch_mode => :HTTP}) # skippable
+  #
+  #     render :action => 'response'
+  #
+  # Complement: Above +ap4r+ method is defiend init.rb in +%RAILS_ROOT%/vendor/plugin/ap4r/+.
+  #
+  class Client
+    extend Forwardable
+    include ::Ap4r::AsyncHelper::Base
+
+    def initialize controller
+      @controller = controller
+    end
+
+    def_delegators :@controller, :logger, :url_for
+
+    # Queue a message for next asynchronous logic. Some options are supported.
+    #
+    # Use options to specify target url, etc.
+    # Accurate meanings are defined by a individual converter class.
+    # * :controller (name of next logic)
+    # * :action (name of next logic)
+    #
+    # Use rm_options to pass parameter in queue-put.
+    # Listings below are AP4R extended options.
+    # See the reliable-msg docuememt for more details.
+    # * :target_url (URL of target, prevail over :controller)
+    # * :target_action (action of target, prevail over :action)
+    # * :target_method (HTTP method, e.g. "GET", "POST", etc.)
+    # * :dispatch_mode (protocol in dispatching)
+    # * :queue_name (prevail over :controller and :action)
+    #
+    # Object of argumemts (async_params, options and rm_options) will not be modified.
+    # Implementors (of this class and converters) should not modify them.
+    #
+    # Examples: the most simple
+    #
+    #     ap4r.async_to({:controller => 'next_controller', :action => 'next_action'},
+    #                   {:world_id => 1, :message => "World"})
+    #
+    #
+    # Examples: taking block
+    #
+    #     ap4r.async_to({:controller => 'next_controller', :action => 'next_action'}) do
+    #       body :world_id, 1
+    #       body :message, "World"
+    #     end
+    #
+    #
+    # Examples: transmitting ActiveRecord object
+    #
+    #     ap4r.async_to({:controller => 'next_controller', :action => 'next_action'}) do
+    #       body :world, World.find(1)
+    #       body :message, "World"
+    #     end
+    #
+    #
+    # Examples: transmitting with xml format over http (now support text, json and yaml format).
+    #
+    #     ap4r.async_to({:controller => 'next_controller', :action => 'next_action'}) do
+    #       body :world, World.find(1)
+    #       body :message, "World"
+    #       format :xml
+    #     end
+    #
+    #
+    # Examples: direct assignment for formatted message body
+    #
+    #     ap4r.async_to({:controller => 'next_controller', :action => 'next_action'}) do
+    #       world = World.find(1).to_xml :except => ...
+    #       body_as_xml world
+    #     end
+    #
+    #
+    # Examples: setting message header
+    #
+    #     ap4r.async_to({:controller => 'next_controller', :action => 'next_action'}) do
+    #       body :world_id, 1
+    #       body :message, "World"
+    #
+    #       header :priority, 1
+    #       http_header "Content-type", ...
+    #     end
+    #
+    alias :async_to :async_dispatch
+
+    # Provides at-least-once QoS level.
+    # +block+ are tipically composed of database accesses and +async_to+ calls.
+    # Database accesses are executed transactionallly by +active_record_class+'s transaction method.
+    # In the +block+, +async_to+ calls invoke NOT immediate queueing but just storing messages
+    # to the database (assumed to be the same one as application uses).
+    #
+    # If the execution of +block+ finishes successfully, database transaction is committed and
+    # forward process of each stored message begins.
+    # Forward process composed in two parts. First puts the message into a queue, secondary update
+    # or delete the entry from a management table.
+    #
+    # SAF (store and forward) processing like this guarantees that any message
+    # is never lost and keeps reasonable performance (without two phase commit).
+    #
+    # Examples: Just call async_to method in this block.
+    #
+    #     ap4r.transaction do
+    #       req = WorldRequest.new([:world_id => 1, :message => "World"})
+    #       ap4r.async_to({:controller => 'async_world', :action => 'execute'},
+    #                     {:world_id => 1, :message => "World"})
+    #
+    #       render :action => 'response'
+    #     end
+    #
+    alias :transaction :transaction_with_saf
+
+  end
+end

data/rails_plugin/ap4r/lib/{async_controller.rb → async_helper.rb}

@@ -3,32 +3,22 @@
 # Licence:: MIT Licence
 
 require 'reliable-msg'
-#require 'ap4r/stored_message'
+require 'ap4r/stored_message'
+require 'message_builder'
 
 module Ap4r
 
-  # This +AsyncController+ is the Rails plugin for asynchronous processing.
-  # Asynchronous logics are called via various protocols, such as XML-RPC,
-  # SOAP, HTTP POST, and more. Now default protocol is HTTP POST.
+  # This +AsyncHelper+ is included to +Ap4rClient+ and works the Rails plugin
+  # for asynchronous processing.
   #
-  # Examples: The part of calling next asynchronous logics in a controller in the HelloWorld Sample.
-  #
-  #     req = WorldRequest.new([:world_id => 1, :message => "World"})
-  #     async_dispatch(req,
-  #                     {:controller => 'async_world', :action => 'execute'},
-  #                     :dispatch_mode => :XMLRPC }) # skippable
-  #
-  #     render :action => 'response'
-  #
-  module AsyncController
+  module AsyncHelper
 
     module Base
       Converters = {}
 
-      # TODO: constant or class variable, whick is better? 2007/05/02 by shino
       DRUBY_HOST = ENV['AP4R_DRUBY_HOST'] || 'localhost'
       DRUBY_PORT = ENV['AP4R_DRUBY_PORT'] || '6438'
-      DRUBY_URI = "druby://#{DRUBY_HOST}:#{DRUBY_PORT}" 
+      DRUBY_URI = "druby://#{DRUBY_HOST}:#{DRUBY_PORT}"
 
       @@default_dispatch_mode = :HTTP
       @@default_rm_options = { :delivery => :once, :dispatch_mode => @@default_dispatch_mode }
@@ -36,30 +26,7 @@ module Ap4r
 
       mattr_accessor :default_dispatch_mode, :default_rm_options, :default_queue_prefix, :saf_delete_mode
 
-      # Provides at-least-once QoS level.
-      # +block+ are tipically composed of database accesses and +async_dispatch+ calls.
-      # Database accesses are executed transactionallly by +active_record_class+'s transaction method.
-      # In the +block+, +async_dispatch+ calls invoke NOT immediate queueing but just storing messages
-      # to the database (assumed to be the same one as application uses).
-      #
-      # If the execution of +block+ finishes successfully, database transaction is committed and
-      # forward process of each stored message begins.
-      # Forward process composed in two parts. First puts the message into a queue, secondary update 
-      # or delete the entry from a management table.
-      #
-      # SAF (store and forward) processing like this guarantees that any message
-      # is never lost and keeps reasonable performance (without two phase commit).
-      #
-      # Examples: Just call async_dispath method in this block.
-      #
-      #     transaction_with saf do
-      #       req = WorldRequest.new([:world_id => 1, :message => "World"})
-      #       async_dispatch(req,
-      #                       {:controller => 'async_world', :action => 'execute'},
-      #                       :dispatch_mode => :XMLRPC }) # skippable
-      #
-      #       render :action => 'response'
-      #     end
+      # This method is aliased as ::Ap4r::Client#transaction
       #
       def transaction_with_saf(active_record_class = ::Ap4r::StoredMessage, *objects, &block)
 
@@ -78,7 +45,7 @@ module Ap4r
           # Once some error occured, such as disconnect reliable-msg or server crush,
           # which is smart to keep to put a message or stop to do it?
           # In the case of being many async messages, the former strategy is not so good.
-          # 
+          #
           # TODO: add delayed forward mode 2007/05/02 by shino
           Thread.current[:stored_messages].each {|k,v|
             __queue_put(v[:queue_name], v[:queue_message], v[:queue_headers])
@@ -106,27 +73,10 @@ module Ap4r
         Thread.current[:stored_messages] = nil
       end
 
-      # Queue a message for next asynchronous logic. Some options are supported.
-      #
-      # Use options to specify target url, etc.
-      # Accurate meanings are defined by a individual converter class.
-      # * :controller (name of next logic)
-      # * :action (name of next logic)
+      # This method is aliased as ::Ap4r::Client#async_to
       #
-      # Use rm_options to pass parameter in queue-put.
-      # Listings below are AP4R extended options.
-      # See the reliable-msg docuememt for more details.
-      # * :target_url (URL of target, prevail over :controller)
-      # * :target_action (action of target, prevail over :action)
-      # * :target_method (HTTP method, e.g. "GET", "POST", etc.)
-      # * :dispatch_mode (protocol in dispatching)
-      # * :queue_name (prevail over :controller and :action)
-      #
-      # Object of argumemts (async_params, options and rm_options) will not be modified.
-      # Implementors (of this class and converters) should not modify them.
-      #
-      def async_dispatch(url_options = {}, async_params = nil, rm_options = nil)
-        # TODO: add :url to url_options to specify :target_url shortly 2007/05/02 by shino
+      def async_dispatch(url_options = {}, async_params = {}, rm_options = {}, &block)
+
         if logger.debug?
           logger.debug("url_options: ")
           logger.debug(url_options.inspect)
@@ -138,7 +88,10 @@ module Ap4r
 
         # TODO: clone it, 2006/10/16 shino
         url_options ||= {}
-        url_options[:controller] ||= self.controller_path.gsub("/", ".")
+        url_options[:controller] ||= @controller.controller_path.gsub("/", ".")
+        url_options[:url] ||= {:controller => url_options[:controller], :action => url_options[:action]}
+        url_options[:url][:controller] ||= url_options[:controller] if url_options[:url].kind_of?(Hash)
+
         rm_options = @@default_rm_options.merge(rm_options || {})
 
         # Only async_params is not cloned. options and rm_options are cloned before now.
@@ -150,6 +103,21 @@ module Ap4r
         queue_message = converter.make_params
         queue_headers = converter.make_rm_options
 
+        message_builder = ::Ap4r::MessageBuilder.new(queue_name, queue_message, queue_headers)
+        if block_given?
+          message_builder.instance_eval(&block)
+        end
+        queue_name = message_builder.queue_name
+        queue_headers = message_builder.message_headers
+        # TODO: proces flow of Converter and MessageBuilder should (probably) be reversed 2007/09/19 by shino
+        # This branching is ad-hoc fix
+        if queue_headers[:dispatch_mode] == :HTTP
+          queue_message = message_builder.format_message_body
+        else
+          queue_message = message_builder.message_body
+        end
+
+
         if Thread.current[:use_saf]
           stored_message = ::Ap4r::StoredMessage.store(queue_name, queue_message, queue_headers)
 
@@ -174,9 +142,14 @@ module Ap4r
       end
 
       def __get_queue_name(options, rm_options)
-        rm_options[:queue_name] ||=
-          @@default_queue_prefix.clone.concat(options[:controller].to_s).concat('.').concat(options[:action].to_s)
-        rm_options[:queue_name]
+        if options[:url].kind_of?(Hash)
+          rm_options[:queue] ||=
+            @@default_queue_prefix.clone.concat(options[:url][:controller].to_s).concat('.').concat(options[:url][:action].to_s)
+        else
+          rm_options[:queue] ||=
+            @@default_queue_prefix.clone.chomp(".").concat(URI::parse(options[:url]).path.gsub("/", "."))
+        end
+        rm_options[:queue]
       end
 
     end
@@ -193,7 +166,7 @@ module Ap4r
         # add self to a Converters list.
         def self.dispatch_mode(mode_symbol)
           self.const_set(:DISPATCH_MODE, mode_symbol)
-          ::Ap4r::AsyncController::Base::Converters[mode_symbol] = self
+          ::Ap4r::AsyncHelper::Base::Converters[mode_symbol] = self
         end
 
         def initialize(url_options, async_params, rm_options, url_for_handler)
@@ -220,6 +193,7 @@ module Ap4r
         private
         # helper method for <tt>ActionController#url_for</tt>
         def url_for(url_for_options, *parameter_for_method_reference)
+          return url_for_options if url_for_options.kind_of?(String)
           @url_for_handler.url_for(url_for_options, *parameter_for_method_reference)
         end
 
@@ -233,7 +207,7 @@ module Ap4r
         end
 
         def make_rm_options
-          @rm_options[:target_url] ||= url_for(@url_options)
+          @rm_options[:target_url] ||= url_for(@url_options[:url])
           @rm_options[:target_method] ||= 'POST'
           #TODO: make option key to specify HTTP headers, 2006/10/16 shino
           @rm_options
@@ -254,14 +228,12 @@ module Ap4r
         end
 
         def action_api_name
-          action_method_name = @url_options[:action]
+          action_method_name = @url_options[:url][:action]
           action_method_name.camelcase
         end
 
         def options_without_action
-          new_opts = @url_options.dup
-          new_opts[:action] = nil
-          new_opts
+          @url_options[:url].reject{ |k,v| k == :action }
         end
 
       end

data/rails_plugin/ap4r/lib/message_builder.rb

@@ -0,0 +1,181 @@
+# Author:: Kiwamu Kato
+# Copyright:: Copyright (c) 2007 Future Architect Inc.
+# Licence:: MIT Licence
+
+require 'active_record'
+
+module Ap4r #:nodoc:
+
+  # This +MessageBuilder+ is the class for formatting message body.
+  # Current support formats are text, xml, json and yaml,
+  # and the formatted messages are sent over HTTP.
+  #
+  # Using +format+ method, this class automatically changes the format of
+  # the given message body and adds appropriate +Content-type+ to http header.
+  # Or using +body_as_*+ methods, you can directly assign formatted message body.
+  class MessageBuilder
+
+    def initialize(queue_name, queue_message, queue_headers)
+      @queue_name = queue_name
+      @message_body = queue_message
+      @message_headers = queue_headers
+      @format = nil
+      @message_body_with_format = nil
+      @to_xml_options = {:root => "root"}
+    end
+
+    attr_accessor :queue_name, :message_body, :message_headers
+    attr_reader :format, :to_xml_options
+
+    # Sets message body in async_to block.
+    # The first argument is key and the second one is value.
+    #
+    # options are for to_xml conversion on Array and Hash, ActiveRecord objects.
+    #
+    def body(k, v, options = { })
+      k ||= v.class
+      if v.kind_of? ActiveRecord::Base
+        @message_body[k.to_sym] = v
+        @to_xml_options = @to_xml_options.merge(options)
+      else
+        @message_body[k.to_sym] = v
+      end
+    end
+
+    # Sets message header in async_to block.
+    # The first argument is key and the second one is value.
+    #
+    # Now supports following keys:
+    #   :expire
+    #   :priority
+    #   :delivery
+    #   :max_deliveries
+    #   :dispatch_mode
+    #   :target_method
+    #   :target_url
+    #   :id
+    #
+    # For details, please refer the reliable-msg.
+    #
+    def header(k, v)
+      @message_headers[k.to_sym] = v
+    end
+
+    # Sets http header in async_to block such as 'Content_type'.
+    # The first argument is key and the second one is value.
+    #
+    def http_header(k, v)
+      @message_headers["http_header_#{k}".to_sym] = v
+    end
+
+    # Sets format message serialization.
+    # As to the format, automatically sets content-type.
+    # Unless any format, content-type is defined as "application/x-www-form-urlencoded".
+    #
+    def format(v)
+      case @format = v
+      when :text
+        set_content_type("text/plain")
+      when :xml
+        set_content_type("text/xml application/x-xml")
+      when :json
+        set_content_type("application/json")
+      when :yaml
+        set_content_type("text/plain text/yaml")
+      else
+        set_content_type("application/x-www-form-urlencoded")
+      end
+    end
+
+    # Sets text format message. No need to use +format+.
+    #
+    def body_as_text(text)
+      @message_body_with_format = text
+      format :text
+    end
+
+    # Sets xml format message. No need to use +format+.
+    #
+    def body_as_xml(xml)
+      @message_body_with_format = xml
+      format :xml
+    end
+
+    # Sets json format message. No need to use +format+.
+    #
+    def body_as_json(json)
+      @message_body_with_format = json
+      format :json
+    end
+
+    # Sets yaml format message. No need to use +format+.
+    #
+    def body_as_yaml(yaml)
+      @message_body_with_format = yaml
+      format :yaml
+    end
+
+    # Return converted message body, as to assigned format.
+    #
+    def format_message_body
+      return @message_body_with_format  if @message_body_with_format
+
+      case @format
+      when :text
+        return @message_body.to_s
+      when :xml
+        return @message_body.to_xml @to_xml_options
+      when :json
+        return @message_body.to_json
+      when :yaml
+        return @message_body.to_yaml
+      else
+        @message_body.each do |k,v|
+          if v.kind_of? ActiveRecord::Base
+            @message_body[k] = v.attributes
+          end
+        end
+        return query_string(@message_body)
+      end
+    end
+
+    private
+    def query_string(hash)
+      build_query_string(hash, nil, nil)
+    end
+
+    def build_query_string(hash, query = nil, top = nil)
+      query ||= []
+      top ||= ""
+
+      _top = top.dup
+
+      hash.each do |k,v|
+        top = _top
+        top += top == "" ? "#{urlencode(k.to_s)}" : "[#{urlencode(k.to_s)}]"
+        if v.kind_of? Hash
+          build_query_string(v, query, top)
+        elsif v.kind_of? Array
+          v.each do |e|
+            query << "#{top}[]=#{urlencode(e.to_s)}"
+          end
+        else
+          query << "#{top}=#{urlencode(v.to_s)}"
+        end
+      end
+      query.join('&')
+    end
+
+    def simple_url_encoded_form_data(params, sep = '&')
+      params.map {|k,v| "#{urlencode(k.to_s)}=#{urlencode(v.to_s)}" }.join(sep)
+    end
+
+    def urlencode(str)
+      str.gsub(/[^a-zA-Z0-9_\.\-]/n) {|s| sprintf('%%%02x', s[0]) }
+    end
+
+    def set_content_type(type)
+      http_header("Content-type", type)
+    end
+  end
+end