Resourceful

Description

A ruby gem to abstract web resource handling.

The key to resourceful is being able to interact with web resources using custom defined objects instead of the raw data. Unlike ActiveResource, Resourceful needs no rigid restful API backing its models. All you need is data in either JSON or XML (or HTML), and be able to creatively define models from that data.

The supported formats are:

  • JSON (objects returned as Ruby Hash)

  • XML (objects returned as Nokogiri Xml object)

Resourceful uses agents to fetch and push data to and from web resources. Supported agents are:

  • rest_client: great for interacting with Restful resources

  • mechanize: great for interacting with raw resources, or secured resources (and for screen scraping raw html)

Installation

gem install kelredd-resourceful

Dependencies

  • nokogiri (xml resource format handling)

  • json (json resource format handling)

  • rest_client (restful web resource access agent)

  • mechanize (more raw web resource access agent; access secured resources)

  • log4r (for resource interaction logging)

Basic Usage

# Single host resource handling
require 'resourceful'
Resourceful::Resource.configure :host => 'localhost:3000'
Resourceful::Resource::Cache.clear
Resourceful::Resource.get '/widgets', :format => 'json'  # specify explicit format
Resourceful::Resource.get '/widgets.json'                # or, imply format from resource request

Defining Models

So it’s all about the models, right. So you have this data resource on the web: a JSON API, an XML feed, an old crappy HTML page, a secured page with personal data you want to access. You start noticing attributes and relationships in this data - it’s time to define some models. Enter resourceful. Resourceful gives you fancy pants ways to define and test some models, without bothering with all the kruft of accessing those resources via the web. Check it:

# TODO: show examples of

  • base access stuff

  • defining attributes

  • defining associations

  • testing the model

Caching

Resourceful provides resource caching by default, both at the model level and at the agent level.

Model Caching

Model caching refers to using the instance of the model to store attribute and association values. Resourceful, by default, caches all attribute values and associations in the model instance. Both attribute values and association values can be “reloaded” by passing true as a single parameter to the attribute or association method. Please note:

  • For attribute values, “reloading” simply means parsing the value from the existing raw agent data. The resource is not fetched via the web for attribute reloading.

  • For associations, “reloading” means calling out for the resource and fetching it from the web. This bypasses any agent caching and forces the resource data to be downloaded.

Agent Caching

Agent caching refers to using a built in cache to store web resource responses for future access. Resourceful, by default, caches all web requests made via the agents. Resource responses are cached in memory, based on a unique key, and expire, by default, after 60 seconds. Custom expiration periods can be specified. This improves performance when repetitively accessing the same resource, while ensuring the resource does not become stale. Caching can be bypassed on any request by forcing data download using the :force => true option in agent or model data access methods.

  • Note: all cached requests will be prepended with “[CACHE]” in resource agent logs

Logging

Resourceful provides resource agent logging for you by default. Log information is written to the console for confirmation of resource access. In addition, you can specify a file to log to by implementing a block that returns the path of a file to log to, such as:

@mechanize ||= Resourceful::Agent::Mechanize.new(:host => @host, :agent_alias => @agent_alias, :verbose => @verbose) do
  @log_file ? File.expand_path(@log_file) : nil
end

Examples

# TODO: add in examples:

  • Screen scraping example (using mechanize to access a secured resource)

  • Restful JSON / XML resources

  • Resourceful external associations

  • Resourceful embedded associations

  • Using associations with non resourceful ruby class (such as an ActiveRecord model)

  • Association eager loading

Testing the Resourceful gem

A suite of cucumber features are available for you to run as acceptance tests. You should look to the features for additional documentation and usage scenarios. To run the features:

# make sure you have these gems
$ sudo gem install cucumber
$ sudo gem install fakeweb
# change to the resourceful gem installed location
$ cd /opt/local/lib/ruby/gems/x.x/gems/kelredd-resourceful-xxx
$ rake features

License

Copyright © 2010 Kelly Redding ([email protected])

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.