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.

Constant Summary collapse

RESERVED_PROPERTIES =

Collection of reserved properties tools.ietf.org/html/draft-kelly-json-hal-07#section-4.1

['_links', '_embedded'].freeze

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.



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/hal_client/representation.rb', line 25

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

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

  (fail InvalidRepresentationError, "Invalid HAL representation: #{raw.inspect}") if
    @raw && ! hashish?(@raw)
end

Instance Attribute Details

#hal_client ⇒ Object (readonly)

Internal: Returns the HalClient used to retrieve this representation



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

def hal_client
  @hal_client
end

Instance Method Details

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



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

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



138
139
140
141
 
# File 'lib/hal_client/representation.rb', line 138

def [](name_or_rel)
  item_key = name_or_rel
  fetch(item_key, nil)
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.



228
229
230
 
# File 'lib/hal_client/representation.rb', line 228

def as_enum
  Collection.new(self)
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.



125
126
127
128
129
130
131
132
 
# File 'lib/hal_client/representation.rb', line 125

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

#hash ⇒ Object 



260
261
262
263
264
265
266
 
# File 'lib/hal_client/representation.rb', line 260

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

#href ⇒ Object

Returns the URL of the resource this representation represents.



105
106
107
108
109
110
 
# File 'lib/hal_client/representation.rb', line 105

def href
  @href ||= raw
          .fetch("_links",{})
          .fetch("self",{})
          .fetch("href",nil)
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`



64
65
66
67
68
 
# File 'lib/hal_client/representation.rb', line 64

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`



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

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

#properties ⇒ Object

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`).



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

def properties
  raw.reject { |k, _| RESERVED_PROPERTIES.include? k }
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.



91
92
93
94
95
 
# File 'lib/hal_client/representation.rb', line 91

def property(name, default=MISSING, &default_proc)
  default_proc ||= ->(_){ default} if default != MISSING

  raw.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



74
75
76
 
# File 'lib/hal_client/representation.rb', line 74

def property?(name)
  raw.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`



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

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

#raw ⇒ Object

Internal: Returns parsed json document



280
281
282
283
284
285
286
287
 
# File 'lib/hal_client/representation.rb', line 280

def raw
  if @raw.nil? && @href
    (fail "unable to make requests due to missing hal client") unless hal_client
    @raw ||= hal_client.get(@href).raw
  end

  @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.



211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/hal_client/representation.rb', line 211

def raw_related_hrefs(link_rel, &default_proc)
  default_proc ||= ->(link_rel){
    raise KeyError, "No resources are related via `#{link_rel}`"
  }

  embedded = embedded(link_rel) { nil }
  linked = links.hrefs(link_rel) { nil }
  return default_proc.call(link_rel) if embedded.nil? and linked.nil?

  Array(linked) + Array(embedded).map(&: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.



168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/hal_client/representation.rb', line 168

def related(link_rel, options = {}, &default_proc)
  default_proc ||= ->(link_rel){
    raise KeyError, "No resources are related via `#{link_rel}`"
  }

  embedded = embedded(link_rel) { nil }
  linked = linked(link_rel, options) { nil }
  return default_proc.call(link_rel) if embedded.nil? and linked.nil?

  RepresentationSet.new (Array(embedded) + Array(linked))
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



147
148
149
150
151
152
153
 
# File 'lib/hal_client/representation.rb', line 147

def related?(link_rel)
  _ = related link_rel
  true

rescue KeyError
  false
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.



192
193
194
195
 
# File 'lib/hal_client/representation.rb', line 192

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.



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

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.



237
238
239
 
# File 'lib/hal_client/representation.rb', line 237

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



255
256
257
 
# File 'lib/hal_client/representation.rb', line 255

def to_json
  MultiJson.dump(raw)
end

#to_s ⇒ Object

Returns a short human readable description of this representation.



250
251
252
 
# File 'lib/hal_client/representation.rb', line 250

def to_s
  "#<" + self.class.name + ": " + (href || "ANONYMOUS")  + ">"
end