pod4 0.10.6 → 1.0.0

data/lib/pod4/model.rb

@@ -1,8 +1,8 @@
-require 'octothorpe'
+require "octothorpe"
 
-require_relative 'basic_model'
-require_relative 'errors'
-require_relative 'alert'
+require_relative "basic_model"
+require_relative "errors"
+require_relative "alert"
 
 
 module Pod4
@@ -112,7 +112,7 @@ module Pod4
       # :id -- otherwise we raise a Pod4Error.
       #
       # Note also that while list returns an array of model objects, `read` has _not_ been run
-      # against each object. The data is there, but @model_status == :empty, and validation has not
+      # against each object. The data is there, but @model_status == :unknown, and validation has not
       # been run.  This is partly for the sake of efficiency, partly to help avoid recursive loops
       # in validation.
       #
@@ -136,7 +136,7 @@ module Pod4
 
       def test_for_invalid_status(action, status)
         raise( Pod4Error, "Invalid model status for an action of #{action}", caller ) \
-          if [:empty, :deleted].include? status
+          if [:unknown, :deleted].include? status
 
       end
 
@@ -159,13 +159,13 @@ module Pod4
     ##
     # Call this to write a new record to the data source.
     #
-    # Note: create needs to set @id. But interface.create should return it, so that's okay.
+    # Note: create needs to set @model_id. But interface.create should return it, so that's okay.
     #
     def create
       run_validation(:create)
       @model_id = interface.create(map_to_interface) unless @model_status == :error
 
-      @model_status = :okay if @model_status == :empty
+      @model_status = :okay if @model_status == :unknown
       self
     rescue Pod4::WeakError
       add_alert(:error, $!)
@@ -183,7 +183,7 @@ module Pod4
       else
         map_to_model(r)
         run_validation(:read)
-        @model_status = :okay if @model_status == :empty
+        @model_status = :okay if @model_status == :unknown
       end
 
       self
@@ -201,6 +201,10 @@ module Pod4
       clear_alerts; run_validation(:update)
       interface.update(@model_id, map_to_interface) unless @model_status == :error
 
+      unless interface.id_ai
+        @model_id = instance_variable_get( "@#{interface.id_fld}".to_sym )
+      end
+
       self
     rescue Pod4::WeakError
       add_alert(:error, $!)
@@ -259,11 +263,12 @@ module Pod4
     end
 
     ##
-    # Return an Octothorpe of all the attr_columns attributes.
+    # Return an Octothorpe of all the attr_columns attributes. This includes the ID field, whether
+    # or not it has been named in attr_columns.
     #
     # Override if you want to return any extra data. (You will need to create a new Octothorpe.) 
     #
-    # See also: `set`, `map_to_model', 'map_to_interface'
+    # See also: `set`
     #
     def to_ot
       Octothorpe.new(to_h)
@@ -272,13 +277,11 @@ module Pod4
     ##
     # Used by the interface to set the column values on the model.
     #
-    # Don't use this to set model attributes from your code; use `set`, instead.
-    #
     # By default this does exactly the same as `set`. Override it if you want the model to
     # represent data differently than the data source does -- but then you will have to override
     # `map_to_interface`, too, to convert the data back.
     #
-    # See also: `to_ot`, `map_to_model'
+    # See also: `map_to_interface'
     #
     def map_to_model(ot)
       merge(ot)
@@ -286,19 +289,18 @@ module Pod4
     end
 
     ##
-    # used by the model to get an OT of column values for the interface. 
-    #
-    # Don't use this to get model values in your code; use `to_ot`, instead.# This is called by
-    # model.create and model.update when it needs to write to the data source.
+    # Used by the model to get an OT to pass to the interface on #create and #update.
     #
-    # By default this behaves exactly the same as to_ot. Override it if you want the model to
-    # represent data differently than the data source -- in which case you also need to override
-    # `map_to_model`.
+    # Override it if you want the model to represent data differently than the data source -- in
+    # which case you also need to override `map_to_model`.
     #
     # Bear in mind that any attribute could be nil, and likely will be when `map_to_interface` is
     # called from the create method.
     #
-    # See also: `to_ot`, `set`.
+    # NB: we always pass the ID field to the Interface, regardless of whether the field
+    # autoincrements or whether it's been named in `attr_columns`.
+    #
+    # See also: `map_to_model'
     #
     def map_to_interface
       Octothorpe.new(to_h)
@@ -307,12 +309,15 @@ module Pod4
     private
 
     ##
-    # Output a hash of the columns
+    # Output a hash of the columns.
+    # _Always_ include the ID field, even if it's not an attribute.
     #
     def to_h
-      columns.each_with_object({}) do |col, hash|
+      h = columns.each_with_object({}) do |col, hash|
         hash[col] = instance_variable_get("@#{col}".to_sym)
       end
+
+      {interface.id_fld => @model_id}.merge h
     end
 
     ##
@@ -327,11 +332,11 @@ module Pod4
     end
 
     ##
