restfulie 0.3 → 0.4.0

data/README.textile

@@ -12,553 +12,17 @@ h2. Why would I use restfulie?
 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
 
-h2. Could you compare it with Spring or JAX-RS based APIs?
+h2. Restfulie
 
-Restfulie is the first API which tries to somehow implement "Jim Webber":http://jim.webber.name/ and "Ian Robinson":http://iansrobinson.com/ opinion on how RESTFul systems use hypermedia
-as the way to lead your client's path through a business process.
+The documentation is at "http://wiki.github.com/caelum/restfulie":http://wiki.github.com/caelum/restfulie
 
-Therefore Restfulie is unique both in its feature set when compared to both Spring and JAX-RS based implementations, and its implementation: looking for simple code and favoring conventions over manual configurations.
-
-h1. Short examples
-
-h2. Restfulie: client-side
-
-Example on accessing a resource and its services through the restfulie API:
-
-<pre>
-order = Order.from_web resource_uri
-
-puts "Order price is #{order.price}"
-
-order.pay payment                        # sends a post request to pay this order
-
-order.cancel                             # sends a delete request
-</pre>
-
-h2. Restfulie: server-side
-
-This is a simple example how to make your state changes available to your resource consumers:
-
-<pre>
-class Order < ActiveRecord::Base
-
-  acts_as_restfulie
-
-  def following_transitions
-    transitions = []
-    transitions << [:show, {}]
-    transitions << [:destroy, {}] if can_cancel?
-    transitions << [:pay, {:id => id}] if can_pay?
-    transitions
-  end
-end
-</pre>
-
-*You might want to create a migration with a string field named status for your resource:*
-
-<pre>
-scripts/generate migration add_status_to_order	
-</pre>
-
-Content:
-
-<pre>
-class AddStatusToOrder < ActiveRecord::Migration
-  def self.up
-    add_column :orders, :status, :string
-	Order.all.each do |order|
-		order.status = "unpaid"
-		order.save
-	end
-  end
-
-  def self.down
-    remove_column :orders, :status
-  end
-end
-</pre>
-
-Or simply define a status reader and writer on your own.
-
-h2. Restfulie server-side: state machine
-
-For those willing to implement a more complex or advanced state machine, you can use the dsl-like api:
-
-<pre>
-class Order < ActiveRecord::Base
-  acts_as_restfulie
-
-  state :unpaid, :allow => [:latest, :pay, :cancel]
-  state :cancelled, :allow => :latest
-
-  transition :latest, {:action => :show}
-  transition :cancel, {:action => :destroy}, :cancelled
-  transition :pay, {}, :preparing
-end
-</pre>
-
-h1. Installing
-
-Just add in your environment.rb the following line:
-
-<pre>
-config.gem "restfulie", :source => "http://gemcutter.org"
-</pre>
-
-And then execute:
-<pre>rake gems:install</pre>
-
-or, if you prefer to install it as a plugin:
-
-<pre>script/plugin install git://github.com/caelum/restfulie.git</pre>
-
-h2. Typical hypermedia aware example
-
-Trying to follow the definition of a RESTful application supporting resources with hypermedia content, a resource would be:
-
-<pre>
-<order>
-	<product>basic rails course</product>
-	<product>RESTful training</product>
-	<atom:link rel="refresh" href="http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom"/>
-	<atom:link rel="update" href="http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom"/>
-	<atom:link rel="pay" href="http://www.caelum.com.br/orders/1/pay" xmlns:atom="http://www.w3.org/2005/Atom"/>
-	<atom:link rel="destroy" href="http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom"/>
-</order>
-</pre>
-
-h2. Client Usage
-
-Create your class and invoke the *uses_restfulie* method:
-
-<pre>class Order < ActiveRecord::Base
-	uses_restfulie
-end
-</pre>
-
-One should first acquire the representation from the server through your common GET request and process it through the usual from_* methods:
-<pre>xml = Net::HTTP.get(URI.parse('http://www.caelum.com.br/orders/1'))
-order = Order.from_xml(xml)</pre>
-or use the restfulie *from_web*:
-<pre>order = Order.from_web 'http://www.caelum.com.br/orders/1'</pre>
-
-And now you can invoke all those actions in order to change your resource's state:
-
-<pre>
-order.refresh
-order.update
-order.destroy
-order.pay
-</pre>
-
-Note that:
-* refresh is get
-* update is put (and you have to put everything back)
-* destroy is delete
-* pay (unknown methods) is post
-
-h2. Resource format support
-
-Restfulie currently supports full xml+atom, partial xml+rel and will soon expand its support to json+links.
-
-
-h2. Help
-
-If you are looking for or want to help, let us know at the mailing list:
-
-"http://groups.google.com/group/restfulie":http://groups.google.com/group/restfulie
-
-h2. Client-side configuration: how to customize your request
-
-h3. HTTP verbs
-
-By default, restfulie uses the following table:
-
-* destroy, cancel and delete send a DELETE request
-* update sends a PUT request
-* refresh, reload, show, latest sends a GET request
-* other methods sends a POST request
-
-If you want to use a custom http verb in order to send your request, you can do it by setting the optional string 'method':
-
-<pre>order.update(:method=>"post")</pre>
-
-h3. Request parameters
-
-If you want to send extra parameters, you can do it through the *data* parameter:
-
-<pre>order.pay(:data => {:payment => my_payment})</pre>
-
-The parameters will be serialized either to xml or json according to which format was used to deserialize the order at first place.
-
-h3. Executing another GET request
-
-If your method executes another GET request, it will automatically deserialize its result as:
-
-<pre>order = Order.from_web order_uri
-payment = order.check_payment_info</pre>
-
-If you want to parse the response yourself, instead of receiving just the final deserialized object, you can do it by passing a body to your method
-
-<pre>order = Order.from_web order_uri
-successful = order.check_payment_info do |response|
-  return response.code==200
-end</pre>
-
-h2. Server-side configuration
-
-There are two different approaches that can be combined to create a full hypermedia aware resource based service, including awareness of its states and transitions.
-
-h3. Simple usage: following transitions
-
-The most easy way to use restfulie is to write the *following_transitions* method.
-There are three easy steps to make it work:
-
-1. Create your model (i.e. Order) with an *status* field
-<pre>
-script/generate scaffold Order status:string location:string
-rake db:create
-rake db:migrate
-</pre>
-
-Note that with this usage the status field is optional (from 0.3.0 onwards).
-
-2. Add the *acts_as_restfulie* invocation and *following_transitions* method returning an array of possible transitions:
-
-<pre>
-acts_as_restfulie
-
-def following_transitions
-  transitions = []
-  transitions << [:show, {}]
-  transitions
-end
-</pre>
-
-3. Update your *show* method within the *OrdersController* to show the hypermedia content:
-
-<pre>
- def show
-   @order = Order.find(params[:id])
-
-   respond_to do |format|
-     format.html # show.html.erb
-     format.xml  { render :xml => @order.to_xml(:controller=>self) }
-   end
- end
-</pre>
-
-You are ready to go, create a new order and save it into the database:
-
-<pre>
-	order = Order.new
-	order.location = "take away"
-	order.status = "unpaid"
-	order.save
-	puts "Order #{order.id} saved"
-</pre>
-
-Start up the server:
-
-<pre>
-	script/server
-</pre>
-
-And now access your server at http://localhost:3000/orders/1.xml
-
-<pre>
-<?xml version="1.0" encoding="UTF-8"?>
-<order>
-  <created-at>2009-11-23T00:15:15Z</created-at>
-  <id>1</id>
-  <location>take away</location>
-  <status>unpaid</status>
-  <updated-at>2009-11-23T00:15:15Z</updated-at>
-  <atom:link rel="show" xmlns:atom="http://www.w3.org/2005/Atom" href="http://localhost:3000/orders/3"/>
-</order>
-</pre>
-
-h3. Customizing the rel name
-
-You can also override the action used, but still keep the rel
-
-<pre>
-def following_transitions
-  transitions = []
-  transitions << [:cancel, { :action => :destroy }]
-  transitions
-end
-</pre>
-
-Which will generate an hyperlink as
-
-<pre><atom:link rel="cancel" rel="http://yourserver/orders/15" /></pre>
-
-h3. Example
-
-A full example showing all capabilities of this method follows:
-
-<pre>
-def following_transitions
-  transitions = []
-  transitions << [:show, {}]
-  transitions << [:destroy, {}] if can_cancel?
-  transitions << [:pay, {:id => id}] if can_pay?
-  transitions << [:show, {:controller => :payments, :payment_id => payment.id }] if paid?
-  transitions
-end
-</pre>
-
-h2. Advanced usage: Defining the state machine and its transitions
-
-The second way of defining your available transitions is to explicitely define the states and transitions.
-
-By using this approach, one has to define a new column named *status* in a database migration file.
-
-The first step involves defining all your states, each one with its own name and possible transitions, as:
-
-<pre>
-	state :state_name, :allow => [ :first_transition_name, :second_transition_name]
-</pre>
-
-The following example shows all possible states for an order:
-
-<pre>
-class Order < ActiveRecord::Base
-
-	acts_as_restfulie
-	
-	state :unpaid, :allow => [:latest, :pay, :cancel]
-	state :cancelled, :allow => :latest
-	state :received, :allow => [:latest, :check_payment_info]
-	state :preparing, :allow => [:latest, :check_payment_info]
-	state :ready, :allow => [:latest, :receive, :check_payment_info]
-end
-</pre>
-
-Now its time to define which controller and action each transition invokes, in a much similar way to
-the transition definitions in the following_transitions method:
-
-<pre>
-class Order < ActiveRecord::Base
-end
-</pre>
-
-Once a transition has been given a name, its name can be used in the following_transitions method also.
-The next example does not configure the transition because it was already defined, only adding it to the
-list of available transition whenever the *can_pay?* method returns true:
-
-<pre>
-class Order < ActiveRecord::Base
-
-	acts_as_restfulie
-	
-	transition :pay, {:action => pay_this_order, :controller => :payments}, :preparing
-
-	def following_transitions
-	  transitions = []
-	  transitions << :pay if can_pay?
-	  transitions
-	end
-end
-</pre>
-
-Note that whenever one defines a transition, there is a third - optional - argument, this is the
-transition's target's state. Whenever the method *order.pay* method is invoked in the *server*, it will
-automatically change the order's status to *preparing*.
-
-You can download the server side example to see the complete code.
-
-The last usage of the transition definition involves passing a block which receives the element in which
-the transition URI's is required. The block should return all the necessary information for retrieving the URI, now having access to your element's instance variables:
-
-<pre>
-class Order < ActiveRecord::Base
-	transition :check_payment_info do |order|
-	   {:controller => :payments, :action => :show, :order_id => order.id, :payment_id => order.payments[0].id, :rel => "check_payment_info"}
-	end
-end
-</pre>
-
-h3. Accessing all possible transitions
-
-One can access all possible transitions for an object by invoking its available_transitions method:
-
-<pre>
-	transitions = order.available_transitions
-</pre>
-
-h3. Checking the possibility of following transitions
-
-By following the advanced usage, one receives also all *can_* method. i.e.:
-
-<pre>
-	order.status = :unpaid
-	puts(order.can_pay?)              # will print true
-	order.status = :paid
-	puts(order.can_pay?)              # will print false
-</pre>
-
-You can use the *can_xxx* methods in your controllers to check if your current resource's state can be changed:
-
-<pre>
-def pay
-  @order = Order.find(params[:id])
-  raise "impossible to pay due to this order status #{order.status}" if !@order.can_pay?
-
-  # payment code
-end
-</pre>
-  
-h3. Using xml+rel links instead of atom links
-
-Atom is everywhere and can be consumed by a number of existing tools but if your system wants to supply its
-services through commons rel+link xml as
-
-<pre>
-	<order>
-		<product>basic rails course</product>
-		<product>RESTful training</product>
-		<refresh>http://www.caelum.com.br/orders/1</refresh>
-		<update>http://www.caelum.com.br/orders/1</update>
-		<pay>http://www.caelum.com.br/orders/1/pay</pay>
-		<destroy>http://www.caelum.com.br/orders/1</destroy>
-	</order>
-</pre>
-
-You can do it by passing the *use_name_based_link* argument:
-
-<pre>
-    order.to_xml(:controller => my_controller, :use_name_based_link => true)
-</pre>
-
-h2. Team
-
-Restfulie was created and is maintained within Caelum by
-
-Projetct Founder
-* "Guilherme Silveira":mailto:guilherme.silveira@caelum.com.br - twitter:http://www.twitter.com/guilhermecaelum "http://guilhermesilveira.wordpress.com":http://guilhermesilveira.wordpress.com
-
-Active Commiters
-* "Caue Guerra":mailto:caue.guerra@gmail.com - "http://caueguerra.com/":http://caueguerra.com/
-* "Guilherme Silveira":mailto:guilherme.silveira@caelum.com.br
-
-Contributors
-* Diego Carrion
-* Leandro Silva
-* Gavin-John Noonan
-
-h2. Try it online
-
-We have a live example of a server implementation using a resource+hypermedia course ordering system available.
-
-Follow the steps below to try out the system:
-
-* "Access the server system":http://restfulie-test.heroku.com
-* Create a couple of trainings
-* Create an order
-* Access the order listing and retrieve its xml link
-
-And now you can try the restfulie client api through a simple and generic resource+hypermedia client application:
-
-* "Access the client system":http://restfulie-client.heroku.com
-* Enter your order uri
-* Check your order information which was retrieved and all available actions
-
-Now you can either:
-
-* *latest* - refresh your order information  _order.latest_
-* *cancel* - cancel your order (dead end!) _order.destroy_
-* *pay* - pay for your order, and don't forget to send your (fake) credit card information _order.pay(payment)_
-* *check_payment_info* - after paying you can check the payment information stored at the server _order.check_payment_info_
-
-In order to pay do not forget to send the parameter *payment* with a value as
-
-<pre>
- <payment>
-   <amount>15</amount>
-   <cardholder_name>Guilherme Silveira</cardholder_name>
-   <card_number>123456789012</card_number>
-   <expiry_month>12</expiry_month>
-   <expiry_year>12</expiry_year>
- </payment>
-</pre>
-
-
-h3. Sources
-
-You can see an application's source code here, both client and server side were implemented using *restfulie*:
-
-"Client":http://github.com/caelum/restfulie-client
-"Server":http://github.com/caelum/restfulie-test
-
-h3. More tutorials
-
-There is a "portuguese tutorial on the server-side support":http://wakethedead.com.br/blog/70-restfulie, "more on restfulie - portuguese":http://andersonleiteblog.wordpress.com/2009/11/23/mais-sobre-restfulie/ and a "blog post on the entire ecosystem in english":http://guilhermesilveira.wordpress.com/2009/11/03/quit-pretending-use-the-web-for-real-restfulie/
-
-
-h2. What's new
-
-h3. next release
-* API change: you need to invoke "acts_as_restfulie" to your models
-* implemented support to can_*** methods
-* post data through http POST body
-* no need for the *status* field if you use the following_transition approach on the server side
-* bug fixed when *status* was nil
-* lots of internal refactoring
-* lots of new documentation
-
-h3. 0.2
-* support to state machine configuration
-* resources must contain a status field
-
-h3. 0.1
-* first release
-
-h2. Coming soon
-
-* Generate and link to rubydoc
-* release 0.3
-* change parameter order for transition: last one is HASH, first is name, second (if existing) is target state
-* allows pure String/byte array client side post and server side retrieval
-* integration tests on orderserver/client api
-* controller method should check if its an restfulie resource
-* full support to extended json
-* rel prepend suffix as http://iansrobinson.com/resources/link-relations/preceding
-* automatically generate uri for this rel with its transition description
-* pure href definition of link
-* post entry point support
-* remove client dependency from ActiveRecord
-* remove server side dependency from ActiveRecord (its ok to use anything else)
-* Set the correct media type instead of application/xml
-* transitions << [:show]  should work
-* rails 3 easier support (no controller argument!)
-* allow servers to define transitions by accessing other systems
-* allow servers to define a state method instead of internal variable
-* controller filtering and methods
-* english tutorial
-* when receiving a 201 + content, it should believe the content
-* when receiving a 201 without any content, it should allow to redirect or not
-* client side should allow withTimeStamp, withETag, withAuth
-* is there is an etag, use it by default (maybe NOT use it by default)... modified since and so on (header tags)
-* server side maybe allow hypermedia controls or not
-
-h2. License
-
-/***
- * 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.
- */
 
