ap4r 0.1.0 → 0.1.1

data/CHANGELOG

@@ -1,6 +1,10 @@
-CHANGELOG
+== 0.1.x
 
-== 0.1.0
+=== 0.1.1 (October 5th, 2006)
 
-* Initial release.
+* Changed: Enriched RDoc.
+* Changed: Enriched README.
+
+=== 0.1.0 (September 1st, 2006)
 
+* Initial release.

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006  ???
+Copyright (c) 2006  Future System Consulting Corp.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README

@@ -1,52 +1,196 @@
-We are pleased to announce the FIRST release of AP4R.
- 
-    http://rubyforge.org/projects/ap4r/
-    
- 
-== DESCRIPTION
- 
-AP4R, Asynchronous Processing for Ruby, is the implementation of 
-reliable asynchous message processing. 
- 
-
-Using asynchronous processing, we can cut down turn-around-time 
-of web applications by queuing, or can utilize more machine power 
-by load-balancing.
- 
-AP4R provides message queuing, and message dispatching.
-Also AP4R nicely ties with your Ruby on Rails applications.
- 
-
-== INSTALLATION
- 
-sudo gem install ap4r
- 
-
-== FEATURES
- 
-* Business logics can be implemented as simple Web apps, or ruby code,
-  whether it's called asynchronously or synchronously.
- 
-* Asynchronous messaging are reliable
-  by PersistRDBMS (now MySQL only) or file persistence.
- 
-* Load balancing over multiple AP4R processes on single/multiple servers 
- is supported.
- 
-* Asynchronous processing is via various protocols, such as XML-RPC, SOAP,
-  HTTP PUT, and more. (now implemented just as XML-RPC) 
- 
-
-== CHANGES
- 
-This is the first release!
- 
-
-== ACKNOWLEDGEMENT
- 
-K.K. and S.S. are on the payroll of Future System Consulting Corp. Japan.
- 
-
---
-Kato, Kiwamu          kato.kiwamu@future.co.jp
-Shinohara, Shunichi   shinohara.shunichi@future.co.jp
+== What is AP4R?
+
+AP4R, Asynchronous Processing for Ruby, is the implementation of reliable asynchronous message processing. It provides message queuing, and message dispatching.
+Using asynchronous processing, we can cut down turn-around-time of web applications by queuing, or can utilize more machine power by load-balancing.
+Also AP4R nicely ties with your Ruby on Rails applications. See Hello World sample application from rubyforge.
+
+http://rubyforge.org/projects/ap4r/
+
+== Features
+
+1. Business logics can be implemented as simple Web applications, or ruby code, whether it's called asynchronously or synchronously.
+1. Asynchronous messaging is reliable by RDBMS persistence (now MySQL only) or file persistence, under the favor of reliable-msg.
+1. Load balancing over multiple AP4R processes on single/multiple servers is supported.
+1. Asynchronous logics are called via various protocols, such as XML-RPC, SOAP, HTTP PUT, and more. (now implemented just as XML-RPC) 
+
+== Typical process flow
+
+1. A client(e.g. a web browser) makes a request to a web server (Apache, Lighttpd, etc...).
+1. A rails application (a synchronous logic) is executed on mongrel via mod_proxy or something.
+1. At the last of the synchronous logic, message(s) are put to AP4R (AP4R provides a helper).
+1. Once the synchronous logic is done, the clients receives a response immediately.
+1. AP4R queues the message, and requests it to the web server asynchronously.
+1. An asynchronous logic, implemented as usual rails action, is executed. 
+
+
+== Installation
+
+Use RubyGems command.
+
+  $ sudo gem install ap4r --include-dependencies
+
+
+== Working directory
+
+Create your working directory (ex. my_work) wherever you want.
+
+  $ ap4r_setup my_work
+  $ cd my_work
+
+Its structure is as follows.
+
+  my_work
+   +-- config
+   +-- log
+   +-- script
+   +-- tmp
+
+== Message Persistence
+
+AP4R uses reliable-msg for message persistence. It enables disk or RDBMS persistence. See references for details of reliable-msg. Install MySQL if you choose MySQL persistence. We recommend to install MySQL/Ruby library to connect to MySQL. For convinience, Ruby/MySQL bundled in the ActiveRecord gem can be used.
+Create a table in your database. (If you use topics via reliable-msg, create another slightly different table.)
+
+  CREATE TABLE `reliable_msg_queues` (
+    `id` varchar(255) NOT NULL default '',
+    `queue` varchar(255) NOT NULL default '',
+    `headers` text NOT NULL,
+    `object` blob NOT NULL,
+    PRIMARY KEY  (`id`)
+  ) ENGINE=InnoDB DEFAULT CHARSET=binary;
+
+== Configuration file
+
+A command ap4r_setup have created a template configuration file (my_work/config/queues.cfg).
+
+  --- 
+  store: 
+    type: mysql
+    host: localhost
+    database: test
+    username: test
+    password: 
+  drb: 
+    host: 
+    port: 6438
+    acl: allow 127.0.0.1
+  dispatchers:
+    -
+      targets: queue.*
+      threads: 1
+  #carriers:
+  #  - 
+  #    source_uri: druby://another.host.local:6438
+  #    threads: 1
+
+queues.cfg has four parts.
+
+* persistent role (store: )
+  * Set database or file information. 
+
+* message listener (drb:)
+  * Set IP, and port number which are used by clients.
+  * acl = access control list, exmaple below.
+
+    allow 127.0.0.1 allow 10.0.0.0/8 deny 192.168.0.1
+
+* asynchronous process invokers (dispatchers:)
+  * Dispatchers handle messages in queues specified by targets,
+  * with as many threads as specified by threads.
+  * Each thread waits (is blocked) until the invocation returns. 
+
+* message routing (carriers:) # EXPERIMENTAL
+  * Carriers get messages from an AP4R server specified by source_uri,
+  * with as many threads as specified by threads,
+  * and put messages to a local AP4R server. 
+
+== Monitoring
+
+Future plan: connections with monitoring tools such as Cacti and ZABBIX.
+
+* Cacti
+  * http://www.cacti.net/ 
+* ZABBIX
+  * http://www.zabbix.org/ 
+
+== Sample - HelloWorld -
+
+There is an asynchronous application sample with file persistence, where a synchronous logic outputs "Hello" to a file, and an asynchronous logic appends "World".
+Once the synchronous logic has done, a client (a web browser) displays response, and there is only "Hello" in a file.
+Since the asynchronous logic sleeps ten seconds and appends to the file, wait briefly and you can see whole "HelloWorld" in the file
+
+* Install Ruby, Rails and AP4R and configure AP4R in reference above sections
+  * No need for MySQL. 
+
+* Make sample application available
+  * If you have an SVN client,
+
+     $ svn co svn://rubyforge.org/var/ap4r/tags/ap4r-0.1.0/sample [some directory]
+
+  * Unless
+    1. download the sample from RubyForge      
+        http://rubyforge.org/projects/ap4r/
+        filename: HelloWorld.zip 
+
+    1. and extract to an appropricate directory(ex. HelloWorld ).
+       There are app/, components/,... directories under HelloWorld. 
+
+* Start WEBRick.
+  * In a command line
+
+     $ cd HelloWorld
+     $ ruby script\server
+
+  * If you see Welcome screen at http://localhost:3000, it's ok. 
+
+* Start AP4R.
+  * In another command line,
+  * start AP4R with specifying the configuraion file.
+
+     $ cd my_work
+     $ ruby script/start -c config/queues_disk.cfg
+
+* Execute a synchronous logic.
+  * http://localhost:3000/sync_hello/execute
+  * A file HelloWorld.txt is creted under HelloWorld/ which contains a word "Hello". 
+
+* Confirm the execution of an asynchronous logic.
+  * Wait ten seconds,
+  * and look into the file HelloWorld.txt again, there must be "HelloWorld". 
+
+* Think of application to your real application
+  * This mechanism can work in general applications.
+    * An order acceptance logic instead of printing "Hello".
+    * Asynchronous logic of auto shipping order or accounting instead of appending "World". 
+
+== Future Plan
+
+* add protocols to invoke asynchronous logics
+* only-once QoS
+* at-lease-once QoS
+* DLQ recovery
+* flow volume control, load balancing
+* 7x24 support (e.g. rolling database tables)
+* monitoring (e.g. thread status, web frontend)
+* Coordination with Ruby on Rails, such as development/testing lifesycle support. 
+
+== References
+
+* Ruby Homepage
+  * http://www.ruby-lang.org/ 
+* Ruby on Rails tutorial
+  * http://www.onlamp.com/pub/a/onlamp/2005/01/20/rails.html 
+* MySQL tutorial
+  * http://dev.mysql.com/doc/refman/5.0/en/index.html 
+* reliable-msg
+  * http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/Ruby/ReliableMessaging 
+
+== Licence
+
+This licence is licensed under the MIT license.
+Copyright(c) 2006 Future System Consulting Corp.
+
+== Authors
+
+* Kiwamu Kato
+* Shunichi Shinohara
+

