actionwebservice 0.5.0

data/examples/metaWeblog/README

@@ -0,0 +1,16 @@
+= metaWeblog example
+
+
+This example shows how one might begin to go about adding metaWeblog
+(http://www.xmlrpc.com/metaWeblogApi) API support to a Rails-based
+blogging application.
+
+
+= Running
+
+  1. Copy blog_controller.rb to "app/controllers" in a Rails project.
+
+
+  2. Fire up a desktop blogging application (such as BloGTK on Linux),
+     point it at http://localhost:3000/blog/api, and try creating or
+     editing blog posts.

data/examples/metaWeblog/blog_controller.rb

@@ -0,0 +1,127 @@
+# point your client at http://project_url/blog/api to test
+# this
+
+# structures as defined by the metaWeblog/blogger
+# specifications.
+module Blog
+  class Enclosure < ActionWebService::Struct
+    member :url,    :string
+    member :length, :int
+    member :type,   :string
+  end
+
+  class Source < ActionWebService::Struct
+    member :url,  :string
+    member :name, :string
+  end
+
+  class Post < ActionWebService::Struct
+    member :title,       :string
+    member :link,        :string
+    member :description, :string
+    member :author,      :string
+    member :category,    :string
+    member :comments,    :string
+    member :enclosure,   Enclosure
+    member :guid,        :string
+    member :pubDate,     :string
+    member :source,      Source
+  end
+
+  class Blog < ActionWebService::Struct
+    member :url,      :string
+    member :blogid,   :string
+    member :blogName, :string
+  end
+end
+
+# skeleton metaWeblog API
+class MetaWeblogAPI < ActionWebService::API::Base
+  inflect_names false
+
+  api_method :newPost, :returns => [:string], :expects => [
+    {:blogid=>:string},
+    {:username=>:string},
+    {:password=>:string},
+    {:struct=>Blog::Post},
+    {:publish=>:bool},
+  ]
+
+  api_method :editPost, :returns => [:bool], :expects => [
+    {:postid=>:string},
+    {:username=>:string},
+    {:password=>:string},
+    {:struct=>Blog::Post},
+    {:publish=>:bool},
+  ]
+
+  api_method :getPost, :returns => [Blog::Post], :expects => [
+    {:postid=>:string},
+    {:username=>:string},
+    {:password=>:string},
+  ]
+
+  api_method :getUsersBlogs, :returns => [[Blog::Blog]], :expects => [
+    {:appkey=>:string},
+    {:username=>:string},
+    {:password=>:string},
+  ]
+
+  api_method :getRecentPosts, :returns => [[Blog::Post]], :expects => [
+    {:blogid=>:string},
+    {:username=>:string},
+    {:password=>:string},
+    {:numberOfPosts=>:int},
+  ]
+end
+
+class BlogController < ApplicationController
+  web_service_api MetaWeblogAPI
+
+  def initialize
+    @postid = 0
+  end
+
+  def newPost
+    $stderr.puts 'Creating post: username=%s password=%s struct=%s' % [
+      @params['username'],
+      @params['password'],
+      @params['struct'].inspect
+    ]
+    (@postid += 1).to_s
+  end
+
+  def editPost
+    $stderr.puts 'Editing post: username=%s password=%s struct=%s' % [
+      @params['username'],
+      @params['password'],
+      @params['struct'].inspect
+    ]
+    true
+  end
+
+  def getUsersBlogs
+    $stderr.puts "Returning user %s's blogs" % @params['username']
+    blog = Blog::Blog.new(
+      :url =>'http://blog.xeraph.org',
+      :blogid => 'sttm',
+      :blogName => 'slave to the machine'
+    )
+    [blog]
+  end
+
+  def getRecentPosts
+    $stderr.puts "Returning recent posts (%d requested)" % @params['numberOfPosts']
+    post1 = Blog::Post.new(
+      :title => 'first post!',
+      :link => 'http://blog.xeraph.org/testOne.html',
+      :description => 'this is the first post'
+    )
+    post2 = Blog::Post.new(
+      :title => 'second post!',
+      :link => 'http://blog.xeraph.org/testTwo.html',
+      :description => 'this is the second post'
+    )
+    [post1, post2]
+  end
+end

data/lib/action_web_service.rb

@@ -0,0 +1,60 @@
+#--
+# 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'
+  require_gem 'activesupport', '>= 0.9.0'
+  require_gem 'actionpack', '>= 1.4.0'
+  require_gem 'activerecord', '>= 1.6.0'
+end
+
+$:.unshift(File.dirname(__FILE__))
+
+require 'action_web_service/base'
+require 'action_web_service/client'
+require 'action_web_service/invocation'
+require 'action_web_service/api'
+require 'action_web_service/struct'
+require 'action_web_service/container'
+require 'action_web_service/protocol'
+require 'action_web_service/dispatcher'
+
+ActionWebService::Base.class_eval do
+  include ActionWebService::API
+  include ActionWebService::Invocation
+end
+
+ActionController::Base.class_eval do
+  include ActionWebService::Container
+  include ActionWebService::Protocol::Registry
+  include ActionWebService::Protocol::Soap
+  include ActionWebService::Protocol::XmlRpc
+  include ActionWebService::API
+  include ActionWebService::API::ActionController
+  include ActionWebService::Dispatcher
+  include ActionWebService::Dispatcher::ActionController
+end

data/lib/action_web_service/api.rb

@@ -0,0 +1,2 @@
+require 'action_web_service/api/abstract'
+require 'action_web_service/api/action_controller'

data/lib/action_web_service/api/abstract.rb

@@ -0,0 +1,192 @@
+module ActionWebService # :nodoc:
+  module API # :nodoc:
+    class APIError < ActionWebService::ActionWebServiceError # :nodoc:
+    end
+
+    def self.append_features(base) # :nodoc:
+      super
+      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(APIError, "symbols can only be used for #web_service_api inside of a controller")
+          end
+          unless definition.respond_to?(:ancestors) && definition.ancestors.include?(Base)
+            raise(APIError, "#{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
+
+    # 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
+    # ClassMethods#web_service_api.
+    class Base
+      # Whether to transform the public API method names into camel-cased names 
+      class_inheritable_option :inflect_names, 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_api_method
+
+      # Disallow instantiation
+      private_class_method :new, :allocate
+      
+      class << self
+        include ActionWebService::Signature
+
+        # 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 of representing one of the Action Web Service base types.
+        #   See ActionWebService::Signature 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={})
+          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) if expects
+          returns = canonical_signature(returns) if returns
+          if expects
+            expects.each do |param|
+              klass = signature_parameter_class(param)
+              klass = klass[0] if klass.is_a?(Array)
+              if klass.ancestors.include?(ActiveRecord::Base)
+                raise(ActionWebServiceError, "ActiveRecord model classes not allowed in :expects")
+              end
+            end
+          end
+          name = name.to_sym
+          public_name = public_api_method_name(name)
+          info = { :expects => expects, :returns => returns }
+          write_inheritable_hash("api_methods", name => info)
+          write_inheritable_hash("api_public_method_names", public_name => name)
+        end
+
+        # Whether the given method name is a service method on this API
+        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
+        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
+        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
+        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.
+        def api_methods
+          read_inheritable_attribute("api_methods") || {}
+        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
+  end
+end

data/lib/action_web_service/api/action_controller.rb

@@ -0,0 +1,92 @@
+module ActionWebService # :nodoc:
+  module API # :nodoc:
+    module ActionController # :nodoc:
+      def self.append_features(base) # :nodoc:
+        base.class_eval do 
+          class << self
+            alias_method :inherited_without_api, :inherited
+            alias_method :web_service_api_without_require, :web_service_api
+          end
+        end
+        base.extend(ClassMethods)
+      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 through
+        # the API definition class in +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
+                probe_protocol_client(api_klass, protocol, endpoint_uri, options)
+              end
+              protected name
+            end
+          end
+        end
+
+        def web_service_api(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]
+              raise LoadError, requiree == file_name ? "Missing API definition file in apis/#{file_name}.rb" : "Can't load file: #{requiree}"
+            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(child)
+            inherited_without_api(child)
+            child.web_service_api(child.controller_path)
+          rescue Exception => e
+          end
+      end
+    end
+  end
+end