fdv-actionwebservice 2.3.8

Sign up to get free protection for your applications and to get access to all the features.
Files changed (79) hide show
  1. data/CHANGELOG +320 -0
  2. data/MIT-LICENSE +21 -0
  3. data/README +381 -0
  4. data/Rakefile +180 -0
  5. data/TODO +32 -0
  6. data/examples/googlesearch/README +143 -0
  7. data/examples/googlesearch/autoloading/google_search_api.rb +50 -0
  8. data/examples/googlesearch/autoloading/google_search_controller.rb +57 -0
  9. data/examples/googlesearch/delegated/google_search_service.rb +108 -0
  10. data/examples/googlesearch/delegated/search_controller.rb +7 -0
  11. data/examples/googlesearch/direct/google_search_api.rb +50 -0
  12. data/examples/googlesearch/direct/search_controller.rb +58 -0
  13. data/examples/metaWeblog/README +17 -0
  14. data/examples/metaWeblog/apis/blogger_api.rb +60 -0
  15. data/examples/metaWeblog/apis/blogger_service.rb +34 -0
  16. data/examples/metaWeblog/apis/meta_weblog_api.rb +67 -0
  17. data/examples/metaWeblog/apis/meta_weblog_service.rb +48 -0
  18. data/examples/metaWeblog/controllers/xmlrpc_controller.rb +16 -0
  19. data/generators/web_service/USAGE +28 -0
  20. data/generators/web_service/templates/api_definition.rb +5 -0
  21. data/generators/web_service/templates/controller.rb +8 -0
  22. data/generators/web_service/templates/functional_test.rb +19 -0
  23. data/generators/web_service/web_service_generator.rb +29 -0
  24. data/lib/action_web_service.rb +66 -0
  25. data/lib/action_web_service/api.rb +297 -0
  26. data/lib/action_web_service/base.rb +38 -0
  27. data/lib/action_web_service/casting.rb +149 -0
  28. data/lib/action_web_service/client.rb +3 -0
  29. data/lib/action_web_service/client/base.rb +28 -0
  30. data/lib/action_web_service/client/soap_client.rb +113 -0
  31. data/lib/action_web_service/client/xmlrpc_client.rb +58 -0
  32. data/lib/action_web_service/container.rb +3 -0
  33. data/lib/action_web_service/container/action_controller_container.rb +93 -0
  34. data/lib/action_web_service/container/delegated_container.rb +86 -0
  35. data/lib/action_web_service/container/direct_container.rb +69 -0
  36. data/lib/action_web_service/dispatcher.rb +2 -0
  37. data/lib/action_web_service/dispatcher/abstract.rb +207 -0
  38. data/lib/action_web_service/dispatcher/action_controller_dispatcher.rb +379 -0
  39. data/lib/action_web_service/invocation.rb +202 -0
  40. data/lib/action_web_service/protocol.rb +4 -0
  41. data/lib/action_web_service/protocol/abstract.rb +112 -0
  42. data/lib/action_web_service/protocol/discovery.rb +37 -0
  43. data/lib/action_web_service/protocol/soap_protocol.rb +176 -0
  44. data/lib/action_web_service/protocol/soap_protocol/marshaler.rb +242 -0
  45. data/lib/action_web_service/protocol/xmlrpc_protocol.rb +122 -0
  46. data/lib/action_web_service/scaffolding.rb +281 -0
  47. data/lib/action_web_service/struct.rb +64 -0
  48. data/lib/action_web_service/support/class_inheritable_options.rb +26 -0
  49. data/lib/action_web_service/support/signature_types.rb +226 -0
  50. data/lib/action_web_service/templates/scaffolds/layout.html.erb +65 -0
  51. data/lib/action_web_service/templates/scaffolds/methods.html.erb +6 -0
  52. data/lib/action_web_service/templates/scaffolds/parameters.html.erb +29 -0
  53. data/lib/action_web_service/templates/scaffolds/result.html.erb +30 -0
  54. data/lib/action_web_service/test_invoke.rb +110 -0
  55. data/lib/action_web_service/version.rb +9 -0
  56. data/lib/actionwebservice.rb +1 -0
  57. data/setup.rb +1379 -0
  58. data/test/abstract_client.rb +183 -0
  59. data/test/abstract_dispatcher.rb +548 -0
  60. data/test/abstract_unit.rb +43 -0
  61. data/test/api_test.rb +102 -0
  62. data/test/apis/auto_load_api.rb +3 -0
  63. data/test/apis/broken_auto_load_api.rb +2 -0
  64. data/test/base_test.rb +42 -0
  65. data/test/casting_test.rb +95 -0
  66. data/test/client_soap_test.rb +155 -0
  67. data/test/client_xmlrpc_test.rb +153 -0
  68. data/test/container_test.rb +73 -0
  69. data/test/dispatcher_action_controller_soap_test.rb +139 -0
  70. data/test/dispatcher_action_controller_xmlrpc_test.rb +59 -0
  71. data/test/fixtures/db_definitions/mysql.sql +8 -0
  72. data/test/fixtures/users.yml +12 -0
  73. data/test/gencov +3 -0
  74. data/test/invocation_test.rb +185 -0
  75. data/test/run +6 -0
  76. data/test/scaffolded_controller_test.rb +146 -0
  77. data/test/struct_test.rb +52 -0
  78. data/test/test_invoke_test.rb +112 -0
  79. metadata +166 -0
