activeresource-five 5.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a090060069d258cd94729d4b260529d9e16c8943
+  data.tar.gz: 210bacf920a99fd19e34092b4c27a60e4a9798bf
+SHA512:
+  metadata.gz: 77f3941f609d8f612b17c0ee76e182475c8610bd9ef9d0fcddb96338409b3a26fbe08fc6a39270dea394ff9f9af4e833110de2016f7997d53ff7227835e1a6c8
+  data.tar.gz: 1c20287839e4b664aa6b73ac5a4e4fbd46ac2459bf4d991114a83c279f0284ea4e17e31949692d6708fa3daf2a8c48d1afefd3722d8c336bf94b95dd853912e0

data/README.rdoc

@@ -0,0 +1,249 @@
+= Active Resource Five
+
+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
+proxying capabilities between a client (ActiveResource) and a RESTful service (which is provided by Simply RESTful routing
+in ActionController::Resources).
+
+There is currently no version 5 release in Ruby gems, so as an interim solution, this release brings 5 functionality to RubyGems so that it can be included in a dependency of other gems without causing dependency conflicts with ActiveResource/ActiveModel 5 etc.
+
+== Philosophy
+
+Active Resource attempts to provide a coherent wrapper object-relational mapping for REST
+web services. It follows the same philosophy as Active Record, in that one of its prime aims
+is to reduce the amount of code needed to map to these resources.  This is made possible
+by relying on a number of code- and protocol-based conventions that make it easy for Active Resource
+to infer complex relations and structures.  These conventions are outlined in detail in the documentation
+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 JSON request is generated, transmitted, and the result
+received and serialized into a usable Ruby object.
+
+== Download and installation
+
+The latest version of Active Resource can be installed with RubyGems:
+
+  % [sudo] gem install activeresource-five
+
+Or added to a Gemfile:
+
+  gem 'activeresource-five'
+
+For compatibility with Rails 5, use:
+
+  gem 'activeresource-five', github: 'rails/activeresource', branch: 'master'
+
+Source code can be downloaded on GitHub
+
+* https://github.com/rails/activeresource/tree/master/activeresource
+
+=== Configuration and Usage
+
+Putting Active Resource to use is very similar to Active Record.  It's as simple as creating a model class
+that inherits from ActiveResource::Base and providing a <tt>site</tt> class variable to it:
+
+   class Person < ActiveResource::Base
+     self.site = "http://api.people.com:3000"
+   end
+
+Now the Person class is REST enabled and can invoke REST services very similarly to how Active Record invokes
+life cycle methods that operate against a persistent store.
+
+   # Find a person with id = 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
+records.  But rather than dealing directly with a database record, you're dealing with HTTP resources (which may or may not be database records).
+
+==== Authentication
+
+Active Resource supports the token based authentication provided by Rails through the <tt>ActionController::HttpAuthentication::Token</tt> class using custom headers.
+
+   class Person < ActiveResource::Base
+     self.headers['Authorization'] = 'Token token="abcd"'
+   end
+
+You can also set any specific HTTP header using the same way.
+
+==== Protocol
+
+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:
+
+* GET requests are used for finding and retrieving resources.
+* POST requests are used to create new resources.
+* PUT requests are used to update existing resources.
+* DELETE requests are used to delete resources.
+
+For more information on how this protocol works with Active Resource, see the ActiveResource::Base documentation;
+for more general information on REST web services, see the article here[http://en.wikipedia.org/wiki/Representational_State_Transfer].
+
+==== Find
+
+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
+   #
+   # {"id":1,"first":"Tyler","last":"Durden"}
+   #
+   # for GET http://api.people.com:3000/people/1.json
+   #
+   tyler = Person.find(1)
+
+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.
+
+   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"}}
+   #
+   # for GET http://api.people.com:3000/people/1.json
+   #
+   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
+   #
+   # [
+   #   {"id":1,"first":"Tyler","last":"Durden"},
+   #   {"id":2,"first":"Tony","last":"Stark",}
+   # ]
+   #
+   # for GET http://api.people.com:3000/people.json
+   #
+   people = Person.all
+   people.first  # => <Person::xxx 'first' => 'Tyler' ...>
+   people.last  # => <Person::xxx 'first' => 'Tony' ...>
+
+==== Create
+
+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.
+
+  # {"first":"Tyler","last":"Durden"}
+  #
+  # is submitted as the body on
+  #
+  # if include_root_in_json is not set or set to false => {"first":"Tyler"}
+  # if include_root_in_json is set to true => {"person":{"first":"Tyler"}}
+  #
+  # 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
+  #
+  tyler = Person.new(:first => 'Tyler')
+  tyler.new?  # => true
+  tyler.save  # => true
+  tyler.new?  # => false
+  tyler.id    # => 2
+
+==== Update
+
+'save' is also used to update an existing resource and follows the same protocol as creating a resource
+with the exception that no response headers are needed -- just an empty response when the update on the
+server side was successful.
+
+  # {"first":"Tyler"}
+  #
+  # is submitted as the body on
+  #
+  # if include_root_in_json is not set or set to false => {"first":"Tyler"}
+  # if include_root_in_json is set to true => {"person":{"first":"Tyler"}}
+  #
+  # 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)
+  #
+  tyler = Person.find(1)
+  tyler.first # => 'Tyler'
+  tyler.first = 'Tyson'
+  tyler.save  # => true
+
+==== Delete
+
+Destruction of a resource can be invoked as a class and instance method of the resource.
+
+  # A request is made to
+  #
+  # DELETE http://api.people.com:3000/people/1.json
+  #
+  # for both of these forms.  An empty response with
+  # is expected with response code (200)
+  #
+  tyler = Person.find(1)
+  tyler.destroy  # => true
+  tyler.exists?  # => false
+  Person.delete(2)  # => true
+  Person.exists?(2) # => false
+
+==== Associations
+
+Relationships between resources can be declared using the standard association syntax
+that should be familiar to anyone who uses activerecord. For example, using the
+class definition below:
+
+  class Post < ActiveResource::Base
+    self.site = "http://blog.io"
+    has_many :comments
+  end
+
+  post = Post.find(1)      # issues GET http://blog.io/posts/1.json
+  comments = post.comments # issues GET http://blog.io/posts/1/comments.json
+
+
+If you control the server, you may wish to include nested resources thus avoiding a
+second network request. Given the resource above, if the response includes comments
+in the response, they will be automatically loaded into the activeresource object.
+The server-side model can be adjusted as follows to include comments in the response.
+
+  class Post < ActiveRecord::Base
+    has_many :comments
+
+    def as_json(options)
+      super.merge(:include=>[:comments])
+    end
+  end
+
+== License
+
+Active Resource is released under the MIT license:
+
+* http://www.opensource.org/licenses/MIT
+
+== Contributing to Active Resource
+
+Active Resource is work of many contributors. You're encouraged to submit pull requests, propose
+features and discuss issues.
+
+See {CONTRIBUTING}[https://github.com/rails/activeresource/blob/master/CONTRIBUTING.md].
+
+== Support
+
+API documentation is at
+
+* http://rubydoc.info/gems/activeresource/4.0.0/frames
+
+Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
+
+* https://github.com/rails/activeresource/issues
+
+You can find more usage information in the ActiveResource::Base documentation.

data/lib/active_resource.rb

@@ -0,0 +1,44 @@
+#--
+# 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
+# "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.
+#++
+
+require 'active_support'
+require 'active_model'
+require 'active_resource/exceptions'
+require 'active_resource/version'
+
+module ActiveResource
+  extend ActiveSupport::Autoload
+
+  autoload :Base
+  autoload :Callbacks
+  autoload :Connection
+  autoload :CustomMethods
+  autoload :Formats
+  autoload :HttpMock
+  autoload :Schema
+  autoload :Singleton
+  autoload :Validations
+  autoload :Collection
+end
+
+require 'active_resource/railtie' if defined?(Rails.application)

data/lib/active_resource/associations.rb

@@ -0,0 +1,175 @@
+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 singleton 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 /products/: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 declares <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 this 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(reflection)
+    method_name = reflection.name
+    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]
+      elsif association_id = send(reflection.foreign_key)
+        instance_variable_set(ivar_name, reflection.klass.find(association_id))
+      end
+    end
+  end
+
+  def defines_has_many_finder_method(reflection)
+    method_name = reflection.name
+    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]
+      elsif !new_record?
+        instance_variable_set(ivar_name, reflection.klass.find(:all, :params => {:"#{self.class.element_name}_id" => self.id}))
+      else
+        instance_variable_set(ivar_name, self.class.collection_parser.new)
+      end
+    end
+  end
+
+  # Defines the has_one association
+  def defines_has_one_finder_method(reflection)
+    method_name = reflection.name
+    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]
+      elsif reflection.klass.respond_to?(:singleton_name)
+        instance_variable_set(ivar_name, reflection.klass.find(:params => {:"#{self.class.element_name}_id" => self.id}))
+      else
+        instance_variable_set(ivar_name, reflection.klass.find(:one, :from => "/#{self.class.collection_name}/#{self.id}/#{method_name}#{self.class.format_extension}"))
+      end
+    end
+  end
+
+end