atomsphere 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bb21b9a66774a9fee3486b96ce9d8f52e7ed633013c828f391bc9cafa56c4d3
-  data.tar.gz: 7f849cfd2473ada55b2cec071583d114658a8b403295dc9c9a26423d077f5351
+  metadata.gz: e78f1312bd07e2b8624c0aae53b83463bf877134d6c9b3d0253f2256528e3441
+  data.tar.gz: 9f34dccf99636cb840a89f48fd256f92944ad55f5e6eec7e3c1d1ad200c0c9d6
 SHA512:
-  metadata.gz: 632193c167af5174b7c050714c9bb05c844ae863eab4a6330daba8c9a372603e2414e77ce0acd61fe41536ba1032398af536af1ae41963326af0bc95c9881824
-  data.tar.gz: 3f4c067af23f0b447dd9692eff618a6107f901025e2ce253db119d744febe119729046d03296df660a02a5b429f0447fd719986362b6ce7b619e57f251f55ffa
+  metadata.gz: 571d407b997b509a116397fce8ee74d32819dab8890575cfa19b5eaff4c02c4a542fb41a3657fe1df0747a74934f429e5a0427d92ee8efba193dc2c31b01586a
+  data.tar.gz: 84f4c92a54014a100e2f33c4021167e085e1ca90291cb07c4d18896c5fe1423145b40013dbb4b303d07834c3b5d79c9277d2d2f34cb64f67f9ff78bb34da32d8

data/.gitignore

@@ -3,3 +3,6 @@
 /.bundle
 /tmp
 Gemfile.lock
+*.gem
+doc/
+.yardoc

data/README.md

@@ -1,5 +1,9 @@
 # Boomi Atomsphere API client for Ruby
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Gem Version](https://badge.fury.io/rb/atomsphere.svg)](https://badge.fury.io/rb/atomsphere)
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/atomsphere)
+
 Unofficial Ruby client for the Dell Boomi Atomsphere API. Implements the JSON flavour of Boomi's "RESTish" API.
 
 ## Status
@@ -40,35 +44,58 @@ Alternatively, environment variables may be used:
 
 ### Querying
 
+Generate a query for all _"Processes"_ that start with _"Production"_ and
+contain _"NetSuite"_ or _"Salesforce"_:
+
+```ruby
+query = Atomsphere.query('Process') do
+  group :and do
+    name.like 'Production%'
+    group :or do
+      name.like '%NetSuite%'
+      name.like '%Salesforce%'
+    end
+  end
+end
+```
+
+Generate a query for all online Atoms:
+
+```ruby
+query = Atomsphere.query('Atom') do
+  status.equals 'ONLINE'
+  type.equals   'CLOUD'
+end
+```
+
+Inspect the query filter:
+
+```ruby
+query.to_hash
+query.to_json
+```
+
+Run the query:
+
 ```ruby
-# create a new query
-query = Atomsphere::Query.new
-
-# specify the object type to query
-query.object_type = 'Process'
-
-# filter for query names starting with 'Netsuite'
-query.filter = Atomsphere::Query::GroupingExpression.new(
-  operator: :and,
-  nested_expression: [
-    Atomsphere::Query::SimpleExpression.new(
-      operator: :equals,
-      property: :name,
-      argument: ['Netsuite%']
-    )
-  ]
-)
-
-# run the query (fetches first page)
 query.run
+```
+
+See results from all pages that have been fetched:
 
-# see results from all pages that have been fetched
+```ruby
 query.results
+```
+
+Fetch the next page (returns `false` if `last_page?` is `true`):
 
-# fetch the next page (returns `false` if `last_page?` is `true`)
+```ruby
 query.next_page
+```
+
+Iterate over `next_page` until `last_page?` is `true` and see all results:
 
-# fetch and show all pages of results (warning: loops over `next_page`)
+```ruby
 query.all_results
 ```
 

data/atomsphere.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name          = 'atomsphere'
-  s.version       = '0.1.7'
+  s.version       = '0.1.8'
   s.licenses      = ['MIT']
   s.summary       = "Unofficial Ruby client for the Dell Boomi Atomsphere API"
   s.authors       = ["Warren Guy"]

data/lib/atomsphere.rb

@@ -1,5 +1,6 @@
+# @author Warren Guy
 module Atomsphere
