fdv-actionwebservice 2.3.8

data/CHANGELOG

@@ -0,0 +1,320 @@
+*2.1.0*
+
+* Porting to Rails 2.1.0 [Kent Sibilev]
+
+* Documentation for ActionWebService::API::Base. Closes #7275. [zackchandler]
+
+* Allow action_web_service to handle various HTTP methods including GET. Closes #7011. [zackchandler]
+
+* Ensure that DispatcherError is being thrown when a malformed request is received. [Kent Sibilev]
+
+* Added support for decimal types. Closes #6676. [Kent Sibilev]
+
+* Removed deprecated end_form_tag helper. [Kent Sibilev]
+
+* Removed deprecated @request and @response usages. [Kent Sibilev]
+
+* Removed deprecated end_form_tag helper. [Kent Sibilev]
+
+* Removed deprecated @request and @response usages. [Kent Sibilev]
+
+*1.2.6* (November 24th, 2007)
+
+* Depend on Action Pack 1.13.6
+
+* Depend on Active Record 1.15.6
+
+
+*1.2.5* (October 12th, 2007)
+
+* Depend on Action Pack 1.13.5
+
+* Depend on Active Record 1.15.5
+
+
+*1.2.4* (October 4th, 2007)
+
+* Depend on Action Pack 1.13.4
+
+* Depend on Active Record 1.15.4
+
+
+*1.2.3* (March 12th, 2007)
+
+* Depend on Action Pack 1.13.3
+
+
+*1.2.2* (Feburary 4th, 2007)
+
+* Depend on Action Pack 1.13.2
+
+
+*1.2.1* (January 16th, 2007)
+
+* Depend on Action Pack 1.13.1
+
+
+*1.2.0* (January 16th, 2007)
+
+* Removed invocation of deprecated before_action and around_action filter methods. Corresponding before_invocation and after_invocation methods should be used instead. #6275 [Kent Sibilev]
+
+* Provide access to the underlying SOAP driver. #6212 [bmilekic, Kent Sibilev]
+
+* ActionWebService WSDL generation ignores HTTP_X_FORWARDED_HOST [Paul Butcher <paul@paulbutcher.com>]
+
+* Tighten rescue clauses.  #5985 [james@grayproductions.net]
+
+* Fixed XMLRPC multicall when one of the called methods returns a struct object. [Kent Sibilev] 
+
+* Fix invoke_layered since api_method didn't declare :expects. Closes #4720. [Kevin Ballard <kevin@sb.org>, Kent Sibilev]
+
+
+*1.1.6* (August 10th, 2006)
+
+* Rely on Action Pack 1.12.5
+
+
+*1.1.5* (August 8th, 2006)
+
+* Rely on Action Pack 1.12.4 and Active Record 1.14.4
+
+
+*1.1.4* (June 29th, 2006)
+
+* Rely on Action Pack 1.12.3
+
+
+*1.1.3* (June 27th, 2006)
+
+* Rely on Action Pack 1.12.2 and Active Record 1.14.3
+
+
+*1.1.2* (April 9th, 2006)
+
+* Rely on Active Record 1.14.2
+
+
+*1.1.1* (April 6th, 2006)
+
+* Do not convert driver options to strings (#4499)
+
+
+*1.1.0* (March 27th, 2006)
+
+* Make ActiveWebService::Struct type reloadable
+
+* Fix scaffolding action when one of the members of a structural type has date or time type
+
+* Remove extra index hash when generating scaffold html for parameters of structural type #4374 [joe@mjg2.com]
+
+* Fix Scaffold Fails with Struct as a Parameter #4363 [joe@mjg2.com]
+
+* Fix soap type registration of multidimensional arrays (#4232)
+
+* Fix that marshaler couldn't handle ActiveRecord models defined in a different namespace (#2392).
+
+* Fix that marshaler couldn't handle structs with members of ActiveRecord type (#1889).
+
+* Fix that marshaler couldn't handle nil values for inner structs (#3576).
+
+* Fix that changes to ActiveWebService::API::Base required restarting of the server (#2390).
+
+* Fix scaffolding for signatures with :date, :time and :base64 types (#3321, #2769, #2078).
+
+* Fix for incorrect casting of TrueClass/FalseClass instances (#2633, #3421).
+
+* Fix for incompatibility problems with SOAP4R 1.5.5 (#2553) [Kent Sibilev]
+
+
+*1.0.0* (December 13th, 2005)
+
+* Become part of Rails 1.0
+
+*0.9.4* (December 7th, 2005)
+
+* Update from LGPL to MIT license as per Minero Aoki's permission. [Marcel Molina Jr.]
+
+* Rename Version constant to VERSION. #2802 [Marcel Molina Jr.]
+
+* Fix that XML-RPC date/time values did not have well-defined behaviour (#2516, #2534). This fix has one caveat, in that we can't support pre-1970 dates from XML-RPC clients.
+
+*0.9.3* (November 7th, 2005)
+
+* Upgraded to Action Pack 1.11.0 and Active Record 1.13.0
+
+
+*0.9.2* (October 26th, 2005)
+
+* Upgraded to Action Pack 1.10.2 and Active Record 1.12.2
+
+
+*0.9.1* (October 19th, 2005)
+
+* Upgraded to Action Pack 1.10.1 and Active Record 1.12.1
+
+
+*0.9.0* (October 16th, 2005)
+
+* Fix invalid XML request generation bug in test_invoke [Ken Barker]
+
+* Add XML-RPC 'system.multicall' support #1941 [jbonnar]
+
+* Fix duplicate XSD entries for custom types shared across delegated/layered services #1729 [Tyler Kovacs]
+
+* Allow multiple invocations in the same test method #1720 [dkhawk]
+
+* Added ActionWebService::API::Base.soap_client and ActionWebService::API::Base.xmlrpc_client helper methods to create the internal clients for an API, useful for testing from ./script/console
+
+* ActionWebService now always returns UTF-8 responses.
+
+
+*0.8.1* (11 July, 2005)
+
+* Fix scaffolding for Action Pack controller changes
+
+
+*0.8.0* (6 July, 2005)
+
+* Fix WSDL generation by aliasing #inherited instead of trying to overwrite it, or the WSDL action may end up not being defined in the controller
+
+* Add ActionController::Base.wsdl_namespace option, to allow overriding of the namespace used in generated WSDL and SOAP messages. This is equivalent to the [WebService(Namespace = "Value")] attribute in .NET.
+
+* Add workaround for Ruby 1.8.3's SOAP4R changing the return value of SOAP::Mapping::Registry#find_mapped_soap_class #1414 [Shugo Maeda]
+
+* Fix moduled controller URLs in WSDL, and add unit test to verify the generated URL #1428
+
+* Fix scaffolding template paths, it was broken on Win32
+
+* Fix that functional testing of :layered controllers failed when using the SOAP protocol
+
+* Allow invocation filters in :direct controllers as well, as they have access to more information regarding the web service request than ActionPack filters
+
+* Add support for a :base64 signature type #1272 [Shugo Maeda]
+
+* Fix that boolean fields were not rendered correctly in scaffolding
+
+* Fix that scaffolding was not working for :delegated dispatching
+
+* Add support for structured types as input parameters to scaffolding, this should let one test the blogging APIs using scaffolding as well
+
+* Fix that generated WSDL was not using relative_url_root for base URI #1210 [Shugo Maeda]
+
+* Use UTF-8 encoding by default for SOAP responses, but if an encoding is supplied by caller, use that for the response  #1211 [Shugo Maeda, NAKAMURA Hiroshi]
+
+* If the WSDL was retrieved over HTTPS, use HTTPS URLs in the WSDL too
+
+* Fix that casting change in 0.7.0 would convert nil values to the default value for the type instead of leaving it as nil
+
+
+*0.7.1* (20th April, 2005)
+
+* Depend on Active Record 1.10.1 and Action Pack 1.8.1
+
+
+*0.7.0* (19th April, 2005)
+
+* When casting structured types, don't try to send obj.name= unless obj responds to it, causes casting to be less likely to fail for XML-RPC
+
+* Add scaffolding via ActionController::Base.web_service_scaffold for quick testing using a web browser
+
+* ActionWebService::API::Base#api_methods now returns a hash containing ActionWebService::API::Method objects instead of hashes. However, ActionWebService::API::Method defines a #[]() backwards compatibility method so any existing code utilizing this will still work.
+
+* The :layered dispatching mode can now be used with SOAP as well, allowing you to support SOAP and XML-RPC clients for APIs like the metaWeblog API
+
+* Remove ActiveRecordSoapMarshallable workaround, see #912 for details
+
+* Generalize casting code to be used by both SOAP and XML-RPC (previously, it was only XML-RPC)
+
+* Ensure return value is properly cast as well, fixes XML-RPC interoperability with Ecto and possibly other clients
+
+* Include backtraces in 500 error responses for failed request parsing, and remove "rescue nil" statements obscuring real errors for XML-RPC
+
+* Perform casting of struct members even if the structure is already of the correct type, so that the type we specify for the struct member is always the type of the value seen by the API implementation
+
+
+*0.6.2* (27th March, 2005)
+
+* Allow method declarations for direct dispatching to declare parameters as well. We treat an arity of < 0 or > 0 as an indication that we should send through parameters. Closes #939.
+
+
+*0.6.1* (22th March, 2005)
+
+* Fix that method response QNames mismatched with that declared in the WSDL, makes SOAP::WSDLDriverFactory work against AWS again
+
+* Fix that @request.env was being modified, instead, dup the value gotten from env
+
+* Fix XML-RPC example to use :layered mode, so it works again
+
+* Support casting '0' or 0 into false, and '1' or 1 into true, when expecting a boolean value
+
+* Fix that SOAP fault response fault code values were not QName's #804
+
+
+*0.6.0* (7th March, 2005)
+
+* Add action_controller/test_invoke, used for integrating AWS with the Rails testing infrastructure
+
+* Allow passing through options to the SOAP RPC driver for the SOAP client
+
+* Make the SOAP WS marshaler use #columns to decide which fields to marshal as well, avoids providing attributes brought in by associations
+  
+* Add <tt>ActionWebService::API::Base.allow_active_record_expects</tt> option, with a default of false. Setting this to true will allow specifying ActiveRecord::Base model classes in <tt>:expects</tt>. API writers should take care to validate the received ActiveRecord model objects when turning it on, and/or have an authentication mechanism in place to reduce the security risk.
+
+* Improve error message reporting. Bugs in either AWS or the web service itself will send back a protocol-specific error report message if possible, otherwise, provide as much detail as possible.
+
+* Removed type checking of received parameters, and perform casting for XML-RPC if possible, but fallback to the received parameters if casting fails, closes #677
+
+* Refactored SOAP and XML-RPC marshaling and encoding into a small library devoted exclusively to protocol specifics, also cleaned up the SOAP marshaling approach, so that array and custom type marshaling should be a bit faster.
+
+* Add namespaced XML-RPC method name support, closes #678
+
+* Replace '::' with '..' in fully qualified type names for marshaling and WSDL. This improves interoperability with .NET, and closes #676.
+
+
+*0.5.0* (24th February, 2005)
+
+	* lib/action_service/dispatcher*: replace "router" fragments with
+	  one file for Action Controllers, moves dispatching work out of
+	  the container
+	* lib/*,test/*,examples/*: rename project to
+	  ActionWebService. prefix all generic "service" type names with web_.
+	  update all using code as well as the RDoc.
+	* lib/action_service/router/wsdl.rb: ensure that #wsdl is
+	  defined in the final container class, or the new ActionPack
+	  filtering will exclude it
+	* lib/action_service/struct.rb,test/struct_test.rb: create a
+	  default #initialize on inherit that accepts a Hash containing
+	  the default member values
+	* lib/action_service/api/action_controller.rb: add support and
+	  tests for #client_api in controller
+	* test/router_wsdl_test.rb: add tests to ensure declared
+	  service names don't contain ':', as ':' causes interoperability
+	  issues
+	* lib/*, test/*: rename "interface" concept to "api", and change all
+	  related uses to reflect this change. update all uses of Inflector
+	  to call the method on String instead.
+	* test/api_test.rb: add test to ensure API definition not
+	  instantiatable
+	* lib/action_service/invocation.rb: change @invocation_params to
+	  @method_params
+	* lib/*: update RDoc
+	* lib/action_service/struct.rb: update to support base types
+	* lib/action_service/support/signature.rb: support the notion of
+	  "base types" in signatures, with well-known unambiguous names such as :int,
+	  :bool, etc, which map to the correct Ruby class. accept the same names
+	  used by ActiveRecord as well as longer versions of each, as aliases.
+	* examples/*: update for seperate API definition updates
+	* lib/action_service/*, test/*: extensive refactoring: define API methods in
+	  a seperate class, and specify it wherever used with 'service_api'.
+	  this makes writing a client API for accessing defined API methods
+	  with ActionWebService really easy.
+	* lib/action_service/container.rb: fix a bug in default call
+	  handling for direct dispatching, and add ActionController filter
+	  support for direct dispatching.
+	* test/router_action_controller_test.rb: add tests to ensure
+	  ActionController filters are actually called.
+	* test/protocol_soap_test.rb: add more tests for direct dispatching.
+
+0.3.0
+
+	* First public release

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+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.
+

data/README

@@ -0,0 +1,381 @@
+= 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
+
+* 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
+
+
+== Defining your APIs
+
+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.
+
+
+==== Method name inflection
+
+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.
+
+
+==== 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.
+
+
+== Download
+
+The latest Action Web Service version can be downloaded from
+http://rubyforge.org/projects/actionservice
+
+
+== Installation
+
+You can install Action Web Service with the following command.
+
+  % [sudo] ruby setup.rb
+
+
+== License
+
+Action Web Service is released under the MIT license.
+
+
+== Support
+
+The Ruby on Rails mailing list
+
+Or, to contact the author, send mail to bitserf@gmail.com
+