madcowley-jambase4r 1.1.3

data/README

@@ -0,0 +1,124 @@
+JamBase4R
+=============
+
+JamBase4R is a framework agnostic Ruby wrapper around the JamBase live music search API.
+(http://developer.jambase.com/docs)
+
+This gem can be used to create mashups where your users might want to search for live music. This gem is a
+replacement for a Ruby on Rails plugin that I wrote a while back called JamBase4Rails. Since Rails is no longer
+promoting the use of traditional plugins, but rather gems, I thought it was time to do a re-write.
+
+**Note: JamBase requires that any site making use of it's API provide attribution.
+See http://developer.jambase.com/docs for more information. This gem provides 
+helpers to make adding attribution to your site easy.
+
+This gem adds helper methods to your views (if you are using Rails), but does not alter controllers or
+models in any way.
+
+This is a forked version from Matt Payne's original, to include new start/end date parameters allowed in the jambase api.
+
+Installation
+============
+
+1) get and install the gem
+   sudo gem install madcowley-jambase4r
+	- OR -
+	If using Rails:
+	a) Add config.gem 'madcowley-jambase4r', :lib => "jambase4r"
+	   to your environment.rb file.
+	b) rake gems:install from your project root
+
+Configuration
+=============
+
+Using the JamBase API requires that you register for an API key. Get one here:
+http://developer.jambase.com/member/register
+
+JamBase4R is configured via the configure method. The configure method takes a block that is 
+passed a settings object. 2 properties can be set: 1) api_key (required) 2) logger (optional)
+
+FOR RAILS
+=========
+In an initializer, add the following configuration:
+
+#app_specific_initializers.rb
+
+JamBase4R.configure do |config|
+  config.api_key = "XXXXXXXXXXXXX"
+  config.logger = RAILS_DEFAULT_LOGGER - This is optional if you want to enable logging. You can pass an instance of
+	any class that conforms to the same interface as RAILS_DEFAULT_LOGGER (Specifically, it must respond to #info(msg) and #error(msg))
+end
+
+FOR SINATRA
+===========
+
+I would typically configure JamBase4R with a Sinatra configure block.
+
+configure do
+	JamBase4R.configure do |config|
+	  config.api_key = "XXXXXXXXXXXXX"
+	end
+end
+
+FOR OTHERS
+==========
+
+Check the documentation of the framework you are using. All should allow for this type of configuration.
+
+ATTRIBUTION
+===========
+JamBase requires that you indicate where your data comes from (attribution). To make this easy, there is a JamBase4R::ViewHelper module that gets automatically included into ActionView::Base if using Rails and into Sinatra's helpers if using Sinatra.
+
+There are a couple of methods:
+1) jambase_text_attribution
+2) jambase_image_attribution
+3) jambase_flavicon
+
+Example
+=======
+
+To make use of JamBase4R just use the JamBase4R::API object.
+
+Available methods (all are class methods):
+
+All methods return an instance of an Array, which contains zero or more Event objects
+
+1) JamBase4R::API.search(options)
+2) JamBase4R::API.search_by_artist(artist_name, additional_options={})
+3) JamBase4R::API.search_by_zipcode(zipcode, additional_options={})
+4) JamBase4R::API.search_by_user(user, additional_options={})
+
+Possible options:
+
+:band (or :artist (an alias for :band)) => The name of the band to search for.
+:zip => The zipcode to search within
+:radius => The distance from the zipcode to include in the search
+:user => The registered user - this limits the results to those within the user's favorite artists
+:startdate => return results on or after this date
+:enddate => return results before this date
+
+ie: JamBase4R::API.search(:band => "A Band", :zip => "90210", :radius => 20)
+    JamBase4R::API.search_by_artist("A Band", {:zip => "90210"})
+    JamBase4R::API.search_by_zipcode("90210")
+    JamBase4R::API.search_by_user("Matt")
+
+The general schema of the results is:
+
+ - events
+ 	- event
+        - event_id (String)
+        - event_date (String)
+        - event_url (String)
+		- ticket_url (String)
+        - venue (Venue)
+            - venue_id (String)
+            - venue_name (String)
+            - venue_city (String)
+            - venue_state (String)
+            - venue_zip (String)
+        - artists (Artists)
+            - Artist(s) (Artist)
+                - artist_id
+                - artist_name
+
+Copyright (c) 2009 [Matt Payne], released under the MIT license

data/jambase4r.gemspec

