com.smartgwt.client.data
Class DSRequest

java.lang.Object
  com.smartgwt.client.core.JsObject
      com.smartgwt.client.core.DataClass
          com.smartgwt.client.rpc.RPCRequest
              com.smartgwt.client.data.DSRequest

public class DSRequest
extends RPCRequest

Request sent to the server to initiate a DataSource operation. All properties which are legal on RPCRequest are legal, in addition to the properties listed here.

See Also:

RPCRequest

Field Summary

Fields inherited from class com.smartgwt.client.core.JsObject

jsObj

Constructor Summary

DSRequest()

DSRequest(JavaScriptObject jsObj)

Method Summary

static DSRequest[]	convertToDSRequestArray(JavaScriptObject nativeArray)
String	getAdditionalOutputs() For fetch operation, an optional comma separated list of fields to fetch from another, related DataSource.
String	getComponentId() For requests submitted by a DataBoundComponent, the ID of the submitting component.
Criteria	getCriteria() Return the Criteria associated with a FETCH operation.
String	getDataSource() DataSource this DSRequest will act on.
Integer	getEndRow() End row of requested results, used only with fetch operations.
ExportFormat	getExportAs() The format in which the data should be exported.
Record[]	getExportData() Only applies to request properties passed to DataBoundComponent.exportClientData.
Boolean	getExportDatesAsFormattedString() Only applicable when exporting to native spreadsheet formats XLS and OOXML.
String	getExportDelimiter() The character to use as a field-separator in CSV exports.
ExportDisplay	getExportDisplay() Specifies whether the exported data will be downloaded as an attachment or displayed in a new browser window.
String[]	getExportFields() The list of field-names to export.
String	getExportFilename() The name of the file to save the exported data into.
String	getExportFooter() Optional text to appear at the end of the file.
String	getExportHeader() Optional text to appear at the beginning of the file.
String	getExportPath() If exportToFilesystem is set, optionally specifies a path to use when saving the file.
Boolean	getExportResults() When set, causes the results of the DSRequest to be exported to a file, whose name and format are indicated by exportFilename and exportAs respectively.
String	getExportTitleSeparatorChar() The character with which to replace spaces in field-titles when exporting to XML.
Boolean	getExportToClient() If set, Smart GWT Server will export data back to the client, either as a file download or as content in a new browser window, depending on the setting of exportDisplay.
Boolean	getExportToFilesystem() If set, Smart GWT Server will export data to a file on the server filesystem.
Boolean	getExportValueFields() Only applies to request properties passed to DataBoundComponent.exportClientData.
Map	getHeaderData() For DataSources using SOAP messaging with a WSDL web service, data to be serialized to form SOAP headers, as a map from the header part name to the data.
String	getLineBreakStyle() The style of line-breaks to use in the exported output.
Record	getOldValues() For an update or remove operation, the original values from the record that is being updated or removed.
String	getOperationId() When a DataBoundComponent sends a DSRequest, the dsRequest.operationId will be automatically picked up from the fetchOperation, addOperation, etc properties of the DataBoundComponent.
DSOperationType	getOperationType() Type of operation being performed: "fetch", "add", "remove", "update" or "custom".
static DSRequest	getOrCreateRef(JavaScriptObject jsObj)
String	getRequestId() Automatically generated unique ID for this request.
ResultSet	getResultSet() For advanced use in integrating dataset paging with web services, the ResultSet that issued this "fetch" DSRequest is automatically made available as the resultSet property.
SortSpecifier[]	getSortBy() Fieldname to sortBy
Integer	getStartRow() Starting row of requested results, used only with fetch operations.
String	getStreamResults() If true, results will be streamed on the server, rather than all records being read into server memory at once; this approach is appropriate for retrieving or exporting large datasets without swamping the server.
TextMatchStyle	getTextMatchStyle() For "fetch" operations, how search criteria should be interpreted for text fields: either "exact" for exact match, "startsWith" for matching at the beginning only, or "substring" for case-insensitive substring match.
Boolean	getUseFlatFields() When useFlatFields is set for a request to be sent to a WSDL web service, when creating the input XML message to send to the web service, properties in request.data will be used as the values for XML elements of the same name, at any level of nesting.
Boolean	getUseFlatHeaderFields() Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request.
ValidationMode	getValidationMode() Mode of validation for entered data.
void	setAdditionalOutputs(String additionalOutputs) For fetch operation, an optional comma separated list of fields to fetch from another, related DataSource.
void	setAttribute(String property, Object value) Set a custom attribute value on the DSRequest as an Object.
void	setComponentId(String componentId) For requests submitted by a DataBoundComponent, the ID of the submitting component.
void	setDataSource(String dataSource) DataSource this DSRequest will act on.
void	setEndRow(Integer endRow) End row of requested results, used only with fetch operations.
void	setExportAs(ExportFormat exportAs) The format in which the data should be exported.
void	setExportData(Record... exportData) Only applies to request properties passed to DataBoundComponent.exportClientData.
void	setExportDatesAsFormattedString(Boolean exportDatesAsFormattedString) Only applicable when exporting to native spreadsheet formats XLS and OOXML.
void	setExportDelimiter(String exportDelimiter) The character to use as a field-separator in CSV exports.
void	setExportDisplay(ExportDisplay exportDisplay) Specifies whether the exported data will be downloaded as an attachment or displayed in a new browser window.
void	setExportFields(String[] exportFields) The list of field-names to export.
void	setExportFilename(String exportFilename) The name of the file to save the exported data into.
void	setExportFooter(String exportFooter) Optional text to appear at the end of the file.
void	setExportHeader(String exportHeader) Optional text to appear at the beginning of the file.
void	setExportPath(String exportPath) If exportToFilesystem is set, optionally specifies a path to use when saving the file.
void	setExportResults(Boolean exportResults) When set, causes the results of the DSRequest to be exported to a file, whose name and format are indicated by exportFilename and exportAs respectively.
void	setExportTitleSeparatorChar(String exportTitleSeparatorChar) The character with which to replace spaces in field-titles when exporting to XML.
void	setExportToClient(Boolean exportToClient) If set, Smart GWT Server will export data back to the client, either as a file download or as content in a new browser window, depending on the setting of exportDisplay.
void	setExportToFilesystem(Boolean exportToFilesystem) If set, Smart GWT Server will export data to a file on the server filesystem.
void	setExportValueFields(Boolean exportValueFields) Only applies to request properties passed to DataBoundComponent.exportClientData.
void	setHeaderData(Map headerData) For DataSources using SOAP messaging with a WSDL web service, data to be serialized to form SOAP headers, as a map from the header part name to the data.
void	setLineBreakStyle(String lineBreakStyle) The style of line-breaks to use in the exported output.
void	setOldValues(JavaScriptObject oldValues) For an update or remove operation, the original values from the record that is being updated or removed.
void	setOldValues(Map oldValues) For an update or remove operation, the original values from the record that is being updated or removed.
void	setOldValues(Record oldValues) For an update or remove operation, the original values from the record that is being updated or removed.
void	setOperationId(String operationId) When a DataBoundComponent sends a DSRequest, the dsRequest.operationId will be automatically picked up from the fetchOperation, addOperation, etc properties of the DataBoundComponent.
void	setOperationType(DSOperationType operationType) Type of operation being performed: "fetch", "add", "remove", "update" or "custom".
void	setParams(Map params) Values to be sent as simple HTTP params, as a JavaScript Object where each property/value pair will become an HTTP parameter name and value.
void	setSortBy(SortSpecifier[] sortSpecifiers) Fieldnames to sortBy.
void	setStartRow(Integer startRow) Starting row of requested results, used only with fetch operations.
void	setStreamResults(String streamResults) If true, results will be streamed on the server, rather than all records being read into server memory at once; this approach is appropriate for retrieving or exporting large datasets without swamping the server.
void	setTextMatchStyle(TextMatchStyle textMatchStyle) For "fetch" operations, how search criteria should be interpreted for text fields: either "exact" for exact match, "startsWith" for matching at the beginning only, or "substring" for case-insensitive substring match.
void	setUseFlatFields(Boolean useFlatFields) When useFlatFields is set for a request to be sent to a WSDL web service, when creating the input XML message to send to the web service, properties in request.data will be used as the values for XML elements of the same name, at any level of nesting.
void	setUseFlatHeaderFields(Boolean useFlatHeaderFields) Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request.
void	setValidationMode(ValidationMode validationMode) Mode of validation for entered data.