+<script type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+try {
+var pageTracker = _gat._getTracker("UA-11770776-1");
+pageTracker._trackPageview();
+} catch(err) {}</script>

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/gempackagetask'
 require 'spec/rake/spectask'
 
 GEM = "restfulie"
-GEM_VERSION = "0.3"
+GEM_VERSION = "0.4.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"
@@ -37,7 +37,7 @@ end
 
 desc "Install the gem locally"
 task :install => [:package] do
-  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION} -l}
 end
 
 desc "Create a gemspec file"

data/lib/restfulie/client/base.rb

@@ -1,18 +1,36 @@
 module Restfulie
   module Client
-    module Base 
-    
-      # translates a response to an object
-      def from_response(res)
+    module Base
+
+      SELF_RETRIEVAL = [:latest, :refresh, :reload]
       
-        raise "unimplemented content type" if res.content_type!="application/xml"
+      class UnsupportedContentType < Exception
+        attr_reader :msg
+        def initialize(msg)
+          @msg = msg
+        end
+        def to_s
+          @msg
+        end
+      end
 
-        hash = Hash.from_xml res.body
+      # translates a response to an object
+      def from_response(res, invoking_object)
+        
+        return invoking_object if res.code=="304"
+        
+        raise UnsupportedContentType.new("unsupported content type '#{res.content_type}' '#{res.code}'") unless res.content_type=="application/xml"
+
+        body = res.body
+        return {} if body.empty?
+        
+        hash = Hash.from_xml body
         return hash if hash.keys.length == 0
