NAR RETS Reference Implementation

Users Guide

      

Version <1.1>

 

 


Revision History

Date

Version

Description

Author

01/03/2001

1.0

<details>

Tom Weber

12/06/2002

1.1

Updated for RETS 1.5

Paula O’Brien

 

 

 

 

 

 

 

 

 


Table of Contents

1.     System Requirements                                                                                                                                                              4

1.1      Hardware/Operating System Requirements                                                                                                            4

1.2      Software Requirements                                                                                                                                               4

2.     Installing the Reference Implementation                                                                                                                              4

3.     Starting the Server                                                                                                                                                                   5

4.     Using the Client                                                                                                                                                                        5

4.1      Login                                                                                                                                                                             5

4.2      Search                                                                                                                                                                            6

4.2.1    Property Search                                                                                                                                                  6

4.2.2    Agent Search                                                                                                                                                    11

4.2.3    Office Search                                                                                                                                                    14

4.3      Monitor                                                                                                                                                                       17

4.4      Misc                                                                                                                                                                             18

4.4.1    View Metadata                                                                                                                                                 18

4.5      JavaDoc                                                                                                                                                                      19

5.     Appendix A -- Software License Information                                                                                                                    20


RETS Reference Implementation Users Guide

 

A publicly available install of the RETS Reference Implementation site can be accessed at the following URL : http://rets.avantia-inc.com

1.     System Requirements

1.1     Hardware/Operating System Requirements

The Reference Implementation of RETS 1.5 has been tested on Windows 2000 and RedHat Linux 7.2 and 8.0.  A minimum of 400 Mhz processor and 128 Megabytes of system memory is suggested.   100 Megabytes of disk space should be plenty.

1.2     Software Requirements

All of the software used to develop and deploy the RETS 1.5 reference implementation is either Open Source or freely available.  The License Information section has links to details of each of the piece of software used.  If you have the reference implementation CD, all required software will be provided on the CD.

·         Java JDK 1.2 or greater.

·         A Java application server that supports version 2.2 or better of the Java Servlet Specification  and 1.1 or better of the Java Server Pages Specification.  The Reference Implementation was developed and tested using Apache Tomcat/4.1.12.  These installation instructions assume Apache Tomcat version 4.1.12 is the Servlet/JSP Engine used.  Tomcat can downloaded from the Apache Jakarta site: http://jakarta.apache.org/tomcat/index.html

·         A Jakarta Ant build script supplied with the Reference Implementation.  Ant is not required but it makes things much easier.  Make sure to setup the environment variables “ANT_HOME” and “JAVA_HOME”. Ant can be downloaded from the Apache Jakarta site: http://jakarta.apache.org/ant/

·         MySQL is used as the database engine.  Version 3.23.52 of MySQL was used in development and testing of the Reference Implementation but later versions should work as well.  MySQL can be downloaded from the following site: http://www.mysql.com/

2.     Installing the Reference Implementation

Install the all software listed in the Software Requirements section.

Download the “rets15Reference.zip” from www.rets-wg.org.  Extract rets15Reference.zip to a directory of your choice. 

Install the data for the Reference implementation:

Start the MySQL server

Change directory to  <MySQL_install_directory>\bin

Issue the following command:

   mysql < ${rets_install_directory}\rets\data\RETS\rets15DB.dmp

 

·         Copy the following jar files to <TOMCAT_HOME>\common\endorsed:

${rets_install_directory}\lib\jakarta-regexp-1.2.jar

${rets_install_directory}\lib\BZip2.jar

${rets_install_directory}\lib\jakarta-regexp-1.2.jar

${rets_install_directory}\lib\log4j.jar

${rets_install_directory}\lib\mm.mysql-2.0.7-bin.jar

${rets_install_directory}\lib\xercesImpl.jar

${rets_install_directory}\lib\xmlParserAPIs.jar

·         In the file, <rets_install_directory>\build\rets.properties, set the “TOMCAT_HOME” property to the directory where Tomcat is installed.

·         Configure the MySQL JDBC connection by modifying the “rets.DATABASE_URL” property in the file <rets_install_directory>\web\RETSDBConnection.properties”.  If MySQL is running on the same machine as Tomcat, this file does not need to change.

Change directory to “<rets_install_directory>\build and type “ant deploy”.  The “build.xml” ant script will build the java source, build the javadocs, create the web archive “rets.war” and deploy rets.war to <TOMCAT_HOME>/webapps directory. The RETS server and client will be deployed the next time Tomcat is started.

3.     Starting the Server

Starting Tomcat should start the RETS Server if everything is installed properly.  The MySQL server must be running to use the RETS Server.

4.     Using the Client

The RETS client is implemented as an HTML application. Start by connecting to http://localhost:8080/rets/RETS.htm assuming Tomcat is installed on the local machine. A copy of the Reference Implementation is running at the following address: http://rets.avantia-inc.com. Figure 1 shows the menu for the RETS Client along the left side and the Login form to the right.  The menu is separated into five sections: Login, Search, Monitor, Misc and JavaDoc.  

