sequel 3.21.0 → 3.36.0

data/lib/sequel/model/base.rb

@@ -11,8 +11,13 @@ module Sequel
     #   the Model's dataset with the method of the same name with the given arguments.
     module ClassMethods
       # Which columns should be the only columns allowed in a call to a mass assignment method (e.g. set)
-      # (default: not set, so all columns not otherwise restricted).
+      # (default: not set, so all columns not otherwise restricted are allowed).
       attr_reader :allowed_columns
+
+      # Whether to cache the anonymous models created by Sequel::Model().  This is
+      # required for reloading them correctly (avoiding the superclass mismatch).  True
+      # by default for backwards compatibility.
+      attr_accessor :cache_anonymous_models
   
       # Array of modules that extend this model's dataset.  Stored
       # so that if the model's dataset is changed, it will be extended
@@ -23,7 +28,15 @@ module Sequel
       # stored so when the dataset changes, methods defined with def_dataset_method
       # will be applied to the new dataset.
       attr_reader :dataset_methods
-      #
+
+      # SQL string fragment used for faster DELETE statement creation when deleting/destroying
+      # model instances, or nil if the optimization should not be used. For internal use only.
+      attr_reader :fast_instance_delete_sql
+
+      # The dataset that instance datasets (#this) are based on.  Generally a naked version of
+      # the model's dataset limited to one row.  For internal use only.
+      attr_reader :instance_dataset
+
       # Array of plugin modules loaded by this class
       #
       #   Sequel::Model.plugins
@@ -86,6 +99,11 @@ module Sequel
       # database to typecast the value correctly.
       attr_accessor :typecast_on_assignment
   
+      # Whether to enable the after_commit and after_rollback hooks when saving/destroying
+      # instances.  On by default, can be turned off for performance reasons or when using
+      # prepared transactions (which aren't compatible with after commit/rollback).
+      attr_accessor :use_after_commit_rollback
+  
       # Whether to use a transaction by default when saving/deleting records (default: true).
       # If you are sending database queries in before_* or after_* hooks, you shouldn't change
       # the default setting without a good reason.
@@ -102,8 +120,19 @@ module Sequel
       #   Artist[:name=>'Bob'] # SELECT * FROM artists WHERE (name = 'Bob') LIMIT 1
       #   # => #<Artist {:name=>'Bob', ...}>
       def [](*args)
-        args = args.first if (args.size == 1)
-        args.is_a?(Hash) ? dataset[args] : primary_key_lookup(args)
+        args = args.first if args.size <= 1
+        args.is_a?(Hash) ? dataset[args] : (primary_key_lookup(args) unless args.nil?)
+      end
+
+      # Initializes a model instance as an existing record. This constructor is
+      # used by Sequel to initialize model instances when fetching records.
+      # Requires that values be a hash where all keys are symbols. It
+      # probably should not be used by external code.
+      def call(values)
+        o = allocate
+        o.set_values(values)
+        o.after_initialize
+        o
       end
       
       # Clear the setter_methods cache
@@ -148,6 +177,36 @@ module Sequel
       def dataset=(ds)
         set_dataset(ds)
       end
+
+      # Extend the dataset with a module, similar to adding
+      # a plugin with the methods defined in DatasetMethods.  If a block
+      # is given, an anonymous module is created and the module_evaled, otherwise
+      # the argument should be a module.  Returns the module given or the anonymous
+      # module created.
+      #
+      #   Artist.dataset_module Sequel::ColumnsIntrospection
+      #
+      #   Artist.dataset_module do
+      #     def foo
+      #       :bar
+      #     end
+      #   end
+      #   Artist.dataset.foo
+      #   # => :bar
+      #   Artist.foo
+      #   # => :bar
+      def dataset_module(mod = nil)
+        if mod
+          raise Error, "can't provide both argument and block to Model.dataset_module" if block_given?
+          dataset_extend(mod)
+          mod
+        else
+          @dataset_module ||= Module.new
+          @dataset_module.module_eval(&Proc.new) if block_given?
+          dataset_extend(@dataset_module)
+          @dataset_module
+        end
+      end
     
       # Returns the database associated with the Model class.
       # If this model doesn't have a database associated with it,
@@ -161,8 +220,8 @@ module Sequel
       #   end # COMMIT
       def db
         return @db if @db
-        @db = self == Model ? DATABASES.first : superclass.db
-        raise(Error, "No database associated with #{self}") unless @db
+        @db = self == Model ? Sequel.synchronize{DATABASES.first} : superclass.db
+        raise(Error, "No database associated with #{self}: have you called Sequel.connect or #{self}.db= ?") unless @db
         @db
       end
       
@@ -193,6 +252,16 @@ module Sequel
         @db_schema ||= get_db_schema
       end
   
+      # Create a column alias, where the column methods have one name, but the underlying storage uses a
+      # different name.
+      def def_column_alias(meth, column)
+        clear_setter_methods_cache
+        overridable_methods_module.module_eval do
+          define_method(meth){self[column]}
+          define_method("#{meth}="){|v| self[column] = v}
+        end
+      end
+  
       # If a block is given, define a method on the dataset (if the model currently has an dataset)  with the given argument name using
       # the given block.  Also define a class method on the model that calls the
       # dataset method.  Stores the method name and block so that it can be reapplied if the model's
@@ -217,9 +286,15 @@ module Sequel
           @dataset_methods[meth] = block
           dataset.meta_def(meth, &block) if @dataset
         end
-        args.each{|arg| instance_eval("def #{arg}(*args, &block); dataset.#{arg}(*args, &block) end", __FILE__, __LINE__) unless respond_to?(arg)}
+        args.each do |arg|
+          if arg.to_s =~ NORMAL_METHOD_NAME_REGEXP
+            instance_eval("def #{arg}(*args, &block); dataset.#{arg}(*args, &block) end", __FILE__, __LINE__) unless respond_to?(arg, true)
+          else
+            def_model_dataset_method_block(arg)
+          end
+        end
       end
-      
+
       # Finds a single record according to the supplied filter.
       # You are encouraged to use Model.[] or Model.first instead of this method.
       #
@@ -248,6 +323,13 @@ module Sequel
         find(cond) || create(cond, &block)
       end
     
+      # Clear the setter_methods cache when a module is included, as it
+      # may contain setter methods.
+      def include(mod)
+        clear_setter_methods_cache
+        super
+      end
+  
       # If possible, set the dataset for the model subclass as soon as it
       # is created.  Also, make sure the inherited class instance variables
       # are copied into the subclass.