+        
         raise "unable to parse an xml with more than one root element" if hash.keys.length>1
       
         type = hash.keys[0].camelize.constantize
-        type.from_xml(res.body)
+        type.from_xml(body)
       
       end
     
@@ -24,53 +42,12 @@ module Restfulie
         return basic_mapping[overriden_option.to_sym] if overriden_option
         defaults[name.to_sym] || Net::HTTP::Post
       end
-    
-      def add_state(transition)
-        name = transition["rel"]
       
-        self.module_eval do
-        
-          def temp_method(options = {}, &block)
-            self.invoke_remote_transition(Restfulie::Client::Helper.current_method, options, block)
-          end
-        
-          alias_method name, :temp_method
-          undef :temp_method
-        end
-      end  
-    
-      # receives an object and inserts all necessary methods
-      # so it can answer to can_??? invocations
-      def add_transitions(result, states)
-        result._possible_states = {}
-
-        states.each do |state|
-          result._possible_states[state["rel"]] = state
-          add_state(state)
-        end
-        result.extend Restfulie::Server::State
-      
-        result
+      def is_self_retrieval?(name)
+        name = name.to_sym if name.kind_of? String
+        SELF_RETRIEVAL.include? name
       end
-
-      # retrieves a resource form a specific uri
-      def from_web(uri)
-        res = Net::HTTP.get_response(URI.parse(uri))
-        # TODO redirect... follow or not? (optional...)
-        raise "invalid request" if res.code != "200"
-      
-        # TODO really support different content types
-        case res.content_type
-        when "application/xml"
-          self.from_xml res.body
-        when "application/json"
-          self.from_json res.body
-        else
-          raise "unknown content type"
-        end
       
