Package com.smartgwt.client.data

# Class RestDataSource

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.data.DataSource
com.smartgwt.client.data.RestDataSource

All Implemented Interfaces:
  `HasHandlers`, `HasDataChangedHandlers`, `HasHandleErrorHandlers`

public class RestDataSource extends DataSource
NOTE: This article discusses Smart GWT's client-side REST client implementation. It should not be confused with the server-side `RestConnector`; this client-side dataSource is intended for cases where you are creating the server API and thus have control over the format and protocols used, but you do not wish to use the Smart GWT Server for some reason. The server-side implementation is intended for cases where you need to connect to existing third-party REST APIs (which, despite the impression that "REST" is a standardized approach, vary significantly from one to the other in their details)

The client-side RestDataSource implements the 4 core DataSource operations using a simple protocol of XML or JSON requests and responses sent over HTTP, which can be easily fulfilled by any HTTP server technology.

RestDataSource is named for the REST (REpresentational State Transfer) pattern, which in brief says that simple messages passed over HTTP is a sufficient protocol for many web applications, without the need for further protocols such as WSDL or SOAP.

A RestDataSource is used just like a normal DataSource. RestDataSources are pre-configured, using the general-purpose databinding facilities of DataSources, to expect a particular format for responses and to send requests in a specific format. These request and response formats represent Isomorphic's recommended best practices for binding Smart GWT to backends which do not already support a similar, pre-existing request and response format and where the Smart GWT Java Server cannot be used.

If you have a pre-existing REST or WSDL service which is difficult to change, consider adapting Smart GWT to the existing service instead, by starting with a normal `DataSource` and either

- U using the `client-side data integration` facilities to create a mapping between Smart GWT's `DSRequest` and `DSResponse` objects and the message formats of your existing services, OR
- Using the highly configurable server-side `RestConnector` to adapt regular client-server DataSource requests/responses to and from the formats required by the remote REST service (server-side data integration)

NOTE: do not begin this process by creating or subclassing RestDataSource; for a pre-existing service which is unrelated to the protocol documented for `RestDataSource`, start by configuring or subclassing `DataSource` instead.

RestDataSource is typically used with PHP, Ruby, Python, Perl or custom server technologies, and represents an alternative to installing the Smart GWT Server in a Java technology stack, or using `WSDL-based binding` with .NET or other WSDL-capable technologies. Note that Smart GWT Server also provides built-in support for the REST protocol via its RESTHandler servlet; this is primarily to allow non-Smart GWT clients to make use of DataSource operations. If you particularly wished to do so, you could use RestDataSource to make a Smart GWT app talk to the Smart GWT Server using REST rather than the proprietary wire format normally used when communicating with Smart GWT Server (this is how we are able to write automated tests for the RESTHandler servlet). However, doing this provides no benefit, imposes a number of inconveniences, and makes a handful of server-based features less useful (`field-level declarative security`, for example), so we strongly recommend that you do not do this; it is only mentioned here for completeness while we are discussing REST.

The request and response formats used by the RestDataSource allow for many of the available features of Smart GWT's databinding system to be used, including data paging, searching & sorting, `long transactions`, `automatic cache sync`, `relogin` and `queuing`. However, advanced features such as `uploading / binary fields` and `export` aren't available with RestDataSource and need to be re-implemented as needed. Most, though not all, `server-based features` are still available when using RestDataSource, as long as you are also using the RESTHandler servlet that is part of Smart GWT Server. However, as noted above, this approach is not recommended; if you are using Isomorphic technology both client- and server-side, it makes more sense to use the proprietary wire format.

RestDataSource and binary data

Binary data in a response provided to a RestDataSource must be delivered as valid XML or JSON Strings. Once delivered to the browser as Strings, there is no way to trigger the browser's "Save As" dialog to download the data, and in most cases no way to trigger other helper applications that might be launched to handle binary data (such as Excel or a PDF viewer). Hence for binary it usually makes sense to make a direct request via RPCManager.sendRequest() with downloadResult:true, separate from RestDataSource.

If you are using the Smart GWT Server included in Pro, Power end Enterprise to handle your REST requests server-side, there is transparent support for conversion between Java `InputStream`s representing binary data, and Strings containing that binary data encoded using the Base64 algorithm. Thus, on the server, the binary data is in its raw binary form, with transparent conversion to or from Base64 for messages to or from the REST client.

Examples

XML formatted responses:

RestDataSource expects a response like the following in response to a "fetch" request:

      <response>
         <status>0</status>
         <startRow>0</startRow>
         <endRow>76</endRow>
         <totalRows>546</totalRows>
         <data>
           <record>
               <field1>value</field1>
               <field2>value</field2>
           </record>
           <record>
               <field1>value</field1>
               <field2>value</field2>
           </record>
           ... 76 total records ...
         </data>
      </response>

The <status> element indicates whether the fetch operation was successful (see `StatusCodes`).

The <data> element contains a list of record nodes, each of which represents a record returned by the server. The optional <startRow>, <endRow> and <totalRows> elements are needed only if data paging is in use, and populate the `startRow`, `endRow` and `totalRows` properties of the `DSResponse`.

Note: for a more compact format, simple field values may be specified on record nodes directly as attributes - in this case a record element might be structured like this:

          <record field1="value" field2="value" />

Note that a RestDataSource will bypass browser caching of all responses by default. See `DataSource.preventHTTPCaching`.

Successful "add" or "update" request responses are similar in format - in this case the data element would be expected to contain a single record object containing the details of the record, as saved on the server.

The response from a "remove" operation would again include status and data elements, but in this case, only the primary key field value(s) of the removed record would be expected to be present under the data element.

If a validation failure occurred on the server, the response would have status set to `STATUS_VALIDATION_ERROR` [`-4`], and any validation errors could be included as per-field sub-elements of an "errors" element. For a validation error, the response is not expected to contain any <data> element.

A response showing a validation error might look like this:

      <response>
         <status>-4</status>
         <errors>
           <field1>
               <errorMessage>A validation error occurred for this field</errorMessage>
           </field1>
         </errors>
      </response>

