ad_gear_client 0.3.8

data/lib/ad_gear/base.rb

@@ -0,0 +1,169 @@
+module AdGear
+  class Base < ActiveResource::Base
+    def initialize(params={})
+      super({})
+      params.each do |key, value|
+        send("#{key}=", value)
+      end
+    end
+
+    # Declares a relationship where we store the ID, but accept and/or return the full object.
+    #
+    # @example
+    #   class AdGear::AdSpot < AdGear::Base
+    #     belongs_to :format
+    #     belongs_to :bookable, :polymorphic => true
+    #     belongs_to :web_campaign, :as => :campaign
+    #   end
+    #
+    #   include AdGear
+    #   AdSpot.new(:format => Format.find(1), :bookable => Publisher.find(2), :web_campaign => WebCampaign.find(3)).attributes
+    #     #=> {"format_id" => 1, "bookable_id" => 2, "bookable_type" => "Publisher", "campaign_id" => 3}
+    def self.belongs_to(*attributes)
+      options = attributes.extract_options!
+      attributes.each do |attribute|
+        attribute_name = attribute.to_s
+        belongs_to_associations[attribute_name] = options.reverse_merge(:as => attribute_name)
+
+        if options[:polymorphic] then
+          polymorphic_belongs_to_attribute_writer_for(attribute_name)
+          polymorphic_belongs_to_attribute_reader_for(attribute_name)
+        else
+          belongs_to_attribute_writer_for(attribute_name)
+          belongs_to_attribute_reader_for(attribute_name)
+        end
+      end
+    end
+
+    def self.belongs_to_associations #:nodoc:
+      @belongs_to_associations ||= {}
+    end
+
+    # Defines a managed sub-collection.  Elements managed through a #has_many are
+    # ready for use by AttributeFu or ActiveRecord's 2.3 nested_attributes.
+    #
+    # @example
+    #   class AdGear::AdUnit < AdGear::Base
+    #     has_many :ad_unit_files, :ad_unit_clicks
+    #     has_many :ad_unit_interactions, :ad_unit_variables
+    #   end
+    #
+    #   AdGear::AdUnit.new(:ad_unit_files => [AdUnitFile.new(...)]).to_xml
+    #   <ad-unit>
+    #     <ad-unit-file-attributes>
+    #       <new>
+    #         <n0>
+    #           ...
+    #         </n0>
+    #       </new>
+    #       <!-- If there were "old" records, they'd be here
+    #     </ad-unit-file-attributes>
+    #   </ad-unit>
+    def self.has_many(*collections)
+      collections.flatten.compact.each do |collection|
+        collection_name = collection.to_s
+
+        # Remember what collections we are managing, for use in #to_xml
+        has_many_collections << collection_name
+
+        # Define a getter for the collection that transforms a plain Array into
+        # a HasManyArray which knows about new and old records
+        define_method(collection_name) do
+          arr = @attributes[collection_name]
+          return arr if arr.kind_of?(AdGear::HasManyArray)
+          @attributes[collection_name] = AdGear::HasManyArray.new(collection_name.to_sym, AdGear.const_get(collection_name.classify), arr)
+        end
+
+        define_method("#{collection_name}=") do |arr|
+          @attributes[collection_name] = if arr.kind_of?(AdGear::HasManyArray) then
+                                           arr
+                                         else
+                                           AdGear::HasManyArray.new(collection_name.to_sym, AdGear.const_get(collection_name.classify), arr)
+                                         end
+        end
+      end
+    end
+
+    def self.has_many_collections #:nodoc:
+      @has_many_collections ||= []
+    end
+
+    # Defines a list of attributes that should be ignored and not sent back to the server.
+    #
+    # @example
+    #   class AdGear::Site < AdGear::Base
+    #     ignorable_attributes :embed_code
+    #   end
+    #
+    #   AdGear::Site.find(13).to_xml
+    #   <site>
+    #     ...
+    #     <!-- no embed-code element -->
+    #   </site>
+    def self.ignorable_attributes(*attributes)
+      @ignorable_attributes ||= []
+      @ignorable_attributes += attributes.flatten.compact.map {|name| name.to_s}
+      @ignorable_attributes
+    end
+
+    def to_xml(options={})
+      self.class.has_many_collections.each do |name|
+        send(name) # convert the @attributes value into a HasManyArray
+      end
+
+      hash = if self.class.ignorable_attributes.empty?
+               @attributes
+             else
+               returning(@attributes.dup) do |hash|
+                 self.class.ignorable_attributes.each do |attr_name|
+                   hash.delete(attr_name)
+                 end
+               end
+             end
+      hash.to_xml({:root => self.class.element_name}.merge(options))
+    end
+
+    # Delegates to #to_xml, as this is the simplest thing that could possibly work
+    def encode(options={}) #:nodoc:
+      self.to_xml
+    end
+
+    private
+
+    def self.polymorphic_belongs_to_attribute_writer_for(attribute_name) #:nodoc:
+      define_method("#{attribute_name}=") do |value|
+        @attributes[self.class.belongs_to_attribute_name_for_id(attribute_name)]    = value ? value.id : nil
+        @attributes[self.class.belongs_to_attribute_name_for_class(attribute_name)] = value ? value.class.name.demodulize : nil
+      end
+    end
+
+    def self.polymorphic_belongs_to_attribute_reader_for(attribute_name) #:nodoc:
+      define_method(attribute_name) do
+        klass = @attributes[self.class.belongs_to_attribute_name_for_class(attribute_name)]
+        id    = @attributes[self.class.belongs_to_attribute_name_for_id(attribute_name)]
+        id.blank? ? nil : AdGear.const_get(AdGear.const_get(klass)).find(id)
+      end
+    end
+
+    def self.belongs_to_attribute_writer_for(attribute_name) #:nodoc:
+      define_method("#{attribute_name}=") do |value|
+        @attributes[self.class.belongs_to_attribute_name_for_id(attribute_name)] = value ? value.id : nil
+      end
+    end
+
+    def self.belongs_to_attribute_reader_for(attribute_name) #:nodoc:
+      define_method(attribute_name) do
+        id = @attributes[self.class.belongs_to_attribute_name_for_id(attribute_name)]
+        id.blank? ? nil : AdGear.const_get(attribute_name.classify).find(id)
+      end
+    end
+
+    def self.belongs_to_attribute_name_for_class(association_name)
+      "%s_type" % belongs_to_associations[association_name][:as]
+    end
+
+    def self.belongs_to_attribute_name_for_id(association_name)
+      "%s_id" % belongs_to_associations[association_name][:as]
+    end
+  end
+end