-      end
-
     end
   end
 end

data/lib/restfulie/client/entry_point.rb

@@ -0,0 +1,122 @@
+module Restfulie
+  module Client
+    module Base
+      
+      # configures an entry point
+      def entry_point_for
+        @entry_points ||= EntryPointControl.new(self)
+        @entry_points
+      end
+      
+      # executes a POST request to create this kind of resource at the server
+      def remote_create(content)
+        content = content.to_xml unless content.kind_of? String
+        remote_post content
+      end
+      
+      # handles which types of responses should be automatically followed
+      def follows
+        @follower ||= FollowConfig.new
+        @follower
+      end
+      
+      # retrieves a resource form a specific uri
+      def from_web(uri, options = {})
+        uri = URI.parse(uri)
+        req = Net::HTTP::Get.new(uri.path)
+        options.each do |key,value| req[key] = value end 
+        res = Net::HTTP.start(uri.host, uri.port) {|http|
+          http.request(req) # canc hange to straight .request(req)
+        }
+
+        code = res.code
+        return from_web(res["Location"]) if code=="301"
+
+        if code=="200"
+          # TODO really support different content types
+          case res.content_type
+          when "application/xml"
+            result = self.from_xml res.body
+          when "application/json"
+            result = self.from_json res.body
+          else
+            raise "unknown content type: #{res.content_type}"
+          end
+          result.etag = res['Etag'] unless res['Etag'].nil?
+          result.last_modified = res['Last-Modified'] unless res['Last-Modified'].nil?
+          result
+        else
+          res
+        end
+      
+      end
+
+      private
+      def remote_post(content)
+        remote_post_to(entry_point_for.create.uri, content)
+      end
+      def remote_post_to(uri, content)
+        
+        url = URI.parse(uri)
+        req = Net::HTTP::Post.new(url.path)
+        req.body = content
+        req.add_field("Accept", "application/xml")
+
+        response = Net::HTTP.new(url.host, url.port).request(req)
+        code = response.code
+        
+        if code=="301" && follows.moved_permanently? == :all
+          remote_post_to(response["Location"], content)
+        elsif code=="201"
+          from_web(response["Location"], "Accept" => "application/xml")
+        else
+          response
+        end
+
+      end
+      
+    end
+    
+    class FollowConfig
+      def initialize
+        @entries = {
+          :moved_permanently => [:get, :head]
+        }
+      end
+      def method_missing(name, *args)
+        return value_for name if name.to_s[-1,1]=="?"
+        set_all_for name
+      end
+      
+      private
+      def set_all_for(name)
+        @entries[name] = :all
+      end
+      def value_for(name)
+        return @entries[name.to_s.chop.to_sym]
+      end
+    end
+    
+    class EntryPointControl
+      
+      def initialize(type)
+        @type = type
+        @entries = {}
+      end
+      
+      def method_missing(name, *args)
+        @entries[name] ||= EntryPoint.new
+        @entries[name]
+      end
+
+    end
+    
+    class EntryPoint
+      attr_accessor :uri
+      def at(uri)
+        @uri = uri
+      end
+    end
+    
+  end
+end

