keshav-actionwebservice 1.0.0

data/lib/action_web_service/client.rb

@@ -0,0 +1,3 @@
+require 'action_web_service/client/base'
+require 'action_web_service/client/soap_client'
+require 'action_web_service/client/xmlrpc_client'

data/lib/action_web_service/client/base.rb

@@ -0,0 +1,28 @@
+module ActionWebService # :nodoc:
+  module Client # :nodoc:
+    class ClientError < StandardError # :nodoc:
+    end
+
+    class Base # :nodoc:
+      def initialize(api, endpoint_uri)
+        @api = api
+        @endpoint_uri = endpoint_uri
+      end
+
+      def method_missing(name, *args) # :nodoc:
+        call_name = method_name(name)
+        return super(name, *args) if call_name.nil?
+        self.perform_invocation(call_name, args)
+      end
+
+      private
+        def method_name(name)
+          if @api.has_api_method?(name.to_sym)
+            name.to_s
+          elsif @api.has_public_api_method?(name.to_s)
+            @api.api_method_name(name.to_s).to_s
+          end
+        end
+    end
+  end
+end

data/lib/action_web_service/client/soap_client.rb

@@ -0,0 +1,113 @@
+require 'soap/rpc/driver'
+require 'uri'
+
+module ActionWebService # :nodoc:
+  module Client # :nodoc:
+
+    # Implements SOAP client support (using RPC encoding for the messages).
+    #
+    # ==== Example Usage
+    #
+    #   class PersonAPI < ActionWebService::API::Base
+    #     api_method :find_all, :returns => [[Person]]
+    #   end
+    #
+    #   soap_client = ActionWebService::Client::Soap.new(PersonAPI, "http://...")
+    #   persons = soap_client.find_all
+    #
+    class Soap < Base
+      # provides access to the underlying soap driver
+      attr_reader :driver
+
+      # Creates a new web service client using the SOAP RPC protocol.
+      #
+      # +api+ must be an ActionWebService::API::Base derivative, and
+      # +endpoint_uri+ must point at the relevant URL to which protocol requests
+      # will be sent with HTTP POST.
+      #
+      # Valid options:
+      # [<tt>:namespace</tt>]    If the remote server has used a custom namespace to
+      #                          declare its custom types, you can specify it here. This would
+      #                          be the namespace declared with a [WebService(Namespace = "http://namespace")] attribute
+      #                          in .NET, for example.
+      # [<tt>:driver_options</tt>]    If you want to supply any custom SOAP RPC driver
+      #                               options, you can provide them as a Hash here
+      #
+      # The <tt>:driver_options</tt> option can be used to configure the backend SOAP
+      # RPC driver. An example of configuring the SOAP backend to do
+      # client-certificate authenticated SSL connections to the server:
+      #
+      #   opts = {}
+      #   opts['protocol.http.ssl_config.verify_mode'] = 'OpenSSL::SSL::VERIFY_PEER'
+      #   opts['protocol.http.ssl_config.client_cert'] = client_cert_file_path
+      #   opts['protocol.http.ssl_config.client_key'] = client_key_file_path
+      #   opts['protocol.http.ssl_config.ca_file'] = ca_cert_file_path
+      #   client = ActionWebService::Client::Soap.new(api, 'https://some/service', :driver_options => opts)
+      def initialize(api, endpoint_uri, options={})
+        super(api, endpoint_uri)
+        @namespace = options[:namespace] || 'urn:ActionWebService'
+        @driver_options = options[:driver_options] || {}
+        @protocol = ActionWebService::Protocol::Soap::SoapProtocol.new @namespace
+        @soap_action_base = options[:soap_action_base]
+        @soap_action_base ||= URI.parse(endpoint_uri).path
+        @driver = create_soap_rpc_driver(api, endpoint_uri)
+        @driver_options.each do |name, value|
+          @driver.options[name.to_s] = value
+        end
+      end
+
+      protected
+        def perform_invocation(method_name, args)
+          method = @api.api_methods[method_name.to_sym]
+          args = method.cast_expects(args.dup) rescue args
+          return_value = @driver.send(method_name, *args)
+          method.cast_returns(return_value.dup) rescue return_value
+        end
+
+        def soap_action(method_name)
+          "#{@soap_action_base}/#{method_name}"
+        end
+
+      private
+        def create_soap_rpc_driver(api, endpoint_uri)
+          @protocol.register_api(api)
+          driver = SoapDriver.new(endpoint_uri, nil)
+          driver.mapping_registry = @protocol.marshaler.registry
+          api.api_methods.each do |name, method|
+            qname = XSD::QName.new(@namespace, method.public_name)
+            action = soap_action(method.public_name)
+            expects = method.expects
+            returns = method.returns
+            param_def = []
+            if expects
+              expects.each do |type|
+                type_binding = @protocol.marshaler.lookup_type(type)
+                if SOAP::Version >= "1.5.5"
+                  param_def << ['in', type.name.to_s, [type_binding.type.type_class.to_s]]
+                else
+                  param_def << ['in', type.name, type_binding.mapping]
+                end
+              end
+            end
+            if returns
+              type_binding = @protocol.marshaler.lookup_type(returns[0])
+              if SOAP::Version >= "1.5.5"
+                param_def << ['retval', 'return', [type_binding.type.type_class.to_s]]
+              else
+                param_def << ['retval', 'return', type_binding.mapping]
+              end
+            end
+            driver.add_method(qname, action, method.name.to_s, param_def)
+          end
+          driver
+        end
+
+        class SoapDriver < SOAP::RPC::Driver # :nodoc:
+          def add_method(qname, soapaction, name, param_def)
+            @proxy.add_rpc_method(qname, soapaction, name, param_def)
+            add_rpc_method_interface(name, param_def)
+          end
+        end
+    end
+  end
+end

