com.isomorphic.datasource
Class DSResponse

java.lang.Object
  |
  +--com.isomorphic.datasource.DSResponse

public class DSResponse

extends java.lang.Object

Field Summary

static int	STATUS_FAILURE Indicates a failure of some sort (generic).
static int	STATUS_SUCCESS Indicates successful completion of the request.
static int	STATUS_VALIDATION_ERROR This error code indicates a validation failure.

Constructor Summary

DSResponse()
Creates an empty DSResponse.

DSResponse(int status)
Creates a DSResponse with the specified status code.

DSResponse(java.lang.Object data)
Creates a DSResponse with the specified status code.

DSResponse(java.lang.Object data, int status)
Creates a DSResponse with the specified data payload and status code.

Method Summary

void	addError(java.lang.String fieldName, ErrorMessage errorMessage) Adds an ErrorMessage to the ErrorReport for this DSResponse.
void	addError(java.lang.String fieldName, java.lang.String errorMessage) Adds an ErrorMessage to the ErrorReport for this DSResponse.
long	getAffectedRows() For operations that modify data, this method returns the number of rows affected by the change.
java.lang.Object	getData() Returns the data object originally set by setData()
long	getEndRow() Returns the endRow for this DSResponse.
ErrorReport	getErrorReport() Returns the current ErrorReport.
boolean	getInvalidateCache() Returns the current value of invalidateCache
long	getStartRow() Returns the startRow for this DSResponse.
int	getStatus() Returns the currently set status code.
long	getTotalRows() Returns the totalRows for this DSResponse.
void	setData(java.lang.Object data) Sets the data to satisfy the DataSource request.
void	setEndRow(long endRow) If the DSRequest specified an endRow, then the DSResponse should return the actual endRow for the response.
void	setErrorReport(ErrorReport errorReport) Sets the ErrorReport for this DSResponse
void	setFailure() Sets the status code to STATUS_FAILURE
void	setInvalidateCache(boolean invalidateCache) Setting invalidateCache to true triggers the client-side ResultSet to drop its existing cache.
void	setStartRow(long startRow) If the DSRequest specified a startRow, then the DSResponse should return the actual startRow for the response.
void	setStatus(int status) Sets the status of this DSResponse.
void	setSuccess() Sets the status of this DSResponse to STATUS_SUCCESS.
void	setTotalRows(long totalRows) If the DSRequest sent a paged request (see DSRequest.isPaged()) and the total number of records available to be sent to the client given the provided criteria is greater than the requested size, then you should provide the total number of rows that actually matched the provided criteria.
boolean	statusIsError() Returns true unless the currently status is STATUS_SUCCESS
boolean	statusIsSuccess()

Field Detail

STATUS_SUCCESS

public static final int STATUS_SUCCESS

Indicates successful completion of the request. This is the default status and is automatically used by the DSResponse unless you override it with setStatus().

STATUS_FAILURE

public static final int STATUS_FAILURE

Indicates a failure of some sort (generic).

See also the error handling doc section in RPCManager for information on how the client handles errors.

STATUS_VALIDATION_ERROR

public static final int STATUS_VALIDATION_ERROR

This error code indicates a validation failure. The databound component will display the validation errors to the user. The actual format of the display is component-dependent.

This error code will automatically be set for you if you call setErrors() or addError().

Constructor Detail

DSResponse

public DSResponse()

Creates an empty DSResponse. Status code defaults to STATUS_SUCCESS

DSResponse

public DSResponse(int status)

Creates a DSResponse with the specified status code.

Parameters:

status - the status code (one of the static STATUS_* codes on this class)

DSResponse

public DSResponse(java.lang.Object data)

Creates a DSResponse with the specified status code.

Parameters:

data - the payload of the response - equivalent to setData()

DSResponse

public DSResponse(java.lang.Object data,
                  int status)

Creates a DSResponse with the specified data payload and status code.

Parameters:

data - the payload of the response - equivalent to setData()

status - the status code (one of the static STATUS_* codes on this class)

Method Detail

getAffectedRows

public long getAffectedRows()

For operations that modify data, this method returns the number of rows affected by the change. This is set by the built-in ISC datasources.

Returns:

number of affected rows

getInvalidateCache

public boolean getInvalidateCache()

Returns the current value of invalidateCache

Returns:

current value of invalidateCache

setInvalidateCache

public void setInvalidateCache(boolean invalidateCache)

Setting invalidateCache to true triggers the client-side ResultSet to drop its existing cache. If you set invalidateCache to an update operation, a new cache will be requested by the ResultSet.

Parameters:

invalidateCache - new value for invalidateCache

setData

public void setData(java.lang.Object data)

Sets the data to satisfy the DataSource request.

The object passed to setData() is translated to JavaScript via the JSTranslater class. The expected return data varies by operationType and is described in terms of the JavaScript result (see below) - anything that will be translated to the appropriate JavaScript result is acceptable. Compare all the data formats you can readily retrieve against the capabilities of the JSTranslater. Common options are to pass an XML document fragment or a Collection of Java Beans.

If the operationType is DataSource.OP_FETCH, then the data is expected to be an Array of JavaScript Objects matching the criteria specified in the DSRequest.

If the operationType is DataSource.OP_UPDATE, then the data is expected to be a JavaScript Object reflecting the updated record as stored.

If the operationType is DataSource.OP_ADD, then the data is expected to be a JavaScript Object reflecting the added record as stored.

If the operationType is DataSource.OP_REMOVE, then the data is expected to be at least the primary key fields of the removed record, an as JavaScript Object. A complete record is also acceptable.

DSResponses or DSResponse data returned by DMI methods is, by default, automatically filtered to just the set of fields defined on the DataSource. You can override this default in several ways - see the DMI overview in the SmartClient Reference documentation for a full description. For backwards compatibility, non-DMI DSResponses are not filtered in this manner. If you want to enable this filtering for non-DMI responses, you can do so by setting the config parameter DSResponse.dropExtraFields to true in [webroot]/WEB-INF/classes/server.properties. Note that per-DataSource overrides specified by the dropExtraFields setting on the DataSource will still apply in this case. Note that DMI.dropExtraFields and DSResponse.dropExtraFields can be enabled/disabled independently of each other - that is, setting one does not side-effect the other.

Parameters:

data - the data

See Also:

JSTranslater.toJS(Object, Writer), JSONFilter

getData

public java.lang.Object getData()

Returns the data object originally set by setData()

Returns:

the data object as originally set by setData()

See Also:

setData(Object)

getStartRow

public long getStartRow()

Returns the startRow for this DSResponse.

Returns:

current value for startRow

setStartRow

public void setStartRow(long startRow)

If the DSRequest specified a startRow, then the DSResponse should return the actual startRow for the response. Note that will not necessarily be the same value as requested. It may be different if the underlying data has changed since the client last made a request.

Note that startRow and endRow are zero-based - the first record is row zero.

Parameters:

startRow - new value for startRow

getEndRow

public long getEndRow()

Returns the endRow for this DSResponse.

Returns:

current value for endRow

setEndRow

public void setEndRow(long endRow)

If the DSRequest specified an endRow, then the DSResponse should return the actual endRow for the response. Note that will not necessarily be the same value as requested. It may be different if the underlying data has changed since the client last made a request.

Note that startRow and endRow are zero-based - the first record is row zero.

If startRow is currently greater than endRow, it will be reduced to a maximum of endRow-1 (or 0).

Parameters:

endRow - new value for endRow

getTotalRows

public long getTotalRows()

Returns the totalRows for this DSResponse.

Returns:

current value for totalRows

setTotalRows

public void setTotalRows(long totalRows)

If the DSRequest sent a paged request (see DSRequest.isPaged()) and the total number of records available to be sent to the client given the provided criteria is greater than the requested size, then you should provide the total number of rows that actually matched the provided criteria. This allows the databound component to properly display a visual representation of the portion of the result set actually retreived.

For example, the ListGrid uses this value to display a properly sized scrollbar thumb.

See Also:

DSRequest.isPaged()

getStatus

public int getStatus()

Returns the currently set status code.

Returns:

current status

statusIsError

public boolean statusIsError()

Returns true unless the currently status is STATUS_SUCCESS

Returns:

false if status is STATUS_SUCCESS, false otherwise

statusIsSuccess

public boolean statusIsSuccess()

Returns:

true if the currently set status code is STATUS_SUCCESS, false otherwise.

setStatus

public void setStatus(int status)

Sets the status of this DSResponse.

Parameters:

status - new status code

setSuccess

public void setSuccess()

Sets the status of this DSResponse to STATUS_SUCCESS.

setFailure

public void setFailure()

Sets the status code to STATUS_FAILURE

getErrorReport

public ErrorReport getErrorReport()

Returns the current ErrorReport.

Returns:

current ErrorReport

See Also:

ErrorReport, ErrorMessage, DSRequest.validate()

setErrorReport

public void setErrorReport(ErrorReport errorReport)

Sets the ErrorReport for this DSResponse

Parameters:

errorReport - new errorReport

addError

public void addError(java.lang.String fieldName,
                     ErrorMessage errorMessage)

Adds an ErrorMessage to the ErrorReport for this DSResponse. If no ErrorReport exists, one is created. Note that multiple ErrorMessages can be returned for a given field - for example if the field specified multiple validators and more than one those failed.

Parameters:

fieldName - the fieldName for the error

errorMessage - the errorMessage

addError

public void addError(java.lang.String fieldName,
                     java.lang.String errorMessage)

Adds an ErrorMessage to the ErrorReport for this DSResponse. If no ErrorReport exists, one is created. Note that multiple ErrorMessages can be returned for a given field - for example if the field specified multiple validators and more than one those failed.

Parameters:

fieldName - the fieldName for the error

errorMessage - the errorMessage