ocean-rails 3.6.1 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9b1ebefcaefe0c03253d9b06bda0853e2e989aee
-  data.tar.gz: a1403dc8927f967419e22cf7007893a0fbeff4be
+  metadata.gz: 77809e9f1822672d4c90aeb4a2409d237acab4c0
+  data.tar.gz: 83438c0ffeb2603067f0f05d8ffb0a29e8926d63
 SHA512:
-  metadata.gz: 4eca93e9da87b0baad368541f08d7c9673fd9bc59ada298be8c3e0a0b8a83322b0b11df9f5f3d0d09041541abf380d93efae65772f64b3d84346a6b1cfb0c8fe
-  data.tar.gz: 5b44ae5a565e4aa376c2f07b01500479ad7f01f43d57a3840efae99f38678416a287e102754dbc121b859b26f8b0304a610759ff28a1bfa9412042f97976d7c4
+  metadata.gz: f053a42f438109874ac1997c974b9528cada2c4e2bdb1bfe0bfe87ab9279f60eedfe046840704b27724836bf0df9fc559d5a0536f8c068cc490c7b98b29dc773
+  data.tar.gz: 4494b55bfe4aed431f141b5789eb68debb938b97c1269263096e4f377805529f791c76cabe05983c7b1bc36e24511f25359bfd232e4c9c36393c9410a2649787

data/lib/ocean/api_remote_resource.rb

@@ -48,19 +48,41 @@ class Api
   #   Api::RemoteResource.get!("foo")        returns a new RemoteResource or raises an error
   #   Api::RemoteResource.new("foo").get!    returns the RemoteResource or raises an error
   #
-  # #post, #post!, #put, #put!, #delete, and #delete! are also available.
-  #
-  # If get or get! retrieve an Ocean collection, they will return an array of RemoteResources.
-  #
   # +thing.get!+ returns the RemoteResource if successful. If not, raises an exception.
   # +thing.get+ does the same, but always returns the RemoteResource. The remote resource
   # can be examined to see its status.
   #
+  # Hyperlinks can be specified to avoid hardcoding API URIs. This is essential. Simply specify
+  # the hyperlink as the first parameter to the instance versions of the HTTP accessors:
+  #
+  #   x = Api::RemoteResource.new("http://foo.com/x")
+  #   x.get(:creator)
+  #   x.get!(:creator)['username']
+  #   x.put(:confirm, body: {x:2, y:3})
+  #   x.post(:bars, body: {username: "Bl0feld", password: "SPECTRE"})
+  #   x.delete(:expired)
+  #
+  # Note the difference between:
+  #
+  #   x.put(body: {x:2, y:3})
+  #   x.put(:self, body: {x:2, y:3})
+  #   x.put(:confirm, body: {x:2, y:3})
+  #
+  # The first two are logically equivalent: they both make a PUT request to x itself,
+  # though in the second case, the self hyperlink is explicit (the first arg defaults to
+  # :self). The third case sends a PUT request to x's hyperlink :confirm. From this follows
+  # that the following also are equivalent:
+  #
+  #   x.get
+  #   x.get(:self)
+  #
+  # #post, #post!, #put, #put!, #delete, and #delete! are also available.
+  #
   # Exceptions:
   #
-  #  GetFailed          raised when the GET to obtain the remote resource has failed.
-  #  UnparseableJson    raised when the response body doesn't parse as JSON.
-  #  JsonIsNoResource   raised when the structure of the parsed JSON body is not a resource.
+  #   GetFailed          raised when the GET to obtain the remote resource has failed.
+  #   UnparseableJson    raised when the response body doesn't parse as JSON.
+  #   JsonIsNoResource   raised when the structure of the parsed JSON body is not a resource.
   #
   # To parse as a resource, the JSON must be a wrapped Ocean resource of this format:
   #
@@ -79,8 +101,12 @@ class Api
   #
   # To refresh a resource using a conditional GET:
   #
-  #  +thing.refresh+
-  #  +thing.refresh!+
+  #   thing.refresh
+  #   thing.refresh!
+  #
+  # #refresh returns the resource itself, so you can do
+  #
+  #   thing.refresh['updated_at']
   #
   # NB: this class can also be used to fetch any JSON data. E.g.:
   #
@@ -91,6 +117,9 @@ class Api
   # +nil+, you can always chack +#status+, +#status_message+, and/or +#headers+ to determine what
   # went wrong. After fetching non-resource data, +#present?+ will always be false.
   #
