Class: HalClient::Representation

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/hal_client/representation.rb

Overview

HAL representation of a single resource. Provides access to properties, links and embedded representations.

Operations on a representation are not thread-safe. If you’d like to use representations in a threaded environment, consider using the method #clone_for_use_in_different_thread to create a copy for each new thread

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Representation

Create a new Representation

options - name parameters

:parsed_json - A hash structure representing a single HAL
  document.
:href - The href of this representation.
:hal_client - The HalClient instance to use when navigating.



41
42
43
44
45
46
47
48
49
 
# File 'lib/hal_client/representation.rb', line 41

def initialize(options)
  @hal_client = options[:hal_client]
  @href = options[:href]

  interpret options[:parsed_json] if options[:parsed_json]

  (fail ArgumentError, "Either parsed_json or href must be provided") if
    @raw.nil? && @href.nil?
end

Instance Attribute Details

#hal_client ⇒ Object

Return the HalClient used to retrieve this representation



324
325
326
 
# File 'lib/hal_client/representation.rb', line 324

def hal_client
  @hal_client
end

#properties ⇒ Object (readonly)

Returns a Hash including the key-value pairs of all the properties

in the resource. It does not include HAL's reserved
properties (`_links` and `_embedded`).



127
128
129
 
# File 'lib/hal_client/representation.rb', line 127

def properties
  @properties
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql? 



305
306
307
308
309
310
311
312
313
 
# File 'lib/hal_client/representation.rb', line 305

def ==(other)
  if href && other.respond_to?(:href)
    href == other.href
  elsif other.respond_to?(:raw)
    @raw == other.raw
  else
    false
  end
end

#[](name_or_rel) ⇒ Object

Returns the value of the specified property or representations

of resources related via the specified link rel or nil

name_or_rel - The name of property or link rel of interest



163
164
165
166
 
# File 'lib/hal_client/representation.rb', line 163

def [](name_or_rel)
  item_key = name_or_rel
  fetch(item_key, nil)
end

#all_links ⇒ Object

Returns set of all links in this representation.



257
258
259
260
261
262
263
264
 
# File 'lib/hal_client/representation.rb', line 257

def all_links
  links_by_rel
    .reduce(Set.new) { |result, kv|
      _,links = *kv
      links.each { |l| result << l }
      result
    }
end

#as_enum ⇒ Object

Returns an Enumerable of the items in this collection resource if this is an rfc 6573 collection.

Raises HalClient::NotACollectionError if this is not a collection resource.



243
244
245
 
# File 'lib/hal_client/representation.rb', line 243

def as_enum
  Collection.new(self)
end

#clone_for_use_in_different_thread ⇒ Object

Returns a copy of this instance that is safe to use in threaded environments



53
54
55
56
57
58
59
 
# File 'lib/hal_client/representation.rb', line 53

def clone_for_use_in_different_thread
  clone.tap do |c|
    if c.hal_client
      c.hal_client = c.hal_client.clone_for_use_in_different_thread
    end
  end
end

#fetch(name_or_rel, default = MISSING, &default_proc) ⇒ Object

Returns the value of the specified property or representations

of resources related via the specified link rel or the
specified default value.

name_or_rel - The name of property or link rel of interest default - an optional object that should be return if the

specified property or link does not exist

default_proc - an option proc that will be called with ‘name`

to produce default value if the specified property or link does not
exist

Raises KeyError if the specified property or link does not exist

and no default nor default_proc is provided.



150
151
152
153
154
155
156
157
 
# File 'lib/hal_client/representation.rb', line 150

def fetch(name_or_rel, default=MISSING, &default_proc)
  item_key = name_or_rel
  default_proc ||= ->(_){default} if default != MISSING

  property(item_key) {
    related(item_key, &default_proc)
  }
end

#form(form_id = "default") ⇒ Object

Returns the specified ‘Form`

form_id - the string or symbol id of the form of interest. Default: ‘“default”`

Raises ‘KeyError` if the specified form doesn’t exist.



271
272
273
274
275
 
# File 'lib/hal_client/representation.rb', line 271

def form(form_id="default")
  parsed_form_json = property("_forms").fetch(form_id.to_s)

  Form.new(parsed_form_json, hal_client)
end

#hash ⇒ Object 



297
298
299
300
301
302
303
 
# File 'lib/hal_client/representation.rb', line 297

def hash
  if href
    href.hash
  else
    @raw.hash
  end
end

#href ⇒ Object

Returns the URL of the resource this representation represents.



130
131
132
133
134
135
 
# File 'lib/hal_client/representation.rb', line 130

def href
  @href ||= raw
          .fetch("_links",{})
          .fetch("self",{})
          .fetch("href", AnonymousResourceLocator.new)
end

#patch(data, options = {}) ⇒ Object

Patchs a ‘Representation` or `String` to this resource. Causes this representation to be reloaded the next time it is used.

data - a ‘String` or an object that responds to `#to_hal` options - set of options to pass to `HalClient#patch`



88
89
90
91
92
 
# File 'lib/hal_client/representation.rb', line 88

def patch(data, options={})
  @hal_client.patch(href, data, options).tap do
    reset
  end
end

#post(data, options = {}) ⇒ Object

Posts a ‘Representation` or `String` to this resource. Causes this representation to be reloaded the next time it is used.

data - a ‘String` or an object that responds to `#to_hal` options - set of options to pass to `HalClient#post`



