1 require 'active_resource/connection'
6 # ActiveResource::Base is the main class for mapping RESTful resources as models in a Rails application.
8 # For an outline of what Active Resource is capable of, see link:files/vendor/rails/activeresource/README.html.
10 # == Automated mapping
12 # Active Resource objects represent your RESTful resources as manipulatable Ruby objects. To map resources
13 # to Ruby objects, Active Resource only needs a class name that corresponds to the resource name (e.g., the class
14 # Person maps to the resources people, very similarly to Active Record) and a +site+ value, which holds the
15 # URI of the resources.
17 # class Person < ActiveResource::Base
18 # self.site = "http://api.people.com:3000/"
21 # Now the Person class is mapped to RESTful resources located at <tt>http://api.people.com:3000/people/</tt>, and
22 # you can now use Active Resource's lifecycles methods to manipulate resources. In the case where you already have
23 # an existing model with the same name as the desired RESTful resource you can set the +element_name+ value.
25 # class PersonResource < ActiveResource::Base
26 # self.site = "http://api.people.com:3000/"
27 # self.element_name = "person"
31 # == Lifecycle methods
33 # Active Resource exposes methods for creating, finding, updating, and deleting resources
34 # from REST web services.
36 # ryan = Person.new(:first => 'Ryan', :last => 'Daigle')
39 # Person.exists?(ryan.id) # => true
40 # ryan.exists? # => true
42 # ryan = Person.find(1)
43 # # Resource holding our newly created Person object
45 # ryan.first = 'Rizzle'
48 # ryan.destroy # => true
50 # As you can see, these are very similar to Active Record's lifecycle methods for database records.
51 # You can read more about each of these methods in their respective documentation.
53 # === Custom REST methods
55 # Since simple CRUD/lifecycle methods can't accomplish every task, Active Resource also supports
56 # defining your own custom REST methods. To invoke them, Active Resource provides the <tt>get</tt>,
57 # <tt>post</tt>, <tt>put</tt> and <tt>\delete</tt> methods where you can specify a custom REST method
60 # # POST to the custom 'register' REST method, i.e. POST /people/new/register.xml.
61 # Person.new(:name => 'Ryan').post(:register)
62 # # => { :id => 1, :name => 'Ryan', :position => 'Clerk' }
64 # # PUT an update by invoking the 'promote' REST method, i.e. PUT /people/1/promote.xml?position=Manager.
65 # Person.find(1).put(:promote, :position => 'Manager')
66 # # => { :id => 1, :name => 'Ryan', :position => 'Manager' }
68 # # GET all the positions available, i.e. GET /people/positions.xml.
69 # Person.get(:positions)
70 # # => [{:name => 'Manager'}, {:name => 'Clerk'}]
72 # # DELETE to 'fire' a person, i.e. DELETE /people/1/fire.xml.
73 # Person.find(1).delete(:fire)
75 # For more information on using custom REST methods, see the
76 # ActiveResource::CustomMethods documentation.
80 # You can validate resources client side by overriding validation methods in the base class.
82 # class Person < ActiveResource::Base
83 # self.site = "http://api.people.com:3000/"
86 # errors.add("last", "has invalid characters") unless last =~ /[a-zA-Z]*/
90 # See the ActiveResource::Validations documentation for more information.
94 # Many REST APIs will require authentication, usually in the form of basic
95 # HTTP authentication. Authentication can be specified by:
96 # * putting the credentials in the URL for the +site+ variable.
98 # class Person < ActiveResource::Base
99 # self.site = "http://ryan:password@api.people.com:3000/"
102 # * defining +user+ and/or +password+ variables
104 # class Person < ActiveResource::Base
105 # self.site = "http://api.people.com:3000/"
107 # self.password = "password"
110 # For obvious security reasons, it is probably best if such services are available
113 # Note: Some values cannot be provided in the URL passed to site. e.g. email addresses
114 # as usernames. In those situations you should use the separate user and password option.
115 # == Errors & Validation
117 # Error handling and validation is handled in much the same manner as you're used to seeing in
118 # Active Record. Both the response code in the HTTP response and the body of the response are used to
119 # indicate that an error occurred.
121 # === Resource errors
123 # When a GET is requested for a resource that does not exist, the HTTP <tt>404</tt> (Resource Not Found)
124 # response code will be returned from the server which will raise an ActiveResource::ResourceNotFound
127 # # GET http://api.people.com:3000/people/999.xml
128 # ryan = Person.find(999) # 404, raises ActiveResource::ResourceNotFound
130 # <tt>404</tt> is just one of the HTTP error response codes that Active Resource will handle with its own exception. The
131 # following HTTP response codes will also result in these exceptions:
133 # * 200..399 - Valid response, no exception (other than 301, 302)
134 # * 301, 302 - ActiveResource::Redirection
135 # * 400 - ActiveResource::BadRequest
136 # * 401 - ActiveResource::UnauthorizedAccess
137 # * 403 - ActiveResource::ForbiddenAccess
138 # * 404 - ActiveResource::ResourceNotFound
139 # * 405 - ActiveResource::MethodNotAllowed
140 # * 409 - ActiveResource::ResourceConflict
141 # * 422 - ActiveResource::ResourceInvalid (rescued by save as validation errors)
142 # * 401..499 - ActiveResource::ClientError
143 # * 500..599 - ActiveResource::ServerError
144 # * Other - ActiveResource::ConnectionError
146 # These custom exceptions allow you to deal with resource errors more naturally and with more precision
147 # rather than returning a general HTTP error. For example:
150 # ryan = Person.find(my_id)
151 # rescue ActiveResource::ResourceNotFound
152 # redirect_to :action => 'not_found'
153 # rescue ActiveResource::ResourceConflict, ActiveResource::ResourceInvalid
154 # redirect_to :action => 'new'
157 # === Validation errors
159 # Active Resource supports validations on resources and will return errors if any these validations fail
160 # (e.g., "First name can not be blank" and so on). These types of errors are denoted in the response by
161 # a response code of <tt>422</tt> and an XML representation of the validation errors. The save operation will
162 # then fail (with a <tt>false</tt> return value) and the validation errors can be accessed on the resource in question.
164 # ryan = Person.find(1)
166 # ryan.save # => false
169 # # PUT http://api.people.com:3000/people/1.xml
170 # # is requested with invalid values, the response is:
173 # # <errors type="array"><error>First cannot be empty</error></errors>
176 # ryan.errors.invalid?(:first) # => true
177 # ryan.errors.full_messages # => ['First cannot be empty']
179 # Learn more about Active Resource's validation features in the ActiveResource::Validations documentation.
183 # Active Resource relies on HTTP to access RESTful APIs and as such is inherently susceptible to slow or
184 # unresponsive servers. In such cases, your Active Resource method calls could \timeout. You can control the
185 # amount of time before Active Resource times out with the +timeout+ variable.
187 # class Person < ActiveResource::Base
188 # self.site = "http://api.people.com:3000/"
192 # This sets the +timeout+ to 5 seconds. You can adjust the +timeout+ to a value suitable for the RESTful API
193 # you are accessing. It is recommended to set this to a reasonably low value to allow your Active Resource
194 # clients (especially if you are using Active Resource in a Rails application) to fail-fast (see
195 # http://en.wikipedia.org/wiki/Fail-fast) rather than cause cascading failures that could incapacitate your
198 # When a \timeout occurs, an ActiveResource::TimeoutError is raised. You should rescue from
199 # ActiveResource::TimeoutError in your Active Resource method calls.
201 # Internally, Active Resource relies on Ruby's Net::HTTP library to make HTTP requests. Setting +timeout+
202 # sets the <tt>read_timeout</tt> of the internal Net::HTTP instance to the same value. The default
203 # <tt>read_timeout</tt> is 60 seconds on most Ruby implementations.
207 # The logger for diagnosing and tracing Active Resource calls.
208 cattr_accessor
:logger
211 # Gets the URI of the REST resources to map for this class. The site variable is required for
212 # Active Resource's mapping to work.
214 # Not using superclass_delegating_reader because don't want subclasses to modify superclass instance
216 # With superclass_delegating_reader
218 # Parent.site = 'http://anonymous@test.com'
219 # Subclass.site # => 'http://anonymous@test.com'
220 # Subclass.site.user = 'david'
221 # Parent.site # => 'http://david@test.com'
223 # Without superclass_delegating_reader (expected behaviour)
225 # Parent.site = 'http://anonymous@test.com'
226 # Subclass.site # => 'http://anonymous@test.com'
227 # Subclass.site.user = 'david' # => TypeError: can't modify frozen object
231 elsif superclass
!= Object
&& superclass
.site
232 superclass
.site
.dup
.freeze
236 # Sets the URI of the REST resources to map for this class to the value in the +site+ argument.
237 # The site variable is required for Active Resource's mapping to work.
243 @site = create_site_uri_from(site
)
244 @user = URI
.decode(@site.user
) if @site.user
245 @password = URI
.decode(@site.password
) if @site.password
249 # Gets the \user for REST HTTP authentication.
251 # Not using superclass_delegating_reader. See +site+ for explanation
254 elsif superclass
!= Object
&& superclass
.user
255 superclass
.user
.dup
.freeze
259 # Sets the \user for REST HTTP authentication.
265 # Gets the \password for REST HTTP authentication.
267 # Not using superclass_delegating_reader. See +site+ for explanation
268 if defined?(@password)
270 elsif superclass
!= Object
&& superclass
.password
271 superclass
.password
.dup
.freeze
275 # Sets the \password for REST HTTP authentication.
276 def password
=(password
)
281 # Sets the format that attributes are sent and received in from a mime type reference:
283 # Person.format = :json
284 # Person.find(1) # => GET /people/1.json
286 # Person.format = ActiveResource::Formats::XmlFormat
287 # Person.find(1) # => GET /people/1.xml
289 # Default format is <tt>:xml</tt>.
290 def format
=(mime_type_reference_or_format
)
291 format
= mime_type_reference_or_format
.is_a
?(Symbol
) ?
292 ActiveResource
::Formats[mime_type_reference_or_format
] : mime_type_reference_or_format
294 write_inheritable_attribute(:format, format
)
295 connection
.format
= format
if site
298 # Returns the current format, default is ActiveResource::Formats::XmlFormat.
300 read_inheritable_attribute(:format) || ActiveResource
::Formats[:xml]
303 # Sets the number of seconds after which requests to the REST API should time out.
304 def timeout
=(timeout
)
309 # Gets the number of seconds after which requests to the REST API should time out.
311 if defined?(@timeout)
313 elsif superclass
!= Object
&& superclass
.timeout
318 # An instance of ActiveResource::Connection that is the base \connection to the remote service.
319 # The +refresh+ parameter toggles whether or not the \connection is refreshed at every request
320 # or not (defaults to <tt>false</tt>).
321 def connection(refresh
= false)
322 if defined?(@connection) || superclass
== Object
323 @connection = Connection
.new(site
, format
) if refresh
|| @connection.nil?
324 @connection.user
= user
if user
325 @connection.password
= password
if password
326 @connection.timeout
= timeout
if timeout
329 superclass
.connection
337 # Do not include any modules in the default element name. This makes it easier to seclude ARes objects
338 # in a separate namespace without having to set element_name repeatedly.
339 attr_accessor_with_default(:element_name) { to_s
.split("::").last
.underscore
} #:nodoc:
341 attr_accessor_with_default(:collection_name) { element_name
.pluralize
} #:nodoc:
342 attr_accessor_with_default(:primary_key, 'id') #:nodoc:
344 # Gets the \prefix for a resource's nested URL (e.g., <tt>prefix/collectionname/1.xml</tt>)
345 # This method is regenerated at runtime based on what the \prefix is set to.
346 def prefix(options
={})
348 default
<< '/' unless default
[-1..-1] == '/'
349 # generate the actual method based on the current site path
350 self.prefix
= default
354 # An attribute reader for the source string for the resource path \prefix. This
355 # method is regenerated at runtime based on what the \prefix is set to.
357 prefix
# generate #prefix and #prefix_source methods first
361 # Sets the \prefix for a resource's nested URL (e.g., <tt>prefix/collectionname/1.xml</tt>).
362 # Default value is <tt>site.path</tt>.
363 def prefix
=(value
= '/')
364 # Replace :placeholders with '#{embedded options[:lookups]}'
365 prefix_call
= value
.gsub(/:\w+/) { |key
| "\#{options[#{key}]}" }
367 # Clear prefix parameters in case they have been cached
368 @prefix_parameters = nil
370 # Redefine the new methods.
372 def prefix_source() "#{value}" end
373 def prefix(options={}) "#{prefix_call}" end
375 silence_warnings
{ instance_eval code
, __FILE__
, __LINE__
}
377 logger
.error
"Couldn't set prefix: #{$!}\n #{code}"
381 alias_method
:set_prefix, :prefix= #:nodoc:
383 alias_method
:set_element_name, :element_name= #:nodoc:
384 alias_method
:set_collection_name, :collection_name= #:nodoc:
386 # Gets the element path for the given ID in +id+. If the +query_options+ parameter is omitted, Rails
387 # will split from the \prefix options.
390 # +prefix_options+ - A \hash to add a \prefix to the request for nested URLs (e.g., <tt>:account_id => 19</tt>
391 # would yield a URL like <tt>/accounts/19/purchases.xml</tt>).
392 # +query_options+ - A \hash to add items to the query string for the request.
395 # Post.element_path(1)
398 # Comment.element_path(1, :post_id => 5)
399 # # => /posts/5/comments/1.xml
401 # Comment.element_path(1, :post_id => 5, :active => 1)
402 # # => /posts/5/comments/1.xml?active=1
404 # Comment.element_path(1, {:post_id => 5}, {:active => 1})
405 # # => /posts/5/comments/1.xml?active=1
407 def element_path(id
, prefix_options
= {}, query_options
= nil)
408 prefix_options
, query_options
= split_options(prefix_options
) if query_options
.nil?
409 "#{prefix(prefix_options)}#{collection_name}/#{id}.#{format.extension}#{query_string(query_options)}"
412 # Gets the collection path for the REST resources. If the +query_options+ parameter is omitted, Rails
413 # will split from the +prefix_options+.
416 # * +prefix_options+ - A hash to add a prefix to the request for nested URL's (e.g., <tt>:account_id => 19</tt>
417 # would yield a URL like <tt>/accounts/19/purchases.xml</tt>).
418 # * +query_options+ - A hash to add items to the query string for the request.
421 # Post.collection_path
424 # Comment.collection_path(:post_id => 5)
425 # # => /posts/5/comments.xml
427 # Comment.collection_path(:post_id => 5, :active => 1)
428 # # => /posts/5/comments.xml?active=1
430 # Comment.collection_path({:post_id => 5}, {:active => 1})
431 # # => /posts/5/comments.xml?active=1
433 def collection_path(prefix_options
= {}, query_options
= nil)
434 prefix_options
, query_options
= split_options(prefix_options
) if query_options
.nil?
435 "#{prefix(prefix_options)}#{collection_name}.#{format.extension}#{query_string(query_options)}"
438 alias_method
:set_primary_key, :primary_key= #:nodoc:
440 # Creates a new resource instance and makes a request to the remote service
441 # that it be saved, making it equivalent to the following simultaneous calls:
443 # ryan = Person.new(:first => 'ryan')
446 # Returns the newly created resource. If a failure has occurred an
447 # exception will be raised (see <tt>save</tt>). If the resource is invalid and
448 # has not been saved then <tt>valid?</tt> will return <tt>false</tt>,
449 # while <tt>new?</tt> will still return <tt>true</tt>.
452 # Person.create(:name => 'Jeremy', :email => 'myname@nospam.com', :enabled => true)
453 # my_person = Person.find(:first)
454 # my_person.email # => myname@nospam.com
456 # dhh = Person.create(:name => 'David', :email => 'dhh@nospam.com', :enabled => true)
457 # dhh.valid? # => true
458 # dhh.new? # => false
460 # # We'll assume that there's a validation that requires the name attribute
461 # that_guy = Person.create(:name => '', :email => 'thatguy@nospam.com', :enabled => true)
462 # that_guy.valid? # => false
463 # that_guy.new? # => true
464 def create(attributes
= {})
465 self.new(attributes
).tap
{ |resource
| resource
.save
}
468 # Core method for finding resources. Used similarly to Active Record's +find+ method.
471 # The first argument is considered to be the scope of the query. That is, how many
472 # resources are returned from the request. It can be one of the following.
474 # * <tt>:one</tt> - Returns a single resource.
475 # * <tt>:first</tt> - Returns the first resource found.
476 # * <tt>:last</tt> - Returns the last resource found.
477 # * <tt>:all</tt> - Returns every resource that matches the request.
481 # * <tt>:from</tt> - Sets the path or custom method that resources will be fetched from.
482 # * <tt>:params</tt> - Sets query and \prefix (nested URL) parameters.
486 # # => GET /people/1.xml
489 # # => GET /people.xml
491 # Person.find(:all, :params => { :title => "CEO" })
492 # # => GET /people.xml?title=CEO
494 # Person.find(:first, :from => :managers)
495 # # => GET /people/managers.xml
497 # Person.find(:last, :from => :managers)
498 # # => GET /people/managers.xml
500 # Person.find(:all, :from => "/companies/1/people.xml")
501 # # => GET /companies/1/people.xml
503 # Person.find(:one, :from => :leader)
504 # # => GET /people/leader.xml
506 # Person.find(:all, :from => :developers, :params => { :language => 'ruby' })
507 # # => GET /people/developers.xml?language=ruby
509 # Person.find(:one, :from => "/companies/1/manager.xml")
510 # # => GET /companies/1/manager.xml
512 # StreetAddress.find(1, :params => { :person_id => 1 })
513 # # => GET /people/1/street_addresses/1.xml
515 scope
= arguments
.slice
!(0)
516 options
= arguments
.slice
!(0) || {}
519 when :all then find_every(options
)
520 when :first then find_every(options
).first
521 when :last then find_every(options
).last
522 when :one then find_one(options
)
523 else find_single(scope
, options
)
527 # Deletes the resources with the ID in the +id+ parameter.
530 # All options specify \prefix and query parameters.
533 # Event.delete(2) # sends DELETE /events/2
535 # Event.create(:name => 'Free Concert', :location => 'Community Center')
536 # my_event = Event.find(:first) # let's assume this is event with ID 7
537 # Event.delete(my_event.id) # sends DELETE /events/7
539 # # Let's assume a request to events/5/cancel.xml
540 # Event.delete(params[:id]) # sends DELETE /events/5
541 def delete(id
, options
= {})
542 connection
.delete(element_path(id
, options
))
545 # Asserts the existence of a resource, returning <tt>true</tt> if the resource is found.
548 # Note.create(:title => 'Hello, world.', :body => 'Nothing more for now...')
549 # Note.exists?(1) # => true
551 # Note.exists(1349) # => false
552 def exists
?(id
, options
= {})
554 prefix_options
, query_options
= split_options(options
[:params])
555 path
= element_path(id
, prefix_options
, query_options
)
556 response
= connection
.head(path
, headers
)
557 response
.code
.to_i
== 200
559 # id && !find_single(id, options).nil?
560 rescue ActiveResource
::ResourceNotFound
565 # Find every resource
566 def find_every(options
)
567 case from
= options
[:from]
569 instantiate_collection(get(from
, options
[:params]))
571 path
= "#{from}#{query_string(options[:params])}"
572 instantiate_collection(connection
.get(path
, headers
) || [])
574 prefix_options
, query_options
= split_options(options
[:params])
575 path
= collection_path(prefix_options
, query_options
)
576 instantiate_collection( (connection
.get(path
, headers
) || []), prefix_options
)
580 # Find a single resource from a one-off URL
581 def find_one(options
)
582 case from
= options
[:from]
584 instantiate_record(get(from
, options
[:params]))
586 path
= "#{from}#{query_string(options[:params])}"
587 instantiate_record(connection
.get(path
, headers
))
591 # Find a single resource from the default URL
592 def find_single(scope
, options
)
593 prefix_options
, query_options
= split_options(options
[:params])
594 path
= element_path(scope
, prefix_options
, query_options
)
595 instantiate_record(connection
.get(path
, headers
), prefix_options
)
598 def instantiate_collection(collection
, prefix_options
= {})
599 collection
.collect
! { |record
| instantiate_record(record
, prefix_options
) }
602 def instantiate_record(record
, prefix_options
= {})
603 new(record
).tap
do |resource
|
604 resource
.prefix_options
= prefix_options
609 # Accepts a URI and creates the site URI from that.
610 def create_site_uri_from(site
)
611 site
.is_a
?(URI
) ? site
.dup
: URI
.parse(site
)
614 # contains a set of the current prefix parameters.
615 def prefix_parameters
616 @prefix_parameters ||= prefix_source
.scan(/:\w+/).map
{ |key
| key
[1..-1].to_sym
}.to_set
619 # Builds the query string for the request.
620 def query_string(options
)
621 "?#{options.to_query}" unless options
.nil? || options
.empty
?
624 # split an option hash into two hashes, one containing the prefix options,
625 # and the other containing the leftovers.
626 def split_options(options
= {})
627 prefix_options
, query_options
= {}, {}
629 (options
|| {}).each
do |key
, value
|
631 (prefix_parameters
.include?(key
.to_sym
) ? prefix_options
: query_options
)[key
.to_sym
] = value
634 [ prefix_options
, query_options
]
638 attr_accessor
:attributes #:nodoc:
639 attr_accessor
:prefix_options #:nodoc:
641 # Constructor method for \new resources; the optional +attributes+ parameter takes a \hash
642 # of attributes for the \new resource.
645 # my_course = Course.new
646 # my_course.name = "Western Civilization"
647 # my_course.lecturer = "Don Trotter"
650 # my_other_course = Course.new(:name => "Philosophy: Reason and Being", :lecturer => "Ralph Cling")
651 # my_other_course.save
652 def initialize(attributes
= {})
658 # Returns a \clone of the resource that hasn't been assigned an +id+ yet and
659 # is treated as a \new resource.
661 # ryan = Person.find(1)
662 # not_ryan = ryan.clone
663 # not_ryan.new? # => true
665 # Any active resource member attributes will NOT be cloned, though all other
666 # attributes are. This is to prevent the conflict between any +prefix_options+
667 # that refer to the original parent resource and the newly cloned parent
668 # resource that does not exist.
670 # ryan = Person.find(1)
671 # ryan.address = StreetAddress.find(1, :person_id => ryan.id)
672 # ryan.hash = {:not => "an ARes instance"}
674 # not_ryan = ryan.clone
675 # not_ryan.new? # => true
676 # not_ryan.address # => NoMethodError
677 # not_ryan.hash # => {:not => "an ARes instance"}
679 # Clone all attributes except the pk and any nested ARes
680 cloned
= attributes
.reject
{|k
,v
| k
== self.class.primary_key
|| v
.is_a
?(ActiveResource
::Base)}.inject({}) do |attrs
, (k
, v
)|
684 # Form the new resource - bypass initialize of resource with 'new' as that will call 'load' which
685 # attempts to convert hashes into member objects and arrays into collections of objects. We want
686 # the raw objects to be cloned so we bypass load by directly setting the attributes hash.
687 resource
= self.class.new({})
688 resource
.prefix_options
= self.prefix_options
689 resource
.send
:instance_variable_set, '@attributes', cloned
694 # A method to determine if the resource a \new object (i.e., it has not been POSTed to the remote service yet).
697 # not_new = Computer.create(:brand => 'Apple', :make => 'MacBook', :vendor => 'MacMall')
698 # not_new.new? # => false
700 # is_new = Computer.new(:brand => 'IBM', :make => 'Thinkpad', :vendor => 'IBM')
701 # is_new.new? # => true
704 # is_new.new? # => false
709 alias :new_record? :new?
711 # Gets the <tt>\id</tt> attribute of the resource.
713 attributes
[self.class.primary_key
]
716 # Sets the <tt>\id</tt> attribute of the resource.
718 attributes
[self.class.primary_key
] = id
721 # Allows Active Resource objects to be used as parameters in Action Pack URL generation.
726 # Test for equality. Resource are equal if and only if +other+ is the same object or
727 # is an instance of the same class, is not <tt>new?</tt>, and has the same +id+.
730 # ryan = Person.create(:name => 'Ryan')
731 # jamie = Person.create(:name => 'Jamie')
734 # # => false (Different name attribute and id)
736 # ryan_again = Person.new(:name => 'Ryan')
738 # # => false (ryan_again is new?)
740 # ryans_clone = Person.create(:name => 'Ryan')
741 # ryan == ryans_clone
742 # # => false (Different id attributes)
744 # ryans_twin = Person.find(ryan.id)
749 other
.equal
?(self) || (other
.instance_of
?(self.class) && other
.id
== id
&& other
.prefix_options
== prefix_options
)
752 # Tests for equality (delegates to ==).
757 # Delegates to id in order to allow two resources of the same type and \id to work with something like:
758 # [Person.find(1), Person.find(2)] & [Person.find(1), Person.find(4)] # => [Person.find(1)]
763 # Duplicate the current resource without saving it.
766 # my_invoice = Invoice.create(:customer => 'That Company')
767 # next_invoice = my_invoice.dup
768 # next_invoice.new? # => true
771 # next_invoice == my_invoice # => false (different id attributes)
773 # my_invoice.customer # => That Company
774 # next_invoice.customer # => That Company
776 self.class.new
.tap
do |resource
|
777 resource
.attributes
= @attributes
778 resource
.prefix_options
= @prefix_options
782 # A method to \save (+POST+) or \update (+PUT+) a resource. It delegates to +create+ if a \new object,
783 # +update+ if it is existing. If the response to the \save includes a body, it will be assumed that this body
784 # is XML for the final object as it looked after the \save (which would include attributes like +created_at+
785 # that weren't part of the original submit).
788 # my_company = Company.new(:name => 'RoleModel Software', :owner => 'Ken Auer', :size => 2)
789 # my_company.new? # => true
790 # my_company.save # sends POST /companies/ (create)
792 # my_company.new? # => false
793 # my_company.size = 10
794 # my_company.save # sends PUT /companies/1 (update)
796 new
? ? create
: update
799 # Deletes the resource from the remote service.
803 # my_person = Person.find(my_id)
805 # Person.find(my_id) # 404 (Resource Not Found)
807 # new_person = Person.create(:name => 'James')
808 # new_id = new_person.id # => 7
810 # Person.find(new_id) # 404 (Resource Not Found)
812 connection
.delete(element_path
, self.class.headers
)
815 # Evaluates to <tt>true</tt> if this resource is not <tt>new?</tt> and is
816 # found on the remote service. Using this method, you can check for
817 # resources that may have been deleted between the object's instantiation
821 # Person.create(:name => 'Theodore Roosevelt')
822 # that_guy = Person.find(:first)
823 # that_guy.exists? # => true
825 # that_lady = Person.new(:name => 'Paul Bean')
826 # that_lady.exists? # => false
828 # guys_id = that_guy.id
829 # Person.delete(guys_id)
830 # that_guy.exists? # => false
832 !new
? && self.class.exists
?(to_param
, :params => prefix_options
)
835 # A method to convert the the resource to an XML string.
838 # The +options+ parameter is handed off to the +to_xml+ method on each
839 # attribute, so it has the same options as the +to_xml+ methods in
842 # * <tt>:indent</tt> - Set the indent level for the XML output (default is +2+).
843 # * <tt>:dasherize</tt> - Boolean option to determine whether or not element names should
844 # replace underscores with dashes (default is <tt>false</tt>).
845 # * <tt>:skip_instruct</tt> - Toggle skipping the +instruct!+ call on the XML builder
846 # that generates the XML declaration (default is <tt>false</tt>).
849 # my_group = SubsidiaryGroup.find(:first)
851 # # => <?xml version="1.0" encoding="UTF-8"?>
852 # # <subsidiary_group> [...] </subsidiary_group>
854 # my_group.to_xml(:dasherize => true)
855 # # => <?xml version="1.0" encoding="UTF-8"?>
856 # # <subsidiary-group> [...] </subsidiary-group>
858 # my_group.to_xml(:skip_instruct => true)
859 # # => <subsidiary_group> [...] </subsidiary_group>
860 def to_xml(options
={})
861 attributes
.to_xml({:root => self.class.element_name
}.merge(options
))
864 # Returns a JSON string representing the model. Some configuration is
865 # available through +options+.
868 # The +options+ are passed to the +to_json+ method on each
869 # attribute, so the same options as the +to_json+ methods in
872 # * <tt>:only</tt> - Only include the specified attribute or list of
873 # attributes in the serialized output. Attribute names must be specified
875 # * <tt>:except</tt> - Do not include the specified attribute or list of
876 # attributes in the serialized output. Attribute names must be specified
880 # person = Person.new(:first_name => "Jim", :last_name => "Smith")
882 # # => {"first_name": "Jim", "last_name": "Smith"}
884 # person.to_json(:only => ["first_name"])
885 # # => {"first_name": "Jim"}
887 # person.to_json(:except => ["first_name"])
888 # # => {"last_name": "Smith"}
889 def to_json(options
={})
890 attributes
.to_json(options
)
893 # Returns the serialized string representation of the resource in the configured
894 # serialization format specified in ActiveResource::Base.format. The options
895 # applicable depend on the configured encoding format.
896 def encode(options
={})
897 case self.class.format
898 when ActiveResource
::Formats[:xml]
899 self.class.format
.encode(attributes
, {:root => self.class.element_name
}.merge(options
))
901 self.class.format
.encode(attributes
, options
)
905 # A method to \reload the attributes of this object from the remote web service.
908 # my_branch = Branch.find(:first)
909 # my_branch.name # => "Wislon Raod"
911 # # Another client fixes the typo...
913 # my_branch.name # => "Wislon Raod"
915 # my_branch.name # => "Wilson Road"
917 self.load(self.class.find(to_param
, :params => @prefix_options).attributes
)
920 # A method to manually load attributes from a \hash. Recursively loads collections of
921 # resources. This method is called in +initialize+ and +create+ when a \hash of attributes
925 # my_attrs = {:name => 'J&J Textiles', :industry => 'Cloth and textiles'}
926 # my_attrs = {:name => 'Marty', :colors => ["red", "green", "blue"]}
928 # the_supplier = Supplier.find(:first)
929 # the_supplier.name # => 'J&M Textiles'
930 # the_supplier.load(my_attrs)
931 # the_supplier.name('J&J Textiles')
933 # # These two calls are the same as Supplier.new(my_attrs)
934 # my_supplier = Supplier.new
935 # my_supplier.load(my_attrs)
937 # # These three calls are the same as Supplier.create(my_attrs)
938 # your_supplier = Supplier.new
939 # your_supplier.load(my_attrs)
942 raise ArgumentError
, "expected an attributes Hash, got #{attributes.inspect}" unless attributes
.is_a
?(Hash
)
943 @prefix_options, attributes
= split_options(attributes
)
944 attributes
.each
do |key
, value
|
945 @attributes[key
.to_s
] =
948 resource
= find_or_create_resource_for_collection(key
)
949 value
.map
{ |attrs
| attrs
.is_a
?(String
) ? attrs
.dup
: resource
.new(attrs
) }
951 resource
= find_or_create_resource_for(key
)
954 value
.dup
rescue value
960 # For checking <tt>respond_to?</tt> without searching the attributes (which is faster).
961 alias_method
:respond_to_without_attributes?, :respond_to?
963 # A method to determine if an object responds to a message (e.g., a method call). In Active Resource, a Person object with a
964 # +name+ attribute can answer <tt>true</tt> to <tt>my_person.respond_to?(:name)</tt>, <tt>my_person.respond_to?(:name=)</tt>, and
965 # <tt>my_person.respond_to?(:name?)</tt>.
966 def respond_to
?(method
, include_priv
= false)
967 method_name
= method
.to_s
970 elsif attributes
.has_key
?(method_name
)
972 elsif ['?','='].include?(method_name
.last
) && attributes
.has_key
?(method_name
.first(-1))
975 # super must be called at the end of the method, because the inherited respond_to?
976 # would return true for generated readers, even if the attribute wasn't present
982 def connection(refresh
= false)
983 self.class.connection(refresh
)
986 # Update the resource on the remote service.
988 connection
.put(element_path(prefix_options
), encode
, self.class.headers
).tap
do |response
|
989 load_attributes_from_response(response
)
993 # Create (i.e., \save to the remote service) the \new resource.
995 connection
.post(collection_path
, encode
, self.class.headers
).tap
do |response
|
996 self.id
= id_from_response(response
)
997 load_attributes_from_response(response
)
1001 def load_attributes_from_response(response
)
1002 if response
['Content-Length'] != "0" && response
.body
.strip
.size
> 0
1003 load(self.class.format
.decode(response
.body
))
1007 # Takes a response from a typical create post and pulls the ID out
1008 def id_from_response(response
)
1009 response
['Location'][/\/([^\
/]*?)(\.\w+)?$/, 1] if response
['Location']
1012 def element_path(options
= nil)
1013 self.class.element_path(to_param
, options
|| prefix_options
)
1016 def collection_path(options
= nil)
1017 self.class.collection_path(options
|| prefix_options
)
1021 # Tries to find a resource for a given collection name; if it fails, then the resource is created
1022 def find_or_create_resource_for_collection(name
)
1023 find_or_create_resource_for(name
.to_s
.singularize
)
1026 # Tries to find a resource in a non empty list of nested modules
1027 # Raises a NameError if it was not found in any of the given nested modules
1028 def find_resource_in_modules(resource_name
, module_names
)
1030 namespaces
= module_names
[0, module_names
.size-1
].map
do |module_name
|
1031 receiver
= receiver
.const_get(module_name
)
1033 if namespace
= namespaces
.reverse
.detect
{ |ns
| ns
.const_defined
?(resource_name
) }
1034 return namespace
.const_get(resource_name
)
1040 # Tries to find a resource for a given name; if it fails, then the resource is created
1041 def find_or_create_resource_for(name
)
1042 resource_name
= name
.to_s
.camelize
1043 ancestors
= self.class.name
.split("::")
1044 if ancestors
.size
> 1
1045 find_resource_in_modules(resource_name
, ancestors
)
1047 self.class.const_get(resource_name
)
1050 if self.class.const_defined
?(resource_name
)
1051 resource
= self.class.const_get(resource_name
)
1053 resource
= self.class.const_set(resource_name
, Class
.new(ActiveResource
::Base))
1055 resource
.prefix
= self.class.prefix
1056 resource
.site
= self.class.site
1060 def split_options(options
= {})
1061 self.class.__send__(:split_options, options
)
1064 def method_missing(method_symbol
, *arguments
) #:nodoc:
1065 method_name
= method_symbol
.to_s
1067 case method_name
.last
1069 attributes
[method_name
.first(-1)] = arguments
.first
1071 attributes
[method_name
.first(-1)]
1073 attributes
.has_key
?(method_name
) ? attributes
[method_name
] : super