actionservice 0.2.102 → 0.3.0

data/lib/action_service/base.rb

@@ -1,12 +1,50 @@
 require 'action_service/support/class_inheritable_options'
 
-module ActionService
-  class ActionServiceError < StandardError
+module ActionService # :nodoc:
+  class ActionServiceError < StandardError # :nodoc:
   end
 
+  # Action Service objects implement an exported API. Used in controllers
+  # operating in _Delegated_ dispatching mode.
+  #
+  # An ActionService::Base derivative is the <em>public interface</em>
+  # of an API.
+  #
+  # === Example
+  #
+  #   class SearchCriteria < ActionStruct::Base
+  #     member :firstname, String
+  #     member :lastname, String
+  #     member :email, String
+  #   end
+  #
+  #   class PersonApi < ActionService::Base
+  #     def find_person(criteria)
+  #       Person.find_all [...]
+  #     end
+  #
+  #     def delete_person(id)
+  #       Person.find_by_id(id).destroy
+  #     end
+  #
+  #     export :find_person, :expects => [SearchCriteria], :returns => [[Person]]
+  #     export :delete_person, :expects => [Integer]
+  #   end
+  #
+  # See ActionService::Exporting::ClassMethods for more details on the syntax
+  # for declaring exported methods.
   class Base
     # 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
+
+    # Whether to mangle method names into friendly camelized names
+    # when declaring them to remote callers
+    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+.
+    class_inheritable_option :default_export
   end
 end

data/lib/action_service/container.rb

@@ -1,12 +1,12 @@
-module ActionService
-  module Container
+module ActionService # :nodoc:
+  module Container # :nodoc:
     DirectDispatching = :direct
     DelegatedDispatching = :delegated
     
-    class ContainerError < ActionService::ActionServiceError
+    class ContainerError < ActionService::ActionServiceError # :nodoc:
     end
 
-    def self.append_features(base)
+    def self.append_features(base) # :nodoc:
       super
       base.class_inheritable_option(:service_dispatching_mode, DirectDispatching)
       base.extend(ClassMethods)
@@ -14,7 +14,36 @@ module ActionService
     end
 
     module ClassMethods
-      def service(name, object=nil, options={}, &block)
+      # Declares a service that will provides access to the exported API
+      # of the given service +object+. +object+ must be an ActionService::Base
+      # derivative.
+      #
+      # === Example
+      #
+      #   class ApiController < ApplicationController
+      #     service_dispatching_mode :delegated
+      #
+      #     service :person, PersonApi.new
+      #   end
+      #
+      # This will generate a <tt>/api/person</tt> action in the controller.
+      # All exported methods of +object+ will be available for invocation by
+      # clients sending protocol messages to <tt>/api/person</tt> with HTTP POST.
+      #
+      # You can also declare a service that defers the service +object+
+      # creation until request time. To do this, pass a block instead of a
+      # service object instance. The block will be executed in instance
+      # context, so it will have access to controller instance variables. Its
+      # return value should be the service object.
+      #
+      # === Deferred Example
+      #
+      #   class ApiController < ApplicationController
+      #     service_dispatching_mode :delegated
+      #
+      #     service(:person) { PersonApi.new }
+      #   end
+      def service(name, object=nil, &block)
         if (object && block_given?) || (object.nil? && block.nil?)
           raise(ContainerError, "either service, or a block must be given")
         end
@@ -28,18 +57,20 @@ module ActionService
         call_service_definition_callbacks(self, name, info)
       end
 
-      def add_service_definition_callback(&block)
-        write_inheritable_array("service_definition_callbacks", [block])
-      end
-
+      # Returns +true+ if #service was used to declare a service with
+      # the given name.
       def has_service?(name)
         services.has_key?(name.to_sym)
       end
 
-      def services
+      def services # :nodoc:
         read_inheritable_attribute("action_services") || {}
       end
 
+      def add_service_definition_callback(&block) # :nodoc:
+        write_inheritable_array("service_definition_callbacks", [block])
+      end
+
       private
         def call_service_definition_callbacks(container_class, service_name, service_info)
           (read_inheritable_attribute("service_definition_callbacks") || []).each do |block|
@@ -48,7 +79,7 @@ module ActionService
         end
     end
 
-    module InstanceMethods
+    module InstanceMethods # :nodoc:
       def service_object(service_name)
         info = self.class.services[service_name.to_sym]
         unless info
@@ -73,13 +104,29 @@ module ActionService
         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]
+          block = nil
+          expects = nil
+          if method_name
+            export_info = self.class.exports[method_name]
             expects = export_info[:expects]