66
67
68
69
70
 
# File 'lib/hal_client/representation.rb', line 66

def post(data, options={})
  @hal_client.post(href, data, options).tap do
    reset
  end
end

#property(name, default = MISSING, &default_proc) ⇒ Object

Returns The value of the specified property or the specified

default value.

name - The name of property of interest default - an optional object that should be return if the

specified property does not exist

default_proc - an option proc that will be called with ‘name`

to produce default value if the specified property does not
exist

Raises KeyError if the specified property does not exist

and no default nor default_proc is provided.



116
117
118
119
120
121
122
 
# File 'lib/hal_client/representation.rb', line 116

def property(name, default=MISSING, &default_proc)
  ensure_reified

  default_proc ||= ->(_){ default} if default != MISSING

  properties.fetch(name.to_s, &default_proc)
end

#property?(name) ⇒ Boolean Also known as: has_property?

Returns true if this representation contains the specified property.

name - the name of the property to check

Returns:

  • (Boolean) 


98
99
100
101
 
# File 'lib/hal_client/representation.rb', line 98

def property?(name)
  ensure_reified
  properties.key? name
end

#put(data, options = {}) ⇒ Object

Puts a ‘Representation` or `String` to this resource. Causes this representation to be reloaded the next time it is used.

data - a ‘String` or an object that responds to `#to_hal` options - set of options to pass to `HalClient#put`



77
78
79
80
81
 
# File 'lib/hal_client/representation.rb', line 77

def put(data, options={})
  @hal_client.put(href, data, options).tap do
    reset
  end
end

#raw ⇒ Object

Returns raw parsed json.



317
318
319
320
321
 
# File 'lib/hal_client/representation.rb', line 317

def raw
  ensure_reified

  @raw
end

#raw_related_hrefs(link_rel, &default_proc) ⇒ Object

Returns values of the ‘href` member of links and the URL of embedded representations related via the specified link rel. The only difference between this and `#related_hrefs` is that this method makes no attempt to expand templated links. For templated links the returned collection will include the template pattern as encoded in the HAL document.

link_rel - The link rel of interest default_proc - an option proc that will be called with ‘name`

to produce default value if the specified property or link does not
exist

Raises KeyError if the specified link does not exist

and no default_proc is provided.



230
231
232
233
234
235
236
 
# File 'lib/hal_client/representation.rb', line 230

def raw_related_hrefs(link_rel, &default_proc)
  default_proc ||= NO_RELATED_RESOURCE

  links_by_rel
    .fetch(link_rel) { return default_proc.call(link_rel) }
    .map { |l| l.raw_href }
end

#related(link_rel, options = {}, &default_proc) ⇒ Object

Returns representations of resources related via the specified

link rel or the specified default value.

link_rel - The link rel of interest options - optional keys and values with which to expand any

templated links that are encountered

default_proc - an option proc that will be called with ‘name`

to produce default value if the specified property or link does not
exist

Raises KeyError if the specified link does not exist

and no default_proc is provided.



189
190
191
192
193
194
195
196
197
 
# File 'lib/hal_client/representation.rb', line 189

def related(link_rel, options = {}, &default_proc)
  default_proc ||= NO_RELATED_RESOURCE

  related = links_by_rel
            .fetch(link_rel) { return default_proc.call(link_rel) }
            .map { |l| l.target(options) }

  RepresentationSet.new(related)
end

#related?(link_rel) ⇒ Boolean Also known as: has_related?

Returns true if this representation contains a link (including embedded links) whose rel is ‘link_rel`.

link_rel - The link rel of interest

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/hal_client/representation.rb', line 172

def related?(link_rel)
  links_by_rel.key?(link_rel)
end

#related_hrefs(link_rel, options = {}, &default_proc) ⇒ Object

Returns urls of resources related via the specified

link rel or the specified default value.

link_rel - The link rel of interest options - optional keys and values with which to expand any

templated links that are encountered

default_proc - an option proc that will be called with ‘name`

to produce default value if the specified property or link does not
exist

Raises KeyError if the specified link does not exist

and no default_proc is provided.



211
212
213
214
 
# File 'lib/hal_client/representation.rb', line 211

def related_hrefs(link_rel, options={}, &default_proc)
  related(link_rel, options, &default_proc).
    map(&:href)
end

#reset ⇒ Object

Resets this representation such that it will be requested from the upstream on it’s next use.



280
281
282
283
 
# File 'lib/hal_client/representation.rb', line 280

def reset
  @href = href # make sure we have the href
  @raw = nil
end

#to_enum(method = :each, *args, &blk) ⇒ Object

Returns an Enumerator of the items in the collection resource if this is an rfc 6573 collection.

Raises HalClient::NotACollectionError if this is not a collection resource.



252
253
254
 
# File 'lib/hal_client/representation.rb', line 252

def to_enum(method=:each, *args, &blk)
  as_enum.to_enum(method, *args, &blk)
end

#to_json ⇒ Object Also known as: to_hal

Returns the raw json representation of this representation



292
293
294
 
# File 'lib/hal_client/representation.rb', line 292

def to_json
  MultiJson.dump(raw)
end

#to_s ⇒ Object

Returns a short human readable description of this representation.



287
288
289
 
# File 'lib/hal_client/representation.rb', line 287

def to_s
  "#<" + self.class.name + ": " + href.to_s  + ">"
end