Class: HyperResource

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Modules::ConfigAttributes, Modules::DataType, Modules::Deprecations, Modules::InternalAttributes
Defined in:
lib/hyper_resource.rb,
lib/hyper_resource/link.rb,
lib/hyper_resource/links.rb,
lib/hyper_resource/adapter.rb,
lib/hyper_resource/objects.rb,
lib/hyper_resource/version.rb,
lib/hyper_resource/attributes.rb,
lib/hyper_resource/exceptions.rb,
lib/hyper_resource/modules/http.rb,
lib/hyper_resource/configuration.rb,
lib/hyper_resource/adapter/hal_json.rb,
lib/hyper_resource/modules/data_type.rb,
lib/hyper_resource/modules/deprecations.rb,
lib/hyper_resource/modules/config_attributes.rb

Overview

HyperResource is the main resource base class. Normally it will be used through subclassing, though it may also be used directly.

Defined Under Namespace

Modules: Modules Classes: Adapter, Attributes, ClientError, Configuration, Exception, Link, Links, Objects, ResponseError, ServerError

Constant Summary collapse

VERSION = 
'0.9.4'
VERSION_DATE = 
'2015-11-18'

Constants included from Modules::ConfigAttributes

Modules::ConfigAttributes::ATTRS

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Modules::InternalAttributes

included

Methods included from Modules::Deprecations

#_hr_deprecate, #deserialized_response, included, #response_body, #response_object

Methods included from Modules::DataType

#get_data_type, #get_data_type_class, included

Methods included from Modules::ConfigAttributes

#adapter, #adapter=, #adapter_for_url, #auth, #auth=, #auth_for_url, #config, #default_attributes, #default_attributes=, #default_attributes_for_url, #faraday_options, #faraday_options=, #faraday_options_for_url, #headers, #headers=, #headers_for_url, #hr_config, #hr_config=, included, #namespace, #namespace=, #namespace_for_url

Constructor Details

#initialize(opts = {}) ⇒ HyperResource

Create a new HyperResource, given a hash of options. These options include:

[root] The root URL of the resource.

[auth] Authentication information. Currently only {basic: ['key', 'secret']} is supported.

[namespace] Class or class name, into which resources should be instantiated.

[headers] Headers to send along with requests for this resource (as well as its eventual child resources, if any).

[faraday_options] Configuration passed to Faraday::Connection.initialize, such as {request: {timeout: 30}}.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/hyper_resource.rb', line 56

def initialize(opts={})
  self.root = opts[:root] if opts[:root]
  self.href = opts[:href] if opts[:href]

  self.hr_config = self.class.hr_config.clone

  self.adapter         = opts[:adapter]         if opts[:adapter]
  self.faraday_options = opts[:faraday_options] if opts[:faraday_options]
  self.auth            = opts[:auth]            if opts[:auth]

  self.headers = DEFAULT_HEADERS.
                   merge(self.class.headers || {}).
                   merge(opts[:headers]     || {})

  self.namespace = opts[:namespace] if opts[:namespace]
  if !self.namespace && self.class != HyperResource
    self.namespace = self.class.namespace || self.class.to_s
  end

  ## There's a little acrobatics in getting Attributes, Links, and Objects
  ## into the correct subclass.
  if self.class != HyperResource
    if self.class::Attributes == HyperResource::Attributes
      Object.module_eval(
        "class #{self.class}::Attributes < HyperResource::Attributes; end"
      )
    end
    if self.class::Links == HyperResource::Links
      Object.module_eval(
        "class #{self.class}::Links < HyperResource::Links; end"
      )
    end
    if self.class::Objects == HyperResource::Objects
      Object.module_eval(
        "class #{self.class}::Objects < HyperResource::Objects; end"
      )
    end
  end

  self.attributes = self.class::Attributes.new(self)
  self.links      = self.class::Links.new(self)
  self.objects    = self.class::Objects.new(self)
  self.loaded     = false
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args) ⇒ Object

method_missing will load this resource if not yet loaded, then attempt to delegate to attributes, then objects, then links. Override with extreme care.

Raises:

  • (NoMethodError) 


189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/hyper_resource.rb', line 189