Methods inherited from class com.smartgwt.client.rpc.RPCRequest

create, getActionURL, getBypassCache, getCallbackParam, getContainsCredentials, getContentType, getData, getDataAsString, getDownloadResult, getDownloadToNewWindow, getEvalResult, getHttpHeaders, getHttpMethod, getIgnoreTimeout, getOmitNullMapValuesInResponse, getPrompt, getPromptCursor, getPromptStyle, getSendNoQueue, getServerOutputAsString, getShowPrompt, getTimeout, getTransport, getUseSimpleHttp, getWillHandleError, setActionURL, setBypassCache, setCallbackParam, setContainsCredentials, setContentType, setData, setData, setData, setData, setDownloadResult, setDownloadToNewWindow, setEvalResult, setEvalVars, setHttpHeaders, setHttpMethod, setIgnoreTimeout, setOmitNullMapValuesInResponse, setPrompt, setPromptCursor, setPromptStyle, setSendNoQueue, setServerOutputAsString, setShowPrompt, setTimeout, setTransport, setUseSimpleHttp, setWillHandleError

Methods inherited from class com.smartgwt.client.core.DataClass

doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute

Methods inherited from class com.smartgwt.client.core.JsObject

isCreated, setJsObj

Methods inherited from class java.lang.Object

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

Constructor Detail

DSRequest

public DSRequest()

DSRequest

public DSRequest(JavaScriptObject jsObj)

Method Detail

getOrCreateRef

public static DSRequest getOrCreateRef(JavaScriptObject jsObj)

setAdditionalOutputs

public void setAdditionalOutputs(String additionalOutputs)

For fetch operation, an optional comma separated list of fields to fetch from another, related DataSource.

Fields should be specified in the format "localFieldName:relatedDataSourceID.relatedDataSourceFieldName". where relatedDataSourceID is the ID of the related dataSource, and relatedDataSourceFieldName is the field for which you want to fetch related values. The returned field values will be stored on the data returned to the client under the specified localFieldName. Note that this will be applied in addition to any specified outputs.

Note that as with includeFrom, the related dataSource must be linked to the primary datasource via a foreignKey relationship.

