ocean-rails 3.8.2 → 3.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3bf3f4a3ed2f020535fd3ae4ab640d2ccf38b8dd
-  data.tar.gz: e60a238e5ea0f8ecb7637695e96e152f50cc3f69
+  metadata.gz: b8016bcce74120528096b71766f7756e0f02b5c6
+  data.tar.gz: e6c5b28ce615e5a0b5e479f73d21663359a9f672
 SHA512:
-  metadata.gz: c8e439ce945b9e43802153825e69eb91cf4b5ea31c5d0eea0af103b02fad8201ce455f364030d891a4b690284f1ac25a86876fbd0b07d7fa8dfacf3806eb8f06
-  data.tar.gz: cce20bd75d95089771a74691365bc650ee44295f0cd93e2226cc48882d7b80bbc1790620ab98979f8e38a2a73f849702bd013fee78eb1f02a17722ff3a068bc7
+  metadata.gz: 5c63d4c52002d236081bc816a8fe8e57283ac6c2a4ab2f1ec5ddf59448c08ae5918161b54ef0066540fd25436c68b469f8c9c746378469dc8f85fbb1272b6544
+  data.tar.gz: b91f6a5a283e7970e481e39cd02a21a512021c6c5acd38edc1cc5d0e2bca0ea952a8579e1a1458c7695d9dfad318887e65ef0c740ac7325a48513e9dcf2f4c22

data/lib/ocean/api.rb

@@ -503,6 +503,21 @@ class Api
   end
 
 