data/lib/ad_gear/click.rb

@@ -0,0 +1,4 @@
+module AdGear
+  class Click < AdGear::Base
+  end
+end

data/lib/ad_gear/config.rb

@@ -0,0 +1,143 @@
+require "erb"
+require "pathname"
+
+module AdGear
+  class Config
+    # Raised when the specified environment could not be found in the YAML configuration file.
+    class MissingEnvironmentSpecification < RuntimeError; end
+
+    # Reads in a YAML file containing configuration parameters for the AdGear::Client.  The file
+    # can contain sections relating to the environment the client is running within.
+    #
+    # The YAML configuration file *must* use strings as keys.
+    #
+    # @example A sample YAML configuration file:
+    #   development:
+    #     site:     http://localhost:3000/api
+    #     user:     dummy
+    #     password: whatever
+    #     logger:   <%= Rails.root %>/path/to/log/file.log
+    #   production:
+    #     site:     http://admin.adgear.com/api
+    #     user:     your_real_login
+    #     password: your_real_digest_password
+    #     logger:   /var/log/ad_gear.log
+    #
+    # @example Reading this sample file:
+    #   AdGear.config = AdGear::Config.new("path/to/config/file", "development")
+    #
+    # @example Reading from +config/initializers/ad_gear.rb+ in a Rails environment
+    #   AdGear.config = AdGear::Config.new(Rails.root + "config/ad_gear.yml", Rails.env)
+    #
+    # @param obj [#read, Hash, String] When the object responds to #read, reads in the IO-like
+    #                                  object and parses it as a YAML stream.  If the object is a
+    #                                  Hash, use it as-is. Else, treat the object as the path to a
+    #                                  YAML file containing the configuration.
+    # @param environment [String, Symbol, nil] If this is +nil+, then do no environment unpacking, else
+    #                                          find the environment that matches this string.  If none
+    #                                          matches, a MissingEnvironmentSpecification exception will
+    #                                          be raised.
+    #
+    # @raise MissingEnvironmentSpecification When the +environment+ parameter specifies a missing environment declaration.
+    def initialize(obj={}, environment=nil)
+      @config = Hash.new
+      @logger = nil
+
+      config = if obj.kind_of?(Hash) then
+                 obj
+               elsif obj.respond_to?(:read) then
+                 YAML.load(ERB.new(obj.read).result)
+               else
+                 YAML.load(ERB.new(IO.read(obj)).result)
+               end
+      if environment then
+        raise MissingEnvironmentSpecification, "Could not find #{environment.to_s.inspect} in #{config.inspect} read from #{obj.inspect}.  Add the missing environment declaration, or change the parameter to this method." unless config.respond_to?(:has_key?) && config.has_key?(environment.to_s)
+        config = config[environment.to_s]
+      end
+
+      config.each_pair do |key, value|
+        send("#{key}=", value)
+      end
+    end
+
+    # Returns a Hash of the currect configuration.
+    def to_hash
+      @config.dup
+    end
+
+    def site=(value)
+      @config["site"] = value
+    end
+
+    # Returns the configured site, which is the root of the API.
+    def site
+      @config["site"]
+    end
+
+    def user=(value)
+      @config["user"] = value
+    end
+
+    # Returns the configured username / login.
+    def user
+      @config["user"]
+    end
+
+    def password=(value)
+      @config["password"] = value
+    end
+
+    # Returns the configured password.
+    def password
+      @config["password"]
+    end
+
+    # Denies or allows using Basic authentication method.  This will have an effect only if you are using http://github.com/francois/rails/ar_basic/activeresource
+    def use_basic_authentication
+      @config["use_basic_authentication"]
+    end
+
+    def use_basic_authentication=(value)
+      @config["use_basic_authentication"] = value
+    end
+
+    # Denies or allows using Digest authentication method.  This will have an effect only if you are using http://github.com/francois/rails/ar_digest/activeresource
+    def use_digest_authentication
+      @config["use_digest_authentication"]
+    end
+
+    def use_digest_authentication=(value)
+      @config["use_digest_authentication"] = value
+    end
+
+    # Returns a format object suitable for use by ActiveResource.
+    def format
+      AdGear::XmlFormat
+    end
+
+    # Returns the Logger instance that was configured in #logger=.
+    def logger
+      @logger
+    end
+
+    # Register a Logger for use by AdGear's client.
+    # @param value [nil, String] When nil, no Logger is assigned.
+    #                            When the values STDERR or STDOUT are used, logs to the specified stream.
+    #                            Else, it is taken as the path to a log file.
+    def logger=(value)
+      @config["logger"] = value
+      @logger = case value
+                when nil, ""
+                  # No logger
+                  nil
+                when /^std(err|out)$/i
+                  # Existing stream
+                  Logger.new(Object.const_get(value.upcase))
+                else
+                  warn("WARNING: path to logger in AdGear::Client configuration is relative: CWD is #{Dir.pwd.inspect}") unless Pathname.new(value).absolute?
+                  # Path to a file
+                  Logger.new(value)
+                end
+    end
+  end
+end