Note : This is an advanced setting

Parameters:

additionalOutputs - additionalOutputs Default value is null

getAdditionalOutputs

public String getAdditionalOutputs()

For fetch operation, an optional comma separated list of fields to fetch from another, related DataSource.

Fields should be specified in the format "localFieldName:relatedDataSourceID.relatedDataSourceFieldName". where relatedDataSourceID is the ID of the related dataSource, and relatedDataSourceFieldName is the field for which you want to fetch related values. The returned field values will be stored on the data returned to the client under the specified localFieldName. Note that this will be applied in addition to any specified outputs.

Note that as with includeFrom, the related dataSource must be linked to the primary datasource via a foreignKey relationship.

Returns:

String

setComponentId

public void setComponentId(String componentId)

For requests submitted by a DataBoundComponent, the ID of the submitting component.

This ID will be present for operations including automatic saves by a ListGrid during editing, or calls to form.saveData(). It will not be present for a direct call to a DataSource method such as DataSource.fetchData.

Note this is the component's String ID - you can retrieve the component itself via Canvas.getById.

Parameters:

componentId - componentId Default value is null

getComponentId

public String getComponentId()

For requests submitted by a DataBoundComponent, the ID of the submitting component.

This ID will be present for operations including automatic saves by a ListGrid during editing, or calls to form.saveData(). It will not be present for a direct call to a DataSource method such as DataSource.fetchData.

Note this is the component's String ID - you can retrieve the component itself via Canvas.getById.

Returns:

String

setDataSource

public void setDataSource(String dataSource)

DataSource this DSRequest will act on.

This property is generally automatically populated, for example when calling DataSource.fetchData the dataSource property is set to the target DataSource.

Parameters:

dataSource - dataSource Default value is null

getDataSource

public String getDataSource()

DataSource this DSRequest will act on.

This property is generally automatically populated, for example when calling DataSource.fetchData the dataSource property is set to the target DataSource.

Returns:

String

setEndRow

public void setEndRow(Integer endRow)

End row of requested results, used only with fetch operations.

Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

Parameters:

endRow - endRow Default value is null

getEndRow

public Integer getEndRow()

End row of requested results, used only with fetch operations.

Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

Returns:

Integer

setExportAs

public void setExportAs(ExportFormat exportAs)

The format in which the data should be exported. See ExportFormat for more information.

Parameters:

exportAs - exportAs Default value is "csv"

getExportAs

public ExportFormat getExportAs()

The format in which the data should be exported. See ExportFormat for more information.

Returns:

ExportFormat

setExportData

public void setExportData(Record... exportData)

Only applies to request properties passed to DataBoundComponent.exportClientData. If specified this property contains an arbitrary set of data to be exported.

Parameters:

exportData - exportData Default value is null

getExportData

public Record[] getExportData()

Only applies to request properties passed to DataBoundComponent.exportClientData. If specified this property contains an arbitrary set of data to be exported.

Returns:

Record

setExportDatesAsFormattedString

public void setExportDatesAsFormattedString(Boolean exportDatesAsFormattedString)

Only applicable when exporting to native spreadsheet formats XLS and OOXML.

If set, we export date fields as strings that exactly match the formatting present in the DataBoundComponent from which we are exporting. Note that this will mean the values are plain strings in the spreadsheet.

The default behavior when this property is not set is to export date fields as real date values in the spreadsheet, using whichever date format is prevalent (the format specified on the field in the component, the dataSourceField or the current system default, in that order). This may result in the spreadsheet cell having a different format to the value that the user sees in the DataBoundComponent we are exporting from.

Parameters:

exportDatesAsFormattedString - exportDatesAsFormattedString Default value is null

getExportDatesAsFormattedString

public Boolean getExportDatesAsFormattedString()

Only applicable when exporting to native spreadsheet formats XLS and OOXML.

If set, we export date fields as strings that exactly match the formatting present in the DataBoundComponent from which we are exporting. Note that this will mean the values are plain strings in the spreadsheet.

The default behavior when this property is not set is to export date fields as real date values in the spreadsheet, using whichever date format is prevalent (the format specified on the field in the component, the dataSourceField or the current system default, in that order). This may result in the spreadsheet cell having a different format to the value that the user sees in the DataBoundComponent we are exporting from.

Returns:

Boolean

setExportDelimiter

public void setExportDelimiter(String exportDelimiter)

The character to use as a field-separator in CSV exports. The default delimiter is comma.

Parameters:

exportDelimiter - exportDelimiter Default value is ","

getExportDelimiter

public String getExportDelimiter()

The character to use as a field-separator in CSV exports. The default delimiter is comma.

Returns:

String

setExportDisplay

public void setExportDisplay(ExportDisplay exportDisplay)

Specifies whether the exported data will be downloaded as an attachment or displayed in a new browser window. See ExportDisplay for more information.

Parameters:

exportDisplay - exportDisplay Default value is "download"

getExportDisplay

public ExportDisplay getExportDisplay()

Specifies whether the exported data will be downloaded as an attachment or displayed in a new browser window. See ExportDisplay for more information.

Returns:

ExportDisplay

setExportFilename

public void setExportFilename(String exportFilename)

The name of the file to save the exported data into. If exportToFilesystem is set, this is the name of the file the server creates on its filesystem. If exportToClient is set, this is the filename that will appear to the browser.

