Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.bigllc.retsiq.simpleclient
Class RETSUserSession

java.lang.Object
  extended by com.bigllc.retsiq.simpleclient.RETSUserSession
All Implemented Interfaces:
java.io.Closeable
public class RETSUserSession
extends java.lang.Object
implements java.io.Closeable

A user session for an authenticated user. The session allows interaction with the RETS Server such as searches, updates and object retrieval.

To create a RETSUserSession use the a RETSConnection class to configure the server and authenticate a user.

     RETSConnection connection = new RETSConnection("http://myretserver.com");
     RETSUserSession session = connection.getSession("username", "password");
     session.logout();

Object Paths For GetObject Transactions

The RETS GetObject transaction calls take object path identifiers in the format /<Resource>/<ObjectType>/<RecordId>:(*|ObjectId-List)[,<RecordId>:(*|ObjectId-List),...]. Resource is the RETS resource system name, ObjectType is the object type name, and RecordID is the key field value of the record for which objects are being retrieved and is followed by either a wildcard (*) or a list of integer object identifiers specifying the objects that are to be retrieved.

Examples of object paths:

For GetObject methods with the suffix byUID, the object path format is of the format /<Resource>/<ObjectType>/<UID>[,<UID>,...] where the UID specifies specific objects to retrieve.

Examples of UID object paths:

Object Paths For PostObject Transactions

The RETS PostObject transaction calls (add/delete/replace object) take object paths that specify the record ID only, passing the object identifier to operate on as a separate method paramater. That is, the :(*|ObjectId-List) component present in GetObject paths is omitted from the path, and only a single integer object identifier is passed to the method. UID paths are specified in the same manner as Get Object paths, but only a single UID is permitted in the last path component.

Author:
Marc G. Smith, Michael Watt

Nested Class Summary
static class RETSUserSession.MetadataLevel
          Enumerated type for determining the level of metadata to load.
 
Field Summary
static int NO_LIMIT
          Magic number for notifying the server that the search limit should be overridden.
static int VALIDATEFLAG_AUTOPOP
          Magic number for sending an update to auto populate the record.
static int VALIDATEFLAG_UPDATE
          Magic number for sending an update that will be written to database if valid.
static int VALIDATEFLAG_VALIDATE
          Magic number for sending an update to validate but no write the record.
 
