mccraigmccraig-better_serialization 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,102 @@
+=== Faster, Smaller, Gzip-able
+
+This adds +marshal_serialize+ and +json_serialize+ to ActiveRecord::Base (class methods), which act similar to rails' own +serialize+ except they don't use yaml, which is slooooow and biiiiig (byte-wise). Also supports adding gzip to the serialization process for really large stuff (can save a ton of database memory with minimal added insert time). Note that gzip columns must be of type "binary", "blob", etc (not text).
+
+Note that there's a limitation with the plugin: you can't call destructive actions on attributes using better_serialization (ex. << for an array), and update_attribute etc won't work. See TODO for an explanation.
+
+=== Example
+
+see tests, but here's the gist:
+
+    class OrderLog < ActiveRecord::Base
+      marshal_serialize :line_items_cache, :gzip => true
+      marshal_serialize :product_cache
+      json_serialize :customer_cache
+    end
+    
+    order_log = OrderLog.new
+    product = Product.new(:name => "Woot")
+    order_log.product_cache = product
+
+    order_log.product_cache # => normal
+    order_log[:product_cache] # => raw Marshal.dump of product
+
+=== Notes for json_serialize
+
+JSON serialization is faster and smaller, but needs more configuration. This is because Marshal and the default YAML serialization dump the whole object, instance variables and all. JSON just stores an instances' attribute values. Thus, you need to tell it what class to instantiate, or tell it not to instantiate anything at all for storing a hash or array of data. 
+
+Also, when serializing ActiveRecord objects, if <code>ActiveRecord::Base.include_root_in_json == true</code> (the new rails defalut), it'll all 'just work'. Otherwise, you will need to use the :class_name option if it's not inferable by the association name, and will probably want modify that class's to_json to include the id.
+    
+=== The Problem With YAML Serialization: speed and size
+
+[NOTE: this code does not represent the BetterSerialization api, but rather the underlying ideas]
+
+The following examples came from the real-world objects that inspired the plugin.
+
++lis+ is an 18-member array of line items that have many associations loaded into memory,
+the point being that they're relatively big objects.
+
+    marshal_data, yaml_data, json_data = nil
+
+    Benchmark.bm(7) do |x|
+      x.report("Marshal") { marshal_data = Marshal.dump(lis) }
+      x.report("to_yaml") { yaml_data    = lis.to_yaml       }
+      x.report('to_json') { json_data    = lis.to_json       }
+    end
+
+                 user     system      total        real
+    Marshal  0.590000   0.000000   0.590000 (  0.605567)
+    to_yaml 11.730000   0.010000  11.740000 ( 12.179310)
+    to_json  0.010000   0.000000   0.010000 (  0.006129)
+
+The reason JSON is so fast is that rails' ActiveRecord::Base#to_json only jsonifies the attributes hash, not the actual ruby object. If you want the full object though, Marshal is waaaaay faster than to_yaml, and it *is* representing the full ruby object.
+
+Marshal is also a lot smaller than yaml:
+
+    >> marshal_data.size
+    => 1119279
+    >> yaml_data.size
+    => 1958610
+    >> json_data.size
+    => 7886
+
+Whammy. What about deserialization?
+
+    Benchmark.bm(7) do |x|
+      x.report("Marshal") { Marshal.load(marshal_data) }
+      x.report("to_yaml") { YAML::load(yaml_data) }
+      x.report('to_json') { ActiveSupport::JSON.decode(json_data).collect {|hash| BuylistLineItem.new(hash)} }
+    end
+
+                 user     system      total        real
+    Marshal  0.040000   0.000000   0.040000 (  0.046616)
+    to_yaml  0.380000   0.000000   0.380000 (  0.380686)
+    to_json  0.020000   0.000000   0.020000 (  0.019096)
+
+With json you can't just unmarshal it 'cuz it's just representing an attribute array, but even compensating with object creation it's still the fastest.
+
+Finally, if you need to save some space, you can use gzip with the serialization:
+
+    >> Benchmark.measure {gz_marshal_data = Zlib::Deflate.deflate(marshal_data)}
+    => #<Benchmark::Tms:0x10a7ee54 @utime=0.0300000000000011, @cstime=0.0, @cutime=0.0, @total=0.0300000000000011, @label="", @stime=0.0, @real=0.0292189121246338>
+    >> marshal_data.size - gz_marshal_data.size
+    => 1036979
+    >> Benchmark.measure {Zlib::Inflate.inflate(marshal_data)}
+    => #<Benchmark::Tms:0x10a8db98 @utime=0.0, @cstime=0.0, @cutime=0.0, @total=0.0, @label="", @stime=0.0, @real=0.00509905815124512>
+
+So on this machine it would add 30ms on insert and 5ms on load, but save ~1mb of database space. Seems worth it if you're saving this much stuff.
+
+[EDIT: Also note that from personal experience, gzipping json will still use 1/10th the overall space with ~.5ms performance hit - WIN]
+
+=== Summary
+
+If you want speed/small data and don't need to flash-freeze the whole object, use json. Otherwise, use Marshal. If you want to use minimal database space, add gzip to those (adds a relatively small performance hit). Use the default yaml if you really, really *need* to save the whole object and also have a more human-readable datastore... eh, actually, don't use yaml.
+
+=== TODO
+
+* deserialization should be cached, and it would be nice if the deserialized value was stored in the attributes hash.
+* Allow destructive actions
+  * The problem is that serializing and de-serializing creates new objects, so if you do object.array_attribute << "blah", you will have deserialized a new object, destructively added a value to it, and thrown the new object away. ActiveRecord avoids this issue by calling to_yaml as a catch-all on the result of read_attribute in activerecord/lib/active_record/connection_adapters/abstract/quoting.rb#quote (as of 2.3.4). What we need is something like being able to specify what AR's catch-all case is (although that wouldn't work for some option/value combos, ex. gzip option on a string or date). Gratefully accepting ideas :)
+  * Also, just thought of another way. have the raw data be in the raw_#{attribute} column, and object.attribute be a method that loads raw_#{attribute}. That + save hooks = win.
+
+Copyright (c) 2009 Woody Peterson, released under the MIT license

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "mccraigmccraig-better_serialization"
+    gem.summary = %Q{json and zlib serialization for activerecord attributes}
+    gem.description = %Q{serialize and deserialize activerecord attributes using json or zlib}
+    gem.email = "mccraigmccraig@googlemail.com"
+    gem.homepage = "http://github.com/trampoline/better_serialization"
+    gem.authors = ["http://github.com/crystalcommerce", "http://github.com/rhburrows", "http://github.com/mccraigmccraig"]
+    gem.add_dependency "activerecord", ">= 2.3.8"
+    gem.add_development_dependency "rspec", ">= 1.2.8"
+    gem.add_development_dependency "sqlite3-ruby", ">= 1.3.1"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "better_serialization #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1,2 @@
+# Include hook code here
+require 'better_serialization'