Parameters:

exportFilename - exportFilename Default value is null

See Also:

setExportPath(java.lang.String)

getExportFilename

public String getExportFilename()

The name of the file to save the exported data into. If exportToFilesystem is set, this is the name of the file the server creates on its filesystem. If exportToClient is set, this is the filename that will appear to the browser.

Returns:

String

See Also:

getExportPath()

setExportFooter

public void setExportFooter(String exportFooter)

Optional text to appear at the end of the file.

Parameters:

exportFooter - exportFooter Default value is null

getExportFooter

public String getExportFooter()

Optional text to appear at the end of the file.

Returns:

String

setExportHeader

public void setExportHeader(String exportHeader)

Optional text to appear at the beginning of the file.

Parameters:

exportHeader - exportHeader Default value is null

getExportHeader

public String getExportHeader()

Optional text to appear at the beginning of the file.

Returns:

String

setExportPath

public void setExportPath(String exportPath)

If exportToFilesystem is set, optionally specifies a path to use when saving the file. This path is relative to the default export path, which is set using the server.properties setting export.location; this is the project webRoot by default. For example, with the default setting of export.location, an exportPath of "shared/ds" and an exportFilename of "exportedData.csv", Smart GWT Server would export to file $webRoot/shared/ds/exportedData.csv.

If you do not specify this property, Smart GWT Server will export to the file indicated by exportFilename directly in the default export location.

This property is only applicable when exportToFilesystem is set.

Parameters:

exportPath - exportPath Default value is null

See Also:

setExportFilename(java.lang.String)

getExportPath

public String getExportPath()

If exportToFilesystem is set, optionally specifies a path to use when saving the file. This path is relative to the default export path, which is set using the server.properties setting export.location; this is the project webRoot by default. For example, with the default setting of export.location, an exportPath of "shared/ds" and an exportFilename of "exportedData.csv", Smart GWT Server would export to file $webRoot/shared/ds/exportedData.csv.

If you do not specify this property, Smart GWT Server will export to the file indicated by exportFilename directly in the default export location.

This property is only applicable when exportToFilesystem is set.

Returns:

String

See Also:

getExportFilename()

setExportResults

public void setExportResults(Boolean exportResults)

When set, causes the results of the DSRequest to be exported to a file, whose name and format are indicated by exportFilename and exportAs respectively. When no exportFilename is provided, the default is Results and the default value of exportAs is csv.

The export field-list can also be configured, see exportFields.

Once the operation completes, exportDisplay specifies whether the exported data should be downloaded to the file-system or displayed in a new window. The default value of exportDisplay is "download" which displays the Save As dialog. See ExportDisplay for more information.

You can configure the style of line-breaks to use when generating the output, the delimiter to use when exporting to CSV and the separator-character to use in field-titles when exporting to XML.

Additionally, you can output arbitrary text before and after the exported data by setting exportHeader and exportFooter.

Note that an export initiated using dsRequest properties does not provide support for JSON format (see this post for more detail).

As well as setting dsRequest.exportResults and related properties, exports can be initiated in two other ways, via OperationBindings and via custom server code which sets export-related properties on the DSResponse. Both of those methods support exporting to JSON format.

Format Examples XML format

      <List>
          <Object>
              <id>10101</id>
              <displayName>Record 10101</displayName>
          </Object>
     </List>
  

JSON Format

      [
          { id: 10101, displayName: "Record 10101" }
      ]
  

CSV Format

      id,displayName
      10101,"Record 10101"
  

Parameters:

exportResults - exportResults Default value is false

getExportResults

public Boolean getExportResults()

When set, causes the results of the DSRequest to be exported to a file, whose name and format are indicated by exportFilename and exportAs respectively. When no exportFilename is provided, the default is Results and the default value of exportAs is csv.

The export field-list can also be configured, see exportFields.

Once the operation completes, exportDisplay specifies whether the exported data should be downloaded to the file-system or displayed in a new window. The default value of exportDisplay is "download" which displays the Save As dialog. See ExportDisplay for more information.

You can configure the style of line-breaks to use when generating the output, the delimiter to use when exporting to CSV and the separator-character to use in field-titles when exporting to XML.

Additionally, you can output arbitrary text before and after the exported data by setting exportHeader and exportFooter.

Note that an export initiated using dsRequest properties does not provide support for JSON format (see this post for more detail).

As well as setting dsRequest.exportResults and related properties, exports can be initiated in two other ways, via OperationBindings and via custom server code which sets export-related properties on the DSResponse. Both of those methods support exporting to JSON format.

Format Examples XML format

      <List>
          <Object>
              <id>10101</id>
              <displayName>Record 10101</displayName>
          </Object>
     </List>
  

JSON Format

      [
          { id: 10101, displayName: "Record 10101" }
      ]
  

CSV Format

      id,displayName
      10101,"Record 10101"
  

Returns:

Boolean

setExportTitleSeparatorChar

public void setExportTitleSeparatorChar(String exportTitleSeparatorChar)

The character with which to replace spaces in field-titles when exporting to XML.

Parameters:

exportTitleSeparatorChar - exportTitleSeparatorChar Default value is null

getExportTitleSeparatorChar

public String getExportTitleSeparatorChar()

The character with which to replace spaces in field-titles when exporting to XML.

Returns:

String

setExportToClient