+            protocol_request.type = Protocol::CheckedMessage
+            protocol_request.signature = expects
+            protocol_request.return_signature = export_info[:returns]
+          else
+            protocol_request.type = Protocol::UncheckedMessage
+            system_exports = self.class.read_inheritable_attribute('default_system_exports') || {}
+            protocol = protocol_request.protocol
+            block = system_exports[protocol.class]
+            unless block
+              method_name = service_class.default_export
+              unless method_name && service.respond_to?(method_name)
+                raise(ContainerError, "no such method /#{service_name}##{public_method_name}")
+              end
+            end
+          end
+
+          @invocation_params = protocol_request.unmarshal
+          if expects
             @params ||= {}
             (1..@invocation_params.size).each do |i|
               i -= 1
@@ -90,7 +137,29 @@ module ActionService
               end
             end
           end
-          result = send(method_name)
+
+          perform_invoke = lambda do
+            if block
+              result = block.call(public_method_name, self.class, *@invocation_params)
+            else
+              result = send(method_name)
+            end
+          end
+          try_default = true
+          result = nil
+          catch(:try_default_export) do
+            result = perform_invoke.call
+            try_default = false
+          end
+          if try_default
+            method_name = self.class.default_export
+            if method_name
+              protocol_request.type = Protocol::UncheckedMessage
+            else
+              raise(ContainerError, "no such method ##{public_method_name}")
+            end
+            result = perform_invoke.call
+          end
           protocol_request.marshal(result)
         end
 

data/lib/action_service/exporting.rb

@@ -1,19 +1,13 @@
-module ActionService
-  module Exporting
-    class ExportError < ActionService::ActionServiceError
+module ActionService # :nodoc:
+  module Exporting # :nodoc:
+    class ExportError < ActionService::ActionServiceError # :nodoc:
     end
 
-    def self.append_features(base)
+    def self.append_features(base) # :nodoc:
       super
-      # Whether to mangle method names into friendly camelized names
-      # when declaring them to remote callers
+      base.class_inheritable_option :report_exceptions, true
       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
 
@@ -38,7 +32,7 @@ module ActionService
       # 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
+      # * An Array containing a Class object. Indicates 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.

data/lib/action_service/invocation.rb

@@ -1,10 +1,10 @@
-module ActionService
-  module Invocation
+module ActionService # :nodoc:
+  module Invocation # :nodoc:
     ConcreteInvocation = :concrete
     VirtualInvocation = :virtual
     UnexportedConcreteInvocation = :unexported_concrete
 
-    class InvocationError < ActionService::ActionServiceError
+    class InvocationError < ActionService::ActionServiceError # :nodoc:
     end
 
     def self.append_features(base) # :nodoc:
@@ -13,7 +13,43 @@ module ActionService
       base.send(:include, ActionService::Invocation::InstanceMethods)
     end
 
+    # Invocation interceptors provide a means to execute custom code before
+    # and after API method invocations on ActionService::Base objects when
+    # running in _Delegated_ dispatching mode.
+    #
+    # When running in _Direct_ mode, ActionController filters should be used
+    # instead.
+    #
+    # The semantics of invocation interceptors are the same as ActionController
+    # filters, and accept the same parameters and options.
+    #
+    # A _before_ interceptor can also cancel execution by returning +false+,
+    # or returning a <tt>[false, "cancel reason"]</tt> array if it wishes to supply
+    # a reason for canceling the request.
+    #
+    # === Example
+    #
+    #   class CustomService < ActionService::Base
+    #     before_invocation :intercept_add, :only => [:add]
+    #
+    #     def add(a, b)
+    #       a + b
+    #     end
+    #
+    #     export :add, :expects => [Integer, Integer], :returns => [Integer]
+    #
+    #     private
+    #       def intercept_add
+    #         return [false, "permission denied"] # cancel it
+    #       end
+    #   end
+    #
+    # Options:
+    # [<tt>:except</tt>]  A list of exports to which the interceptor will NOT apply
+    # [<tt>:only</tt>]    A list of exports to which the interceptor will apply
     module ClassMethods
+      # Appends the given +interceptors+ to be called
+      # _before_ method invocation.
       def append_before_invocation(*interceptors, &block)
         conditions = extract_conditions!(interceptors)
         interceptors << block if block_given?
@@ -21,6 +57,8 @@ module ActionService
         append_interceptors_to_chain("before", interceptors)
       end
 
+      # Prepends the given +interceptors+ to be called
+      # _before_ method invocation.
       def prepend_before_invocation(*interceptors, &block)
         conditions = extract_conditions!(interceptors)
         interceptors << block if block_given?
@@ -30,6 +68,8 @@ module ActionService
 
       alias :before_invocation :append_before_invocation
 
+      # Appends the given +interceptors+ to be called
+      # _after_ method invocation.
       def append_after_invocation(*interceptors, &block)
         conditions = extract_conditions!(interceptors)
         interceptors << block if block_given?
@@ -37,6 +77,8 @@ module ActionService
         append_interceptors_to_chain("after", interceptors)
       end
 