data/lib/better_serialization.rb

@@ -0,0 +1,125 @@
+require 'zlib'
+
+module BetterSerialization
+  class JsonSerializer
+    attr_reader :options
+
+    def initialize(options)
+      @options = options
+    end
+
+    def to_json(object)
+      json = object.to_json
+      json = Zlib::Deflate.deflate(json) if options[:gzip]
+      json
+    end
+
+    def from_json(attribute)
+      return options[:default].try(:call) if attribute.nil?
+
+      json = options[:gzip] ? Zlib::Inflate.inflate(attribute) : attribute
+      decoded = ActiveSupport::JSON.decode(json)
+
+      if options[:with_indifferent_access]
+        return decoded.respond_to?(:with_indifferent_access) ? decoded.with_indifferent_access : decoded
+      end
+      return decoded if !options[:instantiate]
+
+      result = deserialize(attribute, [decoded].flatten)
+      return decoded.is_a?(Array) ? result : result.first
+    end
+
+    private
+
+    def deserialize(attribute, attribute_hashes)
+      class_name = options[:class_name]
+      attribute_hashes.inject([]) do |result, attr_hash|
+        if class_name.blank? || class_included?(class_name)
+          class_name = attr_hash.keys.first.camelcase
+          attr_hash = attr_hash.values.first
+        end
+        class_name ||=  attribute.to_s.singularize.camelize
+
+        result << create(class_name.constantize, attr_hash.with_indifferent_access)
+      end
+    end
+
+    def active_record?(klass)
+      k = klass.superclass
+      while k != Object
+        return true if k == ActiveRecord::Base
+        k = k.superclass
+      end
+      false
+    end
+
+    def class_included?(class_name)
+      class_name.present? &&
+        active_record?(class_name.constantize) &&
+        ActiveRecord::Base.include_root_in_json
+    end
+
+    def create(klass, attr_hash)
+      if active_record?(klass)
+        klass.send(:instantiate, attr_hash)
+      else
+        klass.send(:new, attr_hash)
+      end
+    end
+  end
+
+  # === Options
+  # * +gzip+ - uses gzip before marshalling and unmarshalling. Slight speed hit,
+  #   but can save a lot of hard drive space.
+  def marshal_serialize(*attrs)
+    options = attrs.last.is_a?(Hash) ? attrs.pop : {}
+    
+    attrs.each do |attribute|
+      define_method "#{attribute}=" do |value|
+        marshalled_value = Marshal.dump(value)
+        marshalled_value = Zlib::Deflate.deflate(marshalled_value) if options[:gzip]
+        super(marshalled_value)
+      end
+      
+      define_method attribute do
+        return nil if self[attribute].nil?
+        
+        value = Zlib::Inflate.inflate(self[attribute]) if options[:gzip]
+        Marshal.load(value || self[attribute])
+      end
+    end
+  end
+  
+  # === Options
+  # options is the last parameter (a hash):
+  # * +:gzip+ - uses gzip before and after serialization. Slight speed hit,
+  #   but can save a lot of hard drive space.
+  # * +:instantiate+ - if false, it will return the raw decoded json and not attempt to
+  #   instantiate ActiveRecord objects. Defaults to true.
+  # * +:with_indifferent_access+ - if true, it will return the raw decoded json as
+  #   a hash with indifferent access. This can be handy because json doesn't have a concept
+  #   of symbols, so it gets annoying when you're using a field as a key-value store
+  # * +:default+ - A proc that gets called when the field is null
+  # * +:class_name+ - If ActiveRecord::Base.include_root_in_json is false, you
+  #   will need this option so that we can figure out which AR class to instantiate
+  #   (not applicable if +raw+ is true)
+  def json_serialize(*attrs)
+    options = attrs.last.is_a?(Hash) ? attrs.pop : {}
+    options = {:instantiate => true}.merge(options)
+    
+    attrs.each do |attribute|
+      define_method "#{attribute}=" do |value|
+        super(JsonSerializer.new(options).to_json(value))
+      end
+      
+      define_method attribute do
+        JsonSerializer.new(options).from_json(self[attribute])
+      end
+    end
+  end
+end
+
+class ActiveRecord::Base
+  extend BetterSerialization
+end
+