public void setExportToClient(Boolean exportToClient)

If set, Smart GWT Server will export data back to the client, either as a file download or as content in a new browser window, depending on the setting of exportDisplay.

Note that it is perfectly valid to specify both this property and exportToFilesystem; in this case the data is both exported to a file on the server filesystem, and downloaded to the client. If you specify neither property, the export no-ops.

Parameters:

exportToClient - exportToClient Default value is true

getExportToClient

public Boolean getExportToClient()

If set, Smart GWT Server will export data back to the client, either as a file download or as content in a new browser window, depending on the setting of exportDisplay.

Note that it is perfectly valid to specify both this property and exportToFilesystem; in this case the data is both exported to a file on the server filesystem, and downloaded to the client. If you specify neither property, the export no-ops.

Returns:

Boolean

setExportToFilesystem

public void setExportToFilesystem(Boolean exportToFilesystem)

If set, Smart GWT Server will export data to a file on the server filesystem. The file we export to is determined by the exportFilename and exportPath.

Note that it is perfectly valid to specify both this property and exportToClient; in this case the data is both exported to a file on the server filesystem, and downloaded to the client. If you specify neither property, the export no-ops.

Parameters:

exportToFilesystem - exportToFilesystem Default value is false

getExportToFilesystem

public Boolean getExportToFilesystem()

If set, Smart GWT Server will export data to a file on the server filesystem. The file we export to is determined by the exportFilename and exportPath.

Note that it is perfectly valid to specify both this property and exportToClient; in this case the data is both exported to a file on the server filesystem, and downloaded to the client. If you specify neither property, the export no-ops.

Returns:

Boolean

setExportValueFields

public void setExportValueFields(Boolean exportValueFields)

Only applies to request properties passed to DataBoundComponent.exportClientData. Ordinarily, any fields that have a displayField defined have the value of that displayFIeld exported, rather than the underlying value in the valueField. If you set this property, we export both the underlying value and the displayField value.

Parameters:

exportValueFields - exportValueFields Default value is null

getExportValueFields

public Boolean getExportValueFields()

Only applies to request properties passed to DataBoundComponent.exportClientData. Ordinarily, any fields that have a displayField defined have the value of that displayFIeld exported, rather than the underlying value in the valueField. If you set this property, we export both the underlying value and the displayField value.

Returns:

Boolean

setLineBreakStyle

public void setLineBreakStyle(String lineBreakStyle)

The style of line-breaks to use in the exported output. See LineBreakStyle for more information.

Parameters:

lineBreakStyle - lineBreakStyle Default value is null

getLineBreakStyle

public String getLineBreakStyle()

The style of line-breaks to use in the exported output. See LineBreakStyle for more information.

Returns:

String

setOldValues

public void setOldValues(Record oldValues)

For an update or remove operation, the original values from the record that is being updated or removed. oldValues is automatically added to DSRequests submitted by DataBound Components. Available on the server via DSRequest.getOldValues().

The server can compare the oldValues to the most recent stored values in order to detect that the user was looking at stale values when the user submitted changes (NOTE: this means of detecting concurrent edit is sometimes called "optimistic concurrency" or "long transactions").

In applications where a policy of "last update wins" is not appropriate when updating certain fields, special UI can be shown for this case. For example, on detecting concurrent edit, the server may send back a special dsResponse.status code that the client application detects, offering the user a choice of proceeding with the operation, discarding edits, or reconciling new and old values in a special interface.

Parameters:

oldValues - oldValues Default value is null

getOldValues

public Record getOldValues()

For an update or remove operation, the original values from the record that is being updated or removed. oldValues is automatically added to DSRequests submitted by DataBound Components. Available on the server via DSRequest.getOldValues().

The server can compare the oldValues to the most recent stored values in order to detect that the user was looking at stale values when the user submitted changes (NOTE: this means of detecting concurrent edit is sometimes called "optimistic concurrency" or "long transactions").

In applications where a policy of "last update wins" is not appropriate when updating certain fields, special UI can be shown for this case. For example, on detecting concurrent edit, the server may send back a special dsResponse.status code that the client application detects, offering the user a choice of proceeding with the operation, discarding edits, or reconciling new and old values in a special interface.

Returns:

Record

setOperationId

public void setOperationId(String operationId)

When a DataBoundComponent sends a DSRequest, the dsRequest.operationId will be automatically picked up from the fetchOperation, addOperation, etc properties of the DataBoundComponent.

The operationId serves as an identifier that you can use to create variations on the 4 basic DataSource operations that are used by different components in different parts of your application. For example, you may be using a standard fetch operation in one part of your application, however on another screen you want to perform a fetch operation on the same DataSource but interpret search criteria differently (eg full text search).

If you declare more than one OperationBinding for the same operationType, you can specify an operationId on the operationBinding which will cause that operationBinding to be used for dsRequests containing a matching operationId. This allows all the possible settings of an operationBinding, including wsOperation or DMI settings, to be switched on a per-component or per-request basis.

For example, by setting the fetchOperation on a particular ListGrid, you could cause it to invoke a different server method via DMI, different dataURL or different web service operation.

The operationId can also be directly received by the server in order to affect behavior. When using the Smart GWT Server, operationId can be accessed via dsRequest.getOperationId(). The RestDataSource will also send the operationId to the server as part of the request metadata.

