dbalatero-relax 0.0.7.1

data/lib/relax/response.rb

@@ -0,0 +1,82 @@
+module Relax
+  # Response is intended to be a parent class for responses passed to
+  # Service#call.
+  #
+  # A response is in essence an object used to facilitate XML parsing. It
+  # stores an XML document, and provides access to it through methods like
+  # #element and #attribute.
+  class Response
+    attr_accessor :raw
+
+    # New takes in and parses the raw response.
+    #
+    # This will raise a MissingParameter error if a parameterd marked as
+    # required is not present in the parsed response.
+    def initialize(xml)
+      @raw = xml
+      @parser = Relax::Parsers::Factory.get(parser_name).new(xml.to_s, self)
+    end
+
+    def parser_name #:nodoc:
+      self.class.instance_variable_get('@parser') || :default
+    end
+
+    def node_name(name, namespace=nil) #:nodoc:
+      "#{namespace.to_s + ':' if namespace}#{name}"
+    end
+
+    def method_missing(method, *args) #:nodoc:
+      if @parser.respond_to?(method)
+        @parser.__send__(method, *args)
+      else
+        super
+      end
+    end
+
+    class << self
+      # When a Response is extended, the superclass's parameters are copied
+      # into the new class. This behavior has the following side-effect: if
+      # parameters are added to the superclass after it has been extended,
+      # those new paramters won't be passed on to its children. This shouldn't
+      # be a problem in most cases.
+      def inherited(subclass)
+        @parameters.each do |name, options|
+          subclass.parameter(name, options)
+        end if @parameters
+
+        subclass.parser(@parser) if @parser
+      end
+
+      # Specifes a parameter that will be automatically parsed when the
+      # Response is instantiated.
+      #
+      # Options:
+      # - <tt>:attribute</tt>: An attribute name to use, or <tt>true</tt> to
+      #   use the <tt>:element</tt> value as the attribute name on the root.
+      # - <tt>:collection</tt>: A class used to instantiate each item when
+      #   selecting a collection of elements.
+      # - <tt>:element</tt>: The XML element name.
+      # - <tt>:object</tt>: A class used to instantiate an element.
+      # - <tt>:type</tt>: The type of the parameter. Should be one of
+      #   <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, or <tt>:date</tt>.
+      def parameter(name, options={})
+        attr_accessor name
+        @parameters ||= {}
+        @parameters[name] = options
+      end
+
+      # Specifies the parser to use when decoding the server response. If no
+      # parser is specified for the response, then the default parser will be
+      # used.
+      #
+      # See Relax::Parsers for a list of available parsers.
+      def parser(name)
+        @parser ||= name
+      end
+
+      def ===(response)
+        response.is_a?(Class) ? response.ancestors.include?(self) : super
+      end
+    end
+  end
+end

data/lib/relax/service.rb

@@ -0,0 +1,102 @@
+require 'openssl'
+require 'net/https'
+require 'uri'
+require 'date'
+require 'base64'
+require 'erb'
+
+module Relax
+  # Service is the starting point for any REST consumer written with Relax. It
+  # is responsible for setting up the endpoint for the service, and issuing the
+  # HTTP requests for each call made.
+  #
+  # == Extending Service
+  #
+  # When writing consumers, you should start by extending Service by inheriting
+  # from it and calling its constructor with the endpoint for the service.
+  #
+  # === Example
+  #
+  #   class Service < Relax::Service
+  #     ENDPOINT = 'http://example.com/services/rest/'
+  #
+  #     def initialize
+  #       super(ENDPOINT)
+  #     end
+  #   end
+  #
+  # == Calling a Service
+  #
+  # Each call made to the service goes through the #call method of Service,
+  # which takes in a Request object and a Response class. The Request object is
+  # used to generate the query string that will be passed to the endpoint. The
+  # Reponse class is instantiated with the body of the response from the HTTP
+  # request.
+  #
+  # === Example
+  #
+  # This example show how to create a barebones call. This module can be then
+  # included into your Service class.
+  #
+  #   module Search
+  #     class SearchRequest < Relax::Request
+  #     end
+  #
+  #     class SearchResponse < Relax::Response
+  #     end
+  #
+  #     def search(options = {})
+  #       call(SearchRequest.new(options), SearchResponse)
+  #     end
+  #   end
+  #
+  class Service
+    attr_reader :endpoint
+
+    # This constructor should be called from your Service with the endpoint URL
+    # for the REST service.
+    def initialize(endpoint)
+      @endpoint = URI::parse(endpoint)
+    end
+
+    protected
+
+    # Calls the service using a query built from the Request object passed in
+    # as its first parameter. Once the response comes back from the service,
+    # the body of the response is used to instantiate the response class, and
+    # this response object is returned.
+    def call(request, response_class)
+      request.valid?
+      uri = @endpoint.clone
+      uri.query = query(request).to_s
+      response = request(uri)
+      puts "Response:\n#{response.body}\n\n" if $DEBUG
+      response_class.new(response.body)
+    end
+
+    private
+
+    def default_query
+      Query.new
+    end
+
+    def query(request)
+      Query.new(default_query.merge(request.to_query))
+    end
+
+    def request(uri)
+      puts "Request:\n#{uri.to_s}\n\n" if $DEBUG
+      http = Net::HTTP.new(uri.host, uri.port)
+
+      if uri.scheme == 'https'
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+
+      http.start do |http|
+        request = Net::HTTP::Get.new("#{uri.path}?#{uri.query}")
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/relax/symbolic_hash.rb