Method Summary
 void action()
          Action request.
 PostObjectResponse addObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes)
          Add an object for a record.
 PostObjectResponse addObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          Add an object for a record.
 PostObjectResponse addObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes)
          This version of addObject() explicitly takes an content stream, content length, and content type.
 PostObjectResponse addObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          This version of addObject() explicitly takes an content stream, content length, and content type.
 PostObjectResponse addObjectByUID(java.lang.String objectPath, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes)
          Add an object for a record.
 PostObjectResponse addObjectByUID(java.lang.String objectPath, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          Add an object for a record.
 PostObjectResponse addObjectByUID(java.lang.String objectPath, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes)
          This version of addObjectByUID() explicitly takes an content stream, content length, and content type.
 PostObjectResponse addObjectByUID(java.lang.String objectPath, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          This version of addObjectByUID() explicitly takes an content stream, content length, and content type.
 UpdateResponse beginUpdate(java.lang.String classPath, java.util.Map<java.lang.String,java.lang.String> record, int lockTime, java.lang.String lockKey)
          Get a lock on a record before updating.
 UpdateResponse cancelUpdate(java.lang.String classPath, java.util.Map<java.lang.String,java.lang.String> record, java.lang.String lockKey)
          Get a lock on a record before updating.
 void close()
          Alias for logout so that the Closeable interface can be used.
 PostObjectResponse deleteObject(java.lang.String objectPath, java.lang.Integer objectId)
          Delete an object for a record.
 PostObjectResponse deleteObject(java.lang.String objectPath, java.lang.Integer objectId, java.util.List<WarningResponse> warningResponse)
          Delete an object for a record.
 PostObjectResponse deleteObjectByUID(java.lang.String objectPath)
          Delete an object for a record.
 PostObjectResponse deleteObjectByUID(java.lang.String objectPath, java.util.List<WarningResponse> warningResponse)
          Delete an object for a record.
 java.lang.String getAgentCode()
          Get the agent code.
 java.lang.String getBrokerKey()
          Get the broker key.
 java.lang.String getMemberName()
          Get the member name.
 MetadataSystem getMetadata()
          Fetch the complete Standard XML metadata and load it into the Metadata in memory model.
 MetadataSystem getMetadata(boolean everything)
          Fetch XML metadata from the server.
 void getMetadata(java.io.OutputStream out)
          Fetch the complete Standard XML metadata and write to the stream supplied.
 void getMetadata(java.io.OutputStream out, boolean everything)
          Fetch system metadata from the server.
 MetadataSystem getMetadata(RETSUserSession.MetadataLevel level)
          Fetch XML metadata from the server.
 java.util.List<ObjectRecord> getObjects(java.lang.String objectPath, java.io.File directory)
          Fetch and save objects for records identified by ResourceID:ObjectID pairs.
 java.util.List<ObjectRecord> getObjects(java.lang.String objectPath, ObjectResponseHandler handler)
          Fetch and save objects for records identified by their ResourceID:ObjectID pairs.
 java.util.List<ObjectRecord> getObjectsByUID(java.lang.String objectPath, java.io.File directory)
          Fetch and save objects for records identified by their UIDs.
 java.util.List<ObjectRecord> getObjectsByUID(java.lang.String objectPath, ObjectResponseHandler handler)
          Fetch and save objects for records identified by their object UIDs.
 ObjectRecord getObjectUrl(java.lang.String objectPathId)
          Get the URL location for a single object such as a photo identified by a ResourceID:ObjectID pair.
 ObjectRecord getObjectUrlByUID(java.lang.String objectPathId)
          Get the URL location for a single object such as a photo, identified by an object UID.
 java.util.List<ObjectRecord> getObjectUrls(java.lang.String objectPath)
          Get the URL locations for multiple objects, identified by ResourceID:ObjectID pairs.
 java.util.List<ObjectRecord> getObjectUrlsByUID(java.lang.String objectPath)
          Get the URL locations for multiple objects identified by their object UIDs.
 java.io.InputStream getPayload(java.lang.String path, java.lang.String payload, java.lang.String query, java.util.List<java.lang.String> orderby, int limit, int offset)
          Execute a search for a given payload which returns the input stream containing the paylod.
 java.util.List<PayloadDescriptor> getPayloadList()
          Get the payload list available from the server.
 int getRecordCount(java.lang.String path, java.lang.String query)
          Get the number of records that match a search query.
 com.bigllc.retsiq.api.http.RetsHttpSession getRetsHttpSession()
           
 java.lang.String getRetsVersion()
          Get the RETS version being used to talk to the server.
 java.lang.String getSessionId()
          Get the session id.
 java.lang.String getUserClassification()
          Get the user classification.
 java.lang.String getUserId()
          Get the user ID.
 int getUserLevel()
          Get the user level.
 void logout()
          Logout the session.
 PostObjectResponse replaceObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes)
          Replace an object for a record.
 PostObjectResponse replaceObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          Replace an object for a record.
 PostObjectResponse replaceObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes)
          This version of replaceObject() explicitly takes an content stream, content length, and content type.
 PostObjectResponse replaceObject(java.lang.String objectPath, java.lang.Integer objectId, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          This version of replaceObject() explicitly takes an content stream, content length, and content type.
 PostObjectResponse replaceObjectByUID(java.lang.String objectPath, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes)
          Replace an object for a record.
 PostObjectResponse replaceObjectByUID(java.lang.String objectPath, java.io.File file, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          Replace an object for a record.
 PostObjectResponse replaceObjectByUID(java.lang.String objectPath, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes)
          This version of replaceObjectByUID() explicitly takes an content stream, content length, and content type.
 PostObjectResponse replaceObjectByUID(java.lang.String objectPath, java.io.InputStream content, java.lang.String contentType, int contentLength, java.util.Map<java.lang.String,java.lang.String> attributes, java.util.List<WarningResponse> warningResponse)
          This version of replaceObjectByUID() explicitly takes an content stream, content length, and content type.
 SearchResultSet search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields)
          Execute a search with the default server limit imposed.
 SearchResultSet search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields, int limit, int offset)
          Execute a search.
 SearchResultSet search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields, int limit, int offset, boolean decoded)
          Execute a search.
 void search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields, int limit, int offset, boolean decoded, SearchResponseHandler out)
          Execute a search.
 void search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields, int limit, int offset, SearchResponseHandler out)
          Execute a search.
 SearchResultSet search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields, java.util.List<java.lang.String> orderby, int limit, int offset, boolean decoded)
          Execute a search, ordering the result by one or more fields, returning a SearchResultSet.
 void search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields, java.util.List<java.lang.String> orderby, int limit, int offset, boolean decoded, SearchResponseHandler out)
          Execute a search, ordering the result by one or more fields.
 void search(java.lang.String path, java.lang.String query, java.util.List<java.lang.String> fields, SearchResponseHandler out)
          Execute a search with the default server limit imposed.
 void setRequestRecordCount(boolean count)
          Set whether the search request demand the record count value.
 boolean shouldRequestRecordCount()
          Should the search request include the record count value.
 UpdateResponse update(java.lang.String updatePath, java.util.Map<java.lang.String,java.lang.String> record, int validate)
          Update a record.
 UpdateResponse update(java.lang.String updatePath, java.util.Map<java.lang.String,java.lang.String> record, int validate, java.util.List<java.lang.String> fields)
          Update a record.
 UpdateResponse update(java.lang.String updatePath, java.util.Map<java.lang.String,java.lang.String> record, int validate, java.util.List<java.lang.String> fields, java.lang.String lockKey, java.util.List<WarningResponse> warningResponse)
          Update a record.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_LIMIT