An unrecoverable error, such as an unexpected server failure, can be flagged by setting <status> to -1 and setting <data> to an error message. In this case the <errors> element is not used (it's specific to validation errors). An unrecoverable error causes all response processing to be skipped and `HandleErrorCallback.handleError()` to be invoked, which by default will show the provided error message as an alert using `SC.warn()`.

JSON formatted responses:

JSON format responses are expected to contain the same data / meta-data as XMLresponses, encapsulated in a simple object with a `"response"` attribute.
The response to a "fetch" request would therefore have this format:

      {
         "response": {
            "status": 0,
            "startRow": 0,
            "endRow": 76,
            "totalRows": 546,
            "data": [
                {"field1": "value", "field2": "value"},
                {"field1": "value", "field2": "value"},
                ... 76 total records ...
            ]
         }
      }

The structure successful for "add", "update" and "remove" responses would be similar, though the data array would be expected to contain only a single object, representing the values as saved. This allows the server to return values such as an auto-generated sequence primaryKey, a last modified timestamp, or similar server-generated field values.

For a remove, only the value for the primaryKey field[s] would be required.

For a validation error, the `status` attribute would be set to `STATUS_VALIDATION_ERROR` [`-4`], and errors would be specified in the `errors` attribute of the response. For example:

      {    "response":
           {   "status": -4,
               "errors":
                   {   "field1": {"errorMessage": "A validation error on field1"},
                       "field2": {"errorMessage": "A validation error on field2"}
                   }
           }
      }

An array of errors may also be returned for a single field, like this:

      {    "response":
           {   "status": -4,
               "errors":
                   {   "field1": [
                           {"errorMessage": "First error on field1"},
                           {"errorMessage": "Second error on field1"}
                       ]
                   }
           }
      }

As with the XML format above, an unrecoverable error is indicated by setting the `status` attribute to -1 and the `data` property to the error message.

Responses with related updates

Related updates is a way to communicate additional changes that occur as a consequence of the current DSResponse succeeding, such as changes to other records in the same DataSource or to records from unrelated DataSources. Related updates can be attached to main response via `DSResponse.addRelatedUpdate(dsResponse)` server-side API, see its docs for more details. RestDataSource supports this on the client, `DataSource.updateCaches()` will be called for all related updates found in response. Here's schematic example of how they look like:

      <response>
          ... normal response ...
          <relatedUpdates>
              <response>
                   ... normal response ...
              </response>
              <response>
                   ... normal response ...
              </response>
          </relatedUpdates>
      </response>

same in JSON format

      {
        ... normal response ...,
        relatedUpdates: [
          {
            ... normal response ...
          },
          {
            ... normal response ...
          }
        ]
      }

Server inbound data formats

The format of data sent to the server is determined by the `OperationBinding.dataProtocol` specified for the operation. Request data is sent as parameters if the format is specified as `"getParams"` or `"postParams"`.

In this case, the parameters sent to the server will consist of the DSRequest's data, and any parameters explicitly specified on the DSRequest object (as `RPCRequest.params`.
If `sendMetaData` is true, the DSRequest meta data properties will also be present as parameters, prefixed with `metaDataPrefix`.

Example URL constructed with the metaDataPrefix set to `"_"` (the default):

`[dataURL]?field1=value1&_operationType=fetch&_startRow=0&_endRow=50&_sortBy=-field2&_dataSource=dsName`

In this case the server would be able to separate the request's data from the meta data via the `"_"` prefix.

If data is sent to the server via the `"postMessage"` dataProtocol, the data will be serialized as an XML or JSON message according to the `dataFormat` setting. Both XML and JSON messages will contain request metadata such as startRow and endRow, and will appear exactly as though the subset of the `DSRequest` that is meaningful to the server had been passed to `DataSource.xmlSerialize()` or `JSON.encode()` respectively.

An example of an XML message might look like this:

         <request>
             <data>
                 <countryCode>US</countryCode>
                 <countryName>Edited Value</countryName>
                 <capital>Edited Value</capital>
                 <continent>Edited Value</continent>
             </data>
             <dataSource>countryDS</dataSource>
             <operationType>update</operationType>
         &lt/request>

An example of an XML message for a fetch operation passing simple criteria:

         <request>
             <data>
                 <continent>North America</continent>
             </data>
             <dataSource>countryDS</dataSource>
             <operationType>fetch</operationType>
             <startRow>0</startRow>
             <endRow>75</endRow>
             <componentId>worldGrid</componentId>
             <textMatchStyle>exact</textMatchStyle>
         &lt/request>

And an example of an XML message for a fetch operation passing AdvancedCriteria:

         <request>
             <data>
                 <_constructor>AdvancedCriteria</_constructor>
                 <operator>or</operator>
                 <criteria>
                     <criterion>
                         <fieldName>continent</fieldName>
                         <operator>equals</operator>
                         <value>North America</value>
                     </criterion>
                     <criterion>
                         <operator>and</operator>
                         <criteria>
                             <criterion>
                                 <fieldName>continent</fieldName>
                                 <operator>equals</operator>
                                 <value>Europe</value>
                             </criterion>
                             <criterion>
                                 <fieldName>population</fieldName>
                                 <operator>greaterThan</operator>
                                 <value>50000000</value>
                             </criterion>
                         </criteria>
                     </criterion>
                 </criteria>
             </data>
             <dataSource>countryDS</dataSource>
             <operationType>fetch</operationType>
             <startRow>0</startRow>
             <endRow>75</endRow>
             <componentId>worldGrid</componentId>
         &lt/request>

An example of an XML message for a fetch operation when using `server-side summaries`:

         <request>
             <data></data>
             <dataSource>countryDS</dataSource>
             <operationType>fetch</operationType>
             <summaryFunctions>
                 <pk>count</pk>
             </summaryFunctions>
             <groupBy>member_g8</groupBy>
         &lt/request>

JSON messages are just the plain JSON form of the structures shown in the above XML examples. The advanced criteria XML example above but in JSON form:

      {
          data: {
              _constructor: "AdvancedCriteria",
              operator: "or",
              criteria: [
                  {
                      fieldName: "continent",
                      operator: "equals",
                      value: "North America
                  },
                  {
                      operator: "and", criteria: [
                          {
                              fieldName: "continent",
                              operator: "equals",
                              value: "Europe"
                          },
                          {
                              fieldName: "population",
                              operator: "greaterThan",
                              value: 50000000
                          }
                      ]
                  }
              ]
          }
          dataSource: "countryDS",
          operationType: "fetch",
          startRow: 0,
          endRow: 75,
          componentId: "worldGrid"
      }

The `default OperationBindings` for a RestDataSource specify dataProtocol as "getParams" for the fetch operation, and "postParams" for update, add and remove operations. Note that most webservers impose a limit on the maximum size of GET requests (specifically, on the size of the request URL + HTTP headers). Using dataProtocol:"getParams" for "fetch" operations that involve complex AdvancedCriteria will result in a JSON serialization of the AdvancedCriteria in the request URL, and when combined with large cookies this can easily overflow the default limits on certain webservers (see http://stackoverflow.com/questions/686217/maximum-on-http-header-values). For this reason, we recommend that you use the "postMessage" protocol whenever you are intending to use AdvancedCriteria with RestDataSource.

Date, time and datetime values

Date, time and datetime values must be communicated using XML Schema format, as in the following examples:

        <dateField>2007-04-22</dateField>
        <timeField>11:07:13</timeField>
        <dateTimeField>2007-04-22T11:07:13</dateTimeField>
        <dateTimeField>2007-04-22T11:07:13.582</dateTimeField>

And the equivalent in JSON:

        dateField: "2007-04-22"
        timeField: "11:07:13"
        dateTimeField: "2007-04-22T11:07:13"
        dateTimeField: "2007-04-22T11:07:13.582"

Both RestDataSource on the client-side and the RESTHandler servlet on the server side automatically handle encoding and decoding temporal values using these formats. Both also handle datetime formats including or excluding milliseconds automatically. When encoding, both honor the `DataSource.trimMilliseconds` setting on the DataSource, falling back to the `server.properties` setting `rest.trimMilliseconds`; when decoding, both detect whether or not to try to parse milliseconds based on the string they receive.

Fields of type "date" and "time" are considered to hold logical date and time values, as discussed in the `date and time handling article`, and are not affected by timezones. Fields of type "datetime" will be converted to UTC on the client side by RestDataSource, and will be sent back down to the client as UTC by the server-side RESTHandler. We recommend that your own REST client and/or server code do the same thing (ie, transmit all datetime values in both directions as UTC). Note that the examples given above give no timezone information, and will be treated by the Smart GWT Server as UTC values. If you wish to work with datetime values in a particular timezone, use a format like this:

        <dateField>2007-04-22T11:07:13-0800</dateField>
        <dateField>2012-11-19T22:12:04+0100</dateField>

And the equivalent in JSON:

        dateTimeField: "2007-04-22T11:07:13-0800"
        dateTimeField: "2012-11-19T22:12:04+0100"

NOTE: Although we refer above to XML Schema format, the format used for specifying timezone offset is slightly different from XML Schema - as shown in the above examples, you specify "+HHMM" or "-HHMM", as opposed to the XML Schema format which requires a ":" character between the hours and minutes. The reason for this difference is simply that the Java SimpleDateFormat class imposes it.

RestDataSource queuing support

RestDataSource supports `queuing` of DSRequests. This allows you to send multiple requests to the server in a single HTTP turnaround, thus minimizing network traffic and allowing the server to treat multiple requests as a single transaction, if the server is able to do so (in Power Edition and above, the Smart GWT Server transparently supports grouping multiple REST requests in a queue into a single database transaction when using one of the built-in DataSource types). Note that you can disable queuing support with the `disableQueuing` flag.

If you want to use queuing with RestDataSource, you must use the "postMessage" dataProtocol with either XML or JSON dataFormat. Message format is similar to the non-queued examples shown earlier: it is simply extended to cope with the idea of multiple DSRequests encapsulated in the message.

An example of the XML message sent from RestDataSource to the server for two update requests combined into a queue, using XML dataFormat:

      <transaction>
          <operations>
              <request>
                  <data>
                      <pk>1</pk>
                      <countryName>Edited Value</countryName>
                      <capital>Edited Value</capital>
                      <continent>Edited Value</continent>
                  </data>
                  <dataSource>countryDS</dataSource>
                  <operationType>update</operationType>
              &lt/request>
              <request>
                  <data>
                      <pk>2</pk>
                      <capital>Edited Value</capital>
                      <population>123456</population>
                  </data>
                  <dataSource>countryDS</dataSource>
                  <operationType>update</operationType>
              &lt/request>
          </operations>
      <transaction>

And the same message in JSON format:

      {
          transaction: {
              operations: [{
                  dataSource:"countryDS",
                  operationType:"update",
                  data: {
                      pk: 1,
                      countryName: "Edited Value",
                      capital: "Edited Value",
                      continent: "Edited Value"
                  }
              }, {
                  dataSource:"countryDS",
                  operationType:"update",
                  data: {
                      pk: 2,
                      capital: "Edited Value",
                      population: 123456
                  }
              }]
          }
      }

RestDataSource expects the response to a queue of requests to be a queue of responses in the same order as the original requests. Again, the message format is very similar to the unqueued REST format, it just has an outer container construct. Note also that the individual DSResponses in a queued response have an extra property, ``queueStatus``. This allows each individual response to determine whether the queue as a whole succeeded. For example, if the first update succeeded but the second failed validation, the first response would have a `status` of 0, but a `queueStatus` of -1, while the second response would have both properties set to -1.

The update queue example given above would expect a response like this (in XML):

      <responses>
          <response>
              <status>0</status>
              <queueStatus>0</queueStatus>
              <data>
                  <record>
                      <countryName>Edited Value</countryName>
                      <gdp>1700.0</gdp>
                      <continent>Edited Value</continent>
                      <capital>Edited Value</capital>
                      <pk>1</pk>
                  </record>
              </data>
          </response>
          <response>
              <status>0</status>
              <queueStatus>0</queueStatus>
              <data>
                  <record>
                      <countryName>United States</countryName>
                      <gdp>7247700.0</gdp>
                      <continent>North America</continent>
                      <independence>1776-07-04</independence>
                      <capital>Washington DC</capital>
                      <pk>2</pk>
                      <population>123456</population>
                  </record>
              </data>
          </response>
      </responses>

And in JSON:

      [
      {
          "response": {
              "queueStatus": 0,
              "status": 0,
              "data": [{
                  "countryName": "Edited Value",
                  "gdp": 1700.0,
                  "continent": "Edited Value",
                  "capital": "Edited Value",
                  "pk": 1
              }]
          }
      },
      {
          "response": {
              "queueStatus": 0,
              "status": 0,
              "data": [{
                  "countryName": "United States",
                  "gdp": 7247700.0,
                  "continent": "North America",
                  "independence": "1776-07-04",
                  "capital": "Washington DC",
                  "pk": 2,
                  "population": 123456
              }]
          }
      }
      ]

Hierarchical (Tree) data:

To create a hierarchical DataSource, in the DataSource's `fields` array, a field must be specified as the parent id field - the field which will contain a pointer to the id of each node's parent. This can be achieved by setting the `DataSourceField.foreignKey` and the `DataSourceField.rootValue` attributes on the field definition. For example:

      RestDataSource.create({
         ID:"supplyItem",
         fields : [
             {name:"itemId", type:"sequence", primaryKey:true},
             {name:"parentId", type:"integer", foreignKey:"supplyItem.itemId", rootValue:0},
             ...
         ]
      });

Tree Data is then treated on the server as a flat list of records linked by parent id.

Tree data is typically displayed using a dataBound `TreeGrid` component. TreeGrids automatically create a `ResultTree` data object, which requests data directly from the DataSource. ResultTrees load data on demand, only requesting currently visible (open) nodes from the server. This is handled by including a specified value for the parent id field in the request criteria.
To implement a standard load-on-demand tree RestDataSource back end, you should therefore simply return the set of nodes that match the criteria passed in. For example, if your DataSource was defined as the "supplyItem" code snippet above, a fetch request for all children of a node with `itemId` set to `12` would have `"parentId"` set to `12` in the request criteria. A valid response would then contain all the records that matched this criteria. For example:

      <response>
         <status>0</status>
         <data>
           <record>
               <itemId>15</itemId>
               <parentId>12</parentId>
           </record>
           <record>
               <itemId>16</itemId>
               <parentId>12</parentId>
           </record>
         </data>
      </response>

The structure of responses for Add, Update and Delete type requests will be the same regardless of whether the data is hierarchical. However you should be aware that the underlying data storage may need to be managed slightly differently in some cases.

Specifically, Add and Update operations may change the structure of the tree by returning a new parent id field value for the modified node. Depending on how your data is stored you may need to include special back-end logic to handle this.

Also, if a user deletes a folder within a databound tree, any children of that folder will also be dropped from the tree, and can be removed from the back-end data storage.

Note: For a general overview of binding components to Tree structured data, see `Tree Databinding`.

- ## Field Summary

  ### Fields inherited from class com.smartgwt.client.core.BaseClass

  `config, configOnly, factoryCreated, factoryProperties, id, scClassName`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RestDataSource()`
  `RestDataSource(JavaScriptObject jsObj)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JavaScriptObject`
  `create()`
  `String`
  `getAddDataURL()`
  Custom `dataURL` for `DSRequests` with `operationType` "add".
  `DSDataFormat`
  `getDataFormat()`
  Expected format for server responses.
  `DSProtocol`
  `getDataProtocol()`
  Rather than setting `DataSource.dataProtocol`, to control the format in which inputs are sent to the dataURL, you must specify a replacement `OperationBinding` and specify `OperationBinding.dataProtocol` on that `operationBinding`.
  `String`
  `getDataURL()`
  Default URL to contact to fulfill all DSRequests.
  `Boolean`
  `getDisableQueuing()`
  If set, disables `request queuing` for this RestDataSource.
  `String`
  `getFetchDataURL()`
  Custom `dataURL` for `DSRequests` with `operationType` "fetch".
  `String`
  `getJsonPrefix()`
  Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
  `String`
  `getJsonRecordXPath()`
  `recordXPath` mapping to the data node of json returned by the server.
  `String`
  `getJsonSuffix()`
  Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
  `String`
  `getMetaDataPrefix()`
  If `sendMetaData` is true, this attribute is used to specify the prefix to apply to 'meta data' properties when assembling parameters to send to the server.
  `OperationBinding[]`
  `getOperationBindings()`
  RestDataSource OperationBindings set to specify default dataProtocol per operationType.
  `static RestDataSource`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `Boolean`
  `getPrettyPrintJSON()`
  When using dataFormat:"json" and dataProtocol:"postMessage" should we use the `JSONEncoder.prettyPrint` feature to enable indented, highly readable JSON messages.
  `String`
  `getRecordXPath()`
  For RestDataSources, by default, either the `xmlRecordXPath` or `jsonRecordXPath` is used based on the `dataFormat` setting.
  `String`
  `getRemoveDataURL()`
  Custom `dataURL` for `DSRequests` with `operationType` "remove".
  `Boolean`
  `getSendMetaData()`
  Should operation meta data be included when assembling parameters to send to the server? If true, meta data parameters will be prefixed with the `metaDataPrefix`.
  Applies to operations where OperationBinding.dataProtocol is set to `"getParams"` or `"postParams"` only.
  `String`
  `getUpdateDataURL()`
  Custom `dataURL` for `DSRequests` with `operationType` "update".
  `XmlNamespaces`
  `getXmlNamespaces()`
  When `dataFormat` is "xml", `xmlNamespaces` configures the set of namespace prefixes that are added to the document element of the XML message sent to the server.
  `String`
  `getXmlRecordXPath()`
  `recordXPath` mapping to the data node of XML returned by the server.
  `RestDataSource`
  `setAddDataURL(String addDataURL)`
  Custom `dataURL` for `DSRequests` with `operationType` "add".
  `RestDataSource`
  `setDataFormat(DSDataFormat dataFormat)`
  Expected format for server responses.
  `RestDataSource`
  `setDataProtocol(DSProtocol dataProtocol)`
  Rather than setting `DataSource.dataProtocol`, to control the format in which inputs are sent to the dataURL, you must specify a replacement `OperationBinding` and specify `OperationBinding.dataProtocol` on that `operationBinding`.
  `RestDataSource`
  `setDataURL(String dataURL)`
  Default URL to contact to fulfill all DSRequests.
  `static void`
  `setDefaultProperties(RestDataSource restDataSourceProperties)`
  Class level method to set the default properties of this class.
  `RestDataSource`
  `setDisableQueuing(Boolean disableQueuing)`
  If set, disables `request queuing` for this RestDataSource.
  `RestDataSource`
  `setFetchDataURL(String fetchDataURL)`
  Custom `dataURL` for `DSRequests` with `operationType` "fetch".
  `RestDataSource`
  `setJsonPrefix(String jsonPrefix)`
  Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
  `RestDataSource`
  `setJsonRecordXPath(String jsonRecordXPath)`
  `recordXPath` mapping to the data node of json returned by the server.
  `RestDataSource`
  `setJsonSuffix(String jsonSuffix)`
  Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
  `RestDataSource`
  `setMetaDataPrefix(String metaDataPrefix)`
  If `sendMetaData` is true, this attribute is used to specify the prefix to apply to 'meta data' properties when assembling parameters to send to the server.
  `RestDataSource`
  `setOperationBindings(OperationBinding... operationBindings)`
  RestDataSource OperationBindings set to specify default dataProtocol per operationType.
  `RestDataSource`
  `setPrettyPrintJSON(Boolean prettyPrintJSON)`
  When using dataFormat:"json" and dataProtocol:"postMessage" should we use the `JSONEncoder.prettyPrint` feature to enable indented, highly readable JSON messages.
  `RestDataSource`
  `setRecordXPath(String recordXPath)`
  For RestDataSources, by default, either the `xmlRecordXPath` or `jsonRecordXPath` is used based on the `dataFormat` setting.
  `RestDataSource`
  `setRemoveDataURL(String removeDataURL)`
  Custom `dataURL` for `DSRequests` with `operationType` "remove".
  `RestDataSource`
  `setSendMetaData(Boolean sendMetaData)`
  Should operation meta data be included when assembling parameters to send to the server? If true, meta data parameters will be prefixed with the `metaDataPrefix`.
  Applies to operations where OperationBinding.dataProtocol is set to `"getParams"` or `"postParams"` only.
  `RestDataSource`
  `setUpdateDataURL(String updateDataURL)`
  Custom `dataURL` for `DSRequests` with `operationType` "update".
  `RestDataSource`
  `setXmlNamespaces(XmlNamespaces xmlNamespaces)`
  When `dataFormat` is "xml", `xmlNamespaces` configures the set of namespace prefixes that are added to the document element of the XML message sent to the server.
  `RestDataSource`
  `setXmlRecordXPath(String xmlRecordXPath)`
  `recordXPath` mapping to the data node of XML returned by the server.

  ### Methods inherited from class com.smartgwt.client.data.DataSource

  `addData, addData, addData, addDataChangedHandler, addField, addHandleErrorHandler, addSearchOperator, applyFilter, applyFilter, asJSONSchema, asJSONSchema, asJSONSchemaAsString, canFlattenCriteria, clearValueAtDataPath, clearValueAtDataPath, clearValueAtDataPath, clearValueAtDataPath, cloneDSRequest, cloneDSResponse, combineCriteria, combineCriteria, combineCriteria, commitAllQueuedChanges, commitAllQueuedChanges, commitAllQueuedChanges, commitQueuedChanges, commitQueuedChanges, commitQueuedChanges, compareCriteria, compareCriteria, compareCriteria, compareDates, compareValues, compareValues, convertCriteria, convertCriteria, convertDataSourceCriteria, convertDataSourceCriteria, convertRelativeDates, convertRelativeDates, convertRelativeDates, convertRelativeDates, copyCriteria, copyRecord, copyRecords, createAlias, discardAllQueuedChanges, discardAllQueuedChanges, discardAllQueuedChanges, discardQueuedChanges, discardQueuedChanges, discardQueuedChanges, downloadFile, downloadFile, downloadFile, evaluateCriterion, execute, exportClientData, exportClientDataStatic, exportData, exportData, exportData, exportData, fetchData, fetchData, fetchData, fetchData, fetchRecord, fetchRecord, fetchRecord, fieldMatchesFilter, fieldMatchesFilter, filterData, filterData, filterData, filterData, findSortPosition, flattenCriteria, formatFieldValue, get, get, getAddedAuditFields, getAddGlobalId, getAdvancedCriteriaDescription, getAdvancedCriteriaDescription, getAggregationDescription, getAllowAdvancedCriteria, getAllowAggregation, getAllowCriteriaSubqueries, getAllowDynamicTreeJoins, getAllowRelatedFieldsInCriteria, getAllPathsToRelation, getAllPathsToRelation, getAllQueuedChanges, getAppDataSources, getArrayCriteriaForceExact, getAutoCacheAllData, getAutoConvertRelativeDates, getAutoDeriveTitles, getAutoDiscoverTree, getAutoTitle, getCacheAcrossOperationIds, getCacheAllData, getCacheAllOperationId, getCacheData, getCacheMaxAge, getCallbackParam, getCanAggregate, getCanMultiSort, getChildrenField, getClientOnly, getClientOnlyDataSource, getClientOnlyDataSource, getClientOnlyDataSource, getClientOnlyResponse, getCriteriaPolicy, getCriteriaSchema, getCriteriaSchema, getCriteriaSchema, getCriteriaSchema, getDataField, getDataSource, getDataSource, getDataSource, getDataTransport, getDeepCloneNonFieldValuesOnEdit, getDeepCloneOnEdit, getDefaultParams, getDefaultPathToRelation, getDefaultPathToRelation, getDefaultTextMatchStyle, getDescription, getDescriptionField, getDiscoverTreeSettings, getDisplayValue, getDropExtraFields, getDropUnknownCriteria, getEnforceSecurityOnClient, getEventSchema, getEventSchema, getFetchDataURL, getFetchDataURL, getField, getFieldAutoTitle, getFieldCriterion, getFieldDefaultOperator, getFieldDefaultOperator, getFieldForDataPath, getFieldNames, getFieldNames, getFieldOperators, getFieldOperators, getFields, getFieldValue, getFieldValue, getFieldValue, getFieldValue, getFieldValue, getFieldValue, getFieldValue, getFile, getFileURL, getFileURL, getFileURL, getFileVersion, getGlobalNamespaces, getIconField, getIgnoreTextMatchStyleCaseSensitive, getImplicitCriteria, getInfoField, getInheritsFrom, getIsSampleDS, getJsObj, getLegalChildTags, getLoaderURL, getMockDataCriteria, getMockDataRows, getMockMode, getPatternEscapeChar, getPatternMultiWildcard, getPatternMultiWildcardAsString, getPatternMultiWildcardAsStringArray, getPatternSingleWildcard, getPatternSingleWildcardAsString, getPatternSingleWildcardAsStringArray, getPendingChanges, getPluralTitle, getPreventHTTPCaching, getPrimaryKeyField, getPrimaryKeyFieldName, getPrimaryKeyFieldNames, getPrimaryKeyFields, getProgressiveLoading, getQualifyColumnNames, getQueueChanges, getRecordName, getRequestProperties, getRequiredMessage, getResultBatchSize, getResultSetClass, getResultTreeClass, getSampleData, getSchemaNamespace, getSendExtraFields, getSendParentNode, getServiceNamespace, getShortestPathToRelation, getShortestPathToRelation, getShowLocalFieldsOnly, getShowPrompt, getSkipJSONValidation, getSortBy, getSortSpecifiers, getSortSpecifiers, getStrictSQLFiltering, getTagName, getTestData, getTitle, getTitleField, getTranslatePatternOperators, getTrimMilliseconds, getTypeOperators, getTypeOperators, getTypeOperators, getUseFlatFields, getUseHttpProxy, getUseLocalValidators, getUseOfflineStorage, getUseParentFieldOrder, getUseStrictJSON, getUseTestDataFetch, getValidateRelatedRecords, hasAllData, hasCustomTypeOperators, hasCustomTypeOperators, hasCustomTypeOperators, hasFile, hasFileVersion, invalidateCache, invalidateCache, isAdvancedCriteria, isAdvancedCriteria, isCalculated, isCalculated, isCreated, isFlatCriteria, listFiles, listFileVersions, load, load, load, load, loadWithParents, loadWithParents, loadWithParents, loadWithParents, makeFileSpec, onInit, pendingChangesChanged, performCustomOperation, performCustomOperation, performCustomOperation, performCustomOperation, processResponse, recordsAreEqual, recordsAsText, recordsAsText, recordsFromText, recordsFromText, recordsFromXML, registerID, removeData, removeData, removeData, removeFile, removeFile, removeFile, removeFile, removeFileVersion, removeFileVersion, renameFile, renameFile, saveFile, saveFile, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, saveValueViaDataPath, setAddedAuditFields, setAddGlobalId, setAllowAdvancedCriteria, setAllowAggregation, setAllowCriteriaSubqueries, setAllowDynamicTreeJoins, setAllowRelatedFieldsInCriteria, setArrayCriteriaForceExact, setAutoCacheAllData, setAutoConvertRelativeDates, setAutoDeriveTitles, setAutoDiscoverTree, setCacheAcrossOperationIds, setCacheAllData, setCacheAllOperationId, setCacheData, setCacheMaxAge, setCallbackParam, setCanAggregate, setCanMultiSort, setChildrenField, setClientOnly, setCriteriaPolicy, setDataField, setDataTransport, setDeepCloneNonFieldValuesOnEdit, setDeepCloneOnEdit, setDefaultParams, setDefaultProperties, setDefaultTextMatchStyle, setDescription, setDescriptionField, setDiscoverTreeSettings, setDropExtraFields, setDropUnknownCriteria, setEnforceSecurityOnClient, setEnumConstantProperty, setEnumOrdinalProperty, setEnumTranslateStrategy, setFields, setGlobalNamespaces, setHandleErrorCallback, setIconField, setID, setIgnoreTextMatchStyleCaseSensitive, setImplicitCriteria, setInfoField, setInheritsFrom, setInheritsFrom, setIsSampleDS, setLoaderURL, setMockDataCriteria, setMockDataRows, setMockMode, setPatternEscapeChar, setPatternMultiWildcard, setPatternMultiWildcard, setPatternSingleWildcard, setPatternSingleWildcard, setPluralTitle, setPreventHTTPCaching, setProgressiveLoading, setQualifyColumnNames, setQueueChanges, setRecordName, setRequestProperties, setRequiredMessage, setResultBatchSize, setResultSetClass, setResultTreeClass, setSampleData, setSendExtraFields, setSendParentNode, setServiceNamespace, setShowLocalFieldsOnly, setShowPrompt, setSkipJSONValidation, setStrictSQLFiltering, setTagName, setTestData, setTitle, setTitleField, setTranslatePatternOperators, setTrimMilliseconds, setTypeOperators, setTypeOperators, setUseFlatFields, setUseHttpProxy, setUseLocalValidators, setUseOfflineStorage, setUseParentFieldOrder, setUseStrictJSON, setUseTestDataFetch, setValidateRelatedRecords, splitCriteria, splitCriteria, supportsAdvancedCriteria, supportsDynamicTreeJoins, supportsTextMatchStyle, transformRequest, transformResponse, updateCaches, updateCaches, updateData, updateData, updateData, useOfflineResponse, validateData, validateData, validateData, verifyDataSourcePair, viewFile, viewFile, viewFile, xmlSerialize, xmlSerialize, xmlSerialize, xmlSerialize, xmlSerialize`

  ### Methods inherited from class com.smartgwt.client.core.BaseClass

  `addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getRuleScope, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setConfigOnly, setFactoryCreated, setJavaScriptObject, setProperty, setProperty, setProperty, setProperty, setRuleScope, setScClassName`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

  `fireEvent`

- ## Constructor Details

  - ### RestDataSource

    public RestDataSource()

  - ### RestDataSource

    public RestDataSource(JavaScriptObject jsObj)

- ## Method Details

  - ### getOrCreateRef

    public static RestDataSource getOrCreateRef(JavaScriptObject jsObj)

  - ### create

    public JavaScriptObject create()
    Overrides:
      `create` in class `DataSource`

  - ### setAddDataURL

    public RestDataSource setAddDataURL(String addDataURL) throws IllegalStateException
    Custom `dataURL` for `DSRequests` with `operationType` "add".

    See `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Parameters:
      `addDataURL` - New addDataURL value. Default value is null
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getAddDataURL

    public String getAddDataURL()
    Custom `dataURL` for `DSRequests` with `operationType` "add".

    See `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Returns:
      Current addDataURL value. Default value is null

  - ### setDataFormat

    public RestDataSource setDataFormat(DSDataFormat dataFormat) throws IllegalStateException
    Expected format for server responses. RestDataSources handle `"json"` and `"xml"` format responses by default. See class overview documentation for examples of responses in each format.
    Overrides:
      `setDataFormat` in class `DataSource`
    Parameters:
      `dataFormat` - New dataFormat value. Default value is "xml"
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Server DataSource Integration`
      - JSON DataSource Example
      - Simple JSON Example

  - ### getDataFormat

    public DSDataFormat getDataFormat()
    Expected format for server responses. RestDataSources handle `"json"` and `"xml"` format responses by default. See class overview documentation for examples of responses in each format.
    Overrides:
      `getDataFormat` in class `DataSource`
    Returns:
      Current dataFormat value. Default value is "xml"
    See Also:
      - `Server DataSource Integration`
      - JSON DataSource Example
      - Simple JSON Example

  - ### setDataProtocol

    public RestDataSource setDataProtocol(DSProtocol dataProtocol) throws IllegalStateException
    Rather than setting `DataSource.dataProtocol`, to control the format in which inputs are sent to the dataURL, you must specify a replacement `OperationBinding` and specify `OperationBinding.dataProtocol` on that `operationBinding`.

    This is because `RestDataSource` specifies default `operationBindings` for all operationTypes - see `operationBindings`.

    Overrides:
      `setDataProtocol` in class `DataSource`
    Parameters:
      `dataProtocol` - New dataProtocol value. Default value is null
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Server DataSource Integration`

  - ### getDataProtocol

    public DSProtocol getDataProtocol()
    Rather than setting `DataSource.dataProtocol`, to control the format in which inputs are sent to the dataURL, you must specify a replacement `OperationBinding` and specify `OperationBinding.dataProtocol` on that `operationBinding`.

    This is because `RestDataSource` specifies default `operationBindings` for all operationTypes - see `operationBindings`.

    Overrides:
      `getDataProtocol` in class `DataSource`
    Returns:
      Current dataProtocol value. Default value is null
    See Also:
      - `Server DataSource Integration`

  - ### setDataURL

    public RestDataSource setDataURL(String dataURL) throws IllegalStateException
    Default URL to contact to fulfill all DSRequests. RestDataSources also allow per-operationType dataURLs to be set via
    - `fetchDataURL`
    - `addDataURL`
    - `updateDataURL`
    - `removeDataURL`
    NOTE:: when using `queuing` with RestDataSource, an HTTP request containing mixed `operationTypes` (such as a mixture of "add", "update" and "remove" operations resulting from `Grid Mass Editing`) can only go to one URL, so you should not set distinct URLs for each `operationType`; doing so will break queuing of mixed operationTypes: multiple requests will be sent to distinct URLs, and a warning logged.
    Overrides:
      `setDataURL` in class `DataSource`
    Parameters:
      `dataURL` - New dataURL value. Default value is null
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `URL`
      - `Client-side Data Integration`
      - JSON DataSource Example

  - ### getDataURL

    public String getDataURL()
    Default URL to contact to fulfill all DSRequests. RestDataSources also allow per-operationType dataURLs to be set via
    - `fetchDataURL`
    - `addDataURL`
    - `updateDataURL`
    - `removeDataURL`
    NOTE:: when using `queuing` with RestDataSource, an HTTP request containing mixed `operationTypes` (such as a mixture of "add", "update" and "remove" operations resulting from `Grid Mass Editing`) can only go to one URL, so you should not set distinct URLs for each `operationType`; doing so will break queuing of mixed operationTypes: multiple requests will be sent to distinct URLs, and a warning logged.
    Overrides:
      `getDataURL` in class `DataSource`
    Returns:
      Current dataURL value. Default value is null
    See Also:
      - `URL`
      - `Client-side Data Integration`
      - JSON DataSource Example

  - ### setDisableQueuing

    public RestDataSource setDisableQueuing(Boolean disableQueuing)
    If set, disables `request queuing` for this RestDataSource.
    Parameters:
      `disableQueuing` - New disableQueuing value. Default value is false
    Returns:
      `RestDataSource` instance, for chaining setter calls

  - ### getDisableQueuing

    public Boolean getDisableQueuing()
    If set, disables `request queuing` for this RestDataSource.
    Returns:
      Current disableQueuing value. Default value is false

  - ### setFetchDataURL

    public RestDataSource setFetchDataURL(String fetchDataURL) throws IllegalStateException
    Custom `dataURL` for `DSRequests` with `operationType` "fetch".

    Use `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Parameters:
      `fetchDataURL` - New fetchDataURL value. Default value is null
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getFetchDataURL

    public String getFetchDataURL()
    Custom `dataURL` for `DSRequests` with `operationType` "fetch".

    Use `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Returns:
      Current fetchDataURL value. Default value is null

  - ### setJsonPrefix

    public RestDataSource setJsonPrefix(String jsonPrefix)
    Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application. The client will expect to find this prefix on any JSON response received for this DataSource, and will strip it off before evaluating the response text.

    The default prefix is "<SCRIPT>//'\"]]>>isc_JSONResponseStart>>".

    The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

    You can switch off JSON wrapping altogether by setting both this and `jsonSuffix` to empty strings.

    If you are using Smart GWT Server's RESTHandler servlet, see the server-side Javadocs for details of how to change the way JSON wrapping works on the server side.

    Overrides:
      `setJsonPrefix` in class `DataSource`
    Parameters:
      `jsonPrefix` - New jsonPrefix value. Default value is See below
    Returns:
      `RestDataSource` instance, for chaining setter calls
    See Also:
      - `setJsonSuffix(java.lang.String)`

  - ### getJsonPrefix

    public String getJsonPrefix()
    Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application. The client will expect to find this prefix on any JSON response received for this DataSource, and will strip it off before evaluating the response text.

    The default prefix is "<SCRIPT>//'\"]]>>isc_JSONResponseStart>>".

    The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

    You can switch off JSON wrapping altogether by setting both this and `jsonSuffix` to empty strings.

    If you are using Smart GWT Server's RESTHandler servlet, see the server-side Javadocs for details of how to change the way JSON wrapping works on the server side.

    Overrides:
      `getJsonPrefix` in class `DataSource`
    Returns:
      Current jsonPrefix value. Default value is See below
    See Also:
      - `getJsonSuffix()`

  - ### setJsonRecordXPath

    public RestDataSource setJsonRecordXPath(String jsonRecordXPath) throws IllegalStateException
    `recordXPath` mapping to the data node of json returned by the server. Applies if this.dataFormat is set to `"json"`
    The default value will pick up data from a response structured as follows:

          {response:
           {status:0,
            data:[
               {field1:"value", field2:"value"},
               {field1:"value", field2:"value"}
            ]
          }

    Parameters:
      `jsonRecordXPath` - New jsonRecordXPath value. Default value is "/response/data"
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getJsonRecordXPath

    public String getJsonRecordXPath()
    `recordXPath` mapping to the data node of json returned by the server. Applies if this.dataFormat is set to `"json"`
    The default value will pick up data from a response structured as follows:

          {response:
           {status:0,
            data:[
               {field1:"value", field2:"value"},
               {field1:"value", field2:"value"}
            ]
          }

    Returns:
      Current jsonRecordXPath value. Default value is "/response/data"

  - ### setJsonSuffix

    public RestDataSource setJsonSuffix(String jsonSuffix)
    Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application. The client will expect to find this suffix on any JSON response received for this DataSource, and will strip it off before evaluating the response text.

    The default suffix is "//isc_JSONResponseEnd".

    Overrides:
      `setJsonSuffix` in class `DataSource`
    Parameters:
      `jsonSuffix` - New jsonSuffix value. Default value is See below
    Returns:
      `RestDataSource` instance, for chaining setter calls
    See Also:
      - `setJsonPrefix(java.lang.String)`

  - ### getJsonSuffix

    public String getJsonSuffix()
    Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application. The client will expect to find this suffix on any JSON response received for this DataSource, and will strip it off before evaluating the response text.

    The default suffix is "//isc_JSONResponseEnd".

    Overrides:
      `getJsonSuffix` in class `DataSource`
    Returns:
      Current jsonSuffix value. Default value is See below
    See Also:
      - `getJsonPrefix()`

  - ### setMetaDataPrefix

    public RestDataSource setMetaDataPrefix(String metaDataPrefix) throws IllegalStateException
    If `sendMetaData` is true, this attribute is used to specify the prefix to apply to 'meta data' properties when assembling parameters to send to the server. Applies to operations where OperationBinding.dataProtocol is set to `"getParams"` or `"postParams"` only.
    Parameters:
      `metaDataPrefix` - New metaDataPrefix value. Default value is "_"
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getMetaDataPrefix

    public String getMetaDataPrefix()
    If `sendMetaData` is true, this attribute is used to specify the prefix to apply to 'meta data' properties when assembling parameters to send to the server. Applies to operations where OperationBinding.dataProtocol is set to `"getParams"` or `"postParams"` only.
    Returns:
      Current metaDataPrefix value. Default value is "_"

  - ### setOperationBindings

    public RestDataSource setOperationBindings(OperationBinding... operationBindings) throws IllegalStateException
    RestDataSource OperationBindings set to specify default dataProtocol per operationType. Default databindings are:

            operationBindings : [
              {operationType:"fetch", dataProtocol:"getParams"},
              {operationType:"add", dataProtocol:"postParams"},
              {operationType:"remove", dataProtocol:"postParams"},
              {operationType:"update", dataProtocol:"postParams"}
            ],

    If you are integrating with a `REST` server that requires the more obscure `RPCRequest.httpMethod`s of "PUT", "DELETE" or "HEAD", you can specify these httpMethod settings via `OperationBinding.requestProperties`. dataProtocol settings that mention "GET" or "POST" are compatible with these additional HTTP methods as well. Typical `operationBindings` for a REST server that uses "PUT" and "DELETE" are as follows:

            operationBindings:[
              {operationType:"fetch", dataProtocol:"getParams"},
              {operationType:"add", dataProtocol:"postParams"},
              {operationType:"remove", dataProtocol:"getParams", requestProperties:{httpMethod:"DELETE"}},
              {operationType:"update", dataProtocol:"postParams", requestProperties:{httpMethod:"PUT"}}
            ],

    Note that dataProtocol:"postMessage" is always used when `queuing` is used to send multiple DSRequests to the server as a single HttpRequest. See `RestDataSource` docs, "queuing support". We also recommend that you use the "postMessage" protocol whenever you are intending to use AdvancedCriteria with RestDataSource - this is discussed in the section "Server inbound data format" in the `RestDataSource overview`.

    Overrides:
      `setOperationBindings` in class `DataSource`
    Parameters:
      `operationBindings` - New operationBindings value. Default value is [...]
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `OperationBinding`

  - ### getOperationBindings

    public OperationBinding[] getOperationBindings()
    RestDataSource OperationBindings set to specify default dataProtocol per operationType. Default databindings are:

            operationBindings : [
              {operationType:"fetch", dataProtocol:"getParams"},
              {operationType:"add", dataProtocol:"postParams"},
              {operationType:"remove", dataProtocol:"postParams"},
              {operationType:"update", dataProtocol:"postParams"}
            ],

    If you are integrating with a `REST` server that requires the more obscure `RPCRequest.httpMethod`s of "PUT", "DELETE" or "HEAD", you can specify these httpMethod settings via `OperationBinding.requestProperties`. dataProtocol settings that mention "GET" or "POST" are compatible with these additional HTTP methods as well. Typical `operationBindings` for a REST server that uses "PUT" and "DELETE" are as follows:

            operationBindings:[
              {operationType:"fetch", dataProtocol:"getParams"},
              {operationType:"add", dataProtocol:"postParams"},
              {operationType:"remove", dataProtocol:"getParams", requestProperties:{httpMethod:"DELETE"}},
              {operationType:"update", dataProtocol:"postParams", requestProperties:{httpMethod:"PUT"}}
            ],

    Note that dataProtocol:"postMessage" is always used when `queuing` is used to send multiple DSRequests to the server as a single HttpRequest. See `RestDataSource` docs, "queuing support". We also recommend that you use the "postMessage" protocol whenever you are intending to use AdvancedCriteria with RestDataSource - this is discussed in the section "Server inbound data format" in the `RestDataSource overview`.

    Overrides:
      `getOperationBindings` in class `DataSource`
    Returns:
      Current operationBindings value. Default value is [...]
    See Also:
      - `OperationBinding`

  - ### setPrettyPrintJSON

    public RestDataSource setPrettyPrintJSON(Boolean prettyPrintJSON) throws IllegalStateException
    When using dataFormat:"json" and dataProtocol:"postMessage" should we use the `JSONEncoder.prettyPrint` feature to enable indented, highly readable JSON messages.

    True by default because the bandwidth involved is generally negligible and the benefits for troubleshooting are key.

    Parameters:
      `prettyPrintJSON` - New prettyPrintJSON value. Default value is true
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getPrettyPrintJSON

    public Boolean getPrettyPrintJSON()
    When using dataFormat:"json" and dataProtocol:"postMessage" should we use the `JSONEncoder.prettyPrint` feature to enable indented, highly readable JSON messages.

    True by default because the bandwidth involved is generally negligible and the benefits for troubleshooting are key.

    Returns:
      Current prettyPrintJSON value. Default value is true

  - ### setRecordXPath

    public RestDataSource setRecordXPath(String recordXPath)
    For RestDataSources, by default, either the `xmlRecordXPath` or `jsonRecordXPath` is used based on the `dataFormat` setting.

    Note that you can also apply record xpath binding via `OperationBinding.recordXPath`.

    Overrides:
      `setRecordXPath` in class `DataSource`
    Parameters:
      `recordXPath` - New recordXPath value. Default value is null
    Returns:
      `RestDataSource` instance, for chaining setter calls
    See Also:
      - `XPathExpression`
      - `Client-side Data Integration`
      - XML DataSource Example
      - JSON XPath Binding Example

  - ### getRecordXPath

    public String getRecordXPath()
    For RestDataSources, by default, either the `xmlRecordXPath` or `jsonRecordXPath` is used based on the `dataFormat` setting.

    Note that you can also apply record xpath binding via `OperationBinding.recordXPath`.

    Overrides:
      `getRecordXPath` in class `DataSource`
    Returns:
      Current recordXPath value. Default value is null
    See Also:
      - `XPathExpression`
      - `Client-side Data Integration`
      - XML DataSource Example
      - JSON XPath Binding Example

  - ### setRemoveDataURL

    public RestDataSource setRemoveDataURL(String removeDataURL) throws IllegalStateException
    Custom `dataURL` for `DSRequests` with `operationType` "remove".

    See `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Parameters:
      `removeDataURL` - New removeDataURL value. Default value is null
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getRemoveDataURL

    public String getRemoveDataURL()
    Custom `dataURL` for `DSRequests` with `operationType` "remove".

    See `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Returns:
      Current removeDataURL value. Default value is null

  - ### setSendMetaData

    public RestDataSource setSendMetaData(Boolean sendMetaData) throws IllegalStateException
    Should operation meta data be included when assembling parameters to send to the server? If true, meta data parameters will be prefixed with the `metaDataPrefix`.
    Applies to operations where OperationBinding.dataProtocol is set to `"getParams"` or `"postParams"` only.

    See `transformRequest()` to review the list of default metadata fields. In case you need to add additional parameters to the dsRequest object, you can do it via `RPCRequest.params`.

    Parameters:
      `sendMetaData` - New sendMetaData value. Default value is true
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getSendMetaData

    public Boolean getSendMetaData()
    Should operation meta data be included when assembling parameters to send to the server? If true, meta data parameters will be prefixed with the `metaDataPrefix`.
    Applies to operations where OperationBinding.dataProtocol is set to `"getParams"` or `"postParams"` only.

    See `transformRequest()` to review the list of default metadata fields. In case you need to add additional parameters to the dsRequest object, you can do it via `RPCRequest.params`.

    Returns:
      Current sendMetaData value. Default value is true

  - ### setUpdateDataURL

    public RestDataSource setUpdateDataURL(String updateDataURL) throws IllegalStateException
    Custom `dataURL` for `DSRequests` with `operationType` "update".

    See `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Parameters:
      `updateDataURL` - New updateDataURL value. Default value is null
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getUpdateDataURL

    public String getUpdateDataURL()
    Custom `dataURL` for `DSRequests` with `operationType` "update".

    See `dataURL` to configure a single URL for all requests, which is required to support `RPCManager.startQueue()`.

    Returns:
      Current updateDataURL value. Default value is null

  - ### setXmlNamespaces

    public RestDataSource setXmlNamespaces(XmlNamespaces xmlNamespaces) throws IllegalStateException
    When `dataFormat` is "xml", `xmlNamespaces` configures the set of namespace prefixes that are added to the document element of the XML message sent to the server. Format is the same as `DataSource.xmlNamespaces`.

    By default, the "xsi" prefix is bound to "http://www.w3.org/2001/XMLSchema-instance" in order to allow explicit null values in Records to be sent for `fields declared nillable`. Set to null to avoid any prefixes being added.

    Overrides:
      `setXmlNamespaces` in class `DataSource`
    Parameters:
      `xmlNamespaces` - New xmlNamespaces value. Default value is See below
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `DataSourceField.setNillable(java.lang.Boolean)`

  - ### getXmlNamespaces

    public XmlNamespaces getXmlNamespaces()
    When `dataFormat` is "xml", `xmlNamespaces` configures the set of namespace prefixes that are added to the document element of the XML message sent to the server. Format is the same as `DataSource.xmlNamespaces`.

    By default, the "xsi" prefix is bound to "http://www.w3.org/2001/XMLSchema-instance" in order to allow explicit null values in Records to be sent for `fields declared nillable`. Set to null to avoid any prefixes being added.

    Returns:
      Current xmlNamespaces value. Default value is See below
    See Also:
      - `DataSourceField.getNillable()`

  - ### setXmlRecordXPath

    public RestDataSource setXmlRecordXPath(String xmlRecordXPath) throws IllegalStateException
    `recordXPath` mapping to the data node of XML returned by the server. Applies if this.dataFormat is set to `"xml"`.
    The default value will pick up data from a response structured as follows:

          <response>
             <status>0</status>
             <data>
               <record>
                   <field1>value</field1>
                   <field2>value</field2>
               </record>
               <record>
                   <field1>value</field1>
                   <field2>value</field2>
               </record>
             </data>
          </response>

    Parameters:
      `xmlRecordXPath` - New xmlRecordXPath value. Default value is "/response/data/*"
    Returns:
      `RestDataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getXmlRecordXPath

    public String getXmlRecordXPath()
    `recordXPath` mapping to the data node of XML returned by the server. Applies if this.dataFormat is set to `"xml"`.
    The default value will pick up data from a response structured as follows:

          <response>
             <status>0</status>
             <data>
               <record>
                   <field1>value</field1>
                   <field2>value</field2>
               </record>
               <record>
                   <field1>value</field1>
                   <field2>value</field2>
               </record>
             </data>
          </response>

    Returns:
      Current xmlRecordXPath value. Default value is "/response/data/*"

  - ### setDefaultProperties

    public static void setDefaultProperties(RestDataSource restDataSourceProperties)
    Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

    Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

    Parameters:
      `restDataSourceProperties` - properties that should be used as new defaults when instances of this class are created
    See Also:
      - `SGWTProperties`