@@ -268,15 +350,14 @@ module Sequel
           subclass.instance_variable_set(iv, sup_class_value)
         end
         unless ivs.include?("@dataset")
-          db
-          begin
-            if self == Model || !@dataset
-              subclass.set_dataset(subclass.implicit_table_name) unless subclass.name.empty?
-            elsif @dataset
-              subclass.set_dataset(@dataset.clone, :inherited=>true)
+          if self == Model || !@dataset
+            n = subclass.name
+            unless n.nil? || n.empty?
+              db
+              subclass.set_dataset(subclass.implicit_table_name) rescue nil
             end
-          rescue
-            nil
+          elsif @dataset
+            subclass.set_dataset(@dataset.clone, :inherited=>true) rescue nil
           end
         end
       end
@@ -290,12 +371,9 @@ module Sequel
         pluralize(underscore(demodulize(name))).to_sym
       end
   
-      # Initializes a model instance as an existing record. This constructor is
-      # used by Sequel to initialize model instances when fetching records.
-      # +load+ requires that values be a hash where all keys are symbols. It
-      # probably should not be used by external code.
+      # Calls #call with the values hash.  Only for backwards compatibility.
       def load(values)
-        new(values, true)
+        call(values)
       end
 
       # Clear the setter_methods cache when a setter method is added
@@ -312,7 +390,7 @@ module Sequel
       #   Artist.primary_key # => nil
       def no_primary_key
         clear_setter_methods_cache
-        @simple_pk = @primary_key = nil
+        self.simple_pk = @primary_key = nil
       end
       
       # Loads a plugin for use with the model class, passing optional arguments
@@ -320,23 +398,18 @@ module Sequel
       # require the plugin from either sequel/plugins/#{plugin} or
       # sequel_#{plugin}, and then attempt to load the module using a
       # the camelized plugin name under Sequel::Plugins.
-      def plugin(plugin, *args, &blk)
+      def plugin(plugin, *args, &block)
         m = plugin.is_a?(Module) ? plugin : plugin_module(plugin)
         unless @plugins.include?(m)
           @plugins << m
-          m.apply(self, *args, &blk) if m.respond_to?(:apply)
-          include(m::InstanceMethods) if m.const_defined?("InstanceMethods")
-          extend(m::ClassMethods)if m.const_defined?("ClassMethods")
-          if m.const_defined?("DatasetMethods")
-            dataset.extend(m::DatasetMethods) if @dataset
-            dataset_method_modules << m::DatasetMethods
-            meths = m::DatasetMethods.public_instance_methods.reject{|x| NORMAL_METHOD_NAME_REGEXP !~ x.to_s}
-            def_dataset_method(*meths) unless meths.empty?
-          end
+          m.apply(self, *args, &block) if m.respond_to?(:apply)
+          include(m::InstanceMethods) if plugin_module_defined?(m, :InstanceMethods)
+          extend(m::ClassMethods)if plugin_module_defined?(m, :ClassMethods)
+          dataset_extend(m::DatasetMethods) if plugin_module_defined?(m, :DatasetMethods)
         end
-        m.configure(self, *args, &blk) if m.respond_to?(:configure)
+        m.configure(self, *args, &block) if m.respond_to?(:configure)
       end
-  
+
       # Returns primary key attribute hash.  If using a composite primary key
       # value such be an array with values for each primary key in the correct
       # order.  For a standard primary key, value should be an object with a
@@ -389,8 +462,8 @@ module Sequel
       # setter methods (methods that end in =) that you want to be used during
       # mass assignment, they need to be listed here as well (without the =).
       #
-      # It may be better to use a method such as +set_only+ instead of this in places where
-      # only certain columns may be allowed.
+      # It may be better to use a method such as +set_only+ or +set_fields+ that lets you specify
+      # the allowed fields per call.
       #
       #   Artist.set_allowed_columns(:name, :hometown)
       #   Artist.set(:name=>'Bob', :hometown=>'Sactown') # No Error
@@ -400,10 +473,12 @@ module Sequel
         @allowed_columns = cols
       end
   
-      # Sets the dataset associated with the Model class. +ds+ can be a +Symbol+
-      # (specifying a table name in the current database), or a +Dataset+.
+      # Sets the dataset associated with the Model class. +ds+ can be a +Symbol+,
+      # +LiteralString+, <tt>SQL::Identifier</tt>, <tt>SQL::QualifiedIdentifier</tt>,
+      # <tt>SQL::AliasedExpression</tt>
+      # (all specifying a table name in the current database), or a +Dataset+.
       # If a dataset is used, the model's database is changed to the database of the given
-      # dataset.  If a symbol is used, a dataset is created from the current
+      # dataset.  If a dataset is not used, a dataset is created from the current
       # database with the table name given. Other arguments raise an +Error+.
       # Returns self.
       #
@@ -418,20 +493,24 @@ module Sequel
       def set_dataset(ds, opts={})
         inherited = opts[:inherited]
         @dataset = case ds
-        when Symbol
-          @simple_table = db.literal(ds)
-          db[ds]
+        when Symbol, SQL::Identifier, SQL::QualifiedIdentifier, SQL::AliasedExpression, LiteralString
+          self.simple_table = db.literal(ds)
+          db.from(ds)
         when Dataset
-          @simple_table = nil
+          self.simple_table = if ds.send(:simple_select_all?)
+            ds.literal(ds.first_source_table)
+          else
+            nil
+          end
           @db = ds.db
           ds
         else
-          raise(Error, "Model.set_dataset takes a Symbol or a Sequel::Dataset")
+          raise(Error, "Model.set_dataset takes one of the following classes as an argument: Symbol, LiteralString, SQL::Identifier, SQL::QualifiedIdentifier, SQL::AliasedExpression, Dataset")
         end
-        @dataset.row_proc = Proc.new{|r| load(r)}
+        @dataset.row_proc = self
         @require_modification = Sequel::Model.require_modification.nil? ? @dataset.provides_accurate_rows_matched? : Sequel::Model.require_modification
         if inherited
-          @simple_table = superclass.simple_table
+          self.simple_table = superclass.simple_table
           @columns = @dataset.columns rescue nil
         else
           @dataset_method_modules.each{|m| @dataset.extend(m)} if @dataset_method_modules