-    # Call the validate method on the model.  Allow the user to override the method with or without
-    # the vmode paramter, as they choose.
+    # Call the validate method on the model. 
     #
     def run_validation(vmode)
-      method(:validate).arity == 0 ? validate : validate(vmode)
+      validate(vmode)
+      self
     end
 
   end # of Model

data/lib/pod4/nebulous_interface.rb

@@ -1,5 +1,5 @@
-require_relative 'interface'
-require_relative 'errors'
+require_relative "interface"
+require_relative "errors"
 
 
 module Pod4
@@ -8,7 +8,7 @@ module Pod4
   ##
   # An interface to talk to a Nebulous Target.
   #
-  # Each interface can only speak with one target, designated with #set_target.# The developer must
+  # Each interface can only speak with one target, designated with #set_target. The developer must
   # also set a unique ID key using #set_id_fld.
   #
   # The primary challenge here is to map the CRUDL methods (which interfaces contract to implement)
@@ -42,7 +42,7 @@ module Pod4
   # only keys which are symbols are translated to the corresponding values in the record or
   # selection hash; anything else is passed literally in the Nebulous parameter string.
   #
-  # When you subclass NebulousInterfce, you may want to override some or all of the CRUDL methods
+  # When you subclass NebulousInterface, you may want to override some or all of the CRUDL methods
   # so that your callers can pass specific parameters rather than a hash; the above example
   # demonstrates this.
   #
@@ -72,9 +72,13 @@ module Pod4
   #       self
   #     end
   #
+  # NB: Connections: Nebulous does not use the Connection class. The user must configure
+  # NebulousStomp themselves, once, when their application starts; but they don't need to do this
+  # before requiring the models. And there is no need for a connection pool.
+  #
   class NebulousInterface < Interface
 
-    attr_reader :id_fld
+    attr_reader :id_fld, :id_ai
 
     # The NebulousStomp Message object holding the response from the last message sent, or, nil.
     attr_reader :response 
@@ -91,7 +95,6 @@ module Pod4
     # status for that.
     attr_reader :response_status
 
-
     Verb = Struct.new(:name, :params)
 
 
@@ -118,7 +121,6 @@ module Pod4
 
       def verbs; {}; end
 
-
       ##
       # Set the name of the Nebulous target in the interface definition
       #
@@ -132,18 +134,22 @@ module Pod4
         raise Pod4Error, "You need to use set_target on your interface"
       end
 
-
       ##
       # Set the name of the ID parameter (needs to be in the CRUD verbs param list)
-      def set_id_fld(idFld)
+      def set_id_fld(idFld, opts={})
+        ai = opts.fetch(:autoincrement) { true }
         define_class_method(:id_fld) {idFld}
+        define_class_method(:id_ai)  {!!ai}
       end
 
       def id_fld
         raise Pod4Error, "You need to use set_id_fld"
       end
 
-      
+      def id_ai
+        raise Pod4Error, "You need to use set_id_fld"
+      end
+
       ##
       # Make sure all of the above is consistent
       #
@@ -164,29 +170,26 @@ module Pod4
 
       end
 
-
-    end
-    ##
-
+    end # of class << self
 
     ##
     # In normal operation, takes no parameters.
     #
     # For testing purposes you may pass something here. Whatever it is you pass, it must respond to
-    # a `send` method, take the same parameters as NebulousStomp::Request.new (that is, a target
-    # and a message) and return something that behaves like a NebulousStomp::Request. This method
-    # will be called instead of creating a NebulousStomp::Request directly.
+    # a `send` method, take the same parameters as NebulousStomp::Request.new (that is, a
+    # target and a message) and return something that behaves like a NebulousStomp::Request.
+    # This method will be called instead of creating a NebulousStomp::Request directly.
     #
     def initialize(requestObj=nil)
       @request_object  = requestObj # might as well be a reference 
       @response        = nil
       @response_status = nil
       @id_fld          = self.class.id_fld
+      @id_ai           = self.class.id_ai
 
       self.class.validate_params
     end
 
-
     ##
     # Pass a parameter string or array (which will be taken as the literal Nebulous parameter) or a
     # Hash or Octothorpe (which will be interpreted as per your list of keys set in add_verb
@@ -215,7 +218,6 @@ module Pod4
       handle_error(e)
     end
 
-
     ##
     # Pass a parameter string or an array as the record. returns the ID. We assume that the
     # response to the create message returns the ID as the parameter part of the success verb. If
@@ -224,6 +226,9 @@ module Pod4
     def create(record)
       raise ArgumentError, 'create takes a Hash or an Octothorpe' unless hashy?(record)
 
+      raise ArgumentError, "ID field missing from record" \
+        if !@id_ai && record[@id_fld].nil? && record[@id_fld.to_s].nil?
+
       send_message( verb_for(:create), param_string(:create, record), false )
       @response.params
 
@@ -231,7 +236,6 @@ module Pod4
       handle_error(e)
     end
 
