my_annotations 0.5.0 → 0.5.1

data/.gitignore

@@ -0,0 +1,6 @@
+test/app_root/log/
+doc/
+created.rid
+*.*~
+.svn/
+*.gem

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use ree-1.8.7-2010.02@annotations

data/AUTHORS.rdoc

@@ -0,0 +1,5 @@
+= Authors
+
+== Original Author
+
+Jiten Bhagat (mailto:mail@jits.co.uk), as part of the BioCatalogue project.

data/CHANGELOG.rdoc

@@ -0,0 +1,64 @@
+= Changelog
+
+== 0.4.1
+* Add +Annotation::include_values+ as a named scope that can be used to potentially improve performance.
+* Added +include_values+ optional argument (default: false) to as many finder methods. This allows you to specify whether value records must be included in the query results or not, and *may* be used to improve performance.
+
+== 0.4.0
+* New config option: +Annotations::Config.value_factories+ - support for value object generation factories per attribute name.
+Example:    
+    Annotations::Config.value_factories["tag"] = Proc.new { |v|
+      case v
+        when String, Symbol
+          Tag.find_or_create_by_name(v.to_s)
+        else
+          v
+      end
+    }
+IMPORTANT: don't use explicit +return+s in your Proc otherwise it will cause the returning method to exit too!
+* The process of generating/setting the annotation's actual value object has been changed to "lazy generate" the actual +value+ object of the annotation. This is now done before validation. NOTE: this still allows +Annotation#value+ (which has been overridden) to be set at any time, but the actual setting of the value association at the ActiveRecord level now happens later.
+* The +process_value_adjustments+ code in the +Annotation+ model now happens BEFORE setting the value association. This prevents the value object from being modified after it's been set. NOTE: this does also mean that it will only run when provided with a String or Symbol.
+* New config option: +Annotations::Config.valid_value_types+ - support for validation checks based on the class of the value object.
+Example:
+    Annotations::Config::valid_value_types["tag"] = "Tag"
+
+== 0.3.1
+* Minor bugfixes
+* +annotations_version_fu+ nows allows reloading of the versioned columns (needed if doing something during a migration).
+
+== 0.3.0
+* +acts_as_annotatable+ now requires you to specify an option - +:name_field+ - on the model that is becoming an annotatable.
+* +acts_as_annotatable+ now exposes an +is_annotatable+ attribute to allow you to check if a model can act as an annotatable. 
+
+== 0.2.1
+* Updated the routes to allow +requirements+ to be passed in.
+
+== 0.2.0
+*Main change*: 
+Annotation values are now polymorphic rather than just plain strings. 
+Some basic +act_as_annotation_value+ models have been introduced for this. 
+Note: this has affected all methods that take in or work with annotation values. 
+See below for further details.
+
+* New mixin module: +acts_as_annotation_value+.
+* New basic annotation value models: +TextValue+ and +NumberValue+ (but note that you can use any model as a value by specifying +acts_as_annotation_value+ on it).
+* Removed +Annotation::find_annotatables_with_attribute_name_and_value+.
+* Removed +Annotation::find_annotatables_with_attribute_names_and_values+.
+* Removed +with_annotations_with_attribute_name_and_value+ in the +acts_as_annotatable+ module.
+* +Annotations::Config::value_restrictions+ has been renamed to +Annotations::Config::content_restrictions+
+* Latest migration version = v3
+* NOTE: the new migration script will keep the old +value+ column data in a new +old_value+ column for EXISTING annotations only. This can be used for verification/text purposes.
+
+== 0.1.1
+* Added +identifier+ to +AnnotationAttribute+. This can be used to specify what ontology term / URI the attribute can be
+  uniquely identified using. See +AnnotationAttribute#before_validation+ for more information on how this identifier
+  will be generated if not specified manually.
+* Changed the +annotations+ association in +act_as_annotation_source+ to +annotations_by+, to fix cases when a model has both
+  +acts_as_annotatable+ AND +acts_as_annotation_source+.
+* Latest migration version = v2
+
+== 0.1.0 (July 23rd 2009)
+* Initial import from the BioCatalogue codebase.
+* Improved documentation. See README.rdoc for more info on features and usage.
+* Latest migration version = v1
+              