@@ -0,0 +1,79 @@
+module Relax
+  # SymbolicHash provides an extension of Hash, but one that only supports keys
+  # that are symbols. This has been done in an effort to prevent the case where
+  # both a string key and a symbol key are set on the same hash, and espcially
+  # for dealing with this particular case when convert the hash to a string.
+  #
+  # === Example
+  #
+  #   hash = Relax::SymbolicHash.new
+  #   hash[:one] = 1
+  #   hash['one'] = 2
+  #   puts hash[:one] # => 2
+  #
+  # === Credits
+  #
+  # Some of the inspiration (and code) for this class comes from the
+  # HashWithIndifferentAccess that ships with Rails.
+  class SymbolicHash < Hash
+    def initialize(constructor = {})
+      if constructor.is_a?(Hash)
+        super()
+        update(constructor)
+      else
+        super(constructor)
+      end
+    end
+
+    def [](key)
+      super(convert_key(key))
+    end
+
+    def []=(key, value)
+      super(convert_key(key), convert_value(value))
+    end
+
+    def update(other_hash)
+      other_hash.each_pair { |key, value| store(convert_key(key), convert_value(value)) }
+      self
+    end
+    alias :merge! :update
+
+    def fetch(key, *extras)
+      super(convert_key(key), *extras)
+    end
+
+    def values_at(*indices)
+      indices.collect { |key| self[convert_key(key)] }
+    end
+
+    def dup
+      SymbolicHash.new(self)
+    end
+
+    def merge(hash)
+      self.dup.update(hash)
+    end
+
+    def delete(key)
+      super(convert_key(key))
+    end
+
+    def key?(key)
+      super(convert_key(key))
+    end
+    alias :include? :key?
+    alias :has_key? :key?
+    alias :member? :key?
+
+    def convert_key(key)
+      !key.kind_of?(Symbol) ? key.to_sym : key
+    end
+    protected :convert_key
+
+    def convert_value(value)
+      value
+    end
+    protected :convert_value
+  end
+end

data/spec/parser_helper.rb

@@ -0,0 +1,49 @@
+describe 'a successfully parsed response', :shared => true do
+  it 'should allow access to the root' do
+    root = @response.root
+    root.should_not be_nil
+    root.name.should eql('RESTResponse')
+  end
+
+  it 'should be checkable by the name of its root' do
+    @response.is?(:RESTResponse).should be_true
+  end
+
+  it 'should allow access to an element by its name' do
+    @response.element(:RequestId).should_not be_nil
+  end
+
+  it 'should allow access to an element\'s elements by its name' do
+    tokens = @response.elements(:Tokens)
+    tokens.should respond_to(:each)
+    tokens.should_not be_empty
+  end
+
+  it 'should allow access to an element\'s value by its name' do
+    token = Relax::Response.new(@response.elements(:Tokens).first)
+    token.element(:TokenId).inner_text.should eql('JPMQARDVJK')
+    token.element(:Status).inner_text.should eql('Active')
+  end
+
+  it 'should have a means of checking for the existence of a node' do
+    @response.has?(:Status).should_not be_nil
+    @response.has?(:Errors).should be_nil
+  end
+
+  it 'should set known parameters' do
+    @response.status.should eql('Success')
+    @response.request_id.should eql(44287)
+    @response.valid_request.should eql("true")
+  end
+
+  it 'should automatically pull parameters from the XML' do
+    @response.tokens.length.should eql(2)
+    @response.tokens.first.status.should eql('Active')
+    @response.error.code.should eql(1)
+    @response.error.message.should eql('Failed')
+  end
+
+  it 'should raise MissingParameter if required parameters are missing' do
+    proc { @response.class.new('') }.should raise_error(Relax::MissingParameter)
+  end
+end

data/spec/parsers/factory_spec.rb