Note that if you manually invoke a DataSource operation, you can also specify operationId via the requestProperties parameter.

Note that the operationId has special significance in terms of whether two DSRequests are considered equivalent for caching and synchronization purposes - see DsRequestEquivalence.

Parameters:

operationId - operationId Default value is null

See Also:

Operations overview and related methods

getOperationId

public String getOperationId()

When a DataBoundComponent sends a DSRequest, the dsRequest.operationId will be automatically picked up from the fetchOperation, addOperation, etc properties of the DataBoundComponent.

The operationId serves as an identifier that you can use to create variations on the 4 basic DataSource operations that are used by different components in different parts of your application. For example, you may be using a standard fetch operation in one part of your application, however on another screen you want to perform a fetch operation on the same DataSource but interpret search criteria differently (eg full text search).

If you declare more than one OperationBinding for the same operationType, you can specify an operationId on the operationBinding which will cause that operationBinding to be used for dsRequests containing a matching operationId. This allows all the possible settings of an operationBinding, including wsOperation or DMI settings, to be switched on a per-component or per-request basis.

For example, by setting the fetchOperation on a particular ListGrid, you could cause it to invoke a different server method via DMI, different dataURL or different web service operation.

The operationId can also be directly received by the server in order to affect behavior. When using the Smart GWT Server, operationId can be accessed via dsRequest.getOperationId(). The RestDataSource will also send the operationId to the server as part of the request metadata.

Note that if you manually invoke a DataSource operation, you can also specify operationId via the requestProperties parameter.

Note that the operationId has special significance in terms of whether two DSRequests are considered equivalent for caching and synchronization purposes - see DsRequestEquivalence.

Returns:

String

See Also:

Operations overview and related methods

setOperationType

public void setOperationType(DSOperationType operationType)

Type of operation being performed: "fetch", "add", "remove", "update" or "custom".

This property is generally automatically populated, for example when calling fetchData() on a DataSource or DataBound component the operationType is automatically set to "fetch". Note that "custom" operations are never generated automatically, they are always fired by your code.

Parameters:

operationType - operationType Default value is null

getOperationType

public DSOperationType getOperationType()

Type of operation being performed: "fetch", "add", "remove", "update" or "custom".

This property is generally automatically populated, for example when calling fetchData() on a DataSource or DataBound component the operationType is automatically set to "fetch". Note that "custom" operations are never generated automatically, they are always fired by your code.

Returns:

DSOperationType

getRequestId

public String getRequestId()

Automatically generated unique ID for this request. This ID will be required by developers making use of the "clientCustom" dataProtocol.

Returns:

String

setStartRow

public void setStartRow(Integer startRow)

Starting row of requested results, used only with fetch operations. If unset, 0 is assumed.

Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

Parameters:

startRow - startRow Default value is null

getStartRow

public Integer getStartRow()

Starting row of requested results, used only with fetch operations. If unset, 0 is assumed.

Note that startRow and endRow are zero-based, inclusive at the beginning and exclusive at the end (like substring), so startRow: 0, endRow: 1 is a request for the first record.

Returns:

Integer

setStreamResults

public void setStreamResults(String streamResults)

If true, results will be streamed on the server, rather than all records being read into server memory at once; this approach is appropriate for retrieving or exporting large datasets without swamping the server.

Although this property can be set without any particular concerns (small datasets can be streamed just as readily as large ones), bear in mind that although streaming enables the processing of very large datasets, processing and downloading very large datasets in a normal client/server flow will very rarely give an acceptable user experience. Streaming is of more practical use in a batch setting - for example, a disconnected export.

Note that streaming requires specific server support; of Smart GWT's built-in DataSource types, only SQLDataSource is able to stream results. This property is ignored by other DataSource types.

See also the server-side documentation for DSResponse, SQLDataSource and StreamingResponseIterator.

Parameters:

streamResults - streamResults Default value is false

getStreamResults

public String getStreamResults()

If true, results will be streamed on the server, rather than all records being read into server memory at once; this approach is appropriate for retrieving or exporting large datasets without swamping the server.

Although this property can be set without any particular concerns (small datasets can be streamed just as readily as large ones), bear in mind that although streaming enables the processing of very large datasets, processing and downloading very large datasets in a normal client/server flow will very rarely give an acceptable user experience. Streaming is of more practical use in a batch setting - for example, a disconnected export.

Note that streaming requires specific server support; of Smart GWT's built-in DataSource types, only SQLDataSource is able to stream results. This property is ignored by other DataSource types.

See also the server-side documentation for DSResponse, SQLDataSource and StreamingResponseIterator.

Returns:

String

setTextMatchStyle

public void setTextMatchStyle(TextMatchStyle textMatchStyle)

For "fetch" operations, how search criteria should be interpreted for text fields: either "exact" for exact match, "startsWith" for matching at the beginning only, or "substring" for case-insensitive substring match.

This setting is respected by the built-in SQLDataSource. Your custom DataSource implementation can interpret the search criteria passed into "fetch" operations in arbitrary ways; you can safely ignore this flag and use others of your own devising.

Parameters:

textMatchStyle - textMatchStyle Default value is "exact"

getTextMatchStyle

public TextMatchStyle getTextMatchStyle()

For "fetch" operations, how search criteria should be interpreted for text fields: either "exact" for exact match, "startsWith" for matching at the beginning only, or "substring" for case-insensitive substring match.

