rets4r 0.8.2

data/TODO

@@ -0,0 +1,26 @@
+Fix
+* Unit Tests (We need METADATA!)
+
+Add support for
+* Standard (non-compact) XML
+
+Add
+* More Examples
+* More Documentation
+* Reply Codes (Readable Meaning)
+* A search convenience method that makes subsequent requests if maxrows is true.
+
+Verify
+* 1.7 Compliance and support
+
+Check
+* GetMetadata
+
+Possible To-do Items
+* RETS 1.0
+* RETS 2.0 (May not be necessary since it is now SOAP based, but it would be nice to have a consistent API)
+* Running a RETS Server
+* Update Actions
+* Password Change Transaction
+* Get Transaction
+* HTTPS Support

data/examples/client_get_object.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/ruby
+#
+# This is an example of how to use the RETS client to retrieve an objet.
+#
+# You will need to set the necessary variables below.
+#
+#############################################################################################
+# Settings
+
+rets_url = 'http://server.com/my/rets/url'
+username = 'username'
+password = 'password'
+
+# GetObject Settings
+resource    = 'Property'
+object_type = 'Photo'
+resource_id = 'id:*'
+
+#############################################################################################
+$:.unshift 'lib'
+
+require 'rets4r'
+require 'logger'
+
+def handle_object(object)
+	case object.info['Content-Type']
+		when 'image/jpeg' then extension = 'jpg'
+		when 'image/gif'  then extension = 'gif'
+		when 'image/png'  then extension = 'png'
+		else extension = 'unknown'
+	end
+
+	File.open("#{object.info['Content-ID']}_#{object.info['Object-ID']}.#{extension}", 'w') do |f|
+		f.write(object.data)
+	end
+end
+
+client = RETS4R::Client.new(rets_url)
+
+client.login(username, password) do |login_result|
+	
+	if login_result.success?
+		## Method 1
+		# Get objects using a block
+		client.get_object(resource, object_type, resource_id) do |object|
+			handle_object(object)
+		end
+		
+		## Method 2
+		# Get objects using a return value
+		results = client.get_object(resource, object_type, resource_id)
+		
+		results.each do |object|
+			handle_object(object)
+		end
+	else
+		puts "We were unable to log into the RETS server."
+		puts "Please check that you have set the login variables correctly."
+	end
+end

data/examples/client_login.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/ruby
+#
+# This is an example of how to use the RETS client to log in and out of a server. 
+#
+# You will need to set the necessary variables below.
+#
+#############################################################################################
+# Settings
+
+rets_url = 'http://server.com/my/rets/url'
+username = 'username'
+password = 'password'
+
+#############################################################################################
+$:.unshift 'lib'
+
+require 'rets4r'
+require 'logger'
+
+client = RETS4R::Client.new(rets_url)
+client.logger = Logger.new(STDOUT)
+
+login_result = client.login(username, password)
+
+if login_result.success?
+	puts "We successfully logged into the RETS server!"
+	
+	# Print the action URL results (if any)
+	puts login_result.secondary_response
+	
+	client.logout
+	
+	puts "We just logged out of the server."
+else
+	puts "We were unable to log into the RETS server."
+	puts "Please check that you have set the login variables correctly."
+end

data/examples/client_metadata.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/ruby
+#
+# This is an example of how to use the RETS client to login to a server and retrieve metadata. It
+# also makes use of passing blocks to client methods and demonstrates how to set the output format.
+#
+# You will need to set the necessary variables below.
+#
+#############################################################################################
+# Settings
+
+rets_url = 'http://server.com/my/rets/url'
+username = 'username'
+password = 'password'
+  
+#############################################################################################
+$:.unshift 'lib'
+
+require 'rets4r'
+
+RETS4R::Client.new(rets_url) do |client|
+	client.login(username, password) do |login_result|		
+		if login_result.success?
+			puts "Logged in successfully!"
+						
+			# We want the raw metadata, so we need to set the output to raw XML.
+			client.set_output RETS4R::Client::OUTPUT_RAW
+			metadata = ''
+			
+			begin
+				metadata = client.get_metadata
+			rescue
+				puts "Unable to get metadata: '#{$!}'"
+			end
+			
+			File.open('metadata.xml', 'w') do |file|
+				file.write metadata
+			end
+		else
+			puts "Unable to login: '#{login_result.reply_text}'."
+		end
+	end
+end