public static final int NO_LIMIT
Magic number for notifying the server that the search limit should be overridden. The server may or may not choose to honour this.

See Also:
Constant Field Values

VALIDATEFLAG_UPDATE

public static final int VALIDATEFLAG_UPDATE
Magic number for sending an update that will be written to database if valid.

See Also:
Constant Field Values

VALIDATEFLAG_AUTOPOP

public static final int VALIDATEFLAG_AUTOPOP
Magic number for sending an update to auto populate the record.

See Also:
Constant Field Values

VALIDATEFLAG_VALIDATE

public static final int VALIDATEFLAG_VALIDATE
Magic number for sending an update to validate but no write the record.

See Also:
Constant Field Values
Method Detail

getRetsHttpSession

public com.bigllc.retsiq.api.http.RetsHttpSession getRetsHttpSession()

shouldRequestRecordCount

public boolean shouldRequestRecordCount()
Should the search request include the record count value.

setRequestRecordCount

public void setRequestRecordCount(boolean count)
Set whether the search request demand the record count value. By default this is on but performance may be improved by setting this to false.

getBrokerKey

public java.lang.String getBrokerKey()
Get the broker key.

Returns:
the broker key

getSessionId

public java.lang.String getSessionId()
Get the session id.

Returns:
the session id

getMemberName

public java.lang.String getMemberName()
Get the member name.

Returns:
the member name

getAgentCode

public java.lang.String getAgentCode()
Get the agent code.

Returns:
the agent code

getUserClassification

public java.lang.String getUserClassification()
Get the user classification.

Returns:
the user classfication

getUserId

public java.lang.String getUserId()
Get the user ID.

Returns:
the user ID

getUserLevel

public int getUserLevel()
Get the user level.

Returns:
the user level

getRetsVersion

public java.lang.String getRetsVersion()
Get the RETS version being used to talk to the server.

Returns:
the RETS version returned by the server.

action

public void action()
            throws RETSClientException
Action request. The action request can be used to keep the session alive.

Throws:
RETSClientException

getPayloadList

public java.util.List<PayloadDescriptor> getPayloadList()
                                                 throws RETSClientException
Get the payload list available from the server.

Throws:
RETSClientException

search

public void search(java.lang.String path,
                   java.lang.String query,
                   java.util.List<java.lang.String> fields,
                   SearchResponseHandler out)
            throws RETSClientException
Execute a search with the default server limit imposed. If the server returns any status code other than success or no records found an exception will be thrown detailing the error.

Parameters:
path - the resource and classification to query in the following format - /<Resource>/<Classification>.
query - the DMQL2 query to execute.
fields - the fields to return, an empty list or null will fetch all the fields.
out - the handler to process the response.
Throws:
RETSClientException
See Also:
SearchResponseHandler, DelimitedSearchResponseHandler, RecordCollectionResponseHandler

search

public void search(java.lang.String path,
                   java.lang.String query,
                   java.util.List<java.lang.String> fields,
                   int limit,
                   int offset,
                   SearchResponseHandler out)
            throws RETSClientException
Execute a search. If the server returns any status code other than success or no records found an exception will be thrown detailing the error.

Parameters:
path - the resource and classification to query in the following format - /<Resource>/<Classification>.
query - the DMQL2 query to execute.
fields - the fields to return, an empty list or null will fetch all the fields.
limit - the number of records to limit the response to. The number 0 specifies the server limit if one exists
offset - the offset of the record the server should return. The first record is 0. Note that some servers may not honour this request.
out - the handler to process the response.
Throws:
RETSClientException
See Also:
SearchResponseHandler, DelimitedSearchResponseHandler, RecordCollectionResponseHandler

search

public void search(java.lang.String path,
                   java.lang.String query,
                   java.util.List<java.lang.String> fields,
                   int limit,
                   int offset,
                   boolean decoded,
                   SearchResponseHandler out)
            throws RETSClientException
Execute a search. If the server returns any status code other than success or no records found an exception will be thrown detailing the error.

