qrpc 0.1.1 → 0.2.0

data/lib/qrpc/client/job.rb

@@ -0,0 +1,150 @@
+# encoding: utf-8
+require "uuid"
+require "qrpc/protocol/request"
+require "qrpc/client/exception"
+require "qrpc/general"
+
+##
+# General QRPC module.
+#
+
+module QRPC
+    
+    ##
+    # Queue RPC client.
+    #
+    
+    class Client
+    
+        ##
+        # Queue RPC client job.
+        # @since 0.2.0
+        #
+        
+        class Job
+
+            ##
+            # Holds job ID.
+            #
+            
+            @id
+            
+            ##
+            # Holds associated client ID.
+            #
+            
+            @client_id
+            
+            ##
+            # Holds method name of the job.
+            #
+            
+            @job
+            
+            ##
+            # Holds method arguments array.
+            #
+            
+            @arguments
+            
+            ##
+            # Holds job callback.
+            #
+            
+            @callback
+            
+            ##
+            # Message priority.
+            #
+            
+            @priority
+            
+            ##
+            # Job result.
+            #
+            
+            @result
+        
+            ##
+            # Constructor.
+            #
+            # @param [Symbol] client_id  client (session) ID
+            # @param [Symbol] method  job method name
+            # @param [Array] arguments  array of arguments for job
+            # @param [Integer] priority  job priority
+            # @param [Proc] callback  result callback
+            #
+            
+            def initialize(client_id, method, arguments = [ ], priority = QRPC::DEFAULT_PRIORITY, &callback)
+                @client_id = client_id
+                @method = method
+                @arguments = arguments
+                @callback = callback
+                @priority = priority
+            end
+            
+            ##
+            # Returns job ID.
+            # @return [Symbol] job ID
+            #
+            
+            def id
+                if @id.nil?
+                    @id = UUID.generate.to_sym
+                end
+                
+                return @id
+            end
+            
+            ##
+            # Converts job to JSON.
+            # @return [String] job in JSON form (JSON-RPC)
+            #
+            
+            def to_json
+                QRPC::Protocol::Request::create(@client_id, @id, @method, @arguments, @priority).to_json
+            end
+            
+            ##
+            # Indicates message is notification. So callback isn't set
+            # and it doesn't expect any result.
+            #
+            # @return [Boolean] +true+ if it's, +false+ in otherwise
+            #
+            
+            def notification?
+                @callback.nil?
+            end
+            
+            ##
+            # Assigns job result and subsequently calls callback.
+            # @param [JsonRpcObjects::Generic::Response] result of the call
+            #
+            
+            def assign_result(result)
+                if not result.error?
+                    @result = result.result
+                else
+=begin
+                    STDERR.write(">>> Exception while call ID: " << self.id.to_s << "\n")
+=end                    
+                    exception = QRPC::Client::Exception::get(result.error)
+=begin
+                    STDERR.write exception.class.name.dup << ": " << exception.message << "\n"
+                    
+                    exception.backtrace.each do |i|
+                        STDERR.write "	from " << i << "\n"
+                    end
+=end                    
+                    raise exception
+                end
+                
+                if not @callback.nil?
+                    @callback.call(@result)
+                end
+            end
+            
+        end
+                
+    end
+end

data/lib/qrpc/general.rb

@@ -8,20 +8,30 @@ module QRPC
 
     ##
     # Prefix for handled queues.
+    # @since 0.1.1
     #
     
     QUEUE_PREFIX = "qrpc"
     
     ##
     # Input queue postfix.
+    # @since 0.1.1
     #
     
     QUEUE_POSTFIX_INPUT = "input"
     
     ##
     # Output queue postfix.
+    # @since 0.1.1
     #
     
     QUEUE_POSTFIX_OUTPUT = "output"
+    
+    ##
+    # Indicates default job priority.
+    # @since 0.2.0
+    #
+    
+    DEFAULT_PRIORITY = 50
 
 end

data/lib/qrpc/locator.rb

@@ -15,24 +15,27 @@ module QRPC
     
         ##
         # Contains queue name.
+        # @return [Symbol]
         #
