activeresource 3.2.22.5 → 4.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 480213fdf4278e17032edc702ac6a382fed5e257
-  data.tar.gz: d99d3c4519997be684c92b0d877f2d2126a54ede
+  metadata.gz: 931c2a3ac5d3c4b76c2165a6d58c44f4aedab23e
+  data.tar.gz: 1a3056f9e297d082f97bdb7350023c571c3dc79d
 SHA512:
-  metadata.gz: 074be6f00e06d0bb0af86e772c95e287b65da977010f7e11eca2bc72e68e64612e62abbd24980cfa612f0db33703ee0c306bfea1ed21bc323997633085cc86ee
-  data.tar.gz: 71bf71e63a3037ec3e145282b4ef4c1d6fcf7eaf067ef4ceec75cfde85ea389d8bdb66b764e8e0bd7a181ec0e16a6214eb5a41221d11fb946d0d7c470df6e83c
+  metadata.gz: 459d6c6a88802add4531118ac6f9191c27196e805be61f35e60787a8fc4a4b380cf456c459a63f6f4c6d9c83f8397dec1fdb9d70f8265c2a8358c978dc919d70
+  data.tar.gz: 05bea224b9115b0ab07cdf8c18846b7327ccabf4265d889ee6caff0437a4349de9f68b9e249c5a8679551001da05322a08b28d5cfcf9dee90c12ae4a6a3fa4d4

data/README.rdoc

