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