simplews 1.1.5 → 1.1.6

data/History.txt

@@ -1,3 +1,9 @@
+== 1.1.6 2008-11-24
+
+* 1 minor enhancement:
+  * Added documentation
+
+
 == 1.1.5 2008-10-28
 
 * 1 major enhancement:

data/lib/simplews/asynchronous.rb

@@ -1,13 +1,98 @@
 require File.join(File.dirname(File.dirname(__FILE__)) + '/simplews')
 
 require 'yaml'
+
+# This class extends SimpleWS and allows provides with a framework to
+# run asynchronous jobs. Job are initiated and can be latter be accessed
+# using a unique job id. The status can be queried, and when finished,
+# the results can be gathered. Jobs are also able to save their states
+# between executions of the server.
+#
+# The class provides a instance function start_job, that receives a
+# block of code and creates a new thread to run this block of code. It
+# also provides some helper functions to set the state of the job, as
+# well as messages or to abort of report errors. 
+#
+# Each job can produce a number of results saved into files that can
+# latter be accessed by the client. At any time the code inside the
+# block can access any of the following helper functions: step, read,
+# write, abort_process, job_name and save. As in the following example.
+# (+process+ will be a method served by the server):
+#
+#   def process(name)
+#      start_job(name, %w(test.txt)) do
+#        begin
+#          write('test.txt', job_name)
+#          step(:init)
+#          sleep 2
+#          step(:step1, "Step1")
+#          sleep 2
+#          step(:step2, "Step2")
+#          sleep 2
+#          step(:step2, "Step3")
+#        rescue
+#          error($!.message)
+#        end
+#      end
+#   end
+#
+# Note that any file specified in the write or read method is relative
+# to the workdir directory. The optional array passed as second argument
+# to start_job lists the results the job will be generating and that
+# will be accessible latter to the clients, one could  have also done
+# this:
+#
+#   def process(name)
+#      actual_name = start_job(name) do
+#        begin
+#          write(job_name + ".txt", "Hi")
+#          step(:init)
+#          sleep 2
+#          step(:step1, "Step1")
+#          sleep 2
+#          step(:step2, "Step2")
+#          sleep 2
+#          step(:step2, "Step3")
+#        rescue
+#          error($!.message)
+#        end
+#      end
+#      
+#      set_results(actual_name, [ actual_name + ".txt" ])
+#      
+#      actual_name
+#   end
+#
+# Note in this example that the name provided to start_job is only a
+# suggestion, it a job is already available with that name a number will
+# be prepended to it. The actual name used is return by the start_job
+# method and is the one that must be used in the set_results method.
+# Also note that the +process+ method in the example has to return the
+# actual name of the job so it will be accessible to the client.
+#
+#
+# The clients have a number of methods available to query and modify the
+# state of the job, as well as to gather results: status, messages,
+# done, error, aborted, abort, results and result.
+# 
+#
+# While reading the documentation please note that there are three types
+# of methods here, methods used inside the web server methods, methods
+# used inside code blocks executed by Job Threads, and methods that are
+# exported by the web server. Its important to call each method in the
+# right context.
+#
 class SimpleWS::Asynchronous < SimpleWS
 
+  
   class JobNotFound < Exception; end
   class JobAborted < Exception; end
 
   