@@ -439,12 +518,14 @@ module Sequel
         end
         @dataset.model = self if @dataset.respond_to?(:model=)
         check_non_connection_error{@db_schema = (inherited ? superclass.db_schema : get_db_schema)}
+        @instance_dataset = @dataset.limit(1).naked
         self
       end
-    
+
       # Sets the primary key for this model. You can use either a regular 
       # or a composite primary key.  To not use a primary key, set to nil
-      # or use +no_primary_key+.
+      # or use +no_primary_key+.  On most adapters, Sequel can automatically
+      # determine the primary key to use, so this method is not needed often.
       #
       #   class Person < Sequel::Model
       #     # regular key
@@ -458,20 +539,23 @@ module Sequel
       def set_primary_key(*key)
         clear_setter_methods_cache
         key = key.flatten
-        @simple_pk = key.length == 1 ? db.literal(key.first) : nil 
+        self.simple_pk = if key.length == 1
+          (@dataset || db).literal(key.first)
+        else 
+          nil 
+        end
         @primary_key = (key.length == 1) ? key[0] : key
       end
   
       # Set the columns to restrict when using mass assignment (e.g. +set+).  Using this means that
       # attempts to call setter methods for the columns listed here will cause an
-      # exception or be silently skipped (based on the +strict_param_setting+ setting.
+      # exception or be silently skipped (based on the +strict_param_setting+ setting).
       # If you have any virtual setter methods (methods that end in =) that you
       # want not to be used during mass assignment, they need to be listed here as well (without the =).
       #
-      # It may be better to use a method such as +set_except+ instead of this in places where
-      # certain columns are restricted.  In general, it's better to have a whitelist approach
-      # where you specify only what is allowed, as opposed to a blacklist approach that this
-      # method uses, where everything is allowed other than what you restrict.
+      # It's generally a bad idea to rely on a blacklist approach for security.  Using a whitelist
+      # approach such as set_allowed_columns or the instance level set_only or set_fields methods
+      # is usually a better choice.  So use of this method is generally a bad idea.
       #
       #   Artist.set_restricted_column(:records_sold)
       #   Artist.set(:name=>'Bob', :hometown=>'Sactown') # No Error
@@ -511,6 +595,9 @@ module Sequel
       # 7 days ago.
       #
       # Both the args given and the block are passed to <tt>Dataset#filter</tt>.
+      #
+      # This method creates dataset methods that do not accept arguments.  To create
+      # dataset methods that accept arguments, you have to use def_dataset_method.
       def subset(name, *args, &block)
         def_dataset_method(name){filter(*args, &block)}
       end
@@ -526,6 +613,7 @@ module Sequel
       end
   
       # Allow the setting of the primary key(s) when using the mass assignment methods.
+      # Using this method can open up security issues, be very careful before using it.
       #
       #   Artist.set(:id=>1) # Error
       #   Artist.unrestrict_primary_key
@@ -548,6 +636,16 @@ module Sequel
         end
       end
 
+      # Add the module to the class's dataset_method_modules.  Extend the dataset with the
+      # module if the model has a dataset.  Add dataset methods to the class for all
+      # public dataset methods.
+      def dataset_extend(mod)
+        dataset.extend(mod) if @dataset
+        dataset_method_modules << mod
+        meths = mod.public_instance_methods.reject{|x| NORMAL_METHOD_NAME_REGEXP !~ x.to_s}
+        def_dataset_method(*meths) unless meths.empty?
+      end
+
       # Create a column accessor for a column with a method name that is hard to use in ruby code.
       def def_bad_column_accessor(column)
         overridable_methods_module.module_eval do
@@ -570,6 +668,13 @@ module Sequel
         end
       end
   
+      # Define a model method that calls the dataset method with the same name,
+      # only used for methods with names that can't be presented directly in
+      # ruby code.
+      def def_model_dataset_method_block(arg)
+        meta_def(arg){|*args, &block| dataset.send(arg, *args, &block)}
+      end
+
       # Get the schema from the database, fall back on checking the columns
       # via the database if that will return inaccurate results or if
       # it raises an error.
@@ -578,10 +683,9 @@ module Sequel
         return nil unless @dataset
         schema_hash = {}
         ds_opts = dataset.opts
-        single_table = ds_opts[:from] && (ds_opts[:from].length == 1) \
-          && !ds_opts.include?(:join) && !ds_opts.include?(:sql)
         get_columns = proc{check_non_connection_error{columns} || []}
-        if single_table && (schema_array = (db.schema(dataset.first_source_table, :reload=>reload) rescue nil))
+        schema_array = check_non_connection_error{db.schema(dataset, :reload=>reload)}
+        if schema_array
           schema_array.each{|k,v| schema_hash[k] = v}
           if ds_opts.include?(:select)
             # We don't remove the columns from the schema_hash,
@@ -589,6 +693,7 @@ module Sequel
             # even if they are not selected.
             cols = get_columns.call
             cols.each{|c| schema_hash[c] ||= {}}
+            def_column_accessor(*schema_hash.keys)
           else
             # Dataset is for a single table with all columns,
             # so set the columns based on the order they were
@@ -657,15 +762,43 @@ module Sequel
         Sequel::Plugins.const_get(module_name)
       end
 
+      # Check if the plugin module +plugin+ defines the constant named by +submod+.
+      def plugin_module_defined?(plugin, submod)
+        if RUBY_VERSION >= '1.9'
+          plugin.const_defined?(submod, false)
+        else
+          plugin.const_defined?(submod)
+        end
+      end
+  
       # Find the row in the dataset that matches the primary key.  Uses
       # a static SQL optimization if the table and primary key are simple.
+      #
+      # This method should not be called with a nil primary key, in case
+      # it is overridden by plugins which assume that the passed argument
+      # is valid.
       def primary_key_lookup(pk)
-        if t = simple_table and p = simple_pk
-          with_sql("SELECT * FROM #{t} WHERE #{p} = #{dataset.literal(pk)}").first
+        if sql = @fast_pk_lookup_sql
+          sql = sql.dup
+          ds = dataset
+          ds.literal_append(sql, pk)
+          ds.fetch_rows(sql){|r| return ds.row_proc.call(r)}
+          nil
         else
           dataset[primary_key_hash(pk)]
         end
       end