-  VERSION = '0.1.7'
+  VERSION = '0.1.8'
   ROOT = "#{File.expand_path(__dir__)}/atomsphere"
 
   %w(configuration query api action).each{ |m| require "#{ROOT}/#{m}" }

data/lib/atomsphere/api/client.rb

@@ -96,12 +96,24 @@ module Atomsphere
             'response code was nil'
           ) if response.code.nil?
 
-          raise ApiError.new(
-            request,
-            response,
-            e,
-            "API responded with error #{response.code}: #{response.message}"
-          ) if response.code >= 400
+          if response.code >= 400
+            begin
+              json = JSON.parse(response.response.body)
+              if json['@type'].downcase.eql?('error')
+                 message = json['message']
+              end
+            rescue JSON::ParserError
+            ensure
+              message ||= "API responded with error #{response.code}: #{response.message}"
+            end
+
+            raise ApiError.new(
+              request,
+              response,
+              e,
+              message
+            )
+          end
         end
 
         response

data/lib/atomsphere/query.rb

@@ -1,15 +1,40 @@
 module Atomsphere
+
+  # @attr         [String]               object_type   name of the object to query
+  # @attr         [GroupingExpression]   filter        top level {GroupingExpression} for query
+  # @attr_reader  [Integer]              page          the number of pages retrieved
+  # @attr_reader  [Array<Api::Response>] result_pages  array of api responses for each page retrieved
   class Query
     attr_accessor :object_type, :filter
     attr_reader   :query_token, :result_pages, :page
 
-    def initialize object_type=nil
-      @object_type ||= object_type
-      @page = 0
-      @result_pages = []
-      @filter = GroupingExpression.new
+    # accepts either a string of the name of the object to query, or a hash of options
+    # @param          [String] params       name of the object to query
+    # @param          [Hash]   params       parameters to initialize query with
+    # @option params  [String]              :object_type  name of the object to query
+    # @option params  [GroupingExpression]  :filter       top level {GroupingExpression}
+    def initialize(params={})
+      case params
+      when String
+        params = {object_type: params}
+      end
+
+      params = {
+        object_type: nil,
+        page: 0,
+        result_pages: [],
+        filter: GroupingExpression.new
+      }.merge(Hash[params.select{|k,v| [:object_type, :filter].include? k}])
+
+      %w(object_type page result_pages filter).each do |v|
+        instance_variable_set :"@#{v}", params[v.to_sym]
+      end
+
+      self
     end
 
+    # run all `validate_*!` private methods to ensure validity of query parameters
+    # @return [true, false]
     def validate!
       private_methods.select{ |m| m =~ /^validate_[a-z0-9_]+\!$/ }.each{ |v| send(v) }
       filter.validate!
@@ -17,23 +42,33 @@ module Atomsphere
       true
     end
 
+    # @see #next_page
     def run
       next_page
     end
-    
+
+    # returns rows from {#result_pages} that have been retrieved
+    # @return [Array<Hash>] Array of returned rows as hashes
     def results
       result_pages.map(&:to_hash).map{ |h| h['result'] }.map(&:compact).flatten(1)
     end
 
+    # runs {#next_page} to retrieve all {#result_pages} until {#last_page?} is `false`,
+    # and then returns all rows
+    # @return [Array<Hash>] Array of returned rows as hashes
     def all_results
       next_page until last_page?
       results
     end
 
+    # returns `true` when any pages have been retrieved the value of {#query_token} is `nil`
+    # @return [true, false]
     def last_page?
       !page.eql?(0) && query_token.nil?
     end
 
+    # retrieve the next page for the query
+    # @return [Api::Response, false] returns the response, or `false` if {#last_page?} is `true`
     def next_page
       return false if last_page?
 
@@ -52,12 +87,19 @@ module Atomsphere
       result_pages[page-1] = response
     end
 
+    # validates all parameters with {#validate!} and returns a hash of the query
+    # that will be sent to the boomi api
+    # @see #to_json
+    # @return [Hash] hash representation of query that will be sent to the boomi api
     def to_hash
       validate!
 
       { QueryFilter: filter.to_hash }
     end
 
+    # query json that will be sent to the boomi api
+    # @see #to_hash
+    # @return [String] JSON query string
     def to_json
       JSON.pretty_generate to_hash
     end
@@ -73,10 +115,15 @@ module Atomsphere
       end
     end
 
+    # an instance of the API client
+    # @return [Api::Client]
     def api_client
       Api::Client.new
     end
 