data/examples/client_search.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/ruby
+#
+# This is an example of how to use the RETS client to perform a basic search.
+#
+# You will need to set the necessary variables below.
+#
+#############################################################################################
+# Settings
+
+rets_url = 'http://server.com/my/rets/url'
+username = 'username'
+password = 'password'
+
+rets_resource = 'Property'
+rets_class    = 'Residential'
+rets_query    = '(RetsField=Value)'
+
+#############################################################################################
+$:.unshift 'lib'
+
+require 'rets4r'
+
+client = RETS4R::Client.new(rets_url)
+
+logger = Logger.new($stdout)
+logger.level = Logger::WARN
+client.logger = logger
+
+login_result = client.login(username, password)
+
+if login_result.success?
+	puts "We successfully logged into the RETS server!"
+	
+	options = {'Limit' => 5}
+	
+	client.search(rets_resource, rets_class, rets_query, options) do |result|
+		result.data.each do |row|
+			puts row.inspect
+			puts
+		end
+	end
+	
+	client.logout
+	
+	puts "We just logged out of the server."
+else
+	puts "We were unable to log into the RETS server."
+	puts "Please check that you have set the login variables correctly."
+end
+
+logger.close

data/lib/rets4r.rb

@@ -0,0 +1 @@
+require 'rets4r/client'

data/lib/rets4r/auth.rb

@@ -0,0 +1,69 @@
+require 'digest/md5'
+
+module RETS4R
+	class Auth
+		# This is the primary method that would normally be used, and while it 
+		def Auth.authenticate(response, username, password, uri, method, requestId, useragent, nc = 0)
+			authHeader = Auth.parse_header(response['www-authenticate'])
+					
+			cnonce = cnonce(useragent, password, requestId, authHeader['nonce'])
+			
+			authHash = calculate_digest(username, password, authHeader['realm'], authHeader['nonce'], method, uri, authHeader['qop'], cnonce, nc)
+			
+			header = ''
+			header << "Digest username=\"#{username}\", "
+			header << "realm=\"#{authHeader['realm']}\", "
+			header << "qop=\"#{authHeader['qop']}\", "
+			header << "uri=\"#{uri}\", "
+			header << "nonce=\"#{authHeader['nonce']}\", "
+			header << "nc=#{('%08x' % nc)}, "
+			header << "cnonce=\"#{cnonce}\", "
+			header << "response=\"#{authHash}\", "
+			header << "opaque=\"#{authHeader['opaque']}\""
+			
+			return header
+		end
+		
+		def Auth.calculate_digest(username, password, realm, nonce, method, uri, qop = false, cnonce = false, nc = 0)				
+			a1 = "#{username}:#{realm}:#{password}"
+			a2 = "#{method}:#{uri}"
+						
+			response = '';
+			
+			requestId = Auth.request_id unless requestId
+			
+			if (qop)			
+				throw ArgumentException, 'qop requires a cnonce to be provided.' unless cnonce
+				
+				response = Digest::MD5.hexdigest("#{Digest::MD5.hexdigest(a1)}:#{nonce}:#{('%08x' % nc)}:#{cnonce}:#{qop}:#{Digest::MD5.hexdigest(a2)}")
+			else
+				response = Digest::MD5.hexdigest("#{Digest::MD5.hexdigest(a1)}:#{nonce}:#{Digest::MD5.hexdigest(a2)}")
+			end
+		
+			return response
+		end
+		
+		def Auth.parse_header(header)
+			type = header[0, header.index(' ')]
+			args = header[header.index(' '), header.length].strip.split(',')
+	
+			parts = {'type' => type}
+			
+			args.each do |arg|
+				name, value = arg.split('=')
+				
+				parts[name.downcase] = value.tr('"', '')
+			end
+			
+			return parts
+		end
+		
+		def Auth.request_id
+			Digest::MD5.hexdigest(Time.new.to_f.to_s)
+		end
+		
+		def Auth.cnonce(useragent, password, requestId, nonce)
+			Digest::MD5.hexdigest("#{useragent}:#{password}:#{requestId}:#{nonce}")
+		end
+	end
+end

data/lib/rets4r/client.rb

