bodhi-slam 0.8.6 → 0.8.7

data/lib/bodhi-slam/resource.rb

@@ -1,16 +1,33 @@
 module Bodhi
+  # Interface for interacting with resources on the HotSchedules IoT Platform.
   module Resource
+    # @!parse extend Bodhi::Resource::ClassMethods
 
+    # The API context that binds a +Bodhi::Resource+ instance to the HotSchedules IoT Platform
+    # @note This is required for the all instance methods to work correctly
+    # @return [Bodhi::Context] the API context linked to this object
     attr_accessor :bodhi_context
 
     module ClassMethods
 
-      def embedded(bool); @embedded = bool; end
+      # Sets the resources embedded status to either true/false.
+      #
+      # @param status [Boolean]
+      # @return [Boolean]
+      def embedded(status); @embedded = status; end
+
+      # Checks if the resource is embedded
+      #
+      # @return [Boolean]
       def is_embedded?; @embedded; end
 
       # Defines the given +name+ and +options+ as a form attribute for the class.
-      # The +name+ is set as a property, and validations & factory generators are added based on the supplied +options+
-      # 
+      # The +name+ is set as a property, and validations & factory generators
+      # are added based on the supplied +options+
+      #
+      # @param name [String]
+      # @param options [Hash]
+      # @example
       #   class User
       #     include Bodhi::Resource
       #
@@ -27,13 +44,30 @@ module Bodhi
         generates(name.to_sym, options)
       end
 
+      # Generates a new {Bodhi::Type} instance using the classes metadata
+      #
+      # @return [Bodhi::Type]
+      # @example
+      #   class User
+      #     include Bodhi::Resource
+      #
+      #     field :first_name, type: "String", required: true, is_not_blank: true
+      #     field :last_name, type: "String", required: true, is_not_blank: true
+      #     field :email, type: "String", required: true, is_not_blank: true, is_email: true
+      #
+      #     index ["last_name"]
+      #   end
+      #
+      #   User.build_type #=> #<Bodhi::Type:0x007fbff403e808 @name="User" @properties={...} @indexes=[...]>
       def build_type
         Bodhi::Type.new(name: self.name, properties: self.properties, indexes: self.indexes, embedded: self.is_embedded?)
       end
 
       # Saves a batch of resources to the Bodhi Cloud in the given +context+
       # Returns an array of JSON objects describing the results for each record in the batch
-      # 
+      #
+      # @deprecated This uses the old bulk upload process and will be removed in version 1.0.0  DO NOT USE!
+      # @example
       #   context = Bodhi::Context.new
       #   list = Resource.factory.build_list(10)
       #   Resource.save_batch(context, list)
@@ -43,43 +77,80 @@ module Bodhi
         batch
       end
 
-      # Counts all records that match the given query
+      # Counts all records that match the given +query+
       #
-      #   context = Bodhi::Context.new
-      #   count = Resource.count(context, name: "Foo")
+      # Equivalent CURL command:
+      #   curl -u {username}:{password} https://{server}/{namespace}/resources/{resource}/count?where={query}
+      # @param context [Bodhi::Context]
+      # @param query [Hash] MongoDB query operations
+      # @example
+      #   Resource.count(context) #=> # count all records
+      #   Resource.count(context, name: "Foo") #=> # count all records with name == "Foo"
       def count(context, query={})
         query_obj = Bodhi::Query.new(name)
         query_obj.where(query).from(context)
         query_obj.count
       end
 
-      # Deletes all records that match the given query
+      # Deletes all records that match the given +query+
       #
-      #   context = Bodhi::Context.new
-      #   count = Resource.delete(context, name: "Foo")
+      # Equivalent CURL command:
+      #   curl -u {username}:{password} -X DELETE https://{server}/{namespace}/resources/{resource}?where={query}
+      # @note Beware: It's easy to delete an entire collection with this method!  Use it wisely :)
+      # @param context [Bodhi::Context]
+      # @param query [Hash] MongoDB query operations
+      # @return [Hash] with key: +count+
+      # @todo add more query complex examples
+      # @example
+      #   # delete with a query
+      #   Resource.delete!(context, sys_created_at: { '$lte': 6.months.ago.iso8601 })
+      #
+      #   # delete all records
+      #   Resource.delete!(context)
       def delete!(context, query={})
         query_obj = Bodhi::Query.new(name)
         query_obj.where(query).from(context)
         query_obj.delete
       end
 