@@ -0,0 +1,16 @@
1
+ #
2
+ # example controller implementing both blogger and metaWeblog APIs
3
+ # in a way that should be compatible with clients supporting both/either.
4
+ #
5
+ # test by pointing your client at http://URL/xmlrpc/api
6
+ #
7
+
8
+ require 'meta_weblog_service'
9
+ require 'blogger_service'
10
+
11
+ class XmlrpcController < ApplicationController
12
+ web_service_dispatching_mode :layered
13
+
14
+ web_service :metaWeblog, MetaWeblogService.new
15
+ web_service :blogger, BloggerService.new
16
+ end
@@ -0,0 +1,28 @@
1
+ Description:
2
+ The web service generator creates the controller and API definition for
3
+ a web service.
4
+
5
+ The generator takes a web service name and a list of API methods as arguments.
6
+ The web service name may be given in CamelCase or under_score and should
7
+ contain no extra suffixes. To create a web service within a
8
+ module, specify the web service name as 'module/webservice'.
9
+
10
+ The generator creates a controller class in app/controllers, an API definition
11
+ in app/apis, and a functional test suite in test/functional.
12
+
13
+ Example:
14
+ ./script/generate web_service User add edit list remove
15
+
16
+ User web service.
17
+ Controller: app/controllers/user_controller.rb
18
+ API: app/apis/user_api.rb
19
+ Test: test/functional/user_api_test.rb
20
+
21
+ Modules Example:
22
+ ./script/generate web_service 'api/registration' register renew
23
+
24
+ Registration web service.
25
+ Controller: app/controllers/api/registration_controller.rb
26
+ API: app/apis/api/registration_api.rb
27
+ Test: test/functional/api/registration_api_test.rb
28
+
@@ -0,0 +1,5 @@
1
+ class <%= class_name %>Api < ActionWebService::API::Base
2
+ <% for method_name in args -%>
3
+ api_method :<%= method_name %>
4
+ <% end -%>
5
+ end
@@ -0,0 +1,8 @@
1
+ class <%= class_name %>Controller < ApplicationController
2
+ wsdl_service_name '<%= class_name %>'
3
+ <% for method_name in args -%>
4
+
5
+ def <%= method_name %>
6
+ end
7
+ <% end -%>
8
+ end
@@ -0,0 +1,19 @@
1
+ require File.dirname(__FILE__) + '<%= '/..' * class_nesting_depth %>/../test_helper'
2
+ require '<%= file_path %>_controller'
3
+
4
+ class <%= class_name %>Controller; def rescue_action(e) raise e end; end
5
+
6
+ class <%= class_name %>ControllerApiTest < Test::Unit::TestCase
7
+ def setup
8
+ @controller = <%= class_name %>Controller.new
9
+ @request = ActionController::TestRequest.new
10
+ @response = ActionController::TestResponse.new
11
+ end
12
+ <% for method_name in args -%>
13
+
14
+ def test_<%= method_name %>
15
+ result = invoke :<%= method_name %>
16
+ assert_equal nil, result
17
+ end
18
+ <% end -%>
19
+ end
@@ -0,0 +1,29 @@
1
+ class WebServiceGenerator < Rails::Generator::NamedBase
2
+ def manifest
3
+ record do |m|
4
+ # Check for class naming collisions.
5
+ m.class_collisions class_path, "#{class_name}Api", "#{class_name}Controller", "#{class_name}ApiTest"
6
+
7
+ # API and test directories.
8
+ m.directory File.join('app/services', class_path)
9
+ m.directory File.join('app/controllers', class_path)
10
+ m.directory File.join('test/functional', class_path)
11
+
12
+ # API definition, controller, and functional test.
13
+ m.template 'api_definition.rb',
14
+ File.join('app/services',
15
+ class_path,
16
+ "#{file_name}_api.rb")
17
+
18
+ m.template 'controller.rb',
19
+ File.join('app/controllers',
20
+ class_path,
21
+ "#{file_name}_controller.rb")
22
+
23
+ m.template 'functional_test.rb',
24
+ File.join('test/functional',
25
+ class_path,
26
+ "#{file_name}_api_test.rb")
27
+ end
28
+ end
29
+ end
@@ -0,0 +1,66 @@
1
+ #--
2
+ # Copyright (C) 2005 Leon Breedt
3
+ #
4
+ # Permission is hereby granted, free of charge, to any person obtaining
5
+ # a copy of this software and associated documentation files (the
6
+ # "Software"), to deal in the Software without restriction, including
7
+ # without limitation the rights to use, copy, modify, merge, publish,
8
+ # distribute, sublicense, and/or sell copies of the Software, and to
9
+ # permit persons to whom the Software is furnished to do so, subject to
10
+ # the following conditions:
11
+ #
12
+ # The above copyright notice and this permission notice shall be
13
+ # included in all copies or substantial portions of the Software.
14
+ #
15
+ # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16
+ # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17
+ # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18
+ # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
19
+ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
20
+ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
21
+ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22
+ #++
23
+
24
+ begin
25
+ require 'active_support'
26
+ require 'action_controller'
27
+ require 'active_record'
28
+ rescue LoadError
29
+ require 'rubygems'
30
+ gem 'activesupport', '>= 2.3.0'
31
+ gem 'actionpack', '>= 2.3.0'
32
+ gem 'activerecord', '>= 2.3.0'
33
+ end
34
+
35
+ $:.unshift(File.dirname(__FILE__) + "/action_web_service/vendor/")
36
+
37
+ require 'action_web_service/support/class_inheritable_options'
38
+ require 'action_web_service/support/signature_types'
39
+ require 'action_web_service/base'
40
+ require 'action_web_service/client'
41
+ require 'action_web_service/invocation'
42
+ require 'action_web_service/api'
43
+ require 'action_web_service/casting'
44
+ require 'action_web_service/struct'
45
+ require 'action_web_service/container'
46
+ require 'action_web_service/protocol'
47
+ require 'action_web_service/dispatcher'
48
+ require 'action_web_service/scaffolding'
49
+
50
+ ActionWebService::Base.class_eval do
51
+ include ActionWebService::Container::Direct
52
+ include ActionWebService::Invocation
53
+ end
54
+
55
+ ActionController::Base.class_eval do
56
+ include ActionWebService::Protocol::Discovery
57
+ include ActionWebService::Protocol::Soap
58
+ include ActionWebService::Protocol::XmlRpc
59
+ include ActionWebService::Container::Direct
60
+ include ActionWebService::Container::Delegated
61
+ include ActionWebService::Container::ActionController
62
+ include ActionWebService::Invocation
63
+ include ActionWebService::Dispatcher
64
+ include ActionWebService::Dispatcher::ActionController
65
+ include ActionWebService::Scaffolding
66
+ end
@@ -0,0 +1,297 @@
1
+ module ActionWebService # :nodoc:
2
+ module API # :nodoc:
3
+ # A web service API class specifies the methods that will be available for
4
+ # invocation for an API. It also contains metadata such as the method type
5
+ # signature hints.
6
+ #
7
+ # It is not intended to be instantiated.
8
+ #
9
+ # It is attached to web service implementation classes like
10
+ # ActionWebService::Base and ActionController::Base derivatives by using
11
+ # <tt>container.web_service_api</tt>, where <tt>container</tt> is an
12
+ # ActionController::Base or a ActionWebService::Base.
13
+ #
14
+ # See ActionWebService::Container::Direct::ClassMethods for an example
15
+ # of use.
16
+ class Base
17
+ # Whether to transform the public API method names into camel-cased names
18
+ class_inheritable_option :inflect_names, true
19
+
20
+ # By default only HTTP POST requests are processed
21
+ class_inheritable_option :allowed_http_methods, [ :post ]
22
+
23
+ # Whether to allow ActiveRecord::Base models in <tt>:expects</tt>.
24
+ # The default is +false+; you should be aware of the security implications
25
+ # of allowing this, and ensure that you don't allow remote callers to
26
+ # easily overwrite data they should not have access to.
27
+ class_inheritable_option :allow_active_record_expects, false
28
+
29
+ # If present, the name of a method to call when the remote caller
30
+ # tried to call a nonexistent method. Semantically equivalent to
31
+ # +method_missing+.
32
+ class_inheritable_option :default_api_method
33
+
34
+ # Disallow instantiation
35
+ private_class_method :new, :allocate
36
+
37
+ class << self
38
+ include ActionWebService::SignatureTypes
39
+
40
+ # API methods have a +name+, which must be the Ruby method name to use when
41
+ # performing the invocation on the web service object.
42
+ #
43
+ # The signatures for the method input parameters and return value can
44
+ # by specified in +options+.
45
+ #
46
+ # A signature is an array of one or more parameter specifiers.
47
+ # A parameter specifier can be one of the following:
48
+ #
49
+ # * A symbol or string representing one of the Action Web Service base types.
50
+ # See ActionWebService::SignatureTypes for a canonical list of the base types.
51
+ # * The Class object of the parameter type
52
+ # * A single-element Array containing one of the two preceding items. This
53
+ # will cause Action Web Service to treat the parameter at that position
54
+ # as an array containing only values of the given type.
55
+ # * A Hash containing as key the name of the parameter, and as value
56
+ # one of the three preceding items
57
+ #
58
+ # If no method input parameter or method return value signatures are given,
59
+ # the method is assumed to take no parameters and/or return no values of
60
+ # interest, and any values that are received by the server will be
61
+ # discarded and ignored.
62
+ #
63
+ # Valid options:
64
+ # [<tt>:expects</tt>] Signature for the method input parameters
65
+ # [<tt>:returns</tt>] Signature for the method return value
66
+ # [<tt>:expects_and_returns</tt>] Signature for both input parameters and return value
67
+ def api_method(name, options={})
68
+ unless options.is_a?(Hash)
69
+ raise(ActionWebServiceError, "Expected a Hash for options")
70
+ end
71
+ validate_options([:expects, :returns, :expects_and_returns], options.keys)
72
+ if options[:expects_and_returns]
73
+ expects = options[:expects_and_returns]
74
+ returns = options[:expects_and_returns]
75
+ else
76
+ expects = options[:expects]
77
+ returns = options[:returns]
78
+ end
79
+ expects = canonical_signature(expects)
80
+ returns = canonical_signature(returns)
81
+ if expects
82
+ expects.each do |type|
83
+ type = type.element_type if type.is_a?(ArrayType)
84
+ if type.type_class.ancestors.include?(ActiveRecord::Base) && !allow_active_record_expects
85
+ raise(ActionWebServiceError, "ActiveRecord model classes not allowed in :expects")
86
+ end
87
+ end
88
+ end
89
+ name = name.to_sym
90
+ public_name = public_api_method_name(name)
91
+ method = Method.new(name, public_name, expects, returns)
92
+ write_inheritable_hash("api_methods", name => method)
93
+ write_inheritable_hash("api_public_method_names", public_name => name)
94
+ end
95
+
96
+ # Whether the given method name is a service method on this API
97
+ #
98
+ # class ProjectsApi < ActionWebService::API::Base
99
+ # api_method :getCount, :returns => [:int]
100
+ # end
101
+ #
102
+ # ProjectsApi.has_api_method?('GetCount') #=> false
103
+ # ProjectsApi.has_api_method?(:getCount) #=> true
104
+ def has_api_method?(name)
105
+ api_methods.has_key?(name)
106
+ end
107
+
108
+ # Whether the given public method name has a corresponding service method
109
+ # on this API
110
+ #
111
+ # class ProjectsApi < ActionWebService::API::Base
112
+ # api_method :getCount, :returns => [:int]
113
+ # end
114
+ #
115
+ # ProjectsApi.has_api_method?(:getCount) #=> false
116
+ # ProjectsApi.has_api_method?('GetCount') #=> true
117
+ def has_public_api_method?(public_name)
118
+ api_public_method_names.has_key?(public_name)
119
+ end
120
+
121
+ # The corresponding public method name for the given service method name
122
+ #
123
+ # ProjectsApi.public_api_method_name('GetCount') #=> "GetCount"
124
+ # ProjectsApi.public_api_method_name(:getCount) #=> "GetCount"
125
+ def public_api_method_name(name)
126
+ if inflect_names
127
+ name.to_s.camelize
128
+ else
129
+ name.to_s
130
+ end
131
+ end
132
+
133
+ # The corresponding service method name for the given public method name
134
+ #
135
+ # class ProjectsApi < ActionWebService::API::Base
136
+ # api_method :getCount, :returns => [:int]
137
+ # end
138
+ #
139
+ # ProjectsApi.api_method_name('GetCount') #=> :getCount
140
+ def api_method_name(public_name)
141
+ api_public_method_names[public_name]
142
+ end
143
+
144
+ # A Hash containing all service methods on this API, and their
145
+ # associated metadata.
146
+ #
147
+ # class ProjectsApi < ActionWebService::API::Base
148
+ # api_method :getCount, :returns => [:int]
149
+ # api_method :getCompletedCount, :returns => [:int]
150
+ # end
151
+ #
152
+ # ProjectsApi.api_methods #=>
153
+ # {:getCount=>#<ActionWebService::API::Method:0x24379d8 ...>,
154
+ # :getCompletedCount=>#<ActionWebService::API::Method:0x2437794 ...>}
155
+ # ProjectsApi.api_methods[:getCount].public_name #=> "GetCount"
156
+ def api_methods
157
+ read_inheritable_attribute("api_methods") || {}
158
+ end
159
+
160
+ # The Method instance for the given public API method name, if any
161
+ #
162
+ # class ProjectsApi < ActionWebService::API::Base
163
+ # api_method :getCount, :returns => [:int]
164
+ # api_method :getCompletedCount, :returns => [:int]
165
+ # end
166
+ #
167
+ # ProjectsApi.public_api_method_instance('GetCount') #=> <#<ActionWebService::API::Method:0x24379d8 ...>
168
+ # ProjectsApi.public_api_method_instance(:getCount) #=> nil
169
+ def public_api_method_instance(public_method_name)
170
+ api_method_instance(api_method_name(public_method_name))
171
+ end
172
+
173
+ # The Method instance for the given API method name, if any
174
+ #
175
+ # class ProjectsApi < ActionWebService::API::Base
176
+ # api_method :getCount, :returns => [:int]
177
+ # api_method :getCompletedCount, :returns => [:int]
178
+ # end
179
+ #
180
+ # ProjectsApi.api_method_instance(:getCount) #=> <ActionWebService::API::Method:0x24379d8 ...>
181
+ # ProjectsApi.api_method_instance('GetCount') #=> <ActionWebService::API::Method:0x24379d8 ...>
182
+ def api_method_instance(method_name)
183
+ api_methods[method_name]
184
+ end
185
+
186
+ # The Method instance for the default API method, if any
187
+ def default_api_method_instance
188
+ return nil unless name = default_api_method
189
+ instance = read_inheritable_attribute("default_api_method_instance")
190
+ if instance && instance.name == name
191
+ return instance
192
+ end
193
+ instance = Method.new(name, public_api_method_name(name), nil, nil)
194
+ write_inheritable_attribute("default_api_method_instance", instance)
195
+ instance
196
+ end
197
+
198
+ private
199
+ def api_public_method_names
200
+ read_inheritable_attribute("api_public_method_names") || {}
201
+ end
202
+
203
+ def validate_options(valid_option_keys, supplied_option_keys)
204
+ unknown_option_keys = supplied_option_keys - valid_option_keys
205
+ unless unknown_option_keys.empty?
206
+ raise(ActionWebServiceError, "Unknown options: #{unknown_option_keys}")
207
+ end
208
+ end
209
+ end
210
+ end
211
+
212
+ # Represents an API method and its associated metadata, and provides functionality
213
+ # to assist in commonly performed API method tasks.
214
+ class Method
215
+ attr :name
216
+ attr :public_name
217
+ attr :expects
218
+ attr :returns
219
+
220
+ def initialize(name, public_name, expects, returns)
221
+ @name = name
222
+ @public_name = public_name
223
+ @expects = expects
224
+ @returns = returns
225
+ @caster = ActionWebService::Casting::BaseCaster.new(self)
226
+ end
227
+
228
+ # The list of parameter names for this method
229
+ def param_names
230
+ return [] unless @expects
231
+ @expects.map{ |type| type.name }
232
+ end
233
+
234
+ # Casts a set of Ruby values into the expected Ruby values
235
+ def cast_expects(params)
236
+ @caster.cast_expects(params)
237
+ end
238
+
239
+ # Cast a Ruby return value into the expected Ruby value
240
+ def cast_returns(return_value)
241
+ @caster.cast_returns(return_value)
242
+ end
243
+
244
+ # Returns the index of the first expected parameter
245
+ # with the given name
246
+ def expects_index_of(param_name)
247
+ return -1 if @expects.nil?
248
+ (0..(@expects.length-1)).each do |i|
249
+ return i if @expects[i].name.to_s == param_name.to_s
250
+ end
251
+ -1
252
+ end
253
+
254
+ # Returns a hash keyed by parameter name for the given
255
+ # parameter list
256
+ def expects_to_hash(params)
257
+ return {} if @expects.nil?
258
+ h = {}
259
+ @expects.zip(params){ |type, param| h[type.name] = param }
260
+ h
261
+ end
262
+
263
+ # Backwards compatibility with previous API
264
+ def [](sig_type)
265
+ case sig_type
266
+ when :expects
267
+ @expects.map{|x| compat_signature_entry(x)}
268
+ when :returns
269
+ @returns.map{|x| compat_signature_entry(x)}
270
+ end
271
+ end
272
+
273
+ # String representation of this method
274
+ def to_s
275
+ fqn = ""
276
+ fqn << (@returns ? (@returns[0].human_name(false) + " ") : "void ")
277
+ fqn << "#{@public_name}("
278
+ fqn << @expects.map{ |p| p.human_name }.join(", ") if @expects
279
+ fqn << ")"
280
+ fqn
281
+ end
282
+
283
+ private
284
+ def compat_signature_entry(entry)
285
+ if entry.array?
286
+ [compat_signature_entry(entry.element_type)]
287
+ else
288
+ if entry.spec.is_a?(Hash)
289
+ {entry.spec.keys.first => entry.type_class}
290
+ else
291
+ entry.type_class
292
+ end
293
+ end
294
+ end
295
+ end
296
+ end
297
+ end