+    # if any pages have been retrieved, the value of `queryToken` from the
+    # last response
+    # @return [String, nil] value of `queryToken`, or `nil`
     def query_token
       if result_pages.last.nil? || !result_pages.last.to_hash.keys.include?('queryToken')
         nil
@@ -86,5 +133,6 @@ module Atomsphere
     end
   end
 
-  %w(grouping_expression simple_expression).each{ |m| require "#{ROOT}/query/#{m}" }
+  require "#{ROOT}/query/builder"
+  require "#{ROOT}/query/expression"
 end

data/lib/atomsphere/query/builder.rb

@@ -0,0 +1,39 @@
+module Atomsphere
+  class Query
+    class Builder
+      attr_reader :query
+
+      def initialize(object_type)
+        @query = object_type.nil? ? Query.new : Query.new(object_type)
+      end
+
+      def group operator, &block
+        new_group = GroupingExpression.new(operator)
+        Group.new(new_group).instance_eval(&block)
+
+        if @query.filter
+          @query.filter.nested_expression << new_group
+        else
+          @query.filter = new_group
+        end
+      end
+
+      def method_missing m, *args, &block
+        @query.filter = GroupingExpression.new(:and) unless @query.filter
+        Group.new(@query.filter).instance_eval do
+          send(m, *args, &block)
+        end
+      end
+    end
+  end
+
+  def self.query(object_type=nil, &block)
+    q = Query::Builder.new(object_type)
+    q.instance_eval(&block) if block_given?
+
+    q.query
+  end
+
+  require "#{ROOT}/query/builder/property"
+  require "#{ROOT}/query/builder/group"
+end

data/lib/atomsphere/query/builder/group.rb

@@ -0,0 +1,26 @@
+module Atomsphere
+  class Query
+    class Builder
+      class Group
+        def initialize expression
+          @expression = expression
+        end
+
+        def group operator, &block
+          new_group = GroupingExpression.new(operator)
+          Group.new(new_group).instance_eval(&block)
+          @expression.nested_expression << new_group
+        end
+
+        def method_missing m, *args, &block
+          __property(@expression, m)
+        end
+
+        private
+        def __property(expression, property)
+          Property.new(expression, property)
+        end
+      end
+    end
+  end
+end

data/lib/atomsphere/query/builder/property.rb

@@ -0,0 +1,25 @@
+module Atomsphere
+  class Query
+    class Builder
+      class Property
+        def initialize(expression, property)
+          @expression = expression
+          @property = property
+        end
+
+        def method_missing m, *args, &block
+          __operator(m, *args) if SimpleExpression::OPERATORS.keys.include? m
+        end
+
+        private
+        def __operator(operator, args)
+          @expression.nested_expression << SimpleExpression.new(
+            property: @property,
+            operator: operator,
+            argument: args
+          )
+        end
+      end
+    end
+  end
+end

data/lib/atomsphere/query/expression.rb

@@ -0,0 +1,13 @@
+require 'json'
+
+module Atomsphere
+  class Query
+
+    # @see GroupingExpression
+    # @see SimpleExpression
+    class Expression
+    end
+  end
+
+  Dir["#{ROOT}/query/expression/*.rb"].each{ |f| require f }
+end

data/lib/atomsphere/query/{grouping_expression.rb → expression/grouping_expression.rb}

@@ -2,12 +2,24 @@ require 'json'
 
 module Atomsphere
   class Query
-    class GroupingExpression
+
+    # @see http://help.boomi.com/atomsphere/GUID-4CAE5616-76EB-4C58-B2E3-4173B65EA7EC.html
+    class GroupingExpression < Expression
       attr_accessor :operator, :nested_expression
 
+      # allowed values for {#operator=}
       OPERATORS = :and, :or
 
+      # @param [Hash] params
+      # @option params [:and, :or] :operator query operator
+      # @option params [Array<Expression>] :nested_expression one or more {Expression}s
       def initialize(params={})