@@ -1,4 +1,4 @@
-= Active Resource
+= Active Resource {<img src="https://secure.travis-ci.org/rails/activeresource.png" />}[http://travis-ci.org/rails/activeresource]
 
 Active Resource (ARes) connects business objects and Representational State Transfer (REST)
 web services.  It implements object-relational mapping for REST web services to provide transparent
@@ -17,7 +17,7 @@ for ActiveResource::Base.
 == Overview
 
 Model classes are mapped to remote REST resources by Active Resource much the same way Active Record maps model classes to database
-tables.  When a request is made to a remote resource, a REST XML request is generated, transmitted, and the result
+tables.  When a request is made to a remote resource, a REST JSON request is generated, transmitted, and the result
 received and serialized into a usable Ruby object.
 
 == Download and installation
@@ -26,9 +26,13 @@ The latest version of Active Resource can be installed with RubyGems:
 
   % [sudo] gem install activeresource
 
-Source code can be downloaded as part of the Rails project on GitHub
+Or added to a Gemfile:
 
-* https://github.com/rails/rails/tree/3-2-stable/activeresource
+  gem 'activeresource', :require => 'active_resource'
+
+Source code can be downloaded on GitHub
+
+* https://github.com/rails/activeresource/tree/master/activeresource
 
 === Configuration and Usage
 
@@ -43,7 +47,7 @@ Now the Person class is REST enabled and can invoke REST services very similarly
 life cycle methods that operate against a persistent store.
 
    # Find a person with id = 1
-   ryan = Person.find(1)
+   tyler = Person.find(1)
    Person.exists?(1)  # => true
 
 As you can see, the methods are quite similar to Active Record's methods for dealing with database
@@ -51,7 +55,7 @@ records.  But rather than dealing directly with a database record, you're dealin
 
 ==== Protocol
 
-Active Resource is built on a standard XML format for requesting and submitting resources over HTTP.  It mirrors the RESTful routing
+Active Resource is built on a standard JSON or XML format for requesting and submitting resources over HTTP.  It mirrors the RESTful routing
 built into Action Controller but will also work with any other REST service that properly implements the protocol.
 REST uses HTTP, but unlike "typical" web applications, it makes use of all the verbs available in the HTTP specification:
 
@@ -65,73 +69,72 @@ for more general information on REST web services, see the article here[http://e
 
 ==== Find
 
-Find requests use the GET method and expect the XML form of whatever resource/resources is/are being requested.  So,
-for a request for a single element, the XML of that item is expected in response:
+Find requests use the GET method and expect the JSON form of whatever resource/resources is/are being requested.  So,
+for a request for a single element, the JSON of that item is expected in response:
 
    # Expects a response of
    #
-   # <person><id type="integer">1</id><attribute1>value1</attribute1><attribute2>..</attribute2></person>
+   # {"id":1,"first":"Tyler","last":"Durden"}
    #
-   # for GET http://api.people.com:3000/people/1.xml
+   # for GET http://api.people.com:3000/people/1.json
    #
-   ryan = Person.find(1)
+   tyler = Person.find(1)
 
-The XML document that is received is used to build a new object of type Person, with each
-XML element becoming an attribute on the object.
+The JSON document that is received is used to build a new object of type Person, with each
+JSON element becoming an attribute on the object.
 
-   ryan.is_a? Person  # => true
-   ryan.attribute1  # => 'value1'
+   tyler.is_a? Person  # => true
+   tyler.last  # => 'Durden'
 
 Any complex element (one that contains other elements) becomes its own object:
 
    # With this response:
+   # {"id":1,"first":"Tyler","address":{"street":"Paper St.","state":"CA"}}
    #
-   # <person><id>1</id><attribute1>value1</attribute1><complex><attribute2>value2</attribute2></complex></person>
+   # for GET http://api.people.com:3000/people/1.json
    #
-   # for GET http://api.people.com:3000/people/1.xml
-   #
-   ryan = Person.find(1)
-   ryan.complex  # => <Person::Complex::xxxxx>
-   ryan.complex.attribute2  # => 'value2'
+   tyler = Person.find(1)
+   tyler.address  # => <Person::Address::xxxxx>
+   tyler.address.street  # => 'Paper St.'
 
 Collections can also be requested in a similar fashion
 
    # Expects a response of
    #
-   # <people type="array">
-   #  <person><id type="integer">1</id><first>Ryan</first></person>
-   #  <person><id type="integer">2</id><first>Jim</first></person>
-   # </people>
+   # [ 
+   #   {"id":1,"first":"Tyler","last":"Durden"},
+   #   {"id":2,"first":"Tony","last":"Stark",}
+   # ]
    #
-   # for GET http://api.people.com:3000/people.xml
+   # for GET http://api.people.com:3000/people.json
    #
    people = Person.all
-   people.first  # => <Person::xxx 'first' => 'Ryan' ...>
-   people.last  # => <Person::xxx 'first' => 'Jim' ...>
+   people.first  # => <Person::xxx 'first' => 'Tyler' ...>
+   people.last  # => <Person::xxx 'first' => 'Tony' ...>
 
 ==== Create
 
-Creating a new resource submits the XML form of the resource as the body of the request and expects
+Creating a new resource submits the JSON form of the resource as the body of the request and expects
 a 'Location' header in the response with the RESTful URL location of the newly created resource.  The
 id of the newly created resource is parsed out of the Location response header and automatically set
 as the id of the ARes object.
 
-  # <person><first>Ryan</first></person>
+  # {"person":{"first":"Tyler","last":"Durden"}}
   #
   # is submitted as the body on
   #
-  # POST http://api.people.com:3000/people.xml
+  # POST http://api.people.com:3000/people.json
   #
   # when save is called on a new Person object.  An empty response is
   # is expected with a 'Location' header value:
   #
   # Response (201): Location: http://api.people.com:3000/people/2
   #
-  ryan = Person.new(:first => 'Ryan')
-  ryan.new?  # => true
-  ryan.save  # => true
-  ryan.new?  # => false
-  ryan.id    # => 2
+  tyler = Person.new(:first => 'Tyler')
+  tyler.new?  # => true
+  tyler.save  # => true
+  tyler.new?  # => false
+  tyler.id    # => 2
 
 ==== Update
 
@@ -139,19 +142,19 @@ as the id of the ARes object.
 with the exception that no response headers are needed -- just an empty response when the update on the
 server side was successful.
 
-  # <person><first>Ryan</first></person>
+  # {"person":{"first":"Tyler"}}
   #
   # is submitted as the body on
   #
-  # PUT http://api.people.com:3000/people/1.xml
+  # PUT http://api.people.com:3000/people/1.json
   #
   # when save is called on an existing Person object.  An empty response is
   # is expected with code (204)
   #
-  ryan = Person.find(1)
-  ryan.first # => 'Ryan'
-  ryan.first = 'Rizzle'
-  ryan.save  # => true
+  tyler = Person.find(1)
+  tyler.first # => 'Tyler'
+  tyler.first = 'Tyson'
+  tyler.save  # => true
 
 ==== Delete
 
@@ -159,20 +162,22 @@ Destruction of a resource can be invoked as a class and instance method of the r
 
   # A request is made to
   #
-  # DELETE http://api.people.com:3000/people/1.xml
+  # DELETE http://api.people.com:3000/people/1.json
   #
   # for both of these forms.  An empty response with
   # is expected with response code (200)
   #
-  ryan = Person.find(1)
-  ryan.destroy  # => true
-  ryan.exists?  # => false
+  tyler = Person.find(1)
+  tyler.destroy  # => true
+  tyler.exists?  # => false
   Person.delete(2)  # => true
   Person.exists?(2) # => false
 
 == License
 
-Active Resource is released under the MIT license.
+Active Resource is released under the MIT license:
+
+* http://www.opensource.org/licenses/MIT
 
 == Support
 
@@ -182,6 +187,6 @@ API documentation is at
 
 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
 
-* https://github.com/rails/rails/issues
+* https://github.com/rails/activeresource/issues
 
 You can find more usage information in the ActiveResource::Base documentation.

data/lib/active_resource.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2011 David Heinemeier Hansson
+# Copyright (c) 2006-2012 David Heinemeier Hansson
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -21,12 +21,6 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-activesupport_path = File.expand_path('../../../activesupport/lib', __FILE__)
-$:.unshift(activesupport_path) if File.directory?(activesupport_path) && !$:.include?(activesupport_path)
-
-activemodel_path = File.expand_path('../../../activemodel/lib', __FILE__)
-$:.unshift(activemodel_path) if File.directory?(activemodel_path) && !$:.include?(activemodel_path)
-
 require 'active_support'
 require 'active_model'
 require 'active_resource/exceptions'
@@ -36,11 +30,14 @@ module ActiveResource
   extend ActiveSupport::Autoload
 
   autoload :Base
+  autoload :Callbacks
   autoload :Connection
   autoload :CustomMethods
   autoload :Formats
   autoload :HttpMock
   autoload :Observing
   autoload :Schema
+  autoload :Singleton
   autoload :Validations
+  autoload :Collection
 end

data/lib/active_resource/associations.rb

@@ -0,0 +1,168 @@
+module ActiveResource::Associations
+
+  module Builder
+    autoload :Association, 'active_resource/associations/builder/association'
+    autoload :HasMany,     'active_resource/associations/builder/has_many'
+    autoload :HasOne,      'active_resource/associations/builder/has_one'
+    autoload :BelongsTo,   'active_resource/associations/builder/belongs_to'
+  end
+
+
+
+  # Specifies a one-to-many association.
+  #
+  # === Options
+  # [:class_name]
+  #   Specify the class name of the association. This class name would
+  #   be used for resolving the association class. 
+  #
+  # ==== Example for [:class_name] - option
+  # GET /posts/123.json delivers following response body:
+  #   {
+  #     title: "ActiveResource now has associations",
+  #     body: "Lorem Ipsum"
+  #     comments: [
+  #       {
+  #         content: "..."
+  #       },
+  #       {
+  #         content: "..."
+  #       }
+  #     ]
+  #   }
+  # ====
+  #
+  # <tt>has_many :comments, :class_name => 'myblog/comment'</tt>
+  # Would resolve those comments into the <tt>Myblog::Comment</tt> class.
+  #
+  # If the response body does not contain an attribute matching the association name
+  # a request sent to the index action under the current resource.
+  # For the example above, if the comments are not present the requested path would be:
+  # GET /posts/123/comments.xml
+  def has_many(name, options = {})
+    Builder::HasMany.build(self, name, options)
+  end
+
+  # Specifies a one-to-one association.
+  #
+  # === Options
+  # [:class_name]
+  #   Specify the class name of the association. This class name would
+  #   be used for resolving the association class. 
+  #
+  # ==== Example for [:class_name] - option
+  # GET /posts/1.json delivers following response body:
+  #   {
+  #     title: "ActiveResource now has associations",
+  #     body: "Lorem Ipsum",
+  #     author: {
+  #       name: "Gabby Blogger",
+  #     }
+  #   }
+  # ====
+  #
+  # <tt>has_one :author, :class_name => 'myblog/author'</tt>
+  # Would resolve this author into the <tt>Myblog::Author</tt> class.
+  #
+  # If the response body does not contain an attribute matching the association name
+  # a request is sent to a singelton path under the current resource.
+  # For example, if a Product class <tt>has_one :inventory</tt> calling <tt>Product#inventory</tt>
+  # will generate a request on /product/:product_id/inventory.json.
+  #
+  def has_one(name, options = {})
+    Builder::HasOne.build(self, name, options)
+  end
+
+  # Specifies a one-to-one association with another class. This class should only be used
+  # if this class contains the foreign key. 
+  #
+  # Methods will be added for retrieval and query for a single associated object, for which
+  # this object holds an id:
+  #
+  # [association(force_reload = false)]
+  #   Returns the associated object. +nil+ is returned if the foreign key is +nil+.
+  #   Throws a ActiveResource::ResourceNotFound exception if the foreign key is not +nil+
+  #   and the resource is not found.
+  # 
+  # (+association+ is replaced with the symbol passed as the first argument, so
+  # <tt>belongs_to :post</tt> would add among others <tt>post.nil?</tt>.
+  #
+  # === Example
+  #
+  # A Comment class declaress <tt>belongs_to :post</tt>, which will add:
+  # * <tt>Comment#post</tt> (similar to <tt>Post.find(post_id)</tt>)
+  # The declaration can also include an options hash to specialize the behavior of the association.
+  #
+  # === Options
+  # [:class_name]
+  #   Specify the class name for the association. Use it only if that name canÄt be inferred from association name.
+  #   So <tt>belongs_to :post</tt> will by default be linked to the Post class, but if the real class name is Article,
+  #   you'll have to specify it with whis option.
+  # [:foreign_key]
+  #   Specify the foreign key used for the association. By default this is guessed to be the name
+  #   of the association with an "_id" suffix. So a class that defines a <tt>belongs_to :post</tt>
+  #   association will use "post_id" as the default <tt>:foreign_key</tt>. Similarly,
+  #   <tt>belongs_to :article, :class_name => "Post"</tt> will use a foreign key
+  #   of "article_id".
+  #
+  # Option examples:
+  # <tt>belongs_to :customer, :class_name => 'User'</tt>
+  # Creates a belongs_to association called customer which is represented through the <tt>User</tt> class.
+  #
+  # <tt>belongs_to :customer, :foreign_key => 'user_id'</tt>
+  # Creates a belongs_to association called customer which would be resolved by the foreign_key <tt>user_id</tt> instead of <tt>customer_id</tt>
+  #
+  def belongs_to(name, options={})
+    Builder::BelongsTo.build(self, name, options)
+  end
+
+  # Defines the belongs_to association finder method
+  def defines_belongs_to_finder_method(method_name, association_model, finder_key)
+    ivar_name = :"@#{method_name}"
+
+    if method_defined?(method_name)
+      instance_variable_set(ivar_name, nil)
+      remove_method(method_name)
+    end
+
+    define_method(method_name) do
+      if instance_variable_defined?(ivar_name)
+        instance_variable_get(ivar_name)
+      elsif attributes.include?(method_name)
+        attributes[method_name]
+      else
+        instance_variable_set(ivar_name, association_model.find(send(finder_key)))
+      end
+    end
+  end
+
+  def defines_has_many_finder_method(method_name, association_model)
+    ivar_name = :"@#{method_name}"
+
+    define_method(method_name) do
+      if instance_variable_defined?(ivar_name)
+        instance_variable_get(ivar_name)
+      elsif attributes.include?(method_name)
+        attributes[method_name]
+      else
+        instance_variable_set(ivar_name, association_model.find(:all, :params => {:"#{self.class.element_name}_id" => self.id}))
+      end
+    end
+  end
+  
+  # Defines the has_one association
+  def defines_has_one_finder_method(method_name, association_model)
+    ivar_name = :"@#{method_name}"
+
+    define_method(method_name) do
+      if instance_variable_defined?(ivar_name)
+        instance_variable_get(ivar_name)
+      elsif attributes.include?(method_name)
+        attributes[method_name]
+      else
+        instance_variable_set(ivar_name, association_model.find(:params => {:"#{self.class.element_name}_id" => self.id}))
+      end
+    end
+  end
+
+end

data/lib/active_resource/associations/builder/association.rb

@@ -0,0 +1,32 @@
+module ActiveResource::Associations::Builder
+  class Association #:nodoc:
+
+    # providing a Class-Variable, which will have a different store of subclasses
+    class_attribute :valid_options
+    self.valid_options = [:class_name]
+
+    # would identify subclasses of association
+    class_attribute :macro
+
+    attr_reader :model, :name, :options, :klass
+
+    def self.build(model, name, options)
+      new(model, name, options).build
+    end
+
+    def initialize(model, name, options)
+      @model, @name, @options = model, name, options
+    end
+
+    def build
+      validate_options
+      model.create_reflection(self.class.macro, name, options)
+    end
+
+    private
+
+    def validate_options
+      options.assert_valid_keys(self.class.valid_options)
+    end
+  end
+end