actionservice 0.2.99

data/CHANGELOG

@@ -0,0 +1,3 @@
+*0.2*
+
+* First release

data/HACKING

@@ -0,0 +1,39 @@
+== Coding Style
+
+Please try to follow Rails conventions and idioms.
+
+
+== Concepts
+
+  * Service
+    A service contains zero or more exports (methods)
+
+  * Container
+    A container contains zero or more services
+
+  * Router
+    A router takes raw wire requests, decodes them, performs the invocation on
+    the service, and generates raw wire responses from the invocation result.
+    A router is mixed into a container class.
+
+  * Protocol
+    A protocol implementation implements the unmarshaling and marshaling of 
+    raw wire requests and responses. Registers with router.
+
+
+== Action Pack Integration
+
+For Action Pack, the ActionController is both container and router, and also contains
+the protocol implementations.
+
+
+== Adding support for a new protocol
+
+  1. Add an ActionService::Protocol::YourProtocol module and any classes you need to
+     perform unmarshaling/marshaling of protocol requests. See the SOAP implementation
+     for an example of a complex mapping, and also see
+     ActionService::Protocol::AbstractProtocol for the methods you need to implement.
+
+  2. Add unit tests for your new protocol. Be sure to test using a Action Pack test request
+     duplicating how the real requests will arrive and verify that mapping to and from Ruby
+     types works correctly.

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,36 @@
+= Action Service -- Web service integration with Action Pack
+
+FIXME
+
+== Dependencies
+
+Action Service requires that the Action Pack is either available to be required immediately
+or is accessible as a GEM.
+
+It also requires a version of Ruby that includes SOAP support in the standard library. At
+least version 1.8.2 final is recommended.
+
+
+== Download
+
+
+FIXME
+
+
+== Installation
+
+You can install Action Service with the following command.
+
+  % [sudo] ruby install.rb
+
+from its distribution directory.
+
+
+== License
+
+Action Service is released under the MIT license.
+
+
+== Support
+
+FIXME

data/Rakefile

@@ -0,0 +1,121 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+
+PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+PKG_NAME      = 'actionservice'
+PKG_VERSION   = '0.2.99' + PKG_BUILD
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+desc "Default Task"
+task :default => [ :test ]
+
+
+# Run the unit tests
+Rake::TestTask.new { |t|
+  t.libs << "test"
+  t.pattern = 'test/*_test.rb'
+  t.verbose = true
+}
+
+
+# Generate the RDoc documentation
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "Action Service -- Web services for Action Pack"
+  rdoc.options << '--line-numbers --inline-source --main README'
+  rdoc.rdoc_files.include('README', 'CHANGELOG')
+  rdoc.rdoc_files.include('lib/action_service.rb')
+  rdoc.rdoc_files.include('lib/action_service/*.rb')
+  rdoc.rdoc_files.include('lib/action_service/protocol/*.rb')
+  rdoc.rdoc_files.include('lib/action_service/router/*.rb')
+}
+
+
+# Create compressed packages
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.name = PKG_NAME
+  s.summary = "Web service support for Action Pack."
+  s.description = %q{Adds WSDL/SOAP and XML-RPC web service support to Action Pack}
+  s.version = PKG_VERSION
+
+  s.author = "Leon Breedt"
+  s.email = "bitserf@gmail.com"
+  s.rubyforge_project = "actionservice"
+  s.homepage = "http://rubyforge.org/projects/actionservice"
+
+  s.add_dependency('actionpack', '>= 1.4.0')
+
+  s.has_rdoc = true
+  s.requirements << 'none'
+  s.require_path = 'lib'
+  s.autorequire = 'action_service'
+
+  s.files = [ "Rakefile", "setup.rb", "README", "TODO", "HACKING", "CHANGELOG", "MIT-LICENSE" ]
+  s.files = s.files + Dir.glob( "examples/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
+  s.files = s.files + Dir.glob( "lib/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
+  s.files = s.files + Dir.glob( "test/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
+end
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+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
+  Rake::RubyForgePublisher.new('actionservice', 'ljb').upload
+end
+
+
+desc "Count lines in the main rake file"
+task :lines do
+  lines = 0
+  codelines = 0
+  prefix = File.join(File.dirname(__FILE__), 'lib')
+  puts "Per File:"
+  %w{
+    action_service
+    action_service/protocol
+    action_service/router
+  }.each do |dir|
+    Dir.foreach(File.join(prefix, dir)) { |file_name| 
+      next unless file_name =~ /.*rb$/
+      full_file_name = File.join(prefix, dir, file_name)
+    
+      f = File.open(full_file_name)
+
+      file_lines = 0
+      file_codelines = 0
+      while line = f.gets
+        file_lines += 1
+        next if line =~ /^\s*$/
+        next if line =~ /^\s*#/
+        file_codelines += 1
+      end
+      puts "  #{File.join('lib', dir, file_name)}: Lines #{file_lines}, LOC #{file_codelines}"
+      lines += file_lines
+      codelines += file_codelines
+    }
+  end
+  puts "Total:"
+  puts "  Lines #{lines}, LOC #{codelines}"
+end

data/TODO

@@ -0,0 +1,25 @@
+= Features Remaining
+  - XML-RPC support
+  - Support for ActiveRecord model classes as structure types as well, since
+    we can reflect all the details to do proper mapping from model classes.
+
+= Ideas
+  - <nextangle> Support a second dispatching mechanism, where incoming
+                operation requests are mapped directly to a controller action.
+
+    Advantages: No seperate API service class, the controller becomes the
+                service class.
+
+    Possible approaches:
+      Create a new router that maps an 'api' action to do dispatching using
+      itself as the target service.
+
+      This dispatching would:
+
+        * Unpack request parameters into @params
+        * Execute the action
+        * Use the return value of the action to send back to the client
+
+= Warts
+  - Don't have clean way to go from SOAP Class object to the xsd:NAME type
+    string

data/examples/soap/README

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

data/examples/soap/app/controllers/search_controller.rb

@@ -0,0 +1,8 @@
+require 'google_search_service'
+
+class SearchController < ApplicationController
+  wsdl_service_name 'GoogleSearch'
+  service :beta3, GoogleSearchService.new
+
+  # self.action_service_debugging = true
+end

data/examples/soap/lib/google_search_service.rb

@@ -0,0 +1,90 @@
+require 'action_service'
+
+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 GoogleSearchService < ActionService::Base
+  export_name_mangling false
+
+  def doGetCachedPage(key, url)
+    "<html><body>i am a cached page</body></html>"
+  end
+
+  def doSpellingSuggestion(key, phrase)
+    "Did you mean 'teh'?"
+  end
+
+  def doGoogleSearch(key, q, start, maxResults, filter, restrict, safeSearch, lr, ie, oe)
+    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 = 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 = start
+    result.endIndex = start + 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
+    result.directoryCategories = [
+      category("Web Development", "UTF-8"),
+      category("Programming", "US-ASCII"),
+    ]
+
+    result
+  end
+
+  def category(name, encoding)
+    cat = DirectoryCategory.new
+    cat.fullViewableName = name.dup
+    cat.specialEncoding = encoding.dup
+    cat
+  end
+
+  export :doGetCachedPage,         :returns => [String], :expects => [String, String]
+  export :doGetSpellingSuggestion, :returns => [String], :expects => [String, String]
+  export :doGoogleSearch,          :returns => [GoogleSearchResult], :expects => [String, String, Integer, Integer, TrueClass, String, TrueClass, String, String, String]
+end