This setting is respected by the built-in SQLDataSource. Your custom DataSource implementation can interpret the search criteria passed into "fetch" operations in arbitrary ways; you can safely ignore this flag and use others of your own devising.

Returns:

TextMatchStyle

setUseFlatFields

public void setUseFlatFields(Boolean useFlatFields)

When useFlatFields is set for a request to be sent to a WSDL web service, when creating the input XML message to send to the web service, properties in request.data will be used as the values for XML elements of the same name, at any level of nesting.

useFlatFields allows you to ignore gratuitous XML message structure, such as extra levels of nested elements, and provides some insulation against changes in the required structure of the input message.

For example, given this input message:

  <FindServices>
      <searchFor>search text</searchFor>
      <Options>
          <caseSensitive>false</caseSensitive>
      </Options>
      <IncludeInSearch>
          <serviceName>true</serviceName>
          <documentation>true</documentation>
          <keywords>true</keywords>
      </IncludeInSearch>
  </FindServices>
  

If useFlatFields were not set, in order to fill out this message correctly, request.data would need to be:

{
     searchFor: "search text",
     Options : {
         caseSensitive: false,
     },
     IncludeInSearch : {
         serviceName: true,
         documentation : true,
         keywords : true
     }
  }

However if useFlatFields were set, request.data could be just:

{
     searchFor: "search text",
     caseSensitive: false,
     serviceName: true,
     documentation : true,
     keywords : true
  }

useFlatFields is often set when the input data comes from a DynamicForm to avoid the cumbersome and fragile process of mapping input fields to an XML structure.

useFlatFields can also be set to cause all dsRequests of a particular type to useFlatFields automatically.

For DataBoundComponents, component.useFlatFields can be set use "flattened" binding to fields of a WSDL message or XML Schema.

Note that useFlatFields is not generally recommended for use with XML input messages where multiple simple type fields exist with the same name, however if used in this way, the first field to use a given name wins. "first" means the first field encountered in a depth first search. "wins" means only the first field will be populated in the generated XML message.

Parameters:

useFlatFields - useFlatFields Default value is null

getUseFlatFields

public Boolean getUseFlatFields()

When useFlatFields is set for a request to be sent to a WSDL web service, when creating the input XML message to send to the web service, properties in request.data will be used as the values for XML elements of the same name, at any level of nesting.

useFlatFields allows you to ignore gratuitous XML message structure, such as extra levels of nested elements, and provides some insulation against changes in the required structure of the input message.

For example, given this input message:

  <FindServices>
      <searchFor>search text</searchFor>
      <Options>
          <caseSensitive>false</caseSensitive>
      </Options>
      <IncludeInSearch>
          <serviceName>true</serviceName>
          <documentation>true</documentation>
          <keywords>true</keywords>
      </IncludeInSearch>
  </FindServices>
  

If useFlatFields were not set, in order to fill out this message correctly, request.data would need to be:

{
     searchFor: "search text",
     Options : {
         caseSensitive: false,
     },
     IncludeInSearch : {
         serviceName: true,
         documentation : true,
         keywords : true
     }
  }

However if useFlatFields were set, request.data could be just:

{
     searchFor: "search text",
     caseSensitive: false,
     serviceName: true,
     documentation : true,
     keywords : true
  }

useFlatFields is often set when the input data comes from a DynamicForm to avoid the cumbersome and fragile process of mapping input fields to an XML structure.

useFlatFields can also be set to cause all dsRequests of a particular type to useFlatFields automatically.

For DataBoundComponents, component.useFlatFields can be set use "flattened" binding to fields of a WSDL message or XML Schema.

Note that useFlatFields is not generally recommended for use with XML input messages where multiple simple type fields exist with the same name, however if used in this way, the first field to use a given name wins. "first" means the first field encountered in a depth first search. "wins" means only the first field will be populated in the generated XML message.

Returns:

Boolean

setUseFlatHeaderFields

public void setUseFlatHeaderFields(Boolean useFlatHeaderFields)

Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request. See also headerData.

Parameters:

useFlatHeaderFields - useFlatHeaderFields Default value is null

getUseFlatHeaderFields

public Boolean getUseFlatHeaderFields()

Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request. See also headerData.

Returns:

Boolean

setValidationMode

public void setValidationMode(ValidationMode validationMode)

Mode of validation for entered data.

Parameters:

validationMode - validationMode Default value is "full"

getValidationMode

public ValidationMode getValidationMode()

Mode of validation for entered data.

Returns:

ValidationMode

setAttribute

public void setAttribute(String property,
                         Object value)

Set a custom attribute value on the DSRequest as an Object. Note that this method converts the Java primitive Object types, Dates and Maps to the underyling JavaScriptObject value. All other object types are set as Object type attributes and users are expected to call DataClass.getAttributeAsObject(String) in order to retrieve them.

These attributes are available for client-side use only - these attributes are not transmitted to the server.

Do not use setAttribute() to set any attribute for which there is a dedicated setter (do not setAttribute("data", data) for example).

If you are looking for a way to send additional data to the server, read com.smartgwt.client.docs.DsRequestEquivalence,this overview for the best approach.

Overrides:

setAttribute in class DataClass

Parameters:

property - the attribute name

value - the attribute value.

setExportFields

public void setExportFields(String[] exportFields)

