diff options
Diffstat (limited to 'activeresource')
| -rw-r--r-- | activeresource/README | 14 | ||||
| -rw-r--r-- | activeresource/lib/active_resource/base.rb | 20 | ||||
| -rw-r--r-- | activeresource/lib/active_resource/connection.rb | 22 | ||||
| -rw-r--r-- | activeresource/lib/active_resource/validations.rb | 17 |
4 files changed, 37 insertions, 36 deletions
diff --git a/activeresource/README b/activeresource/README index 924017a659..127ac5b4a9 100644 --- a/activeresource/README +++ b/activeresource/README @@ -1,7 +1,7 @@ = Active Resource Active Resource (ARes) connects business objects and Representational State Transfer (REST) -web services. It implements object-relational mapping for REST webservices to provide transparent +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). @@ -22,14 +22,14 @@ received and serialized into a usable Ruby object. === Configuration and Usage -Putting ActiveResource to use is very similar to ActiveRecord. It's as simple as creating a model class +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 ActiveRecord invokes +Now the Person class is REST enabled and can invoke REST services very similarly to how Active Record invokes lifecycle methods that operate against a persistent store. # Find a person with id = 1 @@ -42,7 +42,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 -built into ActionController but will also work with any other REST service that properly implements the protocol. +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. @@ -55,8 +55,8 @@ for more general information on REST web services, see the article here[http://e ==== Find -GET Http requests 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 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: # Expects a response of # @@ -101,7 +101,7 @@ Collections can also be requested in a similar fashion ==== 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 XML 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. diff --git a/activeresource/lib/active_resource/base.rb b/activeresource/lib/active_resource/base.rb index a8c0da31f2..6cb5beb789 100644 --- a/activeresource/lib/active_resource/base.rb +++ b/activeresource/lib/active_resource/base.rb @@ -19,7 +19,7 @@ module ActiveResource # 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 lifecycle 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 @@ -112,6 +112,7 @@ module ActiveResource # # 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 @@ -156,7 +157,7 @@ module ActiveResource # # === Validation errors # - # Active Resource supports validations on resources and will return errors if any these validations fail + # Active Resource supports validations on resources and will return errors if any of these validations fail # (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. @@ -413,7 +414,7 @@ module ActiveResource # will split from the +prefix_options+. # # ==== Options - # * +prefix_options+ - A hash to add a prefix to the request for nested URL's (e.g., <tt>:account_id => 19</tt> + # * +prefix_options+ - A hash to add a prefix to the request for nested URLs (e.g., <tt>:account_id => 19</tt> # would yield a URL like <tt>/accounts/19/purchases.xml</tt>). # * +query_options+ - A hash to add items to the query string for the request. # @@ -691,7 +692,7 @@ module ActiveResource end - # A method to determine if the resource a \new object (i.e., it has not been POSTed to the remote service yet). + # Returns +true+ if this object hasn't yet been saved, otherwise, returns +false+. # # ==== Examples # not_new = Computer.create(:brand => 'Apple', :make => 'MacBook', :vendor => 'MacMall') @@ -760,7 +761,7 @@ module ActiveResource id.hash end - # Duplicate the current resource without saving it. + # Duplicates the current resource without saving it. # # ==== Examples # my_invoice = Invoice.create(:customer => 'That Company') @@ -779,8 +780,8 @@ module ActiveResource end end - # 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 + # Saves (+POST+) or \updates (+PUT+) a resource. Delegates to +create+ if the object is \new, + # +update+ if it exists. 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). # @@ -832,7 +833,7 @@ module ActiveResource !new? && self.class.exists?(to_param, :params => prefix_options) end - # A method to convert the the resource to an XML string. + # Converts the resource to an XML string representation. # # ==== Options # The +options+ parameter is handed off to the +to_xml+ method on each @@ -861,8 +862,7 @@ module ActiveResource attributes.to_xml({:root => self.class.element_name}.merge(options)) end - # Returns a JSON string representing the model. Some configuration is - # available through +options+. + # Converts the resource to a JSON string representation. # # ==== Options # The +options+ are passed to the +to_json+ method on each diff --git a/activeresource/lib/active_resource/connection.rb b/activeresource/lib/active_resource/connection.rb index 85103b53c5..80d5c95b68 100644 --- a/activeresource/lib/active_resource/connection.rb +++ b/activeresource/lib/active_resource/connection.rb @@ -95,46 +95,46 @@ module ActiveResource @password = URI.decode(@site.password) if @site.password end - # Set user for remote service. + # Sets the user for remote service. def user=(user) @user = user end - # Set password for remote service. + # Sets the password for remote service. def password=(password) @password = password end - # Set the number of seconds after which HTTP requests to the remote service should time out. + # Sets the number of seconds after which HTTP requests to the remote service should time out. def timeout=(timeout) @timeout = timeout end - # Execute a GET request. + # Executes a GET request. # Used to get (find) resources. def get(path, headers = {}) format.decode(request(:get, path, build_request_headers(headers, :get)).body) end - # Execute a DELETE request (see HTTP protocol documentation if unfamiliar). + # Executes a DELETE request (see HTTP protocol documentation if unfamiliar). # Used to delete resources. def delete(path, headers = {}) request(:delete, path, build_request_headers(headers, :delete)) end - # Execute a PUT request (see HTTP protocol documentation if unfamiliar). + # Executes a PUT request (see HTTP protocol documentation if unfamiliar). # Used to update resources. def put(path, body = '', headers = {}) request(:put, path, body.to_s, build_request_headers(headers, :put)) end - # Execute a POST request. + # Executes a POST request. # Used to create new resources. def post(path, body = '', headers = {}) request(:post, path, body.to_s, build_request_headers(headers, :post)) end - # Execute a HEAD request. + # Executes a HEAD request. # Used to obtain meta-information about resources, such as whether they exist and their size (via response headers). def head(path, headers = {}) request(:head, path, build_request_headers(headers)) @@ -142,7 +142,7 @@ module ActiveResource private - # Makes request to remote service. + # Makes a request to the remote service. def request(method, path, *arguments) logger.info "#{method.to_s.upcase} #{site.scheme}://#{site.host}:#{site.port}#{path}" if logger result = nil @@ -153,7 +153,7 @@ module ActiveResource raise TimeoutError.new(e.message) end - # Handles response and error codes from remote service. + # Handles response and error codes from the remote service. def handle_response(response) case response.code.to_i when 301,302 @@ -183,7 +183,7 @@ module ActiveResource end end - # Creates new Net::HTTP instance for communication with + # Creates new Net::HTTP instance for communication with the # remote service and resources. def http http = Net::HTTP.new(@site.host, @site.port) diff --git a/activeresource/lib/active_resource/validations.rb b/activeresource/lib/active_resource/validations.rb index de3339935f..8d21f8adbb 100644 --- a/activeresource/lib/active_resource/validations.rb +++ b/activeresource/lib/active_resource/validations.rb @@ -3,7 +3,7 @@ module ActiveResource end # Active Resource validation is reported to and from this object, which is used by Base#save - # to determine whether the object in a valid state to be saved. See usage example in Validations. + # to determine whether the object is in a valid state to be saved. See usage example in Validations. class Errors include Enumerable attr_reader :errors @@ -14,7 +14,10 @@ module ActiveResource @base, @errors = base, {} end - # Add an error to the base Active Resource object rather than an attribute. + # Adds an error to the base object instead of any particular attribute. This is used + # to report errors that don't tie to any specific attribute, but rather to the object + # as a whole. These error messages don't get prepended with any field name when iterating + # with +each_full+, so they should be complete sentences. # # ==== Examples # my_folder = Folder.find(1) @@ -68,9 +71,9 @@ module ActiveResource !@errors[attribute.to_s].nil? end - # A method to return the errors associated with +attribute+, which returns nil, if no errors are - # associated with the specified +attribute+, the error message if one error is associated with the specified +attribute+, - # or an array of error messages if more than one error is associated with the specified +attribute+. + # Returns +nil+ if no errors are associated with the specified +attribute+. + # Returns the error message if one error is associated with the specified +attribute+. + # Returns an array of error messages if more than one error is associated with the specified +attribute+. # # ==== Examples # my_person = Person.new(params[:person]) @@ -92,9 +95,7 @@ module ActiveResource alias :[] :on - # A method to return errors assigned to +base+ object through add_to_base, which returns nil, if no errors are - # associated with the specified +attribute+, the error message if one error is associated with the specified +attribute+, - # or an array of error messages if more than one error is associated with the specified +attribute+. + # Returns errors assigned to the base object through +add_to_base+ according to the normal rules of <tt>on(attribute)</tt>. # # ==== Examples # my_account = Account.find(1) |