aforward-actionwebservice 2.3.8.1

data/README.rdoc

@@ -0,0 +1,410 @@
+= actionwebservice
+
+* https://github.com/aforward/actionwebservice
+
+= FORKED BASED ON ISSUES WITH RAILES 2.3.8
+
+Our project team was moving from managing gems in the environment.rb file to bundler, and an incompatibility cropped up.
+
+The old gem was included via (environment.rb):
+  config.gem 'datanoise-actionwebservice', :lib => 'actionwebservice'
+
+The new gem was included via (Gemfile):
+  gem 'datanoise-actionwebservice'
+  
+But the following error arose:
+
+  Bundler could not find compatible versions for gem "actionpack":
+  In Gemfile:
+    datanoise-actionwebservice depends on
+      actionpack (= 2.1.0, )
+
+    rails (= 2.3.8) depends on
+      actionpack (2.3.8)  
+
+
+== DESCRIPTION:
+
+Action Web Service -- Serving APIs on rails
+
+Action Web Service provides a way to publish interoperable web service APIs with
+Rails without spending a lot of time delving into protocol details.
+
+
+== FEATURES/PROBLEMS:
+
+* SOAP RPC protocol support
+* Dynamic WSDL generation for APIs
+* XML-RPC protocol support
+* Clients that use the same API definitions as the server for
+  easy interoperability with other Action Web Service based applications
+* Type signature hints to improve interoperability with static languages
+* Active Record model class support in signatures
+
+You specify the methods you want to make available as API methods in an
+ActionWebService::API::Base derivative, and then specify this API
+definition class wherever you want to use that API. 
+
+The implementation of the methods is done separately from the API
+specification.
+
+Action Web Service will camelcase the method names according to Rails Inflector
+rules for the API visible to public callers. What this means, for example,
+is that the method names in generated WSDL will be camelcased, and callers will
+have to supply the camelcased name in their requests for the request to
+succeed.
+
+If you do not desire this behaviour, you can turn it off with the
+ActionWebService::API::Base +inflect_names+ option.
+
+== SYNOPSIS:
+
+==== Inflection examples
+
+  :add       => Add
+  :find_all  => FindAll
+
+  
+==== Disabling inflection
+
+  class PersonAPI < ActionWebService::API::Base
+    inflect_names false
+  end
+
+
+==== API definition example
+
+  class PersonAPI < ActionWebService::API::Base
+    api_method :add, :expects => [:string, :string, :bool], :returns => [:int]
+    api_method :remove, :expects => [:int], :returns => [:bool]
+  end
+
+==== API usage example
+
+  class PersonController < ActionController::Base
+    web_service_api PersonAPI
+
+    def add
+    end
+
+    def remove
+    end
+  end
+
+
+== Publishing your APIs
+
+Action Web Service uses Action Pack to process protocol requests.  There are two
+modes of dispatching protocol requests, _Direct_, and _Delegated_.
+
+
+=== Direct dispatching
+
+This is the default mode. In this mode, public controller instance methods
+implement the API methods, and parameters are passed through to the methods in
+accordance with the API specification.
+
+The return value of the method is sent back as the return value to the
+caller.
+
+In this mode, a special <tt>api</tt> action is generated in the target
+controller to unwrap the protocol request, forward it on to the relevant method
+and send back the wrapped return value. <em>This action must not be
+overridden.</em>
+
+==== Direct dispatching example
+
+  class PersonController < ApplicationController
+    web_service_api PersonAPI
+
+    def add
+    end
+
+    def remove
+    end
+  end
+
+  class PersonAPI < ActionWebService::API::Base
+    ...
+  end
+
+
+For this example, protocol requests for +Add+ and +Remove+ methods sent to
+<tt>/person/api</tt> will be routed to the controller methods +add+ and +remove+.
+
+
+=== Delegated dispatching
+
+This mode can be turned on by setting the +web_service_dispatching_mode+ option
+in a controller to <tt>:delegated</tt>.
+
+In this mode, the controller contains one or more web service objects (objects
+that implement an ActionWebService::API::Base definition). These web service
+objects are each mapped onto one controller action only.
+
+==== Delegated dispatching example
+
+  class ApiController < ApplicationController
+    web_service_dispatching_mode :delegated
+
+    web_service :person, PersonService.new
+  end
+
+  class PersonService < ActionWebService::Base
+    web_service_api PersonAPI
+
+    def add
+    end
+
+    def remove
+    end
+  end
+
+  class PersonAPI < ActionWebService::API::Base
+    ...
+  end
+
+
+For this example, all protocol requests for +PersonService+ are
+sent to the <tt>/api/person</tt> action.
+
+The <tt>/api/person</tt> action is generated when the +web_service+
+method is called. <em>This action must not be overridden.</em>
+
+Other controller actions (actions that aren't the target of a +web_service+ call)
+are ignored for ActionWebService purposes, and can do normal action tasks.
+
+
+=== Layered dispatching
+
+This mode can be turned on by setting the +web_service_dispatching_mode+ option
+in a controller to <tt>:layered</tt>.
+
+This mode is similar to _delegated_ mode, in that multiple web service objects
+can be attached to one controller, however, all protocol requests are sent to a
+single endpoint.
+
+Use this mode when you want to share code between XML-RPC and SOAP clients,
+for APIs where the XML-RPC method names have prefixes. An example of such
+a method name would be <tt>blogger.newPost</tt>.
+
+
+==== Layered dispatching example
+
+
+  class ApiController < ApplicationController
+    web_service_dispatching_mode :layered
+
+    web_service :mt, MovableTypeService.new
+    web_service :blogger, BloggerService.new
+    web_service :metaWeblog, MetaWeblogService.new
+  end
+
+  class MovableTypeService < ActionWebService::Base
+    ...
+  end
+
+  class BloggerService < ActionWebService::Base
+    ...
+  end
+
+  class MetaWeblogService < ActionWebService::API::Base
+    ...
+  end
+
+
+For this example, an XML-RPC call for a method with a name like
+<tt>mt.getCategories</tt> will be sent to the <tt>getCategories</tt>
+method on the <tt>:mt</tt> service.
+
+
+== Customizing WSDL generation
+
+You can customize the names used for the SOAP bindings in the generated
+WSDL by using the wsdl_service_name option in a controller:
+
+  class WsController < ApplicationController
+    wsdl_service_name 'MyApp'
+  end
+
+You can also customize the namespace used in the generated WSDL for
+custom types and message definition types:
+
+  class WsController < ApplicationController
+    wsdl_namespace 'http://my.company.com/app/wsapi'
+  end
+
+The default namespace used is 'urn:ActionWebService', if you don't supply
+one.
+
+
+== ActionWebService and UTF-8
+
+If you're going to be sending back strings containing non-ASCII UTF-8
+characters using the <tt>:string</tt> data type, you need to make sure that
+Ruby is using UTF-8 as the default encoding for its strings.
+
+The default in Ruby is to use US-ASCII encoding for strings, which causes a string
+validation check in the Ruby SOAP library to fail and your string to be sent
+back as a Base-64 value, which may confuse clients that expected strings
+because of the WSDL.
+
+Two ways of setting the default string encoding are:
+
+* Start Ruby using the <tt>-Ku</tt> command-line option to the Ruby executable
+* Set the <tt>$KCODE</tt> flag in <tt>config/environment.rb</tt> to the
+  string <tt>'UTF8'</tt>
+
+
+== Testing your APIs
+
+
+=== Functional testing
+
+You can perform testing of your APIs by creating a functional test for the
+controller dispatching the API, and calling #invoke in the test case to
+perform the invocation.
+
+Example:
+
+  class PersonApiControllerTest < Test::Unit::TestCase
+    def setup
+      @controller = PersonController.new
+      @request    = ActionController::TestRequest.new
+      @response   = ActionController::TestResponse.new
+    end
+
+    def test_add
+      result = invoke :remove, 1
+      assert_equal true, result
+    end
+  end
+
+This example invokes the API method <tt>test</tt>, defined on 
+the PersonController, and returns the result.
+
+If you're not using SOAP (or you're having serialisation difficulties), 
+you can test XMLRPC like this:
+
+  class PersonApiControllerTest < Test::Unit::TestCase
+    def setup
+      @controller = PersonController.new
+      @request    = ActionController::TestRequest.new
+      @response   = ActionController::TestResponse.new
+
+      @protocol   = :xmlrpc # can also be :soap, the default
+    end
+
+    def test_add
+      result = invoke :remove, 1 # no change here
+      assert_equal true, result
+    end
+  end
+
+=== Scaffolding
+
+You can also test your APIs with a web browser by attaching scaffolding
+to the controller.
+
+Example:
+
+  class PersonController
+    web_service_scaffold :invocation
+  end
+
+This creates an action named <tt>invocation</tt> on the PersonController.
+
+Navigating to this action lets you select the method to invoke, supply the parameters,
+and view the result of the invocation.
+
+
+== Using the client support
+
+Action Web Service includes client classes that can use the same API
+definition as the server. The advantage of this approach is that your client
+will have the same support for Active Record and structured types as the
+server, and can just use them directly, and rely on the marshaling to Do The
+Right Thing.
+
+*Note*: The client support is intended for communication between Ruby on Rails
+applications that both use Action Web Service. It may work with other servers, but
+that is not its intended use, and interoperability can't be guaranteed, especially
+not for .NET web services. 
+
+Web services protocol specifications are complex, and Action Web Service client
+support can only be guaranteed to work with a subset.
+
+
+==== Factory created client example
+
+  class BlogManagerController < ApplicationController
+    web_client_api :blogger, :xmlrpc, 'http://url/to/blog/api/RPC2', :handler_name => 'blogger'
+  end
+
+  class SearchingController < ApplicationController
+    web_client_api :google, :soap, 'http://url/to/blog/api/beta', :service_name => 'GoogleSearch'
+  end
+
+See ActionWebService::API::ActionController::ClassMethods for more details.
+
+==== Manually created client example
+
+  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 BloggerAPI < ActionWebService::API::Base
+    inflect_names false
+    api_method :getRecentPosts, :returns => [[Blog::Post]]
+  end
+
+  blog = ActionWebService::Client::XmlRpc.new(BloggerAPI, "http://.../xmlrpc", :handler_name => "blogger")
+  posts = blog.getRecentPosts
+
+
+See ActionWebService::Client::Soap and ActionWebService::Client::XmlRpc for more details.
+
+== Dependencies
+
+Action Web 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 (2004-12-25) of Ruby is recommended; this
+is the version tested against.
+
+== REQUIREMENTS:
+
+* FIX (list of requirements)
+
+== INSTALL:
+
+gem install actionwebservice
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Andrew Forward
+
+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.

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/actionwebservice.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "action_web_service/version"
+
+Gem::Specification.new do |s|
+  s.name        = "aforward-actionwebservice"
+  s.version     = ActionWebService::VERSION::STRING
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Andrew Forward (forked from Leon Breedt, Kent Sibilev)"]
+  s.email       = ["andrew.forward@cenx.com"]
+  s.homepage    = "http://github.com/aforward/actionwebservice"
+  s.summary     = %q{Porting actionwebservice to work with Rails 2.3.8}
+  s.description = %q{Porting actionwebservice to work with Rails 2.3.8}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/autotest/discover.rb

