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