hal-client 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2feba4ea1ae2adc4762239ce875c4d4db3dad541
-  data.tar.gz: d0854b133f4ca25cb6ee21d10e2e7ba8e87d1480
+  metadata.gz: b2ff485e8014f90b3dff0a1dfce149d179dd9cd1
+  data.tar.gz: 52d3c6654272fbca9b80e69c4506182c524a1f46
 SHA512:
-  metadata.gz: 2ac5423a12091b050f6e27b93994b4a4914ab65a1702565b22ab724b45f73baa30a1896402ade0e62c024b1b2cbfacfde689143d41f9246d6900ddf6b723e4fa
-  data.tar.gz: be45454510e90beb073b2b9c8852e59718727ca91ff89cd1da6ef8ccb26d593b9d5a71d604fc02f7f2dad7453515340e8754dab217743bd79729763676ce52a9
+  metadata.gz: 5ab224fd14a959818ce357dc71926fee813f90cc1f583d94c547e0842fabffad307021f285924d9193056b29e3a2b2670f89e55b56626688fbe488a9fc2edbd5
+  data.tar.gz: 31932812f8c8472d4dfd55515e8781c3407627709daf6ce6a25a01c0d5a1064069986bc428c64bfeb85e54addc73911215e15d7035976f7b1da384c0be710f36

data/README.md

@@ -39,14 +39,16 @@ Once we have a representation we will want to navigate its links. This can be ac
     articles = blog.related("item")
     # => #<RepresentationSet:...>
 
-In the example above `item` is the link rel. The `#related` method extracts embedded representations and dereferences links with the specified rel. The resulting representations and packaged into a `HalClient::RepresentationSet`. `HalClient` always returns `RepresentationSet`s when following links, even when there is only one result as doing so tends to result in simpler client code.
+In the example above `item` is the link rel. The `#related` method extracts embedded representations and link hrefs with the specified rel. The resulting representations are packaged into a `HalClient::RepresentationSet`. `HalClient` always returns `RepresentationSet`s when following links, even when there is only one result. `RepresentationSet`s are `Enumerable` so they expose all your favorite methods like `#each`, `#map`, `#any?`, etc. `RepresentationSet`s expose a `#related` method which calls `#related` on each member of the set and then merges the results into a new representation set.
 
-`RepresentationSet`s are `Enumerable` so they expose all your favorite methods like `#each`, `#map`, `#any?`, etc. `RepresentationSet`s expose a `#related` method which calls `#related` on each member of the set and then merges the results into a new representation set.
-
-    authors = blog.related("author").related("item")
-    authors.first.property("name")
+    all_the_authors = blog.related("author").related("item")
+    all_the_authors.first.property("name")
     # => "Bob Smith"
 
+#### Request timing
+
+If the `author` relationship was a link in the above example the HTTP GET to retrieve Bob's representation from the server does not happen until the `#property` method is called. This lazy dereferencing allows for working with efficiently with larger relationship sets.
+
 #### CURIEs
 
 Links specified using a compact URI (or CURIE) as the rel are fully supported. They are accessed using the fully expanded version of the curie. For example, given a representations of an author:
@@ -94,6 +96,16 @@ If the API uses one or more a custom mime types we can specify that they be incl
     my_client.get("http://blog.me/")
     # => #<Representation: http://blog.me/>
 
