class HalClient::Representation

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

Constants

MISSING
NO_EMBED_FOUND

Attributes

hal_client[RW]

Return the HalClient used to retrieve this representation

properties[R]

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

Public Class Methods

new(options) click to toggle source

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

Public Instance Methods

==(other) click to toggle source
# 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
Also aliased as: eql?
[](name_or_rel) click to toggle source

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

# File lib/hal_client/representation.rb, line 163
def [](name_or_rel)
  item_key = name_or_rel
  fetch(item_key, nil)
end
as_enum() click to toggle source

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.

# File lib/hal_client/representation.rb, line 243
def as_enum
  Collection.new(self)
end
clone_for_use_in_different_thread() click to toggle source

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

# 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
eql?(other)
Alias for: ==
fetch(name_or_rel, default=MISSING, &default_proc) click to toggle source

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.
# 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") click to toggle source

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.

# 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
has_property?(name)
Alias for: property?
hash() click to toggle source
# File lib/hal_client/representation.rb, line 297
def hash
  if href
    href.hash
  else
    @raw.hash
  end
end
href() click to toggle source

Returns the URL of the resource this representation represents.

# File lib/hal_client/representation.rb, line 130
def href
  @href ||= raw
          .fetch("_links",{})
          .fetch("self",{})
          .fetch("href", AnonymousResourceLocator.new)
end
patch(data, options={}) click to toggle source

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`

# 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={}) click to toggle source

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`

# 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) click to toggle source

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.
# 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) click to toggle source

Returns true if this representation contains the specified property.

name - the name of the property to check

# File lib/hal_client/representation.rb, line 98
def property?(name)
  ensure_reified
  properties.key? name
end
Also aliased as: has_property?
put(data, options={}) click to toggle source

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`

# File lib/hal_client/representation.rb, line 77
def put(data, options={})
  @hal_client.put(href, data, options).tap do
    reset
  end
end
raw() click to toggle source

Returns raw parsed json.

# File lib/hal_client/representation.rb, line 317
def raw
  ensure_reified

  @raw
end
reset() click to toggle source

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

# 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) click to toggle source

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.

# File lib/hal_client/representation.rb, line 252
def to_enum(method=:each, *args, &blk)
  as_enum.to_enum(method, *args, &blk)
end
to_hal()
Alias for: to_json
to_json() click to toggle source

Returns the raw json representation of this representation

# File lib/hal_client/representation.rb, line 292
def to_json
  MultiJson.dump(raw)
end
Also aliased as: to_hal
to_s() click to toggle source

Returns a short human readable description of this representation.

# File lib/hal_client/representation.rb, line 287
def to_s
  "#<" + self.class.name + ": " + href.to_s  + ">"
end

Protected Instance Methods

ensure_reified() click to toggle source

Fetch the representation from origin server if that has not already happened.

# File lib/hal_client/representation.rb, line 334
def ensure_reified
  return if @raw
  (fail "unable to make requests due to missing hal client") unless hal_client
  (fail "unable to make requests due to missing href") unless @href

  response = hal_client.get(@href)

  unless response.is_a?(Representation)
    error_message = "Response body wasn't a valid HAL document:\n\n"
    error_message += response.body
    raise InvalidRepresentationError.new(error_message)
  end

  interpret response.raw
end
interpret(parsed_json) click to toggle source
# File lib/hal_client/representation.rb, line 350
def interpret(parsed_json)
  @raw = parsed_json

  interpreter = HalClient::Interpreter.new(parsed_json, hal_client)

  @properties = interpreter.extract_props

  @links_by_rel =
    interpreter
    .extract_links
    .reduce(Hash.new { |h,k| h[k] = Set.new }) { |links_tab, link|
      links_tab[link.literal_rel] << link
      links_tab[link.fully_qualified_rel] << link
      links_tab
    }
end