google-ads-common 0.2.0

data/lib/ads_common/config.rb

@@ -0,0 +1,122 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2010, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Configuration handler, can load data from a YAML configuration file and
+# rewrite it in memory.
+
+require 'rubygems'
+require 'yaml'
+
+module AdsCommon
+  class Config
+
+    # Initialized the Config object with either the contents of a provided file
+    # or a provided hash.
+    def initialize(param = nil)
+      @config = {}
+      if param and param.is_a? String
+        load(param)
+      elsif param and param.is_a? Hash
+        set_all(param)
+      end
+    end
+
+    # Reads a property or category from the loaded configuration.
+    # They can be indexed using a dot-based notation (e.g. "category.property"
+    # to access "property" under "category").
+    def read(property_path = nil)
+      current_level = @config
+      if property_path
+        property_path.split('.').each do |item|
+          return nil if !current_level or !(current_level.is_a?(Hash))
+          current_level = current_level[item.to_sym]
+        end
+      end
+      return current_level
+    end
+
+    # Writes a new value to a property or category in memory (creating it if
+    # necessary).
+    # They can be indexed using a dot-based notation (e.g. "category.property"
+    # to access "property" under "category").
+    def set(property_path, value)
+      @config = {} if !@config
+      current_level = @config
+      if property_path
+        segments = property_path.split('.')
+        segments[0,-2].each do |item|
+          return nil if !current_level or !(current_level.is_a?(Hash))
+          current_level = current_level[item.to_sym]
+        end
+        if current_level and current_level.is_a?(Hash)
+          current_level[segments.last] = value
+          return value
+        end
+      end
+      return nil
+    end
+
+    # Writes an entire set of properties.
+    def set_all(properties)
+      @config = process_hash_keys(properties)
+    end
+
+    # Auxiliary method to recurse through a hash and convert all the keys to
+    # symbols.
+    def process_hash_keys(hash)
+      new_hash = {}
+      hash.each do |key, value|
+        if value.is_a? Hash
+          new_hash[key.to_sym] = process_hash_keys(value)
+        else
+          new_hash[key.to_sym] = value
+        end
+      end
+      return new_hash
+    end
+
+    # Reads a configuration file and returns a Ruby structure with the complete
+    # set of keys and values.
+    #
+    #
+    # Args:
+    # - filename: config file to be read (*String*)
+    #
+    # Returns:
+    # - Ruby objects for the stored YAML
+    #
+    # Raises:
+    # - <b>Errno::EACCES</b> if the file does not exist.
+    #
+    def load(filename)
+      unless File.exist?(filename)
+        raise(Errno::EACCES, "File #{filename} does not exist")
+      end
+      file = nil
+      begin
+        file = File.open(filename)
+        @config = YAML::load(file)
+      ensure
+        file.close if file
+      end
+      return @config
+    end
+  end
+
+end

data/lib/ads_common/credential_handler.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2010, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Generic class to handle credentials across client libraries.
+
+module AdsCommon
+  class CredentialHandler
+
+    def initialize(config)
+      @config = config
+      load_from_config
+    end
+
+    # Retrieve all credentials (optional parameter specifying API version).
+    def credentials(version = nil)
+      return @credentials
+    end
+
+    # Set the credentials hash to a new one. Calculate difference, and call the
+    # AuthHandler callback appropriately.
+    def credentials=(new_credentials)
+      # Find new and changed properties.
+      diff = new_credentials.select do |key, value|
+        value != @credentials[key]
+      end
+
+      # Find removed properties.
+      removed = @credentials.select do |key, value|
+        new_credentials[key] == nil
+      end
+      if removed
+        removed = removed.map { |entry| [entry[0], nil] }
+        diff += removed
+      end
+
+      # Set each property.
+      diff.each do |entry|
+        set_credential(entry[0], entry[1])
+      end
+    end
+
+    # Set a single credential to a new value. Call the AuthHandler callback
+    # appropriately.
+    def set_credential(credential, value)
+      @credentials[credential] = value
+      @auth_handler.property_changed(credential, value) if auth_handler
+    end
+
+    private
+
+    # Loads the credentials from the config data.
+    def load_from_config
+      @credentials = @config.read('authentication')
+    end
+  end
+end