@@ -0,0 +1,22 @@
+#The GemSpec to build the gem
+Gem::Specification.new do |s|
+  s.name = 'madcowley-jambase4r'
+  s.version = '1.1.3'
+  s.date = "2010-06-30"
+  s.summary = "Ruby JamBase API library."
+  s.description = %{A Ruby library use to access the JamBase API. Forked from Matt Payne's original.}
+  s.has_rdoc = false
+  s.authors = ["Matt Payne", "Matt Cowley"]
+  s.email = ["matt@mattpayne.ca", "madcowley@gmail.com"]  
+  s.homepage = "http://github.com/madcowley/jambase4r"
+  s.files = [
+    'README', 'jambase4r.gemspec', 'lib/jambase4r.rb', 'lib/utility.rb', 'lib/api.rb', 
+    'lib/extensions.rb', 'lib/http_gateway.rb', 'lib/jambase4r_view_helper.rb', 'lib/models/model.rb', 
+    'lib/models/artist.rb', 'lib/models/venue.rb', 'lib/models/event.rb'
+  ]
+  s.test_files = [
+    'spec/spec_helper.rb', 'spec/lib/api_spec.rb', 'spec/lib/http_gateway_spec.rb',
+    'spec/lib/jambase4r_spec.rb', 'spec/lib/models/artist_spec.rb',
+    'spec/lib/models/event_spec.rb', 'spec/lib/models/venue_spec.rb', "spec/lib/models/model_spec.rb"
+  ]
+end

data/lib/api.rb

@@ -0,0 +1,111 @@
+require "rexml/document"
+
+module JamBase4R
+  class API
+    class << self
+      include Utility
+      
+      API_URL = "http://api.jambase.com/search".freeze
+      JAMBASE_PARAMETERS = [:zip, :radius, :band, :user, :startdate, :enddate].freeze
+      PARAMETER_ALIAS_MAP = {:artist => :band}.freeze
+      
+      #Search Options:
+      #:artist = The name of an artist
+      #:band = alias for artist
+      #:zip = The zipcode to search
+      #:radius = The distance around the zipcode to search
+      #These can be combined, although I doubt that :artist combined with :radius
+      #would do anything useful ;)
+      def search(search_options={})
+        result = jambase_search(search_options)
+        return convert(result.body) unless result.blank?
+      end
+    
+      #Additional Filters - As above, but without :artist/band
+      def search_by_artist(artist_name, additional_filters={})
+        additional_filters[:artist] = artist_name
+        return search(additional_filters)
+      end
+    
+      #Additional Filters - As above, but without :zip
+      def search_by_zipcode(zipcode, additional_filters={})
+        additional_filters[:zip] = zipcode
+        return search(additional_filters)
+      end
+      
+      #Additional filters - As above, but without :user
+      def search_by_user(user, additional_filters={})
+        additional_filters[:user] = user
+        return search(additional_filters)
+      end
+    
+      protected
+    
+      def jambase_search(search_args)
+        check_api_key
+        return if search_args.blank?
+        search_args = search_args.symbolize_keys
+        replace_aliased_keys!(search_args)
+        remove_unnecessary_params!(search_args)
+        return if search_args.blank?
+        query = create_query_string(search_args)
+        log_info("Calling JamBase with the requested search: #{query}")
+        return jambase_gateway.get(query)
+      end
+
+      def check_api_key
+        if JamBase4R.api_key.blank?
+          log_error("No API key has been set for JamBase. Please set it before attempting to use the service.")
+          raise ArgumentError.new("No JamBase API key configured. Please configure JamBase4R before using.")
+        end
+      end
+    
+      def replace_aliased_keys!(options)
+        PARAMETER_ALIAS_MAP.each do |alias_param, real_param|
+          if options.key?(alias_param)
+            check_for_alias_and_real_param!(options, alias_param, real_param)
+            value = options[alias_param]
+            options[real_param] = value
+          end
+        end
+      end
+    
+      def check_for_alias_and_real_param!(options, alias_param, real_param)
+        unless options[real_param].blank?
+          log_error("Cannot have both #{alias_param} and #{real_param} in search.")
+          raise ArgumentError.new("Cannot have both #{alias_param} and #{real_param}.")
+        end
+      end
+    
+      def remove_unnecessary_params!(options)
+        options.reject! do |key, value|
+          !JAMBASE_PARAMETERS.include?(key) ||
+            value.blank?
+        end
+      end
+  
+      def create_query_string(search_args)
+        "#{API_URL}?#{search_args.to_param}&apikey=#{JamBase4R.api_key}"
+      end
+  
+      def jambase_gateway
+        @@gateway ||= JamBase4R::HttpGateway.new
+      end
+    
+      def convert(xml)
+        begin
+          results = []
+          return results if xml.blank?
+          doc = REXML::Document.new(xml)
+          doc.elements.each("//event") do |event|
+            results << Event.new(event)
+          end
+        rescue Exception => e
+          log_error(e.message)
+        end
+        results
+      end
+      
+    end
+  end
+end

data/lib/extensions.rb

@@ -0,0 +1,44 @@
+require 'rubygems' unless defined? RubyGems
+require 'uri' unless defined? URI
+
+#Hack URI::HTTP to include a method that gets us both the path and the querystring
+#since path_query is private
+module URI
+  class HTTP < Generic
+    def path_with_querystring
+      path_query
+    end
+  end
+end
+
+unless defined?(ActiveSupport)
+  class Object
+    def blank?
+      respond_to?(:empty?) ? empty? : !self
+    end
+    
+    def to_param
+      to_s
+    end
+    
+    def to_query(key)
+      require 'cgi' unless defined?(CGI) && defined?(CGI::escape)
+      "#{CGI.escape(key.to_s)}=#{CGI.escape(to_param.to_s)}"
+    end
+  end
+  
+  class Hash
+    def symbolize_keys
+      inject({}) do |options, (key, value)|
+        options[(key.to_sym rescue key) || key] = value
+        options
+      end
+    end
+    
+    def to_param(namespace=nil)
+      collect do |key, value|
+        value.to_query(namespace ? "#{namespace}[#{key}]" : key)
+      end.sort * '&'
+    end
+  end
+end

data/lib/http_gateway.rb

@@ -0,0 +1,43 @@
+require 'net/http'
+
+module JamBase4R
+  
+  class JamBaseError < StandardError
+    
+    attr_reader :message, :response_code
+    
+    def initialize(message, response_code=nil)
+      @message = message
+      @response_code = response_code
+    end
+    
+  end
+  
+  class HttpGateway
+    include Utility
+    
+    def get(url)
+      log_info("#{self.class.name} - Performing GET with URL: #{url}.")
+      url = URI.parse(url)
+      request = Net::HTTP::Get.new(url.path_with_querystring)
+      response = Net::HTTP.start(url.host, url.port) { |http| http.request(request) }
+      handle_response(response)
+    rescue Timeout::Error => e
+      log_error("Connection to JamBase timed out: #{e.message}")
+      raise JamBaseError.new(e.message)
+    end
+    
+    private
+    
+    def handle_response(response)
+      case response.code.to_i
+      when 200...400
+        response
+      else
+        log_error("Unexpect response occurred. Code: #{response.code}, Message: #{response.body}")
+        raise(JamBaseError.new(response.body, response.code))
+      end
+    end    
+  end
+  
+end

data/lib/jambase4r.rb

@@ -0,0 +1,51 @@
+local_path = File.dirname(__FILE__)
+
+[ 'extensions',
+  'utility',
+  'http_gateway',
+  'jambase4r_view_helper',
+  'models/model',
+  'models/artist',
+  'models/venue',
+  'models/event',
+  'api'].each { |file| require File.join(local_path, file) }
+  
+
+module JamBase4R
+  extend Utility
+  
+  @@api_key = nil
+  @@logger = nil
+  
+  def self.api_key
+    @@api_key
+  end
+  
+  def self.api_key=(key)
+    @@api_key = key
+  end
+  
+  def self.logger
+    @@logger
+  end
+  
+  def self.logger=(logger)
+    @@logger = logger
+  end
+  
+  def self.configure(&block)
+    raise ArgumentError.new("A block is expected.") unless block_given?
+    block.call(self)
+    log_error("You must supply an API key.") if api_key.blank?
+    raise ArgumentError.new("You must supply an api key.") if api_key.blank?
+    if defined? ActionView
+      ActionView::Base.send(:include, JamBase4R::ViewHelper)
+    end
+    if defined? Sinatra
+      helpers do
+        include JamBase4R::ViewHelper
+      end
+    end
+  end
+  
+end

data/lib/jambase4r_view_helper.rb

@@ -0,0 +1,24 @@
+module JamBase4R
+  
+  module ViewHelper
+    
+    def jambase_text_attribution
+      %{**Concert information provided by <a href="http://www.jambase.com">JamBase</a>**}
+    end
+    
+    def jambase_image_attribution
+      %{<a href="http://www.JamBase.com" target="_top" title="JamBase Concert Search">
+          <img src= "http://images.jambase.com/logos/jambase140x70.gif" alt="Search JamBase Concerts" border="0" />
+        </a>}
+    end
+    
+    def jambase_favicon
+      %{<a href="http://www.JamBase.com" target="_top" title="JamBase Concert Search">
+          <img src= "http://www.jambase.com/favicon.ico" alt="Search JamBase Concerts" border="0" />
+        </a>
+      }
+    end
+    
+  end
+  
+end

data/lib/models/artist.rb

@@ -0,0 +1,20 @@
+module JamBase4R
+  class Artist
+    include Model
+    
+    attr_reader :id, :name
+    
+    def initialize(element)
+      return if element.blank?
+      build(element)
+    end
+    
+    private
+    
+    def build(element)
+      @id = get_value(element, ARTIST_ID)
+      @name = get_value(element, ARTIST_NAME)
+    end
+    
+  end
+end