active-fedora 3.2.0.pre3 → 3.2.0.pre4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    active-fedora (3.2.0.pre3)
+    active-fedora (3.2.0.pre4)
       activeresource (>= 3.0.0)
       activesupport (>= 3.0.0)
       equivalent-xml

data/History.txt

@@ -1,5 +1,8 @@
 3.2.0
 
+Added ActiveModel validations.
+Added callbacks on initialize, save, update, create, delete and find
+Added Base.create
 HYDRA-730 ActiveFedora isn't being initialized unless it is specified in the project Gemfile
 Don't create pids until save
 inspect and equality methods

data/active-fedora.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |s|
   s.name        = "active-fedora"
   s.version     = ActiveFedora::VERSION
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Matt Zumwalt", "McClain Looney"]
+  s.authors     = ["Matt Zumwalt", "McClain Looney", "Justin Coyne"]
   s.email       = ["matt.zumwalt@yourmediashelf.com"]
   s.homepage    = %q{http://yourmediashelf.com/activefedora}
   s.summary     = %q{A convenience libary for manipulating MODS (Metadata Object Description Schema) documents.}

data/lib/active_fedora.rb

@@ -17,6 +17,7 @@ module ActiveFedora #:nodoc:
     autoload :AttributeMethods
     autoload :Base
     autoload :ContentModel
+    autoload :Callbacks
     autoload :Reflection
     autoload :Relationships
     autoload :FileManagement
@@ -25,11 +26,13 @@ module ActiveFedora #:nodoc:
     autoload :Delegating
     autoload :DigitalObject
     autoload :UnsavedDigitalObject
+    autoload :SolrDigitalObject
     autoload :Model
     autoload :MetadataDatastream
     autoload :MetadataDatastreamHelper
     autoload :NokogiriDatastream
     autoload :Property
+    autoload :Persistence
     autoload :QualifiedDublinCoreDatastream
     autoload :RelsExtDatastream
     autoload :ServiceDefinitions
@@ -39,6 +42,7 @@ module ActiveFedora #:nodoc:
     autoload :DatastreamCollections
     autoload :NamedRelationships
     autoload :Predicates
+    autoload :Validations
 
   end
   

data/lib/active_fedora/base.rb

@@ -101,30 +101,40 @@ module ActiveFedora
       end
     end
 
-    # Constructor. If +attrs+  does  not comtain +:pid+, we assume we're making a new one,
-    # and call off to the Fedora Rest API for the next available Fedora pid, and mark as new object.
+    # Constructor.  You may supply a custom +:pid+, or we call the Fedora Rest API for the
+    # next available Fedora pid, and mark as new object.
     # Also, if +attrs+ does not contain +:pid+ but does contain +:namespace+ it will pass the
     # +:namespace+ value to Fedora::Repository.nextid to generate the next pid available within
     # the given namespace.
-    # 
-    # If there is a pid, we're re-hydrating an existing object, and new object is false. Once the @inner_object is stored,
-    # we configure any defined datastreams.
     def initialize(attrs = nil)
       attrs = {} if attrs.nil?
       attributes = attrs.dup
-      @inner_object = attributes.delete(:inner_object)
-      unless @inner_object
-        if attributes[:pid]
-          @inner_object = DigitalObject.find(self.class, attributes[:pid])
-        else
-          @inner_object = UnsavedDigitalObject.new(self.class, attributes.delete(:namespace))
-          self.relationships_loaded = true
-        end
-      end
+      @inner_object = UnsavedDigitalObject.new(self.class, attributes.delete(:namespace), attributes.delete(:pid))
+      self.relationships_loaded = true
       load_datastreams
 
-      [:pid, :new_object,:create_date, :modified_date].each { |k| attributes.delete(k)}
+      [:new_object,:create_date, :modified_date].each { |k| attributes.delete(k)}
       self.attributes=attributes
+      run_callbacks :initialize
+    end
+
+
+    # Initialize an empty model object and set the +inner_obj+
+    # example:
+    #
+    #   class Post < ActiveFedora::Base
+    #     has_metadata :name => "properties", :type => ActiveFedora::MetadataDatastream
+    #   end
+    #
+    #   post = Post.allocate
+    #   post.init_with(DigitalObject.find(pid))
+    #   post.properties.title # => 'hello world'
+    def init_with(inner_obj)
+      @inner_object = inner_obj
+      load_datastreams
+      run_callbacks :find
+      run_callbacks :initialize
+      self
     end
 
     def self.datastream_class_for_name(dsid)
@@ -139,6 +149,11 @@ module ActiveFedora
       ds_specs[args[:name]]= {:type => args[:type], :label =>  args.fetch(:label,""), :control_group => args.fetch(:control_group,"X"), :disseminator => args.fetch(:disseminator,""), :url => args.fetch(:url,""),:block => block}
     end
 
+    def self.create(args)
+      obj = self.new(args)
+      obj.save
+      obj
+    end
 
     ## Given a method name, return the best-guess dsid
     def corresponding_datastream_name(method_name)
@@ -149,61 +164,7 @@ module ActiveFedora
       nil
     end
 
-    #Saves a Base object, and any dirty datastreams, then updates 
-    #the Solr index for this object.
-    def save
-
-      # If it's a new object, set the conformsTo relationship for Fedora CMA
-      if new_object? 
-        result = create
-      else
-        result = update
-      end
-      self.update_index if @metadata_is_dirty == true && ENABLE_SOLR_UPDATES
-      @metadata_is_dirty = false
-      return result
-    end
-
-    def save!
-      save
-    end
     
-    # Refreshes the object's info from Fedora
-    # Note: Currently just registers any new datastreams that have appeared in fedora
-    def refresh
-#      inner_object.load_attributes_from_fedora
-    end
-
-    #Deletes a Base object, also deletes the info indexed in Solr, and 
-    #the underlying inner_object.  If this object is held in any relationships (ie inbound relationships
-    #outside of this object it will remove it from those items rels-ext as well
-    def delete
-      inbound_relationships(:objects).each_pair do |predicate, objects|
-        objects.each do |obj|
-          if obj.respond_to?(:remove_relationship)
-            obj.remove_relationship(predicate,self)
-            obj.save
-          end 
-        end
-      end
-      
-      #Fedora::Repository.instance.delete(@inner_object)
-      pid = self.pid ## cache so it's still available after delete
-      begin
-        @inner_object.delete
-      rescue RestClient::ResourceNotFound =>e
-        raise ObjectNotFoundError, "Unable to find #{pid} in the repository"
-      end
-      if ENABLE_SOLR_UPDATES
-        ActiveFedora::SolrService.instance.conn.delete(pid) 
-        # if defined?( Solrizer::Solrizer ) 
-        #   solrizer = Solrizer::Solrizer.new
-        #   solrizer.solrize_delete(pid)
-        # end
-      end
-    end
-
-
     #
     # Datastream Management
     #
@@ -445,12 +406,6 @@ module ActiveFedora
       @inner_object.new? ? Time.now : @inner_object.profile["objLastModDate"]
     end
 
-    #return the error list of the inner object (unless it's a new object)
-    def errors
-      #@inner_object.errors
-      []
-    end
-    
     #return the label of the inner object (unless it's a new object)
     def label
       @inner_object.label
@@ -546,7 +501,7 @@ module ActiveFedora
       unless klass.ancestors.include? ActiveFedora::Base
         raise "Cannot adapt #{self.class.name} to #{klass.name}: Not a ActiveFedora::Base subclass"
       end
-      klass.new({:inner_object=>inner_object})
+      klass.allocate.init_with(inner_object)
     end
     # ** EXPERIMENTAL **
     #
@@ -574,7 +529,7 @@ module ActiveFedora
      
       create_date = solr_doc[ActiveFedora::SolrService.solr_name(:system_create, :date)].nil? ? solr_doc[ActiveFedora::SolrService.solr_name(:system_create, :date).to_s] : solr_doc[ActiveFedora::SolrService.solr_name(:system_create, :date)]
       modified_date = solr_doc[ActiveFedora::SolrService.solr_name(:system_create, :date)].nil? ? solr_doc[ActiveFedora::SolrService.solr_name(:system_modified, :date).to_s] : solr_doc[ActiveFedora::SolrService.solr_name(:system_modified, :date)]
-      obj = self.new({:pid=>solr_doc[SOLR_DOCUMENT_ID],:create_date=>create_date,:modified_date=>modified_date})
+      obj = self.allocate.init_with(SolrDigitalObject.new(:pid=>solr_doc[SOLR_DOCUMENT_ID],:create_date=>create_date,:modified_date=>modified_date))
       #set by default to load any dependent relationship objects from solr as well
       #need to call rels_ext once so it exists when iterating over datastreams
       obj.rels_ext
@@ -586,24 +541,6 @@ module ActiveFedora
       obj
     end
 
-    # Updates Solr index with self.
-    def update_index
-      if defined?( Solrizer::Fedora::Solrizer ) 
-        #logger.info("Trying to solrize pid: #{pid}")
-        solrizer = Solrizer::Fedora::Solrizer.new
-        solrizer.solrize( self )
-      else
-        #logger.info("Trying to update solr for pid: #{pid}")
-        SolrService.instance.conn.update(self.to_solr)
-      end
-    end
-
-
-    def update_attributes(properties)
-      self.attributes=properties
-      save
-    end
-
     # A convenience method  for updating indexed attributes.  The passed in hash
     # must look like this : 
     #   {{:name=>{"0"=>"a","1"=>"b"}}
@@ -680,11 +617,6 @@ module ActiveFedora
       end
     end
     
-    # This can be overriden to assert a different model
-    # It's normally called once in the lifecycle, by #create#
-    def assert_content_model
-      add_relationship(:has_model, ActiveFedora::ContentModel.pid_from_ruby_class(self.class))
-    end
 
     private
     def configure_defined_datastreams
@@ -727,39 +659,16 @@ module ActiveFedora
       end
     end
 
-
-    
-    # Deals with preparing new object to be saved to Fedora, then pushes it and its datastreams into Fedora. 
-    def create
-      @inner_object = @inner_object.save #replace the unsaved digital object with a saved digital object
-      assert_content_model
-      @metadata_is_dirty = true
-      update
-    end
-    
-    # Pushes the object and all of its new or dirty datastreams into Fedora
-    def update
-      datastreams.each {|k, ds| ds.serialize! }
-      @metadata_is_dirty = datastreams.any? {|k,ds| ds.changed? && (ds.class.included_modules.include?(ActiveFedora::MetadataDatastreamHelper) || ds.instance_of?(ActiveFedora::RelsExtDatastream))}
-
-      result = @inner_object.save
-
-      ### Rubydora re-inits the datastreams after a save, so ensure our copy stays in synch
-      @inner_object.datastreams.each do |dsid, ds|
-        datastreams[dsid] = ds
-        ds.model = self if ds.kind_of? RelsExtDatastream
-      end 
-      refresh
-      return !!result
-    end
-
   end
 
   Base.class_eval do
+    include ActiveFedora::Persistence
     include Model
     include Solrizer::FieldNameMapper
     include Loggable
     include ActiveModel::Conversion
+    include Validations
+    include Callbacks
     extend ActiveModel::Naming
     include Delegating
     include Associations

data/lib/active_fedora/callbacks.rb

@@ -0,0 +1,252 @@
+require 'active_support/core_ext/array/wrap'
+
+module ActiveFedora
+  # = Active Fedora Callbacks, adapted from ActiveRecord
+  #
+  # Callbacks are hooks into the life cycle of an Active Fedora object that allow you to trigger logic
+  # before or after an alteration of the object state. This can be used to make sure that associated and
+  # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes
+  # before they're validated (by overwriting +before_validation+). As an example of the callbacks initiated, consider
+  # the <tt>Base#save</tt> call for a new record:
+  #
+  # * (-) <tt>save</tt>
+  # * (-) <tt>valid</tt>
+  # * (1) <tt>before_validation</tt>
+  # * (-) <tt>validate</tt>
+  # * (2) <tt>after_validation</tt>
+  # * (3) <tt>before_save</tt>
+  # * (4) <tt>before_create</tt>
+  # * (-) <tt>create</tt>
+  # * (5) <tt>after_create</tt>
+  # * (6) <tt>after_save</tt>
+  # * (7) <tt>after_commit</tt>
+  #
+  # Lastly an <tt>after_find</tt> and <tt>after_initialize</tt> callback is triggered for each object that 
+  # is found and instantiated by a finder, with <tt>after_initialize</tt> being triggered after new objects
+  # are instantiated as well.
+  #
+  # That's a total of twelve callbacks, which gives you immense power to react and prepare for each state in the
+  # Active Fedora life cycle. The sequence for calling <tt>Base#save</tt> for an existing record is similar,
+  # except that each <tt>_create</tt> callback is replaced by the corresponding <tt>_update</tt> callback.
+  #
+  # Examples:
+  #   class CreditCard < ActiveFedora::Base
+  #     # Strip everything but digits, so the user can specify "555 234 34" or
+  #     # "5552-3434" or both will mean "55523434"
+  #     before_validation(:on => :create) do
+  #       self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number")
+  #     end
+  #   end
+  #
+  #   class Subscription < ActiveFedora::Base
+  #     before_create :record_signup
+  #
+  #     private
+  #       def record_signup
+  #         self.signed_up_on = Date.today
+  #       end
+  #   end
+  #
+  #
+  # == Inheritable callback queues
+  #
+  # Besides the overwritable callback methods, it's also possible to register callbacks through the
+  # use of the callback macros. Their main advantage is that the macros add behavior into a callback
+  # queue that is kept intact down through an inheritance hierarchy.
+  #
+  #   class Topic < ActiveFedora::Base
+  #     before_delete :destroy_author
+  #   end
+  #
+  #   class Reply < Topic
+  #     before_delete :destroy_readers
+  #   end
+  #
+  # Now, when <tt>Topic#delete</tt> is run only +destroy_author+ is called. When <tt>Reply#delete</tt> is
+  # run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the following situation
+  # where the +before_delete+ method is overridden:
+  #
+  #   class Topic < ActiveFedora::Base
+  #     def before_delete() destroy_author end
+  #   end
+  #
+  #   class Reply < Topic
+  #     def before_delete() destroy_readers end
+  #   end
+  #
+  # In that case, <tt>Reply#delete</tt> would only run +destroy_readers+ and _not_ +destroy_author+.
+  # So, use the callback macros when you want to ensure that a certain callback is called for the entire
+  # hierarchy, and use the regular overwriteable methods when you want to leave it up to each descendant
+  # to decide whether they want to call +super+ and trigger the inherited callbacks.
+  #
+  # *IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the
+  # callbacks before specifying the associations. Otherwise, you might trigger the loading of a
+  # child before the parent has registered the callbacks and they won't be inherited.
+  #
+  # == Types of callbacks
+  #
+  # There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects,
+  # inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects
+  # are the recommended approaches, inline methods using a proc are sometimes appropriate (such as for
+  # creating mix-ins), and inline eval methods are deprecated.
+  #
+  # The method reference callbacks work by specifying a protected or private method available in the object, like this:
+  #
+  #   class Topic < ActiveFedora::Base
+  #     before_delete :delete_parents
+  #
+  #     private
+  #       def delete_parents
+  #         self.class.delete_all "parent_id = #{id}"
+  #       end
+  #   end
+  #
+  # The callback objects have methods named after the callback called with the record as the only parameter, such as:
+  #
+  #   class BankAccount < ActiveFedora::Base
+  #     before_save      EncryptionWrapper.new
+  #     after_save       EncryptionWrapper.new
+  #     after_initialize EncryptionWrapper.new
+  #   end
+  #
+  #   class EncryptionWrapper
+  #     def before_save(record)
+  #       record.credit_card_number = encrypt(record.credit_card_number)
+  #     end
+  #
+  #     def after_save(record)
+  #       record.credit_card_number = decrypt(record.credit_card_number)
+  #     end
+  #
+  #     alias_method :after_find, :after_save
+  #
+  #     private
+  #       def encrypt(value)
+  #         # Secrecy is committed
+  #       end
+  #
+  #       def decrypt(value)
+  #         # Secrecy is unveiled
+  #       end
+  #   end
+  #
+  # So you specify the object you want messaged on a given callback. When that callback is triggered, the object has
+  # a method by the name of the callback messaged. You can make these callbacks more flexible by passing in other
+  # initialization data such as the name of the attribute to work with:
+  #
+  #   class BankAccount < ActiveFedora::Base
+  #     before_save      EncryptionWrapper.new("credit_card_number")
+  #     after_save       EncryptionWrapper.new("credit_card_number")
+  #     after_initialize EncryptionWrapper.new("credit_card_number")
+  #   end
+  #
+  #   class EncryptionWrapper
+  #     def initialize(attribute)
+  #       @attribute = attribute
+  #     end
+  #
+  #     def before_save(record)
+  #       record.send("#{@attribute}=", encrypt(record.send("#{@attribute}")))
+  #     end
+  #
+  #     def after_save(record)
+  #       record.send("#{@attribute}=", decrypt(record.send("#{@attribute}")))
+  #     end
+  #
+  #     alias_method :after_find, :after_save
+  #
+  #     private
+  #       def encrypt(value)
+  #         # Secrecy is committed
+  #       end
+  #
+  #       def decrypt(value)
+  #         # Secrecy is unveiled
+  #       end
+  #   end
+  #
+  # The callback macros usually accept a symbol for the method they're supposed to run, but you can also
+  # pass a "method string", which will then be evaluated within the binding of the callback. Example:
+  #
+  #   class Topic < ActiveFedora::Base
+  #     before_delete 'self.class.delete_all "parent_id = #{id}"'
+  #   end
+  #
+  # Notice that single quotes (') are used so the <tt>#{id}</tt> part isn't evaluated until the callback
+  # is triggered. Also note that these inline callbacks can be stacked just like the regular ones:
+  #
+  #   class Topic < ActiveFedora::Base
+  #     before_delete 'self.class.delete_all "parent_id = #{id}"',
+  #                    'puts "Evaluated after parents are deleted"'
+  #   end
+  #
+  # == <tt>before_validation*</tt> returning statements
+  #
+  # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be
+  # aborted and <tt>Base#save</tt> will return +false+. If Base#save! is called it will raise a
+  # ActiveFedora::RecordInvalid exception. Nothing will be appended to the errors object.
+  #
+  # == Canceling callbacks
+  #
+  # If a <tt>before_*</tt> callback returns +false+, all the later callbacks and the associated action are
+  # cancelled. If an <tt>after_*</tt> callback returns +false+, all the later callbacks are cancelled.
+  # Callbacks are generally run in the order they are defined, with the exception of callbacks defined as
+  # methods on the model, which are called last.
+  #
+  # == Debugging callbacks
+  # 
+  # The callback chain is accessible via the <tt>_*_callbacks</tt> method on an object. ActiveModel Callbacks support 
+  # <tt>:before</tt>, <tt>:after</tt> and <tt>:around</tt> as values for the <tt>kind</tt> property. The <tt>kind</tt> property
+  # defines what part of the chain the callback runs in.
+  # 
+  # To find all callbacks in the before_save callback chain: 
+  # 
+  #   Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }
+  # 
+  # Returns an array of callback objects that form the before_save chain.
+  # 
+  # To further check if the before_save chain contains a proc defined as <tt>rest_when_dead</tt> use the <tt>filter</tt> property of the callback object:
+  # 
+  #   Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }.collect(&:filter).include?(:rest_when_dead)
+  # 
+  # Returns true or false depending on whether the proc is contained in the before_save callback chain on a Topic model.
+  # 
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    CALLBACKS = [
+      :after_initialize, :after_find, :before_validation, :after_validation,
+      :before_save, :around_save, :after_save, :before_create, :around_create,
+      :after_create, :before_update, :around_update, :after_update,
+      :before_delete, :around_delete, :after_delete
+    ]
+
+    included do
+      extend ActiveModel::Callbacks
+      include ActiveModel::Validations::Callbacks
+
+      define_model_callbacks :initialize, :find, :only => :after
+      define_model_callbacks :save, :create, :update, :delete
+    end
+
+    def destroy #:nodoc:
+      run_callbacks(:destroy) { super }
+    end
+
+    def save #:nodoc:
+      run_callbacks(:save) { super }
+    end
+
+  private
+
+
+    def create #:nodoc:
+      run_callbacks(:create) { super }
+    end
+
+    def update(*) #:nodoc:
+      run_callbacks(:update) { super }
+    end
+  end
+end
+