@@ -0,0 +1,2 @@
+#Autotest.add_discovery { "rails" }
+Autotest.add_discovery { "rspec2" }

data/examples/googlesearch/README

@@ -0,0 +1,143 @@
+= Google Service example
+
+This example shows how one would implement an API like Google
+Search that uses lots of structured types.
+
+There are examples for "Direct" and "Delegated" dispatching
+modes.
+
+There is also an example for API definition file autoloading.
+
+
+= Running the examples
+
+  1. Add the files to an Action Web Service enabled Rails project.
+
+    "Direct" example:
+
+      * Copy direct/search_controller.rb to "app/controllers"
+        in a Rails project.
+      * Copy direct/google_search_api.rb to "app/apis"
+        in a Rails project
+
+    "Delegated" example:
+
+      * Copy delegated/search_controller.rb to "app/controllers"
+        in a Rails project.
+      * Copy delegated/google_search_service.rb to "lib"
+        in a Rails project.
+
+     "Autoloading" example:
+
+      * Copy autoloading/google_search_api.rb to "app/apis" (create the directory
+        if it doesn't exist) in a Rails project.
+
+      * Copy autoloading/google_search_controller.rb "app/controllers"
+        in a Rails project.
+  
+
+  2. Go to the WSDL url in a browser, and check that it looks correct.
+
+      "Direct" and "Delegated" examples:
+        http://url_to_project/search/wsdl
+
+      "Autoloading" example:
+        http://url_to_project/google_search/wsdl
+     
+     You can compare it to Google's hand-coded WSDL at http://api.google.com/GoogleSearch.wsdl
+     and see how close (or not) the generated version is. 
+     
+     Note that I used GoogleSearch as the canonical "best practice"
+     interoperable example when implementing WSDL/SOAP support, which might
+     explain extreme similarities :)
+
+
+  3. Test that it works with .NET (Mono in this example):
+
+        $ wget WSDL_URL
+        $ mv wsdl GoogleSearch.wsdl
+        $ wsdl -out:GoogleSearch.cs GoogleSearch.wsdl
+
+     Add these lines to the GoogleSearchService class body (be mindful of the 
+     wrapping):
+
+        public static void Main(string[] args)
+        {
+            GoogleSearchResult result;
+            GoogleSearchService service;
+        
+            service = new GoogleSearchService();
+            result = service.doGoogleSearch("myApiKey", "my query", 10, 30, true, "restrict", false, "lr", "ie", "oe");
+            System.Console.WriteLine("documentFiltering: {0}", result.documentFiltering);
+            System.Console.WriteLine("searchComments: {0}", result.searchComments);
+            System.Console.WriteLine("estimatedTotalResultsCount: {0}", result.estimatedTotalResultsCount);
+            System.Console.WriteLine("estimateIsExact: {0}", result.estimateIsExact);
+            System.Console.WriteLine("resultElements:");
+            foreach (ResultElement element in result.resultElements) {
+              System.Console.WriteLine("\tsummary: {0}", element.summary);
+              System.Console.WriteLine("\tURL: {0}", element.URL);
+              System.Console.WriteLine("\tsnippet: {0}", element.snippet);
+              System.Console.WriteLine("\ttitle: {0}", element.title);
+              System.Console.WriteLine("\tcachedSize: {0}", element.cachedSize);
+              System.Console.WriteLine("\trelatedInformationPresent: {0}", element.relatedInformationPresent);
+              System.Console.WriteLine("\thostName: {0}", element.hostName);
+              System.Console.WriteLine("\tdirectoryCategory: {0}", element.directoryCategory.fullViewableName);
+              System.Console.WriteLine("\tdirectoryTitle: {0}", element.directoryTitle);
+            }
+            System.Console.WriteLine("searchQuery: {0}", result.searchQuery);
+            System.Console.WriteLine("startIndex: {0}", result.startIndex);
+            System.Console.WriteLine("endIndex: {0}", result.endIndex);
+            System.Console.WriteLine("searchTips: {0}", result.searchTips);
+            System.Console.WriteLine("directoryCategories:");
+            foreach (DirectoryCategory cat in result.directoryCategories) {
+              System.Console.WriteLine("\t{0} ({1})", cat.fullViewableName, cat.specialEncoding);
+            }
+            System.Console.WriteLine("searchTime: {0}", result.searchTime);
+        }
+
+    Now compile and run:
+
+      $ mcs -reference:System.Web.Services GoogleSearch.cs
+      $ mono GoogleSearch.exe
+
+
+    If you had the application running (on the same host you got
+    the WSDL from), you should see something like this:
+
+
+        documentFiltering: True
+        searchComments:
+        estimatedTotalResultsCount: 322000
+        estimateIsExact: False
+        resultElements:
+                summary: ONlamp.com: Rolling with Ruby on Rails
+                URL: http://www.onlamp.com/pub/a/onlamp/2005/01/20/rails.html
+                snippet: Curt Hibbs shows off Ruby on Rails by building a simple ...
+                title: Teh Railz0r
+                cachedSize: Almost no lines of code!
+                relatedInformationPresent: True
+                hostName: rubyonrails.com
+                directoryCategory: Web Development
+                directoryTitle:
+        searchQuery: http://www.google.com/search?q=ruby+on+rails
+        startIndex: 10
+        endIndex: 40
+        searchTips: "on" is a very common word and was not included in your search [details]
+        directoryCategories:
+                Web Development (UTF-8)
+                Programming (US-ASCII)
+        searchTime: 1E-06
+
+
+    Also, if an API method throws an exception, it will be sent back to the
+    caller in the protocol's exception format, so they should get an exception
+    thrown on their side with a meaningful error message.
+
+    If you don't like this behaviour, you can do:
+
+      class MyController < ActionController::Base
+        web_service_exception_reporting false
+      end
+
+  4. Crack open a beer. Publishing APIs for working with the same model as
+     your Rails web app should be easy from now on :)

