sdk/ruby-google-api-client/lib/google/api_client/service.rb

   1 # Copyright 2013 Google Inc.
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #      http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 require 'google/api_client'
  16 require 'google/api_client/service/stub_generator'
  17 require 'google/api_client/service/resource'
  18 require 'google/api_client/service/request'
  19 require 'google/api_client/service/result'
  20 require 'google/api_client/service/batch'
  21 require 'google/api_client/service/simple_file_store'
  22
  23 module Google
  24   class APIClient
  25
  26     ##
  27     # Experimental new programming interface at the API level.
  28     # Hides Google::APIClient. Designed to be easier to use, with less code.
  29     #
  30     # @example
  31     #   calendar = Google::APIClient::Service.new('calendar', 'v3')
  32     #   result = calendar.events.list('calendarId' => 'primary').execute()
  33     class Service
  34       include Google::APIClient::Service::StubGenerator
  35       extend Forwardable
  36
  37       DEFAULT_CACHE_FILE = 'discovery.cache'
  38
  39       # Cache for discovered APIs.
  40       @@discovered = {}
  41
  42       ##
  43       # Creates a new Service.
  44       #
  45       # @param [String, Symbol] api_name
  46       #   The name of the API this service will access.
  47       # @param [String, Symbol] api_version
  48       #   The version of the API this service will access.
  49       # @param [Hash] options
  50       #   The configuration parameters for the service.
  51       # @option options [Symbol, #generate_authenticated_request] :authorization
  52       #   (:oauth_1)
  53       #   The authorization mechanism used by the client.  The following
  54       #   mechanisms are supported out-of-the-box:
  55       #   <ul>
  56       #     <li><code>:two_legged_oauth_1</code></li>
  57       #     <li><code>:oauth_1</code></li>
  58       #     <li><code>:oauth_2</code></li>
  59       #   </ul>
  60       # @option options [Boolean] :auto_refresh_token (true)
  61       #   The setting that controls whether or not the api client attempts to
  62       #   refresh authorization when a 401 is hit in #execute. If the token does
  63       #   not support it, this option is ignored.
  64       # @option options [String] :application_name
  65       #   The name of the application using the client.
  66       # @option options [String] :application_version
  67       #   The version number of the application using the client.
  68       # @option options [String] :host ("www.googleapis.com")
  69       #   The API hostname used by the client. This rarely needs to be changed.
  70       # @option options [String] :port (443)
  71       #   The port number used by the client. This rarely needs to be changed.
  72       # @option options [String] :discovery_path ("/discovery/v1")
  73       #   The discovery base path. This rarely needs to be changed.
  74       # @option options [String] :ca_file
  75       #   Optional set of root certificates to use when validating SSL connections.
  76       #   By default, a bundled set of trusted roots will be used.
  77       # @option options [#generate_authenticated_request] :authorization
  78       #   The authorization mechanism for requests. Used only if
  79       #   `:authenticated` is `true`.
  80       # @option options [TrueClass, FalseClass] :authenticated (default: true)
  81       #   `true` if requests must be signed or somehow
  82       #   authenticated, `false` otherwise.
  83       # @option options [TrueClass, FalseClass] :gzip (default: true)
  84       #   `true` if gzip enabled, `false` otherwise.
  85       # @option options [Faraday::Connection] :connection
  86       #   A custom connection to be used for all requests.
  87       # @option options [ActiveSupport::Cache::Store, :default] :discovery_cache
  88       #   A cache store to place the discovery documents for loaded APIs.
  89       #   Avoids unnecessary roundtrips to the discovery service.
  90       #   :default loads the default local file cache store.
  91       def initialize(api_name, api_version, options = {})
  92         @api_name = api_name.to_s
  93         if api_version.nil?
  94           raise ArgumentError,
  95             "API version must be set"
  96         end
  97         @api_version = api_version.to_s
  98         if options && !options.respond_to?(:to_hash)
  99           raise ArgumentError,
 100             "expected options Hash, got #{options.class}"
 101         end
 102
 103         params = {}
 104         [:application_name, :application_version, :authorization, :host, :port,
 105          :discovery_path, :auto_refresh_token, :key, :user_ip,
 106          :ca_file].each do |option|
 107           if options.include? option
 108             params[option] = options[option]
 109           end
 110         end
 111
 112         @client = Google::APIClient.new(params)
 113
 114         @connection = options[:connection] || @client.connection
 115
 116         @options = options
 117
 118         # Initialize cache store. Default to SimpleFileStore if :cache_store
 119         # is not provided and we have write permissions.
 120         if options.include? :cache_store
 121           @cache_store = options[:cache_store]
 122         else
 123           cache_exists = File.exists?(DEFAULT_CACHE_FILE)
 124           if (cache_exists && File.writable?(DEFAULT_CACHE_FILE)) ||
 125              (!cache_exists && File.writable?(Dir.pwd))
 126             @cache_store = Google::APIClient::Service::SimpleFileStore.new(
 127               DEFAULT_CACHE_FILE)
 128           end
 129         end
 130
 131         # Attempt to read API definition from memory cache.
 132         # Not thread-safe, but the worst that can happen is a cache miss.
 133         unless @api = @@discovered[[api_name, api_version]]
 134           # Attempt to read API definition from cache store, if there is one.
 135           # If there's a miss or no cache store, call discovery service.
 136           if !@cache_store.nil?
 137             @api = @cache_store.fetch("%s/%s" % [api_name, api_version]) do
 138               @client.discovered_api(api_name, api_version)
 139             end
 140           else
 141             @api = @client.discovered_api(api_name, api_version)
 142           end
 143           @@discovered[[api_name, api_version]] = @api
 144         end
 145
 146         generate_call_stubs(self, @api)
 147       end
 148
 149       ##
 150       # Returns the authorization mechanism used by the service.
 151       #
 152       # @return [#generate_authenticated_request] The authorization mechanism.
 153       def_delegators :@client, :authorization, :authorization=
 154
 155       ##
 156       # The setting that controls whether or not the service attempts to
 157       # refresh authorization when a 401 is hit during an API call.
 158       #
 159       # @return [Boolean]
 160       def_delegators :@client, :auto_refresh_token, :auto_refresh_token=
 161
 162       ##
 163       # The application's API key issued by the API console.
 164       #
 165       # @return [String] The API key.
 166       def_delegators :@client, :key, :key=
 167
 168       ##
 169       # The Faraday/HTTP connection used by this service.
 170       #
 171       # @return [Faraday::Connection]
 172       attr_accessor :connection
 173
 174       ##
 175       # The cache store used for storing discovery documents.
 176       #
 177       # @return [ActiveSupport::Cache::Store,
 178       #          Google::APIClient::Service::SimpleFileStore,
 179       #          nil]
 180       attr_reader :cache_store
 181
 182       ##
 183       # Prepares a Google::APIClient::BatchRequest object to make batched calls.
 184       # @param [Array] calls
 185       #   Optional array of Google::APIClient::Service::Request to initialize
 186       #   the batch request with.
 187       # @param [Proc] block
 188       #   Callback for every call's response. Won't be called if a call defined
 189       #   a callback of its own.
 190       #
 191       # @yield [Google::APIClient::Service::Result]
 192       #   block to be called when result ready
 193       def batch(calls = nil, &block)
 194         Google::APIClient::Service::BatchRequest.new(self, calls, &block)
 195       end
 196
 197       ##
 198       # Executes an API request.
 199       # Do not call directly; this method is only used by Request objects when
 200       # executing.
 201       #
 202       # @param [Google::APIClient::Service::Request,
 203       #         Google::APIClient::Service::BatchCall] request
 204       #   The request to be executed.
 205       def execute(request)
 206         if request.instance_of? Google::APIClient::Service::Request
 207           params = {:api_method => request.method,
 208             :parameters => request.parameters,
 209             :connection => @connection}
 210           if request.respond_to? :body
 211             if request.body.respond_to? :to_hash
 212               params[:body_object] = request.body
 213             else
 214               params[:body] = request.body
 215             end
 216           end
 217           if request.respond_to? :media
 218             params[:media] = request.media
 219           end
 220           [:authenticated, :gzip].each do |option|
 221             if @options.include? option
 222               params[option] = @options[option]
 223             end
 224           end
 225           result = @client.execute(params)
 226           return Google::APIClient::Service::Result.new(request, result)
 227         elsif request.instance_of? Google::APIClient::Service::BatchRequest
 228           @client.execute(request.base_batch, {:connection => @connection})
 229         end
 230       end
 231     end
 232   end
 233 end