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.


Field Summary
 
Fields inherited from class com.smartgwt.client.core.JsObject
jsObj
 
Constructor Summary
DSRequest()
           
DSRequest(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 
Method Summary
 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.
 ExportDisplay getExportDisplay()
          Specifies whether the exported data will be downloaded to the file-system or displayed in a new 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.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.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.String getLineBreakStyle()
          The style of line-breaks to use in the exported output.
 DSOperationType getOperationType()
          Type of operation being performed, "fetch", "add", "remove" or "update".
static DSRequest getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 java.lang.String getRequestId()
          Automatically generated unique ID for this request.
 java.lang.String getSortBy()
          Fieldname to sortBy, prefixed with optional "-" indicating descending sort.
 java.lang.Integer getStartRow()
          Starting row of requested results, used only with fetch operations.
 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 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.
 void setComponentId(java.lang.String componentId)
          For requests submitted by a DataBoundComponent, the ID of the submitting component.
 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 setExportDisplay(ExportDisplay exportDisplay)
          Specifies whether the exported data will be downloaded to the file-system or displayed in a new 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 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 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 setLineBreakStyle(java.lang.String lineBreakStyle)
          The style of line-breaks to use in the exported output.
 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" or "update".
 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 setSortBy(java.lang.String sortBy)
          Fieldname to sortBy, prefixed with optional "-" indicating descending sort.
 void setStartRow(java.lang.Integer startRow)
          Starting row of requested results, used only with fetch operations.
 void setTextMatchStyle(java.lang.String 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(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 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.
 
Methods inherited from class com.smartgwt.client.rpc.RPCRequest
create, getActionURL, getBypassCache, getCallbackParam, getContainsCredentials, getContentType, getData, getDataAsString, getEvalResult, getHttpHeaders, getHttpMethod, getIgnoreTimeout, getOmitNullMapValuesInResponse, getPrompt, getPromptCursor, getPromptStyle, getSendNoQueue, getServerOutputAsString, getShowPrompt, getTimeout, getTransport, getUseSimpleHttp, getWillHandleError, setActionURL, setBypassCache, setCallbackParam, setContainsCredentials, setContentType, setData, setData, 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, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsObject, 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
 
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(com.google.gwt.core.client.JavaScriptObject jsObj)
Method Detail

getOrCreateRef

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

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

setOperationType

public void setOperationType(DSOperationType operationType)
Type of operation being performed, "fetch", "add", "remove" or "update".

This property is generally automatically populated, for example when calling fetchData() on a DataSource or DataBound component the operationType is automatically set to "fetch".

Parameters:
operationType - operationType Default value is null

getOperationType

public DSOperationType getOperationType()
Type of operation being performed, "fetch", "add", "remove" or "update".

This property is generally automatically populated, for example when calling fetchData() on a DataSource or DataBound component the operationType is automatically set to "fetch".

Returns:
DSOperationType

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, so startRow: 0, endRow: 1 is a request for the first two records.

Parameters:
startRow - 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, so startRow: 0, endRow: 1 is a request for the first two records.

Returns:
Integer

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, so startRow: 0, endRow: 1 is a request for the first two records.

Parameters:
endRow - 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, so startRow: 0, endRow: 1 is a request for the first two records.

Returns:
Integer

setSortBy

public void setSortBy(java.lang.String sortBy)
Fieldname to sortBy, prefixed with optional "-" indicating descending sort. For example, to sort by the field "userName" in ascending order, set sortBy to just "userName". For descending sort on "userName", set sortBy to "-userName".

Parameters:
sortBy - sortBy Default value is null

getSortBy

public java.lang.String getSortBy()
Fieldname to sortBy, prefixed with optional "-" indicating descending sort. For example, to sort by the field "userName" in ascending order, set sortBy to just "userName". For descending sort on "userName", set sortBy to "-userName".

Returns:
String

setTextMatchStyle

public void setTextMatchStyle(java.lang.String 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"

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

Parameters:
componentId - 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 DynamicForm.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(java.lang.String).

Returns:
String

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 operationId 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 com.smartgwt.client..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 wsOperation.

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

Note that if you DataSource.fetchData() a DataSource operation, you can also specify operationId via the requestProperties parameter.

Parameters:
operationId - operationId Default value is null

getRequestId

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

Returns:
String

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 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 DataBoundComponent, 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 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 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 DataBoundComponent, 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 - 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

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.

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 also configure the style of line-breaks to use when generating the output. See com.smartgwt.client..LineBreakStyle for more information.

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

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 also configure the style of line-breaks to use when generating the output. See com.smartgwt.client..LineBreakStyle for more information.

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

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

setExportFilename

public void setExportFilename(java.lang.String exportFilename)
The name of the file to save the exported data into.

Parameters:
exportFilename - exportFilename Default value is null

getExportFilename

public java.lang.String getExportFilename()
The name of the file to save the exported data into.

Returns:
String

setExportDisplay

public void setExportDisplay(ExportDisplay exportDisplay)
Specifies whether the exported data will be downloaded to the file-system or displayed in a new 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 to the file-system or displayed in a new window. See ExportDisplay for more information.

Returns:
ExportDisplay

setLineBreakStyle

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

Parameters:
lineBreakStyle - lineBreakStyle Default value is null

getLineBreakStyle

public java.lang.String getLineBreakStyle()
The style of line-breaks to use in the exported output. See com.smartgwt.client..LineBreakStyle for more information.

Returns:
String

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 - 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:
the export fields

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.

This API is primarily used in combination with useSimpleHttp.

When contacting the SmartGWT 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 SmartGWT 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. SmartGWT 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(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 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 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 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

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