veneer

Veneer is an interface that sits above Data Sources. A data source may be an ORM like ActiveRecord or DataMapper, or it could be a document store like MongoMapper, Mongoid, a key value storage like Moneta, or even an adapter could be setup to use for an external API.

Veneer aims to provide plugin, engine, and library authors with a consistant interface to any of these libraries so that plugins, engines, stacks and gems may be used across data store types. Reusable code FTW!

It differs from ActiveModel in that it doesn't provide any validation support, serialization, callbacks, state machine or anything like that. Veneer is intended to work with ActiveModel to provide a data store independant interface to create reusable code.

Veneer instead aims to provide a simple interface for

  • querying
  • creating
  • saving
  • deleting
  • basic lifecycle hooks ** before validation ** before save ** after save ** before destroy ** after destroy

There is no interface for validations, since this interface is handled as part of ActiveModel

Creating and Saving an instance

To create an instance of an object wrap the class in a vaneer call and create or get a new instance.

obj = Veneer(MyModel).new(:some => "hash", :of => "attributes")
obj.save

 # OR

obj = Veneer(MyModel).create(:some => "hash", :of => "attributes")

There are also version that will raise an exception if it could not save

obj = Veneer(MyModel).new(:some => "attribute").save!

# OR

obj = Veneer(MyModel).create!(:some => "attribute")

h2. Deleting

You can delete all the instances of a model or a single instance.

Veneer(MyModel).destroy\_all # delete all instances

@some\_veneer\_model.destroy

Updating

To update an instance:

@some\_veneer\_instance.update(:with => "attributes")

OR

@some\_veneer\_instance.update!(:with => "attributes") # raise on error

Queries

Veneer lets you query models with a simple interface. Only simple queries are supported.

You can query a single object, or multiple objects.

Veneer(MyModel).first(:conditions => {:name => "foo"})

Veneer(MyModel).all(:conditions => {:age => 18}, :limit => 5)

The supported options are:

  • :limit
  • :offset
  • :order
  • :conditions

Limit & Offset

The :limit option will limit the number of returned results.

The :offset option, when set to an integer x will begin the results at the xth result.

Order

Ordering should be set as an array. By default, the order is decending.

The format of the array is:

["<field> <directon>", "<field>"]

### Example
  Veneer(MyModel).all(:order => [:name, "age desc")

Conditions

Conditions are a very simple set of conditions on the fields of the model. The for of the conditions are:

:conditions => {:field => value}

  Veneer(MyModel).all(:conditions => {:name => ["fred", "barney"], :age => (18..18)})
  Veneer(MyModel).first(:conditions => {:name => "fred"})

Condition fields should be ready to accept:

  • String
  • Range (Between clauses)
  • Array (IN clauses)
  • nil

The results of a query are all wrapped as Veneer instances.

All Together

Veneer(MyModel).all(:order => [:name, "age asc"], :limit => 5, :offset => 15, :conditions => {:name => "betty", :age => (0..18)})

Object methods

All methods that aren't found on the adapter, are passed through to the instance. So to access any attributes on the actual model instance, just call the method on it. This can be handy to access things that should be avaialble with an ActiveModel.

Current Support

Veneer currently has built in support for ActiveRecord and DataMapper.

Veneer works on a VeneerInterface inner module though so you can easily impelment your adapter without requiring it to be in the veneer repo (although pull requests are welcome) (see Building Your Adapter)

To use DataMapper or ActiveRecord


require 'veneer/adapters/activerecord'
require 'veneer/adapters/datamapper'

Building Your own Adapter

Veneer is made so that you don't need to have access to the main repository to create an adapter. Veneer looks for an inner constant in the klass or object. For example, in ActiveRecord, to provide the adapter, Veneer will look for the adapter in ActiveRecord::VeneerInterface. VeneerInterface should define two classes:

  • ClassWrapper
  • InstanceWrapper

So, you'd end up with

  • ActiveRecord::Base::VeneerInterface::ClassWrapper < Veneer::Base::ClassWrapper
  • ActiveRecord::Base::VeneerInterface::InstanceWrapper < Veneer::Base::InstanceWrapper

By using inner constants, no behavior of the base implementation is overwritten, or will clash with potential methods implented in the base data store.

It also means that any adapter can be created without direct access to the Veneer repository.

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.

Copyright (c) 2009 Daniel Neighman. See LICENSE for details.