data/INDEX.rdoc

@@ -0,0 +1,17 @@
+= Annotations Plugin (for Ruby on Rails applications)
+
+Original Author::   	Jiten Bhagat (mailto:mail@jits.co.uk)
+Copyright::         	(c) 2008-2011, the University of Manchester and the European Bioinformatics Institute (EMBL-EBI)
+License::           	BSD
+Version::           	0.4.1
+
+For information on the plugin and to get started, see README.rdoc
+
+For credits and origins, see AUTHORS.rdoc
+
+For license, see LICENSE
+
+For the latest updates, see CHANGELOG.rdoc
+
+To run the tests in the plugin, see RUNNING_TESTS.rdoc
+

data/generators/annotations_migration/annotations_migration_generator.rb

@@ -0,0 +1,32 @@
+class AnnotationsMigrationGenerator < Rails::Generator::Base
+
+  attr_accessor :version
+
+  def initialize(*runtime_args)
+    super(*runtime_args)
+    if @args[0].nil?
+      @version = "all"
+    else
+      @version = @args[0].downcase
+    end
+  end
+
+  def manifest
+    record do |m|
+      if @version
+        if @version == "all"
+          Dir.chdir(File.join(File.dirname(__FILE__), "templates")) do
+            Dir.glob("*.rb").each do |f|
+              version = f.gsub(/.rb/, '').split('_')[1]
+              m.migration_template "migration_#{version}.rb", 'db/migrate', { :migration_file_name => "annotations_migration_#{version}" }
+              m.sleep 1   # So that the timestamps on the migration are not the same!
+            end
+          end
+        else
+          m.migration_template "migration_#{@version}.rb", 'db/migrate', { :migration_file_name => "annotations_migration_#{@version}" }
+        end
+      end
+    end
+  end
+
+end

data/generators/annotations_migration/templates/migration_v1.rb

@@ -0,0 +1,60 @@
+class AnnotationsMigrationV1 < ActiveRecord::Migration
+  def self.up
+    create_table :annotations, :force => true do |t|
+      t.string    :source_type,         :null => false
+      t.integer   :source_id,           :null => false
+      t.string    :annotatable_type,    :limit => 50, :null => false
+      t.integer   :annotatable_id,      :null => false
+      t.integer   :attribute_id,        :null => false
+      t.text      :value,               :limit => 20000, :null => false
+      t.string    :value_type,          :limit => 50, :null => false
+      t.integer   :version,             :null => false
+      t.integer   :version_creator_id,  :null => true
+      t.timestamps
+    end
+    
+    add_index :annotations, [ :source_type, :source_id ]
+    add_index :annotations, [ :annotatable_type, :annotatable_id ]
+    add_index :annotations, [ :attribute_id ]
+    
+    create_table :annotation_versions, :force => true do |t|
+      t.integer   :annotation_id,       :null => false
+      t.integer   :version,             :null => false
+      t.integer   :version_creator_id,  :null => true
+      t.string    :source_type,         :null => false
+      t.integer   :source_id,           :null => false
+      t.string    :annotatable_type,    :limit => 50, :null => false
+      t.integer   :annotatable_id,      :null => false
+      t.integer   :attribute_id,        :null => false
+      t.text      :value,               :limit => 20000, :null => false
+      t.string    :value_type,          :limit => 50, :null => false
+      t.timestamps
+    end
+    
+    add_index :annotation_versions, [ :annotation_id ]
+    
+    create_table :annotation_attributes, :force => true do |t|
+      t.string :name, :null => false
+      
+      t.timestamps
+    end
+    
+    add_index :annotation_attributes, [ :name ]
+    
+    create_table :annotation_value_seeds, :force => true do |t|
+      t.integer :attribute_id,      :null => false
+      t.string  :value,  :null => false
+      
+      t.timestamps
+    end
+    
+    add_index :annotation_value_seeds, [ :attribute_id ]
+  end
+  
+  def self.down
+    drop_table :annotations
+    drop_table :annotation_versions
+    drop_table :annotation_attributes
+    drop_table :annotation_value_seeds
+  end
+end

