actionservice 0.2.100 → 0.2.102

data/ChangeLog

@@ -0,0 +1,3 @@
+TBD
+
+	* First public release

data/README

@@ -1,29 +1,54 @@
-= Action Service -- Web service integration with Action Pack
+= Action Service -- Serving APIs on rails
+
+Action Service provides a way to publish interoperablel web service APIs with
+Rails without wasting time delving into protocol details.
+
+
+== Features
+
+* SOAP RPC protocol support
+* Dynamic WSDL generation
+* XML-RPC protocol support
+* Strong type signature hints to improve interoperability with static
+  languages
+* Using Active Record derivatives in return signatures automatically generates
+  a structured type equivalent that can be sent over the wire
+
+
+== Integration with Action Pack
+
+Action Service can be integrated in two different dispatching modes, _Direct_ and
+_Delegated_.
+
+
+* _Direct_ mode refers to a dispatching mode where one controller represents a
+  single API service, and actions in the controller represent API methods. This is
+  the default mode.
+* _Delegated_ mode refers to a dispatching mode where a controller is a
+  container for one or more API services, and an action on the controller
+  serves as the entry point for an associated service.
 
-FIXME
 
 == Dependencies
 
-Action Service requires that the Action Pack is either available to be required immediately
-or is accessible as a GEM.
+Action Service requires that the Action Pack and Active Record  are either
+available to be required immediately or are accessible as GEMs.
 
-It also requires a version of Ruby that includes SOAP support in the standard library. At
-least version 1.8.2 final is recommended.
+It also requires a version of Ruby that includes SOAP support in the standard
+library. At least version 1.8.2 final (2004-12-25) of Ruby is recommended.
 
 
 == Download
 
-
-FIXME
+The latest Action Service version can be downloaded from
+http://rubyforge.org/projects/actionservice
 
 
 == Installation
 
 You can install Action Service with the following command.
 
-  % [sudo] ruby install.rb
-
-from its distribution directory.
+  % [sudo] ruby setup.rb
 
 
 == License
@@ -33,4 +58,6 @@ Action Service is released under the MIT license.
 
 == Support
 
-FIXME
+The Ruby on Rails mailing list
+
+Or, to contact the author, send mail to bitserf@gmail.com

data/Rakefile

@@ -8,7 +8,7 @@ require 'rake/contrib/rubyforgepublisher'
 
 PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
 PKG_NAME      = 'actionservice'
-PKG_VERSION   = '0.2.100' + PKG_BUILD
+PKG_VERSION   = '0.2.102' + PKG_BUILD
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
 desc "Default Task"