data/lib/ads_common/errors.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Contains common errors across APIs, as well as base classes to inherit from
+# in specific APIs.
+
+module AdsCommon
+  module Errors
+
+    # Generic error class for non-specific errors.
+    class Error < ::StandardError
+    end
+
+    # Raised if an attempt is made to authenticate via the ClientLogin API with
+    # missing or wrong information
+    class AuthError < Error
+    end
+
+    # Raised if setting a non-existant property on an object
+    class MissingPropertyError < Error
+      attr_reader :property, :object_type
+      def initialize(property, object_type)
+        @property = property
+        @object_type = object_type
+      end
+    end
+
+    # Raised if an attempt is made to connect to the sandbox with production
+    # credentials or vice-versa
+    class EnvironmentMismatchError < Error
+    end
+
+    # Raised if a HTTP error like 403 or 404 has happened.
+    class HttpError < Error
+    end
+
+    # Raised if an error has occured during code generation.
+    class BuildError < Error
+    end
+
+    # Superclass for API exceptions. Each client library should implement its
+    # own subclass with extra fields.
+    class ApiException < Error
+
+      attr_reader :message
+
+      def initialize(message = nil)
+        @message = message
+      end
+
+    end
+
+  end
+end

data/lib/ads_common/http.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Contains helpful methods to make HTTP requests, using all of the connection
+# options available through the client library.
+
+require 'httpi'
+
+require 'ads_common/errors'
+
+module AdsCommon
+  module Http
+
+    # Performs a get on a URL, using all of the connection options in the
+    # client library, returning a HTTPI::Response.
+    def self.get_response(url, config = nil, headers = nil)
+      request = prepare_request(config, url, headers)
+      response = HTTPI.get(request)
+      return response
+    end
+
+    # Performs a get on a URL, using all of the connection options in the
+    # client library, returning the response body as a string.
+    def self.get(url, config = nil, headers = nil)
+      return get_response(url, config, headers).body
+    end
+
+    # Performs a post on a URL, using all of the connection options in the
+    # client library, returning a HTTPI::Response.
+    def self.post_response(url, data, config = nil, headers = nil)
+      request = prepare_request(config, url, headers, data)
+      response = HTTPI.post(request)
+      return response
+    end
+
+    # Performs a post on a URL, using all of the connection options in the
+    # client library, returning the response body as a string.
+    def self.post(url, data, config = nil, headers = nil)
+      return post_response(url, data, config, headers).body
+    end
+
+    private
+
+    # Returns a suitably configured request object for a given URL and options.
+    # Defaulting to stricter :peer validation.
+    def self.prepare_request(config, url, headers = nil, data = nil)
+      request = HTTPI::Request.new(url)
+      proxy = config ? config.read('connection.proxy') : nil
+      request.proxy = proxy if proxy
+      strict_ssl = config.nil? or
+          !(config.read('connection.strict_ssl_verification') == 'false')
+      request.auth.ssl.verify_mode = strict_ssl ? :peer : :none
+      request.headers = headers if headers
+      request.body = data if data
+      HTTPI.log = false # TODO remove after logger CL.
+      return request
+    end
+  end
+end

data/lib/ads_common/logger.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2010, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Wrapper class to handle logging to console and/or files.
+
+require 'logger'
+
+module AdsCommon
+
+  # Wrapper class to handle logging to console and/or files.
+  class Logger
+
+    # Constructor for AdsLogger.
+    #
+    # Args:
+    # - filename: the filename for the log file to be written (if log_to_file is
+    #   called)
+    # - log_to_console: boolean, indicates whether or not to log to the console
+    #
+    def initialize(filename, log_to_console=false)
+      @filename = filename
+      @loggers = []
+      if log_to_console
+        stderr_logger = ::Logger.new(STDERR)
+        stderr_logger.level = ::Logger::INFO
+        @loggers << stderr_logger
+      end
+    end
+
+    # Enables logging to a file.
+    # May be called several times to log to multiple files.
+    #
+    # Args:
+    # - path: where to write the file (defaults to current dir). Path only, do
+    #   not provide filename.
+    #
+    def log_to_file(path='.')
+      new_logger = ::Logger.new(File.join(path, @filename))
+      new_logger.level = ::Logger::INFO
+      @loggers << new_logger
+
+      return nil
+    end
+
+    # Overload << operator to perform logging.
+    def << (text)
+      @loggers.each do |logger|
+        logger.info text.to_s
+      end
+    end
+  end
+end