data/Rakefile

@@ -1,25 +1,143 @@
-require 'rubygems'
+# Author:: Kiwamu Kato
+# Copyright:: Copyright (c) 2006 Future System Consulting Corp.
+# Licence:: MIT Licence
+
 require 'rake'
 require 'rake/testtask'
 require 'rake/rdoctask'
-require 'rake/packagetask'
 require 'rake/gempackagetask'
 require 'rake/contrib/rubyforgepublisher'
 
-Gem::Specification.new do |s|
-  s.name = %q{orca}
-  s.version = "0.1.0"
-  s.date = %q{2006-05-18}
-  s.summary = %q{Messageing library with Rails for asynchronous process.}
-  s.email = %q{kato.kiwamu@future.co.jp}
-  s.homepage = %q{http://orca2.rtfa.local/orca/}
-  s.rubyforge_project = %q{}
-  s.description = %q{Messageing library with Rails for asynchronous proces.}
-  s.autorequire = %q{orca}
+require 'date'
+require 'find'
+require 'rbconfig'
+
+require File.join(File.dirname(__FILE__), 'lib/ap4r', 'version')
+
+PKG_VERSION = AP4R::VERSION::STRING
+
+TEMP_DIR = './temp'
+PKG_DIR = './pkg'
+RELEASE_DIR = './release'
+HELLO_WORLD_DIR = '../samples/HelloWorld'
+
+# Generate GEM ----------------------------------------------------------------------------
+
+
+PKG_FILES = FileList[
+  '[a-zA-Z]*',
+  'bin/**/*', 
+  'config/**/*',
+  'rails_plugin/**/*',
+  'script/**/*',
+  'lib/**/*'
+]
+
+HELLO_WORLD_SAMPLE_FILES = FileList[
+  '[a-zA-Z]*',
+  'app/**/*', 
+  'components/**/*',
+  'config/**/*',
+  'db/**/*',
+  'doc/**/*',
+  'lib/**/*', 
+  'log/**/*',
+  'public/**/*',
+  'script/**/*',
+  'test/**/*',
+  'tmp/**/*', 
+  'vendor/**/*',
+]
+
+
+spec = Gem::Specification.new do |s|
+  s.name = 'ap4r'
+  s.version = PKG_VERSION
+  s.summary = "Asynchronous Processing for Ruby."
+  s.description = <<-EOF
+    Asynchronous Processing for Ruby.
+  EOF
+
+  s.add_dependency(%q<reliable-msg>, ["= 1.1.0"])
+
   s.has_rdoc = true
-  s.authors = ["Shino,Kato"]
-  s.files = Dir.glob("{script,lib,logs,utils}/**/*") << "CHANGELOG" << "log4r.yaml" << "MIT-LICENSE" << "queues.cfg" << "queues1.cfg" << "queues2.cfg" << "Rakefile" << "README"
-  s.requirements = ["none"]
+  s.extra_rdoc_files = ["README", "CHANGELOG", 'rails_plugin']
+  s.rdoc_options << "--main" << "README"
+  s.rdoc_options << "--title" << "Asynchronous Processing for Ruby" 
+  s.rdoc_options << "--line-numbers"
+
+
+  s.files = PKG_FILES.to_a.delete_if {|f| f.include?('.svn')}
+  s.require_path = 'lib'
+  s.autorequire = %q{ap4r.rb}
+
+  s.bindir = "bin"                               # Use these for applications.
+  s.executables = ["ap4r_setup"]
+  s.default_executable = "ap4r_setup"
+
+  s.authors = ["Shunichi Shinohara", "Kiwamu Kato"]
+  s.email = %q{shinohara.shunichi@future.co.jp, kato.kiwamu@future.co.jp}
+  s.homepage = %q{http://rubyforge.org/projects/ap4r/}
+  s.rubyforge_project = "ap4r"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
 end
 
+# Generate documentation ------------------------------------------------------------------
+
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.options << '--line-numbers' << '--inline-source' << '--accessor' << 'cattr_accessor=rw'
+  rdoc.rdoc_files.include('README', 'CHANGELOG')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('rails_plugin/**/*.rb')
+}
+
+# AP4R release ----------------------------------------------------------------
+
+desc "Make gem and sample tgz"
+task :release => [ :make_release_dir, :make_sample_tgz, :copy_to_release_dir ]
+
+task :make_sample_tgz => [ :make_temp_dir, :copy_sample, :make_tgz ]
+
+task :make_release_dir do
+  make_dir RELEASE_DIR
+end
+
+task :make_temp_dir do
+  make_dir TEMP_DIR
+end
+
+def make_dir(path)
+  if(File.exist?(path))
+    FileUtils.remove_entry(path, true)
+  end
+  FileUtils.mkdir_p(path)
+end
+
+
+task :copy_sample do  
+  FileUtils.cp_r(HELLO_WORLD_DIR, TEMP_DIR)
+  Find.find(TEMP_DIR) {|f|
+    if f.include?('.svn')
+      FileUtils.rm_rf(f)
+    end
+  }
+end
+
+task :make_tgz do
+  Dir.chdir('temp/')
+  `tar czvf HelloWorld.tar.gz HelloWorld/`
+  Dir.chdir('../')
+end
+
+task :copy_to_release_dir do
+  Dir.foreach(PKG_DIR) {|f|
+    FileUtils.cp(PKG_DIR + '/' + f, RELEASE_DIR) if File.fnmatch("*.gem", f)
+  }
+  Dir.foreach(TEMP_DIR) {|f|
+    FileUtils.cp(TEMP_DIR + '/' + f, RELEASE_DIR) if File.fnmatch("*.tar.gz", f)
+  }
+end
 

data/bin/ap4r_setup

@@ -0,0 +1,6 @@
+Signal.trap("INT") { puts; exit }
+
+require File.dirname(__FILE__) + '/../lib/ap4r/script/setup'
+
+require 'ap4r/script/workspace_generator'
+AP4R::Script::WorkspaceGenerator.new.run(ARGV, :generator => 'app')

data/config/ap4r_settings.rb

@@ -0,0 +1,5 @@
+AP4R::Configuration.setup {|services|
+  services.add 'queues_disk.cfg', :host => 'localhost', :name => :rm1
+#  services.add 'queues.cfg', :name => :rm2
+}
+