-      def create!(params, context=nil)
-        if context.nil?
-          context = Bodhi::Context.global_context
-        end
-
+      # Creates a new resource with the given +properties+
+      # and POSTs it to the IoT Platform
+      #
+      # Equivalent CURL command:
+      #   curl -u {username}:{password} -X POST -H "Content-Type: application/json" \
+      #   https://{server}/{namespace}/resources/{resource} \
+      #   -d '{properties}'
+      # @param context [Bodhi::Context]
+      # @param properties [Hash]
+      # @return [Bodhi::Resource]
+      # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+      # @raise [Bodhi::ApiErrors] if the record cannot be saved
+      #   Resource.create!(context, name: "Foo", age: 125, tags: ["green", "blue"])
+      def create!(context, properties)
         if context.invalid?
           raise Bodhi::ContextErrors.new(context.errors.messages), context.errors.to_a.to_s
         end
 
-        record = self.new(params)
+        # Build a new record and set the context
+        record = self.new(properties)
         record.bodhi_context = context
+
+        # POST to the IoT Platform
         record.save!
         return record
       end
 
-      # Returns a single resource from the Bodhi Cloud that matches the given +id+
-      # 
+      # Search for a record with the given +id+
+      #
+      # Equivalent CURL command:
+      #   curl -u {username}:{password} https://{server}/{namespace}/resources/{resource}/{id}
+      # @param id [String] the {Bodhi::Properties#sys_id} of the record
+      # @param context [Bodhi::Context]
+      # @return [Bodhi::Resource]
+      # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+      # @raise [Bodhi::ApiErrors] if response status is NOT +200+
+      # @raise [ArgumentError] if the given +id+ is NOT a +String+
+      # @example
       #   context = Bodhi::Context.new
       #   id = Resource.factory.create(context).sys_id
       #   obj = Resource.find(context, id)
@@ -110,9 +181,16 @@ module Bodhi
         record
       end
 
-      # Returns all records of the given resource from the Bodhi Cloud.
-      # 
-      #   context = Bodhi::Context.new
+      # Returns all records in the given +context+
+      #
+      # All records returned by this method will have their
+      # {#bodhi_context} attribute set to +context+
+      # @note This method will return ALL records!!  Don't use on large collections!  YE BE WARNED!!
+      # @param context [Bodhi::Context]
+      # @return [Array<Bodhi::Resource>]
+      # @raise [Bodhi::ContextErrors] if the given +context+ is invalid
+      # @raise [Bodhi::ApiErrors] if any response status is NOT 200
+      # @example
       #   Resource.find_all(context) # => [#<Resource:0x007fbff403e808>, #<Resource:0x007fbff403e808>, ...]
       def find_all(context=nil)
         if context.nil?
@@ -144,10 +222,19 @@ module Bodhi
       end
       alias :all :find_all
 
-      # Aggregates the given resource based on the supplied +pipeline+
-      # 
-      #   context = Bodhi::Context.new
-      #   Resource.aggregate(context, "[{ $match: { property: { $gte: 20 }}}]")
+      # Performs MongoDB aggregations using the given +pipeline+
+      #
+      # Equivalent CURL command:
+      #   curl -u {username}:{password} https://{server}/{namespace}/resources/{resource}/aggregate?pipeline={pipeline}
+      # @note Large aggregations can be very time and resource intensive!
+      # @param context [Bodhi::Context]
+      # @param pipeline [String]
+      # @return [Hash] the JSON response converted to a Ruby Hash
+      # @raise [ArgumentError] if the given +pipeline+ is NOT a +String+
+      # @raise [Bodhi::ContextErrors] if the given +context+ is invalid
+      # @raise [Bodhi::ApiErrors] if any response status is NOT +200+
+      # @example
+      #   Resource.aggregate(context, "[{ $match: { age: { $gte: 21 }}}]")
       def aggregate(context, pipeline)
         if context.invalid?
           raise Bodhi::ContextErrors.new(context.errors.messages), context.errors.to_a.to_s
