fdv-actionwebservice 2.3.8

data/examples/metaWeblog/controllers/xmlrpc_controller.rb

@@ -0,0 +1,16 @@
+#
+# example controller implementing both blogger and metaWeblog APIs
+# in a way that should be compatible with clients supporting both/either.
+#
+# test by pointing your client at http://URL/xmlrpc/api
+# 
+
+require 'meta_weblog_service'
+require 'blogger_service'
+
+class XmlrpcController < ApplicationController
+  web_service_dispatching_mode :layered
+
+  web_service :metaWeblog, MetaWeblogService.new
+  web_service :blogger, BloggerService.new
+end

data/generators/web_service/USAGE

@@ -0,0 +1,28 @@
+Description:
+    The web service generator creates the controller and API definition for 
+    a web service.
+
+    The generator takes a web service name and a list of API methods as arguments.
+    The web service name may be given in CamelCase or under_score and should
+    contain no extra suffixes.  To create a web service within a
+    module, specify the web service name as 'module/webservice'.
+
+    The generator creates a controller class in app/controllers, an API definition
+    in app/apis, and a functional test suite in test/functional.
+
+Example:
+    ./script/generate web_service User add edit list remove
+
+    User web service.
+        Controller: app/controllers/user_controller.rb
+        API:        app/apis/user_api.rb
+        Test:       test/functional/user_api_test.rb
+
+Modules Example:
+    ./script/generate web_service 'api/registration' register renew
+
+    Registration web service.
+        Controller: app/controllers/api/registration_controller.rb
+        API:        app/apis/api/registration_api.rb
+        Test:       test/functional/api/registration_api_test.rb
+

data/generators/web_service/templates/api_definition.rb

@@ -0,0 +1,5 @@
+class <%= class_name %>Api < ActionWebService::API::Base
+<% for method_name in args -%>
+  api_method :<%= method_name %>
+<% end -%>
+end

data/generators/web_service/templates/controller.rb

@@ -0,0 +1,8 @@
+class <%= class_name %>Controller < ApplicationController
+  wsdl_service_name '<%= class_name %>'
+<% for method_name in args -%>
+
+  def <%= method_name %>
+  end
+<% end -%>
+end

data/generators/web_service/templates/functional_test.rb

@@ -0,0 +1,19 @@
+require File.dirname(__FILE__) + '<%= '/..' * class_nesting_depth %>/../test_helper'
+require '<%= file_path %>_controller'
+
+class <%= class_name %>Controller; def rescue_action(e) raise e end; end
+
+class <%= class_name %>ControllerApiTest < Test::Unit::TestCase
+  def setup
+    @controller = <%= class_name %>Controller.new
+    @request    = ActionController::TestRequest.new
+    @response   = ActionController::TestResponse.new
+  end
+<% for method_name in args -%>
+
+  def test_<%= method_name %>
+    result = invoke :<%= method_name %>
+    assert_equal nil, result
+  end
+<% end -%>
+end

data/generators/web_service/web_service_generator.rb

@@ -0,0 +1,29 @@
+class WebServiceGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      # Check for class naming collisions.
+      m.class_collisions class_path, "#{class_name}Api", "#{class_name}Controller", "#{class_name}ApiTest"
+
+      # API and test directories.
+      m.directory File.join('app/services', class_path)
+      m.directory File.join('app/controllers', class_path)
+      m.directory File.join('test/functional', class_path)
+
+      # API definition, controller, and functional test.
+      m.template 'api_definition.rb',
+                  File.join('app/services',
+                            class_path,
+                            "#{file_name}_api.rb")
+
+      m.template 'controller.rb',
+                  File.join('app/controllers',
+                            class_path,
+                            "#{file_name}_controller.rb")
+
+      m.template 'functional_test.rb',
+                  File.join('test/functional',
+                            class_path,
+                            "#{file_name}_api_test.rb")
+    end
+  end
+end