data/examples/googlesearch/autoloading/google_search_api.rb

@@ -0,0 +1,50 @@
+class DirectoryCategory < ActionWebService::Struct
+  member :fullViewableName, :string
+  member :specialEncoding,  :string
+end
+
+class ResultElement < ActionWebService::Struct
+  member :summary,                   :string
+  member :URL,                       :string
+  member :snippet,                   :string
+  member :title,                     :string
+  member :cachedSize,                :string
+  member :relatedInformationPresent, :bool
+  member :hostName,                  :string
+  member :directoryCategory,         DirectoryCategory
+  member :directoryTitle,            :string
+end
+
+class GoogleSearchResult < ActionWebService::Struct
+  member :documentFiltering,          :bool
+  member :searchComments,             :string
+  member :estimatedTotalResultsCount, :int
+  member :estimateIsExact,            :bool
+  member :resultElements,             [ResultElement]
+  member :searchQuery,                :string
+  member :startIndex,                 :int
+  member :endIndex,                   :int
+  member :searchTips,                 :string
+  member :directoryCategories,        [DirectoryCategory]
+  member :searchTime,                 :float
+end
+
+class GoogleSearchAPI < ActionWebService::API::Base
+  inflect_names false
+
+  api_method :doGetCachedPage,         :returns => [:string], :expects => [{:key=>:string}, {:url=>:string}]
+  api_method :doGetSpellingSuggestion, :returns => [:string], :expects => [{:key=>:string}, {:phrase=>:string}]
+
+  api_method :doGoogleSearch, :returns => [GoogleSearchResult], :expects => [
+    {:key=>:string},
+    {:q=>:string},
+    {:start=>:int},
+    {:maxResults=>:int},
+    {:filter=>:bool},
+    {:restrict=>:string},
+    {:safeSearch=>:bool},
+    {:lr=>:string},
+    {:ie=>:string},
+    {:oe=>:string}
+  ]
+end