Parameters:
path - the resource and classification to query in the following format - /<Resource>/<Classification>.
query - the DMQL2 query to execute.
fields - the fields to return, an empty list or null will fetch all the fields.
limit - the number of records to limit the response to. The number 0 specifies the server limit if one exists
offset - the offset of the record the server should return. The first record is 0. Note that some servers may not honour this request.
decoded - if true lookup values are decoded otherwise raw values are returned.
out - the handler to process the response.
Throws:
RETSClientException
See Also:
SearchResponseHandler, DelimitedSearchResponseHandler, RecordCollectionResponseHandler

search

public void search(java.lang.String path,
                   java.lang.String query,
                   java.util.List<java.lang.String> fields,
                   java.util.List<java.lang.String> orderby,
                   int limit,
                   int offset,
                   boolean decoded,
                   SearchResponseHandler out)
            throws RETSClientException
Execute a search, ordering the result by one or more fields.

Parameters:
orderby - The list of field names to order results by. If a field name is prefixed with '-', for example -LISTPRICE, results are sorted in descending order.
Throws:
RETSClientException
See Also:
search(String, String, List, int, int, boolean, SearchResponseHandler)

search

public SearchResultSet search(java.lang.String path,
                              java.lang.String query,
                              java.util.List<java.lang.String> fields)
                       throws RETSClientException
Execute a search with the default server limit imposed. If the server returns any status code other than success or no records found an exception will be thrown detailing the error.

Parameters:
path - the resource and classification to query in the following format - /<Resource>/<Classification>.
query - the DMQL2 query to execute.
fields - the fields to return, an empty list or null will fetch all the fields.
Returns:
the search result set
Throws:
RETSClientException
See Also:
SearchResponseHandler, DelimitedSearchResponseHandler, RecordCollectionResponseHandler

search

public SearchResultSet search(java.lang.String path,
                              java.lang.String query,
                              java.util.List<java.lang.String> fields,
                              int limit,
                              int offset)
                       throws RETSClientException
Execute a search. If the server returns any status code other than success or no records found an exception will be thrown detailing the error.

Parameters:
path - the resource and classification to query in the following format - /<Resource>/<Classification>.
query - the DMQL2 query to execute.
fields - the fields to return, an empty list or null will fetch all the fields.
limit - the number of records to limit the response to. The number 0 specifies the server limit if one exists
offset - the offset of the record the server should return. The first record is 0. Note that some servers may not honour this request.
Returns:
the search result set
Throws:
RETSClientException
See Also:
SearchResponseHandler, DelimitedSearchResponseHandler, RecordCollectionResponseHandler

search

public SearchResultSet search(java.lang.String path,
                              java.lang.String query,
                              java.util.List<java.lang.String> fields,
                              int limit,
                              int offset,
                              boolean decoded)
                       throws RETSClientException
Execute a search. If the server returns any status code other than success or no records found an exception will be thrown detailing the error.

Parameters:
path - the resource and classification to query in the following format - /<Resource>/<Classification>.
query - the DMQL2 query to execute.
fields - the fields to return, an empty list or null will fetch all the fields.
limit - the number of records to limit the response to. The number 0 specifies the server limit if one exists
offset - the offset of the record the server should return. The first record is 0. Note that some servers may not honour this request.
decoded - if true lookup values are decoded otherwise raw values are returned.
Returns:
the search result set
Throws:
RETSClientException
See Also:
SearchResponseHandler, DelimitedSearchResponseHandler, RecordCollectionResponseHandler

search

public SearchResultSet search(java.lang.String path,
                              java.lang.String query,
                              java.util.List<java.lang.String> fields,
                              java.util.List<java.lang.String> orderby,
                              int limit,
                              int offset,
                              boolean decoded)
                       throws RETSClientException
Execute a search, ordering the result by one or more fields, returning a SearchResultSet.

Parameters:
orderby - The list of field names to order results by. If a field name is prefixed with '-', for example -LISTPRICE, results are sorted in descending order.
Throws:
RETSClientException
See Also:
search(String, String, List, int, int, boolean)

getPayload

public java.io.InputStream getPayload(java.lang.String path,
                                      java.lang.String payload,
                                      java.lang.String query,
                                      java.util.List<java.lang.String> orderby,
                                      int limit,
                                      int offset)
                               throws RETSClientException
Execute a search for a given payload which returns the input stream containing the paylod.

Parameters:
path - the resource and classification to query in the following format - /<Resource>/<Classification>.
payload - the payload name as returned by getPayloadList.
query - the DMQL2 query to execute.
orderby - The list of field names to order results by. If a field name is prefixed with '-', for example -LISTPRICE, results are sorted in descending order.
limit - the number of records to limit the response to. The number 0 specifies the server limit if one exists
offset - the offset of the record the server should return. The first record is 0. Note that some servers may not honour this request.
Throws:
RETSClientException