data/lib/action_web_service.rb

@@ -0,0 +1,66 @@
+#--
+# Copyright (C) 2005 Leon Breedt
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+begin
+  require 'active_support'
+  require 'action_controller'
+  require 'active_record'
+rescue LoadError
+  require 'rubygems'
+  gem 'activesupport', '>= 2.3.0'
+  gem 'actionpack', '>= 2.3.0'
+  gem 'activerecord', '>= 2.3.0'
+end
+
+$:.unshift(File.dirname(__FILE__) + "/action_web_service/vendor/")
+
+require 'action_web_service/support/class_inheritable_options'
+require 'action_web_service/support/signature_types'
+require 'action_web_service/base'
+require 'action_web_service/client'
+require 'action_web_service/invocation'
+require 'action_web_service/api'
+require 'action_web_service/casting'
+require 'action_web_service/struct'
+require 'action_web_service/container'
+require 'action_web_service/protocol'
+require 'action_web_service/dispatcher'
+require 'action_web_service/scaffolding'
+
+ActionWebService::Base.class_eval do
+  include ActionWebService::Container::Direct
+  include ActionWebService::Invocation
+end
+
+ActionController::Base.class_eval do
+  include ActionWebService::Protocol::Discovery
+  include ActionWebService::Protocol::Soap
+  include ActionWebService::Protocol::XmlRpc
+  include ActionWebService::Container::Direct
+  include ActionWebService::Container::Delegated
+  include ActionWebService::Container::ActionController
+  include ActionWebService::Invocation
+  include ActionWebService::Dispatcher
+  include ActionWebService::Dispatcher::ActionController
+  include ActionWebService::Scaffolding
+end

data/lib/action_web_service/api.rb

