actionservice 0.2.102 → 0.3.0

data/ChangeLog

@@ -1,3 +1,3 @@
-TBD
+0.3.0
 
 	* First public release

data/README

@@ -1,18 +1,16 @@
 = Action Service -- Serving APIs on rails
 
-Action Service provides a way to publish interoperablel web service APIs with
+Action Service provides a way to publish interoperable web service APIs with
 Rails without wasting time delving into protocol details.
 
 
 == Features
 
 * SOAP RPC protocol support
-* Dynamic WSDL generation
+* Dynamic WSDL generation for exported APIs
 * XML-RPC protocol support
-* Strong type signature hints to improve interoperability with static
-  languages
-* Using Active Record derivatives in return signatures automatically generates
-  a structured type equivalent that can be sent over the wire
+* Type signature hints to improve interoperability with static languages
+* Active Record model class support in signatures
 
 
 == Integration with Action Pack
@@ -21,21 +19,57 @@ Action Service can be integrated in two different dispatching modes, _Direct_ an
 _Delegated_.
 
 
-* _Direct_ mode refers to a dispatching mode where one controller represents a
-  single API service, and actions in the controller represent API methods. This is
-  the default mode.
-* _Delegated_ mode refers to a dispatching mode where a controller is a
-  container for one or more API services, and an action on the controller
-  serves as the entry point for an associated service.
+== Direct dispatching
+
+This is the default mode. In this mode, controller actions can be exported as
+API methods, and parameters for incoming method calls will be placed in
+<tt>@params</tt>. The return value of the action will be sent back as the
+return value to the caller.
+
+Requests from callers will be sent to <tt>/controller_name/api</tt> using
+HTTP POST.
+
+==== Direct dispatching example
+
+  class PersonApiController < ApplicationController
+    def add
+    end
+
+    def remove
+    end
+
+    export :add
+    export :remove
+  end
+
+
+== Delegated dispatching
+
+This mode can be turned on by setting the +service_dispatching_mode+ option.
+In this mode, a controller is a container for one or more service objects,
+each implementing a seperate API.
+
+Requests from callers will be sent to <tt>/controller_name/service_name</tt>
+using HTTP POST.
+
+==== Delegated dispatching example
+
+  class ApiController < ApplicationController
+    service_dispatching_mode :delegated
+
+    service :person, PersonApi.new
+    service :customer, CustomerApi.new
+  end
 
 
 == Dependencies
 
-Action Service requires that the Action Pack and Active Record  are either
+Action 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.
+library. At least version 1.8.2 final (2004-12-25) of Ruby is recommended, this
+is the version tested against.
 
 
 == Download

data/Rakefile

@@ -5,10 +5,11 @@ require 'rake/rdoctask'
 require 'rake/packagetask'
 require 'rake/gempackagetask'
 require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
 
 PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
 PKG_NAME      = 'actionservice'
-PKG_VERSION   = '0.2.102' + PKG_BUILD
+PKG_VERSION   = '0.3.0' + PKG_BUILD
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
 desc "Default Task"
@@ -70,20 +71,10 @@ Rake::GemPackageTask.new(spec) do |p|
 end
 
 
-desc "Publish the beta gem"
-task :pgem => [:package] do 
-#  Rake::SshFilePublisher.new("davidhh@comox.textdrive.com", "public_html/gems/gems", "pkg", "#{PKG_FILE_NAME}.gem").upload
-end
-
-
-desc "Publish the API documentation"
-task :pdoc => [:rdoc] do 
-#  Rake::SshDirPublisher.new("davidhh@comox.textdrive.com", "public_html/am", "doc").upload
-end
-
-
-desc "Publish to RubyForge"
-task :rubyforge do
+desc "Publish API docs to RubyForge"
+task :pdoc => [:rdoc] do
+  FileUtils.mkdir_p 'html'
+  FileUtils.mv 'doc', 'html/api'
   Rake::RubyForgePublisher.new('actionservice', 'ljb').upload
 end
 

data/TODO

@@ -1,4 +1,6 @@
 = Tasks
+  - add more direct dispatching tests (method exists, not exists, etc) in
+    container
   - add better type mapping tests for XML-RPC
   - add tests for ActiveRecord support (with mock objects?)
 

data/examples/{soap → googlesearch}/README

@@ -2,24 +2,39 @@
 
 
 This example shows how one would implement an API like Google
-Search, that uses lots of structured types.
+Search that uses lots of structured types.
 
+There are examples for "Direct" and "Delegated" dispatching
+modes.
 
-= Testing
+
+= Running
 
   1. Ensure you have the 'actionservice' Gem installed. You can generate it using
      this command:
 
        $ rake package
 
-  2. Copy lib/google_search_service.rb and app/controllers/search_controller.rb
-     into a Rails project.
 
-  3. Edit config/environment.rb, and add the following line after the rest of the
+  2. Edit config/environment.rb, and add the following line after the rest of the
      require_gem statements:
 
       require_gem 'actionservice'
 
+
+  3. "Direct" example:
+
+      * Copy direct/search_controller.rb to "app/controllers"
+        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.
+  
+
   4. Go to the url http://URL/search/wsdl in a browser, and check that it looks
      correct.
      
@@ -27,7 +42,9 @@ Search, that uses lots of structured types.
      and see how close (or not) the generated version is. 
      
      Note that I used GoogleSearch as the canonical "best practice"