data/lib/action_web_service/client/xmlrpc_client.rb

@@ -0,0 +1,58 @@
+require 'uri'
+require 'xmlrpc/client'
+
+module ActionWebService # :nodoc:
+  module Client # :nodoc:
+
+    # Implements XML-RPC client support
+    #
+    # ==== Example Usage
+    #
+    #   class BloggerAPI < ActionWebService::API::Base
+    #     inflect_names false
+    #     api_method :getRecentPosts, :returns => [[Blog::Post]]
+    #   end
+    #
+    #   blog = ActionWebService::Client::XmlRpc.new(BloggerAPI, "http://.../RPC", :handler_name => "blogger")
+    #   posts = blog.getRecentPosts
+    class XmlRpc < Base
+
+      # Creates a new web service client using the XML-RPC protocol.
+      #
+      # +api+ must be an ActionWebService::API::Base derivative, and
+      # +endpoint_uri+ must point at the relevant URL to which protocol requests
+      # will be sent with HTTP POST.
+      #
+      # Valid options:
+      # [<tt>:handler_name</tt>]    If the remote server defines its services inside special
+      #                             handler (the Blogger API uses a <tt>"blogger"</tt> handler name for example),
+      #                             provide it here, or your method calls will fail
+      def initialize(api, endpoint_uri, options={})
+        @api = api
+        @handler_name = options[:handler_name]
+        @protocol = ActionWebService::Protocol::XmlRpc::XmlRpcProtocol.new
+        @client = XMLRPC::Client.new2(endpoint_uri, options[:proxy], options[:timeout])
+      end
+
+      protected
+        def perform_invocation(method_name, args)
+          method = @api.api_methods[method_name.to_sym]
+          if method.expects && method.expects.length != args.length
+            raise(ArgumentError, "#{method.public_name}: wrong number of arguments (#{args.length} for #{method.expects.length})")
+          end
+          args = method.cast_expects(args.dup) rescue args
+          if method.expects
+            method.expects.each_with_index{ |type, i| args[i] = @protocol.value_to_xmlrpc_wire_format(args[i], type) }
+          end
+          ok, return_value = @client.call2(public_name(method_name), *args)
+          return (method.cast_returns(return_value.dup) rescue return_value) if ok
+          raise(ClientError, "#{return_value.faultCode}: #{return_value.faultString}")
+        end
+
+        def public_name(method_name)
+          public_name = @api.public_api_method_name(method_name)
+          @handler_name ? "#{@handler_name}.#{public_name}" : public_name
+        end
+    end
+  end
+end

data/lib/action_web_service/container.rb

@@ -0,0 +1,3 @@
+require 'action_web_service/container/direct_container'
+require 'action_web_service/container/delegated_container'
+require 'action_web_service/container/action_controller_container'