data/lib/restfulie/client/instance.rb

@@ -3,28 +3,123 @@ module Restfulie
     module Instance
       
       # list of possible states to access
-      attr_accessor :_possible_states
+      def _possible_states
+        @_possible_states ||= {}
+      end
 
       # which content-type generated this data
       attr_accessor :_came_from
       
-      
       def invoke_remote_transition(name, options, block)
 
         method = self.class.requisition_method_for options[:method], name
 
-        url = URI.parse(_possible_states[name]["href"])
+        state = self._possible_states[name]
+        url = URI.parse(state["href"] || state[:href])
         req = method.new(url.path)
         req.body = options[:data] if options[:data]
         req.add_field("Accept", "application/xml") if self._came_from == :xml
+        req.add_field("If-None-Match", self.etag) if self.class.is_self_retrieval?(name) && self.respond_to?(:etag)
+        req.add_field("If-Modified-Since", self.last_modified) if self.class.is_self_retrieval?(name) && self.respond_to?(:last_modified)
 
         response = Net::HTTP.new(url.host, url.port).request(req)
 
         return block.call(response) if block
-        return response if method != Net::HTTP::Get
-        self.class.from_response response
+        return response unless method == Net::HTTP::Get
+        self.class.from_response response, self
+      end
+
+  
+      # inserts all transitions from this object as can_xxx and xxx methods
+      def add_transitions(transitions)
+
+        transitions.each do |state|
+          self._possible_states[state["rel"] || state[:rel]] = state
+          self.add_state(state)
+        end
+        self.extend Restfulie::Client::State
+      end
+
+    
+      def add_state(transition)
+        name = transition["rel"] || transition[:rel]
+      
+        # TODO: wrong, should be instance_eval
+        self.class.module_eval do
+        
+          def temp_method(options = {}, &block)
+            self.invoke_remote_transition(Restfulie::Client::Helper.current_method, options, block)
+          end
+        
+          alias_method name, :temp_method
+          undef :temp_method
+        end
+      end  
+
+      # returns a list of extended fields for this instance.
+      # extended fields are those unknown to this model but kept in a hash
+      # to allow forward-compatibility.
+      def extended_fields
+        @hash ||= {}
+        @hash
+      end
+
+      def method_missing(name, *args)
+        name = name.to_s if name.kind_of? Symbol
+
+        if name[-1,1] == "="
+          extended_fields[name.chop] = args[0] 
+        elsif name[-1,1] == "?"
+          found = extended_fields[name.chop]
+          return super(name,args) if found.nil?
+          parse(found)
+        else
+          found = extended_fields[name]
+          return super(name,args) if found.nil?
+          parse(transform(found))
+        end
+
+      end
+
+      # TODO test this guy
+      def respond_to?(sym)
+        extended_fields[sym.to_s].nil? ? super(sym) : true
+      end
+
+      # redefines attribute definition allowing the invocation of method_missing
+      # when an attribute does not exist
+      def attributes=(values)
+        values.each do |key, value|
+          unless attributes.include? key
+            method_missing("#{key}=", value)
+            values.delete key
+          end
+        end
+        super(values)
+      end
+
+
+      # serializes the extended fields with the existing fields
+      def to_xml(options={})
+        super(options) do |xml|
+          extended_fields.each do |key,value|
+            xml.tag! key, value
+          end
+        end
       end
 