4.1     Login

The login page is displayed by default or by selecting “Login” from the menu.  The login page as seen in figure 1 has 3 fields.  The “Server URL” field is for the URL of the RETS Server and defaults to “http://localhost:8080/rets/server/login”.    You can also use the RETS Client to connect to other RETS Servers.  Just change the “Server URL” from  the default to the URL of the RETS Server you wish to connect to.  You will need to know the Username and Password for that server, and also which version of RETS—1.0 or 1.5---the server supports. 

 

The Username field is used for the login id of the user and defaults to a valid id for the reference implementation.  The password field is used for the users password, in the reference implementation the password is not set for any user. Just type in a valid Username and leave the Password blank. 

 

RETS Version tells the server  which RETS version you wish to use:  RETS 1.0 or the new RETS 1.5 version.  The RETS Reference Implementation supports backward compatibility for all 1.* releases.  See the RETS 1.5 specification at http://www.rets-wg.org to understand the differences between these two releases. 

 

When the submit button is selected on the login page the RETS client attempts to establish a connection to the RETS Server identified by the “Server URL” field and send a login transaction. The results of the login transaction are displayed in a text box on the web browser.

 

Selecting logout from the menu sends a logout transaction the server.

 

Once you have successfully logged in, you will notice that the RETS Client displays a “Transaction time” for each transaction.  This measures the time, in seconds, that it takes for the Client request and Server response to execute.  You can use the transaction times to test the performance of various transactions against an expected benchmark.  (NOTE:  the transaction time does not include any formatting done by the Client after receiving a response from the Server, such as table formatting performed by the Client for display purposes in this implementation.)

Figure 1 RETS Client login page

 

4.2     Search

The Reference Implementation supports Property, Agent and Office searches.

 

4.2.1     Property Search

 

Selecting “Property” from the menu brings up the Property Search page as seen in Figure 2.  The “Property DMQL Query” field allows the entry of a DMQL query.  The “Property DMQL Query” field is populated with a valid DMQL query by default.

 

The Query Type dropdown allows you to select which version of DMQL you wish to use.  If you are requesting data from  a RETS 1.0 server, you must select DMQL.  If you are requesting data from a RETS 1.5 server, you must select DMQL2.

 

The Class field represents the type of Property you are searching for.  Property classes supported by RETS are: RES, MUL, LND, RENT, and COM.  The Reference Implementation only contains data for residential (RES) properties.  If you are requesting data from a different RETS Server, you can use the “View Metadata” transaction to find out what types of  properties that server supports and enter that data in this field.

 

There are Optional Parameters you may wish to include in your query.

 

“Selected Fields” allows you to select a subset of fields to be returned, instead of returning all fields available for a listing.  You may type these fields in a comma-separated list.  If you leave this field blank, all available fields will be returned.

 

 “Compression Type”  will only work if the RETS Server you are requesting data from supports compression.  The RETS Reference Implementation Server supports two types of compression:  GZIP and BZIP.    Compression is very useful if you have requested data in an XML format.

 

“Name Space” will allow you to choose to request and return data using either System Names (names unique to the database on the RETS Server) or Standard Names (a selection of standard field names defined by the RETS specification).

 

“Format” allows you to choose whether you want your data returned as Compact, Compact-Decoded or Standard XML. 

 

“Count” will provide you with a count of the number of records being returned from your search.  You can choose to have No record count returned, Include record count with data, or Only record count returned.  This last option returns only the number of records which met your search criteria, but not the records themselves. 

 

“Limit Records returned” allows you to set the number of records you wish to returned from your query.  If you wish to return ALL  records that match your search criteria, type NONE in this field.

 

“Offset” allows you to get a record set that begins with a record other than the first.  For example, if you set your offset to “20”, you can get the record set back beginning with the 20th record.  Leaving this field blank will default to a record set that begins with the first record.

 

Some servers have fields that are restricted, and you will be unable to view these fields when they are sent as part of your record.  Normally these fields will be sent as null (or empty) values.  “Restricted Indicator”  allows you to type in another value for restricted fields.  For example, you may choose “xxxx”, and any field that is restricted will be returned with a value of  “xxxx” instead of the default null.

 

Once you have entered all your search criteria,  selecting  the “Submit” button sends to the RETS Server  a property search transaction based on the DMQL and options entered.

 

Figure 2 Property Search Page

 

Figure 3 shows the response page for a Search Property Transaction.  At the top of the page is the text of the Response status in this case “searchProperty Successful”.    The response data is shown in both table format and the raw XML in a textbox below the table.  The RETS Client also exercises a GetObject transaction every time a Property Search is performed.  You can view this image by selecting the “Photo” hyperlink for a particular listing.

 