data/lib/action_web_service/container/action_controller_container.rb

@@ -0,0 +1,94 @@
+module ActionWebService # :nodoc:
+  module Container # :nodoc:
+    module ActionController # :nodoc:
+      def self.included(base) # :nodoc:
+        class << base
+          include ClassMethods
+          alias_method_chain :inherited, :api
+          alias_method_chain :web_service_api, :require
+        end
+      end
+
+      module ClassMethods
+        # Creates a client for accessing remote web services, using the
+        # given +protocol+ to communicate with the +endpoint_uri+.
+        #
+        # ==== Example
+        #
+        #   class MyController < ActionController::Base
+        #     web_client_api :blogger, :xmlrpc, "http://blogger.com/myblog/api/RPC2", :handler_name => 'blogger'
+        #   end
+        #
+        # In this example, a protected method named <tt>blogger</tt> will
+        # now exist on the controller, and calling it will return the
+        # XML-RPC client object for working with that remote service.
+        #
+        # +options+ is the set of protocol client specific options (see
+        # a protocol client class for details).
+        #
+        # If your API definition does not exist on the load path with the
+        # correct rules for it to be found using +name+, you can pass in
+        # the API definition class via +options+, using a key of <tt>:api</tt>
+        def web_client_api(name, protocol, endpoint_uri, options={})
+          unless method_defined?(name)
+            api_klass = options.delete(:api) || require_web_service_api(name)
+            class_eval do
+              define_method(name) do
+                create_web_service_client(api_klass, protocol, endpoint_uri, options)
+              end
+              protected name
+            end
+          end
+        end
+
+        def web_service_api_with_require(definition=nil) # :nodoc:
+          return web_service_api_without_require if definition.nil?
+          case definition
+          when String, Symbol
+            klass = require_web_service_api(definition)
+          else
+            klass = definition
+          end
+          web_service_api_without_require(klass)
+        end
+
+        def require_web_service_api(name) # :nodoc:
+          case name
+          when String, Symbol
+            file_name = name.to_s.underscore + "_api"
+            class_name = file_name.camelize
+            class_names = [class_name, class_name.sub(/Api$/, 'API')]
+            begin
+              require_dependency(file_name)
+            rescue LoadError => load_error
+	      #requiree = / -- (.*?)(\.rb)?$/.match(load_error).to_a[1]
+              requiree = / -- (.*?)(\.rb)?$/.match(load_error.to_s).to_a[1]
+              msg = requiree == file_name ? "Missing API definition file in apis/#{file_name}.rb" : "Can't load file: #{requiree}"
+              raise LoadError.new(msg).copy_blame!(load_error)
+            end
+            klass = nil
+            class_names.each do |name|
+              klass = name.constantize rescue nil
+              break unless klass.nil?
+            end
+            unless klass
+              raise(NameError, "neither #{class_names[0]} or #{class_names[1]} found")
+            end
+            klass
+          else
+            raise(ArgumentError, "expected String or Symbol argument")
+          end
+        end
+
+        private
+          def inherited_with_api(child)
+            inherited_without_api(child)
+            begin child.web_service_api(child.controller_path)
+            rescue MissingSourceFile => e
+              raise unless e.is_missing?("apis/#{child.controller_path}_api")
+            end
+          end
+      end
+    end
+  end
+end

data/lib/action_web_service/container/delegated_container.rb

