Class: Rets::Client
- Inherits:
-
Object
- Object
- Rets::Client
- Defined in:
- lib/rets/client.rb
Defined Under Namespace
Classes: FakeLogger
Constant Summary collapse
- COUNT =
Struct.new(:exclude, :include, :only).new(0,1,2)
- CASE_INSENSITIVE_PROC =
Proc.new { |h,k| h.key?(k.downcase) ? h[k.downcase] : nil }
Instance Attribute Summary collapse
-
#cached_metadata ⇒ Object
Returns the value of attribute cached_metadata.
-
#client_progress ⇒ Object
Returns the value of attribute client_progress.
-
#logger ⇒ Object
Returns the value of attribute logger.
-
#login_url ⇒ Object
Returns the value of attribute login_url.
-
#options ⇒ Object
Returns the value of attribute options.
Instance Method Summary collapse
- #add_case_insensitive_default_proc(hash) ⇒ Object
-
#all_objects(opts = {}) ⇒ Object
Returns an array of all objects associated with the given resource.
-
#capabilities ⇒ Object
The capabilies as provided by the RETS server during login.
- #capability_url(name) ⇒ Object
- #clean_setup ⇒ Object
- #create_parts_from_response(response) ⇒ Object
- #decorate_result(result, rets_class) ⇒ Object
- #decorate_results(results, rets_class) ⇒ Object
- #extract_capabilities(document) ⇒ Object
- #fetch_object(object_id, opts = {}) ⇒ Object
-
#find(quantity, opts = {}) ⇒ Object
(also: #search)
Finds records.
- #find_every(opts) ⇒ Object
- #find_rets_class(resource_name, rets_class_name) ⇒ Object
- #find_with_given_retry(retries, opts) ⇒ Object
- #find_with_retries(opts = {}) ⇒ Object
- #handle_find_failure(retries, opts, e) ⇒ Object
- #http_get(url, params = nil, extra_headers = {}) ⇒ Object
- #http_post(url, params, extra_headers = {}) ⇒ Object
-
#initialize(options) ⇒ Client
constructor
A new instance of Client.
-
#login ⇒ Object
Attempts to login by making an empty request to the URL provided in initialize.
- #logout ⇒ Object
- #metadata(types = nil) ⇒ Object
-
#object(object_id, opts = {}) ⇒ Object
Returns a single object.
-
#objects(object_ids, opts = {}) ⇒ Object
Returns an array of specified objects.
- #retrieve_metadata(types = nil) ⇒ Object
- #retrieve_metadata_type(type) ⇒ Object
- #save_cookie_store ⇒ Object
- #tries ⇒ Object
Constructor Details
#initialize(options) ⇒ Client
Returns a new instance of Client.
10 11 12 13 |
# File 'lib/rets/client.rb', line 10 def initialize() @options = clean_setup end |
Instance Attribute Details
#cached_metadata ⇒ Object
Returns the value of attribute cached_metadata.
8 9 10 |
# File 'lib/rets/client.rb', line 8 def @cached_metadata end |
#client_progress ⇒ Object
Returns the value of attribute client_progress.
8 9 10 |
# File 'lib/rets/client.rb', line 8 def client_progress @client_progress end |
#logger ⇒ Object
Returns the value of attribute logger.
8 9 10 |
# File 'lib/rets/client.rb', line 8 def logger @logger end |
#login_url ⇒ Object
Returns the value of attribute login_url.
8 9 10 |
# File 'lib/rets/client.rb', line 8 def login_url @login_url end |
#options ⇒ Object
Returns the value of attribute options.
8 9 10 |
# File 'lib/rets/client.rb', line 8 def @options end |
Instance Method Details
#add_case_insensitive_default_proc(hash) ⇒ Object
322 323 324 325 326 |
# File 'lib/rets/client.rb', line 322 def add_case_insensitive_default_proc(hash) new_hash = hash.dup new_hash.default_proc = CASE_INSENSITIVE_PROC new_hash end |
#all_objects(opts = {}) ⇒ Object
Returns an array of all objects associated with the given resource.
175 176 177 |
# File 'lib/rets/client.rb', line 175 def all_objects(opts = {}) objects("*", opts) end |
#capabilities ⇒ Object
The capabilies as provided by the RETS server during login.
Currently, only the path in the endpoint URLs is used. Host, port, other details remaining constant with those provided to the constructor.
- 1
-
In fact, sometimes only a path is returned from the server.
282 283 284 285 286 287 288 289 290 |
# File 'lib/rets/client.rb', line 282 def capabilities if @capabilities @capabilities elsif @cached_capabilities @capabilities = add_case_insensitive_default_proc(@cached_capabilities) else login end end |
#capability_url(name) ⇒ Object
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 |
# File 'lib/rets/client.rb', line 292 def capability_url(name) val = capabilities[name] || capabilities[name.downcase] raise UnknownCapability.new(name, capabilities.keys) unless val begin if val.downcase.match(/^https?:\/\//) uri = URI.parse(val) else uri = URI.parse(login_url) uri.path = val end rescue URI::InvalidURIError raise MalformedResponse, "Unable to parse capability URL: #{name} => #{val.inspect}" end uri.to_s end |
#clean_setup ⇒ Object
15 16 17 18 19 20 21 22 23 24 25 |
# File 'lib/rets/client.rb', line 15 def clean_setup @metadata = nil @tries = nil @login_url = [:login_url] @cached_metadata = [:metadata] @cached_capabilities = [:capabilities] @logger = [:logger] || FakeLogger.new @client_progress = ClientProgressReporter.new(logger, [:stats_collector], [:stats_prefix]) @http_client = Rets::HttpClient.(, logger) @caching = Metadata::Caching.make() end |
#create_parts_from_response(response) ⇒ Object
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 |
# File 'lib/rets/client.rb', line 190 def create_parts_from_response(response) content_type = response.header["content-type"][0] if content_type.nil? raise MalformedResponse, "Unable to read content-type from response: #{response.inspect}" end if content_type.include?("multipart") boundary = content_type.scan(/boundary="?([^;"]*)?/).join parts = Parser::Multipart.parse(response.body, boundary) logger.debug "Rets::Client: Found #{parts.size} parts" return parts else logger.debug "Rets::Client: Found 1 part (the whole body)" # fake a multipart for interface compatibility headers = {} response.headers.each { |k,v| headers[k.downcase] = v } part = Parser::Multipart::Part.new(headers, response.body) return [part] end end |
#decorate_result(result, rets_class) ⇒ Object
162 163 164 165 166 167 168 169 170 171 172 |
# File 'lib/rets/client.rb', line 162 def decorate_result(result, rets_class) result.each do |key, value| table = rets_class.find_table(key) if table result[key] = table.resolve(value.to_s) else #can't resolve just leave the value be client_progress.(key) end end end |
#decorate_results(results, rets_class) ⇒ Object
156 157 158 159 160 |
# File 'lib/rets/client.rb', line 156 def decorate_results(results, rets_class) results.map do |result| decorate_result(result, rets_class) end end |
#extract_capabilities(document) ⇒ Object
310 311 312 313 314 315 316 317 318 319 320 |
# File 'lib/rets/client.rb', line 310 def extract_capabilities(document) raw_key_values = document.xpath("/RETS/RETS-RESPONSE").text.strip # ... :( # Feel free to make this better. It has a test. hash = raw_key_values.split(/\n/). map { |r| r.split(/\=/, 2) }. each_with_object({}) { |(k,v), h| h[k.strip.downcase] = v.strip } add_case_insensitive_default_proc(hash) end |
#fetch_object(object_id, opts = {}) ⇒ Object
228 229 230 231 232 233 234 235 236 237 238 239 240 241 |
# File 'lib/rets/client.rb', line 228 def fetch_object(object_id, opts = {}) params = { "Resource" => opts.fetch(:resource), "Type" => opts.fetch(:object_type), "ID" => "#{opts.fetch(:resource_id)}:#{object_id}", "Location" => opts.fetch(:location, 0) } extra_headers = { "Accept" => "image/jpeg, image/png;q=0.5, image/gif;q=0.1", } http_post(capability_url("GetObject"), params, extra_headers) end |
#find(quantity, opts = {}) ⇒ Object Also known as: search
Finds records.
- quantity
-
Return the first record, or an array of records. Uses a symbol
:first
or:all
, respectively. - opts
-
A hash of arguments used to construct the search query, using the following keys:
:search_type
-
Required. The resource to search for.
:class
-
Required. The class of the resource to search for.
:query
-
Required. The DMQL2 query string to execute.
:limit
-
The number of records to request from the server.
:resolve
-
Provide resolved values that use metadata instead of raw system values.
Any other keys are converted to the RETS query format, and passed to the server as part of the query. For instance, the key :offset
will be sent as Offset
.
71 72 73 74 75 76 77 |
# File 'lib/rets/client.rb', line 71 def find(quantity, opts = {}) case quantity when :first then find_with_retries(opts.merge(:limit => 1)).first when :all then find_with_retries(opts) else raise ArgumentError, "First argument must be :first or :all" end end |
#find_every(opts) ⇒ Object
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 |
# File 'lib/rets/client.rb', line 116 def find_every(opts) raise ArgumentError.new("missing option :search_type (provide the name of a RETS resource)") unless opts[:search_type] raise ArgumentError.new("missing option :class (provide the name of a RETS class)") unless opts[:class] params = { "SearchType" => opts.fetch(:search_type), "Class" => opts.fetch(:class), "Count" => opts[:count], "Format" => opts.fetch(:format, "COMPACT"), "Limit" => opts[:limit], "Offset" => opts[:offset], "Select" => opts[:select], "RestrictedIndicator" => opts[:RestrictedIndicator], "StandardNames" => opts[:standard_name], "Payload" => opts[:payload], "Query" => opts[:query], "QueryType" => opts.fetch(:query_type, "DMQL2"), }.reject { |k,v| v.nil? } res = http_post(capability_url("Search"), params) if opts[:count] == COUNT.only Parser::Compact.get_count(res.body) else results = Parser::Compact.parse_document( res.body.encode("UTF-8", res.body.encoding, :invalid => :replace, :undef => :replace) ) if opts[:resolve] rets_class = find_rets_class(opts[:search_type], opts[:class]) decorate_results(results, rets_class) else results end end end |
#find_rets_class(resource_name, rets_class_name) ⇒ Object
152 153 154 |
# File 'lib/rets/client.rb', line 152 def find_rets_class(resource_name, rets_class_name) .tree[resource_name].find_rets_class(rets_class_name) end |
#find_with_given_retry(retries, opts) ⇒ Object
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 |
# File 'lib/rets/client.rb', line 86 def find_with_given_retry(retries, opts) begin find_every(opts) rescue NoRecordsFound => e if opts.fetch(:no_records_not_an_error, false) client_progress.no_records_found opts[:count] == COUNT.only ? 0 : [] else handle_find_failure(retries, opts, e) end rescue InvalidRequest, HttpError => e handle_find_failure(retries, opts, e) rescue AuthorizationFailure => e login handle_find_failure(retries, opts, e) end end |
#find_with_retries(opts = {}) ⇒ Object
81 82 83 84 |
# File 'lib/rets/client.rb', line 81 def find_with_retries(opts = {}) retries = 0 find_with_given_retry(retries, opts) end |
#handle_find_failure(retries, opts, e) ⇒ Object
104 105 106 107 108 109 110 111 112 113 114 |
# File 'lib/rets/client.rb', line 104 def handle_find_failure(retries, opts, e) if retries < opts.fetch(:max_retries, 3) retries += 1 client_progress.find_with_retries_failed_a_retry(e, retries) clean_setup find_with_given_retry(retries, opts) else client_progress.find_with_retries_exceeded_retry_count(e) raise e end end |
#http_get(url, params = nil, extra_headers = {}) ⇒ Object
332 333 334 |
# File 'lib/rets/client.rb', line 332 def http_get(url, params=nil, extra_headers={}) @http_client.http_get(url, params, extra_headers) end |
#http_post(url, params, extra_headers = {}) ⇒ Object
336 337 338 |
# File 'lib/rets/client.rb', line 336 def http_post(url, params, extra_headers = {}) @http_client.http_post(url, params, extra_headers) end |
#login ⇒ Object
Attempts to login by making an empty request to the URL provided in initialize. Returns the capabilities that the RETS server provides, per page 34 of www.realtor.org/retsorg.nsf/retsproto1.7d6.pdf#page=34
30 31 32 33 34 35 36 37 38 39 |
# File 'lib/rets/client.rb', line 30 def login res = http_get(login_url) Parser::ErrorChecker.check(res) new_capabilities = extract_capabilities(Nokogiri.parse(res.body)) unless new_capabilities raise UnknownResponse, "Cannot read rets server capabilities." end @capabilities = new_capabilities end |
#logout ⇒ Object
41 42 43 44 45 46 47 48 49 50 |
# File 'lib/rets/client.rb', line 41 def logout unless capabilities["Logout"] raise NoLogout.new('No logout method found for rets client') end http_get(capability_url("Logout")) rescue UnknownResponse => e unless e..match(/expected a 200, but got 401/) raise e end end |
#metadata(types = nil) ⇒ Object
243 244 245 246 247 248 249 250 251 252 253 254 255 256 |
# File 'lib/rets/client.rb', line 243 def (types=nil) return @metadata if @metadata @cached_metadata ||= @caching.load(@logger) if && ([:skip_metadata_uptodate_check] || .current?(capabilities["MetadataTimestamp"], capabilities["MetadataVersion"])) client_progress. @metadata = else client_progress.() @metadata = Metadata::Root.new(logger, (types)) @caching.save() end @metadata end |
#object(object_id, opts = {}) ⇒ Object
Returns a single object.
resource RETS resource as defined in the resource metadata. object_type an object type defined in the object metadata. resource_id the KeyField value of the given resource instance. object_id can be “*” or a colon delimited string of integers or an array of integers.
223 224 225 226 |
# File 'lib/rets/client.rb', line 223 def object(object_id, opts = {}) response = fetch_object(Array(object_id).join(':'), opts) response.body end |
#objects(object_ids, opts = {}) ⇒ Object
Returns an array of specified objects.
180 181 182 183 184 185 186 187 188 |
# File 'lib/rets/client.rb', line 180 def objects(object_ids, opts = {}) response = case object_ids when String then fetch_object(object_ids, opts) when Array then fetch_object(object_ids.join(":"), opts) else raise ArgumentError, "Expected instance of String or Array, but got #{object_ids.inspect}." end create_parts_from_response(response) end |
#retrieve_metadata(types = nil) ⇒ Object
258 259 260 261 262 263 264 |
# File 'lib/rets/client.rb', line 258 def (types=nil) = {} (types || Metadata::METADATA_TYPES).each {|type| [type] = (type) } end |
#retrieve_metadata_type(type) ⇒ Object
266 267 268 269 270 271 272 273 |
# File 'lib/rets/client.rb', line 266 def (type) res = http_post(capability_url("GetMetadata"), { "Format" => "COMPACT", "Type" => "METADATA-#{type}", "ID" => "0" }) res.body end |
#save_cookie_store ⇒ Object
328 329 330 |
# File 'lib/rets/client.rb', line 328 def @http_client. end |
#tries ⇒ Object
340 341 342 343 344 |
# File 'lib/rets/client.rb', line 340 def tries @tries ||= 1 (@tries += 1) - 1 end |