+
+      # Reset the cached fast primary lookup SQL if a simple table and primary key
+      # are used, or set it to nil if not used.
+      def reset_fast_pk_lookup_sql
+        @fast_pk_lookup_sql = if @simple_table && @simple_pk
+          "SELECT * FROM #@simple_table WHERE #@simple_pk = ".freeze
+        end
+        @fast_instance_delete_sql = if @simple_table && @simple_pk
+          "DELETE FROM #@simple_table WHERE #@simple_pk = ".freeze
+        end
+      end
   
       # Set the columns for this model and create accessor methods for each column.
       def set_columns(new_columns)
@@ -674,6 +807,18 @@ module Sequel
         @columns
       end
 
+      # Reset the fast primary key lookup SQL when the simple_pk value changes.
+      def simple_pk=(pk)
+        @simple_pk = pk
+        reset_fast_pk_lookup_sql
+      end
+
+      # Reset the fast primary key lookup SQL when the simple_table value changes.
+      def simple_table=(t)
+        @simple_table = t
+        reset_fast_pk_lookup_sql
+      end
+
       # Add model methods that call dataset methods
       DATASET_METHODS.each{|arg| class_eval("def #{arg}(*args, &block); dataset.#{arg}(*args, &block) end", __FILE__, __LINE__)}
   
@@ -686,24 +831,25 @@ module Sequel
 
     # Sequel::Model instance methods that implement basic model functionality.
     #
-    # * All of the methods in +HOOKS+ create instance methods that are called
+    # * All of the methods in +HOOKS+ and +AROUND_HOOKS+ create instance methods that are called
     #   by Sequel when the appropriate action occurs.  For example, when destroying
-    #   a model object, Sequel will call +before_destroy+, do the destroy,
-    #   and then call +after_destroy+.
+    #   a model object, Sequel will call +around_destroy+, which will call +before_destroy+, do
+    #   the destroy, and then call +after_destroy+.
     # * The following instance_methods all call the class method of the same
-    #   name: columns, dataset, db, primary_key, db_schema.
+    #   name: columns, db, primary_key, db_schema.
     # * All of the methods in +BOOLEAN_SETTINGS+ create attr_writers allowing you
-    #   to set values for the attribute.  It also creates instnace getters returning
+    #   to set values for the attribute.  It also creates instance getters returning
     #   the value of the setting.  If the value has not yet been set, it
     #   gets the default value from the class by calling the class method of the same name.
     module InstanceMethods
       HOOKS.each{|h| class_eval("def #{h}; end", __FILE__, __LINE__)}
+      AROUND_HOOKS.each{|h| class_eval("def #{h}; yield end", __FILE__, __LINE__)}
 
       # Define instance method(s) that calls class method(s) of the
       # same name, caching the result in an instance variable.  Define
       # standard attr_writer method for modifying that instance variable.
       def self.class_attr_overridable(*meths) # :nodoc:
-        meths.each{|meth| class_eval("def #{meth}; !defined?(@#{meth}) ? (@#{meth} = self.class.#{meth}) : @#{meth} end", __FILE__, __LINE__)}
+        meths.each{|meth| class_eval("def #{meth}; !defined?(@#{meth}) ? (frozen? ? self.class.#{meth} : (@#{meth} = self.class.#{meth})) : @#{meth} end", __FILE__, __LINE__)}
         attr_writer(*meths) 
       end 
     
@@ -712,7 +858,7 @@ module Sequel
       #   
       #   define_method(meth){self.class.send(meth)}
       def self.class_attr_reader(*meths) # :nodoc:
-        meths.each{|meth| class_eval("def #{meth}; model.#{meth} end", __FILE__, __LINE__)}
+        meths.each{|meth| class_eval("def #{meth}; self.class.#{meth} end", __FILE__, __LINE__)}
       end
 
       private_class_method :class_attr_overridable, :class_attr_reader
@@ -735,7 +881,7 @@ module Sequel
       #
       # Arguments:
       # values :: should be a hash to pass to set. 
-      # from_db :: should only be set by <tt>Model.load</tt>, forget it exists.
+      # from_db :: only for backwards compatibility, forget it exists.
       #
       #   Artist.new(:name=>'Bob')
       #
@@ -744,13 +890,12 @@ module Sequel
       #   end
       def initialize(values = {}, from_db = false)
         if from_db
-          @new = false
           set_values(values)
         else
           @values = {}
           @new = true
           @modified = true
-          set(values)
+          initialize_set(values)
           changed_columns.clear 
           yield self if block_given?
         end
@@ -766,7 +911,7 @@ module Sequel
   
       # Sets the value for the given column.  If typecasting is enabled for
       # this object, typecast the value based on the column's type.
-      # If this a a new record or the typecasted value isn't the same
+      # If this is a new record or the typecasted value isn't the same
       # as the current value for the column, mark the column as changed.
       #
       #   a = Artist.new
@@ -778,9 +923,9 @@ module Sequel
         # If the column isn't in @values, we can't assume it is
         # NULL in the database, so assume it has changed.
         v = typecast_value(column, value)
-        if new? || !@values.include?(column) || v != (c = @values[column]) || v.class != c.class
-          changed_columns << column unless changed_columns.include?(column)
-          @values[column] = v
+        vals = @values
+        if new? || !vals.include?(column) || v != (c = vals[column]) || v.class != c.class
+          change_column_value(column, v)
         end
       end
   
@@ -831,6 +976,7 @@ module Sequel
       #   Artist[1].delete # DELETE FROM artists WHERE (id = 1)
       #   # => #<Artist {:id=>1, ...}>
       def delete
+        raise Sequel::Error, "can't delete frozen object" if frozen?
         _delete
         self
       end
@@ -845,6 +991,7 @@ module Sequel
       #   Artist[1].destroy # BEGIN; DELETE FROM artists WHERE (id = 1); COMMIT;
       #   # => #<Artist {:id=>1, ...}>
       def destroy(opts = {})
+        raise Sequel::Error, "can't destroy frozen object" if frozen?
         checked_save_failure(opts){checked_transaction(opts){_destroy(opts)}}
       end
 
@@ -874,14 +1021,38 @@ module Sequel
 
       # Returns true when current instance exists, false otherwise.
       # Generally an object that isn't new will exist unless it has
-      # been deleted.
+      # been deleted.  Uses a database query to check for existence,
+      # unless the model object is new, in which case this is always
+      # false.
       #
       #   Artist[1].exists? # SELECT 1 FROM artists WHERE (id = 1)
       #   # => true
+      #   Artist.new.exists?
+      #   # => false
       def exists?
