com.smartgwt.client.data
Class DSRequest

java.lang.Object
  extended by com.smartgwt.client.core.JsObject
      extended by com.smartgwt.client.core.DataClass
          extended by com.smartgwt.client.rpc.RPCRequest
              extended by 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(DSOperationType operationType)
           
DSRequest(DSOperationType operationType, Criteria criteria)
           
DSRequest(DSOperationType operationType, com.google.gwt.core.client.JavaScriptObject data)
           
DSRequest(DSOperationType operationType, Record data)
           
DSRequest(DSOperationType operationType, java.lang.String operationId)
           
DSRequest(DSOperationType operationType, java.lang.String operationId, Criteria criteria)
           
DSRequest(DSOperationType operationType, java.lang.String operationId, com.google.gwt.core.client.JavaScriptObject data)
           
DSRequest(DSOperationType operationType, java.lang.String operationId, Record data)
           
DSRequest(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 
Method Summary
 java.lang.String getAdditionalOutputs()
          For fetch, add or update operation, an optional comma separated list of fields to fetch from another, related DataSource.
 java.lang.String getComponentId()
          For requests submitted by a DataBoundComponent, the ID of the submitting component.
 Criteria getCriteria()
          Return the Criteria associated with a FETCH operation.
 java.lang.String getDataSource()
          DataSource this DSRequest will act on.
 java.lang.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 ListGrid.exportClientData.
 java.lang.Boolean getExportDatesAsFormattedString()
          When exporting via ListGrid.exportClientData to an XLS or OOXML spreadsheet, forces dates to export as a string rather than a true date value.
 java.lang.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.
 java.lang.String[] getExportFields()
          The list of field-names to export.
 java.lang.String getExportFilename()
          The name of the file to save the exported data into.
 java.lang.String getExportFooter()
          Optional text to appear at the end of the file.
 java.lang.String getExportHeader()
          Optional text to appear at the beginning of the file.
 java.lang.Boolean getExportHeaderless()
          This property allows omitting column names from CSV and Excel exports (no effect on JSON or XML exports).
 ExportImageFormat getExportImageFormat()
          The image format in which the SVG graphic should be exported.
 java.lang.Float getExportImageQuality()
          Deprecated. GwtFloatVsDouble
 java.lang.Double getExportImageQualityAsDouble()
          If exporting in JPEG format, the output JPEG quality level.
 java.lang.String getExportPath()
          If exportToFilesystem is set, optionally specifies a path to use when saving the file.
 java.lang.Boolean getExportRawValues()
          Whether formatting settings should be applied to data being exported.
 java.lang.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.
 java.lang.Boolean getExportShowHeaderSpanTitles()
          When you erxport a ListGrid that has headerSpans, should headerSpans also be exported.
 java.lang.String getExportSpanTitleSeparator()
          When you export a ListGrid that has headerSpans defined and exportShowHeaderSpanTitles is true, the behavior is dependent on the export type.
 java.lang.String getExportTitleSeparatorChar()
          The character with which to replace spaces in field-titles when exporting to XML.
 java.lang.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.
 java.lang.Boolean getExportToFilesystem()
          If set, Smart GWT Server will export data to a file on the server filesystem.
 java.lang.Boolean getExportValueFields()
          Only applies to request properties passed to ListGrid.exportClientData.
 java.lang.Boolean getGenerateRelatedUpdates()
          Specifies should related updates have to be generated.
 java.lang.String[] getGroupBy()
          List of fields to group by when using server-side summarization.
 java.util.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.
 java.lang.Boolean getKeepParentsOnFilter()
          This property is for advanced use in integrating trees that load data on demand using data paging.
 java.lang.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.
 java.lang.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(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 java.lang.String getOutputs()
          The list of fields to return in the response, specified as a comma-separated string (eg, "foo, bar, baz").
 TreeNode getParentNode()
          For advanced use in integrating trees that load data on demand with web services, parentNode is automatically set in "fetch" DSRequests issued by a databound TreeGrid that is loading children for that parentNode.
 java.lang.Boolean getPendingAdd()
          Indicates that a validation request is being made for a record that will ultimately be saved with an "add" request, as opposed to an "update" request.
 java.lang.Boolean getProgressiveLoading()
          Sets progressive loading mode for this specific request, overriding the OperationBinding- and DataSource-level settings.
 java.lang.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.
 ResultTree getResultTree()
          For advanced use in integrating trees that load data on demand with web services, the ResultTree that issued this "fetch" DSRequest is automatically made available as the resultTree property.
 java.lang.Boolean getShouldUseCache()
          This is a per-request flag for explicitly controlling whether the cache is used (bypassing it when not wanted, or using it when settings would indicate otherwise).
 SortSpecifier[] getSortBy()
          Fieldname to sortBy
 java.lang.Integer getStartRow()
          Starting row of requested results, used only with fetch operations.
 java.lang.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.
 java.util.Map<java.lang.String,SummaryFunctionType> getSummaryFunctions()
          A mapping from field names to summary functions to be applied to each field.
 TextMatchStyle getTextMatchStyle()
          For "fetch" operations, how search criteria should be interpreted for text fields: one of "exact" for exact match, "exactCase" for case-sensitive exact match, "startsWith" for matching at the beginning only, or "substring" for substring match.
 java.lang.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.
 java.lang.Boolean getUseFlatHeaderFields()
          Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request.
 java.lang.Boolean getUseStrictJSON()
          Should the HTTP response to this request be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.
 ValidationMode getValidationMode()
          Mode of validation for entered data.
 void setAdditionalOutputs(java.lang.String additionalOutputs)
          For fetch, add or update operation, an optional comma separated list of fields to fetch from another, related DataSource.
 void setAttribute(java.lang.String property, java.lang.Object value)
          Set a custom attribute value on the DSRequest as an Object.
 void setComponentId(java.lang.String componentId)
          For requests submitted by a DataBoundComponent, the ID of the submitting component.
 void setCriteria(Criteria criteria)
          This method applies to "fetch" requests only; for update or delete operations pass a Record to setData() which contains primaryKey values as Record attributes.
 void setDataSource(java.lang.String dataSource)
          DataSource this DSRequest will act on.
 void setEndRow(java.lang.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 ListGrid.exportClientData.
 void setExportDatesAsFormattedString(java.lang.Boolean exportDatesAsFormattedString)
          When exporting via ListGrid.exportClientData to an XLS or OOXML spreadsheet, forces dates to export as a string rather than a true date value.
 void setExportDelimiter(java.lang.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(java.lang.String... exportFields)
          The list of field-names to export.
 void setExportFilename(java.lang.String exportFilename)
          The name of the file to save the exported data into.
 void setExportFooter(java.lang.String exportFooter)
          Optional text to appear at the end of the file.
 void setExportHeader(java.lang.String exportHeader)
          Optional text to appear at the beginning of the file.
 void setExportHeaderless(java.lang.Boolean exportHeaderless)
          This property allows omitting column names from CSV and Excel exports (no effect on JSON or XML exports).
 void setExportImageFormat(ExportImageFormat exportImageFormat)
          The image format in which the SVG graphic should be exported.
 void setExportImageQuality(java.lang.Double exportImageQuality)
          If exporting in JPEG format, the output JPEG quality level.
 void setExportImageQuality(java.lang.Float exportImageQuality)
          Deprecated. GwtFloatVsDouble
 void setExportPath(java.lang.String exportPath)
          If exportToFilesystem is set, optionally specifies a path to use when saving the file.
 void setExportRawValues(java.lang.Boolean exportRawValues)
          Whether formatting settings should be applied to data being exported.
 void setExportResults(java.lang.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 setExportShowHeaderSpanTitles(java.lang.Boolean exportShowHeaderSpanTitles)
          When you erxport a ListGrid that has headerSpans, should headerSpans also be exported.
 void setExportSpanTitleSeparator(java.lang.String exportSpanTitleSeparator)
          When you export a ListGrid that has headerSpans defined and exportShowHeaderSpanTitles is true, the behavior is dependent on the export type.
 void setExportTitleSeparatorChar(java.lang.String exportTitleSeparatorChar)
          The character with which to replace spaces in field-titles when exporting to XML.
 void setExportToClient(java.lang.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(java.lang.Boolean exportToFilesystem)
          If set, Smart GWT Server will export data to a file on the server filesystem.
 void setExportValueFields(java.lang.Boolean exportValueFields)
          Only applies to request properties passed to ListGrid.exportClientData.
 void setGenerateRelatedUpdates(java.lang.Boolean generateRelatedUpdates)
          Specifies should related updates have to be generated.
 void setGroupBy(java.lang.String... groupBy)
          List of fields to group by when using server-side summarization.
 void setHeaderData(java.util.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 setKeepParentsOnFilter(java.lang.Boolean keepParentsOnFilter)
          This property is for advanced use in integrating trees that load data on demand using data paging.
 void setLineBreakStyle(java.lang.String lineBreakStyle)
          The style of line-breaks to use in the exported output.
 void setOldValues(com.google.gwt.core.client.JavaScriptObject oldValues)
          For an update or remove operation, the original values from the record that is being updated or removed.
 void setOldValues(java.util.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(java.lang.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 setOutputs(java.lang.String outputs)
          The list of fields to return in the response, specified as a comma-separated string (eg, "foo, bar, baz").
 void setParams(java.util.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 setPendingAdd(java.lang.Boolean pendingAdd)
          Indicates that a validation request is being made for a record that will ultimately be saved with an "add" request, as opposed to an "update" request.
 void setProgressiveLoading(java.lang.Boolean progressiveLoading)
          Sets progressive loading mode for this specific request, overriding the OperationBinding- and DataSource-level settings.
 void setShouldUseCache(java.lang.Boolean shouldUseCache)
          This is a per-request flag for explicitly controlling whether the cache is used (bypassing it when not wanted, or using it when settings would indicate otherwise).
 void setSkinName(java.lang.String skinName)
          Set the skin to use.
 void setSortBy(SortSpecifier[] sortSpecifiers)
          Fieldnames to sortBy.
 void setStartRow(java.lang.Integer startRow)
          Starting row of requested results, used only with fetch operations.
 void setStreamResults(java.lang.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 setSummaryFunctions(java.util.Map<java.lang.String,SummaryFunctionType> summaryFunctions)
          A mapping from field names to summary functions to be applied to each field.
 void setTextMatchStyle(TextMatchStyle textMatchStyle)
          For "fetch" operations, how search criteria should be interpreted for text fields: one of "exact" for exact match, "exactCase" for case-sensitive exact match, "startsWith" for matching at the beginning only, or "substring" for substring match.
 void setUseFlatFields(java.lang.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(java.lang.Boolean useFlatHeaderFields)
          Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request.
 void setUseStrictJSON(java.lang.Boolean useStrictJSON)
          Should the HTTP response to this request be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.
 void setValidationMode(ValidationMode validationMode)
          Mode of validation for entered data.
 
Methods inherited from class com.smartgwt.client.rpc.RPCRequest
create, getActionURL, getAllowIE9Leak, getBypassCache, getCallbackParam, getContainsCredentials, getContentType, getData, getDataAsString, getDownloadResult, getDownloadToNewWindow, getEvalResult, getHttpHeaders, getHttpMethod, getIgnoreTimeout, getOmitNullMapValuesInResponse, getPrompt, getPromptCursor, getPromptDelay, getPromptStyle, getSendNoQueue, getServerOutputAsString, getShowPrompt, getSuppressAutoDraw, getTimeout, getTransport, getUseHttpProxy, getUseSimpleHttp, getWillHandleError, setActionURL, setAllowIE9Leak, setBypassCache, setCallbackParam, setContainsCredentials, setContentType, setData, setData, setData, setData, setDownloadResult, setDownloadToNewWindow, setEvalResult, setEvalVars, setHttpHeaders, setHttpMethod, setIgnoreTimeout, setOmitNullMapValuesInResponse, setPrompt, setPromptCursor, setPromptDelay, setPromptStyle, setSendNoQueue, setServerOutputAsString, setShowPrompt, setSuppressAutoDraw, setTimeout, setTransport, setUseHttpProxy, setUseSimpleHttp, setWillHandleError
 
Methods inherited from class com.smartgwt.client.core.DataClass
doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject
 
Methods inherited from class com.smartgwt.client.core.JsObject
equals, getJsObj, hashCode, isCreated, setJavaScriptObject, setJsObj
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DSRequest

public DSRequest()

DSRequest

public DSRequest(com.google.gwt.core.client.JavaScriptObject jsObj)

DSRequest

public DSRequest(DSOperationType operationType)

DSRequest

public DSRequest(DSOperationType operationType,
                 java.lang.String operationId)

DSRequest

public DSRequest(DSOperationType operationType,
                 Record data)

DSRequest

public DSRequest(DSOperationType operationType,
                 java.lang.String operationId,
                 Record data)

DSRequest

public DSRequest(DSOperationType operationType,
                 com.google.gwt.core.client.JavaScriptObject data)

DSRequest

public DSRequest(DSOperationType operationType,
                 java.lang.String operationId,
                 com.google.gwt.core.client.JavaScriptObject data)

DSRequest

public DSRequest(DSOperationType operationType,
                 Criteria criteria)

DSRequest

public DSRequest(DSOperationType operationType,
                 java.lang.String operationId,
                 Criteria criteria)
Method Detail

getOrCreateRef

public static DSRequest getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

setAdditionalOutputs

public void setAdditionalOutputs(java.lang.String additionalOutputs)
For fetch, add or update 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 additionalOutputs sent in request from the browser can be completely disabled in server.properties by setting datasource.allowClientAdditionalOutputs:

      datasource.allowClientAdditionalOutputs: false
  
In this case additionalOutputs sent from the browser will be cleared before executing request. Note that programatically configured additionalOutputs are always allowed, but you can't modify them from within a DMI method, so the only way to execute a request with additionalOutputs that differ from what was sent by the client is to create a new DSRequest

Note : This is an advanced setting

Parameters:
additionalOutputs - Default value is null

getAdditionalOutputs

public java.lang.String getAdditionalOutputs()
For fetch, add or update 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 additionalOutputs sent in request from the browser can be completely disabled in server.properties by setting datasource.allowClientAdditionalOutputs:

      datasource.allowClientAdditionalOutputs: false
  
In this case additionalOutputs sent from the browser will be cleared before executing request. Note that programatically configured additionalOutputs are always allowed, but you can't modify them from within a DMI method, so the only way to execute a request with additionalOutputs that differ from what was sent by the client is to create a new DSRequest

Returns:
String

setComponentId

public void setComponentId(java.lang.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.

This property should be used for debugging purposes only - do not use it to trigger differences in server-side behavior, instead, use operationId because only operationId is considered when assessing request equivalence.

Parameters:
componentId - Default value is null

getComponentId

public java.lang.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.

This property should be used for debugging purposes only - do not use it to trigger differences in server-side behavior, instead, use operationId because only operationId is considered when assessing request equivalence.

Returns:
String

setDataSource

public void setDataSource(java.lang.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 - Default value is null

getDataSource

public java.lang.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(java.lang.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 - Default value is null

getEndRow

public java.lang.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 - 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 ListGrid.exportClientData. If specified this property contains an arbitrary set of data to be exported.

Parameters:
exportData - Default value is null

getExportData

public Record[] getExportData()
Only applies to request properties passed to ListGrid.exportClientData. If specified this property contains an arbitrary set of data to be exported.

Returns:
Record...

setExportDatesAsFormattedString

public void setExportDatesAsFormattedString(java.lang.Boolean exportDatesAsFormattedString)
When exporting via ListGrid.exportClientData to an XLS or OOXML spreadsheet, forces dates to export as a string rather than a true date value.

If a date value is provided to a spreadsheet as a string, Excel or other spreadsheet applications may not recognize them as being date values that are valid for use in date-specific functions in formulas, filters, etc.

For this reason, the default behavior of exportClientData is to provide date values to the spreadsheet as true date values. If Format Strings are provided via properties like dataSourceField.format these will be translated to Excel / OpenOffice format strings and used when generating spreadsheets. Other formatting logic, such as cell formatters, will not be used since they cannot be automatically translated to an Excel format string. If no translatable format string is available, date values will be provided to the spreadsheet with no formatter and the spreadsheet program's default formatting for date values will be used.

If exportDatesAsFormattedString is set to true, date fields will appear as strings that exactly match the formatting shown in the DataBoundComponent. As noted above, this means the spreadsheet program will not recognize the value as a date.

Parameters:
exportDatesAsFormattedString - Default value is null
See Also:
ExportFormatting overview and related methods

getExportDatesAsFormattedString

public java.lang.Boolean getExportDatesAsFormattedString()
When exporting via ListGrid.exportClientData to an XLS or OOXML spreadsheet, forces dates to export as a string rather than a true date value.

If a date value is provided to a spreadsheet as a string, Excel or other spreadsheet applications may not recognize them as being date values that are valid for use in date-specific functions in formulas, filters, etc.

For this reason, the default behavior of exportClientData is to provide date values to the spreadsheet as true date values. If Format Strings are provided via properties like dataSourceField.format these will be translated to Excel / OpenOffice format strings and used when generating spreadsheets. Other formatting logic, such as cell formatters, will not be used since they cannot be automatically translated to an Excel format string. If no translatable format string is available, date values will be provided to the spreadsheet with no formatter and the spreadsheet program's default formatting for date values will be used.

If exportDatesAsFormattedString is set to true, date fields will appear as strings that exactly match the formatting shown in the DataBoundComponent. As noted above, this means the spreadsheet program will not recognize the value as a date.

Returns:
Boolean
See Also:
ExportFormatting overview and related methods

setExportDelimiter

public void setExportDelimiter(java.lang.String exportDelimiter)
The character to use as a field-separator in CSV exports. The default delimiter is comma.

Parameters:
exportDelimiter - Default value is ","

getExportDelimiter

public java.lang.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 - 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

setExportFields

public void setExportFields(java.lang.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 - Default value is null

getExportFields

public java.lang.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:
String...

setExportFilename

public void setExportFilename(java.lang.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 - Default value is null
See Also:
setExportPath(java.lang.String)

getExportFilename

public java.lang.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(java.lang.String exportFooter)
Optional text to appear at the end of the file.

Parameters:
exportFooter - Default value is null

getExportFooter

public java.lang.String getExportFooter()
Optional text to appear at the end of the file.

Returns:
String

setExportHeader

public void setExportHeader(java.lang.String exportHeader)
Optional text to appear at the beginning of the file.

Parameters:
exportHeader - Default value is null

getExportHeader

public java.lang.String getExportHeader()
Optional text to appear at the beginning of the file.

Returns:
String

setExportHeaderless

public void setExportHeaderless(java.lang.Boolean exportHeaderless)
This property allows omitting column names from CSV and Excel exports (no effect on JSON or XML exports).

Parameters:
exportHeaderless - Default value is false

getExportHeaderless

public java.lang.Boolean getExportHeaderless()
This property allows omitting column names from CSV and Excel exports (no effect on JSON or XML exports).

Returns:
Boolean

setExportImageFormat

public void setExportImageFormat(ExportImageFormat exportImageFormat)
The image format in which the SVG graphic should be exported.

Parameters:
exportImageFormat - Default value is "png"

getExportImageFormat

public ExportImageFormat getExportImageFormat()
The image format in which the SVG graphic should be exported.

Returns:
ExportImageFormat

setExportImageQuality

public void setExportImageQuality(java.lang.Float exportImageQuality)
Deprecated. GwtFloatVsDouble

If exporting in JPEG format, the output JPEG quality level. This is a number from 0 to 1, with 1 representing the best quality and 0 representing the least quality but smallest file size.

Parameters:
exportImageQuality - Default value is null

getExportImageQuality

public java.lang.Float getExportImageQuality()
Deprecated. GwtFloatVsDouble

If exporting in JPEG format, the output JPEG quality level. This is a number from 0 to 1, with 1 representing the best quality and 0 representing the least quality but smallest file size.

Returns:
Float

setExportImageQuality

public void setExportImageQuality(java.lang.Double exportImageQuality)
If exporting in JPEG format, the output JPEG quality level. This is a number from 0 to 1, with 1 representing the best quality and 0 representing the least quality but smallest file size.

Parameters:
exportImageQuality - Default value is null

getExportImageQualityAsDouble

public java.lang.Double getExportImageQualityAsDouble()
If exporting in JPEG format, the output JPEG quality level. This is a number from 0 to 1, with 1 representing the best quality and 0 representing the least quality but smallest file size.

Returns:
Double

setExportPath

public void setExportPath(java.lang.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 - Default value is null
See Also:
setExportFilename(java.lang.String)

getExportPath

public java.lang.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()

setExportRawValues

public void setExportRawValues(java.lang.Boolean exportRawValues)
Whether formatting settings should be applied to data being exported. Default behavior and the effect of setting of exportRawValues is described in the Export Formatting overview.

Parameters:
exportRawValues - Default value is null
See Also:
ExportFormatting overview and related methods

getExportRawValues

public java.lang.Boolean getExportRawValues()
Whether formatting settings should be applied to data being exported. Default behavior and the effect of setting of exportRawValues is described in the Export Formatting overview.

Returns:
Boolean
See Also:
ExportFormatting overview and related methods

setExportResults

public void setExportResults(java.lang.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. Formats for exported date and numeric are controlled by several settings - see ExportFormatting for an overview.

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 for security reasons, 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 - Default value is false

getExportResults

public java.lang.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. Formats for exported date and numeric are controlled by several settings - see ExportFormatting for an overview.

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 for security reasons, 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

setExportShowHeaderSpanTitles

public void setExportShowHeaderSpanTitles(java.lang.Boolean exportShowHeaderSpanTitles)
When you erxport a ListGrid that has headerSpans, should headerSpans also be exported. See exportSpanTitleSeparator for details of of what it means to export headerSpans to different export targets.

Parameters:
exportShowHeaderSpanTitles - Default value is true

getExportShowHeaderSpanTitles

public java.lang.Boolean getExportShowHeaderSpanTitles()
When you erxport a ListGrid that has headerSpans, should headerSpans also be exported. See exportSpanTitleSeparator for details of of what it means to export headerSpans to different export targets.

Returns:
Boolean

setExportSpanTitleSeparator

public void setExportSpanTitleSeparator(java.lang.String exportSpanTitleSeparator)
When you export a ListGrid that has headerSpans defined and exportShowHeaderSpanTitles is true, the behavior is dependent on the export type. Direct exports to Excel formats (both XLS and OOXML) place the headerSpans in merged cells in the spreadsheet, giving the same visual effect as the original ListGrid. This is not possible with exports to CSV format; instead, we alter the exported headers so that they contain the titles of the ancestor headerSpan(s).

For example, if you had a field titled "Population" inside a headerSpan titled "National", nested inside another headerSpan titled "Demographics", that would result in the exported field being titled "Demographics - National - Population".

The exportSpanTitleSeparator property allows you to override the separator string used when constructing these amalgamated headers.

Parameters:
exportSpanTitleSeparator - Default value is " - "

getExportSpanTitleSeparator

public java.lang.String getExportSpanTitleSeparator()
When you export a ListGrid that has headerSpans defined and exportShowHeaderSpanTitles is true, the behavior is dependent on the export type. Direct exports to Excel formats (both XLS and OOXML) place the headerSpans in merged cells in the spreadsheet, giving the same visual effect as the original ListGrid. This is not possible with exports to CSV format; instead, we alter the exported headers so that they contain the titles of the ancestor headerSpan(s).

For example, if you had a field titled "Population" inside a headerSpan titled "National", nested inside another headerSpan titled "Demographics", that would result in the exported field being titled "Demographics - National - Population".

The exportSpanTitleSeparator property allows you to override the separator string used when constructing these amalgamated headers.

Returns:
String

setExportTitleSeparatorChar

public void setExportTitleSeparatorChar(java.lang.String exportTitleSeparatorChar)
The character with which to replace spaces in field-titles when exporting to XML.

Parameters:
exportTitleSeparatorChar - Default value is null

getExportTitleSeparatorChar

public java.lang.String getExportTitleSeparatorChar()
The character with which to replace spaces in field-titles when exporting to XML.

Returns:
String

setExportToClient

public void setExportToClient(java.lang.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 - Default value is true

getExportToClient

public java.lang.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(java.lang.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.

It is possible to redirect the filesystem export to make use of an OutputStream you provide. You use this when you want to make some use of the export document other than writing it to a disk file - for example, attaching it to an email or writing it to a database table. See the server-side Javadocs for DSRequest.setExportTo().

Parameters:
exportToFilesystem - Default value is false

getExportToFilesystem

public java.lang.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.

It is possible to redirect the filesystem export to make use of an OutputStream you provide. You use this when you want to make some use of the export document other than writing it to a disk file - for example, attaching it to an email or writing it to a database table. See the server-side Javadocs for DSRequest.setExportTo().

Returns:
Boolean

setExportValueFields

public void setExportValueFields(java.lang.Boolean exportValueFields)
Only applies to request properties passed to ListGrid.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 - Default value is null

getExportValueFields

public java.lang.Boolean getExportValueFields()
Only applies to request properties passed to ListGrid.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

setGenerateRelatedUpdates

public void setGenerateRelatedUpdates(java.lang.Boolean generateRelatedUpdates)
Specifies should related updates have to be generated. If not set (or set to null) then related updates will be generated only for "add" and "update" operations. This property has to be explicitly set to true to generate related updates for "remove" operation.

This functionality loads related objects from database thus affecting operation performance. For "add" and "update" operations related objects are loaded anyway and performance impact is minimal. Simple "remove" operation does not need to load related objects. Depending on database structure performance impact can be significant if this property is set to true.

Note this feature works only with Hibernate/JPA data sources, see JPA & Hibernate Relations for instructions how to set up relations. Table below uses "country -> cities" sample data model.

Relation and Operation type Loading complete related objects Loading related IDs
Many-to-one (cities -> country): ADD/UPDATE If operation affected country, for example new city added with existing countryId, then relatedUpdate is generated. Otherwise if city is added or updated without countryId set, relatedUpdate is not generated.
Note that if provided countryId does not exist, it is created.
Same as with complete related objects, except if provided countryId does not exist, then it is not created, but reset to NULL.
Many-to-one (cities -> country): REMOVE Removes record, depending on setting generates or not relatedUpdate for parent record. For example if city record is removed and countryId is sent to the server in remove request, then country record will be generated in relatedUpdates.
One-to-many (country -> cities): ADD/UPDATE If add or update operation provides value sets for cities as well as for country, then cities are created/updated if necessary and relatedUpdates are generated.
Note that all fields in cities value sets can be sent to server.
Same as with complete related objects, except you can only sent primary key values for cities.
One-to-many (country -> cities): REMOVE Removes country, depending on setting returns or not relatedUpdates for the cities of removed country, which can be either REMOVE operations of all cities if cascade enabled, or UPDATE operations setting countryId=null to all cities if cascade is disabled

Note that Many-to-Many works the same way as One-to-Many.

Parameters:
generateRelatedUpdates - Default value is null

getGenerateRelatedUpdates

public java.lang.Boolean getGenerateRelatedUpdates()
Specifies should related updates have to be generated. If not set (or set to null) then related updates will be generated only for "add" and "update" operations. This property has to be explicitly set to true to generate related updates for "remove" operation.

This functionality loads related objects from database thus affecting operation performance. For "add" and "update" operations related objects are loaded anyway and performance impact is minimal. Simple "remove" operation does not need to load related objects. Depending on database structure performance impact can be significant if this property is set to true.

Note this feature works only with Hibernate/JPA data sources, see JPA & Hibernate Relations for instructions how to set up relations. Table below uses "country -> cities" sample data model.

Relation and Operation type Loading complete related objects Loading related IDs
Many-to-one (cities -> country): ADD/UPDATE If operation affected country, for example new city added with existing countryId, then relatedUpdate is generated. Otherwise if city is added or updated without countryId set, relatedUpdate is not generated.
Note that if provided countryId does not exist, it is created.
Same as with complete related objects, except if provided countryId does not exist, then it is not created, but reset to NULL.
Many-to-one (cities -> country): REMOVE Removes record, depending on setting generates or not relatedUpdate for parent record. For example if city record is removed and countryId is sent to the server in remove request, then country record will be generated in relatedUpdates.
One-to-many (country -> cities): ADD/UPDATE If add or update operation provides value sets for cities as well as for country, then cities are created/updated if necessary and relatedUpdates are generated.
Note that all fields in cities value sets can be sent to server.
Same as with complete related objects, except you can only sent primary key values for cities.
One-to-many (country -> cities): REMOVE Removes country, depending on setting returns or not relatedUpdates for the cities of removed country, which can be either REMOVE operations of all cities if cascade enabled, or UPDATE operations setting countryId=null to all cities if cascade is disabled

Note that Many-to-Many works the same way as One-to-Many.

Returns:
Boolean

setGroupBy

public void setGroupBy(java.lang.String... groupBy)
List of fields to group by when using server-side summarization.

Valid only for an operation of type "fetch". See the Server Summaries overview for details and examples of usage.

Parameters:
groupBy - Default value is null
See Also:
setSummaryFunctions(java.util.Map), ServerSummaries overview and related methods

getGroupBy

public java.lang.String[] getGroupBy()
List of fields to group by when using server-side summarization.

Valid only for an operation of type "fetch". See the Server Summaries overview for details and examples of usage.

Returns:
String...
See Also:
getSummaryFunctions(), ServerSummaries overview and related methods

setHeaderData

public void setHeaderData(java.util.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 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.

Note that this only applies to SOAP headers. General HTTP headers for requests may be modified using httpHeaders.

Parameters:
headerData - Default value is null

getHeaderData

public java.util.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 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.

Note that this only applies to SOAP headers. General HTTP headers for requests may be modified using httpHeaders.

Returns:
Map

setKeepParentsOnFilter

public void setKeepParentsOnFilter(java.lang.Boolean keepParentsOnFilter)
This property is for advanced use in integrating trees that load data on demand using data paging. When this flag is set, a server fetch operation is expected to return all of the tree nodes that either match the provided criteria or have one or more children that match the criteria.

A ResultTree with fetchMode:"paged" and with keepParentsOnFilter enabled will automatically set this property to true on all DSRequests that it sends to the server.

Currently, no built-in server-side connectors (SQL, JPA, Hibernate) implement support for the keepParentsOnFilter flag.

Parameters:
keepParentsOnFilter - Default value is null
See Also:
TreeDataBinding overview and related methods

getKeepParentsOnFilter

public java.lang.Boolean getKeepParentsOnFilter()
This property is for advanced use in integrating trees that load data on demand using data paging. When this flag is set, a server fetch operation is expected to return all of the tree nodes that either match the provided criteria or have one or more children that match the criteria.

A ResultTree with fetchMode:"paged" and with keepParentsOnFilter enabled will automatically set this property to true on all DSRequests that it sends to the server.

Currently, no built-in server-side connectors (SQL, JPA, Hibernate) implement support for the keepParentsOnFilter flag.

Returns:
Boolean
See Also:
TreeDataBinding overview and related methods

setLineBreakStyle

public void setLineBreakStyle(java.lang.String lineBreakStyle)
The style of line-breaks to use in the exported output. See LineBreakStyle for more information.

Parameters:
lineBreakStyle - Default value is null

getLineBreakStyle

public java.lang.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 - 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(java.lang.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 - Default value is null
See Also:
Operations overview and related methods

getOperationId

public java.lang.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 - 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

setOutputs

public void setOutputs(java.lang.String outputs)
The list of fields to return in the response, specified as a comma-separated string (eg, "foo, bar, baz"). You can use this property to indicate to the server that you are only interested in a subset of the fields that would normally be returned.

Note that you cannot use this property to request a superset of the fields that would normally be returned, because that would be a security hole. It is possible to configure individual OperationBindings to return extra fields, but this must be done in the server's DataSource descriptor; it cannot be altered on the fly from the client side.

Parameters:
outputs - Default value is null
See Also:
OperationBinding.outputs, setAdditionalOutputs(java.lang.String)

getOutputs

public java.lang.String getOutputs()
The list of fields to return in the response, specified as a comma-separated string (eg, "foo, bar, baz"). You can use this property to indicate to the server that you are only interested in a subset of the fields that would normally be returned.

Note that you cannot use this property to request a superset of the fields that would normally be returned, because that would be a security hole. It is possible to configure individual OperationBindings to return extra fields, but this must be done in the server's DataSource descriptor; it cannot be altered on the fly from the client side.

Returns:
String
See Also:
OperationBinding.outputs, getAdditionalOutputs()

getParentNode

public TreeNode getParentNode()
For advanced use in integrating trees that load data on demand with web services, parentNode is automatically set in "fetch" DSRequests issued by a databound TreeGrid that is loading children for that parentNode.

This is sometimes needed if a web service requires that additional properties beyond the ID of the parentNode must be passed in order to accomplished level-by-level loading. A custom implementation of DataSource.transformRequest can access dsRequest.parentNode and add any such properties to data.

parentNode will also be automatically set by a TreeGrid performing databound reparenting of nodes, as implemented by TreeGrid.folderDrop.

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

Returns:
TreeNode

setPendingAdd

public void setPendingAdd(java.lang.Boolean pendingAdd)
Indicates that a validation request is being made for a record that will ultimately be saved with an "add" request, as opposed to an "update" request. This context is necessary for some validators because the nature of the validation depends on whether we are adding or updating a record. The system sets this flag when processing interim validations, such as those fired when validateOnChange is in force.

Parameters:
pendingAdd - Default value is null

getPendingAdd

public java.lang.Boolean getPendingAdd()
Indicates that a validation request is being made for a record that will ultimately be saved with an "add" request, as opposed to an "update" request. This context is necessary for some validators because the nature of the validation depends on whether we are adding or updating a record. The system sets this flag when processing interim validations, such as those fired when validateOnChange is in force.

Returns:
Boolean

setProgressiveLoading

public void setProgressiveLoading(java.lang.Boolean progressiveLoading)
Sets progressive loading mode for this specific request, overriding the OperationBinding- and DataSource-level settings. Note that this setting applies only to fetch requests - it has no effect if specified on any other kind of request.

Parameters:
progressiveLoading - Default value is null
See Also:
DataSource.setProgressiveLoading(java.lang.Boolean), OperationBinding.progressiveLoading, ProgressiveLoading overview and related methods

getProgressiveLoading

public java.lang.Boolean getProgressiveLoading()
Sets progressive loading mode for this specific request, overriding the OperationBinding- and DataSource-level settings. Note that this setting applies only to fetch requests - it has no effect if specified on any other kind of request.

Returns:
Boolean
See Also:
DataSource.getProgressiveLoading(), OperationBinding.progressiveLoading, ProgressiveLoading overview and related methods

getRequestId

public java.lang.String getRequestId()
Automatically generated unique ID for this request. This ID will be required by developers making use of the "clientCustom" dataProtocol.

Returns:
String

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:
ResultSet

getResultTree

public ResultTree getResultTree()
For advanced use in integrating trees that load data on demand with web services, the ResultTree that issued this "fetch" DSRequest is automatically made available as the resultTree property.

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

Returns:
ResultTree

setShouldUseCache

public void setShouldUseCache(java.lang.Boolean shouldUseCache)
This is a per-request flag for explicitly controlling whether the cache is used (bypassing it when not wanted, or using it when settings would indicate otherwise). See cacheAllData, cacheAllOperationId and cacheAcrossOperationIds for caching management for all requests of a dataSource.

Parameters:
shouldUseCache - Default value is null

getShouldUseCache

public java.lang.Boolean getShouldUseCache()
This is a per-request flag for explicitly controlling whether the cache is used (bypassing it when not wanted, or using it when settings would indicate otherwise). See cacheAllData, cacheAllOperationId and cacheAcrossOperationIds for caching management for all requests of a dataSource.

Returns:
Boolean

setStartRow

public void setStartRow(java.lang.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 - Default value is null

getStartRow

public java.lang.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(java.lang.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 - Default value is false

getStreamResults

public java.lang.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: one of "exact" for exact match, "exactCase" for case-sensitive exact match, "startsWith" for matching at the beginning only, or "substring" for substring match. All textMatchStyle settings except "exactCase" are case-insensitive; use AdvancedCriteria for greater control over matching.

This property defaults to the value of defaultTextMatchStyle if it is not explicitly provided on the DSRequest. Note, however, that DSRequests issued by ListGrids and other components will generally have a setting for textMatchStyle on the component itself (see autoFetchTextMatchStyle, for example).

This setting is respected by the built-in server-side connectors for SQL, JPA and Hibernate. A custom server-side DataSource implementation should generally respect this flag as well, or server-side filtering will not match client-side filtering, which will require disabling client-side filtering, a huge performance loss.

Parameters:
textMatchStyle - Default value is null

getTextMatchStyle

public TextMatchStyle getTextMatchStyle()
For "fetch" operations, how search criteria should be interpreted for text fields: one of "exact" for exact match, "exactCase" for case-sensitive exact match, "startsWith" for matching at the beginning only, or "substring" for substring match. All textMatchStyle settings except "exactCase" are case-insensitive; use AdvancedCriteria for greater control over matching.

This property defaults to the value of defaultTextMatchStyle if it is not explicitly provided on the DSRequest. Note, however, that DSRequests issued by ListGrids and other components will generally have a setting for textMatchStyle on the component itself (see autoFetchTextMatchStyle, for example).

This setting is respected by the built-in server-side connectors for SQL, JPA and Hibernate. A custom server-side DataSource implementation should generally respect this flag as well, or server-side filtering will not match client-side filtering, which will require disabling client-side filtering, a huge performance loss.

Returns:
TextMatchStyle

setUseFlatFields

public void setUseFlatFields(java.lang.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 - Default value is null

getUseFlatFields

public java.lang.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(java.lang.Boolean useFlatHeaderFields)
Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request. See also headerData.

Parameters:
useFlatHeaderFields - Default value is null

getUseFlatHeaderFields

public java.lang.Boolean getUseFlatHeaderFields()
Cause the useFlatFields XML serialization behavior to be used for all soap headers in the request. See also headerData.

Returns:
Boolean

setUseStrictJSON

public void setUseStrictJSON(java.lang.Boolean useStrictJSON)
Should the HTTP response to this request be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.

Only applies to requests sent a server with dataFormat set to "json" or "iscServer".

Parameters:
useStrictJSON - Default value is null

getUseStrictJSON

public java.lang.Boolean getUseStrictJSON()
Should the HTTP response to this request be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.

Only applies to requests sent a server with dataFormat set to "json" or "iscServer".

Returns:
Boolean

setValidationMode

public void setValidationMode(ValidationMode validationMode)
Mode of validation for entered data.

Parameters:
validationMode - Default value is "full"

getValidationMode

public ValidationMode getValidationMode()
Mode of validation for entered data.

Returns:
ValidationMode

setAttribute

public void setAttribute(java.lang.String property,
                         java.lang.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.

setParams

public void setParams(java.util.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.

Array-valued parameters will be submitted as multiple instances of the same parameter, similar to an HTML form with a multi-select (?paramName=value1&paramName=value2 ...), accessible as getParameterValues(paramName) in Java Servlets. Any non-atomic type, such as an Object, will be serialized to JSON by the JSONEncoder. If this isn't desirable, serialize the data in advance so that the value provided in rpcRequest.params is a String.

Note that this API is primarily used in combination with useSimpleHttp - when contacting the Smart GWT Server, use data instead, which provides full JavaScript <-> Java translation of arbitrary structures. rpcRequest.params can also be used with the Smart GWT Server, where it provides an 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, or for making parts of the request visible in the URL for HTTP-level logging or layer 4 switches.

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

Note: The params are submitted once per http transaction. If you are using request queuing 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 - Default value is null

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

setSummaryFunctions

public void setSummaryFunctions(java.util.Map<java.lang.String,SummaryFunctionType> summaryFunctions)
A mapping from field names to summary functions to be applied to each field.

Valid only for an operation of type "fetch". See the Server Summaries overview in the client-side documentation for details and examples of usage.

NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

Parameters:
summaryFunctions - Map<String,SummaryFunction> with field names as keys and summary functions as values.
See Also:
DSRequest.setGroupBy(String[])

getSummaryFunctions

public java.util.Map<java.lang.String,SummaryFunctionType> getSummaryFunctions()
A mapping from field names to summary functions to be applied to each field.

Valid only for an operation of type "fetch". See the Server Summaries overview in the client-side documentation for details and examples of usage.

NOTE: this feature is supported only in Power Edition or above, and only when using the built-in SQL, JPA or Hibernate connectors.

Returns:
Map<String,SummaryFunction> with field names as keys and summary functions as values.
See Also:
DSRequest.getGroupBy()

setOldValues

public void setOldValues(java.util.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(com.google.gwt.core.client.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 java.lang.IllegalStateException
Return the Criteria associated with a FETCH operation.

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

Returns:
the criteria
Throws:
java.lang.IllegalStateException - if called for a non-fetch operation

setSkinName

public void setSkinName(java.lang.String skinName)
Set the skin to use. For example: Enterprise

Parameters:
skinName - the name of the selected skin.

setCriteria

public void setCriteria(Criteria criteria)
This method applies to "fetch" requests only; for update or delete operations pass a Record to setData() which contains primaryKey values as Record attributes.

Parameters:
criteria - the criteria to store.