+  #
+  # Constructs a hash suitable as the body of a POST to async_jobs. It lets you set
+  # all the allowed attributes, and it also provides a terse shortcut for one-step
+  # jobs (by far the most common ones). The following:
+  #
+  #   Api.async_body "/v1/foos", :put
+  #
+  # is equivalent to
+  #
+  #   Api.async_body steps: [{"url" => "#{INTERNAL_OCEAN_API_URL}/v1/foos"}
+  #                           "method" => "PUT",
+  #                           "body" => {}}]
+  # 
+  # A URL not starting with a / will be internalized.
+  #
   def self.async_job_body(href=nil, method=:get, body: {},
                           credentials: nil, 
                           token: nil,

data/lib/ocean/api_remote_resource.rb

@@ -134,6 +134,12 @@ class Api
     attr_reader :raw, :resource, :resource_type, :status, :headers, :credentials, :x_api_token
     attr_reader :status_message, :response, :etag
 
+    #
+    # The credentials and the x_api_token, if both are left unspecified, will default to
+    # the local credentials and service token. If both are specified and different from
+    # the default values, they will be used instead. Specifying only one of them is not
+    # permitted.
+    #
   	def initialize(uri, type="application/json",
                    credentials: nil, x_api_token: nil,
   		             retries: 3, backoff_time: 1, backoff_rate: 0.9, backoff_max: 30)
@@ -155,47 +161,105 @@ class Api
       @x_api_token = x_api_token
   	end
 
+    #
+    # True if the resource has been read successfully.
+    #
     def present?
       @present
     end
 
-
+    #
+    # Returns a resource attribute. If the resource isn't present, +get!+ will used to
+    # retrieve it.
+    #
     def [](key)
       get!
       resource[key]
     end
 
+    #
+    # Sets a resource attribute. The resource will not be retrieved if not present.
+    #
     def []=(key, value)
       resource[key] = value
     end
 
+    #
+    # Returns the hash of hyperlinks. The resource will not be retrieved if not present.
+    #
     def hyperlink
       self['_links']
     end
 
+    #
+    # Returns resources own href. The resource will not be retrieved if not present.
+    #
     def href
       hyperlink['self']['href']
     end
 
+    #
+    # Returns resources own content type. The resource will not be retrieved if not present.
+    #
     def type
       hyperlink['self']['type']
     end
 
-
+    #
+    # Raised when a POST fails, i.e. the response status isn't 2xx.
+    #
     class PostFailed < StandardError; end
+
+    #
+    # Raised when a GET fails, i.e. the response status isn't 2xx.
+    #
     class GetFailed < StandardError; end
+
+    #
+    # Raised when a Conditional GET fails, i.e. the response status isn't 2xx.
+    #
+    class ConditionalGetFailed < StandardError; end
+
+    #
+    # Raised when a PUT fails, i.e. the response status isn't 2xx.
+    #
     class PutFailed < StandardError; end
+
+    #
+    # Raised when a DELETE fails, i.e. the response status isn't 2xx.
+    #
     class DeleteFailed < StandardError; end
+
+    #
+    # Raised when a POST, GET, or PUT doesn't return JSON or when the returned JSON
+    # doesn't parse.
+    #
     class UnparseableJson < StandardError; end
+
+    #
+    # Raised when what a POST, GET, or PUT returns parses correctly but isn't an
+    # Ocean resource in the proper format.
+    #
     class JsonIsNoResource < StandardError; end
+
+    #
+    # Raised when a specified hyperlink doesn't exist in the resource representation.
+    #
     class HyperlinkMissing < StandardError; end
-    class ConditionalGetFailed < StandardError; end
 
 
+    #
+    # Class method to retrieve a resource. Will raise exceptions if problems occur,
+    # otherwise returns the resource itself. The args are passed directly to +new+.
+    #
     def self.get!(*args)
       _retrieve new(*args)
     end
 
+    #
+    # Class method to retrieve a resource. Will not raise exceptions if problems occur,
+    # but will always return the resource itself. The args are passed directly to +new+.
+    #
     def self.get(*args)
       rr = new(*args)
       rr.get! rescue nil
@@ -203,6 +267,10 @@ class Api
     end
 
 
+    #
+    # Instance method to GET a resource or any of its hyperlinks. Will raise exceptions
+    # if they occur, otherwise will return the resource itself.
+    #
     def get!(hlink=nil)
       RemoteResource._retrieve self unless present?
       hlink = hlink.to_s if hlink
@@ -215,6 +283,11 @@ class Api
       end
     end
 
+    #
+    # Instance method to GET a resource or any of its hyperlinks. Will not raise 
+    # exceptions if problems occur, but will always return the resource itself.
+    # A missing hyperlink, though, will always raise a HyperlinkMissing exception.
+    #
     def get(hlink=nil)
       get! rescue nil
       hlink = hlink.to_s if hlink
@@ -228,6 +301,10 @@ class Api
     end
 
 
+    #
+    # Instance method to do a PUT to a resource or any of its hyperlinks. Will raise exceptions
+    # if they occur, otherwise will return the resource itself.
+    #
     def put!(hlink=nil, body: {})
       get!
       hlink = hlink.to_s if hlink
@@ -243,6 +320,11 @@ class Api
       end
     end
 
+    #
+    # Instance method to do a PUT to a resource or any of its hyperlinks. Will not raise 
+    # exceptions if they occur, but will always return the resource itself.
+    # A missing hyperlink, though, will always raise a HyperlinkMissing exception.
+    #
     def put(hlink=nil, body: {})
       get
       hlink = hlink.to_s if hlink
@@ -259,6 +341,10 @@ class Api
     end
 
 
+    #
+    # Instance method to do a POST to a resource or any of its hyperlinks. Will raise exceptions
+    # if they occur, otherwise will return the resource itself.
+    #
     def post!(hlink=nil, body: {})
       get!
       hlink = (hlink || 'self').to_s
@@ -267,6 +353,11 @@ class Api
       _create(hl_data['href'], body)
     end
 
+    #
+    # Instance method to do a POST to a resource or any of its hyperlinks. Will not raise 
+    # exceptions if they occur, but will always return the resource itself.
+    # A missing hyperlink, though, will always raise a HyperlinkMissing exception.
+    #
     def post(hlink=nil, body: {})
       get
       hlink = (hlink || 'self').to_s
@@ -276,6 +367,10 @@ class Api
     end
 
 
+    #
+    # Instance method to do a DELETE to a resource or any of its hyperlinks. Will raise exceptions
+    # if they occur, otherwise will return the resource itself.
+    #
     def delete!(hlink=nil)
       get!
       hlink = (hlink || 'self').to_s
@@ -285,6 +380,11 @@ class Api
       self
     end
 
+    #
+    # Instance method to do a DELETE to a resource or any of its hyperlinks. Will not raise 
+    # exceptions if they occur, but will always return the resource itself.
+    # A missing hyperlink, though, will always raise a HyperlinkMissing exception.
+    #
     def delete(hlink=nil)
       get
       hlink = (hlink || 'self').to_s
@@ -295,6 +395,12 @@ class Api
     end
 
 
+    #
+    # If the resource is present and has received an ETag in previous requests,
+    # will perform a Conditional GET to update the local representation. If the resource
+    # isn't present or has no ETag, a normal +#get!+ will be done. If no exception is
+    # raised, the resource itself is returned.
+    #
     def refresh!
       if present? && etag.present?
         _conditional_get
@@ -304,6 +410,12 @@ class Api
       self
     end
 
+    #
+    # If the resource is present and has received an ETag in previous requests,
+    # will perform a Conditional GET to update the local representation. If the resource
+    # isn't present or has no ETag, a normal +#get+ will be done. The resource will
+    # always be returned.
+    #
     def refresh
       if present? && etag.present?
         _conditional_get rescue nil

data/lib/ocean/version.rb

@@ -1,3 +1,3 @@
 module Ocean
-  VERSION = "3.8.2"
+  VERSION = "3.8.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ocean-rails
 version: !ruby/object:Gem::Version
-  version: 3.8.2
+  version: 3.8.3
 platform: ruby
 authors:
 - Peter Bengtson