The table near the top of the page is generated using XSLT from the XML data displayed in the textbox.  The table contains four hyperlinks for each record, shown as blue underlined text.  Selecting a  hyperlink will send an additional search transaction to the RETS Server.  Selecting the  hyperlink in the “Listing Agent ID” column performs a Search Agent Transaction for the agent whose license number  matches the selected Listing Agent ID.  Selecting the hyperlink in the “City” column performs a Search Property Transaction for all listings in the selected city.  Selecting the hyperlink in the Zip column performs a Search  Property Transaction for  listings in the selected zip code.

 

If you have selected a Compact or Compact-Decoded format, the resulting table will be slightly different and not contain any hyperlinks or photo images. Figure 3 shows the response page for a Search Property Transaction in Compact format.

 

Figure 3 Search Property Response Page, Compact Format

 

 

 Figure 4 shows the response page for a Search Property Transaction in Standard XML format.

 

Figure 4 Search Property Response Page, Standard XML Format

 

 

 

4.2.2     Agent Search

Selecting “Agent” search brings up the Search Agent page seen in Figure 5.  This page is used to send an Agent search to the RETS Server.  The “Search by Agent Last Name” field defaults to a valid Last Name for the Reference Implementation.

 

The Optional Parameters for Agent Search are the same as those used in the Property Search.

 

Figure 5 Search Agent page

 

Figure 5 shows the Search Agent reply page.  The status is displayed at the top, formatted response text is displayed in an HTML table and the raw XML is displayed in a textbox at the bottom part of the page.  There are two columns which contain hyperlinks that will allow you to perform additional transactions.  Selecting the  hyperlink in the “Name” column of the HTML table will perform a Search Property Transaction for all properties where the selected agent is the listing agent.  Selecting the  hyperlink in the “Office ID” column will perform a Search Office Transaction where the office ID is equal to the selected id.

 

Figure 6 Search Agent Response page, Standard XML

 

If you selected Compact or Compact-Decoded as your Format, your response page will contain a slightly different table, seen in Figure 7.  There are no hyperlinks available in the Compact view.

 

Figure 7 Search Agent Response page, Compact Format

4.2.3     Office Search

Selecting the “Office” search brings up the Office Search page shown in Figure 8.  The “Search Office DMQL Query” field defaults to a valid DMQL query.  The Optional Parameters for Office Search are the same as those used in the Property and Agent Searches.

 

 

A Search Office Transaction is sent to the RETS Server when the Submit button is selected.

 

Figure 8 Search Office page

 

Figure 9 shows the Search Office Response page in Standard XML Format.  The status is displayed at the top of the page, formatted response text is displayed in an HTML table and the raw XML is displayed in a textbox at the bottom part of the page.  Selecting the hyperlink in the “Name” column of the HTML table will perform a Search Agent Transaction for all Agents at the selected office.

 

Figure 9 Search Office Response page, Standard XML Format

 

If you selected Compact or Compact-Decoded as your Format, your response page will contain a slightly different table, seen in Figure 10.  There are no hyperlinks available in the Compact view.

 

Figure 10  Search Office Response page, Compact Format

 

 

 

4.3     Monitor

Selecting the “Client Monitor” opens a new browser window, the contents of the RETS Client log file is streamed to the window.  The “Server Monitor” also opens in a new window and the contents of the RETS Server log file is streamed to the window.  Figure 11 shows a sample Server Monitor window.

 

Figure 11 Server Monitor window

 

 

 

4.4     Misc

4.4.1     View Metadata

Selecting “View Metadata” brings up the View Metadata page shown in Figure 9.

The Type dropdown box identifies the type of Metadata to be retrieved. The ID field identifies the resource followed by the class, separated by a ‘:’.(see Real Estate Data Interchange Standard: Real Estate Transaction Specification Version 1.5 Section 11.) A GetMetadata Transaction is sent to the RETS Server when the Submit button is selected.  The only format supported by the Reference Implementation Server is Standard-XML. 

 

Figure 12 View Metadata Page


 

Figure 13 shows the View Metadata reply page.  The status is displayed at the top and the raw XML is displayed in a textbox at the bottom part of the page.

 

Figure 13 GetMetadata Response Page

 

If you request Metadata from a different server that does not support Standard –XML, the Compact metadata will be returned.

 

4.5     JavaDoc

Selecting JavaDoc opens a new window with links to documentation for all classes in the RETS 1.5 reference implementation.

 


5.     Appendix A -- Software License Information

 

All software used in the development of the RETS 1.5 Reference Implementation is Open Source or freely available. License information for each product used can be found at the following links:

 

Apache License Information: http://www.apache.org/LICENSE.txt

Ant License Information:  http://jakarta.apache.org/ant/manual/index.html

Tomcat License Information:  http://www.apache.org/licenses/LICENSE

MySQL/LGPL license information (JDBC are licensed under LGPL as well): http://www.mysql.com/documentation/mysql++/D_Copyright.html