restfulie 0.6.0 → 0.7.0

data/README.textile

@@ -1,21 +1,97 @@
 h1. Web site
 
-Restulie's website can be found at "http://restfulie.caelum.com.br":http://restfulie.caelum.com.br
+Restfulie's website can be found at "http://restfulie.caelum.com.br":http://restfulie.caelum.com.br
+Mikyung's, a REST agent framework built on top of Restfulie can be seen at "http://github.com/caelum/mikyung":http://github.com/caelum/mikyung.
 
 h1. Quit pretending
 
-CRUD through HTTP is a good step forward to using resources and becoming RESTful, another step further into it is to make use of hypermedia based services and this gem allows you to do it really fast.
+CRUD through HTTP is a good step forward to using resources and becoming RESTful, another step further into it is to make use of hypermedia and semantic meaningful media types: this gem allows you to do it really fast.
 
 You can read the "article on using the web for real":http://guilhermesilveira.wordpress.com/2009/11/03/quit-pretending-use-the-web-for-real-restfulie/ which gives an introduction to hypermedia/resources/services.
 
 h2. Why would I use restfulie?
 
-1. Easy --> writing hypermedia aware resource based clients
-2. Easy --> hypermedia aware resource based services
-3. Small -> it's not a bloated solution with a huge list of APIs
-4. HATEOAS --> clients you are unaware of will not bother if you change your URIs
-5. HATEOAS --> services that you consume will not affect your software whenever they change part of their flow or URIs
+#  Easy --> writing hypermedia and semantic meaningful media type aware clients
+#  Small -> it's not a bloated solution with a huge list of APIs
+#  HATEOAS --> clients you are unaware of will not bother if you change your URIs
+#  HATEOAS --> resources that you consume will not affect your software whenever they change part of their flow or URIs
+#  Adaptability --> clients are able to adapt to your changes
+ 
+h2. Installing
 
+For client side usage, execute:
+
+<pre>
+gem install activesupport
+gem install restfulie
+</pre>
+
+For server side usage, execute:
+
+<pre>
+gem install restfulie
+</pre>
+
+h2. Simple server example
+
+In the server side, all you need to do is notify inherited_resources which media types you are able to represent your resource:
+
+<pre>
+	class OrdersController < ApplicationController
+	  include Restfulie::Server::ActionController::Base
+
+	  respond_to :atom, :html, :xml, :commerce, :opensearch
+
+	  def index
+	    respond_with @orders = Order.all
+	  end
+
+	  def show
+	    respond_with @order = Order.find(params[:id])
+	  end
+
+	end
+</pre>
+
+That's it. Restfulie will take care of rendering a valid representation according to content negotiation. You can configure the rendering process through a custom tokamak view:
+
+<pre>
+	describe_collection(@orders) do |collection|
+	  collection.id = orders_url
+	  collection.links << link( :rel => :create,  :href => orders_url )
+	  collection.describe_members
+	end
+</pre>
+
+You can go through an entire application by "watching this video":http://guilhermesilveira.wordpress.com or "downloading an example application":http://github.com/caelum/mikyung.
+
+h2. Simple client example
+
+The following example is a partial REST client implementation that navigates through some relations:
+
+<pre>
+order = Restfulie.at('http://localhost:3000/orders/1').get!
+order.items.each { |item| puts items }
+receipt = order.payment.post! { :amount => 500 }
+puts receipt.id
+</pre>
+
+In order to create a full REST client, "watch this video":http://guilhermesilveira.wordpress.com.
+
+h2. Download source example
+
+You can view an entire application running Restfulie under *spec/integration/order/server* and *spec/integration/order/client* in this git repository.
+
+"You can also download a full example of a REST based agent and server":http://github.com/caelum/mikyung using Restfulie and Mikyung, according to the Rest Architecture Maturity Model.
+
+h2. Building the project
+
+If you want to build the project and run its tests, remember to install all (client and server) required gems and:
+
+<pre>
+gem install rack-conneg
+gem install responders_backport
+</pre>
 
 <script type="text/javascript">
 var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");

data/Rakefile

@@ -3,12 +3,13 @@ require 'rubygems/specification'
 require 'rake'
 require 'rake/gempackagetask'
 require 'spec/rake/spectask'
+require 'rake/rdoctask'
 
 GEM = "restfulie"
-GEM_VERSION = "0.6.0"
-SUMMARY = "Hypermedia aware resource based library in ruby (client side) and ruby on rails (server side)."
-AUTHOR = "Guilherme Silveira, Caue Guerra"
-EMAIL = "guilherme.silveira@caelum.com.br"
+GEM_VERSION = "0.7.0"
+SUMMARY  = "Hypermedia aware resource based library in ruby (client side) and ruby on rails (server side)."
+AUTHOR   = "Guilherme Silveira, Caue Guerra"
+EMAIL    = "guilherme.silveira@caelum.com.br"
 HOMEPAGE = "http://restfulie.caelumobjects.com"
 
 spec = Gem::Specification.new do |s|