@@ -169,11 +256,14 @@ module Bodhi
         result.body
       end
 
-      # Returns a Bodhi::Query object for quering the given Resource
-      # 
+      # Returns a {Bodhi::Query} object with the given +query+
+      #
+      # @param query [Hash] the MongoDB query operations
+      # @return [Bodhi::Query<Bodhi::Resource>] a {Bodhi::Query} object, bound to the {Bodhi::Resource} with the given +query+
+      # @example
       #   context = Bodhi::Context.new
-      #   Resource.where("{property: 'value'}").from(context).all
-      #   Resource.where("{conditions}").and("{more conditions}").limit(10).from(context).all
+      #   Resource.where({conditions}).from(context).all
+      #   Resource.where({conditions}).and({more conditions}).limit(10).from(context).all
       def where(query)
         query_obj = Bodhi::Query.new(name)
         query_obj.where(query)
@@ -181,145 +271,211 @@ module Bodhi
       end
     end
 
-    module InstanceMethods
-      # Saves the resource to the Bodhi Cloud.  Returns true if record was saved
-      # 
-      #   obj = Resource.new
-      #   obj.save # => true
-      #   obj.persisted? # => true
-      def save
-        if invalid?
-          return false
-        end
-
-        if bodhi_context.nil?
-          @bodhi_context = Bodhi::Context.global_context
-        end
+    # POST the record to the IoT Platform.  Returns +true+ if record was saved correctly.
+    #
+    # Equivalent CURL command:
+    #   curl -u {username}:{password} -X POST -H "Content-Type: application/json" \
+    #   https://{server}/{namespace}/resources/{resource} \
+    #   -d '{properties}'
+    # @return [Boolean]
+    # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+    # @example
+    #   obj = Resource.new
+    #   obj.save # => true
+    #   obj.persisted? # => true
+    def save
+      if invalid?
+        return false
+      end
 
-        if bodhi_context.invalid?
-          raise Bodhi::ContextErrors.new(bodhi_context.errors.messages), bodhi_context.errors.to_a.to_s
-        end
+      if bodhi_context.nil?
+        @bodhi_context = Bodhi::Context.global_context
+      end
 
-        result = bodhi_context.connection.post do |request|
-          request.url "/#{bodhi_context.namespace}/resources/#{self.class}"
-          request.headers['Content-Type'] = 'application/json'
-          request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
-          request.body = attributes.to_json
-        end
-  
-        if result.status != 201
-          raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
-        end
+      if bodhi_context.invalid?
+        raise Bodhi::ContextErrors.new(bodhi_context.errors.messages), bodhi_context.errors.to_a.to_s
+      end
 
-        if result.headers['location']
-          @sys_id = result.headers['location'].match(/(?<id>[a-zA-Z0-9]{24})/)[:id]
-        end
+      result = bodhi_context.connection.post do |request|
+        request.url "/#{bodhi_context.namespace}/resources/#{self.class}"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
+        request.body = attributes.to_json
+      end
 
-        true
+      if result.headers['location']
+        @sys_id = result.headers['location'].match(/(?<id>[a-zA-Z0-9]{24})/)[:id]
       end
 
-      # Saves the resource to the Bodhi Cloud.  Raises ArgumentError if record could not be saved.
-      # 
-      #   obj = Resouce.new
-      #   obj.save!
-      #   obj.persisted? # => true
-      def save!
-        if bodhi_context.invalid?
-          raise Bodhi::ContextErrors.new(bodhi_context.errors.messages), bodhi_context.errors.to_a.to_s
-        end
+      true
+    end
 