-        
-        @queue
+
         attr_accessor :queue
+        @queue
         
         ##
         # Contains host.
+        # @return [String]
         #
-        
-        @host
+
         attr_accessor :host
+        @host
         
         ##
         # Contains port.
+        # @return [Integer]
         #
-        
-        @port
+
         attr_accessor :port
+        @port
         
         ##
         # Parser.

data/lib/qrpc/protocol/exception-data.rb

@@ -0,0 +1,227 @@
+# encoding: utf-8
+require "json-rpc-objects/generic/object"
+require "qrpc/protocol/qrpc-object"
+require "base64"
+
+##
+# General QRPC module.
+#
+
+module QRPC
+    
+    ##
+    # JSON RPC helper module.
+    # @since 0.2.0
+    #
+
+    module Protocol
+
+        ##
+        # Exception data QRPC JSON-RPC object.
+        # @since 0.2.0
+        #
+        
+        class ExceptionData < JsonRpcObjects::Generic::Object
+        
+            ##
+            # Holds JSON-RPC version indication.
+            #
+            
+            VERSION = QRPC::Protocol::QrpcObject::VERSION
+            
+            ##
+            # Holds exception name.
+            # @return [Symbol]
+            #
+            
+            attr_accessor :name
+            @name
+            
+            ##
+            # Holds exception message.
+            # @return [String]
+            #
+            
+            attr_accessor :message
+            @message
+            
+            ##
+            # Holds backtrace. See readme for structure details.
+            # @return [Array]
+            #
+            
+            attr_accessor :backtrace
+            @backtrace
+            
+            ##
+            # Holds native dump. See readme for structure details.
+            # @return [Class]
+            #
+            
+            attr_accessor :dump
+            @dump
+            
+            ##
+            # Indicates, data are encoded and should be decoded.
+            #
+            
+            @__encoded
+            
+            ##
+            # Creates new QRPC JSON-RPC object.
+            #
+            # @overload create(exception, nil, opts = { })
+            #   Creates from exception.
+            #   @param [Exception] exception exception object
+            #   @param [NilClass] nil (not applicable)
+            #   @param [Hash] opts optional members of object
+            # @overload create(name, message, opts = { })
+            #   Creates from exception description.
+            #   @param [Symbol, String] name exception name
+            #   @param [Object] exception message
+            #   @param [Hash] opts optional members of object
+            # @return [QRPC::Protocol::ExceptionData]  new instance
+            #
+            
+            def self.create(arg1, message = nil, opts = { })
+                if arg1.kind_of? ::Exception
+                    mode = :decoded
+                    data = {
+                        :name => arg1.class.name,
+                        :message => arg1.message,
+                        :backtrace => arg1.backtrace,
+                        :dump => {
+                            "format" => "ruby",
+                            "object" => arg1
+                        }
+                    }
+                else
+                    mode = :encoded
+                    data = {
+                        :name => arg1,
+                        :message => message
+                    }
+                end
+                
+                data.merge! opts
+                return self::new(data, mode)
+            end
+            
+            ##
+            # Constructor.
+            # @param [Hash] data for initializing the object
+            #
+            
+            def initialize(data, mode = :encoded)
+                @__encoded = (mode == :encoded)
+                super(data)
+            end
+            
+            ##
+            # Checks correctness of the object data.
+            #
+            
+            def check!
+                self.normalize!
+
+                if not @name.kind_of? Symbol
+                    raise Exception::new("Exception name is expected to be Symbol or convertable to symbol.")
+                end
+                
+                if not @backtrace.nil? and not @backtrace.kind_of? Array
+                    raise Exception::new("Backtrace is expected to be an Array.")
+                end
+                
+                if not @dump.nil? 
+                    if @dump.object.nil? and @dump.raw.nil?
+                        raise Exception::new("Either object or RAW form of the dump must be set if dump is set.")
+                    elsif @dump.format.nil? or not @dump.format.kind_of? Symbol
+                        raise Exception::new("Dump format must be set and must be Symbol.")
+                    end
+                end
+            end
+                        
+            ##
+            # Renders data to output form.
+            # @return [Hash] with data of object
+            #
+
+            def output
+                result = { 
+                    :name => @name.to_s,
+                    :message => @message,
+                }
+                
+                # Backtrace
+                if @backtrace.kind_of? Array
+                    result[:backtrace] = @backtrace.map { |i| Base64.encode64(i) }
+                end
+                   
+                # Dump
+                if not @dump.nil?
+                    result[:dump] = {
+                        :format => @dump.format,
+                    }
+                    
+                    if not dump.object.nil?
+                        raw = Base64.encode64(Marshal.dump(dump.object))
+                    else
+                        raw = dump.raw
+                    end
+                    
+                    result[:dump][:raw] = raw
+                end
+                
+                return result
+            end
+       
+
+            protected
+            
+            ##
+            # Assigns data.
+            #
+
+            def data=(value, mode = nil)
+                data = __convert_data(value, mode)
+                
+                # Required
+                @name = data[:name]
+                @message = data[:message]
+                
+                # Backtrace
+                backtrace = data[:backtrace]
+                
+                if @__encoded and (backtrace.kind_of? Array)
+                    @backtrace = backtrace.map { |i| Base64.decode64(i) }
+                end
+                
+                # Dump
+                dump = data[:dump]
+                   
+                if dump.kind_of? Hash
+                    @dump = Struct::new(:format, :raw, :object)::new(dump["format"].downcase.to_sym, dump["raw"], dump["object"])
+                    
+                    if not @dump.raw.nil? and @dump.object.nil? and (@dump.format == :ruby)
+                        @dump.object = Marshal.load(Base64.decode64(@dump.raw))
+                    end
+                end
+                
+            end
+
+            ##
+            # Converts data to standard (defined) format.
+            #
+            
+            def normalize!
+                @name = @name.to_sym
+                
+                if not @dump.nil?
+                    @dump.format = @dump.format.to_sym
+                end
+            end
+            
+        end
+                
+    end
+end