The list of field-names to export. If provided, the field-list in the exported output is limited and sorted as per the list.

If exportFields is not provided, the exported output includes all visible fields from the DataSource (field.hidden=false), sorted in the order they're defined.

Parameters:

exportFields - exportFields Default value is null

getExportFields

public String[] getExportFields()

The list of field-names to export. If provided, the field-list in the exported output is limited and sorted as per the list.

If exportFields is not provided, the exported output includes all visible fields from the DataSource (field.hidden=false), sorted in the order they're defined.

Returns:

the export fields

setParams

public void setParams(Map params)

Description copied from class: RPCRequest

Values to be sent as simple HTTP params, as a JavaScript Object where each property/value pair will become an HTTP parameter name and value. These parameters are then accessible on the server, for example, using servletRequest.getParameter(paramName) in Java Servlets.

This API is primarily used in combination with useSimpleHttp.

When contacting the Smart GWT server, setting params is an opportunity to send additional data aside from the main data payload; this is useful for adding data to DataSource requests which will be kept separate from the automatically sent DataSource data.

Note that in contrast to data object, the data in rpcRequest.params is not serialized/deserialized by the Smart GWT server, and all values arrive on the server as String type (like HTTP parameters always do).

The params value can also be a componentID or component instance that provides a method getValues() that returns an Object literal. Smart GWT components DynamicForm, ValuesManager are two such classes. Lastly, you may specify the ID of a native form element (retreivable via getElementById()) and the params will be populated from there. If there is an error resolving your params directive, it will be logged to the Developer Console.

Note: The params are submitted once per http transaction. If you are using RPCManager.startQueue() to bundle multiple RPCRequests or DSRequests into a single HTTP turnaround, the params from the various RPCRequests will be merged, with the later-queued transactions winning on parameter name collisions. A warning will be logged in the Developer Console if multiple RPCRequests specified params.

Overrides:

setParams in class RPCRequest

Parameters:

params - params Default value is null

setHeaderData

public void setHeaderData(Map headerData)

For DataSources using SOAP messaging with a WSDL web service, data to be serialized to form SOAP headers, as a map from the header part name to the data. See WSRequest.headerData for more information.

SOAP headers typically contain request metadata such as a session id for authentication, and so dsRequest.headerData is typically populated by DataSource.transformRequest(), or, for data that applies to every request sent to the server, by WebService.getHeaderData().

Parameters:

headerData - the header data

getHeaderData

public Map getHeaderData()

For DataSources using SOAP messaging with a WSDL web service, data to be serialized to form SOAP headers, as a map from the header part name to the data. See WSRequest.headerData for more information.

SOAP headers typically contain request metadata such as a session id for authentication, and so dsRequest.headerData is typically populated by DataSource.transformRequest(), or, for data that applies to every request sent to the server, by WebService.getHeaderData().

Returns:

the header data

getResultSet

public ResultSet getResultSet()

For advanced use in integrating dataset paging with web services, the ResultSet that issued this "fetch" DSRequest is automatically made available as the resultSet property.

This property can only be read. There is no meaning to setting this property yourself.

Returns:

the ResultSet

setSortBy

public void setSortBy(SortSpecifier[] sortSpecifiers)

Fieldnames to sortBy.

Parameters:

sortSpecifiers - Default value is null

getSortBy

public SortSpecifier[] getSortBy()

Fieldname to sortBy

Returns:

SortSpecifier array

setOldValues

public void setOldValues(Map oldValues)

For an update or remove operation, the original values from the record that is being updated or removed. oldValues is automatically added to DSRequests submitted by DataBound Components. Available on the server via DSRequest.getOldValues().

The server can compare the oldValues to the most recent stored values in order to detect that the user was looking at stale values when the user submitted changes (NOTE: this means of detecting concurrent edit is sometimes called "optimistic concurrency" or "long transactions").

In applications where a policy of "last update wins" is not appropriate when updating certain fields, special UI can be shown for this case. For example, on detecting concurrent edit, the server may send back a special dsResponse.status code that the client application detects, offering the user a choice of proceeding with the operation, discarding edits, or reconciling new and old values in a special interface.

Parameters:

oldValues - oldValues Default value is null

setOldValues

public void setOldValues(JavaScriptObject oldValues)

For an update or remove operation, the original values from the record that is being updated or removed. oldValues is automatically added to DSRequests submitted by DataBound Components. Available on the server via DSRequest.getOldValues().

The server can compare the oldValues to the most recent stored values in order to detect that the user was looking at stale values when the user submitted changes (NOTE: this means of detecting concurrent edit is sometimes called "optimistic concurrency" or "long transactions").

In applications where a policy of "last update wins" is not appropriate when updating certain fields, special UI can be shown for this case. For example, on detecting concurrent edit, the server may send back a special dsResponse.status code that the client application detects, offering the user a choice of proceeding with the operation, discarding edits, or reconciling new and old values in a special interface.

Parameters:

oldValues - oldValues Default value is null

getCriteria

public Criteria getCriteria()
                     throws IllegalStateException

Return the Criteria associated with a FETCH operation.

Note : This method should only be called during a FETCH operation

Returns:

the criteria

Throws:

IllegalStateException - if called for a non-fetch operation

convertToDSRequestArray

public static DSRequest[] convertToDSRequestArray(JavaScriptObject nativeArray)