def method_missing(method, *args)
  ## If not loaded, load and retry.
  unless loaded
    return self.get.send(method, *args)
  end


  ## Otherwise, try to match against attributes, then objects, then links.
  method = method.to_s
  if method[-1,1] == '='
    return attributes[method[0..-2]] = args.first if attributes && attributes.has_key?(method[0..-2])
  else
    return attributes[method] if attributes && attributes.has_key?(method.to_s)
    return objects[method] if objects && objects[method]
    if links && links[method]
      if args.count > 0
        return links[method].where(*args)
      else
        return links[method]
      end
    end
  end

  raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
end

Class Method Details

.new_from(args) ⇒ Object

Creates a new resource given args :link, :resource, :href, :response, :url, and :body. Either :link or (:resource and :href and :url) are required.



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/hyper_resource.rb', line 106

def self.new_from(args)
  link = args[:link]
  resource = args[:resource] || link.resource
  href = args[:href] || link.href rescue nil
  url = args[:url] || URI.join(resource.root, href || '')
  response = args[:response]
  body = args[:body] || {}

  old_rsrc = resource
  new_class = old_rsrc.get_data_type_class(:resource => old_rsrc,
                                           :link => link,
                                           :url => url,
                                           :response => response,
                                           :body => body)
  new_rsrc = new_class.new(:root => old_rsrc.root,
                           :href => href)
  new_rsrc.hr_config = old_rsrc.hr_config.clone
  new_rsrc.response = response
  new_rsrc.body = body
  new_rsrc.adapter.apply(body, new_rsrc)
  new_rsrc.loaded = true
  new_rsrc
end

.user_agent ⇒ Object 



232
233
234
 
# File 'lib/hyper_resource.rb', line 232

def self.user_agent # @private
  "HyperResource #{HyperResource::VERSION}"
end

Instance Method Details

#[](i) ⇒ Object

Returns the ith object in the first collection of objects embedded in this resource. Returns nil on failure.



172
173
174
175
 
# File 'lib/hyper_resource.rb', line 172

def [](i)
  get unless loaded
  self.objects.first[1][i] rescue nil
end

#changed?(*args) ⇒ Boolean

Returns true if one or more of this object's attributes has been reassigned.

Returns:

  • (Boolean) 


138
139
140
 
# File 'lib/hyper_resource.rb', line 138

def changed?(*args)
  attributes.changed?(*args)
end

#create(attrs) ⇒ Object 



98
99
100
101
102
 
# File 'lib/hyper_resource/modules/http.rb', line 98

def create(attrs)
  _hr_deprecate('HyperResource#create is deprecated. Please use '+
                '#post instead.')
  to_link.post(attrs)
end

#delete ⇒ Object

Performs a DELETE request to this resource's URL. Returns a new resource representing the response.



77
78
79
 
# File 'lib/hyper_resource/modules/http.rb', line 77

def delete
  to_link.delete
end

#delete_response ⇒ Object

Performs a DELETE request to this resource's URL. Returns a Faraday::Response object representing the response.



83
84
85
 
# File 'lib/hyper_resource/modules/http.rb', line 83

def delete_response
  to_link.delete_response
end

#each(&block) ⇒ Object

Iterates over the objects in the first collection of embedded objects in this resource.



179
180
181
182
 
# File 'lib/hyper_resource.rb', line 179

def each(&block)
  get unless loaded
  self.objects.first[1].each(&block) rescue nil
end

#get ⇒ Object

Performs a GET request to this resource's URL, and returns a new resource representing the response.



21
22
23
 
# File 'lib/hyper_resource/modules/http.rb', line 21

def get
  to_link.get
end

#get_response ⇒ Object

Performs a GET request to this resource's URL, and returns a Faraday::Response object representing the response.



27
28
29
 
# File 'lib/hyper_resource/modules/http.rb', line 27

def get_response
  to_link.get_response
end

#incoming_body_filter(attr_hash) ⇒ Object

incoming_body_filter filters a hash of attribute keys and values on their way from a response body to a HyperResource. Override this in a subclass of HyperResource to implement filters on incoming data.



148
149
150
 
# File 'lib/hyper_resource.rb', line 148

def incoming_body_filter(attr_hash)
  attr_hash
end

#inspect ⇒ Object 



226
227
228
229
230
 
# File 'lib/hyper_resource.rb', line 226

def inspect # @private
  "#<#{self.class}:0x#{"%x" % self.object_id} @root=#{self.root.inspect} "+
  "@href=#{self.href.inspect} @loaded=#{self.loaded} "+
  "@namespace=#{self.namespace.inspect} ...>"
end

#new_from(args) ⇒ Object 



131
132
133
 
# File 'lib/hyper_resource.rb', line 131

