bloom-ad_gear_client 0.3.5

data/lib/ad_gear/base.rb

@@ -0,0 +1,168 @@
+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
+    #   end
+    #
+    #   include AdGear
+    #   AdSpot.new(:format => Format.find(1), :bookable => Publisher.find(2)).attributes
+    #     #=> {"format_id" => 1, "bookable_id" => 2, "bookable_type" => "Publisher"}
+    def self.belongs_to(*attributes)
+      options = attributes.extract_options!
+      attributes.each do |attribute|
+        attribute_name = attribute.to_s
+        belongs_to_associations[attribute_name] = options
+
+        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[belongs_to_attribute_name_for_class(attribute_name)]
+        id    = @attributes[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[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)
+      "#{association_name}_type"
+    end
+
+    def self.belongs_to_attribute_name_for_id(association_name)
+      "#{association_name}_id"
+    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" 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,58 @@
+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
+               # Instantiate an object from the Hash, which will obviously be a new object
+               object = @klass.new(object)
+               @new
+             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 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
+  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,4 @@
+module AdGear
+  class WebCampaign < AdGear::Base
+  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

data/lib/ad_gear.rb

@@ -0,0 +1,105 @@
+#--
+# Copyright (c) 2009 François Beausoleil
+# Copyright (c) 2009 Bloom Digital Platforms
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+require "active_support"
+require "active_resource"
+require "logger"
+
+warn "You are using the plain jane version of ActiveResource.  You could use Digest authentication if you used http://github.com/francois/rails/tree/ar_digest" unless ActiveResource::Base.respond_to?(:use_basic_authentication)
+
+module AdGear
+  # AdGear's models superclass
+  autoload :Base, "ad_gear/base"
+
+  # AdGear models themselves
+  autoload :Site, "ad_gear/site"
+  autoload :AdSpot, "ad_gear/ad_spot"
+  autoload :AdSpotMembership, "ad_gear/ad_spot_membership"
+  autoload :WebCampaign, "ad_gear/web_campaign"
+  autoload :Format, "ad_gear/format"
+  autoload :Upload, "ad_gear/upload"
+  autoload :Publisher, "ad_gear/publisher"
+
+  # Placements and it's dependencies
+  autoload :WebPlacement, "ad_gear/web_placement"
+  autoload :PlacementRule, "ad_gear/placement_rule"
+  autoload :PlacementMembership, "ad_gear/placement_membership"
+
+  # AdUnits and it's child models
+  autoload :AdUnit, "ad_gear/ad_unit"
+  autoload :AdUnitFile, "ad_gear/ad_unit_file"
+  autoload :AdUnitInteraction, "ad_gear/ad_unit_interaction"
+  autoload :AdUnitClick, "ad_gear/ad_unit_click"
+  autoload :AdUnitVariable, "ad_gear/ad_unit_variable"
+
+  # Templates and their dependencies, to know what child models are required
+  autoload :Template, "ad_gear/template"
+  autoload :File, "ad_gear/file"
+  autoload :Variable, "ad_gear/variable"
+  autoload :Click, "ad_gear/click"
+  autoload :Interaction, "ad_gear/interaction"
+
+  # Miscellaneous stuff
+  autoload :Config, "ad_gear/config"
+  autoload :XmlFormat, "ad_gear/xml_format"
+  autoload :HasManyArray, "ad_gear/has_many_array"
+
+  class UnsupportedOperation < RuntimeError; end
+
+  # Configures AdGear's ActiveResource models.
+  #
+  # NOTE: AdGear's client expects and uses Nokogiri instead of REXML.
+  # See http://rubyglasses.blogspot.com/2009/07/40-speedup-using-nokogiri.html#instructions
+  def self.config=(config)
+    @config = config
+
+    AdGear::Base.logger   = config.logger
+
+    AdGear::Base.site     = config.site
+    AdGear::Base.user     = config.user
+    AdGear::Base.password = config.password
+    AdGear::Base.format   = config.format
+
+    if AdGear::Base.respond_to?(:use_basic_authentication=)
+      AdGear::Base.use_basic_authentication = config.use_basic_authentication
+    end
+
+    if AdGear::Base.respond_to?(:use_digest_authentication=)
+      AdGear::Base.use_digest_authentication = config.use_digest_authentication
+    end
+
+    ActiveSupport::XmlMini.backend = "Nokogiri"
+
+    # Can't require before now, because our own method is overwritten
+    require "ad_gear/core_ext"
+  end
+
+  def self.config
+    @config
+  end
+
+  def self.logger
+    config.logger
+  end
+end