getRecordCount

public int getRecordCount(java.lang.String path,
                          java.lang.String query)
                   throws RETSClientException
Get the number of records that match a search query.

Parameters:
path - the resource and classification to query in the following format: /<Resource>/<Classification>
query - the DMQL2 query to execute.
Returns:
the number of records that match the query.
Throws:
RETSClientException

getObjectUrl

public ObjectRecord getObjectUrl(java.lang.String objectPathId)
                          throws RETSClientException
Get the URL location for a single object such as a photo identified by a ResourceID:ObjectID pair.

Parameters:
objectPathId - the object path of object to retrieve the URL of.
Returns:
an object record with the object information or null if the object was not found.
Throws:
RETSClientException

getObjectUrlByUID

public ObjectRecord getObjectUrlByUID(java.lang.String objectPathId)
                               throws RETSClientException
Get the URL location for a single object such as a photo, identified by an object UID.

Parameters:
objectPathId - the UID object path of object to retrieve the URL of.
Returns:
an object record with the object information or null if the object was not found.
Throws:
RETSClientException

getObjectUrls

public java.util.List<ObjectRecord> getObjectUrls(java.lang.String objectPath)
                                           throws RETSClientException
Get the URL locations for multiple objects, identified by ResourceID:ObjectID pairs.

Parameters:
objectPath - the object path of objects to retrieve URLs for.
Returns:
a list of object records for the object path.
Throws:
RETSClientException

getObjectUrlsByUID

public java.util.List<ObjectRecord> getObjectUrlsByUID(java.lang.String objectPath)
                                                throws RETSClientException
Get the URL locations for multiple objects identified by their object UIDs.

Parameters:
objectPath - the UID object path of objects to retrieve URLs for.
Returns:
an list of object records for the object path.
Throws:
RETSClientException

getObjects

public java.util.List<ObjectRecord> getObjects(java.lang.String objectPath,
                                               java.io.File directory)
                                        throws RETSClientException
Fetch and save objects for records identified by ResourceID:ObjectID pairs. The method takes a directory and all objects returned will be saved to that directory with a filename of <RecordID>-<ObjectID>[.<FileExtension>]. The file extension is derived from the MIME type. If no match is found then there will be no extension. It is possible to register extensions with MIME types. If you want to do this then please get in touch ;)

Parameters:
objectPath - the object path of objects to retrieve.
directory - the directory to save the returned objects to.
Returns:
an list of object records for the object path.
Throws:
RETSClientException

getObjectsByUID

public java.util.List<ObjectRecord> getObjectsByUID(java.lang.String objectPath,
                                                    java.io.File directory)
                                             throws RETSClientException
Fetch and save objects for records identified by their UIDs. The method takes a directory and all objects returned will be saved to that directory with a filename of <RecordID>-<ObjectID>[.<FileExtension>]. The file extension is derived from the MIME type. If no match is found then there will be no extension. It is possible to register extensions with MIME types. If you want to do this then please get in touch ;)

Parameters:
objectPath - the UID object paths of objects to retrieve.
directory - the directory to save the returned objects to.
Returns:
a list of object records for the object path.
Throws:
RETSClientException

getObjects

public java.util.List<ObjectRecord> getObjects(java.lang.String objectPath,
                                               ObjectResponseHandler handler)
                                        throws RETSClientException
Fetch and save objects for records identified by their ResourceID:ObjectID pairs. The method takes a handler for allowing user controlled persistence of objects.

Parameters:
objectPath - the object paths of objects to retrieve.
handler - the handler responsible for persistence.
Returns:
a list of object records for the object path.
Throws:
RETSClientException

getObjectsByUID

public java.util.List<ObjectRecord> getObjectsByUID(java.lang.String objectPath,
                                                    ObjectResponseHandler handler)
                                             throws RETSClientException
Fetch and save objects for records identified by their object UIDs. The method takes a handler for allowing user controlled persistence of objects.

Parameters:
objectPath - the UID object paths of objects to retrieve.
handler - the handler responsible for persistence.
Returns:
an list of object records for the object path.
Throws:
RETSClientException

addObject

public PostObjectResponse addObject(java.lang.String objectPath,
                                    java.lang.Integer objectId,
                                    java.io.File file,
                                    java.util.Map<java.lang.String,java.lang.String> attributes)
                             throws RETSClientException
Add an object for a record. The object id may be null in which case it should be added as the last item.

Parameters:
objectPath - the object path of the object to operate on.
objectId - the sequential integer id
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
Returns:
the post object response
Throws:
RETSClientException

addObject

