diff options
Diffstat (limited to 'activeresource/lib/active_resource/base.rb')
-rw-r--r-- | activeresource/lib/active_resource/base.rb | 162 |
1 files changed, 85 insertions, 77 deletions
diff --git a/activeresource/lib/active_resource/base.rb b/activeresource/lib/active_resource/base.rb index 347dbb82aa..4af30ea13f 100644 --- a/activeresource/lib/active_resource/base.rb +++ b/activeresource/lib/active_resource/base.rb @@ -13,43 +13,43 @@ module ActiveResource # to Ruby objects, Active Resource only needs a class name that corresponds to the resource name (e.g., the class # Person maps to the resources people, very similarly to Active Record) and a +site+ value, which holds the # URI of the resources. - # + # # class Person < ActiveResource::Base # self.site = "http://api.people.com:3000/" # end - # + # # Now the Person class is mapped to RESTful resources located at <tt>http://api.people.com:3000/people/</tt>, and - # you can now use Active Resource's lifecycles methods to manipulate resources. In the case where you already have + # you can now use Active Resource's lifecycles methods to manipulate resources. In the case where you already have # an existing model with the same name as the desired RESTful resource you can set the +element_name+ value. # # class PersonResource < ActiveResource::Base # self.site = "http://api.people.com:3000/" # self.element_name = "person" # end - # - # + # + # # == Lifecycle methods # # Active Resource exposes methods for creating, finding, updating, and deleting resources # from REST web services. - # + # # ryan = Person.new(:first => 'Ryan', :last => 'Daigle') # ryan.save # => true # ryan.id # => 2 # Person.exists?(ryan.id) # => true # ryan.exists? # => true - # + # # ryan = Person.find(1) # # Resource holding our newly created Person object - # + # # ryan.first = 'Rizzle' # ryan.save # => true - # + # # ryan.destroy # => true # # As you can see, these are very similar to Active Record's lifecycle methods for database records. # You can read more about each of these methods in their respective documentation. - # + # # === Custom REST methods # # Since simple CRUD/lifecycle methods can't accomplish every task, Active Resource also supports @@ -71,14 +71,14 @@ module ActiveResource # # # DELETE to 'fire' a person, i.e. DELETE /people/1/fire.xml. # Person.find(1).delete(:fire) - # + # # For more information on using custom REST methods, see the # ActiveResource::CustomMethods documentation. # # == Validations # # You can validate resources client side by overriding validation methods in the base class. - # + # # class Person < ActiveResource::Base # self.site = "http://api.people.com:3000/" # protected @@ -86,19 +86,19 @@ module ActiveResource # errors.add("last", "has invalid characters") unless last =~ /[a-zA-Z]*/ # end # end - # + # # See the ActiveResource::Validations documentation for more information. # # == Authentication - # + # # Many REST APIs will require authentication, usually in the form of basic # HTTP authentication. Authentication can be specified by: # * putting the credentials in the URL for the +site+ variable. - # + # # class Person < ActiveResource::Base # self.site = "http://ryan:password@api.people.com:3000/" # end - # + # # * defining +user+ and/or +password+ variables # # class Person < ActiveResource::Base @@ -107,29 +107,29 @@ module ActiveResource # self.password = "password" # end # - # For obvious security reasons, it is probably best if such services are available + # For obvious security reasons, it is probably best if such services are available # over HTTPS. - # - # Note: Some values cannot be provided in the URL passed to site. e.g. email addresses - # as usernames. In those situations you should use the seperate user and password option. + # + # Note: Some values cannot be provided in the URL passed to site. e.g. email addresses + # as usernames. In those situations you should use the separate user and password option. # == Errors & Validation # # Error handling and validation is handled in much the same manner as you're used to seeing in # Active Record. Both the response code in the HTTP response and the body of the response are used to # indicate that an error occurred. - # + # # === Resource errors - # + # # When a GET is requested for a resource that does not exist, the HTTP <tt>404</tt> (Resource Not Found) # response code will be returned from the server which will raise an ActiveResource::ResourceNotFound # exception. - # + # # # GET http://api.people.com:3000/people/999.xml # ryan = Person.find(999) # 404, raises ActiveResource::ResourceNotFound - # + # # <tt>404</tt> is just one of the HTTP error response codes that Active Resource will handle with its own exception. The # following HTTP response codes will also result in these exceptions: - # + # # * 200..399 - Valid response, no exception # * 404 - ActiveResource::ResourceNotFound # * 409 - ActiveResource::ResourceConflict @@ -149,17 +149,17 @@ module ActiveResource # end # # === Validation errors - # + # # Active Resource supports validations on resources and will return errors if any these validations fail - # (e.g., "First name can not be blank" and so on). These types of errors are denoted in the response by + # (e.g., "First name can not be blank" and so on). These types of errors are denoted in the response by # a response code of <tt>422</tt> and an XML representation of the validation errors. The save operation will # then fail (with a <tt>false</tt> return value) and the validation errors can be accessed on the resource in question. - # + # # ryan = Person.find(1) # ryan.first # => '' # ryan.save # => false # - # # When + # # When # # PUT http://api.people.com:3000/people/1.xml # # is requested with invalid values, the response is: # # @@ -169,7 +169,7 @@ module ActiveResource # # ryan.errors.invalid?(:first) # => true # ryan.errors.full_messages # => ['First cannot be empty'] - # + # # Learn more about Active Resource's validation features in the ActiveResource::Validations documentation. # # === Timeouts @@ -200,7 +200,7 @@ module ActiveResource cattr_accessor :logger class << self - # Gets the URI of the REST resources to map for this class. The site variable is required + # Gets the URI of the REST resources to map for this class. The site variable is required for # Active Resource's mapping to work. def site # Not using superclass_delegating_reader because don't want subclasses to modify superclass instance @@ -226,7 +226,7 @@ module ActiveResource end # Sets the URI of the REST resources to map for this class to the value in the +site+ argument. - # The site variable is required Active Resource's mapping to work. + # The site variable is required for Active Resource's mapping to work. def site=(site) @connection = nil if site.nil? @@ -280,7 +280,7 @@ module ActiveResource # # Default format is <tt>:xml</tt>. def format=(mime_type_reference_or_format) - format = mime_type_reference_or_format.is_a?(Symbol) ? + format = mime_type_reference_or_format.is_a?(Symbol) ? ActiveResource::Formats[mime_type_reference_or_format] : mime_type_reference_or_format write_inheritable_attribute("format", format) @@ -288,7 +288,7 @@ module ActiveResource end # Returns the current format, default is ActiveResource::Formats::XmlFormat. - def format # :nodoc: + def format read_inheritable_attribute("format") || ActiveResource::Formats[:xml] end @@ -298,7 +298,7 @@ module ActiveResource @timeout = timeout end - # Gets tthe number of seconds after which requests to the REST API should time out. + # Gets the number of seconds after which requests to the REST API should time out. def timeout if defined?(@timeout) @timeout @@ -332,7 +332,7 @@ module ActiveResource attr_accessor_with_default(:collection_name) { element_name.pluralize } #:nodoc: attr_accessor_with_default(:primary_key, 'id') #:nodoc: - + # Gets the prefix for a resource's nested URL (e.g., <tt>prefix/collectionname/1.xml</tt>) # This method is regenerated at runtime based on what the prefix is set to. def prefix(options={}) @@ -356,6 +356,9 @@ module ActiveResource # Replace :placeholders with '#{embedded options[:lookups]}' prefix_call = value.gsub(/:\w+/) { |key| "\#{options[#{key}]}" } + # Clear prefix parameters in case they have been cached + @prefix_parameters = nil + # Redefine the new methods. code = <<-end_code def prefix_source() "#{value}" end @@ -381,21 +384,21 @@ module ActiveResource # +query_options+ - A hash to add items to the query string for the request. # # ==== Examples - # Post.element_path(1) + # Post.element_path(1) # # => /posts/1.xml # - # Comment.element_path(1, :post_id => 5) + # Comment.element_path(1, :post_id => 5) # # => /posts/5/comments/1.xml # - # Comment.element_path(1, :post_id => 5, :active => 1) + # Comment.element_path(1, :post_id => 5, :active => 1) # # => /posts/5/comments/1.xml?active=1 # - # Comment.element_path(1, {:post_id => 5}, {:active => 1}) + # Comment.element_path(1, {:post_id => 5}, {:active => 1}) # # => /posts/5/comments/1.xml?active=1 # def element_path(id, prefix_options = {}, query_options = nil) prefix_options, query_options = split_options(prefix_options) if query_options.nil? - "#{prefix(prefix_options)}#{collection_name}/#{id}.#{format.extension}#{query_string(query_options)}" + "#{prefix(prefix_options)}#{collection_name}/#{id}.#{format.extension}#{query_string(query_options)}" end # Gets the collection path for the REST resources. If the +query_options+ parameter is omitted, Rails @@ -410,13 +413,13 @@ module ActiveResource # Post.collection_path # # => /posts.xml # - # Comment.collection_path(:post_id => 5) + # Comment.collection_path(:post_id => 5) # # => /posts/5/comments.xml # - # Comment.collection_path(:post_id => 5, :active => 1) + # Comment.collection_path(:post_id => 5, :active => 1) # # => /posts/5/comments.xml?active=1 # - # Comment.collection_path({:post_id => 5}, {:active => 1}) + # Comment.collection_path({:post_id => 5}, {:active => 1}) # # => /posts/5/comments.xml?active=1 # def collection_path(prefix_options = {}, query_options = nil) @@ -426,16 +429,16 @@ module ActiveResource alias_method :set_primary_key, :primary_key= #:nodoc: - # Create a new resource instance and request to the remote service + # Creates a new resource instance and makes a request to the remote service # that it be saved, making it equivalent to the following simultaneous calls: # # ryan = Person.new(:first => 'ryan') # ryan.save # - # The newly created resource is returned. If a failure has occurred an - # exception will be raised (see save). If the resource is invalid and - # has not been saved then valid? will return <tt>false</tt>, - # while new? will still return <tt>true</tt>. + # Returns the newly created resource. If a failure has occurred an + # exception will be raised (see <tt>save</tt>). If the resource is invalid and + # has not been saved then <tt>valid?</tt> will return <tt>false</tt>, + # while <tt>new?</tt> will still return <tt>true</tt>. # # ==== Examples # Person.create(:name => 'Jeremy', :email => 'myname@nospam.com', :enabled => true) @@ -451,50 +454,54 @@ module ActiveResource # that_guy.valid? # => false # that_guy.new? # => true def create(attributes = {}) - returning(self.new(attributes)) { |res| res.save } + returning(self.new(attributes)) { |res| res.save } end # Core method for finding resources. Used similarly to Active Record's +find+ method. # # ==== Arguments - # The first argument is considered to be the scope of the query. That is, how many + # The first argument is considered to be the scope of the query. That is, how many # resources are returned from the request. It can be one of the following. # # * <tt>:one</tt> - Returns a single resource. # * <tt>:first</tt> - Returns the first resource found. + # * <tt>:last</tt> - Returns the last resource found. # * <tt>:all</tt> - Returns every resource that matches the request. - # + # # ==== Options # # * <tt>:from</tt> - Sets the path or custom method that resources will be fetched from. # * <tt>:params</tt> - Sets query and prefix (nested URL) parameters. # # ==== Examples - # Person.find(1) + # Person.find(1) # # => GET /people/1.xml # - # Person.find(:all) + # Person.find(:all) # # => GET /people.xml # - # Person.find(:all, :params => { :title => "CEO" }) + # Person.find(:all, :params => { :title => "CEO" }) # # => GET /people.xml?title=CEO # - # Person.find(:first, :from => :managers) + # Person.find(:first, :from => :managers) # # => GET /people/managers.xml # - # Person.find(:all, :from => "/companies/1/people.xml") + # Person.find(:last, :from => :managers) + # # => GET /people/managers.xml + # + # Person.find(:all, :from => "/companies/1/people.xml") # # => GET /companies/1/people.xml # - # Person.find(:one, :from => :leader) + # Person.find(:one, :from => :leader) # # => GET /people/leader.xml # # Person.find(:all, :from => :developers, :params => { :language => 'ruby' }) # # => GET /people/developers.xml?language=ruby # - # Person.find(:one, :from => "/companies/1/manager.xml") + # Person.find(:one, :from => "/companies/1/manager.xml") # # => GET /companies/1/manager.xml # - # StreetAddress.find(1, :params => { :person_id => 1 }) + # StreetAddress.find(1, :params => { :person_id => 1 }) # # => GET /people/1/street_addresses/1.xml def find(*arguments) scope = arguments.slice!(0) @@ -503,6 +510,7 @@ module ActiveResource case scope when :all then find_every(options) when :first then find_every(options).first + when :last then find_every(options).last when :one then find_one(options) else find_single(scope, options) end @@ -560,7 +568,7 @@ module ActiveResource instantiate_collection( (connection.get(path, headers) || []), prefix_options ) end end - + # Find a single resource from a one-off URL def find_one(options) case from = options[:from] @@ -578,7 +586,7 @@ module ActiveResource path = element_path(scope, prefix_options, query_options) instantiate_record(connection.get(path, headers), prefix_options) end - + def instantiate_collection(collection, prefix_options = {}) collection.collect! { |record| instantiate_record(record, prefix_options) } end @@ -602,10 +610,10 @@ module ActiveResource # Builds the query string for the request. def query_string(options) - "?#{options.to_query}" unless options.nil? || options.empty? + "?#{options.to_query}" unless options.nil? || options.empty? end - # split an option hash into two hashes, one containing the prefix options, + # split an option hash into two hashes, one containing the prefix options, # and the other containing the leftovers. def split_options(options = {}) prefix_options, query_options = {}, {} @@ -654,7 +662,7 @@ module ActiveResource # ryan = Person.find(1) # ryan.address = StreetAddress.find(1, :person_id => ryan.id) # ryan.hash = {:not => "an ARes instance"} - # + # # not_ryan = ryan.clone # not_ryan.new? # => true # not_ryan.address # => NoMethodError @@ -706,7 +714,7 @@ module ActiveResource id && id.to_s end - # Test for equality. Resource are equal if and only if +other+ is the same object or + # Test for equality. Resource are equal if and only if +other+ is the same object or # is an instance of the same class, is not <tt>new?</tt>, and has the same +id+. # # ==== Examples @@ -742,7 +750,7 @@ module ActiveResource def hash id.hash end - + # Duplicate the current resource without saving it. # # ==== Examples @@ -762,7 +770,7 @@ module ActiveResource end end - # A method to save (+POST+) or update (+PUT+) a resource. It delegates to +create+ if a new object, + # A method to save (+POST+) or update (+PUT+) a resource. It delegates to +create+ if a new object, # +update+ if it is existing. If the response to the save includes a body, it will be assumed that this body # is XML for the final object as it looked after the save (which would include attributes like +created_at+ # that weren't part of the original submit). @@ -786,7 +794,7 @@ module ActiveResource # my_person = Person.find(my_id) # my_person.destroy # Person.find(my_id) # 404 (Resource Not Found) - # + # # new_person = Person.create(:name => 'James') # new_id = new_person.id # => 7 # new_person.destroy @@ -812,7 +820,7 @@ module ActiveResource # Person.delete(guys_id) # that_guy.exists? # => false def exists? - !new? && self.class.exists?(to_param, :params => prefix_options) + !new? && self.class.exists?(to_param, :params => prefix_options) end # A method to convert the the resource to an XML string. @@ -825,7 +833,7 @@ module ActiveResource # * <tt>:indent</tt> - Set the indent level for the XML output (default is +2+). # * <tt>:dasherize</tt> - Boolean option to determine whether or not element names should # replace underscores with dashes (default is <tt>false</tt>). - # * <tt>:skip_instruct</tt> - Toggle skipping the +instruct!+ call on the XML builder + # * <tt>:skip_instruct</tt> - Toggle skipping the +instruct!+ call on the XML builder # that generates the XML declaration (default is <tt>false</tt>). # # ==== Examples @@ -849,7 +857,7 @@ module ActiveResource # ==== Examples # my_branch = Branch.find(:first) # my_branch.name # => "Wislon Raod" - # + # # # Another client fixes the typo... # # my_branch.name # => "Wislon Raod" @@ -897,7 +905,7 @@ module ActiveResource end self end - + # For checking <tt>respond_to?</tt> without searching the attributes (which is faster). alias_method :respond_to_without_attributes?, :respond_to? @@ -909,7 +917,7 @@ module ActiveResource if attributes.nil? return super elsif attributes.has_key?(method_name) - return true + return true elsif ['?','='].include?(method_name.last) && attributes.has_key?(method_name.first(-1)) return true end @@ -917,7 +925,7 @@ module ActiveResource # would return true for generated readers, even if the attribute wasn't present super end - + protected def connection(refresh = false) @@ -938,7 +946,7 @@ module ActiveResource load_attributes_from_response(response) end end - + def load_attributes_from_response(response) if response['Content-Length'] != "0" && response.body.strip.size > 0 load(self.class.format.decode(response.body)) @@ -963,7 +971,7 @@ module ActiveResource def find_or_create_resource_for_collection(name) find_or_create_resource_for(name.to_s.singularize) end - + # Tries to find a resource in a non empty list of nested modules # Raises a NameError if it was not found in any of the given nested modules def find_resource_in_modules(resource_name, module_names) |