data/generators/annotations_migration/templates/migration_v2.rb

@@ -0,0 +1,9 @@
+class AnnotationsMigrationV2 < ActiveRecord::Migration
+  def self.up
+    add_column :annotation_attributes, :identifier, :string, :null => false
+  end
+
+  def self.down
+    remove_column :annotation_attributes, :identifier  
+  end
+end

data/generators/annotations_migration/templates/migration_v3.rb

@@ -0,0 +1,74 @@
+class AnnotationsMigrationV3 < ActiveRecord::Migration
+  def self.up
+    
+    change_table :annotations do |t|
+      t.rename :value, :old_value
+      t.remove :value_type
+      t.string :value_type, :limit => 50, :null => false, :default => "TextValue"
+      t.integer :value_id, :null => false, :default => 0
+    end
+    change_column :annotations, :old_value, :string, :null => true
+    add_index :annotations, [ :value_type, :value_id ]
+    
+    change_table :annotation_versions do |t|
+      t.rename :value, :old_value
+      t.remove :value_type
+      t.string :value_type, :limit => 50, :null => false, :default => "TextValue"
+      t.integer :value_id, :null => false, :default => 0
+    end
+    change_column :annotation_versions, :old_value, :string, :null => true
+    
+    create_table :text_values, :force => true do |t|
+      t.integer :version, :null => false
+      t.integer :version_creator_id, :null => true
+      t.text :text, :limit => 16777214, :null => false
+      t.timestamps
+    end
+    
+    create_table :text_value_versions, :force => true do |t|
+      t.integer :text_value_id, :null => false
+      t.integer :version, :null => false
+      t.integer :version_creator_id, :null => true
+      t.text :text, :limit => 16777214, :null => false
+      t.timestamps
+    end
+    add_index :text_value_versions, [ :text_value_id ]
+    
+    create_table :number_values, :force => true do |t|
+      t.integer :version, :null => false
+      t.integer :version_creator_id, :null => true
+      t.integer :number, :null => false
+      t.timestamps
+    end
+    
+    create_table :number_value_versions, :force => true do |t|
+      t.integer :number_value_id, :null => false
+      t.integer :version, :null => false
+      t.integer :version_creator_id, :null => true
+      t.integer :number, :null => false
+      t.timestamps
+    end
+    add_index :number_value_versions, [ :number_value_id ]
+    
+    # Migrate existing annotations to the v3 db schema
+    # 
+    # TODO: IMPORTANT: please check the comments and logic in
+    # this util method to see if it is what you want.
+    # If you need to change the behaviour, redefine it in your app.
+    Annotation::reset_column_information
+    Annotation::reload_versioned_columns_info
+    Annotations::Util::migrate_annotations_to_v3
+    
+    change_table :annotation_value_seeds do |t|
+      t.rename :value, :old_value
+      t.string :value_type, :limit => 50, :null => false, :default => "FIXME"
+      t.integer :value_id, :null => false, :default => 0
+    end
+    change_column :annotation_value_seeds, :old_value, :string, :null => true
+    
+  end
+
+  def self.down
+    raise ActiveRecord::IrreversibleMigration.new
+  end
+end

data/generators/annotations_migration/templates/migration_v4.rb