public PostObjectResponse addObject(java.lang.String objectPath,
                                    java.lang.Integer objectId,
                                    java.io.File file,
                                    java.util.Map<java.lang.String,java.lang.String> attributes,
                                    java.util.List<WarningResponse> warningResponse)
                             throws RETSClientException
Add an object for a record. The object id may be null in which case it should be added as the last item.

Parameters:
objectPath - the object path of the object to operate on.
objectId - the sequential integer id
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
warningResponse - the warning response if one is required
Returns:
the post object response
Throws:
RETSClientException

addObject

public PostObjectResponse addObject(java.lang.String objectPath,
                                    java.lang.Integer objectId,
                                    java.io.InputStream content,
                                    java.lang.String contentType,
                                    int contentLength,
                                    java.util.Map<java.lang.String,java.lang.String> attributes)
                             throws RETSClientException
This version of addObject() explicitly takes an content stream, content length, and content type. See addObject(String, Integer, File, Map).

Throws:
RETSClientException

addObject

public PostObjectResponse addObject(java.lang.String objectPath,
                                    java.lang.Integer objectId,
                                    java.io.InputStream content,
                                    java.lang.String contentType,
                                    int contentLength,
                                    java.util.Map<java.lang.String,java.lang.String> attributes,
                                    java.util.List<WarningResponse> warningResponse)
                             throws RETSClientException
This version of addObject() explicitly takes an content stream, content length, and content type. See addObject(String, Integer, File, Map).

Throws:
RETSClientException

addObjectByUID

public PostObjectResponse addObjectByUID(java.lang.String objectPath,
                                         java.io.File file,
                                         java.util.Map<java.lang.String,java.lang.String> attributes)
                                  throws RETSClientException
Add an object for a record. The object is inserted before the object with the specified UID.

Parameters:
objectPath - the object path of the object to operate on.
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
Returns:
the post object response
Throws:
RETSClientException

addObjectByUID

public PostObjectResponse addObjectByUID(java.lang.String objectPath,
                                         java.io.File file,
                                         java.util.Map<java.lang.String,java.lang.String> attributes,
                                         java.util.List<WarningResponse> warningResponse)
                                  throws RETSClientException
Add an object for a record. The object is inserted before the object with the specified UID.

Parameters:
objectPath - the object path of the object to operate on.
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
warningResponse - the warning response if one is required
Returns:
the post object response
Throws:
RETSClientException

addObjectByUID

public PostObjectResponse addObjectByUID(java.lang.String objectPath,
                                         java.io.InputStream content,
                                         java.lang.String contentType,
                                         int contentLength,
                                         java.util.Map<java.lang.String,java.lang.String> attributes)
                                  throws RETSClientException
This version of addObjectByUID() explicitly takes an content stream, content length, and content type. See addObjectByUID(String, File, Map);

Throws:
RETSClientException

addObjectByUID

public PostObjectResponse addObjectByUID(java.lang.String objectPath,
                                         java.io.InputStream content,
                                         java.lang.String contentType,
                                         int contentLength,
                                         java.util.Map<java.lang.String,java.lang.String> attributes,
                                         java.util.List<WarningResponse> warningResponse)
                                  throws RETSClientException
This version of addObjectByUID() explicitly takes an content stream, content length, and content type. See addObjectByUID(String, File, Map);

Throws:
RETSClientException

replaceObject

public PostObjectResponse replaceObject(java.lang.String objectPath,
                                        java.lang.Integer objectId,
                                        java.io.File file,
                                        java.util.Map<java.lang.String,java.lang.String> attributes)
                                 throws RETSClientException
Replace an object for a record.

Parameters:
objectPath - the object path of the object to operate on.
objectId - the sequential integer id
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
Returns:
the post object response
Throws:
RETSClientException

replaceObject

public PostObjectResponse replaceObject(java.lang.String objectPath,
                                        java.lang.Integer objectId,
                                        java.io.File file,
                                        java.util.Map<java.lang.String,java.lang.String> attributes,
                                        java.util.List<WarningResponse> warningResponse)
                                 throws RETSClientException
Replace an object for a record.

Parameters:
objectPath - the object path of the object to operate on.
objectId - the sequential integer id
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
warningResponse - the warning response if one is required
Returns:
the post object response
Throws:
RETSClientException

replaceObject

public PostObjectResponse replaceObject(java.lang.String objectPath,
                                        java.lang.Integer objectId,
                                        java.io.InputStream content,
                                        java.lang.String contentType,
                                        int contentLength,
                                        java.util.Map<java.lang.String,java.lang.String> attributes)
                                 throws RETSClientException
This version of replaceObject() explicitly takes an content stream, content length, and content type. See replaceObject(String, Integer, File, Map).

Throws:
RETSClientException

replaceObject