data/lib/ad_gear/core_ext.rb

@@ -0,0 +1,18 @@
+#
+# ActiveSupport's Array#to_xml will build an XML with root set to the full class name including
+# module(s) it may be nested in - we don't want that, we want it to be *just* the class name,
+# make it so with this monkey patch...
+#
+# Note this is loaded last from AdGear.config= after ActiveSupport has already been loaded.  We
+# cannot simply override because ActiveSupport does lazy loading.
+#
+class Array
+  def to_xml_with_module_prefixing(options = {})
+    raise "Not all elements respond to to_xml in #{self.inspect}" unless all? { |e| e.respond_to? :to_xml }
+    root = all? { |e| e.is_a?(first.class) && first.class.to_s != "Hash" } ?
+      ActiveSupport::Inflector.pluralize(ActiveSupport::Inflector.underscore(first.class.to_s.split("::").last)) : "records"
+    to_xml_without_module_prefixing({ :root => root }.merge(options))
+  end
+
+  alias_method_chain :to_xml, :module_prefixing
+end

data/lib/ad_gear/file.rb

@@ -0,0 +1,4 @@
+module AdGear
+  class File < AdGear::Base
+  end
+end

data/lib/ad_gear/format.rb

@@ -0,0 +1,4 @@
+module AdGear
+  class Format < AdGear::Base
+  end
+end