@@ -0,0 +1,29 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+require 'relax'
+require 'relax/parsers/factory'
+
+class TestParser ; end
+
+describe 'a parser factory' do
+  
+  before(:each) do
+    @factory = Relax::Parsers::Factory
+    Relax::Parsers::Factory.register(:test, TestParser)
+  end
+  
+  it 'should raise UnrecognizedParser for un-registered names' do
+    lambda {
+      @factory.get(:bad_name)
+    }.should raise_error(Relax::UnrecognizedParser)
+  end
+  
+  it 'should return a registered parser class' do
+    @factory.get(:test).should ==TestParser
+  end
+  
+  it 'should register the first registered parser as the default' do
+    @factory.get(:default).should ==Relax::Parsers::Hpricot
+  end
+  
+end

data/spec/parsers/hpricot_spec.rb

@@ -0,0 +1,31 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require File.dirname(__FILE__) + '/../parser_helper'
+
+class HpricotTestResponse < Relax::Response
+  class Token < Relax::Response
+    parser :hpricot
+    parameter :token_id, :element => :tokenid
+    parameter :status
+  end
+
+  class Error < Relax::Response
+    parser :hpricot
+    parameter :code, :type => :integer
+    parameter :message
+  end
+
+  parser :hpricot
+  parameter :status, :required => true
+  parameter :request_id, :element => :requestid, :type => :integer
+  parameter :valid_request, :element => :requestid, :attribute => :valid
+  parameter :tokens, :collection => Token
+  parameter :error, :type => Error
+end
+
+describe 'an Hpricot parser' do
+  before(:each) do
+    @response = HpricotTestResponse.new(XML)
+  end
+
+  it_should_behave_like 'a successfully parsed response'
+end

data/spec/parsers/rexml_spec.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require File.dirname(__FILE__) + '/../parser_helper'
+
+class RexmlTestResponse < Relax::Response
+  class Token < Relax::Response
+    parser :rexml
+    parameter :token_id, :element => 'TokenId'
+    parameter :status, :element => 'Status'
+  end
+
+  class Error < Relax::Response
+    parser :rexml
+    parameter :code, :element => 'Code', :type => :integer
+    parameter :message, :element => 'Message'
+  end
+
+  parser :rexml
+  parameter :status, :element => 'Status', :required => true
+  parameter :request_id, :element => 'RequestId', :type => :integer
+  parameter :valid_request, :element => 'RequestId', :attribute => :valid
+  parameter :namespace, :element => 'Namespace', :namespace => 'ns1'
+  parameter :tokens, :element => 'Tokens', :collection => Token
+  parameter :error, :element => 'Error', :type => Error
+end
+
+describe 'a REXML parser' do
+  before(:each) do
+    @response = RexmlTestResponse.new(XML)
+  end
+
+  it_should_behave_like 'a successfully parsed response'
+
+  it 'should parse namespaced parameters' do
+    @response.namespace.should eql('Passed')
+  end
+end

data/spec/query_spec.rb

@@ -0,0 +1,60 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+require 'relax/query'
+
+describe 'a query' do
+  before(:each) do
+    @uri = URI::parse('http://example.com/?action=search&query=keyword')
+    @query = Relax::Query.new
+  end
+
+  it 'should convert to a query string' do
+    @query[:action] = 'Search'
+    @query[:query] = 'strings'
+    @query.to_s.should eql('action=Search&query=strings')
+  end
+
+  it 'should convert its values to strings' do
+    date = Date.today
+    @query[:date] = date
+    @query.to_s.should eql("date=#{date.to_s}")
+  end
+
+  it 'should escape its values using "+" instead of "%20"' do
+    Relax::Query.send(:escape_value, 'two words').should == 'two+words'
+  end
+  
+  it 'should sort its parameters' do
+    @query[:charlie] = 3
+    @query[:alpha] = 1
+    @query[:bravo] = 2
+    @query.to_s.should eql('alpha=1&bravo=2&charlie=3')
+  end
+
+  it 'should encode its parameter values' do
+    @query[:spaces] = 'two words'
+    @query[:url] = 'http://example.com/'
+    @query.to_s.should eql('spaces=two+words&url=http%3A%2F%2Fexample.com%2F')
+  end
+
+  it 'should be able to parse query strings' do
+    parsed_query = Relax::Query.parse(@uri)
+    parsed_query[:action].should eql('search')
+    parsed_query[:query].should eql('keyword')
+  end
+  
+  it 'should parse key value pairs into only two parts' do
+    parsed_query = Relax::Query.parse(URI.parse("http://example.com/?action=test=&foo=bar"))
+    parsed_query[:action].should eql('test=')
+  end
+  
+  it 'should unescape query string key-value pair keys' do
+    parsed_query = Relax::Query.parse(URI.parse("http://example.com/?action%20helper=test"))
+    parsed_query[:"action helper"].should eql('test')
+  end
+  
+  it 'should unescape query string key-value pair values' do
+    parsed_query = Relax::Query.parse(URI.parse("http://example.com/?action=test%20action"))
+    parsed_query[:action].should eql('test action')
+  end
+end