-        !this.get(1).nil?
+        new? ? false : !this.get(1).nil?
       end
       
+      # Ignore the model's setter method cache when this instances extends a module, as the
+      # module may contain setter methods.
+      def extend(mod)
+        @singleton_setter_added = true
+        super
+      end
+
+      # Freeze the object in such a way that it is still usable but not modifiable.
+      # Once an object is frozen, you cannot modify it's values, changed_columns,
+      # errors, or dataset.
+      def freeze
+        values.freeze
+        changed_columns.freeze
+        errors
+        validate
+        errors.freeze
+        this.freeze unless new?
+        super
+      end
+  
       # Value that should be unique for objects with the same class and pk (if pk is not nil), or
       # the same class and values (if pk is nil).
       #
@@ -890,7 +1061,14 @@ module Sequel
       #   Artist.new.hash == Artist.new.hash # true
       #   Artist.new(:name=>'Bob').hash == Artist.new.hash # false
       def hash
-        [model, pk.nil? ? @values.sort_by{|k,v| k.to_s} : pk].hash
+        case primary_key
+        when Array
+          [model, !pk.all? ? @values.sort_by{|k,v| k.to_s} : pk].hash
+        when Symbol
+          [model, pk.nil? ? @values.sort_by{|k,v| k.to_s} : pk].hash
+        else
+          [model, @values.sort_by{|k,v| k.to_s}].hash
+        end
       end
   
       # Returns value for the :id attribute, even if the primary key is
@@ -926,7 +1104,8 @@ module Sequel
       #     a.update(...)
       #   end
       def lock!
-        new? ? self : _refresh(this.for_update)
+        _refresh(this.for_update) unless new?
+        self
       end
       
       # Remove elements of the model object that make marshalling fail. Returns self.
@@ -957,7 +1136,7 @@ module Sequel
       #   a = Artist[1]
       #   a.modified? # => false
       #   a.set(:name=>'Jim')
-      #   a.modified # => true
+      #   a.modified? # => true
       def modified?
         @modified || !changed_columns.empty?
       end
@@ -967,18 +1146,23 @@ module Sequel
       #   Artist.new.new? # => true
       #   Artist[1].new? # => false
       def new?
-        @new
+        defined?(@new) ? @new : (@new = false)
       end
       
       # Returns the primary key value identifying the model instance.
-      # Raises an error if this model does not have a primary key.
+      # Raises an +Error+ if this model does not have a primary key.
       # If the model has a composite primary key, returns an array of values.
       #
       #   Artist[1].pk # => 1
       #   Artist[[1, 2]].pk # => [1, 2]
       def pk
         raise(Error, "No primary key is associated with this model") unless key = primary_key
-        key.is_a?(Array) ? key.map{|k| @values[k]} : @values[key]
+        if key.is_a?(Array)
+          vals = @values
+          key.map{|k| vals[k]}
+        else
+          @values[key]
+        end
       end
       
       # Returns a hash identifying mapping the receivers primary key column(s) to their values.
@@ -998,7 +1182,9 @@ module Sequel
       #   a.refresh
       #   a.name # => 'Bob'
       def refresh
+        raise Sequel::Error, "can't refresh frozen object" if frozen?
         _refresh(this)
+        self
       end
 
       # Alias of refresh, but not aliased directly to make overriding in a plugin easier.
@@ -1016,26 +1202,32 @@ module Sequel
       #
       # If +save+ fails and either raise_on_save_failure or the
       # :raise_on_failure option is true, it raises ValidationFailed
-      # or BeforeHookFailed. Otherwise it returns nil.
+      # or HookFailed. Otherwise it returns nil.
       #
       # If it succeeds, it returns self.
       #
       # You can provide an optional list of columns to update, in which
-      # case it only updates those columns.
+      # case it only updates those columns, or a options hash.
       #
       # Takes the following options:
       #
-      # * :changed - save all changed columns, instead of all columns or the columns given
-      # * :transaction - set to true or false to override the current
-      #   use_transactions setting
-      # * :validate - set to false to skip validation
-      # * :raise_on_failure - set to true or false to override the current
-      #   raise_on_save_failure setting
+      # :changed :: save all changed columns, instead of all columns or the columns given
+      # :raise_on_failure :: set to true or false to override the current
+      #                      +raise_on_save_failure+ setting
+      # :server :: set the server/shard on the object before saving, and use that
+      #            server/shard in any transaction.
+      # :transaction :: set to true or false to override the current
+      #                 +use_transactions+ setting
+      # :validate :: set to false to skip validation
       def save(*columns)
+        raise Sequel::Error, "can't save frozen object" if frozen?
         opts = columns.last.is_a?(Hash) ? columns.pop : {}
-        if opts[:validate] != false and !valid?(opts)
-          raise(ValidationFailed.new(errors)) if raise_on_failure?(opts)
-          return
+        set_server(opts[:server]) if opts[:server] 
+        if opts[:validate] != false
+          unless checked_save_failure(opts){_valid?(true, opts)}
+            raise(ValidationFailed.new(errors)) if raise_on_failure?(opts)
+            return
+          end
         end
         checked_save_failure(opts){checked_transaction(opts){_save(columns, opts)}}
       end
@@ -1075,7 +1267,8 @@ module Sequel
       end
   
       # Set all values using the entries in the hash, except for the keys
-      # given in except.
+      # given in except.  You should probably use +set_fields+ or +set_only+
+      # instead of this method, as blacklist approaches to security are a bad idea.
       #
       #   artist.set_except({:name=>'Jim'}, :hometown)
       #   artist.name # => 'Jim'
@@ -1086,28 +1279,85 @@ module Sequel
       # For each of the fields in the given array +fields+, call the setter
       # method with the value of that +hash+ entry for the field. Returns self.
       #
-      #   artist.set_fields({:name=>'Jim'}, :name)
+      # You can provide an options hash, with the following options currently respected:
+      # :missing :: Can be set to :skip to skip missing entries or :raise to raise an
+      #             Error for missing entries.  The default behavior is not to check for
+      #             missing entries, in which case the default value is used.  To be
+      #             friendly with most web frameworks, the missing check will also check
+      #             for the string version of the argument in the hash if given a symbol.
+      #
+      # Examples:
+      #
+      #   artist.set_fields({:name=>'Jim'}, [:name])
       #   artist.name # => 'Jim'
       #