public PostObjectResponse replaceObject(java.lang.String objectPath,
                                        java.lang.Integer objectId,
                                        java.io.InputStream content,
                                        java.lang.String contentType,
                                        int contentLength,
                                        java.util.Map<java.lang.String,java.lang.String> attributes,
                                        java.util.List<WarningResponse> warningResponse)
                                 throws RETSClientException
This version of replaceObject() explicitly takes an content stream, content length, and content type. See replaceObject(String, Integer, File, Map).

Throws:
RETSClientException

replaceObjectByUID

public PostObjectResponse replaceObjectByUID(java.lang.String objectPath,
                                             java.io.File file,
                                             java.util.Map<java.lang.String,java.lang.String> attributes)
                                      throws RETSClientException
Replace an object for a record. The object replaces the object given by the specified UID.

Parameters:
objectPath - the object path of the object to operate on.
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
Returns:
the post object response
Throws:
RETSClientException

replaceObjectByUID

public PostObjectResponse replaceObjectByUID(java.lang.String objectPath,
                                             java.io.File file,
                                             java.util.Map<java.lang.String,java.lang.String> attributes,
                                             java.util.List<WarningResponse> warningResponse)
                                      throws RETSClientException
Replace an object for a record. The object replaces the object given by the specified UID.

Parameters:
objectPath - the object path of the object to operate on.
file - the the file to post
attributes - name-value pairs sent to the server which may be used to update the object record.
warningResponse - the warning response if one is required
Returns:
the post object response
Throws:
RETSClientException

replaceObjectByUID

public PostObjectResponse replaceObjectByUID(java.lang.String objectPath,
                                             java.io.InputStream content,
                                             java.lang.String contentType,
                                             int contentLength,
                                             java.util.Map<java.lang.String,java.lang.String> attributes)
                                      throws RETSClientException
This version of replaceObjectByUID() explicitly takes an content stream, content length, and content type. See replaceObjectByUID(String, File, Map);

Throws:
RETSClientException

replaceObjectByUID

public PostObjectResponse replaceObjectByUID(java.lang.String objectPath,
                                             java.io.InputStream content,
                                             java.lang.String contentType,
                                             int contentLength,
                                             java.util.Map<java.lang.String,java.lang.String> attributes,
                                             java.util.List<WarningResponse> warningResponse)
                                      throws RETSClientException
This version of replaceObjectByUID() explicitly takes an content stream, content length, and content type. See replaceObjectByUID(String, File, Map);

Throws:
RETSClientException

deleteObject

public PostObjectResponse deleteObject(java.lang.String objectPath,
                                       java.lang.Integer objectId)
                                throws RETSClientException
Delete an object for a record.

Parameters:
objectPath - the object path of the object to operate on.
objectId - the sequential integer id
Returns:
the post object response
Throws:
RETSClientException

deleteObject

public PostObjectResponse deleteObject(java.lang.String objectPath,
                                       java.lang.Integer objectId,
                                       java.util.List<WarningResponse> warningResponse)
                                throws RETSClientException
Delete an object for a record.

Parameters:
objectPath - the object path of the object to operate on.
objectId - the sequential integer id
warningResponse - the warning response if one is required
Returns:
the post object response
Throws:
RETSClientException

deleteObjectByUID

public PostObjectResponse deleteObjectByUID(java.lang.String objectPath)
                                     throws RETSClientException
Delete an object for a record. The object to be deleted is specified by object path, including UID.

Parameters:
objectPath - the object path of the object to operate on.
Returns:
the post object response
Throws:
RETSClientException

deleteObjectByUID

public PostObjectResponse deleteObjectByUID(java.lang.String objectPath,
                                            java.util.List<WarningResponse> warningResponse)
                                     throws RETSClientException
Delete an object for a record. The object to be deleted is specified by object path, including UID.

Parameters:
objectPath - the object path of the object to operate on.
warningResponse - the warning response if one is required
Returns:
the post object response
Throws:
RETSClientException

update

public UpdateResponse update(java.lang.String updatePath,
                             java.util.Map<java.lang.String,java.lang.String> record,
                             int validate)
                      throws RETSClientException
Update a record. The method will throw an exception for any return codes that are neither success or invalid parameter.

Parameters:
updatePath - the type of update to perform. The format is /<Resource>/<Classification>/<UpdateType>
e.g. /Property/Residential/Edit
record - a column value map of fields representing the record to be added or edited.
validate - false to try and execute the update, true to simply perfrom validation
Returns:
an update response object detailing any errors and the returned record
Throws:
RETSClientException

update

public UpdateResponse update(java.lang.String updatePath,
                             java.util.Map<java.lang.String,java.lang.String> record,
                             int validate,
                             java.util.List<java.lang.String> fields)
                      throws RETSClientException