@@ -0,0 +1,13 @@
+class AnnotationsMigrationV4 < ActiveRecord::Migration
+  def self.up
+    change_column :annotations,:version,:integer,:null=>true
+    change_column :text_values,:version,:integer,:null=>true
+    change_column :number_values,:version,:integer,:null=>true
+  end
+
+  def self.down
+    change_column :annotations,:version,:integer,:null=>false
+    change_column :text_values,:version,:integer,:null=>false
+    change_column :number_values,:version,:integer,:null=>false
+  end
+end

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/annotations/acts_as_annotatable.rb

@@ -0,0 +1,271 @@
+# ActsAsAnnotatable
+module Annotations
+  module Acts #:nodoc:
+    module Annotatable #:nodoc:
+
+      def self.included(base)
+        base.send :extend, ClassMethods 
+      end
+
+      module ClassMethods
+        def acts_as_annotatable(options)
+          cattr_accessor :annotatable_name_field, :is_annotatable
+          
+          if options[:name_field].blank?
+            raise ArgumentError.new("Must specify the :name_field option that will be used as the field for the name")
+          end
+          
+          self.annotatable_name_field = options[:name_field] 
+          
+          has_many :annotations, 
+                   :as => :annotatable, 
+                   :dependent => :destroy, 
+                   :order => 'updated_at ASC'
+                   
+          __send__ :extend, SingletonMethods
+          __send__ :include, InstanceMethods
+          
+          self.is_annotatable = true
+        end
+      end
+      
+      # Class methods added to the model that has been made acts_as_annotatable (ie: the mixin target class).
+      module SingletonMethods
+        # Helper finder to get all annotations for an object of the mixin annotatable type with the ID provided.
+        # This is the same as object.annotations with the added benefit that the object doesnt have to be loaded.
+        # E.g: Book.find_annotations_for(34) will give all annotations for the Book with ID 34.
+        def find_annotations_for(id, include_values=false)
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self).to_s
+          
+          options = { 
+            :conditions => { :annotatable_type =>  obj_type, 
+                             :annotatable_id => id },
+            :order => "updated_at DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        # Helper finder to get all annotations for all objects of the mixin annotatable type, by the source specified.
+        # E.g: Book.find_annotations_by('User', 10) will give all annotations for all Books by User with ID 10. 
+        def find_annotations_by(source_type, source_id, include_values=false)
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self).to_s
+          
+          options = {
+            :conditions => { :annotatable_type =>  obj_type, 
+                             :source_type => source_type,
+                             :source_id => source_id },
+            :order => "updated_at DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+      end
+      
+      # This module contains instance methods
+      module InstanceMethods
+        
+        # Gets the name of the annotatable object
+        def annotatable_name
+          self.send(self.class.annotatable_name_field)
+        end
+        
+        # Helper method to get latest annotations
+        def latest_annotations(limit=nil, include_values=false)
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self.class).to_s
+          
+          options = {
+            :conditions => { :annotatable_type =>  obj_type, 
+                             :annotatable_id => self.id },
+            :order => "updated_at DESC",
+            :limit => limit
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        # Finder to get annotations with a specific attribute.
+        # The input parameter is the attribute name 
+        # (MUST be a String representing the attribute's name).
+        def annotations_with_attribute(attrib, include_values=false)
+          return [] if attrib.blank?
+          
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self.class).to_s
+          
+          options = {
+            :joins => :attribute,
+            :conditions => { :annotatable_type => obj_type,
+            :annotatable_id => self.id,
+            :annotation_attributes =>  { :name => attrib.strip.downcase } },
+            :order => "updated_at DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        # Same as the {obj}.annotations_with_attribute method (above) but 
+        # takes in an array for attribute names to look for.
+        #
+        # NOTE (1): the argument to this method MUST be an Array of Strings.
+        def annotations_with_attributes(attribs, include_values=false)
+          return [] if attribs.blank?
+          
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self.class).to_s
+          
+          options = {
+            :joins => :attribute,
+            :conditions => { :annotatable_type => obj_type,
+                             :annotatable_id => self.id,
+                             :annotation_attributes =>  { :name => attribs } },
+            :order => "updated_at DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        # Finder to get annotations with a specific attribute by a specific source.
+        #
+        # The first input parameter is the attribute name (MUST be a String representing the attribute's name).
+        # The second input is the source object.
+        def annotations_with_attribute_and_by_source(attrib, source, include_values=false)
+          return [] if attrib.blank? or source.nil?
+          
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self.class).to_s
+          
+          options = {
+            :joins => :attribute,
+            :conditions => { :annotatable_type => obj_type,
+                             :annotatable_id => self.id,
+                             :source_type => source.class.name,
+                             :source_id => source.id,
+                             :annotation_attributes =>  { :name => attrib.strip.downcase } },
+            :order => "updated_at DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        # Finder to get all annotations on this object excluding those that
+        # have the attribute names specified.
+        #
+        # NOTE (1): the argument to this method MUST be an Array of Strings.
+        # NOTE (2): the returned records will be Read Only.
+        def all_annotations_excluding_attributes(attribs, include_values=false)
+          return [] if attribs.blank?
+          
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self.class).to_s
+          
+          options = {
+            :joins => :attribute,
+            :conditions => [ "`annotations`.`annotatable_type` = ? AND `annotations`.`annotatable_id` = ? AND `annotation_attributes`.`name` NOT IN (?)",
+                             obj_type,
+                             self.id,
+                             attribs ],
+            :order => "`annotations`.`updated_at` DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        # Returns the number of annotations on this annotatable object by the source type specified.
+        # "all" (case insensitive) can be provided to get all annotations regardless of source type.
+        # E.g.: book.count_annotations_by("User") or book.count_annotations_by("All")
+        def count_annotations_by(source_type_in)
+          if source_type_in == nil || source_type_in.downcase == "all"
+            return self.annotations.count
+          else
+            return self.annotations.count(:conditions => { :source_type => source_type_in })  
+          end
+        end
+        
+        # Use this method to create many annotations from a Hash of data.
+        # Arrays for Hash values will be converted to multiple annotations.
+        # Blank values (nil or empty string) will be ignored and thus annotations
+        # will not be created for them.
+        #
+        # Returns an array of Annotation objects of the annotations that were
+        # successfully created.
+        #
+        # Code example:
+        # -------------
+        # data = { "tag" => [ "tag1", "tag2", "tag3" ], "description" => "This is a book" }
+        # book.create_annotations(data, current_user)
+        def create_annotations(annotations_data, source)
+          anns = [ ]
+          
+          annotations_data.each do |attrib, val|
+            unless val.blank?
+              val = [ val ].flatten
+              val.each do |val_inner|
+                unless val_inner.blank?
+                  ann = self.annotations.new(:attribute_name => attrib,
+                                             :source_type => source.class.name,
+                                             :source_id => source.id)
+                  
+                  ann.value = val_inner
+                  ann.save
+                  
+                  if ann && ann.valid?
+                    anns << ann
+                  end
+                end
+              end
+            end
+          end
+
+          # Reload annotations collection
+          self.annotations(true)
+          
+          return anns
+        end
+
+        # When used with the default style (:simple), returns a Hash of the +annotations+ values
+        # grouped by attribute name.
+        #
+        # Example output:
+        # {
+        #   "Summary" => "Something interesting happens",
+        #   "length" => 345,
+        #   "Title" => "Harry Potter and the Exploding Men's Locker Room",
+        #   "Tag" => [ "amusing rhetoric", "wizadry" ],
+        #   "rating" => "4/5"
+        # }
+        def annotations_hash(style=:simple)
+          h = { }
+
+          unless self.annotations.blank?
+            self.annotations.each do |a|
+              if h.has_key?(a.attribute_name)
+                case h[a.attribute_name]
+                  when Array
+                    h[a.attribute_name] << a.value_content
+                  else
+                    h[a.attribute_name] = [ h[a.attribute_name], a.value_content ]
+                end
+              else
+                h[a.attribute_name] = a.value_content
+              end
+            end
+          end
+
+          return h
+        end
+      end
+      
+    end
+  end
+end

data/lib/annotations/acts_as_annotation_source.rb

@@ -0,0 +1,117 @@
+# ActsAsAnnotationSource
+module Annotations
+  module Acts #:nodoc:
+    module AnnotationSource #:nodoc:
+
+      def self.included(base)
+        base.send :extend, ClassMethods  
+      end
+
+      module ClassMethods
+        def acts_as_annotation_source
+          has_many :annotations_by,
+                   :class_name => "Annotation",
+                   :as => :source, 
+                   :order => 'updated_at ASC'
+                   
+          __send__ :extend, SingletonMethods
+          __send__ :include, InstanceMethods
+        end
+      end
+      
+      # Class methods added to the model that has been made acts_as_annotation_source (the mixin target class).
+      module SingletonMethods
+        # Helper finder to get all annotations for an object of the mixin source type with the ID provided.
+        # This is the same as +#annotations+ on the object, with the added benefit that the object doesnt have to be loaded.
+        # E.g: +User.find_annotations_by(10)+ will give all annotations by User with ID 34.
+        def annotations_by(id, include_values=false)
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self).to_s
+          
+          options = {
+            :conditions => { :source_type =>  obj_type, 
+                             :source_id => id },
+            :order => "updated_at DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        # Helper finder to get all annotations for all objects of the mixin source type, for the annotatable object provided.
+        # E.g: +User.find_annotations_for('Book', 28)+ will give all annotations made by all Users for Book with ID 28. 
+        def annotations_for(annotatable_type, annotatable_id, include_values=false)
+          obj_type = ActiveRecord::Base.send(:class_name_of_active_record_descendant, self).to_s
+          
+          options = {
+            :conditions => { :source_type => obj_type,
+                             :annotatable_type =>  annotatable_type, 
+                             :annotatable_id => annotatable_id },
+            :order => "updated_at DESC"
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+      end
+      
+      # This module contains instance methods
+      module InstanceMethods
+        # Helper method to get latest annotations
+        def latest_annotations(limit=nil, include_values=false)
+          options = {
+            :conditions => { :source_type =>  self.class.name, 
+                             :source_id => id },
+            :order => "updated_at DESC",
+            :limit => limit
+          }
+          
+          options[:include] = [ :value ] if include_values
+          
+          Annotation.find(:all, options)
+        end
+        
+        def annotation_source_name
+          %w{ preferred_name display_name title name }.each do |w|
+            return eval("self.#{w}") if self.respond_to?(w)
+          end
+          return "#{self.class.name}_#{self.id}"
+        end
+
+        # When used with the default style (:simple), returns a Hash of the +annotations_by+ values
+        # grouped by attribute name.
+        #
+        # Example output:
+        # {
+        #   "Summary" => "Something interesting happens",
+        #   "length" => 345,
+        #   "Title" => "Harry Potter and the Exploding Men's Locker Room",
+        #   "Tag" => [ "amusing rhetoric", "wizadry" ],
+        #   "rating" => "4/5"
+        # }
+        def annotations_by_hash(style=:simple)
+          h = { }
+
+          unless self.annotations_by.blank?
+            self.annotations_by.each do |a|
+              if h.has_key?(a.attribute_name)
+                case h[a.attribute_name]
+                  when Array
+                    h[a.attribute_name] << a.value_content
+                  else
+                    h[a.attribute_name] = [ h[a.attribute_name], a.value_content ]
+                end
+              else
+                h[a.attribute_name] = a.value_content
+              end
+            end
+          end
+
+          return h
+        end
+      end
+      
+    end
+  end
+end