data/lib/ads_common/savon_headers/simple_header_handler.rb

@@ -0,0 +1,148 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Handles SOAP headers and namespaces definition for Savon SOAP backend.
+
+module AdsCommon
+  module SavonHeaders
+    class SimpleHeaderHandler
+
+      # Default namespace alias
+      DEFAULT_NAMESPACE = 'wsdl'
+
+      # Initializes a header handler.
+      #
+      # Args:
+      #  - credential_handler: a header with credential data.
+      #  - auth_handler: a header with auth data.
+      #  - element_name: an API-specific name of header element.
+      #  - namespace: default namespace to use.
+      #  - version: services version.
+      def initialize(credential_handler, auth_handler, element_name,
+                     namespace, version)
+        @credential_handler = credential_handler
+        @auth_handler = auth_handler
+        @element_name = element_name
+        @namespace = namespace
+        @version = version
+        Savon.configure {|config| config.raise_errors = false}
+      end
+
+      # Enriches soap object with API-specific headers like namespaces, login
+      # credentials etc.
+      #
+      # Args:
+      #  - soap: a Savon soap object to fill fields in.
+      #  - args: request parameters to adjust for namespaces.
+      #
+      # Returns:
+      #  - Modified soap structure.
+      def prepare_soap(soap, args)
+        soap.header[prepend_namespace(@element_name)] =
+            generate_request_header()
+        soap.namespace = @namespace
+        if (!args.nil?)
+          soap.body = prepare_args(args)
+        end
+      end
+
+      private
+
+      # Generates SOAP request header with login credentials and namespace
+      # definition.
+      #
+      # Args:
+      #  - None.
+      #
+      # Returns:
+      #  - Hash containing a header with filled in credentials.
+      def generate_request_header()
+        request_header = {}
+        credentials = @credential_handler.credentials(@version)
+        headers = @auth_handler.headers(credentials)
+        headers.each do |header, value|
+          request_header[prepend_namespace(header)] = value
+        end
+        return request_header
+      end
+
+      # Modifies request parameters to include namespace reference. For Hash
+      # and Array data types dives deeper into structure.
+      #
+      # Args:
+      #  - args: subtree of request parameters.
+      #
+      # Returns:
+      #  - subtree with modified parameters including namespaces.
+      def prepare_args(args)
+        res = case args
+            when Hash
+              prepare_hash_args(args)
+            when Array
+              prepare_array_args(args)
+            else
+              args
+            end
+        return res
+      end
+
+      # Crawls hash for all the request parameters and adds namespace
+      # reference for the keys.
+      #
+      # Args:
+      #  - args: Hash element of subtree of request parameters.
+      #
+      # Returns:
+      #  - Modified Hash with all keys updated and all values crawled.
+      def prepare_hash_args(args)
+        res = {}
+        args.each do |key, value|
+          res[prepend_namespace(key)] = prepare_args(value)
+        end
+        return res
+      end
+
+      # Crawls array and process each of its elements to include namespace.
+      #
+      # Args:
+      #  - args: Array element of subtree of request parameters.
+      #
+      # Returns:
+      #  - Modified Array with every element crawled.
+      def prepare_array_args(args)
+        res = []
+        args.each do |item|
+          res << prepare_args(item)
+        end
+        return res
+      end
+
+      # Adds namespace to the request parameter name.
+      #
+      # Args:
+      #  - str: String to prepend with a namespace
+      #
+      # Returns:
+      #  - String with a namespace.
+      def prepend_namespace(str)
+        return "%s:%s" % [DEFAULT_NAMESPACE, str.to_s]
+      end
+    end
+  end
+end