@@ -0,0 +1,86 @@
+module ActionWebService # :nodoc:
+  module Container # :nodoc:
+    module Delegated # :nodoc:
+      class ContainerError < ActionWebServiceError # :nodoc:
+      end
+  
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+        base.send(:include, ActionWebService::Container::Delegated::InstanceMethods)
+      end
+  
+      module ClassMethods
+        # Declares a web service that will provide access to the API of the given
+        # +object+. +object+ must be an ActionWebService::Base derivative.
+        #
+        # Web service object creation can either be _immediate_, where the object
+        # instance is given at class definition time, or _deferred_, where
+        # object instantiation is delayed until request time.
+        #
+        # ==== Immediate web service object example
+        #
+        #   class ApiController < ApplicationController
+        #     web_service_dispatching_mode :delegated
+        #
+        #     web_service :person, PersonService.new
+        #   end
+        #
+        # For deferred instantiation, a block should be given instead of an
+        # object instance. This block will be executed in controller instance
+        # context, so it can rely on controller instance variables being present.
+        #
+        # ==== Deferred web service object example
+        #
+        #   class ApiController < ApplicationController
+        #     web_service_dispatching_mode :delegated
+        #
+        #     web_service(:person) { PersonService.new(request.env) }
+        #   end
+        def web_service(name, object=nil, &block)
+          if (object && block_given?) || (object.nil? && block.nil?)
+            raise(ContainerError, "either service, or a block must be given")
+          end
+          name = name.to_sym
+          if block_given?
+            info = { name => { :block => block } }
+          else
+            info = { name => { :object => object } }
+          end
+          write_inheritable_hash("web_services", info)
+          call_web_service_definition_callbacks(self, name, info)
+        end
+  
+        # Whether this service contains a service with the given +name+
+        def has_web_service?(name)
+          web_services.has_key?(name.to_sym)
+        end
+  
+        def web_services # :nodoc:
+          read_inheritable_attribute("web_services") || {}
+        end
+  
+        def add_web_service_definition_callback(&block) # :nodoc:
+          write_inheritable_array("web_service_definition_callbacks", [block])
+        end
+  
+        private
+          def call_web_service_definition_callbacks(container_class, web_service_name, service_info)
+            (read_inheritable_attribute("web_service_definition_callbacks") || []).each do |block|
+              block.call(container_class, web_service_name, service_info)
+            end
+          end
+      end
+  
+      module InstanceMethods # :nodoc:
+        def web_service_object(web_service_name)
+          info = self.class.web_services[web_service_name.to_sym]
+          unless info
+            raise(ContainerError, "no such web service '#{web_service_name}'")
+          end
+          service = info[:block]
+          service ? self.instance_eval(&service) : info[:object]
+        end
+      end
+    end
+  end
+end

data/lib/action_web_service/container/direct_container.rb

@@ -0,0 +1,69 @@
+module ActionWebService # :nodoc:
+  module Container # :nodoc:
+    module Direct # :nodoc:
+      class ContainerError < ActionWebServiceError # :nodoc:
+      end
+
+      def self.included(base) # :nodoc:
+        base.extend(ClassMethods)
+      end
+  
+      module ClassMethods
+        # Attaches ActionWebService API +definition+ to the calling class.
+        #
+        # Action Controllers can have a default associated API, removing the need
+        # to call this method if you follow the Action Web Service naming conventions.
+        #
+        # A controller with a class name of GoogleSearchController will
+        # implicitly load <tt>app/apis/google_search_api.rb</tt>, and expect the
+        # API definition class to be named <tt>GoogleSearchAPI</tt> or
+        # <tt>GoogleSearchApi</tt>.
+        #
+        # ==== Service class example
+        #
+        #   class MyService < ActionWebService::Base
+        #     web_service_api MyAPI
+        #   end
+        #
+        #   class MyAPI < ActionWebService::API::Base
+        #     ...
+        #   end
+        #
+        # ==== Controller class example
+        #
+        #   class MyController < ActionController::Base
+        #     web_service_api MyAPI
+        #   end
+        #
+        #   class MyAPI < ActionWebService::API::Base
+        #     ...
+        #   end
+        def web_service_api(definition=nil)
+          if definition.nil?
+            read_inheritable_attribute("web_service_api")
+          else
+            if definition.is_a?(Symbol)
+              raise(ContainerError, "symbols can only be used for #web_service_api inside of a controller")
+            end
+            unless definition.respond_to?(:ancestors) && definition.ancestors.include?(ActionWebService::API::Base)
+              raise(ContainerError, "#{definition.to_s} is not a valid API definition")
+            end
+            write_inheritable_attribute("web_service_api", definition)
+            call_web_service_api_callbacks(self, definition)
+          end
+        end
+  
+        def add_web_service_api_callback(&block) # :nodoc:
+          write_inheritable_array("web_service_api_callbacks", [block])
+        end
+  
+        private
+          def call_web_service_api_callbacks(container_class, definition)
+            (read_inheritable_attribute("web_service_api_callbacks") || []).each do |block|
+              block.call(container_class, definition)
+            end
+          end
+      end
+    end
+  end
+end