+      private
+      
+      # transforms a value in a custom hash
+      def transform(value)
+        return CustomHash.new(value) if value.kind_of?(Hash) || value.kind_of?(Array)
+        value
+      end
+      
+      def parse(val)
+        raise "undefined method: '#{val}'" if val.nil?
+        val
+      end
 
 
     end

data/lib/restfulie/{server → client}/state.rb

@@ -1,6 +1,6 @@
 module Restfulie
   
-  module Server
+  module Client
   
     # adds respond_to and has_state methods to resources
     module State

data/lib/restfulie/client.rb

@@ -0,0 +1,25 @@
+require 'net/http'
+require 'uri'
+
+require 'restfulie/client/base'
+require 'restfulie/client/entry_point'
+require 'restfulie/client/helper'
+require 'restfulie/client/instance'
+require 'restfulie/client/state'
+
+module Restfulie
+  
+  # Extends your class to support restfulie-client side's code.
+  # This will extends Restfulie::Client::Base methods as class methods,
+  # Restfulie::Client::Instance as instance methods and Restfulie::Unmarshalling as class methods.
+  def uses_restfulie
+    extend Restfulie::Client::Base
+    include Restfulie::Client::Instance
+    extend Restfulie::Unmarshalling
+  end
+  
+end
+
+Object.extend Restfulie
+
+require 'restfulie/unmarshalling'

data/lib/restfulie/server/base.rb

@@ -22,31 +22,49 @@ module Restfulie
         options[:allow] = [options[:allow]] unless options[:allow].kind_of? Array
         states[name] = options
       end
-
+      
       # defines a new transition. the transition options works in the same way
       # that following_transition definition does.
-      def transition(name, options = {}, result = nil, &body)
+      def transition(name = nil, options = {}, result = nil, &body)
+        return TransitionBuilder.new(self) if name.nil?
       
         transition = Restfulie::Server::Transition.new(name, options, result, body)
         transitions[name] = transition
 
-        define_methods_for(self, name, result)
-        controller_name = (self.name + "Controller")
+        define_execution_method(self, name, result)
+        define_can_method(self, name)
+      end
+      
+      class TransitionBuilder
+        def initialize(type)
+          @type = type
+        end
+        def method_missing(name, *args)
+          @transition = Restfulie::Server::Transition.new(name)
+          @type.transitions[name] = @transition
+          @type.define_can_method(@type, name)
+          self
+        end
+        def at(options)
+          @transition.options = options
+        end
+        def results_in(result)
+          @transition.result = result
+        end
+        
       end
  
-      def define_methods_for(type, name, result) 
-
-        return nil if type.respond_to?(name)
-
+      def define_execution_method(type, name, result) 
         type.send(:define_method, name) do |*args|
-          self.status = result.to_s unless result == nil
-        end
-
+          self.status = result.to_s unless result.nil?
+        end unless type.respond_to?(name)
+      end
+ 
+      def define_can_method(type, name) 
         type.send(:define_method, "can_#{name}?") do
           transitions = self.available_transitions[:allow]
           transitions.include? name
-        end
-
+        end unless type.respond_to?("can_#{name}?")
       end
  
     end

data/lib/restfulie/server/controller.rb

@@ -1,17 +1,33 @@
-require 'restfulie'
-
 module ActionController