@@ -27,12 +27,13 @@ Rake::TestTask.new { |t|
 Rake::RDocTask.new { |rdoc|
   rdoc.rdoc_dir = 'doc'
   rdoc.title    = "Action Service -- Web services for Action Pack"
-  rdoc.options << '--line-numbers --inline-source --main README'
-  rdoc.rdoc_files.include('README', 'CHANGELOG')
+  rdoc.options << '--line-numbers --inline-source --main README --accessor class_inheritable_option=RW'
+  rdoc.rdoc_files.include('README')
   rdoc.rdoc_files.include('lib/action_service.rb')
   rdoc.rdoc_files.include('lib/action_service/*.rb')
   rdoc.rdoc_files.include('lib/action_service/protocol/*.rb')
   rdoc.rdoc_files.include('lib/action_service/router/*.rb')
+  rdoc.rdoc_files.include('lib/action_service/support/*.rb')
 }
 
 
@@ -50,13 +51,14 @@ spec = Gem::Specification.new do |s|
   s.homepage = "http://rubyforge.org/projects/actionservice"
 
   s.add_dependency('actionpack', '>= 1.4.0')
+  s.add_dependency('activerecord', '>= 1.6.0')
 
   s.has_rdoc = true
   s.requirements << 'none'
   s.require_path = 'lib'
   s.autorequire = 'action_service'
 
-  s.files = [ "Rakefile", "setup.rb", "README", "TODO", "HACKING", "CHANGELOG", "MIT-LICENSE" ]
+  s.files = [ "Rakefile", "setup.rb", "README", "TODO", "HACKING", "ChangeLog", "MIT-LICENSE" ]
   s.files = s.files + Dir.glob( "examples/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
   s.files = s.files + Dir.glob( "lib/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
   s.files = s.files + Dir.glob( "test/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
@@ -96,6 +98,7 @@ task :lines do
     action_service
     action_service/protocol
     action_service/router
+    action_service/support
   }.each do |dir|
     Dir.foreach(File.join(prefix, dir)) { |file_name| 
       next unless file_name =~ /.*rb$/

data/TODO

@@ -1,30 +1,13 @@
-= Features Remaining
-  - Support for ActiveRecord model classes as structure types as well, since
-    we can reflect all the details to do proper mapping from model classes.
-
-= Ideas
-  - <nextangle> Support a second dispatching mechanism, where incoming
-                operation requests are mapped directly to a controller action.
-
-    Advantages: No seperate API service class, the controller becomes the
-                service class.
-
-    Possible approaches:
-      Create a new router that maps an 'api' action to do dispatching using
-      itself as the target service.
-
-      This dispatching would:
-
-        * Unpack request parameters into @params
-        * Execute the action
-        * Use the return value of the action to send back to the client
-
-= Warts
-  - Come up with a cleaner way for supporting XML-RPC introspection that doesn't
-    involve throwing a SystemExportNotHandledError exception.
-  - Come up with a cleaner approach for 'default_export' implementations.
-    But NOT method_missing!
-  - Create abstract SOAP test that provides helpers for doing SOAP method
-    calls, get rid of the copy & paste SOAP crap in the SOAP protocol tests
+= Tasks
+  - add better type mapping tests for XML-RPC
+  - add tests for ActiveRecord support (with mock objects?)
+
+= Refactoring
+  - Find an alternative way to map interesting types for SOAP (like ActiveRecord
+    model classes) that doesn't require creation of a sanitized copy object with data
+    copied from the real one. Ideally this would let us get rid of
+    ActionService::Struct altogether and provide a block that would yield the
+    attributes and values. "Filters" ?  Not sure how to integrate with SOAP though.
+  
   - Don't have clean way to go from SOAP Class object to the xsd:NAME type
-    string
+    string -- NaHi possibly looking at remedying this situation

data/examples/soap/app/controllers/search_controller.rb

@@ -2,7 +2,6 @@ require 'google_search_service'
 
 class SearchController < ApplicationController
   wsdl_service_name 'GoogleSearch'
+  service_dispatching_mode :delegated
   service :beta3, GoogleSearchService.new
-
-  # self.action_service_debugging = true
 end

data/examples/soap/lib/google_search_service.rb

@@ -68,7 +68,10 @@ class GoogleSearchService < ActionService::Base
 
     # For Mono, we have to clone objects if they're referenced by more than one place, otherwise
     # the Ruby SOAP collapses them into one instance and uses references all over the
-    # place, confusing Mono
+    # place, confusing Mono. 
+    #
+    # This has recently been fixed:
+    #   http://bugzilla.ximian.com/show_bug.cgi?id=72265
     result.directoryCategories = [
       category("Web Development", "UTF-8"),
       category("Programming", "US-ASCII"),
@@ -84,7 +87,7 @@ class GoogleSearchService < ActionService::Base
     cat
   end
 
-  export :doGetCachedPage,         :returns => [String], :expects => [String, String]
+  export :doGetCachedPage,         :returns => [String], :expects => [{:key=>String}, {:url=>String}]
   export :doGetSpellingSuggestion, :returns => [String], :expects => [String, String]
   export :doGoogleSearch,          :returns => [GoogleSearchResult], :expects => [String, String, Integer, Integer, TrueClass, String, TrueClass, String, String, String]
 end

data/lib/action_service/base.rb

@@ -5,63 +5,8 @@ module ActionService
   end
 
   class Base
-    class_inheritable_option :export_name_mangling, true
+    # Whether to send back a detailed stack trace to the remote caller
+    # when an exception is thrown on the server
     class_inheritable_option :report_exceptions, true
-    class_inheritable_option :logger
-    class_inheritable_option :default_export
-
-    class << self
-      def export(name, options={})
-        validate_options([:expects, :returns, :expects_and_returns], options.keys)
-        if options[:expects_and_returns]
-          expects = options[:expects_and_returns]
-          returns = options[:expects_and_returns]
-        else
-          expects = options[:expects]
-          returns = options[:returns]
-        end
-        name = name.to_sym
-        public_name = public_export_name(name)
-        info = { :expects => expects, :returns => returns }
-        write_inheritable_hash("action_service_exports", name => info)
-        write_inheritable_hash("action_service_public_exports", public_name => name)
-      end
-
-      def has_export?(name)
-        exports.has_key?(name)
-      end
-
-      def has_public_export?(name)
-        public_exports.has_key?(name)
-      end
-
-      def public_export_name(export_name)
-        if export_name_mangling
-          Inflector.camelize(export_name.to_s)
-        else
-          export_name.to_s
-        end
-      end
-
-      def internal_export_name(public_name)
-        public_exports[public_name]
-      end
-
-      def exports
-        read_inheritable_attribute("action_service_exports") || {}
-      end
-
-      private
-        def public_exports
-          read_inheritable_attribute("action_service_public_exports") || {}
-        end
-
-        def validate_options(valid_option_keys, supplied_option_keys)
-          unknown_option_keys = supplied_option_keys - valid_option_keys
-          unless unknown_option_keys.empty?
-            raise(ActionServiceError, "Unknown options: #{unknown_option_keys}")
-          end
-        end
-    end
   end
 end

data/lib/action_service/container.rb

@@ -1,10 +1,14 @@
 module ActionService
   module Container
+    DirectDispatching = :direct
+    DelegatedDispatching = :delegated
+    
     class ContainerError < ActionService::ActionServiceError
     end
 
     def self.append_features(base)
       super
+      base.class_inheritable_option(:service_dispatching_mode, DirectDispatching)
       base.extend(ClassMethods)
       base.send(:include, ActionService::Container::InstanceMethods)
     end
@@ -25,7 +29,7 @@ module ActionService
       end
 
       def add_service_definition_callback(&block)
-        write_inheritable_array("action_service_definition_callbacks", [block])
+        write_inheritable_array("service_definition_callbacks", [block])
       end
 
       def has_service?(name)
@@ -37,9 +41,9 @@ module ActionService
       end
 
       private
-        def call_service_definition_callbacks(container_klass, service_name, service_info)
-          (read_inheritable_attribute("action_service_definition_callbacks") || []).each do |block|
-            block.call(container_klass, service_name, service_info)
+        def call_service_definition_callbacks(container_class, service_name, service_info)
+          (read_inheritable_attribute("service_definition_callbacks") || []).each do |block|
+            block.call(container_class, service_name, service_info)
           end
         end
     end
@@ -55,56 +59,104 @@ module ActionService
       end
 
       private
-        def dispatch_service_invocation_request(protocol, info)
-          service = service_object(info.service_name)
-          service_klass = service.class
-          method_name = service_klass.internal_export_name(info.public_method_name)
-          opts = {}
-          params = []
+        def dispatch_service_request(protocol_request)
+          case service_dispatching_mode
+          when DirectDispatching
+            dispatch_direct_service_request(protocol_request)
+          when DelegatedDispatching
+            dispatch_delegated_service_request(protocol_request)
+          else
+            raise(ContainerError, "unsupported dispatching mode '#{service_dispatching_mode}'")
+          end
+        end
+
+        def dispatch_direct_service_request(protocol_request)
+          public_method_name = protocol_request.public_method_name
+          method_name = self.class.internal_export_name(public_method_name)
+          export_info = self.class.exports[method_name]
+          protocol_request.type = Protocol::CheckedMessage
+          protocol_request.signature = export_info[:expects]
+          protocol_request.return_signature = export_info[:returns]
+          @invocation_params = protocol_request.unmarshal
+          if export_info[:expects]
+            expects = export_info[:expects]
+            @params ||= {}
+            (1..@invocation_params.size).each do |i|
+              i -= 1
+              if expects[i].is_a?(Hash)
+                @params[expects[i].keys.shift.to_s] = @invocation_params[i]
+              else
+                @params["param#{i}"] = @invocation_params[i]
+              end
+            end
+          end
+          result = send(method_name)
+          protocol_request.marshal(result)
+        end
+
+        def dispatch_delegated_service_request(protocol_request)
+          service_name = protocol_request.service_name
+          service = service_object(service_name)
+          service_class = service.class
+          public_method_name = protocol_request.public_method_name
+          method_name = service_class.internal_export_name(public_method_name)
+
+          invocation = ActionService::Invocation::InvocationRequest.new(
+            ActionService::Invocation::ConcreteInvocation,
+            public_method_name,
+            method_name)
+
           if method_name
-            export_info = service_klass.exports[method_name]
-            strict = true
+            protocol_request.type = Protocol::CheckedMessage
+            export_info = service_class.exports[method_name]
+            protocol_request.signature = export_info[:expects]
+            protocol_request.return_signature = export_info[:returns]
+            invocation.params = protocol_request.unmarshal
           else
+            protocol_request.type = Protocol::UncheckedMessage
+            invocation.type = ActionService::Invocation::VirtualInvocation
             system_exports = self.class.read_inheritable_attribute('default_system_exports') || {}
-            method_name = system_exports[protocol.class]
-            if method_name
-              opts[:system_call] = [info.public_method_name, system_exports[protocol.class]]
-              params.unshift service_klass
+            protocol = protocol_request.protocol
+            block = system_exports[protocol.class]
+            if block
+              invocation.block = block
+              invocation.block_params << service_class
             else
-              method_name = service_klass.default_export
-              method_name = method_name.to_sym if method_name
-              unless method_name
-                raise(ContainerError, "no such method /#{info.service_name}##{info.public_method_name}()")
+              method_name = service_class.default_export
+              if method_name && service.respond_to?(method_name)
+                invocation.params = protocol_request.unmarshal
+                invocation.method_name = method_name.to_sym
+              else
+                raise(ContainerError, "no such method /#{service_name}##{public_method_name}")
               end
             end
-            export_info = {}
-            strict = false
           end
-          opts[:require_exported] = false unless strict
-          params = params + protocol.unmarshal_request(info, export_info, strict)
+
           canceled_reason = nil
           canceled_block = lambda{|r| canceled_reason = r}
           perform_invoke = lambda do
-            service.perform_invocation(method_name, params, opts, &canceled_block)
+            service.perform_invocation(invocation, &canceled_block)
           end
-          begin
+          try_default = true
+          result = nil
+          catch(:try_default_export) do
             result = perform_invoke.call
-          rescue ActionService::Protocol::SystemExportNotHandledError => e
-            params.shift
-            method_name = service_klass.default_export
-            opts.delete(:system_call)
+            try_default = false
+          end
+          if try_default
+            method_name = service_class.default_export
             if method_name
-              method_name = method_name.to_sym
-              export_info = {}
-              strict = false
+              protocol_request.type = Protocol::UncheckedMessage
+              invocation.params = protocol_request.unmarshal
+              invocation.method_name = method_name.to_sym
+              invocation.type = ActionService::Invocation::UnexportedConcreteInvocation
             else
-              raise(ContainerError, "no such method /#{info.service_name}##{info.public_method_name}()")
+              raise(ContainerError, "no such method /#{service_name}##{public_method_name}")
             end
             result = perform_invoke.call
           end
-          protocol.marshal_response(info, export_info, result, strict)
+          protocol_request.marshal(result)
         end
-
     end
   end
 end

data/lib/action_service/exporting.rb

@@ -0,0 +1,140 @@
+module ActionService
+  module Exporting
+    class ExportError < ActionService::ActionServiceError
+    end
+
+    def self.append_features(base)
+      super
+      # Whether to mangle method names into friendly camelized names
+      # when declaring them to remote callers
+      base.class_inheritable_option :export_name_mangling, true
+    
+      # If present, the name of a method to call when the remote caller
+      # tried to call a nonexistent method. Semantically equivalent to
+      # +method_missing+.
+      base.class_inheritable_option :default_export
+
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Declares the named method to be available for remote execution.
+      #
+      # Example:
+      #
+      #   class CalculatorService < ActionService::Base
+      #     def add(a, b)
+      #       a + b
+      #     end
+      #
+      #     export :add, :expects => [Integer, Integer], :returns => [Integer]
+      #   end
+      #
+      #
+      # You will need to provide type annotation options if the method will be
+      # receiving arguments, or returning values that will be used by remote
+      # callers.
+      #
+      # A type annotation is an Array, containing as elements one or more of:
+      #
+      # * A Class object for the desired type.
+      # * An Array containing a Class object. Declares that the argument at that
+      #   position is to be an Array containing values of type Class.
+      # * A Hash containing the argument name as the key, and one of the above as
+      #   value.
+      #
+      # Valid annotations:
+      # [<tt>:expects</tt>]             The arguments that will be received by the method
+      # [<tt>:returns</tt>]             The type of the method return value. May contain only one element.
+      # [<tt>:expects_and_returns</tt>] Shortcut for specifying <tt>:expects</tt> and <tt>:returns</tt> with the same signature.
+      # 
+      # The public name of the method (that is, the name that must be used by
+      # remote callers) will be a _camelized_ version of +name+. Camelization is
+      # performed using Rails inflector camelization rules.
+      #
+      # Method name camelization can be turned off for a class by using the
+      # +export_name_mangling+ class option:
+      #
+      #   class MyService < ActionService::Base
+      #     export_name_mangling false
+      #   end
+     def export(name, options={})
+        validate_options([:expects, :returns, :expects_and_returns], options.keys)
+        if options[:expects_and_returns]
+          expects = options[:expects_and_returns]
+          returns = options[:expects_and_returns]
+        else
+          expects = options[:expects]
+          returns = options[:returns]
+        end
+        if expects
+          expects.each do |klass| 
+            klass = klass.values.shift if klass.is_a?(Hash)
+            klass = klass[0] if klass.is_a?(Array)
+            if klass.ancestors.include?(ActiveRecord::Base)
+              raise(ActionServiceError, "ActiveRecord model classes not allowed in :expects")
+            end
+          end
+        end
+        name = name.to_sym
+        public_name = public_export_name(name)
+        info = { :expects => expects, :returns => returns }
+        write_inheritable_hash("action_service_exports", name => info)
+        write_inheritable_hash("action_service_public_exports", public_name => name)
+        call_export_definition_callbacks(self, name, info)
+      end
+
+      # Whether the given name is exported by this service
+      def has_export?(name)
+        exports.has_key?(name)
+      end
+
+      # Whether the given public method name (mangled) is exported by
+      # this service
+      def has_public_export?(name)
+        public_exports.has_key?(name)
+      end
+
+      # The mangled public method name for the given method name
+      def public_export_name(export_name)
+        if export_name_mangling
+          Inflector.camelize(export_name.to_s)
+        else
+          export_name.to_s
+        end
+      end
+
+      # The internal method name for the given public method name
+      def internal_export_name(public_name)
+        public_exports[public_name]
+      end
+
+      # A Hash of method name to export information
+      def exports
+        read_inheritable_attribute("action_service_exports") || {}
+      end
+
+      def add_export_definition_callback(&block) # :nodoc:
+        write_inheritable_array("export_definition_callbacks", [block])
+      end
+
+      private
+        def call_export_definition_callbacks(service_class, export_name, export_info)
+          (read_inheritable_attribute("export_definition_callbacks") || []).each do |block|
+            block.call(service_class, export_name, export_info)
+          end
+        end
+
+        def public_exports
+          read_inheritable_attribute("action_service_public_exports") || {}
+        end
+
+        def validate_options(valid_option_keys, supplied_option_keys)
+          unknown_option_keys = supplied_option_keys - valid_option_keys
+          unless unknown_option_keys.empty?
+            raise(ActionServiceError, "Unknown options: #{unknown_option_keys}")
+          end
+        end
+    end
+  end
+end

data/lib/action_service/invocation.rb

@@ -1,5 +1,9 @@
 module ActionService
   module Invocation
+    ConcreteInvocation = :concrete
+    VirtualInvocation = :virtual
+    UnexportedConcreteInvocation = :unexported_concrete
+
     class InvocationError < ActionService::ActionServiceError
     end
 
@@ -95,29 +99,29 @@ module ActionService
         end
       end
 
-      def perform_invocation_with_interception(name, args=nil, options={}, &block)
-        return if before_invocation(name, args, &block) == false
-        result = perform_invocation_without_interception(name, args, options)
-        after_invocation(name, args, result)
+      def perform_invocation_with_interception(invocation, &block)
+        return if before_invocation(invocation.method_name, invocation.params, &block) == false
+        result = perform_invocation_without_interception(invocation)
+        after_invocation(invocation.method_name, invocation.params, result)
         result
       end
 
-      def perform_invocation(name, args=nil, options={})
-        unless options[:require_exported] == false
-          unless self.respond_to?(name) && self.class.has_export?(name)
-            raise InvocationError, "no such exported method '#{name}'"
+      def perform_invocation(invocation)
+        if invocation.concrete?
+          unless self.respond_to?(invocation.method_name) && self.class.has_export?(invocation.method_name)
+            raise InvocationError, "no such exported method '#{invocation.method_name}'"
           end
         end
-        args ||= []
-        if options[:system_call]
-          name, block = options[:system_call]
-          if block.respond_to?('call')
-            block.call(name, *args)
+        params = invocation.params
+        if invocation.concrete? || invocation.unexported_concrete?
+          self.send(invocation.method_name, *params)
+        else
+          if invocation.block
+            params = invocation.block_params + params
+            invocation.block.call(invocation.public_method_name, *params)
           else
-            self.send(block, *args)
+            self.send(invocation.method_name, *params)
           end
-        else
-          self.send(name, *args)
         end
       end
 
@@ -177,7 +181,33 @@ module ActionService
               self.class.excluded_intercepted_methods[interceptor].include?(method_name)
           end
         end
+    end
+
+    class InvocationRequest
+      attr_accessor :type
+      attr :public_method_name
+      attr_accessor :method_name
+      attr_accessor :params
+      attr_accessor :block
+      attr :block_params
+
+      def initialize(type, public_method_name, method_name, params=nil)
+        @type = type
+        @public_method_name = public_method_name
+        @method_name = method_name
+        @params = params || []
+        @block = nil
+        @block_params = []
+      end
+
+      def concrete?
+        @type == ConcreteInvocation ? true : false
+      end
 
+      def unexported_concrete?
+        @type == UnexportedConcreteInvocation ? true : false
+      end
     end
+
   end
 end