com.bigllc.retsiq.simpleclient
Class RETSUserSession

java.lang.Object
  com.bigllc.retsiq.simpleclient.RETSUserSession

public class RETSUserSession
extends java.lang.Object

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();
 

Author:

Marc G. Smith

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.
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.
java.util.List<ObjectRecord>	getObjects(java.lang.String objectPath, java.io.File directory) Fetch and save objects for records.
java.util.List<ObjectRecord>	getObjects(java.lang.String objectPath, ObjectResponseHandler handler) Fetch and save objects for records.
ObjectRecord	getObjectUrl(java.lang.String objectPathId) Get the URL location for a single object such as a photo.
java.util.List<ObjectRecord>	getObjectUrls(java.lang.String objectPath) Get the URL locations for multiple objects.
int	getRecordCount(java.lang.String path, java.lang.String query) Get the number of records that match a search query.
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.
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.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_LIMIT

public static 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.

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

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

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

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.

Parameters:

objectPathId - the object to fetch the URL for in the following format:
/<Resource>/<Type>/<RecordID>:<ObjectID>
e.g. /Property/Photo/123456:0

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.

Parameters:

objectPath - the object to fetch the URL for in the following format:
/<Resource>/<Type>/<RecordID>:[*|<ObjectID-List>]
e.g. /Property/Photo/123456:* - all objects for a record
/Property/Photo/123456:1:2:3 - object 1 2 and 3 for a single record /Property/Photo/123456:*,123457:* - all objects for two records

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. 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 to fetch the URL for in the following format:
/<Resource>/<Type>/<RecordID>:[*|<ObjectID-List>]
e.g. /Property/Photo/123456:* - all objects for a record
/Property/Photo/123456:1:2:3 - object 1 2 and 3 for a single record /Property/Photo/123456:*,123457:* - all objects for two records

directory - the directory to save the returned objects to.

Returns:

an 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. The method takes a handler for allowing user controlled persistence of objects.

Parameters:

objectPath - the object to fetch the URL for in the following format:
/<Resource>/<Type>/<RecordID>:[*|<ObjectID-List>]
e.g. /Property/Photo/123456:* - all objects for a record
/Property/Photo/123456:1:2:3 - object 1 2 and 3 for a single record /Property/Photo/123456:*,123457:* - all objects for two records

handler - the handler responsible for persistence.

Returns:

an list of object records for the object path.

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 ot 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

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.

everthing - 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()
                           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