activeresource 3.2.22.5 → 5.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 480213fdf4278e17032edc702ac6a382fed5e257
-  data.tar.gz: d99d3c4519997be684c92b0d877f2d2126a54ede
+SHA256:
+  metadata.gz: 9e0cde8f42f06f37aa13a7098b9a1e828aac34c90971a62f4c9a1a7fcf529ce7
+  data.tar.gz: 11e7f85a7c565de83cb5248d8ee35783b343b8714e8ed9adcf08462f8aaceeda
 SHA512:
-  metadata.gz: 074be6f00e06d0bb0af86e772c95e287b65da977010f7e11eca2bc72e68e64612e62abbd24980cfa612f0db33703ee0c306bfea1ed21bc323997633085cc86ee
-  data.tar.gz: 71bf71e63a3037ec3e145282b4ef4c1d6fcf7eaf067ef4ceec75cfde85ea389d8bdb66b764e8e0bd7a181ec0e16a6214eb5a41221d11fb946d0d7c470df6e83c
+  metadata.gz: 133f4a82c31d9c925bc1c04a304c63e03982d45aa51b97d7e9ba580a433579802fb811a32009d40ebb7fc84e947fe65c60fd658b2cebb2f2f4c724efc536f528
+  data.tar.gz: 0f0042b3b644fe8584d34403913f2e11363a684fe438d536303871baaed2a98f26319b0e1dcd036364b42597b48e76c5713a627ea4431a2b2ec9263fce98b3a6

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2011 David Heinemeier Hansson
+Copyright (c) 2006-2016 David Heinemeier Hansson
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -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'
+
+Source code can be downloaded on GitHub
+
+* https://github.com/rails/activeresource/tree/master/activeresource
 
 === Configuration and Usage
 
@@ -43,15 +47,54 @@ 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
 records.  But rather than dealing directly with a database record, you're dealing with HTTP resources (which may or may not be database records).
 
+Connection settings (`site`, `headers`, `user`, `password`, `proxy`) and the connections themselves are store in
+thread-local variables to make them thread-safe, so you can also set these dynamically, even in a multi-threaded environment, for instance:
+
+    ActiveResource::Base.site = api_site_for(request)
+
+==== 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.  As mentioned above, headers are thread-safe, so you can set headers dynamically, even in a multi-threaded environment:
+
+    ActiveResource::Base.headers['Authorization'] = current_session_api_token
+    
+Global Authentication to be used across all subclasses of ActiveResource::Base should be handled using the ActiveResource::Connection class.
+
+    ActiveResource::Base.connection.auth_type = :bearer
+    ActiveResource::Base.connection.bearer_token = @bearer_token
+    
+    class Person < ActiveResource::Base
+      self.connection.auth_type = :bearer
+      self.connection.bearer_token = @bearer_token
+    end
+
+ActiveResource supports 2 options for HTTP authentication today.
+
+1. Basic
+
+    ActiveResource::Connection.new("http://my%40email.com:%31%32%33@localhost")
+    # username: my@email.com password: 123
+
+2. Bearer Token
+
+    ActiveResource::Base.connection.auth_type = :bearer
+    ActiveResource::Base.connection.bearer_token = @bearer_token
+
 ==== 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 +108,75 @@ 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>
+  # {"first":"Tyler","last":"Durden"}
   #
   # is submitted as the body on
   #
-  # POST http://api.people.com:3000/people.xml
+  # 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
   #
-  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 +184,22 @@ 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>
+  # {"first":"Tyler"}
   #
   # is submitted as the body on
   #
-  # PUT http://api.people.com:3000/people/1.xml
+  # 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)
   #
-  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,29 +207,79 @@ 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
 
+==== 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/comments.json?post_id=1
+
+
+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
+
+==== Logging
+
+Active Resource instruments the event `request.active_resource` when doing a request
+to the remote service. You can subscribe to it by doing:
+
+   ActiveSupport::Notifications.subscribe('request.active_resource')  do |name, start, finish, id, payload|
+
+The `payload` is a `Hash` with the following keys:
+
+* `method` as a `Symbol`
+* `request_uri` as a `String`
+* `result` as an `Net::HTTPResponse`
+
 == License
 
-Active Resource is released under the MIT 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
+Full API documentation is available at
 
-* http://api.rubyonrails.org
+* http://rubydoc.info/gems/activeresource
 
 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,7 @@
+# frozen_string_literal: true
+
 #--
-# 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,26 +23,24 @@
 # 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'
-require 'active_resource/version'
+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 :Observing
   autoload :Schema
+  autoload :Singleton
   autoload :Validations
+  autoload :Collection
 end
+
+require "active_resource/railtie" if defined?(Rails.application)

data/lib/active_resource/active_job_serializer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActiveResource
+  class ActiveJobSerializer < ActiveJob::Serializers::ObjectSerializer
+    def serialize(resource)
+      super(
+        "class" => resource.class.name,
+        "persisted" => resource.persisted?,
+        "prefix_options" => resource.prefix_options.as_json,
+        "attributes" => resource.attributes.as_json
+      )
+    end
+
+    def deserialize(hash)
+      hash["class"].constantize.new(hash["attributes"]).tap do |resource|
+        resource.persisted      = hash["persisted"]
+        resource.prefix_options = hash["prefix_options"]
+      end
+    end
+
+    private
+      def klass
+        ActiveResource::Base
+      end
+  end
+end

data/lib/active_resource/associations.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+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