-
     ##
     # Given the id, return an Octothorpe of the record.
     #
@@ -253,7 +257,6 @@ module Pod4
       Octothorpe.new( @response.body.is_a?(Hash) ? @response.body : {} )
     end
 
-
     ##
     # Given an id an a record (Octothorpe or Hash), update the record. Returns self.
     #
@@ -268,7 +271,6 @@ module Pod4
       self
     end
 
-
     ##
     # Given an ID, delete the record. Return self.
     #
@@ -283,7 +285,6 @@ module Pod4
 
       self
     end
-
     
     ##
     # Bonus method: chain this method before a CRUDL method to clear the cache for that parameter
@@ -337,10 +338,8 @@ module Pod4
       handle_error(err)
     end
 
-
     private
 
-
     ##
     # Given :create, :read, :update, :delete or :list, return the Nebulous verb
     #
@@ -348,7 +347,6 @@ module Pod4
       self.class.verbs[action].name
     end
 
-
     ##
     # Work out the parameter string based on the corresponding #set_Verb call. Insert the ID value
     # if given
@@ -365,7 +363,6 @@ module Pod4
       para.join(',')
     end
 
-
     ##
     # Deal with any exceptions that are raised.
     #
@@ -393,7 +390,6 @@ module Pod4
 
     end
 
-
     ##
     # A little helper method to create a response object (unless we were given one for testing
     # purposes), clear the cache if we are supposed to, and then send the message.
@@ -417,12 +413,11 @@ module Pod4
       with_cache ? request.send : request.send_no_cache
     end
 
-
     def hashy?(obj)
       obj.kind_of?(Hash) || obj.kind_of?(Octothorpe)
     end
 
-  end
+  end # of NebulousInterface
 
 
 end

data/lib/pod4/null_interface.rb

@@ -1,7 +1,7 @@
-require 'octothorpe'
+require "octothorpe"
 
-require_relative 'interface'
-require_relative 'errors'
+require_relative "interface"
+require_relative "errors"
 
 
 module Pod4
@@ -13,16 +13,22 @@ module Pod4
   # Example:
   #     class TestModel < Pod4::Model
   #       attr_columns :one, :two
-  #       set_interface NullInterface.new( :one, :two [ {one: 1, two: 2} ] )
+  #       set_interface NullInterface.new( :one, :two [ {one: 1, two: 2},
+  #                                                     {one: 2, two: 4} ] )
   #       ...
   #
-  # The first column passed is taken to be the ID. Note that ID is not auto-assigned; you need to
-  # specify it in the record.
+  # The first column passed is taken to be the ID.  We default to autoincrement = true, as
+  # standard.  Note that ID values for the initial data are not auto-assigned; you need to specify them.
+  #
+  # You can switch to autoincrement = false by setting `interface.id_ai = false`.
+  #
+  # Note: this is quite different from the behaviour before v1.0, where NullInterface effectively
+  # only allowed you to create a non-autoincrement interface.
   #
   class NullInterface < Interface
 
-    attr_reader :id_fld
-
+    attr_reader   :id_fld
+    attr_accessor :id_ai
 
     ##
     # Initialise the interface by passing it a list of columns and an array of hashes to fill them.
@@ -33,12 +39,12 @@ module Pod4
       @cols   = cols.dup.map(&:to_sym)
       @data   = Array.new(data.dup).flatten 
       @id_fld = @cols.first
+      @id_ai  = true
 
     rescue => e
       handle_error(e)
     end
 
-
     ##
     # Selection is a hash, but only the first key/value pair is honoured.
     #
@@ -56,7 +62,6 @@ module Pod4
       handle_error(e)
     end
 
-
     ##
     # Record is a hash of field: value
     #
@@ -65,14 +70,19 @@ module Pod4
     def create(record)
       raise(ArgumentError, "Create requires an ID") if record.nil? || ! record.respond_to?(:to_h)
 
+      raise(ArgumentError, "Record missing ID field") \
+        if !@id_ai && record[@id_fld].nil? && record[@id_fld.to_s].nil?
+
+      datum = record.to_h
+      datum[@id_fld] = (@data.size + 1) if @id_ai
       @data << record.to_h
-      record[@id_fld]
+
+      datum[@id_fld]
 
     rescue => e
       handle_error(e)
     end
 
-
     ##
     # ID is the first column you named in new()
     #
@@ -86,7 +96,6 @@ module Pod4
       handle_error(e)
     end
 
-
     ##
     # ID is the first column you named in new(). Record should be a Hash or Octothorpe.
     # Again, note that we don't care what columns you send us.
@@ -103,7 +112,6 @@ module Pod4
       handle_error(e)
     end
 
-
     ##
     # ID is that first column
     #
@@ -117,10 +125,8 @@ module Pod4
       handle_error(e)
     end
 
-
     private
 
-
     def handle_error(err, kaller=nil)
       kaller ||= caller[1..-1]