@@ -0,0 +1,563 @@
+# RETS4R Client
+#
+# Copyright (c) 2006 Scott Patterson <scott.patterson@digitalaun.com>
+#
+# This program is copyrighted free software by Scott Patterson.  You can
+# redistribute it and/or modify it under the same terms of Ruby's license;
+# either the dual license version in 2003 (see the file RUBYS), or any later
+# version.
+#
+#	TODO
+#		1.0 Support (Adding this support should be fairly easy)
+#		2.0 Support (Adding this support will be very difficult since it is a completely different methodology)
+#		Case-insensitive header
+
+require 'digest/md5'
+require 'net/http'
+require 'uri'
+require 'cgi'
+require 'rets4r/auth'
+require 'rets4r/client/dataobject'
+require 'thread'
+require 'logger'
+
+module RETS4R
+	class Client
+		OUTPUT_RAW	= 0	# Nothing done. Simply returns the XML.
+		OUTPUT_DOM	= 1	# Returns a DOM object (REXML)	**** NO LONGER SUPPORTED! ****
+		OUTPUT_RUBY	= 2 # Returns a RETS::Data object
+		
+		METHOD_GET	= 'GET'
+		METHOD_POST = 'POST'
+		METHOD_HEAD = 'HEAD'
+		
+		DEFAULT_OUTPUT		   = OUTPUT_RUBY
+		DEFAULT_METHOD 		   = METHOD_GET
+		DEFAULT_RETRY        = 2
+		DEFAULT_USER_AGENT 	 = 'RETS4R/0.8.2'
+		DEFAULT_RETS_VERSION = '1.7'
+		SUPPORTED_RETS_VERSIONS = ['1.5', '1.7']
+		CAPABILITY_LIST   = ['Action', 'ChangePassword', 'GetObject', 'Login', 'LoginComplete', 'Logout', 'Search', 'GetMetadata', 'Update']
+		SUPPORTED_PARSERS = [] # This will be populated by parsers as they load
+
+		attr_accessor :mimemap, :logger
+		
+		# We load our parsers here so that they can modify the client class appropriately. Because
+		# the default parser will be the first parser to list itself in the DEFAULT_PARSER array,
+		# we need to require them in the order of preference. Hence, XMLParser is loaded first because
+		# it is preferred to REXML since it is much faster.
+		require 'rets4r/client/parser/xmlparser'
+		require 'rets4r/client/parser/rexml'
+		
+		# Set it as the first
+		DEFAULT_PARSER = SUPPORTED_PARSERS[0]
+		
+		# Constructor
+		# 
+		# Requires the URL to the RETS server and takes an optional output format. The output format
+		# determines the type of data returned by the various RETS transaction methods.
+		def initialize(url, output = DEFAULT_OUTPUT)
+			raise Unsupported.new('DOM output is no longer supported.') if output == OUTPUT_DOM
+			
+			@urls     = { 'Login' => URI.parse(url) }
+			@nc       = 0
+			@headers  = {
+				'User-Agent'   => DEFAULT_USER_AGENT, 
+				'Accept'       => '*/*', 
+				'RETS-Version' => "RETS/#{DEFAULT_RETS_VERSION}", 
+				'RETS-Session-ID' => '0'
+				}
+			@request_method = DEFAULT_METHOD
+			@parser_class   = DEFAULT_PARSER
+			@semaphore      = Mutex.new
+			@output         = output
+			
+			self.mimemap		= {
+				'image/jpeg'  => 'jpg',
+				'image/gif'   => 'gif'
+				}
+				
+			if block_given?
+				yield self
+			end
+		end
+		
+		# We only allow external read access to URLs because they are internally set based on the
+		# results of various queries.
+		def urls
+			@urls
+		end
+		
+		# Parses the provided XML returns it in the specified output format.
+		# Requires an XML string and takes an optional output format to override the instance output
+		# format variable. We current create a new parser each time, which seems a bit wasteful, but
+		# it allows for the parser to be changed in the middle of a session as well as XML::Parser
+		# requiring a new instance for each execution...that could be encapsulated within its parser
+		# class,though, so we should benchmark and see if it will make a big difference with the 
+		# REXML parse, which I doubt.
+		def parse(xml, output = false)
+			if xml == ''
+				trans = Transaction.new()
+				trans.reply_code = -1
+				trans.reply_text = 'No transaction body was returned!'
+			end
+			
+			if output == OUTPUT_RAW || @output == OUTPUT_RAW
+				xml
+			else
+				begin
+					parser = @parser_class.new
+					parser.logger = logger
+					parser.output = output ? output : @output
+
+					parser.parse(xml)
+				rescue
+					raise ParserException.new($!)
+				end
+			end
+		end
+		
+		# Setup Methods (accessors and mutators)
+		def set_output(output = DEFAULT_OUTPUT)
+			@output = output
+		end
+		
+		def get_output
+			@output
+		end
+		
+		def set_parser_class(klass, force = false)
+			if force || SUPPORTED_PARSERS.include?(klass)
+				@parser_class = klass
+			else
+				message = "The parser class '#{klass}' is not supported!"
+				logger.debug(message) if logger
+				
+				raise Unsupported.new(message)
+			end
+		end
+		
+		def get_parser_class
+			@parser_class
+		end
+		
+		def set_header(name, value)
+			if value.nil? then
+				@headers.delete(name)
+			else
+				@headers[name] = value
+			end
+			
+			logger.debug("Set header '#{name}' to '#{value}'") if logger
+		end
+		
+		def get_header(name)
+			@headers[name]
+		end
+		
+		def set_user_agent(name)
+			set_header('User-Agent', name)
+		end
+		
+		def get_user_agent
+			get_header('User-Agent')
+		end
+		
+		def set_rets_version(version)
+			if (SUPPORTED_RETS_VERSIONS.include? version)
+				set_header('RETS-Version', "RETS/#{version}")
+			else
+				raise Unsupported.new("The client does not support RETS version '#{version}'.")
+			end
+		end
+		
+		def get_rets_version
+			(get_header('RETS-Version') || "").gsub("RETS/", "")
+		end
+		
+		def set_request_method(method)
+			@request_method = method
+		end
+		
+		def get_request_method
+			@request_method
+		end
+		
+		# Provide more Ruby-like attribute accessors instead of get/set methods
+		alias_method :user_agent=, :set_user_agent
+		alias_method :user_agent, :get_user_agent
+		alias_method :request_method=, :set_request_method
+		alias_method :request_method, :get_request_method
+		alias_method :rets_version=, :set_rets_version
+		alias_method :rets_version, :get_rets_version
+		alias_method :parser_class=, :set_parser_class
+		alias_method :parser_class, :get_parser_class
+		alias_method :output=, :set_output
+		alias_method :output, :get_output
+		
+		#### RETS Transaction Methods ####
+		#
+		# Most of these transaction methods mirror the RETS specification methods, so if you are 
+		# unsure what they mean, you should check the RETS specification. The latest version can be
+		# found at http://www.rets.org
+		
+		# Attempts to log into the server using the provided username and password.
+		#
+		# If called with a block, the results of the login action are yielded,
+		# and logout is called when the block returns.  In that case, #login
+		# returns the block's value. If called without a block, returns the
+		# result.
+		#
+		# As specified in the RETS specification, the Action URL is called and
+		# the results made available in the #secondary_results accessor of the
+		# results object.
+		def login(username, password) #:yields: login_results
+			@username = username
+			@password = password
+			
+			# We are required to set the Accept header to this by the RETS 1.5 specification.
+			set_header('Accept', '*/*')
+			
+			response = request(@urls['Login'])
+			
+			# Parse response to get other URLS
+			results = self.parse(response.body, OUTPUT_RUBY)
+			
+			if (results.success?)
+				CAPABILITY_LIST.each do |capability|
+					next unless results.response[capability]
+					base = @urls['Login'].clone
+					base.path = results.response[capability]
+					
+					@urls[capability] = base
+				end
+				
+				logger.debug("Capability URL List: #{@urls.inspect}") if logger
+			else
+				raise LoginError.new(response.message + "(#{results.reply_code}: #{results.reply_text})")
+			end
+			
+			if @output != OUTPUT_RUBY
+				results = self.parse(response.body)
+			end
+			
+			# Perform the mandatory get request on the action URL.
+			results.secondary_response = perform_action_url
+			
+			# We only yield
+			if block_given?
+				begin
+					yield results
+				ensure
+					self.logout
+				end
+			else
+				results
+			end
+		end
+		
+		# Logs out of the RETS server.
+		def logout()
+			# If no logout URL is provided, then we assume that logout is not necessary (not to 
+			# mention impossible without a URL). We don't throw an exception, though, but we might
+			# want to if this becomes an issue in the future.
+			
+			request(@urls['Logout']) if @urls['Logout']
+		end
+		
+		# Requests Metadata from the server. An optional type and id can be specified to request
+		# subsets of the Metadata. Please see the RETS specification for more details on this.
+		# The format variable tells the server which format to return the Metadata in. Unless you
+		# need the raw metadata in a specified format, you really shouldn't specify the format.
+		#
+		# If called with a block, yields the results and returns the value of the block, or
+		# returns the metadata directly.
+		def get_metadata(type = 'METADATA-SYSTEM', id = '*', format = 'COMPACT')
+			header = {
+				'Accept' => 'text/xml,text/plain;q=0.5'
+			}
+			
+			data = {
+				'Type'   => type,
+				'ID'     => id,
+				'Format' => format
+			}
+					
+			response = request(@urls['GetMetadata'], data, header)
+			
+			result = self.parse(response.body)
+			
+			if block_given?
+				yield result
+			else
+				result
+			end
+		end
+		
+		# Performs a GetObject transaction on the server. For details on the arguments, please see
+		# the RETS specification on GetObject requests.
+		#
+		# This method either returns an Array of DataObject instances, or yields each DataObject
+		# as it is created. If a block is given, the number of objects yielded is returned.
+		def get_object(resource, type, id, location = 1) #:yields: data_object
+			header = {
+				'Accept' => mimemap.keys.join(',')
+			}
+			
+			data = {
+				'Resource' => resource,
+				'Type'     => type,
+				'ID'       => id,
+				'Location' => location.to_s
+			}
+			
+			response = request(@urls['GetObject'], data, header)
+			results = block_given? ? 0 : []
+			
+			if response['content-type'].include?('multipart/parallel')
+				content_type = process_content_type(response['content-type'])
+
+				parts = response.body.split("\r\n--#{content_type['boundary']}")
+				parts.shift # Get rid of the initial boundary
+				
+				parts.each do |part|
+					(raw_header, raw_data) = part.split("\r\n\r\n")
+					
+					next unless raw_data
+					
+					data_header = process_header(raw_header)
+					data_object = DataObject.new(data_header, raw_data)
+					
+					if block_given?
+						yield data_object
+						results += 1
+					else
+						results << data_object
+					end
+				end 
+			else
+				info = {
+					'content-type' => response['content-type'], # Compatibility shim.  Deprecated.
+					'Content-Type' => response['content-type'],
+					'Object-ID'    => response['Object-ID'],
+					'Content-ID'   => response['Content-ID']
+				}
+				
+				if response['Content-Length'].to_i > 100
+					data_object = DataObject.new(info, response.body)
+				
+					if block_given?
+						yield data_object
+						results += 1
+					else
+						results << data_object
+					end
+				end
+			end
+			
+			results
+		end
+		
+		# Peforms a RETS search transaction. Again, please see the RETS specification for details
+		# on what these parameters mean. The options parameter takes a hash of options that will
+		# added to the search statement.
+		def search(search_type, klass, query, options = false)
+			header = {}
+		
+			# Required Data
+			data = {
+				'SearchType' => search_type,
+				'Class'      => klass,
+				'Query'      => query,
+				'QueryType'  => 'DMQL2',
+				'Format'     => 'COMPACT',
+				'Count'      => '0'
+			}
+			
+			# Options
+			#--
+			# We might want to switch this to merge!, but I've kept it like this for now because it
+			# explicitly casts each value as a string prior to performing the search, so we find out now
+			# if can't force a value into the string context. I suppose it doesn't really matter when
+			# that happens, though...
+			#++
+			options.each { |k,v| data[k] = v.to_s } if options
+			
+			response = request(@urls['Search'], data, header)
+			
+			results = self.parse(response.body)
+			
+			if block_given?
+				yield results
+			else
+				return results
+			end
+		end
+		
+		private
+	
+		def process_content_type(text)
+			content = {}
+			
+			field_start = text.index(';')
+
+			content['content-type'] = text[0 ... field_start].strip
+			fields = text[field_start..-1]
+			
+			parts = text.split(';')
+			
+			parts.each do |part|
+				(name, value) = part.split('=')
+				
+				content[name.strip] = value ? value.strip : value
+			end
+			
+			content
+		end
+		
+		# Processes the HTTP header
+		#-- 
+		# Could we switch over to using CGI for this?
+		#++
+		def process_header(raw)
+			header = {}
+			
+			raw.each do |line|
+				(name, value) = line.split(':')
+				
+				header[name.strip] = value.strip if name && value
+			end
+			
+			header
+		end
+		
+		# Given a hash, it returns a URL encoded query string.
+		def create_query_string(hash)
+			parts = hash.map {|key,value| "#{CGI.escape(key)}=#{CGI.escape(value)}"}
+			return parts.join('&')
+		end
+		
+		# This is the primary transaction method, which the other public methods make use of.
+		# Given a url for the transaction (endpoint) it makes a request to the RETS server.
+		# 
+		#-- 
+		# This needs to be better documented, but for now please see the public transaction methods
+		# for how to make use of this method.
+		#++
+		def request(url, data = {}, header = {}, method = @request_method, retry_auth = DEFAULT_RETRY)
+			response = ''
+			
+			@semaphore.lock
+			
+			http = Net::HTTP.new(url.host, url.port)
+			
+			if logger && logger.debug?
+				http.set_debug_output HTTPDebugLogger.new(logger)
+			end
+			
+			http.start do |http|
+				begin
+					uri = url.path
+					
+					if ! data.empty? && method == METHOD_GET
+						uri += "?#{create_query_string(data)}"
+					end
+
+					headers = @headers
+					headers.merge(header) unless header.empty?
+					
+					logger.debug(headers.inspect) if logger
+					
+					@semaphore.unlock
+										
+					response = http.get(uri, headers)
+										
+					@semaphore.lock
+					
+					if response.code == '401'
+						# Authentication is required
+						raise AuthRequired
+					else
+						cookies = []
+						if set_cookies = response.get_fields('set-cookie') then
+							set_cookies.each do |cookie|
+								cookies << cookie.split(";").first
+							end
+						end
+						set_header('Cookie', cookies.join("; ")) unless cookies.empty?
+						set_header('RETS-Session-ID', response['RETS-Session-ID']) if response['RETS-Session-ID']
+					end
+				rescue AuthRequired
+					@nc += 1
+
+					if retry_auth > 0
+						retry_auth -= 1
+						set_header('Authorization', Auth.authenticate(response, @username, @password, url.path, method, @headers['RETS-Request-ID'], get_user_agent, @nc))
+						retry
+					end
+				end		
+				
+				logger.debug(response.body) if logger
+			end
+			
+			@semaphore.unlock if @semaphore.locked?
+			
+			return response
+		end
+		
+		# If an action URL is present in the URL capability list, it calls that action URL and returns the
+		# raw result. Throws a generic RETSException if it is unable to follow the URL.
+		def perform_action_url
+			begin
+				if @urls.has_key?('Action')
+					return request(@urls['Action'], {}, {}, METHOD_GET)
+				end
+			rescue
+				raise RETSException.new("Unable to follow action URL: '#{$!}'.")
+			end
+		end
+		
+		# Provides a proxy class to allow for net/http to log its debug to the logger.
+		class HTTPDebugLogger
+			def initialize(logger)
+				@logger = logger
+			end
+			
+			def <<(data)
+				@logger.debug(data)
+			end
+		end
+		
+		#### Exceptions ####
+		
+		# This exception should be thrown when a generic client error is encountered.
+		class ClientException < Exception
+		end
+		
+		# This exception should be thrown when there is an error with the parser, which is 
+		# considered a subcomponent of the RETS client. It also includes the XML data that
+		# that was being processed at the time of the exception.
+		class ParserException < ClientException
+			attr_accessor :file
+		end
+		
+		# The client does not currently support a specified action.
+		class Unsupported < ClientException
+		end
+		
+		# A general RETS level exception was encountered. This would include HTTP and RETS 
+		# specification level errors as well as informative mishaps such as authentication being
+		# required for access.
+		class RETSException < Exception
+		end
+		
+		# There was a problem with logging into the RETS server.
+		class LoginError < RETSException
+		end
+		
+		# For internal client use only, it is thrown when the a RETS request is made but a password
+		# is prompted for.
+		class AuthRequired < RETSException
+		end
+	end
+end