numerousapp 1.2.6 → 1.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6dae231f126ef9c4f0a71673a575a27321fa5223
-  data.tar.gz: 4eab62238a84dc5994552b80bd88177f2a464a92
+  metadata.gz: d84cedd80341e019f0e486dd57c265ef46df5379
+  data.tar.gz: c362a7d857fdc212c4e3f6b23dee841ce6d170ec
 SHA512:
-  metadata.gz: d2c669133e594e0af1dbf72f786ec58b7d10b6f58c0155a619837ccbe4538e15fdb5365f230f4c9a174e484e3a9d94de13cf0c1b5978c1b0f20b946d1e4490cc
-  data.tar.gz: 651b29f1f3ba7423174149329a421c035ce6b26012d48499e51bd92a3803ef8f9953c2f3a045b5ed459d22c6cfbd7f3eeb847639cb2ec124ffa743e98a08a2d8
+  metadata.gz: 867a746bce44f34bea1b7b451ed93d07c0bbe3d1aa1a11d076dba317f32d81b85bec44947b5c00b5e3b37cf078288668e04fbde5ad968e8a600f416a1277b00e
+  data.tar.gz: a5ef9a2db1b91f00290400fe6efe114705792ed7f0726c8be1e75a027f7fb584e3b747d44a2008f88b9d3a5a6949af9eba42fa23ca43a39faba5f00de299d295

data/lib/numerousapp.rb

@@ -121,7 +121,7 @@ class NumerousClientInternals
     #    @return [String] FQDN of the target NumerousApp server.
     #
     # @!attribute [r] debugLevel
-    #    @return [Fixnum] Current debugging level; use debug() method to change.
+    #    @return [Fixnum] Current debugging level; change via debug() method
     #
     def initialize(apiKey=nil, server:'api.numerousapp.com',
                            throttle:nil, throttleData:nil)
@@ -142,11 +142,12 @@ class NumerousClientInternals
         @filterDuplicates = true     # see discussion elsewhere
         @need_restart = true         # port will be opened in simpleAPI
 
-        # throttling.
-        # The arbitraryMaximum is just that: under no circumstances will we retry
+        # Throttling:
+        #
+        # arbitraryMaximum is just that: under no circumstances will we retry
         # any particular request more than that. Tough noogies.
         #
-        # the throttlePolicy "tuple" is:
+        # throttlePolicy "tuple" is:
         #     [ 0 ] - Proc
         #     [ 1 ] - specific data for Proc
         #     [ 2 ] - "up" tuple for chained policy
@@ -157,7 +158,8 @@ class NumerousClientInternals
         #
         @arbitraryMaximumTries = 10
         voluntary = { voluntary: 40, volmaxdelay: 5}
-        # you can keep the dflt throttle but just alter the voluntary param, this way:
+        # you can keep the dflt throttle but just alter the voluntary
+        # parameters, this way:
         if throttleData and not throttle
             voluntary = voluntary.merge(throttleData)
         end
@@ -166,7 +168,7 @@ class NumerousClientInternals
             @throttlePolicy = [throttle, throttleData, @throttlePolicy]
         end
 
-        @statistics = Hash.new { |h, k| h[k] = 0 }  # statistics are "infotainment"
+        @statistics = Hash.new { |h, k| h[k] = 0 }  # stats are "infotainment"
         @debugLevel = 0
 
     end
@@ -179,7 +181,7 @@ class NumerousClientInternals
     #
     # @return [String] Human-appropriate string representation.
     def to_s()
-        oid = (2 * self.object_id).to_s(16)  # XXX "2*" makes it match native to_s
+        oid = (2 * self.object_id).to_s(16)  # XXX "2*" matches native to_s
         return "<Numerous {#{@serverName}} @ 0x#{oid}>"
     end
 
@@ -223,7 +225,7 @@ class NumerousClientInternals
 
     protected
 
-    VersionString = '20150811-1.2.6'
+    VersionString = '20150904-1.2.7'
 
     MethMap = {
         GET: Net::HTTP::Get,
@@ -242,7 +244,7 @@ class NumerousClientInternals
         rslt = {}
         rslt[:httpMethod] = whichOp
 
-        # Build the substitutions from the defaults (if any) and non-nil kwargs.
+        # Build the substitutions from defaults (if any) and non-nil kwargs.
         # Note: we are carefully making copies of the underlying dictionaries
         #       so you get your own private context returned to you
         substitutions = (info[:defaults]||{}).clone
@@ -605,7 +607,6 @@ class NumerousClientInternals
     #
     # The policy this implements:
     #    * if "getting close" to the limit, arbitrarily delay ourselves.
-    #      See ComputeVoluntaryDelay above for details on that policy
     #
     #    * if we truly got spanked with "Too Many Requests"
     #      then delay the amount of time the server told us to delay.
@@ -1660,10 +1661,13 @@ class NumerousMetric < NumerousClientInternals
     #
     # @param [Fixnum|Float] newval Required. Value to be written.
     #
-    # @param [Boolean] onlyIf
-    #   Optional (keyword arg). Only creates an event at the server
-    #   if the newval is different from the current value. Raises
-    #   NumerousMetricConflictError if there is no change in value.
+    # @param [Boolean|String] onlyIf
+    #   Optional (keyword arg). Default is false.
+    #   If this is true or the string 'IGNORE' then the server only creates
+    #   a metric event if the newval is different from the current value.
+    #   If onlyIf=true then this RaisesNumerousMetricConflictError if there
+    #   is no change in value. If onlyIf is 'IGNORE' then the "conflict" error
+    #   is silently ignored (probably the more common usage case).
     #
     # @param [Boolean] add
     #   Optional (keyword arg). Sends the "action: ADD"	attribute which
@@ -1691,7 +1695,11 @@ class NumerousMetric < NumerousClientInternals
     #
     def write(newval, onlyIf:false, add:false, dictionary:false, updated:nil)
         j = { 'value' => newval }
-        if onlyIf
+        if onlyIf != false
+            if not [ true, 'IGNORE' ].include? onlyIf
+                # onlyIf must be false, true, or "IGNORE"
+                raise ArgumentError, 'onlyIf must be false, true, or "IGNORE"'
+            end
             j['onlyIfChanged'] = true
         end
         if add
@@ -1722,8 +1730,14 @@ class NumerousMetric < NumerousClientInternals
         rescue NumerousError => e
             # if onlyIf was specified and the error is "conflict"
             # (meaning: no change), raise ConflictError specifically
+            # or ignore it if you specified onlyIf="IGNORE"
             if onlyIf and e.code == 409
-                raise NumerousMetricConflictError.new("No Change", e.details)
+                if onlyIf != 'IGNORE'
+                    raise NumerousMetricConflictError.new("No Change", e.details)
+                else
+                    # forge a pseudo-result because you asked for it
+                    v = { 'value'=>newval, 'unchanged'=>true }
+                end
             else
                 raise e        # never mind, plain NumerousError is fine
             end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: numerousapp
 version: !ruby/object:Gem::Version
-  version: 1.2.6
+  version: 1.2.7
 platform: ruby
 authors:
 - Neil Webber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-11 00:00:00.000000000 Z
+date: 2015-09-04 00:00:00.000000000 Z
 dependencies: []
 description: Classes implementing the NumerousApp REST APIs for metrics. Requires
   Ruby 2.x