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
- NO_LINK_FOUND
- NO_RELATED_RESOURCE
Attributes
Return the HalClient
used to retrieve this representation
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
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
# 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
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
Returns set of all links in this representation.
# 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
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
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
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
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
# File lib/hal_client/representation.rb, line 297 def hash if href href.hash else @raw.hash end end
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
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
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
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
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
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
Returns raw parsed json.
# File lib/hal_client/representation.rb, line 317 def raw ensure_reified @raw end
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
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
Returns the raw json representation of this representation
# File lib/hal_client/representation.rb, line 292 def to_json MultiJson.dump(raw) end
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
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
# 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
# File lib/hal_client/representation.rb, line 367 def links_by_rel @links_by_rel || ensure_reified end