Getting Objects

There are multiple methods available on RETSUserSession for retrieving object information or the objects themselves, such as photos. Each method comes in two variants, the first using traditional RETS Object paths, the second using RETS Object paths that specify objects by their UID (RETS 1.8 only).

  /**
   * Get the URL location for a single object such as a photo.
   */
  public ObjectRecord getObjectUrl(String objectPathId) 
  public ObjectRecord getObjectUrlByUID(String objectPathId) 

  /**
   * Get the URL locations for multiple objects.
   */
  public List<ObjectRecord> getObjectUrls(String objectPath)
  public List<ObjectRecord> getObjectUrlsByUID(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);
  public List<ObjectRecord> getObjectsByUID(String objectPath, File directory);

  /*
   * Fetch objects specified by objectPath, calling the response handler for
   * each retrieved object.
   */
  public List<ObjectRecord> getObjects(String objectPath, ObjectResponseHandler handler);
  public List<ObjectRecord> getObjectsByUID(String objectPath, ObjectResponseHandler handler);
    		  

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 remaining methods download the object content and either store them in a directory on the local filesystem, or call a user implemented ObjectResponseHandler allowing customised behaviour. The file extension of the saved object is determined by the MIME type specified by the server for the object. 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.

UID Object Paths (RETS 1.8)

For the get object methods with the suffix byUID, the object path is specified as follows /<Resource>/<Type>/<UID>,[<UID>,...]

Resource and type are interpreted as described in the previous section. The UID or UIDs in the final part of the path are used to retrieve specific objects identified by their UID as returned by a previous RETS GetObject call or some other method. This feature is only available when using RETS 1.8, and only if the server supports GetObject by UID.

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.

See the example.

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.

See the example.