-  class Job < Thread
+  class Job < Thread # :nodoc:
+
+    private
+
     def self.random_name(s="", num=20)
       num.times{
         r = rand
@@ -40,6 +125,10 @@ class SimpleWS::Asynchronous < SimpleWS
       end
     end
 
+    public
+
+    # Returns the job specified in the +name+. If it is not currently
+    # found but it has a saved state, then it is loaded.
     def self.job(name)
       if @@jobs[name].nil?
         if File.exists?(File.join(@@workdir, ".save/#{name}.yaml"))
@@ -47,7 +136,7 @@ class SimpleWS::Asynchronous < SimpleWS
           job.load
           @@jobs[name] = job
         else
-          raise JobNotFound, "Job with name '#{ name }' was not found" 
+          raise SimpleWS::Asynchronous::JobNotFound, "Job with name '#{ name }' was not found" 
         end
       end
       @@jobs[name]
@@ -74,7 +163,7 @@ class SimpleWS::Asynchronous < SimpleWS
     def self.workdir=(workdir)
       @@workdir = workdir
       begin
-        FileUtils.mkdir(@@workdir) unless File.exist?( @@workdir)
+        FileUtils.mkdir_p(@@workdir) unless File.exist?( @@workdir)
         FileUtils.mkdir(File.join(@@workdir,'.save')) unless File.exist?( File.join(@@workdir,'.save'))
       rescue
         puts "Error creating work directory:"
@@ -139,9 +228,9 @@ class SimpleWS::Asynchronous < SimpleWS
       @name
     end
 
-    def step(status, message="")
+    def step(status, message= nil)
       @status = status
-      @messages << message if message != ""
+      @messages << message if message && message != ""
     end
 
     def read(path)
@@ -204,18 +293,37 @@ class SimpleWS::Asynchronous < SimpleWS
   ############################################################################################3
   #{{{ Server
 
+  # SERVER METHOD:
+  #
+  # Sets the workdir for the jobs
   def set_workdir(workdir)
     Job::workdir = workdir
   end
   
+  # SERVER METHOD:
+  #
+  # Returns the workdir that any jobs created will be using
   def workdir
     Job::workdir
   end
   
+  # SERVER METHOD:
+  #
+  # Starts a new job. The parameter +name+ is just a suggestion, if it
+  # is not available a number will be prepended to it. Results are a
+  # list of relative paths to files where results are expected to be
+  # stored. All paths are relative to the jobs workdir. Finally, block
+  # is the block of code to be executed by the Job Thread.
+  #
+  # Returns the actual name used as unique identifier for the job
   def start_job(name, results = [], &block)
     Job.start(name, results, &block)
   end
 
+  # SERVER METHOD:
+  #
+  # Sets the list of paths to results for a particular job. This
+  # overwrites the ones specified by start_job.
   def set_results(name, results)
     Job.job(name).results = results
   end
@@ -223,68 +331,154 @@ class SimpleWS::Asynchronous < SimpleWS
 
 
   #{{{ Thread helper methods
+  
+
+  # CODE HELPER FUNCTION:
+  #
+  # Saves the job to it can survive server restarts. This is
+  # automatically called when the code is finished.
   def save
     Thread.current.save
   end
 
- 
-  def write(*args)
-    Thread.current.write(*args)
+  # CODE HELPER FUNCTION:
+  #
+  # Writes +content+ into the file specified by +path+. The +path+`is
+  # taken relative to the job's workdir.
+  def write(path, content)
+    Thread.current.write(path, content)
   end
 
-  def step(*args)
-    Thread.current.step(*args)
+  # CODE HELPER FUNCTION:
+  #
+  # Reads the content of the file specified by +path+ relative to the
+  # job's workdir. 
+  def read(path)
+    Thread.current.read(path)
   end
 
-  def read(*args)
-    Thread.current.read(*args)
+
+  # CODE HELPER FUNCTION:
+  #
+  # Sets the status of the job and adds a message to the message queue
+  # if the message is specified, and is different from an empty string.
+  # This method is called automatically in the following situations.
+  #
+  # * The block has finished executing:
+  #      step(:done)
+  # * The job recieves an untreated SimpleWS::Asynchronous::JobAborted  exception
+  #      step(:aborted, $!.message)
+  # * The job recieves any other exception
+  #      step(:error, $!.message)
+  #
+  def step(status, message=nil)
+    Thread.current.step(status, message)
   end
 
+
+  # CODE HELPER FUNCTION:
+  #
+  # Returns the actual name of the job running the code.
   def job_name
     Thread.current.name
   end
 
+  # CODE HELPER FUNCTION:
+  #
+  # Aborts the job raising a SimpleWS::Asynchronous::JobAborted
+  # exception.
   def abort_process
     Thread.current.abort
   end
 
 
-
   #{{{ WS Methods
 
+  # CLIENT METHOD SERVED BY DEFAULT: 
+  #
+  # +name+ is the unique job identifier.
+  #
+  # Returns job status of the job.
   def status(name)
     Job.job(name).status
   end
 
+  # CLIENT METHOD SERVED BY DEFAULT:
+  #
+  # +name+ is the unique job identifier.
+  #
+  # Raises a SimpleWS::Asynchronous::JobAborted exception in the job
   def abort(name)
     Job.job(name).abort
   end
 
+  # CLIENT METHOD SERVED BY DEFAULT:
+  #
+  # +name+ is the unique job identifier.
+  #
+  # Checks if the job is still running or has finished, either normally
+  # or after been aborted or suffering an error.
   def done(name)
     Job.job(name).done?
   end
  
+  # CLIENT METHOD SERVED BY DEFAULT:
+  #
+  # +name+ is the unique job identifier.
+  #
+  # Checks if the job has been aborted.
   def aborted(name)
     Job.job(name).aborted?
   end
  
+  # CLIENT METHOD SERVED BY DEFAULT:
+  #
+  # +name+ is the unique job identifier.
+  #
+  # Checks if the job has suffered an error
   def error(name)
     Job.job(name).error?
   end
  
+  # CLIENT METHOD SERVED BY DEFAULT:
+  #
+  # +name+ is the unique job identifier.
+  #
+  # Returns the list of messages of the job.
   def messages(name)
     Job.job(name).messages
   end
  
+  # CLIENT METHOD SERVED BY DEFAULT:
+  #
+  # +name+ is the unique job identifier.
+  #
+  # Returns a list of unique results identifiers, one for each of the
+  # results of the job.
   def results(name)
     Job.job(name).results
   end
  
+  # CLIENT METHOD SERVED BY DEFAULT:
+  #
+  # +name+ is the unique job identifier.
+  # +result+ is the unique result identifier as returned by the results
+  # method.
+  #
+  # Retrieves a result of a given job.
   def result(name, result)
     Job.job(name).result(result)
   end
 
 
+  # Creates an instance. All the parameters are as in SimpleWS, except
+  # for the additional workdir parameter. It the workdir is not provided
+  # a directory in the /tmp directory with the name of the server will
+  # be used.
+  #
+  # It serves by default the methods: abort, messages, status, done,
+  # error, abort, aborted, results and result, as well as the +wsdl+
+  # method from SimpleWS.
   def initialize(name="WS", description="", host="localhost", port="1984", workdir=nil, *args)
     super(name, description, host, port, *args)
     @results = {}

data/lib/simplews/version.rb

@@ -2,7 +2,7 @@ module Simplews
   module VERSION #:nodoc:
     MAJOR = 1
     MINOR = 1
-    TINY  = 5
+    TINY  = 6
 
     STRING = [MAJOR, MINOR, TINY].join('.')
     self

data/lib/simplews.rb

@@ -2,8 +2,55 @@ require 'soap/rpc/standaloneServer'
 require 'builder'
 
 
+# SimpleWS is a class that wraps SOAP::RPC::StandaloneServer to ease the
+# implementation of Web Services, specifically the generation of the
+# +WSDL+ file. It provides a particular syntax that allows to specify
+# the methods that are going to be served along with the types of the
+# parameters and of the response so that the +WSDL+ can be generated
+# accordingly. Actual Servers can be instances of this class where
+# methods are assigned dynamically or of classes that extend SimpleWS.
+#   class TestWS < SimpleWS
+#    def hi(name)
+#      "Hi #{name}, how are you?"
+#    end
+#
+#    def initialize(*args)
+#      super(*args)
+#      serve :hi, %w(name), :name => :string, :return => :string
+#
+#      serve :bye, %w(name), :name => :string, :return => :string do |name|
+#          "Bye bye #{name}. See you soon."
+#      end
+#
+#    end
+#  end
+#
+#  # Creating a server and starting it
+#  
+#  server = TestWS.new("TestWS", "Greeting Services", 'localhost', '1984') 
+#  server.wsdl("TestWS.wsdl")
+#
+#  Thread.new do
+#     server.start
+#  end
+#
+#  # Client code. This could be run in another process.
+#
+#  driver = SimpleWS::get_driver('http://localhost:1984', "TestWS")
+#  puts driver.hi('Gladis')  #=> "Hi Gladis, how are you?"
+#  puts driver.bye('Gladis') #=> "Bye bye Gladis. See you soon."
+#
+
+
+
 class SimpleWS <  SOAP::RPC::StandaloneServer
 
+  # This is a helper function for clients. Given the +url+ where the
+  # server is listening, as well as the name of the server, it can
+  # manually access the +wsdl+ function and retrieve the complete +WSDL+
+  # file. This works *only* in web servers of class SimpleWS, not on
+  # the general SOAP::RPC::StandaloneServer or any other type of web
+  # server.
   def self.get_wsdl(url, name)
      require 'soap/rpc/driver'
      driver = SOAP::RPC::Driver.new(url, "urn:#{ name }")
@@ -11,6 +58,8 @@ class SimpleWS <  SOAP::RPC::StandaloneServer
      driver.wsdl
   end
 
+  # Builds on the get_wsdl function to provide the client with a
+  # reference to the driver. Again, only works with SimpleWS servers.
   def self.get_driver(url, name)
     require 'soap/wsdlDriver'
     require 'fileutils'
@@ -24,6 +73,12 @@ class SimpleWS <  SOAP::RPC::StandaloneServer
     driver
   end
 
+  # Creates an instance of a Server. The parameter +name+ specifies the
+  # +namespace+ used in the +WSDL+, +description+ is the description
+  # also included in the +WSDL+. The parameters +host+ and +port+,
+  # specify where the server will be listening, they are parameters of
+  # the +super+ class SOAP::RPC::StandaloneServer, they are made
+  # explicit here because they are included in the +WSDL+ as well.
   def initialize(name="WS", description="", host="localhost", port="1984", *args)
     super(description, "urn:#{ name }", host, port, *args)
     @host        = host
@@ -37,11 +92,20 @@ class SimpleWS <  SOAP::RPC::StandaloneServer
     serve :wsdl, %w(),  :return => :string
   end
 
-  def name
-    @name
-  end
-
 
+  # This method tells the server to provide a method named by the +name+
+  # parameter, with arguments listed in the +args+ parameter. The
+  # +types+ parameter specifies the types of the arguments as will be
+  # described in the +WSDL+ file (see the TYPES2WSDL constant). The
+  # actual method called will be the one with the same name. Optionally
+  # a block can be provided, this block will be used to define a
+  # function named as in name.
+  #
+  # If the method returns something, then the type of the return value
+  # must be specified in the +types+ parameter as :return. If not value
+  # for :return parameter is specified in the +types+ parameter the
+  # method is taken to return no value. Other than that, if a parameter
+  # type is omitted it is taken to be :string.
   def serve(name, args=[], types={}, &block)
     
     if block
@@ -54,6 +118,11 @@ class SimpleWS <  SOAP::RPC::StandaloneServer
     nil
   end
 
+  # If +filename+ is specified it saves the +WSDL+ file in that file. If
+  # no +filename+ is specified it returns a string containing  the
+  # +WSDL+. The no parameter version is served by default, so that
+  # clients can use this method to access the complete +WSDL+ file, as
+  # used in get_wsdl and get_driver.
   def wsdl(filename = nil)
     wsdl = WSDL_STUB.dup
     wsdl.gsub!(/\$\{MESSAGES\}/m,@messages.join("\n"))
@@ -83,7 +152,7 @@ class SimpleWS <  SOAP::RPC::StandaloneServer
       args.each{|param|
         type = types[param.to_s] || types[param.to_sym] || :string
         type = type.to_sym
-        xml.part :name => param, :type => @@type2wsdl[type]
+        xml.part :name => param, :type => TYPES2WSDL[type]
       }
     end
     @messages << message
@@ -91,7 +160,7 @@ class SimpleWS <  SOAP::RPC::StandaloneServer
       type = types[:return] || types["return"]
       if type
         type = type.to_sym
-        xml.part :name => 'return', :type => @@type2wsdl[type]
+        xml.part :name => 'return', :type => TYPES2WSDL[type]
       end
     end
     @messages << message
@@ -117,6 +186,7 @@ class SimpleWS <  SOAP::RPC::StandaloneServer
 
   end
   
+
   WSDL_STUB =<<EOT
 <?xml version="1.0"?>
 <definitions xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
@@ -167,7 +237,7 @@ ${BINDINGS}
 </definitions>
 EOT
 
-  @@type2wsdl = {
+  TYPES2WSDL = {
     :boolean => 'xsd:boolean',
     :string => 'xsd:string',
     :integer => 'xsd:integer',

data/test/simplews/test_asynchronous.rb

@@ -9,7 +9,7 @@ class TestSimpleWS < Test::Unit::TestCase
     end
 
     def process(name)
-      name = start_job(name, %w(test.txt)) do
+      actual_name = start_job(name, %w(test.txt)) do
         begin
           write('test.txt', job_name)
           step(:init)
@@ -20,12 +20,11 @@ class TestSimpleWS < Test::Unit::TestCase
           sleep 2
           step(:step2, "Step3")
         rescue
-          puts $!.message
-          raise $!
+          error($!.message)
         end
       end
 
-      name
+      actual_name
     end
 
     def initialize(*args)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: simplews
 version: !ruby/object:Gem::Version 
-  version: 1.1.5
+  version: 1.1.6
 platform: ruby
 authors: 
 - Miguel Vazquez