@@ -0,0 +1,297 @@
+module ActionWebService # :nodoc:
+  module API # :nodoc:
+    # A web service API class specifies the methods that will be available for
+    # invocation for an API. It also contains metadata such as the method type
+    # signature hints.
+    #
+    # It is not intended to be instantiated.
+    #
+    # It is attached to web service implementation classes like
+    # ActionWebService::Base and ActionController::Base derivatives by using
+    # <tt>container.web_service_api</tt>, where <tt>container</tt> is an
+    # ActionController::Base or a ActionWebService::Base.
+    #
+    # See ActionWebService::Container::Direct::ClassMethods for an example
+    # of use.
+    class Base
+      # Whether to transform the public API method names into camel-cased names 
+      class_inheritable_option :inflect_names, true
+
+      # By default only HTTP POST requests are processed
+      class_inheritable_option :allowed_http_methods, [ :post ]
+       
+      # Whether to allow ActiveRecord::Base models in <tt>:expects</tt>.
+      # The default is +false+; you should be aware of the security implications
+      # of allowing this, and ensure that you don't allow remote callers to
+      # easily overwrite data they should not have access to.
+      class_inheritable_option :allow_active_record_expects, false
+
+      # 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_api_method
+
+      # Disallow instantiation
+      private_class_method :new, :allocate
+      
+      class << self
+        include ActionWebService::SignatureTypes
+
+        # API methods have a +name+, which must be the Ruby method name to use when
+        # performing the invocation on the web service object.
+        #
+        # The signatures for the method input parameters and return value can
+        # by specified in +options+.
+        #
+        # A signature is an array of one or more parameter specifiers. 
+        # A parameter specifier can be one of the following:
+        #
+        # * A symbol or string representing one of the Action Web Service base types.
+        #   See ActionWebService::SignatureTypes for a canonical list of the base types.
+        # * The Class object of the parameter type
+        # * A single-element Array containing one of the two preceding items. This
+        #   will cause Action Web Service to treat the parameter at that position
+        #   as an array containing only values of the given type.
+        # * A Hash containing as key the name of the parameter, and as value
+        #   one of the three preceding items
+        # 
+        # If no method input parameter or method return value signatures are given,
+        # the method is assumed to take no parameters and/or return no values of
+        # interest, and any values that are received by the server will be
+        # discarded and ignored.
+        #
+        # Valid options:
+        # [<tt>:expects</tt>]             Signature for the method input parameters
+        # [<tt>:returns</tt>]             Signature for the method return value
+        # [<tt>:expects_and_returns</tt>] Signature for both input parameters and return value
+        def api_method(name, options={})
+          unless options.is_a?(Hash)
+            raise(ActionWebServiceError, "Expected a Hash for options")
+          end
+          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
+          expects = canonical_signature(expects)
+          returns = canonical_signature(returns)
+          if expects
+            expects.each do |type|
+              type = type.element_type if type.is_a?(ArrayType)
+              if type.type_class.ancestors.include?(ActiveRecord::Base) && !allow_active_record_expects
+                raise(ActionWebServiceError, "ActiveRecord model classes not allowed in :expects")
+              end
+            end
+          end
+          name = name.to_sym
+          public_name = public_api_method_name(name)
+          method = Method.new(name, public_name, expects, returns)
+          write_inheritable_hash("api_methods", name => method)
+          write_inheritable_hash("api_public_method_names", public_name => name)
+        end
+
+        # Whether the given method name is a service method on this API
+        #
+        #   class ProjectsApi < ActionWebService::API::Base
+        #     api_method :getCount, :returns => [:int]
+        #   end
+        #
+        #   ProjectsApi.has_api_method?('GetCount')   #=> false
+        #   ProjectsApi.has_api_method?(:getCount)    #=> true
+        def has_api_method?(name)
+          api_methods.has_key?(name)
+        end
+  
+        # Whether the given public method name has a corresponding service method
+        # on this API
+        #
+        #   class ProjectsApi < ActionWebService::API::Base
+        #     api_method :getCount, :returns => [:int]
+        #   end
+        #
+        #   ProjectsApi.has_api_method?(:getCount)    #=> false
+        #   ProjectsApi.has_api_method?('GetCount')   #=> true
+        def has_public_api_method?(public_name)
+          api_public_method_names.has_key?(public_name)
+        end
+  
+        # The corresponding public method name for the given service method name
+        #
+        #   ProjectsApi.public_api_method_name('GetCount')  #=> "GetCount"
+        #   ProjectsApi.public_api_method_name(:getCount)   #=> "GetCount"
+        def public_api_method_name(name)
+          if inflect_names
+            name.to_s.camelize
+          else
+            name.to_s
+          end
+        end
+  
+        # The corresponding service method name for the given public method name
+        #
+        #   class ProjectsApi < ActionWebService::API::Base
+        #     api_method :getCount, :returns => [:int]
+        #   end
+        #        
+        #   ProjectsApi.api_method_name('GetCount') #=> :getCount
+        def api_method_name(public_name)
+          api_public_method_names[public_name]
+        end
+  
+        # A Hash containing all service methods on this API, and their
+        # associated metadata.
+        #
+        #   class ProjectsApi < ActionWebService::API::Base
+        #     api_method :getCount,          :returns => [:int]
+        #     api_method :getCompletedCount, :returns => [:int]
+        #   end
+        #
+        #   ProjectsApi.api_methods #=> 
+        #     {:getCount=>#<ActionWebService::API::Method:0x24379d8 ...>,
+        #      :getCompletedCount=>#<ActionWebService::API::Method:0x2437794 ...>}
+        #   ProjectsApi.api_methods[:getCount].public_name #=> "GetCount"
+        def api_methods
+          read_inheritable_attribute("api_methods") || {}
+        end
+
+        # The Method instance for the given public API method name, if any
+        #
+        #   class ProjectsApi < ActionWebService::API::Base
+        #     api_method :getCount,          :returns => [:int]
+        #     api_method :getCompletedCount, :returns => [:int]
+        #   end
+        #
+        #   ProjectsApi.public_api_method_instance('GetCount')  #=> <#<ActionWebService::API::Method:0x24379d8 ...>
+        #   ProjectsApi.public_api_method_instance(:getCount)   #=> nil
+        def public_api_method_instance(public_method_name)
+          api_method_instance(api_method_name(public_method_name))
+        end
+
+        # The Method instance for the given API method name, if any
+        #
+        #   class ProjectsApi < ActionWebService::API::Base
+        #     api_method :getCount,          :returns => [:int]
+        #     api_method :getCompletedCount, :returns => [:int]
+        #   end
+        #
+        #   ProjectsApi.api_method_instance(:getCount) #=> <ActionWebService::API::Method:0x24379d8 ...>
+        #   ProjectsApi.api_method_instance('GetCount') #=> <ActionWebService::API::Method:0x24379d8 ...>
+        def api_method_instance(method_name)
+          api_methods[method_name]
+        end
+
+        # The Method instance for the default API method, if any
+        def default_api_method_instance
+          return nil unless name = default_api_method
+          instance = read_inheritable_attribute("default_api_method_instance")
+          if instance && instance.name == name
+            return instance
+          end
+          instance = Method.new(name, public_api_method_name(name), nil, nil)
+          write_inheritable_attribute("default_api_method_instance", instance)
+          instance
+        end
+
+        private
+          def api_public_method_names
+            read_inheritable_attribute("api_public_method_names") || {}
+          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(ActionWebServiceError, "Unknown options: #{unknown_option_keys}")
+            end
+          end
+      end
+    end
+
+    # Represents an API method and its associated metadata, and provides functionality
+    # to assist in commonly performed API method tasks.
+    class Method
+      attr :name
+      attr :public_name
+      attr :expects
+      attr :returns
+
+      def initialize(name, public_name, expects, returns)
+        @name = name
+        @public_name = public_name
+        @expects = expects
+        @returns = returns
+        @caster = ActionWebService::Casting::BaseCaster.new(self)
+      end
+      
+      # The list of parameter names for this method
+      def param_names
+        return [] unless @expects
+        @expects.map{ |type| type.name }
+      end
+
+      # Casts a set of Ruby values into the expected Ruby values
+      def cast_expects(params)
+        @caster.cast_expects(params)
+      end
+
+      # Cast a Ruby return value into the expected Ruby value
+      def cast_returns(return_value)
+        @caster.cast_returns(return_value)
+      end
+
+      # Returns the index of the first expected parameter
+      # with the given name
+      def expects_index_of(param_name)
+        return -1 if @expects.nil?
+        (0..(@expects.length-1)).each do |i|
+          return i if @expects[i].name.to_s == param_name.to_s
+        end
+        -1
+      end
+
+      # Returns a hash keyed by parameter name for the given
+      # parameter list
+      def expects_to_hash(params)
+        return {} if @expects.nil?
+        h = {}
+        @expects.zip(params){ |type, param| h[type.name] = param }
+        h
+      end
+
+      # Backwards compatibility with previous API
+      def [](sig_type)
+        case sig_type
+        when :expects
+          @expects.map{|x| compat_signature_entry(x)}
+        when :returns
+          @returns.map{|x| compat_signature_entry(x)}
+        end
+      end
+
+      # String representation of this method
+      def to_s
+        fqn = ""
+        fqn << (@returns ? (@returns[0].human_name(false) + " ") : "void ")
+        fqn << "#{@public_name}("
+        fqn << @expects.map{ |p| p.human_name }.join(", ") if @expects
+        fqn << ")"
+        fqn
+      end
+
+      private
+        def compat_signature_entry(entry)
+          if entry.array?
+            [compat_signature_entry(entry.element_type)]
+          else
+            if entry.spec.is_a?(Hash)
+              {entry.spec.keys.first => entry.type_class}
+            else
+              entry.type_class
+            end
+          end
+        end
+    end
+  end
+end