-  # class Base
-  #   alias_method :simple_render, :render
-  #   def render(options={})
-  #     debugger
-  #     if options[:xml]
-  #       resource = options[:xml]
-  #       debugger
-  #       return simple_render(options) if resource.kind_of?(String) || !resource.class.respond_to?(:is_acting_as_restfulie)
-  #       options[:xml] = resource.to_xml(:controller => self)
-  #     end
-  #     simple_render(options)
-  #   end
-  # end
+  class Base
+    
+    # renders an specific resource to xml
+    # using any extra options to render it (invoke to_xml).
+    def render_resource(resource, options = {})
+      cache_info = {:etag => resource}
+      cache_info[:last_modified] = resource.updated_at.utc if resource.respond_to? :updated_at
+      if stale? cache_info
+        options[:controller] = self
+        format = (self.params && self.params[:format]) || "xml"
+        if ["xml", "json"].include?(format)
+          render format.to_sym => resource.send(:"to_#{format}", options)
+        else
+          render format.to_sym => resource
+        end
+      end
+    end
+
+    # adds support to rendering resources, i.e.:
+    # render :resource => @order, :with => { :except => [:paid_at] }
+    alias_method :old_render, :render
+    def render(options = nil, extra_options = {}, &block)
+      resource = options[:resource] unless options.nil?
+      unless resource.nil?
+        render_resource(resource, options[:with])
+      else
+        old_render(options, extra_options)
+      end
+    end
+    
+  end
 end

data/lib/restfulie/server/instance.rb

@@ -2,25 +2,6 @@ module Restfulie
   module Server
     module Instance
 
-      # Returns an array with extra possible transitions.
-      # Those transitions will be concatenated with any extra transitions provided by your resource through
-      # the use of state and transition definitions.
-      # For every transition its name is the only mandatory field:
-      # options = {}
-      # [:show, options] # will generate a link to your controller's show action
-      #
-      # The options can be used to override restfulie's conventions:
-      # options[:rel] = "refresh" # will create a rel named refresh
-      # options[:action] = "destroy" # will link to the destroy method
-      # options[:controller] = another controller # will use another controller's action
-      #
-      # Any extra options will be passed to the target controller url_for method in order to retrieve
-      # the transition's uri.
-      def following_transitions
-        []
-      end
-
-
       # returns a list of available transitions for this objects state
       # TODO rename because it should never be used by the client...
       def available_transitions

data/lib/restfulie/server/marshalling.rb

@@ -5,8 +5,8 @@ module Restfulie
   
     module Marshalling
   
-      def to_json
-        super :methods => :following_states
+      def to_json(options = {})
+        Hash.from_xml(to_xml(options)).to_json
       end
   
       # adds a link for each transition to the current xml writer
@@ -18,17 +18,17 @@ module Restfulie
 
       # adds a link for this transition to the current xml writer
       def add_link(transition, xml, options) 
-
         transition = self.class.existing_transitions(transition.to_sym) unless transition.kind_of? Restfulie::Server::Transition
         transition.add_link_to(xml, self, options)
-
       end
 
+      # marshalls your object to xml.
+      # adds all links if there are any available.
       def to_xml(options = {})
     
         transitions = all_following_transitions
         return super(options) if transitions.empty? || options[:controller].nil?
-    
+
         options[:skip_types] = true
         super options do |xml|
           add_links xml, transitions, options

data/lib/restfulie/server/transition.rb

@@ -4,8 +4,10 @@ module Restfulie
 
     # represents a transition on the server side
     class Transition
-      attr_reader :body, :name, :result
-      def initialize(name, options, result, body)
+      attr_reader :body, :name
+      attr_writer :options
+      attr_accessor :result
+      def initialize(name, options = {}, result = nil, body = nil)
         @name = name
         @options = options
         @result = result
@@ -25,6 +27,18 @@ module Restfulie
         specific_action = action.dup
         specific_action = @body.call(model) if @body
 
+        # if you use the class level DSL, you will need to add a lambda for instance level accessors:
+        #   transition :show, {:action => :show, :foo_id => lambda { |model| model.id }}
+        # but you can replace it for a symbol and defer the model call
+        #   transition :show, {:action => :show, :foo_id => :id}
+        specific_action = specific_action.inject({}) do |actions, pair|
+          if pair.last.is_a?( Symbol ) && model.attributes.include?(pair.last)
+            actions.merge!( pair.first => model.send(pair.last) )
+          else
+            actions.merge!( pair.first => pair.last )
+          end
+        end
+
         rel = specific_action[:rel] || @name
         specific_action[:rel] = nil
 
@@ -37,8 +51,8 @@ module Restfulie
           xml.tag!('atom:link', 'xmlns:atom' => 'http://www.w3.org/2005/Atom', :rel => rel, :href => uri)
         end
       end
-    
+      
     end
   end
 
-end
+end

data/lib/restfulie/unmarshalling.rb