+        case params
+        when String
+        when Symbol
+          params = {operator: params}
+        end
+
         params = {
           operator: :and,
           nested_expression: []
@@ -17,6 +29,16 @@ module Atomsphere
         @nested_expression = params[:nested_expression]
       end
 
+      def operator= arg
+        unless OPERATORS.include? arg.to_sym
+          raise ArgumentError, "operator must be one of: #{OPERATORS.join(', ')}"
+        end
+
+        instance_variable_set :@operator, arg.to_sym
+      end
+
+      # run all `validate_*!` private methods to ensure validity of expression parameters
+      # @return [true, false]
       def validate!
         private_methods.select{ |m| m =~ /^validate_[a-z0-9_]+\!$/ }.each{ |v| "#{v}"; send(v) }
         @nested_expression.each(&:validate!)
@@ -24,6 +46,9 @@ module Atomsphere
         true
       end
 
+      # returns a hash of the expression that will be sent to the boomi api with {Query#to_hash}
+      # @see #to_json
+      # @return [Hash] hash representation of query that will be sent to the boomi api
       def to_hash
         {
           expression: {
@@ -35,10 +60,6 @@ module Atomsphere
         }
       end
 
-      def to_json
-        JSON.pretty_generate to_hash
-      end
-
       private
       def validate_operators!
         unless OPERATORS.include? @operator
@@ -49,13 +70,13 @@ module Atomsphere
       def validate_expressions!
         raise ArgumentError, "nested_expression must be an array" unless @nested_expression.is_a?(Array)
 
-        not_expressions = @nested_expression.map(&:class).reject do |k|
-          [GroupingExpression, SimpleExpression].include? k
+        not_expressions = @nested_expression.map(&:class).map(&:ancestors).reject do |k|
+          k.include? Atomsphere::Query::Expression
         end
 
         if not_expressions.size > 0
           raise ArgumentError,
-            "invalid expression class(es): #{not_expressions.map(&:class).join(', ')}"
+            "Expressions must be an object of a subclass of Atomsphere::Query::Expression"
         end
       end
 

data/lib/atomsphere/query/{simple_expression.rb → expression/simple_expression.rb}

@@ -2,9 +2,12 @@ require 'json'
 
 module Atomsphere
   class Query
-    class SimpleExpression
+
+    # @see http://help.boomi.com/atomsphere/GUID-4CAE5616-76EB-4C58-B2E3-4173B65EA7EC.html
+    class SimpleExpression < Expression
       attr_accessor :operator, :property, :argument
 
+      # allowed values for {#operator=}
       OPERATORS = {
         equals:       1,
         like:         1,
@@ -19,6 +22,10 @@ module Atomsphere
         less_than_or_equal: 1
       }
 
+      # @param [Hash] params
+      # @option params [String] :property the property/field to query
+      # @option params [:equals,:like,:not_equals,:is_null,:is_not_null,:starts_with,:between,:greater_than,:less_than,:greater_than_or_equal,:less_than_or_equal] :operator query operator
+      # @option params [Array] :argument array containing the number of arguments specified in the {OPERATORS} constant, as arguments to the query {#operator}
       def initialize(params={})
         params = {
           operator: :equals,
@@ -31,25 +38,26 @@ module Atomsphere
         end
       end
 
+      # run all `validate_*!` private methods to ensure validity of expression parameters
+      # @return [true, false]
       def validate!
         private_methods.select{ |m| m =~ /^validate_[a-z0-9_]+\!$/ }.each{ |v| send(v) }
         true
       end
 
+      # returns a hash of the expression that will be sent to the boomi api with {Query#to_hash}
+      # @see #to_json
+      # @return [Hash] hash representation of query that will be sent to the boomi api
       def to_hash
         {
           expression: {
-            operator: operator.upcase,
-            property: property,
-            argument: [*argument]
+            operator: operator.to_s.upcase,
+            property: property.to_s,
+            argument: [*argument].map(&:to_s)
           }
         }
       end
 
-      def to_json
-        to_hash.to_json
-      end
-
       def operator= arg
         unless OPERATORS.keys.include? arg.to_sym
           raise ArgumentError, "operator must be one of: #{OPERATORS.keys.join(', ')}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomsphere
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Warren Guy
@@ -59,8 +59,12 @@ files:
 - lib/atomsphere/api/response.rb
 - lib/atomsphere/configuration.rb
 - lib/atomsphere/query.rb
-- lib/atomsphere/query/grouping_expression.rb
-- lib/atomsphere/query/simple_expression.rb
+- lib/atomsphere/query/builder.rb
+- lib/atomsphere/query/builder/group.rb
+- lib/atomsphere/query/builder/property.rb
+- lib/atomsphere/query/expression.rb
+- lib/atomsphere/query/expression/grouping_expression.rb
+- lib/atomsphere/query/expression/simple_expression.rb
 homepage: https://github.com/warrenguy/atomsphere-ruby
 licenses:
 - MIT