-      #   artist.set_fields({:hometown=>'LA'}, :name)
+      #   artist.set_fields({:hometown=>'LA'}, [:name])
       #   artist.name # => nil
       #   artist.hometown # => 'Sac'
-      def set_fields(hash, fields)
-        fields.each{|f| send("#{f}=", hash[f])}
+      #
+      #   artist.name # => 'Jim'
+      #   artist.set_fields({}, [:name], :missing=>:skip)
+      #   artist.name # => 'Jim'
+      #
+      #   artist.name # => 'Jim'
+      #   artist.set_fields({}, [:name], :missing=>:raise)
+      #   # Sequel::Error raised
+      def set_fields(hash, fields, opts=nil)
+        if opts
+          case opts[:missing]
+          when :skip
+            fields.each do |f|
+              if hash.has_key?(f) 
+                send("#{f}=", hash[f])
+              elsif f.is_a?(Symbol) && hash.has_key?(sf = f.to_s)
+                send("#{sf}=", hash[sf])
+              end
+            end
+          when :raise
+            fields.each do |f|
+              if hash.has_key?(f)
+                send("#{f}=", hash[f])
+              elsif f.is_a?(Symbol) && hash.has_key?(sf = f.to_s)
+                send("#{sf}=", hash[sf])
+              else
+                raise(Sequel::Error, "missing field in hash: #{f.inspect} not in #{hash.inspect}")
+              end
+            end
+          else
+            fields.each{|f| send("#{f}=", hash[f])}
+          end
+        else
+          fields.each{|f| send("#{f}=", hash[f])}
+        end
         self
       end
   
       # Set the values using the entries in the hash, only if the key
-      # is included in only.
+      # is included in only.  It may be a better idea to use +set_fields+
+      # instead of this method.
       #
       #   artist.set_only({:name=>'Jim'}, :name)
       #   artist.name # => 'Jim'
       #
-      #   artist.set_only({:hometown=>'LA'}, :name) # Raise error
+      #   artist.set_only({:hometown=>'LA'}, :name) # Raise Error
       def set_only(hash, *only)
         set_restricted(hash, only.flatten, false)
       end
   
+      # Set the shard that this object is tied to.  Returns self.
+      def set_server(s)
+        @server = s
+        @this.opts[:server] = s if @this
+        self
+      end
+
+      # Replace the current values with hash.  Should definitely not be
+      # used with untrusted input, and should probably not be called
+      # directly by user code.
+      def set_values(hash)
+        @values = hash
+      end
+      
       # Clear the setter_methods cache when a method is added
       def singleton_method_added(meth)
         @singleton_setter_added = true if meth.to_s =~ SETTER_METHOD_REGEXP
@@ -1119,10 +1369,10 @@ module Sequel
       #   Artist[1].this
       #   # SELECT * FROM artists WHERE (id = 1) LIMIT 1
       def this
-        @this ||= model.dataset.filter(pk_hash).limit(1).naked
+        @this ||= use_server(model.instance_dataset.filter(pk_hash))
       end
       
-      # Runs set with the passed hash and then runs save_changes.
+      # Runs #set with the passed hash and then runs save_changes.
       #
       #   artist.update(:name=>'Jim') # UPDATE artists SET name = 'Jim' WHERE (id = 1)
       def update(hash)
@@ -1130,7 +1380,7 @@ module Sequel
       end
   
       # Update all values using the entries in the hash, ignoring any setting of
-      # allowed_columns or restricted columns in the model.
+      # +allowed_columns+ or +restricted_columns+ in the model.
       #
       #   Artist.set_restricted_columns(:name)
       #   artist.update_all(:name=>'Jim') # UPDATE artists SET name = 'Jim' WHERE (id = 1)
@@ -1139,28 +1389,30 @@ module Sequel
       end
   
       # Update all values using the entries in the hash, except for the keys
-      # given in except.
+      # given in except.  You should probably use +update_fields+ or +update_only+
+      # instead of this method, as blacklist approaches to security are a bad idea.
       #
       #   artist.update_except({:name=>'Jim'}, :hometown) # UPDATE artists SET name = 'Jim' WHERE (id = 1)
       def update_except(hash, *except)
         update_restricted(hash, false, except.flatten)
       end
   
-      # Update the instances values by calling +set_fields+ with the +hash+
-      # and +fields+, then save any changes to the record.  Returns self.
+      # Update the instances values by calling +set_fields+ with the arguments, then
+      # saves any changes to the record.  Returns self.
       #
-      #   artist.update_fields({:name=>'Jim'}, :name)
+      #   artist.update_fields({:name=>'Jim'}, [:name])
       #   # UPDATE artists SET name = 'Jim' WHERE (id = 1)
       #
-      #   artist.update_fields({:hometown=>'LA'}, :name)
+      #   artist.update_fields({:hometown=>'LA'}, [:name])
       #   # UPDATE artists SET name = NULL WHERE (id = 1)
-      def update_fields(hash, fields)
-        set_fields(hash, fields)
+      def update_fields(hash, fields, opts=nil)
+        set_fields(hash, fields, opts)
         save_changes
       end
 
       # Update the values using the entries in the hash, only if the key
-      # is included in only.
+      # is included in only.  It may be a better idea to use +update_fields+
+      # instead of this method.
       #
       #   artist.update_only({:name=>'Jim'}, :name)
       #   # UPDATE artists SET name = 'Jim' WHERE (id = 1)
@@ -1185,21 +1437,15 @@ module Sequel
       #   artist(:name=>'Invalid').valid? # => false
       #   artist.errors.full_messages # => ['name cannot be Invalid']
       def valid?(opts = {})
-        errors.clear
-        if before_validation == false
-          raise_hook_failure(:validation) if raise_on_failure?(opts)
-          return false
-        end
-        validate
-        after_validation
-        errors.empty?
+        _valid?(false, opts)
       end
 
       private
       
-      # Actually do the deletion of the object's dataset.
+      # Do the deletion of the object's dataset, and check that the row
+      # was actually deleted.
       def _delete
-        n = _delete_dataset.delete
+        n = _delete_without_checking
         raise(NoExistingObject, "Attempt to delete object did not result in a single row modification (Rows Deleted: #{n}, SQL: #{_delete_dataset.delete_sql})") if require_modification && n != 1
         n
       end
@@ -1210,12 +1456,33 @@ module Sequel
         this
       end
   