@@ -1,10 +1,33 @@
-module ActiveRecord
-  class Base
+# module Hashi
+#   class CustomHash
+#     # uses_restfulie
+#     def initialize(h)
+#       @hash = h
+#       link = h['link']
+#       add_transitions([link]) if link.kind_of? Hash
+#       add_transitions(link) if link.kind_of? Array
+#     end
+#   end
+# end
+# 
+# module Jeokkarak
+#   module Base
+#     alias_method :old_from_hash_parse, :from_hash_parse
+#     def from_hash_parse(result,h,key,value)
+#       return old_from_hash_parse(result, h, key, value) if key!='link'
+#       link = h[key]
+#       result.add_transitions([link]) if link.kind_of? Hash
+#       result.add_transitions(link) if link.kind_of? Array
+#     end
+#   end
+# end
 
+module Restfulie
+  module Unmarshalling
     # basic code from Matt Pulver
     # found at http://www.xcombinator.com/2008/08/11/activerecord-from_xml-and-from_json-part-2/
     # addapted to support links
-    def self.from_hash( hash )
+    def from_hash( hash )
       h = {}
       h = hash.dup if hash
       links = nil
@@ -29,18 +52,25 @@ module ActiveRecord
       end
       result = self.new h
       if !(links.nil?) && self.include?(Restfulie::Client::Instance)
-        add_transitions(result, links)
+        result.add_transitions(links)
       end
       result
     end
+  end
+end  
+
+module ActiveRecord
+  class Base
+    extend Restfulie::Unmarshalling
+    # acts_as_jeokkarak
 
-    def self.from_json( json )
-      from_hash safe_json_decode( json )
+    def self.from_json(json)
+      from_hash(safe_json_decode(json).values.first)
     end
 
     # The xml has a surrounding class tag (e.g. ship-to),
     # but the hash has no counterpart (e.g. 'ship_to' => {} )
-    def self.from_xml( xml )
+    def self.from_xml(xml)
       hash = Hash.from_xml xml
       head = hash[self.to_s.underscore]
       result = self.from_hash head
@@ -48,13 +78,14 @@ module ActiveRecord
       result._came_from = :xml if self.include?(Restfulie::Client::Instance)
       result
     end
+    
   end
 end
 
-def safe_json_decode( json )
+def safe_json_decode(json)
   return {} if !json
   begin
     ActiveSupport::JSON.decode json
   rescue ; {} end
 end
-# end of code based on Matt Pulver's
+# end of code based on Matt Pulver's

data/lib/restfulie.rb

@@ -1,30 +1,46 @@
 require 'net/http'
 require 'uri'
-require 'restfulie/unmarshalling'
 
-require 'restfulie/client/base'
-require 'restfulie/client/helper'
-require 'restfulie/client/instance'
+require 'restfulie/client'
 
 require 'restfulie/server/base'
 require 'restfulie/server/controller'
 require 'restfulie/server/instance'
 require 'restfulie/server/marshalling'
-require 'restfulie/server/state'
 require 'restfulie/server/transition'
 
-class Class
+module Restfulie
+
+  # Sets this class as a restfulie class.
+  # You may pass a block defining your own transitions.
+  #
+  # The transitions added will be concatenated with any extra transitions provided by your resource through
+  # the use of state and transition definitions.
+  # For every transition its name is the only mandatory field:
+  # options = {}
+  # [:show, options] # will generate a link to your controller's show action
+  #
+  # The options can be used to override restfulie's conventions:
+  # options[:rel] = "refresh" # will create a rel named refresh
+  # options[:action] = "destroy" # will link to the destroy method
+  # options[:controller] = another controller # will use another controller's action
+  #
+  # Any extra options will be passed to the target controller url_for method in order to retrieve
+  # the transition's uri.
   def acts_as_restfulie
-    class << self
-      include Restfulie::Server::Base
-    end
+    extend Restfulie::Server::Base
     include Restfulie::Server::Instance
     include Restfulie::Server::Marshalling
-  end
-  def uses_restfulie
-    class << self
-      include Restfulie::Client::Base
+    
+    self.send :define_method, :following_transitions do
+      transitions = []
+      yield( self, transitions ) if block_given?
+      transitions
     end
-    include Restfulie::Client::Instance
   end
-end
+  
+end
+
+Object.extend Restfulie
+
+require 'restfulie/unmarshalling'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: restfulie
 version: !ruby/object:Gem::Version 
-  version: "0.3"
+  version: 0.4.0
 platform: ruby
 authors: 
 - Guilherme Silveira, Caue Guerra
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-25 00:00:00 -02:00
+date: 2009-12-10 00:00:00 -02:00
 default_executable: 
 dependencies: []
 
@@ -23,13 +23,15 @@ extra_rdoc_files: []
 
 files: 
 - lib/restfulie/client/base.rb
+- lib/restfulie/client/entry_point.rb
 - lib/restfulie/client/helper.rb
 - lib/restfulie/client/instance.rb
+- lib/restfulie/client/state.rb
+- lib/restfulie/client.rb
 - lib/restfulie/server/base.rb
 - lib/restfulie/server/controller.rb
 - lib/restfulie/server/instance.rb
 - lib/restfulie/server/marshalling.rb
-- lib/restfulie/server/state.rb
 - lib/restfulie/server/transition.rb
 - lib/restfulie/unmarshalling.rb
 - lib/restfulie.rb