lib/google/api_client/discovery/resource.rb

   1 # Copyright 2010 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
  16 require 'addressable/uri'
  17
  18 require 'google/inflection'
  19 require 'google/api_client/discovery/method'
  20
  21
  22 module Google
  23   class APIClient
  24     ##
  25     # A resource that has been described by a discovery document.
  26     class Resource
  27
  28       ##
  29       # Creates a description of a particular version of a resource.
  30       #
  31       # @param [Google::APIClient::API] api
  32       #   The API this resource belongs to.
  33       # @param [Addressable::URI] method_base
  34       #   The base URI for the service.
  35       # @param [String] resource_name
  36       #   The identifier for the resource.
  37       # @param [Hash] discovery_document
  38       #   The section of the discovery document that applies to this resource.
  39       #
  40       # @return [Google::APIClient::Resource] The constructed resource object.
  41       def initialize(api, method_base, resource_name, discovery_document)
  42         @api = api
  43         @method_base = method_base
  44         @name = resource_name
  45         @discovery_document = discovery_document
  46         metaclass = (class <<self; self; end)
  47         self.discovered_resources.each do |resource|
  48           method_name = Google::INFLECTOR.underscore(resource.name).to_sym
  49           if !self.respond_to?(method_name)
  50             metaclass.send(:define_method, method_name) { resource }
  51           end
  52         end
  53         self.discovered_methods.each do |method|
  54           method_name = Google::INFLECTOR.underscore(method.name).to_sym
  55           if !self.respond_to?(method_name)
  56             metaclass.send(:define_method, method_name) { method }
  57           end
  58         end
  59       end
  60
  61       # @return [String] unparsed discovery document for the resource
  62       attr_reader :discovery_document
  63
  64       ##
  65       # Returns the identifier for the resource.
  66       #
  67       # @return [String] The resource identifier.
  68       attr_reader :name
  69
  70       ##
  71       # Returns the base URI for this resource.
  72       #
  73       # @return [Addressable::URI] The base URI that methods are joined to.
  74       attr_reader :method_base
  75
  76       ##
  77       # Returns a human-readable description of the resource.
  78       #
  79       # @return [Hash] The API description.
  80       def description
  81         return @discovery_document['description']
  82       end
  83
  84       ##
  85       # Updates the hierarchy of resources and methods with the new base.
  86       #
  87       # @param [Addressable::URI, #to_str, String] new_method_base
  88       #   The new base URI to use for the resource.
  89       def method_base=(new_method_base)
  90         @method_base = Addressable::URI.parse(new_method_base)
  91         self.discovered_resources.each do |resource|
  92           resource.method_base = @method_base
  93         end
  94         self.discovered_methods.each do |method|
  95           method.method_base = @method_base
  96         end
  97       end
  98
  99       ##
 100       # A list of sub-resources available on this resource.
 101       #
 102       # @return [Array] A list of {Google::APIClient::Resource} objects.
 103       def discovered_resources
 104         return @discovered_resources ||= (
 105           (@discovery_document['resources'] || []).inject([]) do |accu, (k, v)|
 106             accu << Google::APIClient::Resource.new(
 107               @api, self.method_base, k, v
 108             )
 109             accu
 110           end
 111         )
 112       end
 113
 114       ##
 115       # A list of methods available on this resource.
 116       #
 117       # @return [Array] A list of {Google::APIClient::Method} objects.
 118       def discovered_methods
 119         return @discovered_methods ||= (
 120           (@discovery_document['methods'] || []).inject([]) do |accu, (k, v)|
 121             accu << Google::APIClient::Method.new(@api, self.method_base, k, v)
 122             accu
 123           end
 124         )
 125       end
 126
 127       ##
 128       # Converts the resource to a flat mapping of RPC names and method
 129       # objects.
 130       #
 131       # @return [Hash] All methods available on the resource.
 132       def to_h
 133         return @hash ||= (begin
 134           methods_hash = {}
 135           self.discovered_methods.each do |method|
 136             methods_hash[method.id] = method
 137           end
 138           self.discovered_resources.each do |resource|
 139             methods_hash.merge!(resource.to_h)
 140           end
 141           methods_hash
 142         end)
 143       end
 144
 145       ##
 146       # Returns a <code>String</code> representation of the resource's state.
 147       #
 148       # @return [String] The resource's state, as a <code>String</code>.
 149       def inspect
 150         sprintf(
 151           "#<%s:%#0x NAME:%s>", self.class.to_s, self.object_id, self.name
 152         )
 153       end
 154     end
 155   end
 156 end