data/lib/ad_gear/has_many_array.rb

@@ -0,0 +1,84 @@
+module AdGear
+  class HasManyArray
+    include Enumerable
+
+    def initialize(name, klass, saved=nil)
+      @name  = name.to_s.singularize.dasherize + "-attributes"
+      @klass = klass
+      @new   = []
+      @saved = []
+      saved.each do |obj|
+        self << obj
+      end if saved
+    end
+
+    def <<(object)
+      root = if object.kind_of?(Hash) then
+               if object.has_key?("id") || object.has_key?(:id) then
+                 object = @klass.new(object)
+                 @saved
+               else
+                 # Instantiate an object from the Hash, which will obviously be a new object
+                 object = @klass.new(object)
+                 @new
+               end
+             elsif object.respond_to?(:new_record?) && object.new_record?
+               @new
+             else
+               @saved
+             end
+      root << object
+    end
+
+    def each(&block)
+      @saved.each(&block)
+      @new.each(&block)
+    end
+
+    def length
+      @saved.length + @new.length
+    end
+
+    alias_method :size, :length
+
+    def empty?
+      combined.empty?
+    end
+
+    def [](*args)
+      combined[*args]
+    end
+
+    def first
+      combined.first
+    end
+
+    def last
+      combined.last
+    end
+
+    def to_xml(options={})
+      xml = options[:builder] || Builder::XmlMarkup.new
+      xml.__send__(@name) do
+        unless @new.empty?
+          xml.tag!(:new) do
+            @new.each_with_index do |obj, index|
+              obj.to_xml(options.merge(:root => "n" << index.to_s))
+            end
+          end
+        end
+
+        unless @saved.empty?
+          @saved.each do |obj|
+            obj.to_xml(options.merge(:root => "n" << obj.id.to_s))
+          end
+        end
+      end
+    end
+
+    private
+    def combined
+      @new + @saved
+    end
+  end
+end

data/lib/ad_gear/interaction.rb

@@ -0,0 +1,4 @@
+module AdGear
+  class Interaction < AdGear::Base
+  end
+end

data/lib/ad_gear/placement_membership.rb

@@ -0,0 +1,5 @@
+module AdGear
+	class PlacementMembership < AdGear::Base
+		belongs_to :ad_unit
+	end
+end

data/lib/ad_gear/placement_rule.rb

@@ -0,0 +1,5 @@
+module AdGear
+	class PlacementRule < AdGear::Base
+    belongs_to :bookable, :polymorphic => true
+	end
+end

data/lib/ad_gear/publisher.rb

@@ -0,0 +1,7 @@
+module AdGear
+  class Publisher < AdGear::Base
+    def active?
+      state == "active"
+    end
+  end
+end

data/lib/ad_gear/site.rb