data/examples/googlesearch/autoloading/google_search_controller.rb

@@ -0,0 +1,57 @@
+class GoogleSearchController < ApplicationController
+  wsdl_service_name 'GoogleSearch'
+
+  def doGetCachedPage
+    "<html><body>i am a cached page. my key was %s, url was %s</body></html>" % [@params['key'], @params['url']]
+  end
+
+  def doSpellingSuggestion
+    "%s: Did you mean '%s'?" % [@params['key'], @params['phrase']]
+  end
+
+  def doGoogleSearch
+    resultElement = ResultElement.new
+    resultElement.summary = "ONlamp.com: Rolling with Ruby on Rails"
+    resultElement.URL = "http://www.onlamp.com/pub/a/onlamp/2005/01/20/rails.html"
+    resultElement.snippet = "Curt Hibbs shows off Ruby on Rails by building a simple application that requires " +
+                            "almost no Ruby experience. ... Rolling with Ruby on Rails. ..."
+    resultElement.title = "Teh Railz0r"
+    resultElement.cachedSize = "Almost no lines of code!"
+    resultElement.relatedInformationPresent = true
+    resultElement.hostName = "rubyonrails.com"
+    resultElement.directoryCategory = category("Web Development", "UTF-8")
+
+    result = GoogleSearchResult.new
+    result.documentFiltering = @params['filter']
+    result.searchComments = ""
+    result.estimatedTotalResultsCount = 322000
+    result.estimateIsExact = false
+    result.resultElements = [resultElement]
+    result.searchQuery = "http://www.google.com/search?q=ruby+on+rails"
+    result.startIndex = @params['start']
+    result.endIndex = @params['start'] + @params['maxResults']
+    result.searchTips = "\"on\" is a very common word and was not included in your search [details]"
+    result.searchTime = 0.000001
+
+    # 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. 
+    #
+    # 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"),
+    ]
+
+    result
+  end
+
+  private
+    def category(name, encoding)
+      cat = DirectoryCategory.new
+      cat.fullViewableName = name.dup
+      cat.specialEncoding = encoding.dup
+      cat
+    end
+end