+      # Actually do the deletion of the object's dataset.  Return the
+      # number of rows modified.
+      def _delete_without_checking
+        if sql = (m = model).fast_instance_delete_sql
+          sql = sql.dup
+          (ds = m.dataset).literal_append(sql, pk)
+          ds.with_sql_delete(sql)
+        else
+          _delete_dataset.delete 
+        end
+      end
+
       # Internal destroy method, separted from destroy to
       # allow running inside a transaction
       def _destroy(opts)
-        raise_hook_failure(:destroy) if before_destroy == false
-        _destroy_delete
-        after_destroy
+        sh = {:server=>this_server}
+        db.after_rollback(sh){after_destroy_rollback} if uacr = use_after_commit_rollback
+        called = false
+        around_destroy do
+          called = true
+          raise_hook_failure(:destroy) if before_destroy == false
+          _destroy_delete
+          after_destroy
+          true
+        end
+        raise_hook_failure(:destroy) unless called
+        db.after_commit(sh){after_destroy_commit} if uacr
         self
       end
       
@@ -1230,68 +1497,107 @@ module Sequel
       # the record should be refreshed from the database.
       def _insert
         ds = _insert_dataset
-        if ds.respond_to?(:insert_select) and h = ds.insert_select(@values)
-          @values = h
+        if !ds.opts[:select] and ds.supports_insert_select? and h = _insert_select_raw(ds)
+          set_values(h)
           nil
         else
-          iid = ds.insert(@values)
+          iid = _insert_raw(ds)
           # if we have a regular primary key and it's not set in @values,
           # we assume it's the last inserted id
-          if (pk = autoincrementing_primary_key) && pk.is_a?(Symbol) && !@values[pk]
-            @values[pk] = iid
+          if (pk = autoincrementing_primary_key) && pk.is_a?(Symbol) && !(vals = @values)[pk]
+            vals[pk] = iid
           end
           pk
         end
       end
-      
+
       # The dataset to use when inserting a new object.   The same as the model's
       # dataset by default.
       def _insert_dataset
-        model.dataset
+        use_server(model.instance_dataset)
       end
   
+      # Insert into the given dataset and return the primary key created (if any).
+      def _insert_raw(ds)
+        ds.insert(@values)
+      end
+
+      # Insert into the given dataset and return the hash of column values.
+      def _insert_select_raw(ds)
+        ds.insert_select(@values)
+      end
+      
       # Refresh using a particular dataset, used inside save to make sure the same server
       # is used for reading newly inserted values from the database
       def _refresh(dataset)
-        set_values(dataset.first || raise(Error, "Record not found"))
+        set_values(_refresh_get(dataset) || raise(Error, "Record not found"))
         changed_columns.clear
-        self
+      end
+
+      # Get the row of column data from the database.
+      def _refresh_get(dataset)
+        dataset.first
       end
       
       # Internal version of save, split from save to allow running inside
       # it's own transaction.
       def _save(columns, opts)
-        raise_hook_failure(:save) if before_save == false
-        if new?
-          raise_hook_failure(:create) if before_create == false
-          pk = _insert
-          @this = nil
-          @new = false
-          @was_new = true
-          after_create
+        sh = {:server=>this_server}
+        db.after_rollback(sh){after_rollback} if uacr = use_after_commit_rollback
+        was_new = false
+        pk = nil
+        called_save = false
+        called_cu = false
+        around_save do
+          called_save = true
+          raise_hook_failure(:save) if before_save == false
+          if new?
+            was_new = true
+            around_create do
+              called_cu = true
+              raise_hook_failure(:create) if before_create == false
+              pk = _insert
+              @this = nil
+              @new = false
+              @was_new = true
+              after_create
+              true
+            end
+            raise_hook_failure(:create) unless called_cu
+          else
+            around_update do
+              called_cu = true
+              raise_hook_failure(:update) if before_update == false
+              if columns.empty?
+                @columns_updated = if opts[:changed]
+                  @values.reject{|k,v| !changed_columns.include?(k)}
+                else
+                  _save_update_all_columns_hash
+                end
+                changed_columns.clear
+              else # update only the specified columns
+                @columns_updated = @values.reject{|k, v| !columns.include?(k)}
+                changed_columns.reject!{|c| columns.include?(c)}
+              end
+              _update_columns(@columns_updated)
+              @this = nil
+              after_update
+              true
+            end
+            raise_hook_failure(:update) unless called_cu
+          end
           after_save
+          true
+        end
+        raise_hook_failure(:save) unless called_save
+        if was_new
           @was_new = nil
           pk ? _save_refresh : changed_columns.clear
         else
-          raise_hook_failure(:update) if before_update == false
-          if columns.empty?
-            @columns_updated = if opts[:changed]
-              @values.reject{|k,v| !changed_columns.include?(k)}
-            else
-              _save_update_all_columns_hash
-            end
-            changed_columns.clear
-          else # update only the specified columns
-            @columns_updated = @values.reject{|k, v| !columns.include?(k)}
-            changed_columns.reject!{|c| columns.include?(c)}
-          end
-          _update_columns(@columns_updated)
-          @this = nil
-          after_update
-          after_save
           @columns_updated = nil
         end
         @modified = false
+        db.after_commit(sh){after_commit} if uacr
         self
       end
 
@@ -1321,9 +1627,10 @@ module Sequel
         _update(columns) unless columns.empty?
       end
 
-      # Update this instance's dataset with the supplied column hash.
+      # Update this instance's dataset with the supplied column hash,
+      # checking that only a single row was modified.
       def _update(columns)
-        n = _update_dataset.update(columns)
+        n = _update_without_checking(columns)
         raise(NoExistingObject, "Attempt to update object did not result in a single row modification (SQL: #{_update_dataset.update_sql(columns)})") if require_modification && n != 1
         n
       end
@@ -1334,7 +1641,47 @@ module Sequel
         this
       end
 
-      # If not raising on failure, check for BeforeHookFailed
+      # Update this instances dataset with the supplied column hash.
+      def _update_without_checking(columns)
+        _update_dataset.update(columns)
+      end
+
+      # Internal validation method.  If +raise_errors+ is +true+, hook
+      # failures will be raised as HookFailure exceptions.  If it is
+      # +false+, +false+ will be returned instead.
+      def _valid?(raise_errors, opts)
+        return errors.empty? if frozen?
+        errors.clear
+        called = false
+        error = false
+        around_validation do
+          called = true
+          if before_validation == false
+            if raise_errors
+              raise_hook_failure(:validation)
+            else
+              error = true
+            end
+            false
+          else
+            validate
+            after_validation
+            errors.empty?
+          end
+        end
+        error = true unless called
+        if error
+          if raise_errors
+            raise_hook_failure(:validation)
+          else
+            false
+          end
+        else
+          errors.empty?
+        end
+      end
+
+      # If not raising on failure, check for HookFailed
       # being raised by yielding and swallow it.
       def checked_save_failure(opts)
         if raise_on_failure?(opts)