@@ -0,0 +1,6 @@
+module AdGear
+  class Site < AdGear::Base
+    has_many :ad_spots
+    ignorable_attributes :embed_code
+  end
+end

data/lib/ad_gear/template.rb

@@ -0,0 +1,4 @@
+module AdGear
+  class Template < AdGear::Base
+  end
+end

data/lib/ad_gear/upload.rb

@@ -0,0 +1,46 @@
+begin
+  gem "francois-rest-client", ">= 1.1.5"
+rescue
+  # Ignored.  We hope we got what we wanted
+  warn "Could not ensure francois-rest-client 1.1.5 is loaded.  If you have problems uploading files, make sure you have that gem installed and that the AdGear::Client uses that version."
+end
+require "restclient"
+
+module AdGear
+  class Upload < AdGear::Base
+    def save
+      retried = false
+      headers = Hash.new
+      begin
+        uri = self.class.site.merge(URI.parse(self.class.collection_path))
+        params  = {"upload[uploaded_data]" => ::File.new(attributes["filename"]), "upload[filename]" => ::File.basename(attributes["filename"])}
+        out = RestClient.post(uri.to_s, params, headers)
+        logger.debug out if logger
+        load(connection.format.decode(out))
+      rescue RestClient::Unauthorized => e
+        # Retry once only
+        raise if retried
+
+        www_authenticate = e.response["www-authenticate"]
+        header = ActiveResource::Digest.authenticate(uri, self.class.user, self.class.password, www_authenticate, :post)
+        headers["Authorization"] = header
+
+        retried = true
+        retry
+      end
+    end
+
+    def update_attribute(*args)
+      raise_unsupported_operation
+    end
+
+    def update_attributes(*args)
+      raise_unsupported_operation
+    end
+
+    protected
+    def raise_unsupported_operation
+      raise UnsupportedOperation, "Unsupported operation: uploads are write-once only"
+    end
+  end
+end

data/lib/ad_gear/variable.rb

@@ -0,0 +1,4 @@
+module AdGear
+  class Variable < AdGear::Base
+  end
+end

data/lib/ad_gear/web_campaign.rb

@@ -0,0 +1,6 @@
+module AdGear
+  class WebCampaign < AdGear::Base
+    belongs_to :advertiser
+    has_many :web_placements
+  end
+end

data/lib/ad_gear/web_placement.rb

@@ -0,0 +1,26 @@
+module AdGear
+  class WebPlacement < AdGear::Base
+    belongs_to :campaign, :format
+    has_many :placement_rules, :placement_memberships
+
+    def selection_mechanism
+      case value = attributes["selection_mechanism"]
+      when "R" ; "rotated"
+      when "W" ; "weighted"
+      else     ; value
+      end
+    end
+
+    def selection_mechanism=(value)
+      case value
+      when /^r/i
+        attributes["selection_mechanism"] = "R"
+      when /^w/i
+        attributes["selection_mechanism"] = "W"
+      else
+        # Assign whatever we received, and hope for the best
+        attributes["selection_mechanism"] = value
+      end
+    end
+  end
+end

data/lib/ad_gear/xml_format.rb

@@ -0,0 +1,35 @@
+require 'active_support/core_ext/hash/conversions'
+
+module AdGear
+  # Copied from ActiveResource's +active_resource/formats/xml_format.rb+.  Changed +mime_type+ to return AdGear's expected mime type.
+  module XmlFormat
+    extend self
+
+    def extension
+      "agml"
+    end
+
+    def mime_type
+      "application/vnd.bloom.adgear.v1+xml"
+    end
+
+    def encode(hash, options={})
+      hash.to_xml(options)
+    end
+
+    def decode(xml)
+      from_xml_data(Hash.from_xml(xml))
+    end
+
+    private
+      # Manipulate from_xml Hash, because xml_simple is not exactly what we
+      # want for Active Resource.
+      def from_xml_data(data)
+        if data.is_a?(Hash) && data.keys.size == 1
+          data.values.first
+        else
+          data
+        end
+      end
+  end
+end