data/spec/better_serialization_spec.rb

@@ -0,0 +1,122 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe BetterSerialization do
+  before do
+    @order_log = OrderLog.new
+    @li = LineItem.new
+    @product = Product.new(:name => "Woot", :line_items => [@li])
+    @li.product = @product
+  end
+  
+  describe "json serialization" do
+    before do
+      @customer = Customer.new(:name => "John Spartan")
+      @order_log.customer_cache = @customer
+      @serialized_customer = @customer.to_json
+    end
+    
+    it "serializes the attribute" do
+      @order_log[:customer_cache].should == @serialized_customer
+    end
+    
+    it "deserializes the attribute" do
+      @order_log.customer_cache.attributes.should == @customer.attributes
+    end
+
+    it "works with arrays (and gzip)" do
+      OrderLog.json_serialize :line_items_cache, :class_name => "LineItem", :gzip => true
+      @order_log.line_items_cache = [@li]
+      @serialized_gzip_li = Zlib::Deflate.deflate([@li].to_json)
+
+      @order_log.save
+      @order_log.reload
+      @order_log[:line_items_cache].should == @serialized_gzip_li
+      @order_log.line_items_cache.first.attributes.should == @li.attributes
+
+      OrderLog.marshal_serialize :line_items_cache, :gzip => true
+    end
+    
+    it "works with ActiveRecord::Base.include_root_in_json == true" do
+      ActiveRecord::Base.include_root_in_json = true
+      
+      @order_log.customer_cache = @customer
+      @serialized_customer = @customer.to_json
+
+      @order_log[:customer_cache].should == @serialized_customer
+      @order_log.customer_cache.attributes.should == @customer.attributes
+    end
+    
+    it "includes :id in serialization" do
+      @customer.save
+      
+      @order_log.customer_cache = @customer
+      @serialized_customer = @customer.to_json
+      
+      @order_log.customer_cache.attributes.should == @customer.attributes
+      @order_log.customer_cache.id.should == @customer.id
+    end
+
+    it "includes :id in a subclass of a subclass of ActiveRecord::Base" do
+      context "STI" do
+        before do
+          $DBG = true
+          @customer = PreferredCustomer.new(:name => "Lt. Lenina Huxley")
+          @order_log = OrderLog.new
+        end
+
+        it "includes :id when deserialized" do
+          @customer.save
+
+          @order_log.customer_cache = @customer
+          @order_log.customer_cache.id.should == @customer.id
+          $DBG = false
+        end
+      end
+    end
+
+    context "on a non-ActiveRecord object" do
+      let(:directory){ Directory.new }
+
+      it "unserializes the same" do
+        person = Person.new(:name => "Simon Phoenix", :age => 75)
+        directory.people = [person]
+        directory.people.first.should == person
+      end
+    end
+  end
+  
+  describe "Marshal serialization" do
+    before do
+      @order_log.product_cache = @product
+      @serialized_product = Marshal.dump(@product)
+    end
+    
+    it "serializes the input of attribute=" do
+      @order_log[:product_cache].should == @serialized_product
+    end
+
+    it "deserializes the input of attribute=" do
+      # can't compare them directly 'cuz they have different object ids
+      @order_log.product_cache.attributes.should == @product.attributes
+    end
+  end
+  
+  describe "Marshal serialization with gzip" do
+    before do
+      @order_log.line_items_cache = [@li]
+      @serialized_gzip_li = Zlib::Deflate.deflate(Marshal.dump([@li]))
+
+      # testing putting binary data in the database
+      @order_log.save
+      @order_log.reload
+    end
+    
+    it "serializes the input of attribute=" do
+      @order_log[:line_items_cache].should == @serialized_gzip_li
+    end
+
+    it "deserializes the input of attribute=" do
+      @order_log.line_items_cache.first.attributes.should == @li.attributes
+    end
+  end
+end