-        result = bodhi_context.connection.post do |request|
-          request.url "/#{bodhi_context.namespace}/resources/#{self.class}"
-          request.headers['Content-Type'] = 'application/json'
-          request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
-          request.body = attributes.to_json
-        end
-  
-        if result.status != 201
-          raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
-        end
+    # POST the record to the IoT Platform.  Raises error if record could not be saved
+    #
+    # Equivalent CURL command:
+    #   curl -u {username}:{password} -X POST -H "Content-Type: application/json" \
+    #   https://{server}/{namespace}/resources/{resource} \
+    #   -d '{properties}'
+    # @return [nil]
+    # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+    # @raise [Bodhi::ApiErrors] if the response status is NOT +201+
+    # @example
+    #   obj = Resource.new
+    #   obj.save # => true
+    #   obj.persisted? # => true
+    def save!
+      if bodhi_context.invalid?
+        raise Bodhi::ContextErrors.new(bodhi_context.errors.messages), bodhi_context.errors.to_a.to_s
+      end
 
-        if result.headers['location']
-          @sys_id = result.headers['location'].match(/(?<id>[a-zA-Z0-9]{24})/)[:id]
-        end
+      result = bodhi_context.connection.post do |request|
+        request.url "/#{bodhi_context.namespace}/resources/#{self.class}"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
+        request.body = attributes.to_json
       end
 
-      def delete!
-        result = bodhi_context.connection.delete do |request|
-          request.url "/#{bodhi_context.namespace}/resources/#{self.class}/#{sys_id}"
-          request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
-        end
-  
-        if result.status != 204
-          raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
-        end
+      if result.status != 201
+        raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
       end
-      alias :destroy :delete!
 
-      def update!(params)
-        update_attributes(params)
+      if result.headers['location']
+        @sys_id = result.headers['location'].match(/(?<id>[a-zA-Z0-9]{24})/)[:id]
+      end
 
-        if invalid?
-          return false
-        end
+      return nil
+    end
 
-        result = bodhi_context.connection.put do |request|
-          request.url "/#{bodhi_context.namespace}/resources/#{self.class}/#{sys_id}"
-          request.headers['Content-Type'] = 'application/json'
-          request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
-          request.body = attributes.to_json
-        end
+    # DELETE the record from the IoT Platform.  Raises error if record could not be deleted
+    #
+    # Equivalent CURL command:
+    #   curl -u {username}:{password} -X DELETE https://{server}/{namespace}/resources/{resource}/{sys_id}
+    # @return [nil]
+    # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+    # @raise [Bodhi::ApiErrors] if the response status is NOT +204+
+    # @example
+    #   #given:  obj.persisted? # => true
+    #   obj.delete! # => nil
+    def delete!
+      result = bodhi_context.connection.delete do |request|
+        request.url "/#{bodhi_context.namespace}/resources/#{self.class}/#{sys_id}"
+        request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
+      end
 
-        if result.status != 204
-          raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
-        end
+      if result.status != 204
+        raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
+      end
 
-        true
+      return nil
+    end
+    alias :destroy :delete!
+
+    # PUT an updated version of the record to the IoT Platform.  Raises error if record could not be updated
+    #
+    # Equivalent CURL command:
+    #   curl -u {username}:{password} -X PUT -H "Content-Type: application/json" \
+    #   https://{server}/{namespace}/resources/{resource}/{sys_id} \
+    #   -d '{updated properties}'
+    # @param properties [Hash] Key/Value pairs of the properties to update
+    # @return [nil]
+    # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+    # @raise [Bodhi::ApiErrors] if the response status is NOT +204+
+    # @example
+    #   #given:  obj.persisted? # => true
+    #   obj.update!(foo: "test", bar: 12345) # => nil
+    def update!(properties)
+      update_attributes(properties)
+
+      if invalid?
+        return false
       end
-      alias :update :update!
 
-      def upsert!(params={})
-        update_attributes(params)
+      result = bodhi_context.connection.put do |request|
+        request.url "/#{bodhi_context.namespace}/resources/#{self.class}/#{sys_id}"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
+        request.body = attributes.to_json
+      end
 
-        if invalid?
-          return false
-        end
+      if result.status != 204
+        raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
+      end
 