+  # TODO: 1. If .get or .get! retrieve an Ocean collection, let them return an array of RemoteResources.
+  #       2. Implement refresh.
+  #
   class RemoteResource
 
   	attr_reader :uri, :content_type, :retries, :backoff_time, :backoff_rate, :backoff_max
@@ -123,26 +152,6 @@ class Api
     end
 
 
-    def self.get!(*args)
-      _retrieve new(*args)
-    end
-
-    def get!
-      RemoteResource._retrieve self unless present?
-      self
-    end
-
-    def self.get(*args)
-      rr = new(*args)
-      rr.get! rescue nil
-      rr
-    end
-
-    def get
-      get! rescue nil
-      self
-    end
-
     def [](key)
       get!
       resource[key]
@@ -165,18 +174,108 @@ class Api
     end
 
 
+    class PostFailed < StandardError; end
     class GetFailed < StandardError; end
+    class PutFailed < StandardError; end
+    class DeleteFailed < StandardError; end
     class UnparseableJson < StandardError; end
     class JsonIsNoResource < StandardError; end
 
 
+    def self.get!(*args)
+      _retrieve new(*args)
+    end
+
+    def self.get(*args)
+      rr = new(*args)
+      rr.get! rescue nil
+      rr
+    end
+
+
+    def get!(hlink=nil)
+      RemoteResource._retrieve self unless present?
+      hlink = hlink.to_s if hlink
+      if !hlink || hlink == 'self' 
+        self
+      else
+        RemoteResource.get!(hyperlink[hlink]['href'])
+      end
+    end
+
+    def get(hlink=nil)
+      get! rescue nil
+      hlink = hlink.to_s if hlink
+      if !hlink || hlink == 'self' 
+        self
+      else
+        RemoteResource.get(hyperlink[hlink]['href'])
+      end
+    end
+
+
+    def put!(hlink=nil, body: {})
+      get!
+      hlink = hlink.to_s if hlink
+      if !hlink || hlink == 'self' 
+        _modify(body)
+        self
+      else
+        hl_res = RemoteResource.new(self.hyperlink[hlink]['href'])
+        hl_res.send :_modify, body
+        hl_res
+      end
+    end
+
+    def put(hlink=nil, body: {})
+      get
+      hlink = hlink.to_s if hlink
+      if !hlink || hlink == 'self' 
+        _modify(body) rescue nil
+        self
+      else
+        hl_res = RemoteResource.new(self.hyperlink[hlink]['href'])
+        hl_res.send :_modify, body
+        hl_res
+      end
+    end
+
+
+    def post!(hlink=nil, body: {})
+      get!
+      hlink = (hlink || 'self').to_s
+      _create(hyperlink[hlink]['href'], body)
+    end
+
+    def post(hlink=nil, body: {})
+      get
+      hlink = (hlink || 'self').to_s
+      _create(hyperlink[hlink]['href'], body) rescue nil
+    end
+
+
+    def delete!(hlink=nil)
+      get!
+      hlink = (hlink || 'self').to_s
+      _destroy(hyperlink[hlink]['href'])
+      self
+    end
+
+    def delete(hlink=nil)
+      get
+      hlink = (hlink || 'self').to_s
+      _destroy(hyperlink[hlink]['href']) rescue nil
+      self
+    end
+
+
     private
 
     attr_accessor :present
     attr_writer :raw, :resource, :resource_type, :status, :headers, :status_message
 
 
-    def self._retrieve(rr)
+    def self._credentials(rr)
       if rr.credentials.present? && rr.credentials != Api.credentials(API_USER, API_PASSWORD)
         credentials = rr.credentials
         token = rr.x_api_token
@@ -184,6 +283,12 @@ class Api
         credentials = nil
         token = rr.x_api_token || Api.service_token
       end
+      [credentials, token]
+    end
+
+
+    def self._retrieve(rr)
+      credentials, token = _credentials(rr)
       response = Api.request rr.uri, :get, headers: {}, credentials: credentials, x_api_token: token,
                              retries: rr.retries, backoff_time: rr.backoff_time, backoff_rate: rr.backoff_rate, 
                              backoff_max: rr.backoff_max
@@ -203,16 +308,9 @@ class Api
 
     def _setup(body, response)
       self.raw = body
