com.isomorphic.datasource

## Class DSResponse

- java.lang.Object
- - com.isomorphic.base.Base
  - - com.isomorphic.rpc.BaseResponse
    - - com.isomorphic.datasource.DSResponse

-     public class DSResponse
      extends BaseResponse

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

- - ### Field Summary

    - ### Fields inherited from class com.isomorphic.rpc.BaseResponse

      `STATUS_AUTHORIZATION_FAILURE, STATUS_FAILURE, STATUS_FILE_NOT_FOUND, STATUS_FILE_REQUIRED_ERROR, STATUS_LOGIN_INCORRECT, STATUS_LOGIN_REQUIRED, STATUS_LOGIN_SUCCESS, STATUS_MAX_FILE_SIZE_EXCEEDED, STATUS_MAX_LOGIN_ATTEMPTS_EXCEEDED, STATUS_PROCESSING_SKIPPED, STATUS_REQUIRED_CRITERIA_MISSING, STATUS_SUCCESS, STATUS_TRANSACTION_FAILED, STATUS_UPDATE_WITHOUT_PK, STATUS_VALIDATION_ERROR, UPDATE_WITHOUT_PK`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DSResponse()` Creates an empty DSResponse.
    `DSResponse(DataSource dataSource)` Creates a DSResponse with the specified dataSource.
    `DSResponse(DataSource dataSource, int status)` Creates a DSResponse with the specified dataSource and status code.
    `DSResponse(DataSource dataSource, java.lang.Object data)` Creates a DSResponse with the specified dataSource and data payload
    `DSResponse(DataSource dataSource, java.lang.Object data, int status)` Creates a DSResponse with the specified dataSource, data payload and status code.
    `DSResponse(int status)` Creates a DSResponse with the specified status code.
    `DSResponse(java.lang.Object data)` Creates a DSResponse with the specified data payload.
    `DSResponse(java.lang.Object data, int status)` Creates a DSResponse with the specified data payload and status code.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DSResponse` | `addError(java.lang.String fieldName, ErrorMessage errorMessage)` Adds an ErrorMessage to the ErrorReport for this DSResponse.
    `DSResponse` | `addError(java.lang.String fieldName, java.lang.String errorMessage)` Adds an ErrorMessage to the ErrorReport for this DSResponse.
    `DSResponse` | `addRelatedUpdate(DSResponse relatedUpdate)` Causes client-side components to react as though the provided DSResponse had just successfully completed.
    `void` | `clearRelatedUpdates()` This can be used to clear any automatically-generated related updates
    `long` | `getAffectedRows()` For operations that modify data, this method returns the number of rows affected by the change.
    `java.lang.Boolean` | `getBypassDataFilter()` This method returns true if this DSResponse will bypass the normal data filter pipeline (i.e dropExtraFields, valueXPath evaluation, etc) and simply serialize the provided data to the client.
    `java.lang.Object` | `getData()` Returns the data object originally set by setData()
    `java.util.List` | `getDataList()` Convenience method to return the data object originally set by setData(), as a List.
    `java.util.Map` | `getDataMap()` Convenience method to return the data object originally set by setData(), as a Map.
    `DataSource` | `getDataSource()` Returns the currently set DataSource.
    `java.lang.Boolean` | `getDropExtraFields()` This method returns true if this DSResponse will automatically trim the fields in its data member to just those fields declared in the DataSource.
    `long` | `getEndRow()` Returns the endRow for this DSResponse.
    `ErrorReport` | `getErrorReport()` Returns the current ErrorReport.
    `java.lang.Object` | `getExportObject(DSRequest dsRequest)` Returns the Java object encapsulating the exported data in a format suitable for directly loading into Microsoft Excel.
    `java.io.OutputStream` | `getExportTo()` Returns the OuputStream we will use for data export.
    `java.lang.Object` | `getFieldValue(java.lang.String fieldName)` Returns the value of the field name provided in this dsResponse's data member.
    `boolean` | `getInvalidateCache()` Returns the current value of invalidateCache
    `java.util.Map` | `getKeys()` For responses produced by SQLDataSource and subclasses only, this method returns the Map of key values used in the SQL query.
    `java.lang.String` | `getOperationType()` Returns the operationType associated with this DSResponse.
    `java.lang.Object` | `getProperty(java.lang.String key)` Returns an arbitrary property of the DSResponse that has previously been set with `DSResponse.setProperty(String, Object)`
    `java.util.Map` | `getRecord()` Returns the DSResponse's data member in "record" format (ie, as a nested collection of Maps and Lists that can be directly translated into JSON format by the JSTranslater).
    `java.util.List` | `getRecords()` Returns the DSResponse's data member as a list of maps in "record" format (ie, each entry in the list is a nested collection of Maps and Lists that can be directly translated into JSON format by the JSTranslater).
    `java.util.List` | `getRecords(ValidationContext vc)` Returns the DSResponse's data member as a list of maps in "record" format (ie, each entry in the list is a nested collection of Maps and Lists that can be directly translated into JSON format by the JSTranslater).
    `java.util.List` | `getRelatedUpdates()` Gets list of related updates previously added to this response.
    `long` | `getStartRow()` Returns the startRow for this DSResponse.
    `long` | `getTotalRows()` Returns the totalRows for this DSResponse.
    `boolean` | `hasNextRecord()` This method is called by the framework during streaming.
    `java.lang.Object` | `nextRecordAsObject()` This method is called by the framework during streaming.
    `DSResponse` | `setBypassDataFilter(java.lang.Boolean value)` This method sets the DSResponse's behavior with regard to the normal data filter pipeline (i.e dropExtraFields, valueXPath evaluation, etc).
    `DSResponse` | `setData(java.lang.Object data)` Sets the data to satisfy the DataSource request.
    `DSResponse` | `setDataSource(DataSource dataSource)` Sets the DataSource associated with this DSResponse.
    `DSResponse` | `setDropExtraFields(java.lang.Boolean value)` This method sets the DSResponse's behavior with regard to extra fields in the data it returns.
    `DSResponse` | `setEndRow(long endRow)` If the DSRequest specified an endRow, then the DSResponse should return the actual endRow for the response.
    `DSResponse` | `setErrorReport(ErrorReport errorReport)` Sets the ErrorReport for this DSResponse
    `DSResponse` | `setEstimatedTotalRows(java.lang.String estimatedTotalRows)` For fetch requests where progressiveLoading is enabled, dsResponse.estimatedTotalRows may be set to indicate the true size of the data set.
    `DSResponse` | `setExportObject(java.lang.Object exportObject)` Set the export object on the DSResponse.
    `DSResponse` | `setExportTo(java.io.OutputStream exportOutputStream)` Sets the OuputStream we will use for data export (this means exports to CSV, XML, JSON and Excel formats; PDF exports are "content exports" and are different).
    `DSResponse` | `setFailure(java.lang.String message)` Sets the status code to `BaseResponse.STATUS_FAILURE` and provides an error message to be shown to the user.
    `DSResponse` | `setInvalidateCache(boolean invalidateCache)` Setting invalidateCache to true triggers the client-side ResultSet to drop its existing cache.
    `DSResponse` | `setOperationType(java.lang.String value)` Set the operationType associated with this DSResponse.
    `void` | `setProgressiveLoading(boolean value)` Mark this dsResponse as having progressiveLoading enabled.
    `DSResponse` | `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.
    `DSResponse` | `setStartRow(long startRow)` If the DSRequest specified a startRow, then the DSResponse should return the actual startRow for the response.
    `DSResponse` | `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.

    - ### Methods inherited from class com.isomorphic.rpc.BaseResponse

      `getStatus, setFailure, setStatus, setSuccess, statusIsError, statusIsSuccess`

- - ### 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 data payload.
      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:
        `DSResponse.setData(java.lang.Object)`, `BaseResponse.setStatus(int)`

    - #### DSResponse

          public DSResponse(DataSource dataSource)

      Creates a DSResponse with the specified dataSource.
      Parameters:
        `dataSource` - the DataSource associated with this DSResponse
      See Also:
        `DSResponse.setDataSource(com.isomorphic.datasource.DataSource)`

    - #### DSResponse

          public DSResponse(DataSource dataSource,
                            int status)

      Creates a DSResponse with the specified dataSource and status code.
      Parameters:
        `dataSource` - the DataSource associated with this DSResponse
        `status` - the status code (one of the static STATUS_* codes on this class)
      See Also:
        `DSResponse.setDataSource(com.isomorphic.datasource.DataSource)`, `BaseResponse.setStatus(int)`

    - #### DSResponse

          public DSResponse(DataSource dataSource,
                            java.lang.Object data)

      Creates a DSResponse with the specified dataSource and data payload
      Parameters:
        `dataSource` - the DataSource associated with this DSResponse
        `data` - the payload of the response - equivalent to setData()
      See Also:
        `DSResponse.setDataSource(com.isomorphic.datasource.DataSource)`, `DSResponse.setData(java.lang.Object)`, `BaseResponse.setStatus(int)`

    - #### DSResponse

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

      Creates a DSResponse with the specified dataSource, data payload and status code.
      Parameters:
        `dataSource` - the DataSource associated with this DSResponse
        `data` - the payload of the response - equivalent to setData()
        `status` - the status code (one of the static STATUS_* codes on this class)
      See Also:
        `DSResponse.setDataSource(com.isomorphic.datasource.DataSource)`, `DSResponse.setData(java.lang.Object)`, `BaseResponse.setStatus(int)`

  - ### Method Detail

    - #### getOperationType

          public java.lang.String getOperationType()

      Returns the operationType associated with this DSResponse.
      Returns:
        the DSResponse's operationType, or null if it is unset

    - #### setOperationType

          public DSResponse setOperationType(java.lang.String value)

      Set the operationType associated with this DSResponse.

      Parameters:
        `value` - the operationType
      Returns:
        the DSResponse

    - #### setProperty

          public DSResponse 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", Boolean.TRUE);

      JavaScript code on the client could then access "dsResponse.totalsRowsIsApproximate" from any method that receives the DSResponse, eg, DataSource.transformResponse(). In the case of SmartGWT, you will need to call getAttribute("totalsRowsIsApproximate").

      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:

      - returning extra data. You should instead use queuing (see the JavaScript method RPCManager.startQueue()) to submit multiple independent requests in one HTTP turnaround. By returning extra data as a DSResponse property, you make it impossible to fetch the extra data independently.
      - preserving state during a network turnaround. The client-side DSRequest is generally passed to every client-side method that receives a DSResponse, so you can access properties such as dsRequest.data and dsRequest.oldValues, as well as any custom properties you set on the DSRequest, without having to have the server add those properties to the DSResponse.
      Returns:
        the DSResponse

    - #### getProperty

          public java.lang.Object getProperty(java.lang.String key)

      Returns an arbitrary property of the DSResponse that has previously been set with `DSResponse.setProperty(String, Object)`
      Parameters:
        `key` - the key of the property to return
      Returns:
        The value of the requested property, or null if it has never been set

    - #### getBypassDataFilter

          public java.lang.Boolean getBypassDataFilter()

      This method returns true if this DSResponse will bypass the normal data filter pipeline (i.e dropExtraFields, valueXPath evaluation, etc) and simply serialize the provided data to the client. This setting also applies to getRecord().
      Returns:
        Boolean.TRUE if this DSResponse will bypass extra fields; otherwise Boolean.FALSE
      See Also:
        `DSResponse.setBypassDataFilter(java.lang.Boolean)`, `DSResponse.getRecord()`

    - #### setBypassDataFilter

          public DSResponse setBypassDataFilter(java.lang.Boolean value)

      This method sets the DSResponse's behavior with regard to the normal data filter pipeline (i.e dropExtraFields, valueXPath evaluation, etc).
      One use case for this flag is to suppress automatic valueXPath derivation on the response in cases where you have postprocessing logic that has already converted the response into client-consumable records.
      Returns:
        the DSResponse
      See Also:
        `DSResponse.getBypassDataFilter()`, `DSResponse.setData(java.lang.Object)`

    - #### getDropExtraFields

          public java.lang.Boolean getDropExtraFields()

      This method returns true if this DSResponse will automatically trim the fields in its data member to just those fields declared in the DataSource. This is the default for normal, non-custom DataSource operations. This method also applies to getRecord()
      Returns:
        Boolean.TRUE if this DSResponse will drop extra fields; otherwise Boolean.FALSE
      See Also:
        `DSResponse.setDropExtraFields(java.lang.Boolean)`, `DSResponse.getRecord()`

    - #### setDropExtraFields

          public DSResponse setDropExtraFields(java.lang.Boolean value)

      This method sets the DSResponse's behavior with regard to extra fields in the data it returns. If set to true, only the fields declared in the DataSource will be returned by the DSResponse; all other fields will be automatically trimmed off. If set to false, the DSResponse will return all fields.
      Returns:
        the DSResponse
      See Also:
        `DSResponse.getDropExtraFields()`, `DSResponse.setData(java.lang.Object)`

    - #### 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 DSResponse 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 DSResponse 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.

      Specified by:
        `setData` in class `BaseResponse`
      Parameters:
        `data` - the data
      Returns:
        the DSResponse
      See Also:
        `JSTranslater.toJS(Object, java.io.Writer)`, `JSONFilter`, `DataSourceBeanFilter`

    - #### getDataList

          public java.util.List getDataList()

      Convenience method to return the data object originally set by setData(), as a List. If the data object is a List, the object is returned; if the data object is a JSONFilter and the wrapped object inside the JSONFilter is a List, the wrapped object is returned. In all other circumstances, this method returns null.
      Returns:
        the data object as originally set by setData(), as a List
      See Also:
        `DSResponse.getData()`, `DSResponse.getDataMap()`

    - #### getDataMap

          public java.util.Map getDataMap()

      Convenience method to return the data object originally set by setData(), as a Map. If the data object is a Map, the object is returned; if the data object is actually a List but the first entry in that List is a Map, the first entry in the List is returned. If the data object is a JSONFilter wrapping a Map or a List with a Map in its first entry, this method returns the wrapped Map or the first List entry, as appropriate. In all other circumstances, this method returns null.
      Returns:
        the data object as originally set by setData(), as a Map
      See Also:
        `DSResponse.getData()`, `DSResponse.getDataList()`

    - #### getData

          public java.lang.Object getData()

      Returns the data object originally set by setData()
      Specified by:
        `getData` in class `BaseResponse`
      Returns:
        the data object as originally set by setData()
      See Also:
        `DSResponse.setData(Object)`

    - #### getStartRow

          public long getStartRow()

      Returns the startRow for this DSResponse.
      Returns:
        current value for startRow. If unset, returns -1.

    - #### setStartRow

          public DSResponse 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
      Returns:
        the DSResponse

    - #### getEndRow

          public long getEndRow()

      Returns the endRow for this DSResponse.
      Returns:
        current value for endRow. If unset, returns -1.

    - #### setEndRow

          public DSResponse 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
      Returns:
        the DSResponse

    - #### getTotalRows

          public long getTotalRows()

      Returns the totalRows for this DSResponse.
      Returns:
        current value for totalRows. If unset, returns -1.

    - #### setTotalRows

          public DSResponse 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 retrieved.

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

      Returns:
        the DSResponse
      See Also:
        `DSRequest.isPaged()`

    - #### setFailure

          public DSResponse setFailure(java.lang.String message)

      Sets the status code to `BaseResponse.STATUS_FAILURE` and provides an error message to be shown to the user.
      Returns:
        the DSResponse

    - #### getDataSource

          public DataSource getDataSource()

      Returns the currently set DataSource.
      Returns:
        the DataSource associated with this DSResponse

    - #### setDataSource

          public DSResponse setDataSource(DataSource dataSource)

      Sets the DataSource associated with this DSResponse.
      Parameters:
        `dataSource` - the datasource to set.
      Returns:
        the DSResponse

    - #### getRelatedUpdates

          public java.util.List getRelatedUpdates()

      Gets list of related updates previously added to this response.
      Returns:
        list of related responses.
      See Also:
        `DSResponse.addRelatedUpdate(DSResponse)`

    - #### addRelatedUpdate

          public DSResponse addRelatedUpdate(DSResponse relatedUpdate)

      Causes client-side components to react as though the provided DSResponse had just successfully completed.

      This API can be used to communicate additional changes that occur as a consequence of the current DSResponse succeeding, such as changes to other records in the same DataSource or to records from unrelated DataSources. For example, in CRM applications, Leads may be converted to Accounts. In this case the "remove" operation on the Leads DataSource might call `addRelatedUpdate()` with a DSResponse representing an "add" operation on the Accounts DataSource. This would cause any client-side caches of Accounts (such as a drop-down list for picking an Account) to automatically update.

      If a DSResponse is passed with the DataSource or operationType unset, they will match the current DSResponse.

      This API can be called multiple times for multiple related updates. Each update is processed by the client-side method DataSource.updateCaches().

      This API should NOT be used simply to complete multiple requests in a single HTTP turnaround, instead, use Queuing for this (see the client-side API isc.RPCManager.startQueue()).

      Parameters:
        `relatedUpdate` - `DSResponse` to add.
      Returns:
        the DSResponse that addRelatedUpdate() was called on

    - #### clearRelatedUpdates

          public void clearRelatedUpdates()

      This can be used to clear any automatically-generated related updates

    - #### getErrorReport

          public ErrorReport getErrorReport()

      Returns the current ErrorReport.
      Returns:
        current ErrorReport
      See Also:
        `ErrorReport`, `ErrorMessage`, `DSRequest.validate()`

    - #### setErrorReport

          public DSResponse setErrorReport(ErrorReport errorReport)

      Sets the ErrorReport for this DSResponse
      Parameters:
        `errorReport` - new errorReport
      Returns:
        the DSResponse

    - #### addError

          public DSResponse 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
      Returns:
        the DSResponse

    - #### addError

          public DSResponse 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
      Returns:
        the DSResponse

    - #### getRecord

          public java.util.Map getRecord()

      Returns the DSResponse's data member in "record" format (ie, as a nested collection of Maps and Lists that can be directly translated into JSON format by the JSTranslater). Note that this method only works if the DSResponse has had its dataSource member set, either by constructing with a suitable constructor or by calling dsResponse.setDataSource().

      Note: if you want to suppress valueXPath and dropExtraFields, you can call setBypassDataFilter. setDropExtraFields() will likewise be honored.

      Returns:
        This dsResponse's data object, in record format
      See Also:
        `DSResponse.setBypassDataFilter(java.lang.Boolean)`, `DSResponse.setDropExtraFields(java.lang.Boolean)`

    - #### getRecords

          public java.util.List getRecords()

      Returns the DSResponse's data member as a list of maps in "record" format (ie, each entry in the list is a nested collection of Maps and Lists that can be directly translated into JSON format by the JSTranslater). Note that this method only works if the DSResponse has had its dataSource member set, either by constructing with a suitable constructor or by calling dsResponse.setDataSource().
      Returns:
        This dsResponse's data object, as a list of maps in record format

    - #### getRecords

          public java.util.List getRecords(ValidationContext vc)

      Returns the DSResponse's data member as a list of maps in "record" format (ie, each entry in the list is a nested collection of Maps and Lists that can be directly translated into JSON format by the JSTranslater). Note that this method only works if the DSResponse has had its dataSource member set, either by constructing with a suitable constructor or by calling dsResponse.setDataSource().
      Parameters:
        `vc` - Validation context
      Returns:
        This dsResponse's data object, as a list of maps in record format

    - #### getFieldValue

          public java.lang.Object getFieldValue(java.lang.String fieldName)

      Returns the value of the field name provided in this dsResponse's data member. Note that this method first calls getRecord() to obtain a record view of the data.
      Parameters:
        `fieldName` - The name of the field whose value to return
      Returns:
        The value of the supplied field name in this dsResponse's data member

    - #### getExportTo

          public java.io.OutputStream getExportTo()

      Returns the OuputStream we will use for data export. If you have not set this explicitly with the `DSResponse.setExportTo(OutputStream)` API, it will be null.
      Returns:
        The export OutputStream

    - #### setExportTo

          public DSResponse setExportTo(java.io.OutputStream exportOutputStream)

      Sets the OuputStream we will use for data export (this means exports to CSV, XML, JSON and Excel formats; PDF exports are "content exports" and are different). This API allows you to arrange for other export scenarios than the two built-in options (download to client and write to filesystem). If you set this property, it overrides the default OutputStream we would normally create for a filesystem export; in other words, we will export to your OutputStream rather than to a filesystem file.
      Parameters:
        `exportOutputStream` - An OutputStream to use for the export
      Returns:
        The DSResponse itself

    - #### getExportObject

          public java.lang.Object getExportObject(DSRequest dsRequest)
                                           throws java.lang.Exception

      Returns the Java object encapsulating the exported data in a format suitable for directly loading into Microsoft Excel. Note that calling this method causes the parameter dsRequest to be executed inline, if it has not already been executed, in order to fetch and format the data. Note that this API is only applicable when the parameter DSRequest is for an export to XLS or OOXML format.

      Currently, we use the Apache POI library to perform Excel exports, so the object returned by this method will be an instance of that library's Workbook interface.

      Use this API with extreme caution. Most of its behavior is subject to change without notice. The types of objects returned by this API may be changed in future versions without notice if the Server Framework begins using a newer version of the various libraries used for exports (eg a newer version of Apache POI) and could change to a completely different type if the Server Framework switches to using a different library for a given type of export.

      Further, the contents of the export object are likewise subject to change without notice, including, for example, the specific way that type, formatting and styling information is conveyed to Excel.

      If you choose to use this API, when interacting with the generated export object, code defensively and rely on as few specifics as possible. Also, be sure to revisit and re-test this code when upgrading to new versions of the Server Framework.

      Parameters:
        `dsRequest` - The DSRequest to execute to obtain the export object
      Returns:
        The export object
      Throws:
        `java.lang.Exception`

    - #### setExportObject

          public DSResponse setExportObject(java.lang.Object exportObject)
                                     throws java.lang.Exception

      Set the export object on the DSResponse. Note that this API is only applicable when the parameter DSRequest is for an export to XLS or OOXML format. Calling this method causes the server framework to use the provided object rather than running through the export process.

      Currently, we use the Apache POI library to perform Excel exports, so the object provided to this method must be an instance of that library's Workbook interface.

      Use this API with extreme caution. Most of its behavior is subject to change without notice. The types of object accepted by this API may be changed in future versions without notice if the Server Framework begins using a newer version of the various libraries used for exports (eg a newer version of Apache POI) and could change to a completely different type if the Server Framework switches to using a different library for a given type of export.

      Parameters:
        `exportObject` - The export object to associate with this DSResponse
      Returns:
        The DSResponse itself
      Throws:
        `java.lang.Exception`

    - #### hasNextRecord

          public boolean hasNextRecord()

      This method is called by the framework during streaming. If you are using `SQLDataSource`, the default implementation will return the correct value. Otherwise, you must override this method and cause it to return an appropriate value for the current dataset. The approach we recommend is to convert your DSResponse's data member to an `StreamingResponseIterator` and then override `hasNextRecord()` and `DSResponse.nextRecordAsObject()` on the DSResponse to return appropriate values. For example:

             public DSResponse dmiMethod(DSRequest dsRequest) {
                 List data = (List)dsRequest.execute().getData();
                 CustomDSResponse resp = new CustomDSResponse();
                 resp.setUnderlyingIterator(data.iterator());
                 resp.setData(new StreamingResponseIterator(resp));
                 return resp;
             }

             static class CustomDSResponse extends DSResponse {

                 private Iterator underlyingIterator;
                 public void setUnderlyingIterator(Iterator it) {
                     underlyingIterator = it;
                 }

                 public CustomDSResponse(DataSource dataSource) {
                     super(dataSource);
                 }
                 public boolean hasNextRecord() {
                     return underlyingIterator.hasNext();
                 }
                 public Object nextRecordAsObject() throws StreamingResponseException {
                     return underlyingIterator.next();
                 }
             }

      Note, this method is only applicable when streaming a response.
      Returns:
        true if there is at least one more record to read
      See Also:
        `DSResponse.nextRecordAsObject()`

    - #### nextRecordAsObject

          public java.lang.Object nextRecordAsObject()
                                              throws StreamingResponseException

      This method is called by the framework during streaming. If you are using `SQLDataSource`, the default implementation will return the next available row, as you would expect. Otherwise, you must override this method and cause it to return the next row. If you do not know upfront how many rows there are in your dataset, you can also increment endRow in this method, so that the client ends up with an accurate rowcount. For example:

             public Object nextRecordAsObject() throws StreamingResponseException {
                 Object obj = someUserMethodToGetTheNextRecord();
                 if (obj != null) {
                     this.setEndRow(this.getEndRow() + 1);
                 }
                 return obj;
             }

      Note, this method is only applicable when streaming a response.
      Returns:
        the next record as an instance of `Object`
      Throws:
        `StreamingResponseException`
      See Also:
        `DSResponse.hasNextRecord()`

    - #### setProgressiveLoading

          public void setProgressiveLoading(boolean value)

      Mark this dsResponse as having progressiveLoading enabled. In this mode, the totalRows attribute of the response is intended to be a valid lower-bound

    - #### setEstimatedTotalRows

          public DSResponse setEstimatedTotalRows(java.lang.String estimatedTotalRows)

      For fetch requests where progressiveLoading is enabled, dsResponse.estimatedTotalRows may be set to indicate the true size of the data set.

      This value may be set to a String in the following format:

      - "500+": There are at least 500 records
      - "-500": There are fewer than 500 records
      - "450-500": There are between 450 and 500 records
      - "~500": There are approximately 500 records
      - "500": There are exactly than 500 records
      This property will be set automatically to an exact value if a row count query was performed and the result exceeded the progressiveLoadingThreshold (where supported), causing progressiveLoading to be enabled.
      See Also:
        `com.isomorphic.datasource.DSRequest#setProgressiveLoading()`

    - #### getKeys

          public java.util.Map getKeys()

      For responses produced by SQLDataSource and subclasses only, this method returns the Map of key values used in the SQL query. It includes any keys that were generated by the database for "add" operations (though note there are some provisos - see the client-side documentation for "makeKeysAvailable").

      The motivation for providing this API is to allow user-written code to provide data for cache-synchronization purposes, in rare edge cases where the framework's automatic cache-sync processing causes problems (for example, record deadlocks in complex scenarios involving queues of updates to multiple different DataSources). The intention is that you mark your operationBinding `canSyncCache="false"` and then use the `getKeys()` API in your own logic.

      Returns:
        the Map of key values used