data/lib/qrpc/protocol/qrpc-object.rb

@@ -0,0 +1,103 @@
+# encoding: utf-8   
+require "json-rpc-objects/generic/object"
+require "json-rpc-objects/request"
+
+##
+# General QRPC module.
+#
+
+module QRPC
+    
+    ##
+    # JSON RPC helper module.
+    # @since 0.2.0
+    #
+
+    module Protocol
+
+        ##
+        # QRPC JSON-RPC QRPC object. Extends the 
+        # +JsonRpcObjects::Generic::Object+. See its documentation for
+        # additional methods.
+        #
+        # @since 0.2.0
+        #
+        
+        class QrpcObject < JsonRpcObjects::Generic::Object
+        
+            ##
+            # Holds JSON-RPC version indication.
+            #
+            
+            VERSION = JsonRpcObjects::Request::VERSION
+            
+            ##
+            # Creates new QRPC JSON-RPC object.
+            #
+            # @param [Hash] QRPC object optional arguments
+            # @return [QRPC::Protocol::QrpcObject] new instance
+            #
+            
+            def self.create(opts = { })
+                self::new(opts)
+            end
+            
+            ##
+            # Checks correctness of the object data.
+            #
+            
+            def check!
+                self.normalize!
+                
+                if (not @priority.nil?) and not (@priority.kind_of? Numeric)
+                    raise Exception::new("Priority is expected to be Numeric.")
+                end
+            end
+                        
+            ##
+            # Renders data to output form.
+            # @return [Hash] with data of object
+            #
+
+            def output
+                result = { :version => :"1.0.1" }
+                
+                if not @priority.nil?
+                    result[:priority] = @priority
+                end
+                
+                if not @client.nil?
+                    result[:client] = @client
+                end
+                
+                return result
+            end
+       
+
+            protected
+            
+            ##
+            # Assigns data.
+            #
+
+            def data=(value, mode = nil)
+                data = __convert_data(value, mode)
+                
+                @priority = data[:priority]
+                @client = data[:client]
+            end
+
+            ##
+            # Converts data to standard (defined) format.
+            #
+            
+            def normalize!
+                if not @priority.nil?
+                    @priority = @priority.to_i
+                end
+            end
+            
+        end
+                
+    end
+end