def new_from(args)
  self.class.new_from(args)
end

#outgoing_body_filter(attr_hash) ⇒ Object

outgoing_body_filter filters a hash of attribute keys and values on their way from a HyperResource to a request body. Override this in a subclass of HyperResource to implement filters on outgoing data.



155
156
157
 
# File 'lib/hyper_resource.rb', line 155

def outgoing_body_filter(attr_hash)
  attr_hash
end

#outgoing_uri_filter(attr_hash) ⇒ Object

outgoing_uri_filter filters a hash of attribute keys and values on their way from a HyperResource to a URL. Override this in a subclass of HyperResource to implement filters on outgoing URI parameters.



163
164
165
 
# File 'lib/hyper_resource.rb', line 163

def outgoing_uri_filter(attr_hash)
  attr_hash
end

#patch(*args) ⇒ Object

Performs a PATCH request to this resource's URL, sending attributes.changed_attributes as a request body unless an attrs Hash is given. Returns a new resource representing the response.



63
64
65
 
# File 'lib/hyper_resource/modules/http.rb', line 63

def patch(*args)
  self.to_link.patch(*args)
end

#patch_response(*args) ⇒ Object

Performs a PATCH request to this resource's URL, sending attributes.changed_attributes as a request body unless an attrs Hash is given. Returns a Faraday::Response object representing the response.



71
72
73
 
# File 'lib/hyper_resource/modules/http.rb', line 71

def patch_response(*args)
  self.to_link.patch_response(*args)
end

#post(attrs = nil) ⇒ Object

Performs a POST request to this resource's URL, sending all of attributes as a request body unless an attrs Hash is given. Returns a new resource representing the response.



34
35
36
 
# File 'lib/hyper_resource/modules/http.rb', line 34

def post(attrs=nil)
  to_link.post(attrs)
end

#post_response(attrs = nil) ⇒ Object

Performs a POST request to this resource's URL, sending all of attributes as a request body unless an attrs Hash is given. Returns a Faraday::Response object representing the response.



41
42
43
 
# File 'lib/hyper_resource/modules/http.rb', line 41

def post_response(attrs=nil)
  to_link.post_response(attrs)
end

#put(*args) ⇒ Object

Performs a PUT request to this resource's URL, sending all of attributes as a request body unless an attrs Hash is given. Returns a new resource representing the response.



48
49
50
 
# File 'lib/hyper_resource/modules/http.rb', line 48

def put(*args)
  to_link.put(*args)
end

#put_response(*args) ⇒ Object

Performs a PUT request to this resource's URL, sending all of attributes as a request body unless an attrs Hash is given. Returns a Faraday::Response object representing the response.



55
56
57
 
# File 'lib/hyper_resource/modules/http.rb', line 55

def put_response(*args)
  to_link.put_response(*args)
end

#respond_to?(method, *args) ⇒ Boolean

respond_to? is patched to return true if method_missing would successfully delegate a method call to attributes, links, or objects.

Returns:

  • (Boolean) 


218
219
220
221
222
223
 
# File 'lib/hyper_resource.rb', line 218

def respond_to?(method, *args)
  return true if self.links && self.links.respond_to?(method)
  return true if self.attributes && self.attributes.respond_to?(method)
  return true if self.objects && self.objects.respond_to?(method)
  super
end

#to_link(args = {}) ⇒ Object

Creates a Link representing this resource. Used for HTTP delegation.



89
90
91
92
93
 
# File 'lib/hyper_resource/modules/http.rb', line 89

def to_link(args={})
  self.class::Link.new(self,
                       :href => args[:href] || self.href,
                       :params => args[:params] || self.attributes)
end

#update(*args) ⇒ Object 



105
106
107
108
109
 
# File 'lib/hyper_resource/modules/http.rb', line 105

def update(*args)
  _hr_deprecate('HyperResource#update is deprecated. Please use '+
                '#put or #patch instead.')
  to_link.put(*args)
end

#url ⇒ Object

Returns this resource's fully qualified URL. Returns nil when root or href are malformed.



10
11
12
13
14
15
16
 
# File 'lib/hyper_resource/modules/http.rb', line 10

def url
  begin
    URI.join(self.root, (self.href || '')).to_s
  rescue StandardError
    nil
  end
end

#user_agent ⇒ Object 



236
237
238
 
# File 'lib/hyper_resource.rb', line 236

def user_agent # @private
  self.class.user_agent
end