Getting Objects
There are three methods on RETSUserSession for retrieving object information or the objects themselves, such as photos.
/**
* Get the URL location for a single object such as a photo.
*/
public ObjectRecord getObjectUrl(String objectPathId)
/**
* Get the URL locations for multiple objects.
*/
public List<ObjectRecord> getObjectUrls(String objectPath)
/**
* Fetch and save objects for records. The method takes a directory and all
* objects returned will be saved to that directory.
*/
public List<ObjectRecord> getObjects(String objectPath, File directory);
The first two methods return object information pertaining to the URL location of the objects. The objects themselves are not downloaded. The ObjectRecord beans returned provide the URL location of the queried objects.
The third method downloads the actual objects and stores them to the directory specified in the method call. Objects are saved with a filename in the following format <RecordID>-<ObjectID>[.<FileExtension>]. The file extension is determined by the MIME type. If there is no mapping to the MIME type for an extension then it is possible to register an extension for the MIME type.
Fetching An Object URL
To fetch a single URL for an object, use the getObjectUrl() method. This will return a single ObjectRecord if successful containing the URL to the object.
The objectPathId should target a single object id. The format of the objectPathId is /<Resource>/<Type>/<RecordID>:<ObjectID>. For example /Property/Photo/123456:1 will request the 1st photo for property listing with the MLS number 123456.
String loginurl = "http://rets.server.com/rets/login";
String username = "username";
String password = "password";
String objectPathId = "/Property/Photo/123456:1";
// Create the connection class
RETSConnection connection = new RETSConnection(loginurl);
// Authenticate the user and get session
RETSUserSession session = connection.getSession(username, password);
// Get the url to the object
ObjectRecord object = session.getObjectUrl(objectPathId);
if(object != null) {
System.out.println("Type: " + object.getMimeType());
System.out.println("Content ID: " + object.getContentId());
System.out.println("Object ID: " + object.getObjectId());
System.out.println("URL: " + object.getUri());
}
// Logout from the session
session.logout();
Fetching A Collection Of Object URLs
To fetch a collection of URLs, use the getObjectUrls() method. This will return a list of ObjectRecord of available objects.
String loginurl = "http://rets.server.com/rets/login";
String username = "username";
String password = "password";
String objectPath = "/Property/Photo/123456:*";
// Create the connection class
RETSConnection connection = new RETSConnection(loginurl);
// Authenticate the user and get session
RETSUserSession session = connection.getSession(username, password);
// Get the url to the object
List<ObjectRecord> object = session.getObjectUrls(objectPath);
for(ObjectRecord object: objects) {
System.out.println("Type: " + object.getMimeType());
System.out.println("Content ID: " + object.getContentId());
System.out.println("Object ID: " + object.getObjectId());
System.out.println("URL: " + object.getUri());
}
// Logout from the session
session.logout();
Requesting Objects
To fetch the actual objects, use the getObjects() method. This will return a list of ObjectRecord of objects that will contain the location the file was saved to.
The method takes a directory to write the files to. Files are saved with a filename in the following format <RecordID>-<ObjectID>[.<FileExtension>].
If errors occur a file will be created with the error detailed in the file.
String loginurl = "http://rets.server.com/rets/login";
String username = "username";
String password = "password";
String objectPath = "/Property/Photo/123456:*";
File directory = new File("/tmp");
// Create the connection class
RETSConnection connection = new RETSConnection(loginurl);
// Authenticate the user and get session
RETSUserSession session = connection.getSession(username, password);
// Get the the object and store them in directory.
List<ObjectRecord> object = session.getObjects(objectPath, directory);
for(ObjectRecord object: objects) {
System.out.println("Type: " + object.getMimeType());
System.out.println("Content ID: " + object.getContentId());
System.out.println("Object ID: " + object.getObjectId());
System.out.println("File: " + object.getUri());
}
// Logout from the session
session.logout();
A Brief Overview Of Object Paths
The object path should be in the following format /<Resource>/<Type>/<ID>.
The RETS specification defines the parts as follows:
Resource - A resource defined in the metadata dictionary. The resource from which the object should be retrieved is specified by this entry.
Type The object type as defined in the metadata. The grouping category to which the object belongs. Type MUST be an ObjectType defined in the Object metadata for this Resource.
ID - A string identifying the object or objects being requested.
ID ::= resource-set *( , resource-set)
resource-set ::= resource-entity [ : object-id-list ]
resource-entity ::= 1*ALPHANUM
object-id-list ::= * | object-id *( : object-id)
object-id ::= 1*DIGIT
For objects, the resource-entity is a value (e.g., MLS number, AgentID) from the KeyField of the Resource for which the object is to be retrieved. The object-id is the particular object to be retrieved. Objects are assumed to be stored sequentially on the host beginning with an object-id of "1". If the object-id is 0 (zero or not provided), the designated preferred object of the given type is returned. If the objectid is set to "*" then all objects corresponding to the resource-entity are returned. This parameter can be used to specify the photo number, e.g. a value of "3" would indicate photo number 3.
This means that objects can be retrieved, assuming a resource of Property and a type of Photo in the following manner:
/Property/Photo/123456:1 - Return the 1st photo for resource property with MLS number 123456.
/Property/Photo/123456:1:2 - Return the 1st and 2nd photo for resource property with MLS number 123456.
/Property/Photo/123456:* - Return all the photos for resource property with MLS number 123456.
/Property/Photo/123456:*,12347:1:2 - Return all the photos for resource property with MLS number 123456 and the first and second of property with MLS number 123457.
Examples
The GetObjectUrls example to demonstrates how to get URL locations for objects. The example performs a search limited to 3 records and then fetches all the URLS for all the photos associated with those records.
The GetObject example demonstrates how to get object such as photos for a record. The example performs a search limited to 3 records and then fetches all the the photos associated with those records.
The objects are output to the specified directory with the content ID and object ID as the filename.