Update a record. The method will throw an exception for any return codes that are neither success or invalid parameter.

Parameters:
updatePath - the type of update to perform. The format is /<Resource>/<Classification>/<UpdateType>
e.g. /Property/Residential/Edit
record - a column value map of fields representing the record to be added or edited.
validate - false to try and execute the update, true to simply perfrom validation
fields - the fields to return, an empty list or null will fetch all the fields.
Returns:
an update response object detailing any errors and the returned record
Throws:
RETSClientException

update

public UpdateResponse update(java.lang.String updatePath,
                             java.util.Map<java.lang.String,java.lang.String> record,
                             int validate,
                             java.util.List<java.lang.String> fields,
                             java.lang.String lockKey,
                             java.util.List<WarningResponse> warningResponse)
                      throws RETSClientException
Update a record. The method will throw an exception for any return codes that are neither success or invalid parameter.

Parameters:
updatePath - the type of update to perform. The format is /<Resource>/<Classification>/<UpdateType>
e.g. /Property/Residential/Edit
record - a column value map of fields representing the record to be added or edited.
validate - false to try and execute the update, true to simply perfrom validation
fields - the fields to return, an empty list or null will fetch all the fields.
lockKey - if the server supports locking and begin update returned a lock key then this needs to be sent. Otherwise it can be null.
warningResponse - if the server requires a warning response then submit this as per the specification format.
Returns:
an update response object detailing any errors and the returned record
Throws:
RETSClientException

beginUpdate

public UpdateResponse beginUpdate(java.lang.String classPath,
                                  java.util.Map<java.lang.String,java.lang.String> record,
                                  int lockTime,
                                  java.lang.String lockKey)
                           throws RETSClientException
Get a lock on a record before updating. This calls the update transaction with the BeginUpdate update type.

Parameters:
classPath - the type of update to perform. The format is /<Resource>/<Classification>
e.g. /Property/Residential
record - a column value map of fields representing the record to be added or edited.
lockTime - the lock time in seconds to request.
lockKey - the lock key must be supplied if the record is already locked and an extension to the lock time.
Returns:
an update response object detailing any errors and the returned record
Throws:
RETSClientException

cancelUpdate

public UpdateResponse cancelUpdate(java.lang.String classPath,
                                   java.util.Map<java.lang.String,java.lang.String> record,
                                   java.lang.String lockKey)
                            throws RETSClientException
Get a lock on a record before updating. This calls the update transaction with the BeginUpdate update type.

Parameters:
classPath - the type of update to perform. The format is /<Resource>/<Classification>
e.g. /Property/Residential
record - a column value map of fields representing the record to be added or edited.
lockKey - the lock key returned by the server when the lock was attained.
Returns:
an update response object detailing any errors and the returned record
Throws:
RETSClientException

getMetadata

public void getMetadata(java.io.OutputStream out,
                        boolean everything)
                 throws RETSClientException
Fetch system metadata from the server.

Parameters:
out - the output stream to write the metadata too.
everything - if true, fetch the entire metadata. If false, fetch only the METADATA-SYSTEM level
Throws:
RETSClientException

getMetadata

public void getMetadata(java.io.OutputStream out)
                 throws RETSClientException
Fetch the complete Standard XML metadata and write to the stream supplied.

Parameters:
out - the output stream to write the metadata too.
Throws:
RETSClientException

getMetadata

public MetadataSystem getMetadata(boolean everything)
                           throws RETSClientException
Fetch XML metadata from the server.

Parameters:
everything - if false, only fetch the METADATA-SYSTEM level of metadata. If true, fetch METADATA-SYSTEM and all contained metadata (ie, everything).
Throws:
RETSClientException

getMetadata

public MetadataSystem getMetadata(RETSUserSession.MetadataLevel level)
                           throws RETSClientException
Fetch XML metadata from the server.

Parameters:
level - the level of metadata to get
Throws:
RETSClientException

getMetadata

public MetadataSystem getMetadata()
                           throws RETSClientException
Fetch the complete Standard XML metadata and load it into the Metadata in memory model. Please note that this requires a large amount of memory depending on the size of the servers metadata. Start your application with appropriate -Xms and -Xmx VM arguments. For example a good starting point is -Xms128m and -Xmx256m.

This is equivalent to calling 

getMetadata(true)

Returns:
the root of the metadata tree.
Throws:
RETSClientException

logout

public void logout()
            throws RETSClientException
Logout the session. Once this has been called this session will most likely not work and should be discarded.

Throws:
RETSClientException

close

public void close()
           throws java.io.IOException
Alias for logout so that the Closeable interface can be used.

Specified by:
close in interface java.io.Closeable
Throws:
java.io.IOException
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD