google-ads-common 0.2.0

data/README

@@ -0,0 +1,68 @@
+= Google AdsCommon Library
+
+This gem is a dependency for the new generation of Ruby Google Ads client
+libraries. It contains common code shared among all of these libraries, such as
+authentication, SOAP stub generation, error handling, logging, etc.
+
+This is an early preview release, so a lot of things are still missing!
+
+
+= Docs for Users
+
+== 1 - Installation:
+
+google-ads-common is a Ruby gem.  See http://docs.rubygems.org/read/book/1
+
+Install it using the gem install command.
+   $ gem install --local google-ads-common-VERSION.gem
+
+The following gem libraries are required:
+ - soap4r v1.5.8 (only for soap4r-based libraries);
+ - savon v0.8.5 or greater (only for savon-enabled libraries);
+ - httpclient v2.1.2 or greater.
+
+= Docs for Developers
+
+== 1 - Directory Structure
+
+- +lib/ads_common/+: Contains the bulk of the library.
+  - +auth/+: Contains classes that can handle different authentication methods.
+    Currently only supports ClientLogin.
+  - +build/+: Contains classes that handle code generation, packaging and other
+    build-time tasks for client libraries (not for google-ads-common).
+  - +savon_headers/+: Contains classes that handle header injection into savon
+    requests.
+  - +soap4r_headers/+: Contains classes that handle header injection into soap4r
+    requests.
+- +test/+: Contains the unit tests for the library.
+
+== 2 - Commands
+
+ $ rake package
+to package the gem and create a release
+
+ $ rake test
+to run unit tests on the library
+
+
+= Copyright/License Info
+
+Copyright 2010, Google Inc. All Rights Reserved.
+
+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.
+
+
+== Authors
+
+Sérgio Gomes (api.sgomes@gmail.com)
+Danial Klimkin (api.dklimkin@gmail.com)

data/Rakefile

@@ -0,0 +1,128 @@
+#!/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.
+#
+# Rakefile for the ads_common package.
+
+require 'rubygems'
+gem 'rake'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/clean'
+require 'rake/testtask'
+require 'lib/ads_common/api_config'
+
+$WSDLDIR = 'wsdl'
+$LIBDIR = 'lib'
+$DOCDIR = 'doc'
+$TESTDIR = 'test'
+
+$PROJECT_NAME = 'ads_common'
+$GEM_NAME = 'google-ads-common'
+
+$CURRENT_VERSION = AdsCommon::ApiConfig::ADS_COMMON_VERSION
+$PKG_VERSION = ENV['REL'] ? ENV['REL'] : $CURRENT_VERSION
+
+# Configure gem details
+$GEM_SUMMARY = "Common code for Google Ads APIs."
+$GEM_DESCRIPTION = "#{$PROJECT_NAME} provides essential utilities shared by " +
+    "all Ads Ruby client libraries."
+$GEM_AUTHORS = ['Sergio Gomes', 'Danial Klimkin']
+$GEM_EMAIL = 'api.sgomes@gmail.com'
+$GEM_HOMEPAGE = 'http://code.google.com/p/google-api-adwords-ruby/'
+
+# ====================================================================
+# Default task - call package
+task :default => [:package]
+
+# ====================================================================
+# Create a task to build the RDOC documentation tree.
+Rake::RDocTask.new("rdoc") do |rdoc|
+  # Try to use SDoc to generate the docs
+  begin
+    require 'sdoc'
+    rdoc.options << '--fmt' << 'shtml'
+    rdoc.template = 'direct'
+  rescue LoadError
+    # Do nothing, give up on SDoc and continue with whatever is the default.
+  end
+  rdoc.rdoc_dir = $DOCDIR
+  rdoc.title = "#{$PROJECT_NAME} -- Common code for Google Ads APIs"
+  rdoc.main = 'README'
+  rdoc.rdoc_files.include('README', 'COPYING', 'ChangeLog')
+  rdoc.rdoc_files.include("#{$LIBDIR}/**/*.rb")
+end
+
+# ====================================================================
+# Create a task to perform the unit testing.
+Rake::TestTask.new("test") do |test|
+  test.libs << $TESTDIR
+  test.pattern = "#{$TESTDIR}/**/test_*.rb"
+  test.verbose = true
+end
+
+# ====================================================================
+# Create a task that will package the Rake software into distributable
+# gem files.
+PKG_FILES = FileList[
+  '*.*',
+  'Rakefile',
+  "#{$LIBDIR}/**/*.rb",
+  "#{$DOCDIR}/**/*.*",
+  "#{$TESTDIR}/**/*.*"
+]
+
+PKG_FILES.exclude(/\._/)
+
+if ! defined?(Gem)
+  puts "Package Target requires RubyGems"
+else
+  spec = Gem::Specification.new do |s|
+
+    # Basic information
+    s.name = $GEM_NAME
+    s.version = $PKG_VERSION
+    s.summary = $GEM_SUMMARY
+    s.description = $GEM_DESCRIPTION
+
+    # Files and dependencies
+    s.files = PKG_FILES.to_a
+    s.require_path = $LIBDIR
+    s.add_dependency('soap4r', '= 1.5.8')
+    s.add_dependency('httpclient', '>= 2.1.5.2')
+    s.add_dependency('httpi', '~>0.7.9')
+
+    # RDoc information
+    s.has_rdoc = true
+    s.extra_rdoc_files = ['README']
+    s.rdoc_options << '--main' << 'README'
+
+    # Metadata
+    s.authors = $GEM_AUTHORS
+    s.email = $GEM_EMAIL
+    s.homepage = $GEM_HOMEPAGE
+    s.rubyforge_project = $GEM_NAME
+    s.requirements << 'soap4r v1.5.8'
+    s.requirements << 'httpclient v2.1.5.2 or greater'
+    s.requirements << 'httpi v0.7.9 or greater'
+  end
+
+  Rake::GemPackageTask.new(spec) do |t|
+    t.need_tar = true
+  end
+end

data/lib/ads_common/api.rb

@@ -0,0 +1,183 @@
+#!/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 Api class, to be inherited from and extended by specific APIs.
+
+require 'ads_common/errors'
+require 'ads_common/auth/base_handler'
+require 'ads_common/auth/client_login_handler'
+require 'ads_common/soap4r_headers/nested_header_handler'
+require 'ads_common/soap4r_headers/single_header_handler'
+require 'ads_common/soap4r_response_handler'
+
+module AdsCommon
+  class Api
+
+    # Auxiliary method to create a new Soap4rResponseHandler
+    # Should be redefined in inheriting classes, if planning to do specific
+    # logging.
+    def create_handler
+      AdsCommon::Soap4rResponseHandler.new(self)
+    end
+
+    # Logger object used for logging request info
+    attr_reader :request_logger
+
+    # Logger object used for logging SOAP XML
+    attr_reader :xml_logger
+
+    # Methods that return the service configuration and the client library
+    # configuration. They need to be redefined in subclasses.
+    attr_reader :api_config, :config
+
+    # Credential handler objects used for authentication
+    attr_reader :credential_handler
+
+    # The configuration for this Api object
+    attr_reader :config
+
+    # Obtain an API service, given a version and its name.
+    #
+    # Args:
+    # - name: name for the intended service
+    # - version: intended API version.
+    #
+    # Returns:
+    # - the service wrapper for the intended service.
+    #
+    def service(name, version = nil)
+      version = api_config.default_version if version == nil
+      # Check if version exists
+      if !api_config.versions.include?(version.to_sym)
+        if version.is_a? Integer
+          raise AdsCommon::Errors::Error, "Unknown version '#{version}'. " +
+              "Please note that version numbers should be symbols; check the" +
+              "Readme or the included examples for more information."
+        else
+          raise AdsCommon::Errors::Error, "Unknown version #{version}"
+        end
+      end
+      version = version.to_sym
+      name = name.to_sym
+      environment = config.read('service.environment')
+      # Check if the current environment supports the requested version
+      if !api_config.environment_has_version(environment, version)
+        raise AdsCommon::Errors::Error,
+          "Environment #{environment} does not support version #{version}"
+      end
+      # Check if the specified version has the requested service
+      if !api_config.version_has_service(version, name)
+        raise AdsCommon::Errors::Error, "Version #{version} does not contain " +
+          "service #{name}"
+      end
+      prepare_driver(version, name)
+      return @wrappers[[version, name]]
+    end
+
+    # Retrieve the SOAP header handlers to plug into the drivers. Needs to
+    # be implemented on the specific API, because of the different types of
+    # SOAP headers (optional parameter specifying API version).
+    #
+    # Args:
+    # - auth_handler: instance of an AdsCommon::Auth::BaseHandler subclass to
+    #   handle authentication
+    # - header_list: the list of headers to be handled
+    # - version: intended API version
+    # - wrapper: wrapper object for the service being handled
+    #
+    # Returns:
+    # - a list of SOAP header handlers; one per provided header
+    #
+    def soap_header_handlers(auth_handler, header_list, version, wrapper = nil)
+    end
+
+    private
+
+    # Auxiliary method to create an authentication handler. Needs to be
+    # implemented on the specific API because of the different nesting models
+    # used in different APIs and API versions.
+    #
+    # Args:
+    # - version: intended API version
+    # - environment: the current working environment (production, sandbox, etc.)
+    #
+    # Returns:
+    # - auth handler
+    #
+    def create_auth_handler(version = nil, environment = nil)
+    end
+
+    # Handle loading of a single service.
+    # Creates the driver, sets up handlers and loggers, declares the appropriate
+    # wrapper class and creates an instance of it.
+    #
+    # Args:
+    # - version: intended API version. Must be an integer.
+    # - service: name for the intended service
+    #
+    # Returns:
+    # - the driver for the service
+    # - the simplified wrapper generated for the driver
+    #
+    def prepare_driver(version, service)
+      version = version.to_sym
+      service = service.to_sym
+      environment = config.read('service.environment')
+      api_config.do_require(version, service)
+      endpoint = api_config.endpoint(environment, version, service)
+      # Set endpoint if not using the default
+      if endpoint.nil? then
+        driver = eval("#{api_config.interface_name(version, service)}.new")
+      else
+        endpoint_url = endpoint.to_s + service.to_s
+        driver = eval("#{api_config.interface_name(version, service)}.new" +
+                      "(\"#{endpoint_url}\")")
+      end
+
+      # Create an instance of the wrapper class for this service.
+      wrapper_class = api_config.wrapper_name(version, service)
+      wrapper = eval("#{wrapper_class}.new(driver, self)")
+
+      auth_handler = create_auth_handler(version, environment)
+      header_list =
+          auth_handler.header_list(@credential_handler.credentials(version))
+
+      soap_handlers = soap_header_handlers(auth_handler, header_list, version,
+          wrapper)
+
+      soap_handlers.each do |handler|
+        driver.headerhandler << handler
+      end
+
+      # Add response handler to this driver for API unit usage processing.
+      driver.callbackhandler = create_callback_handler
+      # Plug the wiredump to our XML logger
+      driver.wiredump_dev = xml_logger
+      driver.options['protocol.http.ssl_config.verify_mode'] = nil
+      proxy = config.read('connection.proxy')
+      if proxy
+        driver.options['protocol.http.proxy'] = proxy
+      end
+
+      @drivers[[version, service]] = driver
+      @wrappers[[version, service]] = wrapper
+      return driver, wrapper
+    end
+  end
+end

data/lib/ads_common/api_config.rb

@@ -0,0 +1,284 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#           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.
+#
+# Helper methods for loading and managing services for an API. Defines methods
+# to be included as class modules in a service class for a specific API.
+
+module AdsCommon
+
+  # Contains helper methods for loading and managing the available services.
+  # This module is meant to be imported into API-specific modules.
+  module ApiConfig
+    ADS_COMMON_VERSION = '0.2.0'
+
+    # Get the available API versions.
+    #
+    # Returns:
+    # List of versions available (as integers)
+    #
+    def versions
+      service_config.keys
+    end
+
+    # Get the latest API version.
+    #
+    # Returns:
+    # Latest version (as an integer)
+    #
+    def latest_version
+      service_config.keys.select { |service| service.is_a? Integer }.max
+    end
+
+    # Does the given environment exist and contain the given version?
+    #
+    # Returns:
+    # Boolean indicating whether the given environment exists and contains the
+    # given version
+    #
+    def environment_has_version(environment, version)
+      environment = environment.upcase.to_sym
+      version = version.to_sym
+      !environment_config[environment].nil? and
+          !environment_config[environment][version].nil?
+    end
+
+    # Does the given version exist and contain the given service?
+    #
+    # Returns:
+    # Boolean indicating whether the given version exists and contains the
+    # given service
+    #
+    def version_has_service(version, service)
+      version = version.to_sym
+      service = service.to_sym
+      (!service_config[version].nil? and
+          service_config[version].include?(service))
+    end
+
+    # Get the default API version.
+    #
+    # Returns:
+    # Default version (as an integer)
+    #
+    def default_version
+      nil
+    end
+
+    # Get the list of service names for a given version
+    #
+    # Args:
+    # - version: the API version (as an integer)
+    #
+    # Returns:
+    # List of names of services (as strings) available for given version
+    #
+    def services(version)
+      service_config[version]
+    end
+
+    # Get the available environments.
+    #
+    # Returns:
+    # List of available environments (as strings)
+    #
+    def environments
+      environment_config.keys
+    end
+
+    # Get the default environment.
+    #
+    # Returns:
+    # Default environment (as a string)
+    #
+    def default_environment
+      nil
+    end
+
+    # Get the endpoint for a service on a given environment and API version.
+    #
+    # Args:
+    # - environment: the service environment to be used (as a string)
+    # - version: the API version (as an integer)
+    # - service: the name of the API service (as a string)
+    #
+    # Returns:
+    # The endpoint URL (as a string)
+    #
+    def endpoint(environment, version, service)
+      environment = environment.upcase.to_sym
+      version = version.to_sym
+      service = service.to_sym
+      base = get_wsdl_base(environment, version)
+      if !subdir_config().nil?
+        base = base.to_s + subdir_config()[[version, service]].to_s
+      end
+      return base.to_s + version.to_s + '/'
+    end
+
+    # Get the subdirectory for a service, for a given API version.
+    #
+    # Args:
+    # - version: the API version (as an integer)
+    # - service: the name of the API service (as a string)
+    #
+    # Returns:
+    # The endpoint URL (as a string)
+    #
+    def subdir(version, service)
+      return nil if subdir_config().nil?
+      version = version.to_sym
+      service = service.to_sym
+      subdir_config()[[version, service]]
+    end
+
+    # Get the authentication server details for an environment. Allows to
+    # override the auth URL via environmental variable.
+    #
+    # Args:
+    # - environment: the service environment to be used (as a string)
+    #
+    # Returns:
+    # The full URL for the auth server.
+    #
+    def auth_server(environment)
+      auth_server_url = ENV['ADSAPI_AUTH_URL']
+      if auth_server_url.nil?
+        environment = environment.upcase.to_sym
+        auth_server_url = auth_server_config[environment]
+      end
+      if auth_server_url.nil?
+        # If we don't have an entry for this environment, we just return the
+        # default server (the same one being used for the default environment)
+        auth_server_url = auth_server_config[default_environment()]
+      end
+      return auth_server_url
+    end
+
+    # Add a new environment to the list.
+    #
+    # Args:
+    # - name: the name for the new environment
+    # - endpoint_hash: a hash of base endpoint URLs, indexed by version number,
+    #   e.g.:
+    #    { :v13 => 'URL_FOR_v13', :v200906 => 'URL_FOR_v200906' }
+    #
+    def add_environment(name, endpoint_hash)
+      name = name.upcase.to_sym
+      environment_config[name] = endpoint_hash
+    end
+
+    # Perform the loading of the necessary source files for a version
+    #
+    # Args:
+    # - version: the API version (as an integer)
+    #
+    def do_require(version, service)
+      version = version.to_sym
+      eval("require '#{api_path}/#{version}/#{service}Wrapper.rb'")
+    end
+
+    # Returns the full module name for a given service
+    #
+    # Args:
+    # - version: the API version (as an integer)
+    # - service: the service name (as a string)
+    #
+    # Returns:
+    # The full module name for the given service (as a string)
+    #
+    def module_name(version, service)
+      version = version.to_sym
+      service = service.to_sym
+      return "#{api_name}::#{version.to_s.upcase}::#{service}"
+    end
+
+    # Returns the full interface class name for a given service
+    #
+    # Args:
+    # - version: the API version (as an integer)
+    # - service: the service name (as a string)
+    #
+    # Returns:
+    # The full interface class name for the given service (as a string)
+    #
+    def interface_name(version, service)
+      version = version.to_sym
+      service = service.to_sym
+      return module_name(version, service) + "::#{service}Interface"
+    end
+
+    # Returns the full wrapper class name for a given service
+    #
+    # Args:
+    # - version: the API version (as an integer)
+    # - service: the service name (as a string)
+    #
+    # Returns:
+    # The full wrapper class name for the given service (as a string)
+    #
+    def wrapper_name(version, service)
+      version = version.to_sym
+      service = service.to_sym
+      return module_name(version, service) + "::#{service}Wrapper"
+    end
+
+    # Generates an array of WSDL URLs based on defined Services and version
+    # supplied. This method is used by generators to determine what service
+    # wrappers to generate.
+    #
+    # Args:
+    #   - version: the API version.
+    #
+    # Returns
+    #   hash of pairs Service => WSDL URL.
+    #
+    def get_wsdls(version)
+      res = {}
+      wsdl_base = get_wsdl_base(default_environment(), version)
+      services(version).each do |service|
+        path = wsdl_base
+        if (!subdir_config().nil?)
+          subdir_name = subdir(version, service);
+          path = path + subdir_name if !subdir_name.empty?()
+        end
+        path = path + version.to_s + '/' + service.to_s + '?wsdl'
+        res[service.to_s] = path
+      end
+      return res
+    end
+
+    # Returns WSDL base url defined in Service configuration. Allows to override
+    # the base URL via environmental variable.
+    #
+    # Args:
+    #   - environment: environment to use like SANDBOX or PRODUCTION
+    #   - version: the API version.
+    #
+    # Returns:
+    #   String containing base URL.
+    def get_wsdl_base(environment, version)
+      wsdl_base = ENV['ADSAPI_BASE_URL']
+      if wsdl_base.nil?
+        wsdl_base = environment_config[environment][version]
+      end
+      return wsdl_base
+    end
+  end
+end