+### Parsing presentations from clients
+
+HalClient can be used by servers of HAL APIs to interpret the bodies of requests. For example,
+
+    new_post_repr = HalClient::Representation.new(JSON.load(request.raw_post))
+    author = Author.by_href(new_post_repr.related('author').first.href)
+    new_post = Post.new title: new_post_repr['title'], author: author, #...
+
+Created this way the representation will not dereference any links (because it doesn't have a HalClient) but it will provide `HalClient::Representation`s of both embedded and linked resources.
+
 ## Contributing
 
 1. Fork it ( http://github.com/pezra/hal-client/fork )

data/lib/hal_client/representation.rb

@@ -13,12 +13,48 @@ class HalClient
 
     # Create a new Representation
     #
-    # hal_client - The HalClient instance to use when navigating.
     # parsed_json - A hash structure representing a single HAL
     #   document.
-    def initialize(hal_client, parsed_json)
-      @hal_client = hal_client
-      @raw = parsed_json
+    # href - The href of this representation.
+    # hal_client - The HalClient instance to use when navigating.
+    #
+    # Signature
+    #
+    #     initialize(hal_client, parsed_json)
+    #     initialize(parsed_json, hal_client)
+    #
+    # Initialize this representation with a parsed json document and a
+    # hal_client with which to make requests.
+    #
+    #     initialize(href, hal_client)
+    #
+    # Initialize this representation with an href and a hal_client
+    # with which to make requests. Any attempt to retrieve properties
+    # or related representations will result in the href being
+    # dereferenced.
+    #
+    #     initialize(href)
+    #
+    # Initialize this representation with an href. The representation
+    # will not be able to make requests to dereference itself but this
+    # can still be useful in test situations to maintain a uniform
+    # interface.
+    #
+    #     initialize(parse_json)
+    #
+    # Initializes representation that cannot request related
+    # representations.
+    #
+    def initialize(*args)
+      (raise ArgumentError, "wrong number of arguments (#{args.size} for 1 or 2)") if
+        args.size > 2
+
+      @raw = args.find {|it| (it.respond_to? :has_key?) &&  (it.respond_to? :fetch) }
+      @hal_client = args.find {|it| HalClient === it }
+
+      if @raw.nil?
+        @href = args.find {|it| it.respond_to? :downcase }
+      end
     end
 
     # Returns The value of the specified property or the specified
@@ -41,7 +77,7 @@ class HalClient
 
     # Returns the URL of the resource this representation represents.
     def href
-      link_section.fetch("self").fetch("href")
+      @href ||= link_section.fetch("self").fetch("href")
     end
 
     # Returns the value of the specified property or representations
@@ -92,8 +128,8 @@ class HalClient
         raise KeyError, "No resources are related via `#{link_rel}`"
       }
 
-      embedded = embedded(link_rel) rescue nil
-      linked = linked(link_rel, options) rescue nil
+      embedded = embedded_or_nil(link_rel)
+      linked = linked_or_nil(link_rel, options)
 
       if !embedded.nil? or !linked.nil?
         RepresentationSet.new (Array(embedded) + Array(linked))
@@ -115,20 +151,8 @@ class HalClient
     # Raises KeyError if the specified link does not exist
     #   and no default_proc is provided.
     def related_hrefs(link_rel, options={}, &default_proc)
-      default_proc ||= ->(link_rel){
-        raise KeyError, "No resources are related via `#{link_rel}`"
-      }
-
-      embedded = boxed embedded_section.fetch(link_rel, nil)
-      linked = boxed link_section.fetch(link_rel, nil)
-
-      if !embedded.nil? or !linked.nil?
-        Array(embedded).map{|it| it.fetch("_links").fetch("self").fetch("href") rescue nil} +
-          Array(linked).map{|it| it.fetch("href", nil) }.
-          compact
-      else
-        default_proc.call link_rel
-      end
+      related(link_rel, options, &default_proc).
+        map(&:href)
     end
 
     # Returns a short human readable description of this
@@ -138,10 +162,14 @@ class HalClient
     end
 
     protected
-    attr_reader :raw, :hal_client
+    attr_reader :hal_client
 
     MISSING = Object.new
 
+    def raw
+      @raw ||= hal_client.get(href)
+    end
+
     def link_section
       @link_section ||= fully_qualified raw.fetch("_links", {})
     end
@@ -156,12 +184,26 @@ class HalClient
       relations.map{|it| Representation.new hal_client, it}
     end
 
+    def embedded_or_nil(link_rel)
+      embedded link_rel
+
+    rescue KeyError
+      nil
+    end
+
     def linked(link_rel, options)
       relations = boxed link_section.fetch(link_rel)
 
       relations.
         map {|link| href_from link, options }.
-        map {|href| hal_client.get href }
+        map {|href| Representation.new href, hal_client }
+    end
+
+    def linked_or_nil(link_rel, options)
+      linked link_rel, options
+
+    rescue KeyError
+      nil
     end
 
 

data/lib/hal_client/version.rb

@@ -1,3 +1,3 @@
 class HalClient
-  VERSION = "1.3.1"
+  VERSION = "1.4.0"
 end

data/spec/hal_client/representation_spec.rb

@@ -3,12 +3,11 @@ require_relative "../spec_helper"
 require "hal_client/representation"
 
 describe HalClient::Representation do
-  describe ".new" do
+  describe ".new(a_hal_client, a_parsed_json_doc)" do
     let!(:return_val) { described_class.new(a_client, MultiJson.load(raw_repr)) }
     describe "return_val" do
       subject { return_val }
       it { should be_kind_of described_class }
-
     end
   end
 
@@ -231,3 +230,27 @@ HAL
     }
   end
 end
+
+describe HalClient::Representation, "w/o hal_client" do
+  subject(:repr) { described_class.new(MultiJson.load(raw_repr)) }
+
+  specify { expect(subject.href).to eq "http://example.com/foo" }
+  specify { expect(subject.related_hrefs "link1").to include "http://example.com/bar" }
+  specify { expect(subject.related("link1").first.href).to eq "http://example.com/bar" }
+  specify { expect(subject.related("embed1").first.href).to eq "http://example.com/baz" }
+
+
+  let(:raw_repr) { <<-HAL }
+{ "prop1": 1
+  ,"_links": {
+    "self": { "href": "http://example.com/foo" }
+    ,"link1": { "href": "http://example.com/bar" }
+  }
+  ,"_embedded": {
+    "embed1": {
+      "_links": { "self": { "href": "http://example.com/baz" }}
+    }
+  }
+}
+  HAL
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hal-client
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Peter Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-14 00:00:00.000000000 Z
+date: 2014-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client