@@ -1342,7 +1689,7 @@ module Sequel
         else
           begin
             yield
-          rescue BeforeHookFailed 
+          rescue HookFailed 
             nil
           end
         end
@@ -1350,7 +1697,21 @@ module Sequel
       
       # If transactions should be used, wrap the yield in a transaction block.
       def checked_transaction(opts={})
-        use_transaction?(opts) ? db.transaction(opts){yield} : yield
+        use_transaction?(opts) ? db.transaction({:server=>this_server}.merge(opts)){yield} : yield
+      end
+
+      # Change the value of the column to given value, recording the change.
+      def change_column_value(column, value)
+        cc = changed_columns
+        cc << column unless cc.include?(column)
+        @values[column] = value
+      end
+
+      # Set the columns with the given hash.  By default, the same as +set+, but
+      # exists so it can be overridden.  This is called only for new records, before
+      # changed_columns is cleared.
+      def initialize_set(h)
+        set(h) unless h.empty?
       end
 
       # Default inspection output for the values hash, overwrite to change what #inspect displays.
@@ -1369,11 +1730,12 @@ module Sequel
       # Raise an error appropriate to the hook type. May be swallowed by
       # checked_save_failure depending on the raise_on_failure? setting.
       def raise_hook_failure(type)
-        raise BeforeHookFailed, "one of the before_#{type} hooks returned false"
+        raise HookFailed, "one of the before_#{type} hooks returned false"
       end
   
       # Set the columns, filtered by the only and except arrays.
       def set_restricted(hash, only, except)
+        return self if hash.empty?
         meths = if only.nil? && except.nil? && !@singleton_setter_added
           model.setter_methods
         else
@@ -1385,17 +1747,21 @@ module Sequel
           if meths.include?(m)
             send(m, v)
           elsif strict
-            raise Error, "method #{m} doesn't exist or access is restricted to it"
+            # Avoid using respond_to? or creating symbols from user input
+            if public_methods.map{|s| s.to_s}.include?(m)
+              if Array(model.primary_key).map{|s| s.to_s}.member?(k.to_s) && model.restrict_primary_key?
+                raise Error, "#{k} is a restricted primary key"
+              else
+                raise Error, "#{k} is a restricted column"
+              end
+            else
+              raise Error, "method #{m} doesn't exist"
+            end
           end
         end
         self
       end
       
-      # Replace the current values with hash.
-      def set_values(hash)
-        @values = hash
-      end
-      
       # Returns all methods that can be used for attribute
       # assignment (those that end with =), modified by the only
       # and except arguments:
@@ -1424,13 +1790,25 @@ module Sequel
           meths
         end
       end
+
+      # The server/shard that the model object's dataset uses, or :default if the
+      # model object's dataset does not have an associated shard.
+      def this_server
+        if (s = @server)
+          s
+        elsif (t = @this)
+          t.opts[:server] || :default
+        else
+          model.dataset.opts[:server] || :default
+        end
+      end
   
       # Typecast the value to the column's type if typecasting.  Calls the database's
       # typecast_value method, so database adapters can override/augment the handling
       # for database specific column types.
       def typecast_value(column, value)
         return value unless typecast_on_assignment && db_schema && (col_schema = db_schema[column])
-        value = nil if value == '' and typecast_empty_string_to_nil and col_schema[:type] and ![:string, :blob].include?(col_schema[:type])
+        value = nil if '' == value and typecast_empty_string_to_nil and col_schema[:type] and ![:string, :blob].include?(col_schema[:type])
         raise(InvalidValue, "nil/NULL is not allowed for the #{column} column") if raise_on_typecast_failure && value.nil? && (col_schema[:allow_null] == false)
         begin
           model.db.typecast_value(col_schema[:type], value)
@@ -1444,6 +1822,11 @@ module Sequel
         set_restricted(hash, only, except)
         save_changes
       end
+
+      # Set the given dataset to use the current object's shard.
+      def use_server(ds)
+        @server ? ds.server(@server) : ds
+      end
       
       # Whether to use a transaction for this action.  If the :transaction
       # option is present in the hash, use that, otherwise, fallback to the
@@ -1461,6 +1844,18 @@ module Sequel
       #   Artist.dataset.model # => Artist
       attr_accessor :model
 
+      # Assume if a single integer is given that it is a lookup by primary
+      # key, and call with_pk with the argument.
+      #
+      #   Artist.dataset[1] # SELECT * FROM artists WHERE (id = 1) LIMIT 1
+      def [](*args)
+        if args.length == 1 && (i = args.at(0)) && i.is_a?(Integer)
+          with_pk(i)
+        else
+          super
+        end
+      end
+
       # Destroy each row in the dataset by instantiating it and then calling
       # destroy on the resulting model object.  This isn't as fast as deleting
       # the dataset, which does a single SQL call, but this runs any destroy
@@ -1472,7 +1867,7 @@ module Sequel
       #   # ...
       def destroy
         pr = proc{all{|r| r.destroy}.length}
-        model.use_transactions ? @db.transaction(&pr) : pr.call
+        model.use_transactions ? @db.transaction(:server=>opts[:server], &pr) : pr.call
       end
 
       # This allows you to call +to_hash+ without any arguments, which will
@@ -1491,6 +1886,19 @@ module Sequel
           super(pk, value_column) 
         end
       end
+
+      # Given a primary key value, return the first record in the dataset with that primary key
+      # value.
+      #
+      #   # Single primary key
+      #   Artist.dataset.with_pk(1) # SELECT * FROM artists WHERE (id = 1) LIMIT 1
+      #
+      #   # Composite primary key
+      #   Artist.dataset.with_pk([1, 2]) # SELECT * FROM artists
+      #                                  # WHERE ((id1 = 1) AND (id2 = 2)) LIMIT 1
+      def with_pk(pk)
+        first(model.qualified_primary_key_hash(pk))
+      end
     end
 
     extend ClassMethods