@@ -18,28 +19,111 @@ spec = Gem::Specification.new do |s|
   s.summary = SUMMARY
   s.require_paths = ['lib']
   s.files = FileList['lib/**/*.rb', '[A-Z]*'].to_a
-  s.add_dependency("ratom", [">= 0.6.3"])
-  # s.add_dependency("jeokkarak", [">= 1.0.3"])
-
-  # s.add_dependency(%q<rubigen>, [">= 1.3.4"])
+  s.add_dependency("actionpack", [">= 2.3.2"])
+  s.add_dependency("activesupport", [">= 2.3.2"])
+  s.add_dependency("responders_backport", ["~> 0.1.0"])
 
   s.author = AUTHOR
   s.email = EMAIL
   s.homepage = HOMEPAGE
 end
 
-Spec::Rake::SpecTask.new do |t|
-  t.spec_files = FileList['spec/**/*_spec.rb']
-  t.spec_opts = %w(-fs -fh:doc/specs.html --color)
+namespace :test do
+  def execute_process(name)
+    sh "ruby ./spec/units/client/#{name}.rb &"  
+    %x(ps -ef | grep #{name}).split[1]  
+  end
+  def process(name)
+    %x(ps -ef | grep #{name} | grep -v grep).split[1] || execute_process(name)
+  end
+  def start_server_and_invoke_test(task_name)
+    pid = process "fake_server"
+    puts "fake_server pid >>>> #{pid}"
+    Rake::Task[task_name].invoke
+    sh "kill -9 #{pid}"
+  end
+
+  desc "Execute integration Order tests"
+  task :integration do
+    integration_path = "spec/integration/order/server"
+
+    Dir.chdir(File.join(File.dirname(__FILE__), integration_path)) do
+      system('rake db:drop db:create db:migrate')
+      system('rake')
+    end
+  end
+  
+  namespace :spec do
+    spec_opts = ['--options', File.join(File.dirname(__FILE__) , 'spec', 'units', 'spec.opts')]
+    Spec::Rake::SpecTask.new(:all) do |t|
+      t.spec_files = FileList['spec/units/**/*_spec.rb']
+      t.spec_opts = spec_opts
+    end
+    Spec::Rake::SpecTask.new(:common) do |t|
+      t.spec_files = FileList['spec/common/**/*_spec.rb']
+      t.spec_opts = spec_opts
+    end
+    Spec::Rake::SpecTask.new(:client) do |t|
+      t.spec_files = FileList['spec/units/client/**/*_spec.rb']
+      t.spec_opts = spec_opts
+    end
+    Spec::Rake::SpecTask.new(:server) do |t|
+      t.spec_files = FileList['spec/units/server/**/*_spec.rb']
+      t.spec_opts = spec_opts
+    end
+  end
+  
+  namespace :rcov do
+    Spec::Rake::SpecTask.new('rcov') do |t|
+      options_file = File.expand_path('spec/units/spec.opts')
+      t.spec_opts = %w(-fs -fh:doc/specs.html --color)
+      t.spec_files = FileList['spec/units/**/*_spec.rb']
+      t.rcov = true
+      t.rcov_opts = ["-e", "/Library*", "-e", "~/.rvm", "-e", "spec", "-i", "bin"]
+    end
+  end
+  
+  namespace :run do
+    task :all do
+      start_server_and_invoke_test('test:spec:all')
+      puts "Execution integration tests... (task test:integration)"
+      Rake::Task["test:integration"].invoke()
+    end
+    task :common do
+      start_server_and_invoke_test('test:spec:common')
+    end
+    task :client do
+      start_server_and_invoke_test('test:spec:client')
+    end
+    task :server do
+      start_server_and_invoke_test('test:spec:server')
+    end
+    task :rcov do
+      start_server_and_invoke_test('test:rcov:rcov')
+    end
+  end
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
   pkg.gem_spec = spec
 end
 
+Rake::RDocTask.new("rdoc") do |rdoc|
+   rdoc.options << '--line-numbers' << '--inline-source'
+#   rdoc.rdoc_files.include('lib/**/**/*.rb')
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/restfulie/**/*.rb', 'README.textile']   # optional
+    # t.options = ['--any', '--extra', '--opts'] # optional
+  end
+rescue; end
+
 desc "Install the gem locally"
 task :install => [:package] do
-  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION} -l}
+  sh %{gem install pkg/#{GEM}-#{GEM_VERSION} -l}
 end
 
 desc "Create a gemspec file"
@@ -53,4 +137,5 @@ desc "Builds the project"
 task :build => :spec
 
 desc "Default build will run specs"
-task :default => :spec
+task :default => ['test:run:all']
+

data/lib/restfulie/client/base.rb

@@ -1,65 +1,60 @@
-#
-#  Copyright (c) 2009 Caelum - www.caelum.com.br/opensource
-#  All rights reserved.
-# 
-#  Licensed under the Apache License, Version 2.0 (the "License"); 
-#  you may not use this file except in compliance with the License. 
-#  You may obtain a copy of the License at 
-#  
-#   http://www.apache.org/licenses/LICENSE-2.0 
-#  
-#  Unless required by applicable law or agreed to in writing, software 
-#  distributed under the License is distributed on an "AS IS" BASIS, 
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
-#  See the License for the specific language governing permissions and 
-#  limitations under the License. 
-#
+module Restfulie::Client#:nodoc
 
-class Hash
-  def to_object(body)
-    if keys.length>1
-      raise "unable to parse an xml with more than one root element"
-    elsif keys.length == 0
-      self
-    else
-      type = keys[0].camelize.constantize
-      type.from_xml(body)
+  module EntryPoint
+    include HTTP::RequestMarshaller
+    extend self
+
+    @resources_configurations = {}
+    def configuration_of(resource_name)
+      @resources_configurations[resource_name]
     end
-  end
-end
 
-module Restfulie
+    def configuration_for(resource_name,configuration = Configuration.new)
+      yield configuration if block_given?
+      @resources_configurations[resource_name] = configuration
+    end
+
+    def retrieve(resource_name)
+      returning Object.new do |resource| 
+        restore.extend(Base)
+        resource.configure
+      end
+    end
 
-  # will execute some action in a specific URI
-  def self.at(uri)
-    Client::RequestExecution.new(nil, nil).at uri
   end
-  
-  module Client
-    module Config
-      BASIC_MAPPING = { :delete => Net::HTTP::Delete, :put => Net::HTTP::Put, :get => Net::HTTP::Get, :post => Net::HTTP::Post}
-      DEFAULTS = { :destroy => Net::HTTP::Delete, :delete => Net::HTTP::Delete, :cancel => Net::HTTP::Delete,
-                   :refresh => Net::HTTP::Get, :reload => Net::HTTP::Get, :show => Net::HTTP::Get, :latest => Net::HTTP::Get, :self => Net::HTTP::Get}
 
-      def self.self_retrieval
-        [:latest, :refresh, :reload, :self]
-      end
-  
-      def self.requisition_method_for(overriden_option,name)
-        return BASIC_MAPPING[overriden_option.to_sym] if overriden_option
-        DEFAULTS[name.to_sym] || Net::HTTP::Post
-      end
-    
+  module Base
+    include HTTP::RequestMarshaller
+   
+    def self.included(base)#:nodoc
+      base.extend(self)
     end
-    
-    module Base
 
-      def is_self_retrieval?(name)
-        name = name.to_sym if name.kind_of? String
-        Restfulie::Client::Config.self_retrieval.include? name
+    def uses_restfulie(configuration = Configuration.new,&block)
+      EntryPoint.configuration_for(resource_name,configuration,&block)
+      configure
+    end
+
+    def configure
+      configuration = EntryPoint.configuration_of(resource_name)
+      raise "Undefined configuration for #{resource_name}" unless configuration
+      at(configuration.entry_point)
+      configuration.representations.each do |representation_name,representation|
+        register_representation(representation_name,representation)
       end
-    
     end
-    
+
+    def resource_name
+      @resource_name || @resource_name = self.class.to_s.to_sym 
+    end
+
   end
+
 end
+
+# Shortcut to Restfulie::Client::EntryPoint
+module Restfulie
+  include Client::EntryPoint
+  extend self
+end
+

data/lib/restfulie/client/configuration.rb

@@ -0,0 +1,69 @@
+module Restfulie::Client #:nodoc:
+
+  # Use this class to configure the entry point and other relevant behaviors related to accessing or interacting with resources
+  # 
+  # The available options are:
+  # 
+  # * <tt>:entry_point</tt> - The URI for an entry point, such as http://resource.entrypoint.com/post
+  # * <tt>:representations</tt> - Representations.
+  # 
+  # You can also store any other custom configuration.
+  # 
+  # ==== Example
+  # 
+  #   configuration = Configuration.new
+  #   configuration[:entry_point] = 'http://resource.entrypoint.com/post'
+  #   configuration[:entry_point] # => 'http://resource.entrypoint.com/post'
+  # 
+  # or you can use:
+  # 
+  #   configuration.entry_point = 'http://resource.entrypoint.com/post'
+  #   configuration.entry_point # => 'http://resource.entrypoint.com/post'
+  class Configuration < ::Hash
+
+    # the current environment
+    attr_reader :environment
+
+    @@default_configuration = {
+      :entry_point     => '',
+      :representations => {}
+    }
+
+    def initialize
+      super
+      self.environment = :development
+    end
+
+    # this will store a new configuration (based on the default) for the environment passed by value.
+    def environment=(value)
+      @environment = value
+      unless has_key?(@environment) 
+        dee_clone = Marshal::load(Marshal::dump(@@default_configuration))
+        store(@environment,dee_clone)
+      end
+      @environment
+    end
+
+    # access (key) configuration value
+    def [](key)
+      fetch(@environment)[key]
+    end
+
+    # store on (key) configuration the value
+    def []=(key,value)
+      fetch(@environment)[key] = value
+    end 
+
+    def method_missing(name, *args, &block)
+      method_name = name.to_s
+      if method_name.last == '='
+        fetch(environment)[method_name.chop.to_sym] = args[0]
+      else
+        value = fetch(environment)[name]
+        value ? value : super
+      end
+    end
+
+  end
+  
+end