axtro-actionwebservice 2.3.5.1.20101118142125

Sign up to get free protection for your applications and to get access to all the features.
Files changed (85) hide show
  1. data/CHANGELOG +335 -0
  2. data/MIT-LICENSE +21 -0
  3. data/README +381 -0
  4. data/Rakefile +184 -0
  5. data/TODO +32 -0
  6. data/examples/googlesearch/README +143 -0
  7. data/examples/googlesearch/autoloading/google_search_api.rb +51 -0
  8. data/examples/googlesearch/autoloading/google_search_controller.rb +58 -0
  9. data/examples/googlesearch/delegated/google_search_service.rb +109 -0
  10. data/examples/googlesearch/delegated/search_controller.rb +8 -0
  11. data/examples/googlesearch/direct/google_search_api.rb +51 -0
  12. data/examples/googlesearch/direct/search_controller.rb +59 -0
  13. data/examples/metaWeblog/README +17 -0
  14. data/examples/metaWeblog/apis/blogger_api.rb +61 -0
  15. data/examples/metaWeblog/apis/blogger_service.rb +35 -0
  16. data/examples/metaWeblog/apis/meta_weblog_api.rb +68 -0
  17. data/examples/metaWeblog/apis/meta_weblog_service.rb +49 -0
  18. data/examples/metaWeblog/controllers/xmlrpc_controller.rb +17 -0
  19. data/generators/web_service/USAGE +28 -0
  20. data/generators/web_service/templates/api_definition.rb +6 -0
  21. data/generators/web_service/templates/controller.rb +9 -0
  22. data/generators/web_service/templates/functional_test.rb +20 -0
  23. data/generators/web_service/web_service_generator.rb +30 -0
  24. data/lib/action_web_service.rb +61 -0
  25. data/lib/action_web_service/acts_as_web_service.rb +26 -0
  26. data/lib/action_web_service/api.rb +298 -0
  27. data/lib/action_web_service/base.rb +39 -0
  28. data/lib/action_web_service/casting.rb +160 -0
  29. data/lib/action_web_service/client.rb +4 -0
  30. data/lib/action_web_service/client/base.rb +29 -0
  31. data/lib/action_web_service/client/soap_client.rb +114 -0
  32. data/lib/action_web_service/client/xmlrpc_client.rb +59 -0
  33. data/lib/action_web_service/container.rb +4 -0
  34. data/lib/action_web_service/container/action_controller_container.rb +94 -0
  35. data/lib/action_web_service/container/delegated_container.rb +87 -0
  36. data/lib/action_web_service/container/direct_container.rb +70 -0
  37. data/lib/action_web_service/dispatcher.rb +3 -0
  38. data/lib/action_web_service/dispatcher/abstract.rb +209 -0
  39. data/lib/action_web_service/dispatcher/action_controller_dispatcher.rb +397 -0
  40. data/lib/action_web_service/invocation.rb +203 -0
  41. data/lib/action_web_service/protocol.rb +5 -0
  42. data/lib/action_web_service/protocol/abstract.rb +113 -0
  43. data/lib/action_web_service/protocol/discovery.rb +38 -0
  44. data/lib/action_web_service/protocol/soap_protocol.rb +177 -0
  45. data/lib/action_web_service/protocol/soap_protocol/marshaler.rb +243 -0
  46. data/lib/action_web_service/protocol/soap_protocol/marshaler.rb~ +243 -0
  47. data/lib/action_web_service/protocol/xmlrpc_protocol.rb +124 -0
  48. data/lib/action_web_service/scaffolding.rb +282 -0
  49. data/lib/action_web_service/simple.rb +54 -0
  50. data/lib/action_web_service/string_to_datetime_for_soap.rb +17 -0
  51. data/lib/action_web_service/struct.rb +69 -0
  52. data/lib/action_web_service/support/class_inheritable_options.rb +27 -0
  53. data/lib/action_web_service/support/signature_types.rb +262 -0
  54. data/lib/action_web_service/templates/scaffolds/layout.html.erb +65 -0
  55. data/lib/action_web_service/templates/scaffolds/methods.html.erb +6 -0
  56. data/lib/action_web_service/templates/scaffolds/parameters.html.erb +29 -0
  57. data/lib/action_web_service/templates/scaffolds/result.html.erb +30 -0
  58. data/lib/action_web_service/test_invoke.rb +111 -0
  59. data/lib/action_web_service/version.rb +11 -0
  60. data/lib/action_web_service/version.rb~ +10 -0
  61. data/lib/actionwebservice.rb +2 -0
  62. data/setup.rb +1380 -0
  63. data/test/abstract_client.rb +185 -0
  64. data/test/abstract_dispatcher.rb +550 -0
  65. data/test/abstract_unit.rb +44 -0
  66. data/test/api_test.rb +103 -0
  67. data/test/apis/auto_load_api.rb +4 -0
  68. data/test/apis/broken_auto_load_api.rb +3 -0
  69. data/test/base_test.rb +43 -0
  70. data/test/casting_test.rb +96 -0
  71. data/test/client_soap_test.rb +157 -0
  72. data/test/client_xmlrpc_test.rb +155 -0
  73. data/test/container_test.rb +76 -0
  74. data/test/dispatcher_action_controller_soap_test.rb +147 -0
  75. data/test/dispatcher_action_controller_xmlrpc_test.rb +60 -0
  76. data/test/fixtures/db_definitions/mysql.sql +8 -0
  77. data/test/fixtures/db_definitions/sqlite3.sql +8 -0
  78. data/test/fixtures/users.yml +12 -0
  79. data/test/gencov +3 -0
  80. data/test/invocation_test.rb +187 -0
  81. data/test/run +6 -0
  82. data/test/scaffolded_controller_test.rb +148 -0
  83. data/test/struct_test.rb +85 -0
  84. data/test/test_invoke_test.rb +114 -0
  85. metadata +167 -0
@@ -0,0 +1,335 @@
1
+ *2.3.5*
2
+
3
+ * Added support for sqlite3 in testing [Steve Weet]
4
+
5
+ * Allow ActionWebService::Struct to be initialized with a Hash that contains keys not included within the members [Steve Weet]
6
+
7
+ * Depend on Action Pack >= 2.3.5
8
+
9
+ * Depend on Active Record >= 2.3.5
10
+
11
+ * Added init.rb to allow using as a rails plugin
12
+
13
+ *2.3.4.2*
14
+ * Adding Simple Type possible as custom type [Matheus Paschoal]
15
+
16
+ *2.1.0*
17
+
18
+ * Porting to Rails 2.1.0 [Kent Sibilev]
19
+
20
+ * Documentation for ActionWebService::API::Base. Closes #7275. [zackchandler]
21
+
22
+ * Allow action_web_service to handle various HTTP methods including GET. Closes #7011. [zackchandler]
23
+
24
+ * Ensure that DispatcherError is being thrown when a malformed request is received. [Kent Sibilev]
25
+
26
+ * Added support for decimal types. Closes #6676. [Kent Sibilev]
27
+
28
+ * Removed deprecated end_form_tag helper. [Kent Sibilev]
29
+
30
+ * Removed deprecated @request and @response usages. [Kent Sibilev]
31
+
32
+ * Removed deprecated end_form_tag helper. [Kent Sibilev]
33
+
34
+ * Removed deprecated @request and @response usages. [Kent Sibilev]
35
+
36
+ *1.2.6* (November 24th, 2007)
37
+
38
+ * Depend on Action Pack 1.13.6
39
+
40
+ * Depend on Active Record 1.15.6
41
+
42
+
43
+ *1.2.5* (October 12th, 2007)
44
+
45
+ * Depend on Action Pack 1.13.5
46
+
47
+ * Depend on Active Record 1.15.5
48
+
49
+
50
+ *1.2.4* (October 4th, 2007)
51
+
52
+ * Depend on Action Pack 1.13.4
53
+
54
+ * Depend on Active Record 1.15.4
55
+
56
+
57
+ *1.2.3* (March 12th, 2007)
58
+
59
+ * Depend on Action Pack 1.13.3
60
+
61
+
62
+ *1.2.2* (Feburary 4th, 2007)
63
+
64
+ * Depend on Action Pack 1.13.2
65
+
66
+
67
+ *1.2.1* (January 16th, 2007)
68
+
69
+ * Depend on Action Pack 1.13.1
70
+
71
+
72
+ *1.2.0* (January 16th, 2007)
73
+
74
+ * 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]
75
+
76
+ * Provide access to the underlying SOAP driver. #6212 [bmilekic, Kent Sibilev]
77
+
78
+ * ActionWebService WSDL generation ignores HTTP_X_FORWARDED_HOST [Paul Butcher <paul@paulbutcher.com>]
79
+
80
+ * Tighten rescue clauses. #5985 [james@grayproductions.net]
81
+
82
+ * Fixed XMLRPC multicall when one of the called methods returns a struct object. [Kent Sibilev]
83
+
84
+ * Fix invoke_layered since api_method didn't declare :expects. Closes #4720. [Kevin Ballard <kevin@sb.org>, Kent Sibilev]
85
+
86
+
87
+ *1.1.6* (August 10th, 2006)
88
+
89
+ * Rely on Action Pack 1.12.5
90
+
91
+
92
+ *1.1.5* (August 8th, 2006)
93
+
94
+ * Rely on Action Pack 1.12.4 and Active Record 1.14.4
95
+
96
+
97
+ *1.1.4* (June 29th, 2006)
98
+
99
+ * Rely on Action Pack 1.12.3
100
+
101
+
102
+ *1.1.3* (June 27th, 2006)
103
+
104
+ * Rely on Action Pack 1.12.2 and Active Record 1.14.3
105
+
106
+
107
+ *1.1.2* (April 9th, 2006)
108
+
109
+ * Rely on Active Record 1.14.2
110
+
111
+
112
+ *1.1.1* (April 6th, 2006)
113
+
114
+ * Do not convert driver options to strings (#4499)
115
+
116
+
117
+ *1.1.0* (March 27th, 2006)
118
+
119
+ * Make ActiveWebService::Struct type reloadable
120
+
121
+ * Fix scaffolding action when one of the members of a structural type has date or time type
122
+
123
+ * Remove extra index hash when generating scaffold html for parameters of structural type #4374 [joe@mjg2.com]
124
+
125
+ * Fix Scaffold Fails with Struct as a Parameter #4363 [joe@mjg2.com]
126
+
127
+ * Fix soap type registration of multidimensional arrays (#4232)
128
+
129
+ * Fix that marshaler couldn't handle ActiveRecord models defined in a different namespace (#2392).
130
+
131
+ * Fix that marshaler couldn't handle structs with members of ActiveRecord type (#1889).
132
+
133
+ * Fix that marshaler couldn't handle nil values for inner structs (#3576).
134
+
135
+ * Fix that changes to ActiveWebService::API::Base required restarting of the server (#2390).
136
+
137
+ * Fix scaffolding for signatures with :date, :time and :base64 types (#3321, #2769, #2078).
138
+
139
+ * Fix for incorrect casting of TrueClass/FalseClass instances (#2633, #3421).
140
+
141
+ * Fix for incompatibility problems with SOAP4R 1.5.5 (#2553) [Kent Sibilev]
142
+
143
+
144
+ *1.0.0* (December 13th, 2005)
145
+
146
+ * Become part of Rails 1.0
147
+
148
+ *0.9.4* (December 7th, 2005)
149
+
150
+ * Update from LGPL to MIT license as per Minero Aoki's permission. [Marcel Molina Jr.]
151
+
152
+ * Rename Version constant to VERSION. #2802 [Marcel Molina Jr.]
153
+
154
+ * 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.
155
+
156
+ *0.9.3* (November 7th, 2005)
157
+
158
+ * Upgraded to Action Pack 1.11.0 and Active Record 1.13.0
159
+
160
+
161
+ *0.9.2* (October 26th, 2005)
162
+
163
+ * Upgraded to Action Pack 1.10.2 and Active Record 1.12.2
164
+
165
+
166
+ *0.9.1* (October 19th, 2005)
167
+
168
+ * Upgraded to Action Pack 1.10.1 and Active Record 1.12.1
169
+
170
+
171
+ *0.9.0* (October 16th, 2005)
172
+
173
+ * Fix invalid XML request generation bug in test_invoke [Ken Barker]
174
+
175
+ * Add XML-RPC 'system.multicall' support #1941 [jbonnar]
176
+
177
+ * Fix duplicate XSD entries for custom types shared across delegated/layered services #1729 [Tyler Kovacs]
178
+
179
+ * Allow multiple invocations in the same test method #1720 [dkhawk]
180
+
181
+ * 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
182
+
183
+ * ActionWebService now always returns UTF-8 responses.
184
+
185
+
186
+ *0.8.1* (11 July, 2005)
187
+
188
+ * Fix scaffolding for Action Pack controller changes
189
+
190
+
191
+ *0.8.0* (6 July, 2005)
192
+
193
+ * 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
194
+
195
+ * 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.
196
+
197
+ * Add workaround for Ruby 1.8.3's SOAP4R changing the return value of SOAP::Mapping::Registry#find_mapped_soap_class #1414 [Shugo Maeda]
198
+
199
+ * Fix moduled controller URLs in WSDL, and add unit test to verify the generated URL #1428
200
+
201
+ * Fix scaffolding template paths, it was broken on Win32
202
+
203
+ * Fix that functional testing of :layered controllers failed when using the SOAP protocol
204
+
205
+ * Allow invocation filters in :direct controllers as well, as they have access to more information regarding the web service request than ActionPack filters
206
+
207
+ * Add support for a :base64 signature type #1272 [Shugo Maeda]
208
+
209
+ * Fix that boolean fields were not rendered correctly in scaffolding
210
+
211
+ * Fix that scaffolding was not working for :delegated dispatching
212
+
213
+ * Add support for structured types as input parameters to scaffolding, this should let one test the blogging APIs using scaffolding as well
214
+
215
+ * Fix that generated WSDL was not using relative_url_root for base URI #1210 [Shugo Maeda]
216
+
217
+ * 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]
218
+
219
+ * If the WSDL was retrieved over HTTPS, use HTTPS URLs in the WSDL too
220
+
221
+ * 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
222
+
223
+
224
+ *0.7.1* (20th April, 2005)
225
+
226
+ * Depend on Active Record 1.10.1 and Action Pack 1.8.1
227
+
228
+
229
+ *0.7.0* (19th April, 2005)
230
+
231
+ * 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
232
+
233
+ * Add scaffolding via ActionController::Base.web_service_scaffold for quick testing using a web browser
234
+
235
+ * 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.
236
+
237
+ * 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
238
+
239
+ * Remove ActiveRecordSoapMarshallable workaround, see #912 for details
240
+
241
+ * Generalize casting code to be used by both SOAP and XML-RPC (previously, it was only XML-RPC)
242
+
243
+ * Ensure return value is properly cast as well, fixes XML-RPC interoperability with Ecto and possibly other clients
244
+
245
+ * Include backtraces in 500 error responses for failed request parsing, and remove "rescue nil" statements obscuring real errors for XML-RPC
246
+
247
+ * 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
248
+
249
+
250
+ *0.6.2* (27th March, 2005)
251
+
252
+ * 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.
253
+
254
+
255
+ *0.6.1* (22th March, 2005)
256
+
257
+ * Fix that method response QNames mismatched with that declared in the WSDL, makes SOAP::WSDLDriverFactory work against AWS again
258
+
259
+ * Fix that @request.env was being modified, instead, dup the value gotten from env
260
+
261
+ * Fix XML-RPC example to use :layered mode, so it works again
262
+
263
+ * Support casting '0' or 0 into false, and '1' or 1 into true, when expecting a boolean value
264
+
265
+ * Fix that SOAP fault response fault code values were not QName's #804
266
+
267
+
268
+ *0.6.0* (7th March, 2005)
269
+
270
+ * Add action_controller/test_invoke, used for integrating AWS with the Rails testing infrastructure
271
+
272
+ * Allow passing through options to the SOAP RPC driver for the SOAP client
273
+
274
+ * Make the SOAP WS marshaler use #columns to decide which fields to marshal as well, avoids providing attributes brought in by associations
275
+
276
+ * 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.
277
+
278
+ * 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.
279
+
280
+ * 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
281
+
282
+ * 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.
283
+
284
+ * Add namespaced XML-RPC method name support, closes #678
285
+
286
+ * Replace '::' with '..' in fully qualified type names for marshaling and WSDL. This improves interoperability with .NET, and closes #676.
287
+
288
+
289
+ *0.5.0* (24th February, 2005)
290
+
291
+ * lib/action_service/dispatcher*: replace "router" fragments with
292
+ one file for Action Controllers, moves dispatching work out of
293
+ the container
294
+ * lib/*,test/*,examples/*: rename project to
295
+ ActionWebService. prefix all generic "service" type names with web_.
296
+ update all using code as well as the RDoc.
297
+ * lib/action_service/router/wsdl.rb: ensure that #wsdl is
298
+ defined in the final container class, or the new ActionPack
299
+ filtering will exclude it
300
+ * lib/action_service/struct.rb,test/struct_test.rb: create a
301
+ default #initialize on inherit that accepts a Hash containing
302
+ the default member values
303
+ * lib/action_service/api/action_controller.rb: add support and
304
+ tests for #client_api in controller
305
+ * test/router_wsdl_test.rb: add tests to ensure declared
306
+ service names don't contain ':', as ':' causes interoperability
307
+ issues
308
+ * lib/*, test/*: rename "interface" concept to "api", and change all
309
+ related uses to reflect this change. update all uses of Inflector
310
+ to call the method on String instead.
311
+ * test/api_test.rb: add test to ensure API definition not
312
+ instantiatable
313
+ * lib/action_service/invocation.rb: change @invocation_params to
314
+ @method_params
315
+ * lib/*: update RDoc
316
+ * lib/action_service/struct.rb: update to support base types
317
+ * lib/action_service/support/signature.rb: support the notion of
318
+ "base types" in signatures, with well-known unambiguous names such as :int,
319
+ :bool, etc, which map to the correct Ruby class. accept the same names
320
+ used by ActiveRecord as well as longer versions of each, as aliases.
321
+ * examples/*: update for seperate API definition updates
322
+ * lib/action_service/*, test/*: extensive refactoring: define API methods in
323
+ a seperate class, and specify it wherever used with 'service_api'.
324
+ this makes writing a client API for accessing defined API methods
325
+ with ActionWebService really easy.
326
+ * lib/action_service/container.rb: fix a bug in default call
327
+ handling for direct dispatching, and add ActionController filter
328
+ support for direct dispatching.
329
+ * test/router_action_controller_test.rb: add tests to ensure
330
+ ActionController filters are actually called.
331
+ * test/protocol_soap_test.rb: add more tests for direct dispatching.
332
+
333
+ 0.3.0
334
+
335
+ * First public release
@@ -0,0 +1,21 @@
1
+ Copyright (C) 2005 Leon Breedt
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21
+
data/README ADDED
@@ -0,0 +1,381 @@
1
+ = Action Web Service -- Serving APIs on rails
2
+
3
+ Action Web Service provides a way to publish interoperable web service APIs with
4
+ Rails without spending a lot of time delving into protocol details.
5
+
6
+
7
+ == Features
8
+
9
+ * SOAP RPC protocol support
10
+ * Dynamic WSDL generation for APIs
11
+ * XML-RPC protocol support
12
+ * Clients that use the same API definitions as the server for
13
+ easy interoperability with other Action Web Service based applications
14
+ * Type signature hints to improve interoperability with static languages
15
+ * Active Record model class support in signatures
16
+
17
+
18
+ == Defining your APIs
19
+
20
+ You specify the methods you want to make available as API methods in an
21
+ ActionWebService::API::Base derivative, and then specify this API
22
+ definition class wherever you want to use that API.
23
+
24
+ The implementation of the methods is done separately from the API
25
+ specification.
26
+
27
+
28
+ ==== Method name inflection
29
+
30
+ Action Web Service will camelcase the method names according to Rails Inflector
31
+ rules for the API visible to public callers. What this means, for example,
32
+ is that the method names in generated WSDL will be camelcased, and callers will
33
+ have to supply the camelcased name in their requests for the request to
34
+ succeed.
35
+
36
+ If you do not desire this behaviour, you can turn it off with the
37
+ ActionWebService::API::Base +inflect_names+ option.
38
+
39
+
40
+ ==== Inflection examples
41
+
42
+ :add => Add
43
+ :find_all => FindAll
44
+
45
+
46
+ ==== Disabling inflection
47
+
48
+ class PersonAPI < ActionWebService::API::Base
49
+ inflect_names false
50
+ end
51
+
52
+
53
+ ==== API definition example
54
+
55
+ class PersonAPI < ActionWebService::API::Base
56
+ api_method :add, :expects => [:string, :string, :bool], :returns => [:int]
57
+ api_method :remove, :expects => [:int], :returns => [:bool]
58
+ end
59
+
60
+ ==== API usage example
61
+
62
+ class PersonController < ActionController::Base
63
+ web_service_api PersonAPI
64
+
65
+ def add
66
+ end
67
+
68
+ def remove
69
+ end
70
+ end
71
+
72
+
73
+ == Publishing your APIs
74
+
75
+ Action Web Service uses Action Pack to process protocol requests. There are two
76
+ modes of dispatching protocol requests, _Direct_, and _Delegated_.
77
+
78
+
79
+ === Direct dispatching
80
+
81
+ This is the default mode. In this mode, public controller instance methods
82
+ implement the API methods, and parameters are passed through to the methods in
83
+ accordance with the API specification.
84
+
85
+ The return value of the method is sent back as the return value to the
86
+ caller.
87
+
88
+ In this mode, a special <tt>api</tt> action is generated in the target
89
+ controller to unwrap the protocol request, forward it on to the relevant method
90
+ and send back the wrapped return value. <em>This action must not be
91
+ overridden.</em>
92
+
93
+ ==== Direct dispatching example
94
+
95
+ class PersonController < ApplicationController
96
+ web_service_api PersonAPI
97
+
98
+ def add
99
+ end
100
+
101
+ def remove
102
+ end
103
+ end
104
+
105
+ class PersonAPI < ActionWebService::API::Base
106
+ ...
107
+ end
108
+
109
+
110
+ For this example, protocol requests for +Add+ and +Remove+ methods sent to
111
+ <tt>/person/api</tt> will be routed to the controller methods +add+ and +remove+.
112
+
113
+
114
+ === Delegated dispatching
115
+
116
+ This mode can be turned on by setting the +web_service_dispatching_mode+ option
117
+ in a controller to <tt>:delegated</tt>.
118
+
119
+ In this mode, the controller contains one or more web service objects (objects
120
+ that implement an ActionWebService::API::Base definition). These web service
121
+ objects are each mapped onto one controller action only.
122
+
123
+ ==== Delegated dispatching example
124
+
125
+ class ApiController < ApplicationController
126
+ web_service_dispatching_mode :delegated
127
+
128
+ web_service :person, PersonService.new
129
+ end
130
+
131
+ class PersonService < ActionWebService::Base
132
+ web_service_api PersonAPI
133
+
134
+ def add
135
+ end
136
+
137
+ def remove
138
+ end
139
+ end
140
+
141
+ class PersonAPI < ActionWebService::API::Base
142
+ ...
143
+ end
144
+
145
+
146
+ For this example, all protocol requests for +PersonService+ are
147
+ sent to the <tt>/api/person</tt> action.
148
+
149
+ The <tt>/api/person</tt> action is generated when the +web_service+
150
+ method is called. <em>This action must not be overridden.</em>
151
+
152
+ Other controller actions (actions that aren't the target of a +web_service+ call)
153
+ are ignored for ActionWebService purposes, and can do normal action tasks.
154
+
155
+
156
+ === Layered dispatching
157
+
158
+ This mode can be turned on by setting the +web_service_dispatching_mode+ option
159
+ in a controller to <tt>:layered</tt>.
160
+
161
+ This mode is similar to _delegated_ mode, in that multiple web service objects
162
+ can be attached to one controller, however, all protocol requests are sent to a
163
+ single endpoint.
164
+
165
+ Use this mode when you want to share code between XML-RPC and SOAP clients,
166
+ for APIs where the XML-RPC method names have prefixes. An example of such
167
+ a method name would be <tt>blogger.newPost</tt>.
168
+
169
+
170
+ ==== Layered dispatching example
171
+
172
+
173
+ class ApiController < ApplicationController
174
+ web_service_dispatching_mode :layered
175
+
176
+ web_service :mt, MovableTypeService.new
177
+ web_service :blogger, BloggerService.new
178
+ web_service :metaWeblog, MetaWeblogService.new
179
+ end
180
+
181
+ class MovableTypeService < ActionWebService::Base
182
+ ...
183
+ end
184
+
185
+ class BloggerService < ActionWebService::Base
186
+ ...
187
+ end
188
+
189
+ class MetaWeblogService < ActionWebService::API::Base
190
+ ...
191
+ end
192
+
193
+
194
+ For this example, an XML-RPC call for a method with a name like
195
+ <tt>mt.getCategories</tt> will be sent to the <tt>getCategories</tt>
196
+ method on the <tt>:mt</tt> service.
197
+
198
+
199
+ == Customizing WSDL generation
200
+
201
+ You can customize the names used for the SOAP bindings in the generated
202
+ WSDL by using the wsdl_service_name option in a controller:
203
+
204
+ class WsController < ApplicationController
205
+ wsdl_service_name 'MyApp'
206
+ end
207
+
208
+ You can also customize the namespace used in the generated WSDL for
209
+ custom types and message definition types:
210
+
211
+ class WsController < ApplicationController
212
+ wsdl_namespace 'http://my.company.com/app/wsapi'
213
+ end
214
+
215
+ The default namespace used is 'urn:ActionWebService', if you don't supply
216
+ one.
217
+
218
+
219
+ == ActionWebService and UTF-8
220
+
221
+ If you're going to be sending back strings containing non-ASCII UTF-8
222
+ characters using the <tt>:string</tt> data type, you need to make sure that
223
+ Ruby is using UTF-8 as the default encoding for its strings.
224
+
225
+ The default in Ruby is to use US-ASCII encoding for strings, which causes a string
226
+ validation check in the Ruby SOAP library to fail and your string to be sent
227
+ back as a Base-64 value, which may confuse clients that expected strings
228
+ because of the WSDL.
229
+
230
+ Two ways of setting the default string encoding are:
231
+
232
+ * Start Ruby using the <tt>-Ku</tt> command-line option to the Ruby executable
233
+ * Set the <tt>$KCODE</tt> flag in <tt>config/environment.rb</tt> to the
234
+ string <tt>'UTF8'</tt>
235
+
236
+
237
+ == Testing your APIs
238
+
239
+
240
+ === Functional testing
241
+
242
+ You can perform testing of your APIs by creating a functional test for the
243
+ controller dispatching the API, and calling #invoke in the test case to
244
+ perform the invocation.
245
+
246
+ Example:
247
+
248
+ class PersonApiControllerTest < Test::Unit::TestCase
249
+ def setup
250
+ @controller = PersonController.new
251
+ @request = ActionController::TestRequest.new
252
+ @response = ActionController::TestResponse.new
253
+ end
254
+
255
+ def test_add
256
+ result = invoke :remove, 1
257
+ assert_equal true, result
258
+ end
259
+ end
260
+
261
+ This example invokes the API method <tt>test</tt>, defined on
262
+ the PersonController, and returns the result.
263
+
264
+ If you're not using SOAP (or you're having serialisation difficulties),
265
+ you can test XMLRPC like this:
266
+
267
+ class PersonApiControllerTest < Test::Unit::TestCase
268
+ def setup
269
+ @controller = PersonController.new
270
+ @request = ActionController::TestRequest.new
271
+ @response = ActionController::TestResponse.new
272
+
273
+ @protocol = :xmlrpc # can also be :soap, the default
274
+ end
275
+
276
+ def test_add
277
+ result = invoke :remove, 1 # no change here
278
+ assert_equal true, result
279
+ end
280
+ end
281
+
282
+ === Scaffolding
283
+
284
+ You can also test your APIs with a web browser by attaching scaffolding
285
+ to the controller.
286
+
287
+ Example:
288
+
289
+ class PersonController
290
+ web_service_scaffold :invocation
291
+ end
292
+
293
+ This creates an action named <tt>invocation</tt> on the PersonController.
294
+
295
+ Navigating to this action lets you select the method to invoke, supply the parameters,
296
+ and view the result of the invocation.
297
+
298
+
299
+ == Using the client support
300
+
301
+ Action Web Service includes client classes that can use the same API
302
+ definition as the server. The advantage of this approach is that your client
303
+ will have the same support for Active Record and structured types as the
304
+ server, and can just use them directly, and rely on the marshaling to Do The
305
+ Right Thing.
306
+
307
+ *Note*: The client support is intended for communication between Ruby on Rails
308
+ applications that both use Action Web Service. It may work with other servers, but
309
+ that is not its intended use, and interoperability can't be guaranteed, especially
310
+ not for .NET web services.
311
+
312
+ Web services protocol specifications are complex, and Action Web Service client
313
+ support can only be guaranteed to work with a subset.
314
+
315
+
316
+ ==== Factory created client example
317
+
318
+ class BlogManagerController < ApplicationController
319
+ web_client_api :blogger, :xmlrpc, 'http://url/to/blog/api/RPC2', :handler_name => 'blogger'
320
+ end
321
+
322
+ class SearchingController < ApplicationController
323
+ web_client_api :google, :soap, 'http://url/to/blog/api/beta', :service_name => 'GoogleSearch'
324
+ end
325
+
326
+ See ActionWebService::API::ActionController::ClassMethods for more details.
327
+
328
+ ==== Manually created client example
329
+
330
+ class PersonAPI < ActionWebService::API::Base
331
+ api_method :find_all, :returns => [[Person]]
332
+ end
333
+
334
+ soap_client = ActionWebService::Client::Soap.new(PersonAPI, "http://...")
335
+ persons = soap_client.find_all
336
+
337
+ class BloggerAPI < ActionWebService::API::Base
338
+ inflect_names false
339
+ api_method :getRecentPosts, :returns => [[Blog::Post]]
340
+ end
341
+
342
+ blog = ActionWebService::Client::XmlRpc.new(BloggerAPI, "http://.../xmlrpc", :handler_name => "blogger")
343
+ posts = blog.getRecentPosts
344
+
345
+
346
+ See ActionWebService::Client::Soap and ActionWebService::Client::XmlRpc for more details.
347
+
348
+ == Dependencies
349
+
350
+ Action Web Service requires that the Action Pack and Active Record are either
351
+ available to be required immediately or are accessible as GEMs.
352
+
353
+ It also requires a version of Ruby that includes SOAP support in the standard
354
+ library. At least version 1.8.2 final (2004-12-25) of Ruby is recommended; this
355
+ is the version tested against.
356
+
357
+
358
+ == Download
359
+
360
+ The latest Action Web Service version can be downloaded from
361
+ http://rubyforge.org/projects/actionservice
362
+
363
+
364
+ == Installation
365
+
366
+ You can install Action Web Service with the following command.
367
+
368
+ % [sudo] ruby setup.rb
369
+
370
+
371
+ == License
372
+
373
+ Action Web Service is released under the MIT license.
374
+
375
+
376
+ == Support
377
+
378
+ The Ruby on Rails mailing list
379
+
380
+ Or, to contact the author, send mail to bitserf@gmail.com
381
+