+      # Prepends the given +interceptors+ to be called
+      # _after_ method invocation.
       def prepend_after_invocation(*interceptors, &block)
         conditions = extract_conditions!(interceptors)
         interceptors << block if block_given?
@@ -46,24 +88,23 @@ module ActionService
 
       alias :after_invocation :append_after_invocation
 
-      def before_invocation_interceptors
+      def before_invocation_interceptors # :nodoc:
         read_inheritable_attribute("before_invocation_interceptors")
       end
 
-      def after_invocation_interceptors
+      def after_invocation_interceptors # :nodoc:
         read_inheritable_attribute("after_invocation_interceptors")
       end
 
-      def included_intercepted_methods
+      def included_intercepted_methods # :nodoc:
         read_inheritable_attribute("included_intercepted_methods") || {}
       end
       
-      def excluded_intercepted_methods
+      def excluded_intercepted_methods # :nodoc:
         read_inheritable_attribute("excluded_intercepted_methods") || {}
       end
 
       private
-        
         def append_interceptors_to_chain(condition, interceptors)
           write_inheritable_array("#{condition}_invocation_interceptors", interceptors)
         end
@@ -90,7 +131,7 @@ module ActionService
         end
     end
 
-    module InstanceMethods
+    module InstanceMethods # :nodoc:
       def self.append_features(base)
         super
         base.class_eval do
@@ -183,7 +224,7 @@ module ActionService
         end
     end
 
-    class InvocationRequest
+    class InvocationRequest # :nodoc:
       attr_accessor :type
       attr :public_method_name
       attr_accessor :method_name

data/lib/action_service/protocol/abstract.rb

@@ -1,12 +1,12 @@
-module ActionService
-  module Protocol
+module ActionService # :nodoc:
+  module Protocol # :nodoc:
     CheckedMessage = :checked
     UncheckedMessage = :unchecked
 
-    class ProtocolError < ActionService::ActionServiceError
+    class ProtocolError < ActionService::ActionServiceError # :nodoc:
     end
 
-    class AbstractProtocol
+    class AbstractProtocol # :nodoc:
       attr :container_class
 
       def initialize(container_class)
@@ -30,14 +30,16 @@ module ActionService
       end
     end
 
-    class AbstractProtocolMessage
+    class AbstractProtocolMessage # :nodoc:
       attr_accessor :signature
       attr_accessor :return_signature
       attr_accessor :type
+      attr :options
 
       def initialize(options={})
         @signature = @return_signature = nil
-        @type = options[:type] || CheckedMessage
+        @options = options
+        @type = @options[:type] || CheckedMessage
       end
 
       def signature=(value)
@@ -79,14 +81,13 @@ module ActionService
       end
     end
 
-    class ProtocolRequest < AbstractProtocolMessage
+    class ProtocolRequest < AbstractProtocolMessage # :nodoc:
       attr :protocol
       attr :raw_body
 
       attr_accessor :service_name
       attr_accessor :public_method_name
       attr_accessor :content_type
-      attr_accessor :values
 
       def initialize(protocol, raw_body, service_name, public_method_name, content_type, options={})
         super(options)
@@ -95,11 +96,10 @@ module ActionService
         @service_name = service_name
         @public_method_name = public_method_name
         @content_type = content_type
-        @values = nil
       end
 
       def unmarshal
-        @values ||= @protocol.unmarshal_request(self)
+        @protocol.unmarshal_request(self)
       end
 
       def marshal(return_value)
@@ -107,7 +107,7 @@ module ActionService
       end
     end
 
-    class ProtocolResponse < AbstractProtocolMessage
+    class ProtocolResponse < AbstractProtocolMessage # :nodoc:
       attr :protocol
       attr :raw_body
 

data/lib/action_service/protocol/registry.rb

@@ -1,17 +1,17 @@
-module ActionService
-  module Protocol
+module ActionService # :nodoc:
+  module Protocol # :nodoc:
     HeaderAndBody = :header_and_body
     BodyOnly      = :body_only
 
-    module Registry
-      def self.append_features(base)
+    module Registry # :nodoc:
+      def self.append_features(base) # :nodoc:
         super
         base.extend(ClassMethods)
         base.send(:include, ActionService::Protocol::Registry::InstanceMethods)
       end
 
-      module ClassMethods
-        def register_protocol(type, klass)
+      module ClassMethods # :nodoc:
+        def register_protocol(type, klass) # :nodoc:
           case type
           when HeaderAndBody
             write_inheritable_array("header_and_body_protocols", [klass])
@@ -23,7 +23,7 @@ module ActionService
         end
       end
 
-      module InstanceMethods
+      module InstanceMethods # :nodoc:
         private
           def probe_request_protocol(action_pack_request)
             (header_and_body_protocols + body_only_protocols).each do |protocol|