data/spec/models/customer.rb

@@ -0,0 +1,6 @@
+class Customer < ActiveRecord::Base
+  has_many :line_items
+end
+
+class PreferredCustomer < Customer
+end

data/spec/models/directory.rb

@@ -0,0 +1,3 @@
+class Directory < ActiveRecord::Base
+  json_serialize :people, :class_name => 'Person'
+end

data/spec/models/line_item.rb

@@ -0,0 +1,4 @@
+class LineItem < ActiveRecord::Base
+  belongs_to :product
+  belongs_to :customer
+end

data/spec/models/order_log.rb

@@ -0,0 +1,5 @@
+class OrderLog < ActiveRecord::Base
+  marshal_serialize :line_items_cache, :gzip => true
+  marshal_serialize :product_cache
+  json_serialize :customer_cache, :class_name => "Customer"
+end

data/spec/models/person.rb

@@ -0,0 +1,12 @@
+# Non-active record model to test
+class Person
+  attr_accessor :name, :age
+
+  def initialize(attr)
+    @name, @age = attr[:name], attr[:age]
+  end
+
+  def ==(other)
+    other.is_a?(Person) && other.name == name && other.age == age
+  end
+end

data/spec/models/product.rb

@@ -0,0 +1,3 @@
+class Product < ActiveRecord::Base
+  has_many :line_items
+end

data/spec/schema.rb

@@ -0,0 +1,24 @@
+ActiveRecord::Schema.define do
+  create_table :order_logs do |t|
+    t.text "customer_cache"
+    t.text "product_cache"
+    t.binary "line_items_cache"
+  end
+
+  create_table :customers do |t|
+    t.string "name"
+  end
+
+  create_table :products do |t|
+    t.string "name"
+  end
+
+  create_table :line_items do |t|
+    t.integer "product_id"
+    t.integer "customer_id"
+  end
+
+  create_table :directories do |t|
+    t.binary "people"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,30 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rubygems'
+require 'spec'
+require 'spec/autorun'
+require 'activerecord'
+require 'better_serialization'
+
+Spec::Runner.configure do |config|
+  
+end
+
+RAILS_ENV="test"
+ActiveRecord::Base.logger = Logger.new(StringIO.new) # make it think it has a logger
+ 
+ActiveRecord::Base.configurations = {
+  "test" => {
+    :adapter => 'sqlite3',
+    :database => ":memory:"
+  }
+}
+ActiveRecord::Base.establish_connection
+silence_stream(STDOUT) {require 'schema'}
+
+require "models/order_log"
+require "models/customer"
+require "models/line_item"
+require "models/product"
+require "models/person"
+require "models/directory"

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification 
+name: mccraigmccraig-better_serialization
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- http://github.com/crystalcommerce
+- http://github.com/rhburrows
+- http://github.com/mccraigmccraig
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-15 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 2
+        - 3
+        - 8
+        version: 2.3.8
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 2
+        - 8
+        version: 1.2.8
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 1
+        - 3
+        - 1
+        version: 1.3.1
+  type: :development
+  version_requirements: *id003
+description: serialize and deserialize activerecord attributes using json or zlib
+email: mccraigmccraig@googlemail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- init.rb
+- lib/better_serialization.rb
+- spec/better_serialization_spec.rb
+- spec/models/customer.rb
+- spec/models/directory.rb
+- spec/models/line_item.rb
+- spec/models/order_log.rb
+- spec/models/person.rb
+- spec/models/product.rb
+- spec/schema.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/trampoline/better_serialization
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: json and zlib serialization for activerecord attributes
+test_files: 
+- spec/better_serialization_spec.rb
+- spec/models/customer.rb
+- spec/models/directory.rb
+- spec/models/line_item.rb
+- spec/models/order_log.rb
+- spec/models/person.rb
+- spec/models/product.rb
+- spec/schema.rb
+- spec/spec_helper.rb