-        result = bodhi_context.connection.put do |request|
-          request.url "/#{bodhi_context.namespace}/resources/#{self.class}?upsert=true"
-          request.headers['Content-Type'] = 'application/json'
-          request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
-          request.body = attributes.to_json
-        end
+      true
+    end
+    alias :update :update!
+
+
+    # Create or Update an existing record on the IoT Platform.  Raises error if record could not be updated
+    #
+    # Equivalent CURL command:
+    #   curl -u {username}:{password} -X PUT -H "Content-Type: application/json" \
+    #   https://{server}/{namespace}/resources/{resource}/{sys_id} \
+    #   -d '{updated properties}'
+    # @param properties [Hash] Key/Value pairs of the properties to update
+    # @return [nil]
+    # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+    # @raise [Bodhi::ApiErrors] if the response status is NOT +204+ OR +201+
+    # @example
+    #   #given:  obj.persisted? # => true
+    #   obj.upsert!(foo: "test", bar: 12345) # => nil
+    def upsert!(properties={})
+      update_attributes(properties)
+
+      if invalid?
+        return false
+      end
 
-        unless [204, 201].include?(result.status)
-          raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
-        end
+      result = bodhi_context.connection.put do |request|
+        request.url "/#{bodhi_context.namespace}/resources/#{self.class}?upsert=true"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
+        request.body = attributes.to_json
+      end
 
-        if result.headers['location']
-          @sys_id = result.headers['location'].match(/(?<id>[a-zA-Z0-9]{24})/)[:id]
-        end
+      unless [204, 201].include?(result.status)
+        raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
       end
-      alias :upsert :upsert!
-
-      def patch!(params)
-        result = bodhi_context.connection.patch do |request|
-          request.url "/#{bodhi_context.namespace}/resources/#{self.class}/#{sys_id}"
-          request.headers['Content-Type'] = 'application/json'
-          request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
-          request.body = params.to_json
-        end
-  
-        if result.status != 204
-          raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
-        end
+
+      if result.headers['location']
+        @sys_id = result.headers['location'].match(/(?<id>[a-zA-Z0-9]{24})/)[:id]
+      end
+    end
+    alias :upsert :upsert!
+
+
+    # PATCH an existing record on the IoT Platform.  Raises error if record could not be updated
+    #
+    # Equivalent CURL command:
+    #   curl -u {username}:{password} -X PATCH -H "Content-Type: application/json" \
+    #   https://{server}/{namespace}/resources/{resource}/{sys_id} \
+    #   -d '[{operation1}, {operation2}, ...]'
+    #
+    # @note This method will not update the object after patching.  Only the record on the IoT Platform will be updated.
+    # @param operations [Array<Hash>] Array of PATCH operations
+    # @return [nil]
+    # @raise [Bodhi::ContextErrors] if the given +Bodhi::Context+ is invalid
+    # @raise [Bodhi::ApiErrors] if the response status is NOT +204+ OR +201+
+    # @example
+    #   #given:  obj.persisted? # => true
+    #   obj.upsert!(foo: "test", bar: 12345) # => nil
+    def patch!(operations)
+      result = bodhi_context.connection.patch do |request|
+        request.url "/#{bodhi_context.namespace}/resources/#{self.class}/#{sys_id}"
+        request.headers['Content-Type'] = 'application/json'
+        request.headers[bodhi_context.credentials_header] = bodhi_context.credentials
+        request.body = operations.to_json
+      end
+
+      if result.status != 204
+        raise Bodhi::ApiErrors.new(body: result.body, status: result.status), "status: #{result.status}, body: #{result.body}"
       end
     end
 
     def self.included(base)
       base.extend(ClassMethods)
-      base.include(InstanceMethods, Bodhi::Properties, Bodhi::Associations, Bodhi::Validations, Bodhi::Indexes, Bodhi::Factories)
+      base.include(Bodhi::Properties, Bodhi::Associations, Bodhi::Validations, Bodhi::Indexes, Bodhi::Factories)
       base.instance_variable_set(:@embedded, false)
     end
   end
-end
+end