com.isomorphic.datasource
Class DSResponse

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

public class DSResponse
extends java.lang.Object

Response object to be populated by server-side code responding to a DSRequest.


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 setProperty(java.lang.String key, java.lang.Object value)
          Set an arbitrary property of the DSResponse, so that the value will be visible to custom JavaScript code on the client-side DSResponse object.
 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)
See Also:
setData(java.lang.Object), setStatus(int)
Method Detail

setProperty

public void setProperty(java.lang.String key,
                        java.lang.Object value)
Set an arbitrary property of the DSResponse, so that the value will be visible to custom JavaScript code on the client-side DSResponse object.

The value parameter will be translated to JavaScript by the JSTranslater.

For example, if you were to call:

    dsResponse.setProperty("totalRowsIsApproximate", new Boolean(true));
 
JavaScript code on the client could then access "dsResponse.totalsRowsIsApproximate" from any method that receives the DSResponse, eg, DataSource.transformResponse().

This API is easily misused. setProperty should only be used to pass metadata about the request, similar to the existing DSResponse properties like startRow/endRow and status. The following are bad patterns:


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.

Also, all data objects are automatically filtered through a DataSourceBeanFilter to resolve valueXPaths specified on the DataSource fields. Search the client-side reference for 'valueXPath' for more information on this mechanism.

Parameters:
data - the data
See Also:
JSTranslater.toJS(Object, Writer), JSONFilter, com.isomorphic.ds.DataSourceBeanFilter

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. If unset, returns -1.

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. If unset, returns -1.

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 (or 0).

Parameters:
endRow - new value for endRow

getTotalRows

public long getTotalRows()
Returns the totalRows for this DSResponse.
Returns:
current value for totalRows. If unset, returns -1.

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