-     interoperable example, which might explain extreme similarities :)
+     interoperable example when implementing WSDL/SOAP support, which might
+     explain extreme similarities :)
+
 
   5. Test that it works with .NET (Mono in this example):
 
@@ -79,8 +96,7 @@ Search, that uses lots of structured types.
 
 
     If you had the application running (on the same host you got
-    the WSDL from), you should see something like this (values will match up
-    with those in lib/google_search_service.rb):
+    the WSDL from), you should see something like this:
 
 
         documentFiltering: True
@@ -108,8 +124,8 @@ Search, that uses lots of structured types.
 
 
     Also, if an API method throws an exception, it will be sent back to the
-    caller in SOAP exception format, so they'll get an exception thrown on
-    their side with a meaningful error message.
+    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:
 

data/examples/{soap/lib → googlesearch/delegated}/google_search_service.rb

@@ -80,14 +80,27 @@ class GoogleSearchService < ActionService::Base
     result
   end
 
-  def category(name, encoding)
-    cat = DirectoryCategory.new
-    cat.fullViewableName = name.dup
-    cat.specialEncoding = encoding.dup
-    cat
-  end
-
   export :doGetCachedPage,         :returns => [String], :expects => [{:key=>String}, {:url=>String}]
-  export :doGetSpellingSuggestion, :returns => [String], :expects => [String, String]
-  export :doGoogleSearch,          :returns => [GoogleSearchResult], :expects => [String, String, Integer, Integer, TrueClass, String, TrueClass, String, String, String]
+  export :doGetSpellingSuggestion, :returns => [String], :expects => [{:key=>String}, {:phrase=>String}]
+
+  export :doGoogleSearch, :returns => [GoogleSearchResult], :expects => [
+    {:key=>String},
+    {:q=>String},
+    {:start=>Integer},
+    {:maxResults=>Integer},
+    {:filter=>TrueClass},
+    {:restrict=>String},
+    {:safeSearch=>TrueClass},
+    {:lr=>String},
+    {:ie=>String},
+    {:oe=>String}
+  ]
+
+  private
+    def category(name, encoding)
+      cat = DirectoryCategory.new
+      cat.fullViewableName = name.dup
+      cat.specialEncoding = encoding.dup
+      cat
+    end
 end

data/examples/googlesearch/direct/search_controller.rb

@@ -0,0 +1,106 @@
+class DirectoryCategory < ActionService::Struct
+  member :fullViewableName, String
+  member :specialEncoding,  String
+end
+
+class ResultElement < ActionService::Struct
+  member :summary,                   String
+  member :URL,                       String
+  member :snippet,                   String
+  member :title,                     String
+  member :cachedSize,                String
+  member :relatedInformationPresent, TrueClass
+  member :hostName,                  String
+  member :directoryCategory,         DirectoryCategory
+  member :directoryTitle,            String
+end
+
+class GoogleSearchResult < ActionService::Struct
+  member :documentFiltering,          TrueClass
+  member :searchComments,             String
+  member :estimatedTotalResultsCount, Integer
+  member :estimateIsExact,            TrueClass
+  member :resultElements,             [ResultElement]
+  member :searchQuery,                String
+  member :startIndex,                 Integer
+  member :endIndex,                   Integer
+  member :searchTips,                 String
+  member :directoryCategories,        [DirectoryCategory]
+  member :searchTime,                 Float
+end
+
+
+class SearchController < ApplicationController
+  wsdl_service_name    'GoogleSearch'
+  export_name_mangling false
+
+  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
+
+  export :doGetCachedPage,         :returns => [String], :expects => [{:key=>String}, {:url=>String}]
+  export :doGetSpellingSuggestion, :returns => [String], :expects => [{:key=>String}, {:phrase=>String}]
+
+  export :doGoogleSearch, :returns => [GoogleSearchResult], :expects => [
+    {:key=>String},
+    {:q=>String},
+    {:start=>Integer},
+    {:maxResults=>Integer},
+    {:filter=>TrueClass},
+    {:restrict=>String},
+    {:safeSearch=>TrueClass},
+    {:lr=>String},
+    {:ie=>String},
+    {:oe=>String}
+  ]
+
+  private
+    def category(name, encoding)
+      cat = DirectoryCategory.new
+      cat.fullViewableName = name.dup
+      cat.specialEncoding = encoding.dup
+      cat
+    end
+end

data/examples/metaWeblog/README

@@ -0,0 +1,28 @@
+= metaWeblog example
+
+
+This example shows how one might begin to go about adding metaWeblog
+(http://www.xmlrpc.com/metaWeblogApi) API support to a Rails-based
+blogging application.
+
+
+= Running
+
+  1. Ensure you have the 'actionservice' Gem installed. You can generate it using
+     this command:
+
+       $ rake package
+
+
+  2. Edit config/environment.rb, and add the following line after the rest of the
+     require_gem statements:
+
+      require_gem 'actionservice'
+
+
+  3. Copy blog_controller.rb to "app/controllers" in a Rails project.
+
+
+  4. Fire up a desktop blogging application (such as BloGTK on Linux),
+     point it at http://localhost:3000/blog/api, and try creating or
+     editing blog posts.

data/examples/metaWeblog/blog_controller.rb

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