jruby-rack-worker 0.3-jruby → 0.4-jruby

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright (c) 2010 Karol Bucek
+   Copyright (c) 2010-2012 Karol Bucek
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -1,48 +1,47 @@
-JRuby Rack Worker
-=================
+# JRuby Rack Worker
 
-Java based thread worker implementation over [jruby-rack](http://github.com/nicksieger/jruby-rack).
+Thread based workers on top of [jruby-rack](http://github.com/jruby/jruby-rack).
 
-Natively supports [Delayed::Job](http://github.com/collectiveidea/delayed_job) and
-[Navvy](http://github.com/jeffkreeftmeijer/navvy) but one can easily write his own
-worker loop.
+With out of the box [JRuby](http://jruby.org) "adapters" for: 
 
+* [Resque](http://github.com/defunkt/resque) (**COMING SOON**)
+* [Delayed::Job](http://github.com/collectiveidea/delayed_job)
+* [Navvy](http://github.com/jeffkreeftmeijer/navvy) 
 
-Motivation
-----------
+... but one can easily write/adapt his own worker loop.
 
-While migrating a rails application to [JRuby](http://jruby.org) I found myself
-stuck with [Delayed::Job](http://github.com/collectiveidea/delayed_job). I wanted
-to deploy the application without having to spawn a separate daemon process in
-another *Ruby* (as *JRuby* is not daemonizable the [daemons](http://daemons.rubyforge.org)
-way).
 
-Well, why not spawn a "daemon" thread looping over the jobs from the servlet
-container ... after all the java world is inherently thread-oriented !
+## Motivation
 
-This does have the advantage of keeping the deployment simple and saving some
-precious memory (most notably with `threadsafe!` mode) that would have been
-eaten by the separate process. Besides Your daemons start benefiting from
-JRuby's (as well as Java's) runtime optimalizations ...
+Ruby attempts to stay pretty close to UNIX and most popular workers have been 
+modeled the spawn a background process way. [JRuby](http://jruby.org) brings 
+Java to the table, where "Young Java Knights" are thought to use threads 
+whenever in a need to compute something parallel while serving requests.
+
+There's no right or wrong way of doing this. If you do expect chaos like Resque
+proclaims - have long running jobs that consume a lot of memory they have trouble 
+releasing (e.g. due C extensions) run a separate process for sure.
+But otherwise (after all C exts usually have a native Java alternative on JRuby) 
+having predictable thread-safely written workers, one should be fine with 
+running them concurrently as part of the application in a daemon thread.
 
-On the other hand Your jobs should be simple and complete "fast" (in a rate of
-seconds rather than several minutes or hours) as they will restart and live with
-the lifecycle of the deployed application and/or application server.
+This does have the advantage of keeping the deployment simple and saving some
+precious memory (most notably with `threadsafe!` mode) that would have been 
+eaten by the separate process. Besides, your application might warm up faster 
+and start benefiting from JRuby's runtime optimalizations slightly sooner ...
 
-Java purist might objects the servlet specification does not advise spawning
-daemon threads in a servlet container, objection noted. Whether this style of
-asynchronous processing suits Your limits, needs and taste is entirely up to
-You.
+On the other hand your jobs should be fairly simple and complete "fast" (in a 
+rate of seconds rather than several minutes or hours) as they will live and 
+restart with the lifecycle of the deployed application and application server.
 
 
-Setup
-=====
+## Setup
 
 Copy the `jruby-rack-worker.jar` into the `lib` folder or the directory being
 mapped to `WEB-INF/lib` e.g. `lib/java`.
 
-Configure the worker in `web.xml`, You'll need to add a servlet context listener
-that will start threads when You application boots and a script to be executed
+Configure the worker in `web.xml`, you'll need to add a servlet context listener
+that will start threads when your application boots and a script to be executed
 (should be an "endless" loop-ing script). Sample configuration :
 
     <context-param>
@@ -57,55 +56,81 @@ that will start threads when You application boots and a script to be executed
       <listener-class>org.kares.jruby.rack.WorkerContextListener</listener-class>
     </listener>
 
-**NOTE**: The `WorkerContextListener` needs to be executed (and thus configured)
-after the `RailsServletContextListener`/`RackServletContextListener` as it expects
-the *jruby-rack* environment to be available.
+The `WorkerContextListener` needs to be executed (and thus configured) after the 
+`RailsServletContextListener`/`RackServletContextListener` as it expects the 
+*jruby-rack* environment to be available.
 
-**NOTE**: If You're not using `threadsafe!` than You really **should** ...
+Sample deployment descriptor including optional parameters:
+[web.xml](/kares/jruby-rack-worker/blob/master/src/test/resources/sample.web.xml).
 
-**NOTE**: If You're still not using `threadsafe!` mode than You're polling several
-(non-thread-safe) JRuby runtimes instances while serving requests, the *workers
-are nor running as a part of the application* thus each worker thread will remove
-and use (block) an application runtime from the instance pool (consider it while
-setting the `jruby.min.runtimes`/`jruby.max.runtimes` parameters) !
+### Warbler
 
-Sample Rails `web.xml` usable with [Warbler](http://caldersphere.rubyforge.org/warbler)
-including optional configuration parameters
-[web.xml](/kares/jruby-rack-worker/blob/master/src/test/resources/warbler.web.xml).
+If you're using [Warbler](http://caldersphere.rubyforge.org/warbler) to assemble
+your application you might simply declare a gem dependency with Bundler as your
+gems will be scanned for jars and packaged correctly:
 
-A simpler configuration using the built-in `Delayed::Job` / `Navvy` support :
+    gem 'jruby-rack-worker', :platform => :jruby, :require => nil
 
-    <context-param>
-      <param-name>jruby.worker</param-name>
-      <param-value>delayed_job</param-value> <!-- or navvy -->
-    </context-param>
+Otherwise copy the jar into your *warble.rb* configured `config.java_libs`.
 
-    <listener>
-      <listener-class>org.kares.jruby.rack.WorkerContextListener</listener-class>
-    </listener>
+Warbler checks for a *config/web.xml.erb* thus configure the worker there, e.g. :
 
+    <!DOCTYPE web-app PUBLIC
+      "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+      "http://java.sun.com/dtd/web-app_2_3.dtd">
+    <web-app>
+    <% webxml.context_params.each do |k,v| %>
+      <context-param>
+        <param-name><%= k %></param-name>
+        <param-value><%= v %></param-value>
+      </context-param>
+    <% end %>
 
-Build
-=====
+      <filter>
+        <filter-name>RackFilter</filter-name>
+        <filter-class>org.jruby.rack.RackFilter</filter-class>
+      </filter>
+      <filter-mapping>
+        <filter-name>RackFilter</filter-name>
+        <url-pattern>/*</url-pattern>
+      </filter-mapping>
 
-[JRuby](http://jruby.org) 1.5+ is required to build the project.
-The build is performed by [rake](http://rake.rubyforge.org) which should be part
-of the JRuby installation, if You're experiencing conflicts with another Ruby and
-it's rake executable use `jruby -S rake` instead of the bare `rake` command.
+      <listener>
+        <listener-class><%= webxml.servlet_context_listener %></listener-class>
+      </listener>
 
-Build the `jruby-rack-worker.jar` using :
+    <% if webxml.jndi then [webxml.jndi].flatten.each do |jndi| %>
+      <resource-ref>
+        <res-ref-name><%= jndi %></res-ref-name>
+        <res-type>javax.sql.DataSource</res-type>
+        <res-auth>Container</res-auth>
+      </resource-ref>
+    <% end; end %>
 
-    rake jar
+      <!-- jruby-rack-worker setup using the built-in libraries support : -->
 
-Build the gem (includes the jar) :
+      <context-param>
+        <param-name>jruby.worker</param-name>
+        <param-value>delayed_job</param-value> <!-- or resque or navvy -->
+      </context-param>
 
-    rake gem
+      <listener>
+        <listener-class>org.kares.jruby.rack.WorkerContextListener</listener-class>
+      </listener>
+
+    </web-app>
 
-Run the tests with :
 
-    rake test
+If you're deploying a Rails application on JRuby it's highly **recommended** to 
+uncomment `config.threadsafe!`. Otherwise, if unsure or you're code is not 
+thread-safe yet you'll end up polling several JRuby runtimes in a single process, 
+in this case however each worker thread will use (block) an application runtime 
+from the pool (consider it while setting 
+`jruby.min.runtimes` and `jruby.max.runtimes` parameters).
 
 
+### Custom Workers
+
 Worker Migration
 ================
 
@@ -117,17 +142,35 @@ most probably need to start by looking at the current worker spawning script
  * avoid native gems such as daemons (in DJ's case this means avoiding the whole
    `Delayed::Command` implementation)
 
- * remove command line processing - all Your configuration should happen in an
+ * remove command line processing - all your configuration should happen in an
    application initializer or the `web.xml`
 
- * make sure the worker code is thread-safe in case Your application is running
+ * make sure the worker code is thread-safe in case your application is running
    in `threadsafe!` mode (make sure no global state is changing by the worker or
    class variables are not being used to store worker state)
 
- * refactor Your worker's exit code from a (process oriented) signal based `trap`
-   to `at_exit` - which respects better the JRuby environment Your workers are
+ * refactor your worker's exit code from a (process oriented) signal based `trap`
+   to `at_exit` - which respects better the JRuby environment your workers are
    going to run in
 
 
 See the [Delayed::Job](/kares/jruby-rack-worker/tree/master/src/main/ruby/delayed)
 JRuby "adapted" worker code for inspiration.
+
+
+## Build
+
+[JRuby](http://jruby.org) 1.5+ is required to build the project.
+The build is performed by [rake](http://rake.rubyforge.org) which should be part
+of your JRuby installation, if you're experiencing conflicts with another Ruby and
+it's rake executable use `jruby -S rake` instead of the bare `rake` command.
+Besides you'll to need [ant](http://ant.apache.org/) installed for the Java part.
+
+Build the `jruby-rack-worker.jar` using :
+
+    rake jar
+
+Build the gem (with the jar packaged) :
+
+    rake gem
+

data/lib/jruby/rack/worker/version.rb

@@ -1,7 +1,7 @@
 module JRuby
   module Rack
     module Worker
-      VERSION = '0.3'
+      VERSION = '0.4'
     end
   end
 end

metadata

@@ -2,7 +2,7 @@
 name: jruby-rack-worker
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: "0.3"
+  version: "0.4"
 platform: jruby
 authors: 
   - Karol Bucek
@@ -10,8 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-24 00:00:00 +02:00
-default_executable: 
+date: 2012-07-05 00:00:00 Z
 dependencies: 
   - !ruby/object:Gem::Dependency 
     name: jruby-rack
@@ -21,10 +20,10 @@ dependencies:
       requirements: 
         - - ">="
           - !ruby/object:Gem::Version 
-            version: 1.0.1
+            version: 1.1.1
     type: :runtime
     version_requirements: *id001
-description: Implements a thread based worker using JRuby-Rack (a.k.a. Delayed Job for Java). Usable in servlet containers.
+description: Implements a thread based worker pattern on top of JRuby-Rack. Useful if you'd like to run a worker loop (such as Delayed::Job or Resque) as part of your web-application (concurrently in a separate thread) instead of using a separate process. To be used with a servlet containers.
 email: 
   - self@kares.org
 executables: []
@@ -36,10 +35,9 @@ extra_rdoc_files: []
 files: 
   - README.md
   - LICENSE
+  - lib/jruby-rack-worker_0.4.jar
   - lib/jruby_rack_worker.rb
-  - lib/jruby-rack-worker_0.3.jar
   - lib/jruby/rack/worker/version.rb
-has_rdoc: true
 homepage: http://github.com/kares/jruby-rack-worker
 licenses: []
 
@@ -62,10 +60,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
         version: "0"
 requirements: []
 
-rubyforge_project: 
-rubygems_version: 1.5.1
+rubyforge_project: "[none]"
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
-summary: Simple Worker for JRuby-Rack
+summary: Simple Worker with JRuby-Rack
 test_files: []