-      raise JsonIsNoResource unless raw.is_a? Hash
-      raise JsonIsNoResource unless raw.size == 1
-      resource_type, value = raw.to_a.first
-      raise JsonIsNoResource unless value.is_a? Hash
-      raise JsonIsNoResource unless value['_links'].is_a? Hash
-      raise JsonIsNoResource unless value['_links']['self'].is_a? Hash
-      raise JsonIsNoResource unless value['_links']['self']['href'].is_a? String
-      raise JsonIsNoResource unless value['_links']['self']['type'].is_a? String
-      self.resource = value
-      self.resource_type = resource_type
+      type, resource = verify_resource body
+      self.resource = resource
+      self.resource_type = type
       self.status = response.status
       self.status_message = response.message
       self.headers = response.headers
@@ -220,5 +318,72 @@ class Api
     end
 
 
+    def verify_resource(json)
+      raise JsonIsNoResource unless json.is_a? Hash
+      raise JsonIsNoResource unless json.size == 1
+      resource_type, attributes = json.to_a.first
+      raise JsonIsNoResource unless attributes.is_a? Hash
+      raise JsonIsNoResource unless attributes['_links'].is_a? Hash
+      raise JsonIsNoResource unless attributes['_links']['self'].is_a? Hash
+      raise JsonIsNoResource unless attributes['_links']['self']['href'].is_a? String
+      raise JsonIsNoResource unless attributes['_links']['self']['type'].is_a? String
+      [resource_type, attributes]
+    end
+
+
+    def _modify(body)
+      credentials, token = RemoteResource._credentials(self)
+      response = Api.request uri, :put, headers: {}, body: body,
+                             credentials: credentials, x_api_token: token,
+                             retries: retries, backoff_time: backoff_time, backoff_rate: backoff_rate, 
+                             backoff_max: backoff_max
+      raise PutFailed unless response.success?
+      begin
+        self.raw = response.body
+      rescue JSON::ParserError
+        raise UnparseableJson
+      end
+      type, resource = verify_resource(response.body) rescue return
+      return if resource_type && type != resource_type
+      self.resource = resource
+      self.resource_type = type
+      self.status = response.status
+      self.status_message = response.message
+      self.headers = response.headers
+      self.present = true
+    end
+
+
+    def _create(post_uri, body)
+      credentials, token = RemoteResource._credentials(self)
+      response = Api.request post_uri, :post, headers: {}, body: body,
+                             credentials: credentials, x_api_token: token,
+                             retries: retries, backoff_time: backoff_time, backoff_rate: backoff_rate, 
+                             backoff_max: backoff_max
+      raise PostFailed unless response.success?
+      begin
+        raw = response.body
+      rescue JSON::ParserError
+        raise UnparseableJson
+      end
+      type, resource = verify_resource(response.body)
+      created = RemoteResource.new(post_uri)
+      created.send :_setup, raw, response
+      created
+    end
+
+
+    def _destroy(delete_uri)
+      credentials, token = RemoteResource._credentials(self)
+      response = Api.request delete_uri, :delete, headers: {},
+                             credentials: credentials, x_api_token: token,
+                             retries: retries, backoff_time: backoff_time, backoff_rate: backoff_rate, 
+                             backoff_max: backoff_max
+      self.status = response.status
+      self.status_message = response.message
+      self.headers = response.headers
+      raise DeleteFailed unless response.success?
+    end
+
   end
 end

data/lib/ocean/ocean_application_controller.rb

@@ -83,25 +83,6 @@ module OceanApplicationController
   end
 
 
-  # #
-  # # Requires the request to be conditional: it must have an +If-None-Match+ and/or an
-  # # +If-Modified-Since+ HTTP header. If the request isn't conditional, a 428 error is
-  # # returned. The body will be a standard API error message, with two strings:
-  # # <tt>"Precondition Required"</tt> and <tt>"If-None-Match and/or If-Modified-Since missing"</tt>.
-  # #
-  # def require_conditional
-  #   if request.headers['If-None-Match'].blank? && request.headers['If-Modified-Since'].blank?
-  #     render_api_error 428, "Precondition Required", 
-  #                           "If-None-Match and/or If-Modified-Since missing"
-  #     #expires_in 0, must_revalidate: true
-  #     expires_now
-  #     false
-  #   else
-  #     true
-  #   end
-  # end
-
-  
   #
   # Updates +created_by+ and +updated_by+ to the ApiUser for which the current request
   # is authorised. The attributes can be declared either String (recommended) or

data/lib/ocean/version.rb

@@ -1,3 +1,3 @@
 module Ocean
-  VERSION = "3.6.1"
+  VERSION = "3.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ocean-rails
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.7.0
 platform: ruby
 authors:
 - Peter Bengtson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-02 00:00:00.000000000 Z
+date: 2014-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus