Package com.smartgwt.client.data

# Class DataSource

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

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

Direct Known Subclasses:
  `FacadeDataSource`, `MockDataSource`, `RestDataSource`, `WSDataSource`, `XJSONDataSource`

public class DataSource extends BaseClass implements HasDataChangedHandlers, HasHandleErrorHandlers
A DataSource is data-provider-independent description of a set of objects that will be loaded, edited and saved within the user interface of your application.

Each DataSource consists of a list of `fields` that make up a DataSource `record`, along with `field types`, `validation rules`, `relationships` to other DataSources, and other metadata.

The abstract object description provided by a DataSource is easily mapped to a variety of backend object models and storage schemes. The following table shows analogous terminology across systems.

Isomorphic Smart GWT | Relational Database | Enterprise Java Beans (EJB) | Entity/Relationship Modeling | OO/UML | XML Schema/WSDL | LDAP
DataSource | Table | EJB class | Entity | Class | Element Schema (ComplexType) | Objectclass
Record | Row | EJB instance | Entity instance | Class instance/Object | Element instance (ComplexType) | Entry
Field | Column | Property | Attribute | Property/Attribute | Attribute or Element (SimpleType) | Attribute

DataSources can be `declared` in either JavaScript or XML format, and can also be `imported` from existing metadata formats, including XML Schema.

Data Binding is the process by which `Data Binding-capable UI components` can automatically configure themselves for viewing, editing and saving data described by DataSources. DataBinding is covered in the 'QuickStart Guide', Chapter 6, Data Binding.

`Data Integration` is the process by which a DataSource can be connected to server systems such as SQL DataBases, Java Object models, WSDL web services and other data providers. Data Integration comes in two variants: client-side and server-side. `Server-side integration` uses the Smart GWT Java-based server to connect to data represented by Java Objects or JDBC-accessible databases. `Client-side integration` connects Smart GWT DataSources to XML, JSON or other formats accessible via HTTP.

DataSources have a concept of `4 core operations` ("fetch", "add", "update" and "remove") that can be performed on the set of objects represented by a DataSource. Once a DataSource has been integrated with your data store, databinding-capable UI components can leverage the 4 core DataSource operations to provide many complete user interactions without the need to configure how each individual component loads and saves data.

These interactions include `grid views`, `tree views`, `detail views`, `form`-based `editing` and `saving`, grid-based `editing` and `saving`, and custom interactions provided by Pattern Reuse Example custom databinding-capable components.

See Also:
  - `DataBoundComponent`
  - `FileSource Operations`

- ## Field Summary

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

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataSource()`
  `DataSource(JavaScriptObject jsObj)`
  `DataSource(String dataURL)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addData(Record newRecord)`
  Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
  `void`
  `addData(Record newRecord, DSCallback callback)`
  `void`
  `addData(Record newRecord, DSCallback callback, DSRequest requestProperties)`
  Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
  `HandlerRegistration`
  `addDataChangedHandler(DataChangedHandler handler)`
  Add a dataChanged handler.
  `void`
  `addField(DataSourceField field)`
  Add a field to the DataSource
  `HandlerRegistration`
  `addHandleErrorHandler(HandleErrorHandler handler)`
  Add a handleError handler.
  `void`
  `addSearchOperator(Operator operator, FieldType[] types)`
  Add a new search operator, only to this DataSource.
  `Record[]`
  `applyFilter(Record[] records, Criteria criteria)`
  Returns records in the passed Record that match the provided filter `Criteria`.
  `Record[]`
  `applyFilter(Record[] records, Criteria criteria, DSRequest requestProperties)`
  Returns records in the passed Record that match the provided filter `Criteria`.
  `static boolean`
  `canFlattenCriteria(AdvancedCriteria criteria)`
  Returns true if calling `flattenCriteria()` on the passed criteria would produce logically equivalent criteria.
  `static void`
  `clearValueAtDataPath(DataSourceField field, String dataPath, Record values)`
  Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `clearValueAtDataPath(FormItem field, String dataPath, Record values)`
  Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `clearValueAtDataPath(ListGridField field, String dataPath, Record values)`
  Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `clearValueAtDataPath(DetailViewerField field, String dataPath, Record values)`
  Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.
  `DSRequest`
  `cloneDSRequest(DSRequest dsRequest)`
  Creates a shallow copy of the given `DSRequest`.
  `DSResponse`
  `cloneDSResponse(DSResponse dsResponse)`
  Creates a shallow copy of the given `DSResponse`.
  `static Criteria`
  `combineCriteria(Criteria criteria1, Criteria criteria2)`
  Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator".
  `static Criteria`
  `combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator)`
  `static Criteria`
  `combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator, TextMatchStyle textMatchStyle)`
  Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator".
  `int`
  `compareCriteria(Criteria newCriteria, Criteria oldCriteria)`
  Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.
  `int`
  `compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties)`
  `int`
  `compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties, String policy)`
  Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.
  `int`
  `compareDates(Date date1, Date date2, String fieldName)`
  Convenience method to compare two Date objects appropriately, depending on whether the passed-in fieldName refers to a field of `type` "datetime" or "date".
  `static AdvancedCriteria`
  `convertCriteria(Criteria criteria)`
  Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
  `static AdvancedCriteria`
  `convertCriteria(Criteria criteria, TextMatchStyle textMatchStyle)`
  Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
  `AdvancedCriteria`
  `convertDataSourceCriteria(Criteria criteria)`
  Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
  `AdvancedCriteria`
  `convertDataSourceCriteria(Criteria criteria, TextMatchStyle textMatchStyle)`
  Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
  `Criteria`
  `convertRelativeDates(Criteria criteria)`
  Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.
  `Criteria`
  `convertRelativeDates(Criteria criteria, String timezoneOffset)`
  `Criteria`
  `convertRelativeDates(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek)`
  `Criteria`
  `convertRelativeDates(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek, Date baseDate)`
  Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.
  `static Criteria`
  `copyCriteria(Criteria criteria)`
  Create a copy of a criteria.
  `Record`
  `copyRecord(Record record)`
  Copies all DataSource field values of a Record (including a TreeNode) to a new Record, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.
  `Record[]`
  `copyRecords(Record... records)`
  Copies all DataSource field values of an (Array) of Records (including a TreeNode) to a new array of Records, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.
  `JavaScriptObject`
  `create()`
  `void`
  `createAlias(String alias)`
  Assigns an alias to this DataSource
  `void`
  `downloadFile(Record data)`
  Download a file stored in a field of type:"binary" in a DataSource record.
  `void`
  `downloadFile(Record data, String fieldName)`
  `void`
  `downloadFile(Record data, String fieldName, DSRequest requestProperties)`
  Download a file stored in a field of type:"binary" in a DataSource record.
  `boolean`
  `evaluateCriterion(Record record, Criterion criterion)`
  Evaluate the given criterion with respect to the passed record.
  `void`
  `execute(DSRequest dsRequest)`
  Executes the given DSRequest on this DataSource.
  `void`
  `exportClientData(Object[] data, DSRequest requestProperties)`
  Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users.
  `static void`
  `exportClientDataStatic(Object[] data, DSRequest requestProperties)`
  Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users.
  `void`
  `exportData()`
  Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results.
  `void`
  `exportData(Criteria criteria)`
  `void`
  `exportData(Criteria criteria, DSRequest requestProperties)`
  `void`
  `exportData(Criteria criteria, DSRequest requestProperties, DSCallback callback)`
  Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results.
  `void`
  `fetchData()`
  Deprecated.
  `void`
  `fetchData(Criteria criteria)`
  `void`
  `fetchData(Criteria criteria, DSCallback callback)`
  `void`
  `fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)`
  Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
  `void`
  `fetchRecord(Object pkValue)`
  Fetch a single record from the DataSource by `primary key`.
  `void`
  `fetchRecord(Object pkValue, DSCallback callback)`
  `void`
  `fetchRecord(Object pkValue, DSCallback callback, DSRequest requestProperties)`
  Fetch a single record from the DataSource by `primary key`.
  `boolean`
  `fieldMatchesFilter(Object fieldValue, Object filterValue)`
  Compares a criteria value to a field value and returns whether they match, as follows: any non-String filter value is directly compared (==) to the field value any String filter value is compared according to `DSRequest.textMatchStyle` in the passed `requestProperties`, regardless of the actual field type if the filter value is an Array, the comparison is a logical OR.
  `boolean`
  `fieldMatchesFilter(Object fieldValue, Object filterValue, DSRequest requestProperties)`
  Compares a criteria value to a field value and returns whether they match, as follows: any non-String filter value is directly compared (==) to the field value any String filter value is compared according to `DSRequest.textMatchStyle` in the passed `requestProperties`, regardless of the actual field type if the filter value is an Array, the comparison is a logical OR.
  `void`
  `filterData()`
  Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
  `void`
  `filterData(Criteria criteria)`
  `void`
  `filterData(Criteria criteria, DSCallback callback)`
  `void`
  `filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)`
  Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
  `static AdvancedCriteria`
  `flattenCriteria(AdvancedCriteria criteria)`
  Returns new criteria that has at most one top-level LogicalOperator ("and" or "or").
  `String`
  `formatFieldValue(DataSourceField field, Object value)`
  Formats the supplied value using the `SimpleType` derived from the field definition.
  `static DataSource`
  `get(String ID)`
  Synonym of `DataSource.getDataSource`: Lookup a DataSource by ID.
  `static DataSource`
  `get(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)`
  Synonym of `DataSource.getDataSource`: Lookup a DataSource by ID.
  `DataSourceField[]`
  `getAddedAuditFields()`
  The list of extra manually managed fields that will be added to the `fields` of the `Audit DataSource`.
  `Boolean`
  `getAddGlobalId()`
  Whether to make this DataSource available as a global variable for convenience.
  `static String`
  `getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource)`
  Returns a human-readable string describing the clauses in this advanced criteria or criterion.
  `static String`
  `getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource, CriteriaOutputSettings criteriaOutputSettings)`
  Returns a human-readable string describing the clauses in this advanced criteria or criterion.
  `static String`
  `getAggregationDescription(AdvancedCriterionSubquery subquery, DataSource dataSource)`
  Returns a human-readable string describing the aggregation properties in the request: `DSRequest.groupBy` and `DSRequest.summaryFunctions`.
  `Boolean`
  `getAllowAdvancedCriteria()`
  By default, all DataSources are assumed to be capable of handling `AdvancedCriteria` on fetch or filter type operations.
  `Boolean`
  `getAllowAggregation()`
  This property indicates whether this DataSource supports aggregation/summarization and grouping of field values using the `summaryFunction` mechanism.
  `Boolean`
  `getAllowCriteriaSubqueries()`
  Controls whether `AdvancedCriteria subqueries` are permitted for this `DataSource`.
  `Boolean`
  `getAllowDynamicTreeJoins()`
  By default, custom dataSource implementations are assumed to be unable to support `dynamic tree joins`.
  `Boolean`
  `getAllowRelatedFieldsInCriteria()`
  This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries.
  `RelationPath`
  `getAllPathsToRelation(DataSource targetDS)`
  Returns all known paths between this and the given targetDS.
  `RelationPath`
  `getAllPathsToRelation(String targetDS)`
  Returns all known paths between this and the given targetDS.
  `Boolean`
  `getArrayCriteriaForceExact()`
  With ordinary `simple criteria`, it is possible to provide an array of values for a given field, which means "any of these values".
  `Boolean`
  `getAutoCacheAllData()`
  When a DataSource is not `cacheAllData`:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch to `cacheAllData:true` and prevent further server-trips for fetch requests.
  `Boolean`
  `getAutoConvertRelativeDates()`
  Whether to convert relative date values to concrete date values before sending to the server.
  `boolean`
  `getAutoDeriveTitles()`
  If set, titles are automatically derived from `field.name` for any field that does not have a `field.title` and is not marked `hidden`:true, by calling the method `getAutoTitle()`.
  `boolean`
  `getAutoDiscoverTree()`
  Causes `Tree.discoverTree()` to be called on dsResponse.data in order to automatically discover tree structures in the response data.
  `static String`
  `getAutoTitle(String identifier)`
  Utility method to derive a reasonable user-visible title from an identifier.
  `Boolean`
  `getCacheAcrossOperationIds()`
  When `cacheAllData` mode is enabled and a `cacheAllOperationId` has been set, this flag affects whether cached results are used for all "fetch" requests regardless of their `DSRequest.operationId`, or are used only for "fetch" requests that use the `cacheAllOperationId`, allowing other requests to go to server normally.
  `Boolean`
  `getCacheAllData()`
  Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
  `String`
  `getCacheAllOperationId()`
  `DSRequest.operationId` to use for fetching data in case `cacheAllData` is true.
  `Record[]`
  `getCacheData()`
  For a `cacheAllData` or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.
  `int`
  `getCacheMaxAge()`
  The maximum time, in seconds, to maintain the client-side cache.
  `String`
  `getCallbackParam()`
  Applies only to dataFormat: "json" and `dataTransport`:"scriptInclude".
  `Boolean`
  `getCanAggregate()`
  By default, all DataSources are assumed to be capable of handling `ServerSummaries` on fetch or filter type operations.
  `boolean`
  `getCanMultiSort()`
  When true, indicates that this DataSource supports multi-level sorting.
  `String`
  `getChildrenField()`
  fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
  `Boolean`
  `getClientOnly()`
  A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as `DSRequests` are executed on it.
  `void`
  `getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback)`
  Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that `inheritsFrom` the original DataSource.
  `void`
  `getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties)`
  `void`
  `getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties, DataSource dataSourceProperties)`
  Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that `inheritsFrom` the original DataSource.
  `protected DSResponse`
  `getClientOnlyResponse(DSRequest request, Record... serverData)`
  Return a "spoofed" response for a `clientOnly` or `cacheAllData` DataSource.
  `CriteriaPolicy`
  `getCriteriaPolicy()`
  Decides under what conditions the `ResultSet` cache should be dropped when the `ResultSet.criteria` changes.
  `String`
  `getDataField()`
  Name of the field that has the most pertinent numeric, date, or enum value, for use when a `DataBoundComponent` needs to show a short summary of a record.
  `DSDataFormat`
  `getDataFormat()`
  Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when `fetchData()` is called).
  `DSProtocol`
  `getDataProtocol()`
  Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
  `static DataSource`
  `getDataSource(String ID)`
  Lookup a DataSource by ID.
  `static DataSource`
  `getDataSource(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)`
  Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer.
  `RPCTransport`
  `getDataTransport()`
  Transport to use for all operations on this DataSource.
  `String`
  `getDataURL()`
  Default URL to contact to fulfill all DSRequests.
  `Boolean`
  `getDeepCloneNonFieldValuesOnEdit()`
  When editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or by `dataPath`).
  `Boolean`
  `getDeepCloneOnEdit()`
  Before we start editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays).
  `Map`
  `getDefaultParams()`
  HTTP parameters that should be submitted with every DSRequest.
  `RelationPath`
  `getDefaultPathToRelation(DataSource targetDS)`
  Returns the path having the shortest distance between this and the given targetDS, as determined by `getShortestPathToRelation()`.
  `RelationPath`
  `getDefaultPathToRelation(String targetDS)`
  Returns the path having the shortest distance between this and the given targetDS, as determined by `getShortestPathToRelation()`.
  `TextMatchStyle`
  `getDefaultTextMatchStyle()`
  The default textMatchStyle to use for `DSRequest`s that do not explicitly state a `textMatchStyle`.
  `String`
  `getDescription()`
  An optional description of the DataSource's content.
  `String`
  `getDescriptionField()`
  Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.
  `DiscoverTreeSettings`
  `getDiscoverTreeSettings()`
  Settings to use when discoverTree() is automatcially called because `autoDiscoverTree` is set to true for this DataSource
  `Object`
  `getDisplayValue(String fieldName, Object value)`
  Given a fieldName and a dataValue, apply any `DataSourceField.valueMap` for the field and return the display value for the field
  `Boolean`
  `getDropExtraFields()`
  Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.
  `Boolean`
  `getDropUnknownCriteria()`
  If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client.
  `Boolean`
  `getEnforceSecurityOnClient()`
  Indicates that `DeclarativeSecurity` should be enforced on the client.
  `String`
  `getFetchDataURL(Criteria criteria)`
  Returns a URL to DataSource fetch operation.
  `String`
  `getFetchDataURL(Criteria criteria, DSRequest requestProperties)`
  Returns a URL to DataSource fetch operation.
  `DataSourceField`
  `getField(String fieldName)`
  Return the field definition object.
  `String`
  `getFieldAutoTitle(String identifier)`
  Return a reasonable user-visible title given a fieldName.
  `Criteria`
  `getFieldCriterion(Criteria criterion, String fieldName)`
  Returns the depth-first match of a criterion matching the given fieldName.
  `OperatorId[]`
  `getFieldDefaultOperator(DataSourceField field)`
  Get the default `OperatorId` for this field.
  `OperatorId[]`
  `getFieldDefaultOperator(String field)`
  Get the default `OperatorId` for this field.
  `DataSourceField`
  `getFieldForDataPath(String dataPath)`
  Return the field definition object corresponding to the supplied dataPath
  `String[]`
  `getFieldNames()`
  Retrieves the list of fields declared on this DataSource.
  `String[]`
  `getFieldNames(boolean excludeHidden)`
  Retrieves the list of fields declared on this DataSource.
  `OperatorId[]`
  `getFieldOperators(DataSourceField field)`
  Get the list of OperatorId's available for the passed field.
  `OperatorId[]`
  `getFieldOperators(String fieldName)`
  Get the list of OperatorId's available for the passed field-name.
  `DataSourceField[]`
  `getFields()`
  The list of fields that compose records from this DataSource.
  `static Object`
  `getFieldValue(DataSourceField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)`
  Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.
  `static Object`
  `getFieldValue(FormItem field, Record record)`
  Given a field definition and a record object, this method will return the field value for the record.
  `static Object`
  `getFieldValue(FormItem field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)`
  Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.
  `static Object`
  `getFieldValue(ListGridField field, Record record)`
  Given a field definition and a record object, this method will return the field value for the record.
  `static Object`
  `getFieldValue(ListGridField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)`
  Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.
  `static Object`
  `getFieldValue(DetailViewerField field, Record record)`
  Given a field definition and a record object, this method will return the field value for the record.
  `static Object`
  `getFieldValue(DetailViewerField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)`
  Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.
  `void`
  `getFile(FileSpec fileSpec, GetFileCallback callback)`
  Gets the contents of a file stored in this DataSource.
  `String`
  `getFileURL(Record data)`
  Returns a direct URL to access a file stored in a field of type:"binary".
  `String`
  `getFileURL(Record data, String fieldName)`
  `String`
  `getFileURL(Record data, String fieldName, DSRequest requestProperties)`
  Returns a direct URL to access a file stored in a field of type:"binary".
  `void`
  `getFileVersion(FileSpec fileSpec, Date version, GetFileVersionCallback callback)`
  Gets the contents of a particular file version stored in this DataSource.
  `Map`
  `getGlobalNamespaces()`
  Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.
  `String`
  `getIconField()`
  Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.
  `Boolean`
  `getIgnoreTextMatchStyleCaseSensitive()`
  For fields on this dataSource that specify `ignoreTextMatchStyle` true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values.
  `Criteria`
  `getImplicitCriteria()`
  Criteria that are implicitly applied to all fetches made through this DataSource.
  `String`
  `getInfoField()`
  Name of the field that has the second most pertinent piece of textual information in the record, for use when a `DataBoundComponent` needs to show a short summary of a record.
  `String`
  `getInheritsFrom()`
  ID of another DataSource this DataSource inherits its `fields` from.
  `Boolean`
  `getIsSampleDS()`
  Used by Reify to identify DataSources that are provided as samples.
  `JavaScriptObject`
  `getJsObj()`
  `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`
  `getJsonSuffix()`
  Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
  `void`
  `getLegalChildTags()`
  For a DataSource that describes a DOM structure, the list of legal child elements that can be contained by the element described by this DataSource.
  `static String`
  `getLoaderURL()`
  Returns the `loaderURL`
  `Criteria`
  `getMockDataCriteria()`
  When `mockMode` is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.
  `Integer`
  `getMockDataRows()`
  When `mockMode` is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data.
  `Boolean`
  `getMockMode()`
  If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to a `clientOnly` DataSource, never writing changes back to the server.
  `OperationBinding[]`
  `getOperationBindings()`
  Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
  `static DataSource`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `String`
  `getPatternEscapeChar()`
  When using the `pattern operators` `search operator`, character that escapes the `patternSingleWildcard` or `patternMultiWildcard` if placed before it, so that it is treated as a literal character.
  `String`
  `getPatternMultiWildcard()`
  When using the `pattern operators` `search operator`, character that matches a series of one or more characters.
  `String[]`
  `getPatternMultiWildcardAsString()`
  Deprecated.
  in favor of `getPatternMultiWildcardAsStringArray()`.
  `String[]`
  `getPatternMultiWildcardAsStringArray()`
  When using the `pattern operators` `search operator`, character that matches a series of one or more characters.
  `String`
  `getPatternSingleWildcard()`
  When using the `pattern operators` `search operator`, character that matches any single character.
  `String[]`
  `getPatternSingleWildcardAsString()`
  Deprecated.
  in favor of `getPatternSingleWildcardAsStringArray()`.
  `String[]`
  `getPatternSingleWildcardAsStringArray()`
  When using the `pattern operators` `search operator`, character that matches any single character.
  `String`
  `getPluralTitle()`
  User-visible plural name for this DataSource.
  `Boolean`
  `getPreventHTTPCaching()`
  If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.
  `DataSourceField`
  `getPrimaryKeyField()`
  Returns a pointer to the primaryKey field for this DataSource.
  `String`
  `getPrimaryKeyFieldName()`
  Returns the primary key fieldName for this DataSource.
  `String[]`
  `getPrimaryKeyFieldNames()`
  Returns a list of the names of this DataSource's `primaryKey` fields.
  `Record`
  `getPrimaryKeyFields()`
  Returns this DataSource's `primaryKey` fields as a map of fieldName to field.
  `Boolean`
  `getProgressiveLoading()`
  If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the `ResultSet documentation`.
  `Boolean`
  `getQualifyColumnNames()`
  For dataSources of `serverType` "sql", determines whether we qualify column names with table names in any SQL we generate.
  `String`
  `getRecordName()`
  Provides a default value for `OperationBinding.recordName`.
  `String`
  `getRecordXPath()`
  See `OperationBinding.recordXPath`.
  `DSRequest`
  `getRequestProperties()`
  Additional properties to pass through to the `DSRequest`s made by this DataSource.
  `String`
  `getRequiredMessage()`
  The required message when a field that has been marked as `required` is not filled in by the user.
  `int`
  `getResultBatchSize()`
  Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.
  `String`
  `getResultSetClass()`
  Class for ResultSets used by this datasource.
  `String`
  `getResultTreeClass()`
  Class for ResultTrees used by this datasource.
  `Record[]`
  `getSampleData()`
  An optional array of sample data records.
  `String`
  `getSchemaNamespace()`
  For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to.
  `Boolean`
  `getSendExtraFields()`
  Analogous to `dropExtraFields`, for data sent to the server.
  `Boolean`
  `getSendParentNode()`
  Set this attribute if you need to send the dsRequest.parentNode to the server-side.
  `String`
  `getServiceNamespace()`
  For an XML DataSource, URN of the WebService to use to invoke operations.
  `RelationPath`
  `getShortestPathToRelation(DataSource targetDS)`
  Returns the path having the shortest distance between this and the given targetDS.
  `RelationPath`
  `getShortestPathToRelation(String targetDS)`
  Returns the path having the shortest distance between this and the given targetDS.
  `Boolean`
  `getShowLocalFieldsOnly()`
  For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that only the fields listed in this DataSource should be shown.
  `Boolean`
  `getShowPrompt()`
  Whether RPCRequests sent by this DataSource should enable `RPCRequest.showPrompt` in order to block user interactions until the request completes.
  `SkipJSONValidation`
  `getSkipJSONValidation()`
  Sets what level of JSON validation will apply for this DataSource.
  `static String[]`
  `getSortBy(SortSpecifier[] sortSpecifiers)`
  Given an array of `SortSpecifier`s, return a simple list of Strings in the format expected by `DSRequest.sortBy`.
  `static SortSpecifier[]`
  `getSortSpecifiers(String[] sortBy)`
  Return an array of `SortSpecifier`s, given an array of Strings in the format expected by `DSRequest.sortBy`.
  `static SortSpecifier[]`
  `getSortSpecifiers(String[] sortBy, DataSource context)`
  Return an array of `SortSpecifier`s, given an array of Strings in the format expected by `DSRequest.sortBy`.
  `Boolean`
  `getStrictSQLFiltering()`
  If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.
  `String`
  `getTagName()`
  Tag name to use when serializing to XML.
  `Record[]`
  `getTestData()`
  For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
  `String`
  `getTitle()`
  User-visible name for this DataSource.
  `String`
  `getTitleField()`
  Best field to use for a user-visible title for an individual record from this dataSource.
  `boolean`
  `getTranslatePatternOperators()`
  `Search operators` like "matchesPattern" use patterns like "foo*txt" to match text values.
  `Boolean`
  `getTrimMilliseconds()`
  For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa.
  `OperatorId[]`
  `getTypeOperators()`
  Get the list of `OperatorId`s available on this DataSource for the given `FieldType`.
  `OperatorId[]`
  `getTypeOperators(FieldType typeName)`
  Get the list of `OperatorId`s available on this DataSource for the given `FieldType`.
  `OperatorId[]`
  `getTypeOperators(String typeName)`
  Get the list of `OperatorId`s available on this DataSource for the given `FieldType`.
  `Boolean`
  `getUseFlatFields()`
  Like `DataBoundComponent.useFlatFields`, but applies to all DataBound components that bind to this DataSource.
  `Boolean`
  `getUseHttpProxy()`
  Like `OperationBinding.useHttpProxy`, but serves as a default for this DataSource that may be overridden by individual operationBindings.
  `Boolean`
  `getUseLocalValidators()`
  Whether to attempt validation on the client at all for this DataSource.
  `Boolean`
  `getUseOfflineStorage()`
  Whether we store server responses for this DataSource into `browser-based offline storage`, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server).
  `Boolean`
  `getUseParentFieldOrder()`
  For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.
  `Boolean`
  `getUseStrictJSON()`
  Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.
  `Boolean`
  `getUseTestDataFetch()`
  When set, causes a `client-only` or `cacheAllData` DataSource to create a second DataSource to perform it's one-time fetch.
  `Boolean`
  `getValidateRelatedRecords()`
  If true, indicates that the Smart GWT Server should automatically apply a `ValidatorType` of "hasRelatedRecord" to every field on this dataSource that has a `foreignKey` defined.
  `Boolean`
  `hasAllData()`
  When `cacheAllData` is true, has all the data been retrieved to the client?
  `void`
  `hasCustomTypeOperators(FieldType typeName)`
  Returns true if the operator list for the passed type has been customized via a call to `setTypeOperators()`.
  `void`
  `hasCustomTypeOperators(String typeName)`
  Returns true if the operator list for the passed type has been customized via a call to `setTypeOperators()`.
  `static void`
  `hasCustomTypeOperators(String typeName, DataSource ds)`
  Returns true if the operator list for the passed type has been customized via a call to `setTypeOperators()`.
  `void`
  `hasFile(FileSpec fileSpec, HasFileCallback callback)`
  Indicates whether a file exists in this DataSource.
  `void`
  `hasFileVersion(FileSpec fileSpec, Date version, HasFileCallback callback)`
  Indicates whether a particular file version exists in this DataSource.
  `void`
  `invalidateCache()`
  Drop the current dataSource cache.
  `void`
  `invalidateCache(boolean notify)`
  Drop the current dataSource cache.
  `static Boolean`
  `isAdvancedCriteria(Criteria criteria)`
  Determines whether the passed criteria object is AdvancedCriteria or simple criteria.
  `static Boolean`
  `isAdvancedCriteria(Criteria criteria, DataSource dataSource)`
  Determines whether the passed criteria object is AdvancedCriteria or simple criteria.
  `boolean`
  `isCalculated(DataSourceField field)`
  Does the specified field have its value dynamically calculated via `DataSourceField.formula` or other similar attributes?
  `boolean`
  `isCalculated(String field)`
  Does the specified field have its value dynamically calculated via `DataSourceField.formula` or other similar attributes?
  `boolean`
  `isCreated()`
  `static boolean`
  `isFlatCriteria(AdvancedCriteria criteria)`
  Returns true if a given AdvancedCriteria is "flat." That is, the criteria consists of either: a top-level "and" or "or" `Criterion`, where none of the `subcriteria` use `logical operators`, hence have no subcriteria of their own a single Criterion that is not a logical operator, hence has no subcriteria
  `void`
  `listFiles(Criteria criteria, DSCallback callback)`
  Get a list of files from the DataSource.
  `void`
  `listFileVersions(FileSpec fileSpec, DSCallback callback)`
  Get the list of a given file's versions from the dataSource, sorted in version order (most recent version first).
  `static void`
  `load(String[] dsID, Function callback, boolean forceReload)`
  Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
  `static void`
  `load(String[] dsID, Function callback, DSLoadSettings settings)`
  Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
  `static void`
  `load(String dsID, Function callback)`
  Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
  `static void`
  `load(String dsID, Function callback, boolean forceReload)`
  Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
  `static void`
  `loadWithParents(String[] dsID, Function callback, boolean forceReload)`
  Variation of `DataSource.load` that will also automatically load any DataSources that the requested DataSources inherit from (via `DataSource.inheritsFrom`)
  `static void`
  `loadWithParents(String[] dsID, Function callback, DSLoadSettings settings)`
  Variation of `DataSource.load` that will also automatically load any DataSources that the requested DataSources inherit from (via `DataSource.inheritsFrom`).
  `static void`
  `loadWithParents(String dsID, Function callback)`
  Variation of `load()` that will also automatically load any DataSources that the requested DataSources inherit from (via `inheritsFrom`).
  `static void`
  `loadWithParents(String dsID, Function callback, boolean forceReload)`
  Variation of `load()` that will also automatically load any DataSources that the requested DataSources inherit from (via `inheritsFrom`).
  `static FileSpec`
  `makeFileSpec(String path)`
  Converts a file path to a `FileSpec`.
  `protected void`
  `onInit()`
  `void`
  `performCustomOperation(String operationId)`
  Invoke an operation declared with `OperationBinding.operationType` "custom".
  `void`
  `performCustomOperation(String operationId, Record data)`
  `void`
  `performCustomOperation(String operationId, Record data, DSCallback callback)`
  `void`
  `performCustomOperation(String operationId, Record data, DSCallback callback, DSRequest requestProperties)`
  Invoke an operation declared with `OperationBinding.operationType` "custom".
  `void`
  `processResponse(String requestId, DSResponse dsResponse)`
  Process a dsResponse for a request initiated by a DataSource with `dataProtocol:"clientCustom"`.
  `boolean`
  `recordsAreEqual(Object record1, Object record2)`
  Convenience method to test if two records are equal.
  `String`
  `recordsAsText(Record[] records)`
  Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).
  `String`
  `recordsAsText(Record[] records, TextExportSettings settings)`
  Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).
  `Record[]`
  `recordsFromText(String text)`
  Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.
  `Record[]`
  `recordsFromText(String text, TextImportSettings settings)`
  Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.
  `Record[]`
  `recordsFromXML(Object elements)`
  Transform a list of XML elements to DataSource records.
  `protected void`
  `registerID(String id, boolean skipUniqueJSIdentifierCheck)`
  `void`
  `removeData(Record data)`
  Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
  `void`
  `removeData(Record data, DSCallback callback)`
  `void`
  `removeData(Record data, DSCallback callback, DSRequest requestProperties)`
  Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
  `void`
  `removeFile(FileSpec fileSpec)`
  Remove a file stored in this DataSource.
  `void`
  `removeFile(FileSpec fileSpec, DSCallback callback)`
  Remove a file stored in this DataSource.
  `void`
  `removeFile(String fileSpec)`
  Remove a file stored in this DataSource.
  `void`
  `removeFileVersion(FileSpec fileSpec, Date version)`
  Remove a particular file version stored in this DataSource.
  `void`
  `removeFileVersion(FileSpec fileSpec, Date version, DSCallback callback)`
  Remove a particular file version stored in this DataSource.
  `void`
  `renameFile(FileSpec oldFileSpec, FileSpec newFileSpec)`
  Rename a file stored in this DataSource.
  `void`
  `renameFile(FileSpec oldFileSpec, FileSpec newFileSpec, DSCallback callback)`
  Rename a file stored in this DataSource.
  `void`
  `saveFile(FileSpec fileSpec, String contents)`
  Save a file to the DataSource.
  `void`
  `saveFile(FileSpec fileSpec, String contents, DSCallback callback)`
  Save a file to the DataSource.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, JavaScriptObject value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, Boolean value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, Double value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, Float value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, Integer value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, String value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, Date value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DataSourceField field, String dataPath, Map value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, JavaScriptObject value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, Boolean value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, Double value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, Float value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, Integer value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, String value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, Date value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(FormItem field, String dataPath, Map value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, JavaScriptObject value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, Boolean value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, Double value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, Float value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, Integer value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, String value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, Date value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(ListGridField field, String dataPath, Map value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, JavaScriptObject value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, Boolean value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, Double value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, Float value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, Integer value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, String value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, Date value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `static void`
  `saveValueViaDataPath(DetailViewerField field, String dataPath, Map value, Record values, String reason)`
  Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.
  `DataSource`
  `setAddedAuditFields(DataSourceField... addedAuditFields)`
  The list of extra manually managed fields that will be added to the `fields` of the `Audit DataSource`.
  `void`
  `setAddGlobalId(Boolean addGlobalId)`
  Whether to make this DataSource available as a global variable for convenience.
  `DataSource`
  `setAllowAdvancedCriteria(Boolean allowAdvancedCriteria)`
  By default, all DataSources are assumed to be capable of handling `AdvancedCriteria` on fetch or filter type operations.
  `DataSource`
  `setAllowAggregation(Boolean allowAggregation)`
  This property indicates whether this DataSource supports aggregation/summarization and grouping of field values using the `summaryFunction` mechanism.
  `DataSource`
  `setAllowCriteriaSubqueries(Boolean allowCriteriaSubqueries)`
  Controls whether `AdvancedCriteria subqueries` are permitted for this `DataSource`.
  `DataSource`
  `setAllowDynamicTreeJoins(Boolean allowDynamicTreeJoins)`
  By default, custom dataSource implementations are assumed to be unable to support `dynamic tree joins`.
  `DataSource`
  `setAllowRelatedFieldsInCriteria(Boolean allowRelatedFieldsInCriteria)`
  This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries.
  `DataSource`
  `setArrayCriteriaForceExact(Boolean arrayCriteriaForceExact)`
  With ordinary `simple criteria`, it is possible to provide an array of values for a given field, which means "any of these values".
  `DataSource`
  `setAutoCacheAllData(Boolean autoCacheAllData)`
  When a DataSource is not `cacheAllData`:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch to `cacheAllData:true` and prevent further server-trips for fetch requests.
  `DataSource`
  `setAutoConvertRelativeDates(Boolean autoConvertRelativeDates)`
  Whether to convert relative date values to concrete date values before sending to the server.
  `DataSource`
  `setAutoDeriveTitles(boolean autoDeriveTitles)`
  If set, titles are automatically derived from `field.name` for any field that does not have a `field.title` and is not marked `hidden`:true, by calling the method `getAutoTitle()`.
  `DataSource`
  `setAutoDiscoverTree(boolean autoDiscoverTree)`
  Causes `Tree.discoverTree()` to be called on dsResponse.data in order to automatically discover tree structures in the response data.
  `DataSource`
  `setCacheAcrossOperationIds(Boolean cacheAcrossOperationIds)`
  When `cacheAllData` mode is enabled and a `cacheAllOperationId` has been set, this flag affects whether cached results are used for all "fetch" requests regardless of their `DSRequest.operationId`, or are used only for "fetch" requests that use the `cacheAllOperationId`, allowing other requests to go to server normally.
  `DataSource`
  `setCacheAllData(Boolean cacheAllData)`
  Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
  `DataSource`
  `setCacheAllOperationId(String cacheAllOperationId)`
  `DSRequest.operationId` to use for fetching data in case `cacheAllData` is true.
  `void`
  `setCacheData(Record... cacheData)`
  For a `cacheAllData` or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.
  `DataSource`
  `setCacheMaxAge(int cacheMaxAge)`
  The maximum time, in seconds, to maintain the client-side cache.
  `DataSource`
  `setCallbackParam(String callbackParam)`
  Applies only to dataFormat: "json" and `dataTransport`:"scriptInclude".
  `DataSource`
  `setCanAggregate(Boolean canAggregate)`
  By default, all DataSources are assumed to be capable of handling `ServerSummaries` on fetch or filter type operations.
  `DataSource`
  `setCanMultiSort(boolean canMultiSort)`
  When true, indicates that this DataSource supports multi-level sorting.
  `DataSource`
  `setChildrenField(String childrenField)`
  fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
  `DataSource`
  `setClientOnly(Boolean clientOnly)`
  A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as `DSRequests` are executed on it.
  `DataSource`
  `setCriteriaPolicy(CriteriaPolicy criteriaPolicy)`
  Decides under what conditions the `ResultSet` cache should be dropped when the `ResultSet.criteria` changes.
  `DataSource`
  `setDataField(String dataField)`
  Name of the field that has the most pertinent numeric, date, or enum value, for use when a `DataBoundComponent` needs to show a short summary of a record.
  `DataSource`
  `setDataFormat(DSDataFormat dataFormat)`
  Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when `fetchData()` is called).
  `DataSource`
  `setDataProtocol(DSProtocol dataProtocol)`
  Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
  `DataSource`
  `setDataTransport(RPCTransport dataTransport)`
  Transport to use for all operations on this DataSource.
  `DataSource`
  `setDataURL(String dataURL)`
  Default URL to contact to fulfill all DSRequests.
  `DataSource`
  `setDeepCloneNonFieldValuesOnEdit(Boolean deepCloneNonFieldValuesOnEdit)`
  When editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or by `dataPath`).
  `DataSource`
  `setDeepCloneOnEdit(Boolean deepCloneOnEdit)`
  Before we start editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays).
  `void`
  `setDefaultParams(Map defaultParams)`
  HTTP parameters that should be submitted with every DSRequest.
  `static void`
  `setDefaultProperties(DataSource dataSourceProperties)`
  Class level method to set the default properties of this class.
  `DataSource`
  `setDefaultTextMatchStyle(TextMatchStyle defaultTextMatchStyle)`
  The default textMatchStyle to use for `DSRequest`s that do not explicitly state a `textMatchStyle`.
  `DataSource`
  `setDescription(String description)`
  An optional description of the DataSource's content.
  `DataSource`
  `setDescriptionField(String descriptionField)`
  Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.
  `DataSource`
  `setDiscoverTreeSettings(DiscoverTreeSettings discoverTreeSettings)`
  Settings to use when discoverTree() is automatcially called because `autoDiscoverTree` is set to true for this DataSource
  `DataSource`
  `setDropExtraFields(Boolean dropExtraFields)`
  Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.
  `DataSource`
  `setDropUnknownCriteria(Boolean dropUnknownCriteria)`
  If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client.
  `DataSource`
  `setEnforceSecurityOnClient(Boolean enforceSecurityOnClient)`
  Indicates that `DeclarativeSecurity` should be enforced on the client.
  `DataSource`
  `setEnumConstantProperty(String enumConstantProperty)`
  The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean".
  `DataSource`
  `setEnumOrdinalProperty(String enumOrdinalProperty)`
  The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean".
  `DataSource`
  `setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy)`
  Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript.
  `void`
  `setFields(DataSourceField... fields)`
  The list of fields that compose records from this DataSource.
  `DataSource`
  `setGlobalNamespaces(Map globalNamespaces)`
  Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.
  `void`
  `setHandleErrorCallback(HandleErrorCallback callback)`
  If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other than `STATUS_SUCCESS`.
  `DataSource`
  `setIconField(String iconField)`
  Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.
  `DataSource`
  `setID(String id)`
  `DataSource`
  `setIgnoreTextMatchStyleCaseSensitive(Boolean ignoreTextMatchStyleCaseSensitive)`
  For fields on this dataSource that specify `ignoreTextMatchStyle` true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values.
  `DataSource`
  `setImplicitCriteria(Criteria implicitCriteria)`
  Criteria that are implicitly applied to all fetches made through this DataSource.
  `DataSource`
  `setInfoField(String infoField)`
  Name of the field that has the second most pertinent piece of textual information in the record, for use when a `DataBoundComponent` needs to show a short summary of a record.
  `void`
  `setInheritsFrom(DataSource inheritsFrom)`
  ID of another DataSource this DataSource inherits its DataSource fields from.
  Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields.
  `DataSource`
  `setInheritsFrom(String inheritsFrom)`
  ID of another DataSource this DataSource inherits its `fields` from.
  `DataSource`
  `setIsSampleDS(Boolean isSampleDS)`
  Used by Reify to identify DataSources that are provided as samples.
  `DataSource`
  `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.
  `DataSource`
  `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.
  `static void`
  `setLoaderURL(String url)`
  Sets the URL where the DataSourceLoader servlet has been installed; this is used by the `load()` method.
  `DataSource`
  `setMockDataCriteria(Criteria mockDataCriteria)`
  When `mockMode` is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.
  `DataSource`
  `setMockDataRows(Integer mockDataRows)`
  When `mockMode` is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data.
  `DataSource`
  `setMockMode(Boolean mockMode)`
  If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to a `clientOnly` DataSource, never writing changes back to the server.
  `DataSource`
  `setOperationBindings(OperationBinding... operationBindings)`
  Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
  `DataSource`
  `setPatternEscapeChar(String patternEscapeChar)`
  When using the `pattern operators` `search operator`, character that escapes the `patternSingleWildcard` or `patternMultiWildcard` if placed before it, so that it is treated as a literal character.
  `DataSource`
  `setPatternMultiWildcard(String patternMultiWildcard)`
  When using the `pattern operators` `search operator`, character that matches a series of one or more characters.
  `DataSource`
  `setPatternMultiWildcard(String... patternMultiWildcard)`
  When using the `pattern operators` `search operator`, character that matches a series of one or more characters.
  `DataSource`
  `setPatternSingleWildcard(String patternSingleWildcard)`
  When using the `pattern operators` `search operator`, character that matches any single character.
  `DataSource`
  `setPatternSingleWildcard(String... patternSingleWildcard)`
  When using the `pattern operators` `search operator`, character that matches any single character.
  `DataSource`
  `setPluralTitle(String pluralTitle)`
  User-visible plural name for this DataSource.
  `DataSource`
  `setPreventHTTPCaching(Boolean preventHTTPCaching)`
  If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.
  `DataSource`
  `setProgressiveLoading(Boolean progressiveLoading)`
  If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the `ResultSet documentation`.
  `DataSource`
  `setQualifyColumnNames(Boolean qualifyColumnNames)`
  For dataSources of `serverType` "sql", determines whether we qualify column names with table names in any SQL we generate.
  `DataSource`
  `setRecordName(String recordName)`
  Provides a default value for `OperationBinding.recordName`.
  `DataSource`
  `setRecordXPath(String recordXPath)`
  See `OperationBinding.recordXPath`.
  `DataSource`
  `setRequestProperties(DSRequest requestProperties)`
  Additional properties to pass through to the `DSRequest`s made by this DataSource.
  `DataSource`
  `setRequiredMessage(String requiredMessage)`
  The required message when a field that has been marked as `required` is not filled in by the user.
  `DataSource`
  `setResultBatchSize(int resultBatchSize)`
  Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.
  `DataSource`
  `setResultSetClass(String resultSetClass)`
  Class for ResultSets used by this datasource.
  `DataSource`
  `setResultTreeClass(String resultTreeClass)`
  Class for ResultTrees used by this datasource.
  `DataSource`
  `setSampleData(Record... sampleData)`
  An optional array of sample data records.
  `DataSource`
  `setSendExtraFields(Boolean sendExtraFields)`
  Analogous to `dropExtraFields`, for data sent to the server.
  `DataSource`
  `setSendParentNode(Boolean sendParentNode)`
  Set this attribute if you need to send the dsRequest.parentNode to the server-side.
  `DataSource`
  `setServiceNamespace(String serviceNamespace)`
  For an XML DataSource, URN of the WebService to use to invoke operations.
  `DataSource`
  `setShowLocalFieldsOnly(Boolean showLocalFieldsOnly)`
  For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that only the fields listed in this DataSource should be shown.
  `DataSource`
  `setShowPrompt(Boolean showPrompt)`
  Whether RPCRequests sent by this DataSource should enable `RPCRequest.showPrompt` in order to block user interactions until the request completes.
  `DataSource`
  `setSkipJSONValidation(SkipJSONValidation skipJSONValidation)`
  Sets what level of JSON validation will apply for this DataSource.
  `DataSource`
  `setStrictSQLFiltering(Boolean strictSQLFiltering)`
  If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.
  `DataSource`
  `setTagName(String tagName)`
  Tag name to use when serializing to XML.
  `void`
  `setTestData(Record... cacheData)`
  For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
  `DataSource`
  `setTitle(String title)`
  User-visible name for this DataSource.
  `DataSource`
  `setTitleField(String titleField)`
  Best field to use for a user-visible title for an individual record from this dataSource.
  `DataSource`
  `setTranslatePatternOperators(boolean translatePatternOperators)`
  `Search operators` like "matchesPattern" use patterns like "foo*txt" to match text values.
  `DataSource`
  `setTrimMilliseconds(Boolean trimMilliseconds)`
  For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa.
  `void`
  `setTypeOperators(FieldType typeName, OperatorId[] operators)`
  Set the list of `OperatorId`s valid for a given FieldType.
  `static void`
  `setTypeOperators(String typeName, OperatorId[] operators)`
  Set the list of valid `OperatorId`s for a given FieldType.
  `DataSource`
  `setUseFlatFields(Boolean useFlatFields)`
  Like `DataBoundComponent.useFlatFields`, but applies to all DataBound components that bind to this DataSource.
  `DataSource`
  `setUseHttpProxy(Boolean useHttpProxy)`
  Like `OperationBinding.useHttpProxy`, but serves as a default for this DataSource that may be overridden by individual operationBindings.
  `DataSource`
  `setUseLocalValidators(Boolean useLocalValidators)`
  Whether to attempt validation on the client at all for this DataSource.
  `DataSource`
  `setUseOfflineStorage(Boolean useOfflineStorage)`
  Whether we store server responses for this DataSource into `browser-based offline storage`, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server).
  `DataSource`
  `setUseParentFieldOrder(Boolean useParentFieldOrder)`
  For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.
  `DataSource`
  `setUseStrictJSON(Boolean useStrictJSON)`
  Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.
  `DataSource`
  `setUseTestDataFetch(Boolean useTestDataFetch)`
  When set, causes a `client-only` or `cacheAllData` DataSource to create a second DataSource to perform it's one-time fetch.
  `DataSource`
  `setValidateRelatedRecords(Boolean validateRelatedRecords)`
  If true, indicates that the Smart GWT Server should automatically apply a `ValidatorType` of "hasRelatedRecord" to every field on this dataSource that has a `foreignKey` defined.
  `DataSource`
  `setXmlNamespaces(XmlNamespaces xmlNamespaces)`
  Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions.
  `Criteria`
  `splitCriteria(Criteria criteria, String[] fields)`
  Split a criteria apart based on `fields`.
  `Criteria`
  `splitCriteria(Criteria criteria, String[] fields, Boolean preserveAdvanced)`
  Split a criteria apart based on `fields`.
  `Boolean`
  `supportsAdvancedCriteria()`
  Do fetch and filter operations on this dataSource support being passed `AdvancedCriteria`?
  `Boolean`
  `supportsDynamicTreeJoins()`
  This method returns true for dataSources that support both self-joins and `additionalOutputs`.
  `void`
  `supportsTextMatchStyle(TextMatchStyle textMatchStyle)`
  Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.
  `protected Object`
  `transformRequest(DSRequest dsRequest)`
  For a dataSource using `client-side data integration`, return the data that should be sent to the `dataURL`.
  `protected void`
  `transformResponse(DSResponse dsResponse, DSRequest dsRequest, Object data)`
  Modify the DSResponse object derived from the response returned from the `dataURL`.
  `void`
  `updateCaches(DSResponse dsResponse)`
  Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed.
  `void`
  `updateCaches(DSResponse dsResponse, DSRequest dsRequest)`
  Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed.
  `void`
  `updateData(Record updatedRecord)`
  Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
  `void`
  `updateData(Record updatedRecord, DSCallback callback)`
  `void`
  `updateData(Record updatedRecord, DSCallback callback, DSRequest requestProperties)`
  Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
  `protected boolean`
  `useOfflineResponse(DSRequest dsRequest, DSResponse dsResponse)`
  Override point to allow application code to suppress use of a particular offline response.
  `void`
  `validateData(Record values)`
  Contacts the server to run server-side validation on a DSRequest and either returns `DSResponse.errors` validation errors or a `DSResponse.status` code of 0.
  `void`
  `validateData(Record values, DSCallback callback)`
  `void`
  `validateData(Record values, DSCallback callback, DSRequest requestProperties)`
  Contacts the server to run server-side validation on a DSRequest and either returns `DSResponse.errors` validation errors or a `DSResponse.status` code of 0.
  `static Map[]`
  `verifyDataSourcePair(DataSource live, DataSource mock)`
  A utility that checks for discrepancies between any two DataSources, typically used to warn about issues commonly found during the Reify design / development cycle, and logs its findings to the console.
  `void`
  `viewFile(Record data)`
  Display a file stored in a field of type:"binary" in a new browser window.
  `void`
  `viewFile(Record data, String fieldName)`
  `void`
  `viewFile(Record data, String fieldName, DSRequest requestProperties)`
  Display a file stored in a field of type:"binary" in a new browser window.
  `String`
  `xmlSerialize(JavaScriptObject data)`
  Serialize a JavaScript object as XML.&#010
  `String`
  `xmlSerialize(JavaScriptObject data, SerializationContext flags)`
  Serialize a JavaScript object as XML.&#010
  `String`
  `xmlSerialize(Record[] data, SerializationContext flags)`
  Serialize a JavaScript object as XML.&#010
  `String`
  `xmlSerialize(Record data, SerializationContext flags)`
  Serialize a JavaScript object as XML.&#010
  `String`
  `xmlSerialize(Map data, SerializationContext flags)`
  Serialize a JavaScript object as XML.&#010

  ### 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, setAutoID, 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

  - ### DataSource

    public DataSource()

  - ### DataSource

    public DataSource(JavaScriptObject jsObj)

  - ### DataSource

    public DataSource(String dataURL)

- ## Method Details

  - ### getOrCreateRef

    public static DataSource getOrCreateRef(JavaScriptObject jsObj)

  - ### create

    public JavaScriptObject create()
    Specified by:
      `create` in class `BaseClass`

  - ### setAddedAuditFields

    public DataSource setAddedAuditFields(DataSourceField... addedAuditFields) throws IllegalStateException
    The list of extra manually managed fields that will be added to the `fields` of the `Audit DataSource`.

    This feature enables the storage of additional information in the `Audit DataSource` alongside the standard audit data. In order to do that the audited DataSource needs to declare `auditDSConstructor` referring custom `serverConstructor`, so that all requests to add data to the Audit DataSource could be intercepted allowing to make changes to the new records (obtained using `DSRequest.getValues()` server-side API). In this particular use case values for the `addedAuditFields` need to be provided.

    Example of an audited DataSource (schematically):

          <DataSource audit="true" auditDSConstructor="package.AuditDS">
          <fields>....</fields>
          <addedAuditFields>
               <addedAuditField name="altitude" type="float" />
               <addedAuditField name="longitude" type="float" />
               <addedAuditField name="logCorrelationId" type="text" />
          </addedAuditFields>
          </DataSource>

    An example implementation of AuditDS could be as follows:

          public class AuditDS extends SQLDataSource {
              public DSResponse executeAdd(DSRequest req) throws Exception {
                  // populate additional fields
                  Map values = req.getValues();
                  values.put("altitude", 54.685);
                  values.put("longitude", 25.286);
                  values.put("logCorrelationId", "foobar");
                  // execute "add" request
                  return super.executeAdd(req);
              }
          }

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

  - ### getAddedAuditFields

    public DataSourceField[] getAddedAuditFields()
    The list of extra manually managed fields that will be added to the `fields` of the `Audit DataSource`.

    This feature enables the storage of additional information in the `Audit DataSource` alongside the standard audit data. In order to do that the audited DataSource needs to declare `auditDSConstructor` referring custom `serverConstructor`, so that all requests to add data to the Audit DataSource could be intercepted allowing to make changes to the new records (obtained using `DSRequest.getValues()` server-side API). In this particular use case values for the `addedAuditFields` need to be provided.

    Example of an audited DataSource (schematically):

          <DataSource audit="true" auditDSConstructor="package.AuditDS">
          <fields>....</fields>
          <addedAuditFields>
               <addedAuditField name="altitude" type="float" />
               <addedAuditField name="longitude" type="float" />
               <addedAuditField name="logCorrelationId" type="text" />
          </addedAuditFields>
          </DataSource>

    An example implementation of AuditDS could be as follows:

          public class AuditDS extends SQLDataSource {
              public DSResponse executeAdd(DSRequest req) throws Exception {
                  // populate additional fields
                  Map values = req.getValues();
                  values.put("altitude", 54.685);
                  values.put("longitude", 25.286);
                  values.put("logCorrelationId", "foobar");
                  // execute "add" request
                  return super.executeAdd(req);
              }
          }

    Returns:
      Current addedAuditFields value. Default value is null
    See Also:
      - `DataSourceField`

  - ### setAllowAdvancedCriteria

    public DataSource setAllowAdvancedCriteria(Boolean allowAdvancedCriteria)
    By default, all DataSources are assumed to be capable of handling `AdvancedCriteria` on fetch or filter type operations. This property may be set to `false` to indicate that this dataSource does not support advancedCriteria. See `supportsAdvancedCriteria()` for further information on this.

    NOTE: If you specify this property in a DataSource descriptor (`.ds.xml` file), it is enforced on the server. This means that if you run a request containing AdvancedCriteria against a DataSource that advertises itself as `allowAdvancedCriteria:false`, it will be rejected.

    Note : This is an advanced setting

    Parameters:
      `allowAdvancedCriteria` - New allowAdvancedCriteria value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `OperationBinding.setAllowAdvancedCriteria(java.lang.Boolean)`

  - ### getAllowAdvancedCriteria

    public Boolean getAllowAdvancedCriteria()
    By default, all DataSources are assumed to be capable of handling `AdvancedCriteria` on fetch or filter type operations. This property may be set to `false` to indicate that this dataSource does not support advancedCriteria. See `supportsAdvancedCriteria()` for further information on this.

    NOTE: If you specify this property in a DataSource descriptor (`.ds.xml` file), it is enforced on the server. This means that if you run a request containing AdvancedCriteria against a DataSource that advertises itself as `allowAdvancedCriteria:false`, it will be rejected.

    Returns:
      Current allowAdvancedCriteria value. Default value is null
    See Also:
      - `OperationBinding.getAllowAdvancedCriteria()`

  - ### setAllowAggregation

    public DataSource setAllowAggregation(Boolean allowAggregation)
    This property indicates whether this DataSource supports aggregation/summarization and grouping of field values using the `summaryFunction` mechanism. All the `built-in DataSource types` support aggregation by default: SQL, Hibernate and JPA DataSources support aggregation inherently, using the underlying persistence engine's query language. Other server-side implementations support aggregation and grouping as a post-fetch, in-memory operation; and because this in-memory aggregation happens after the DataSource has fetched data, and is transparent to the DataSource, it will also automatically apply to your own custom DataSource implementations without any effort, unless you switch it off (see `suppressManualAggregation`).

    `clientOnly` DataSources also support aggregation and grouping, using a similar approach to the server-side post-fetch aggregation described above (but running on the client, obviously).

    This property is intended as a means of preventing attempts to run aggregations on a given DataSource. For example, if you know that running aggregations on a particular DataSource can cause performance problems, you can set this flag false to disallow all aggregations on that DataSource. The only meaningful place to specify this property is in a DataSource descriptor (`.ds.xml` file), which will cause it to be enforced on the server. This means that if you run a fetch involving summaryFunctions at the `DSRequest`, `OperationBinding` or `field` level, against a DataSource that advertises itself as `allowAggregation:false`, it will be rejected.

    Note : This is an advanced setting

    Parameters:
      `allowAggregation` - New allowAggregation value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `DataSource.suppressManualAggregation`

  - ### getAllowAggregation

    public Boolean getAllowAggregation()
    This property indicates whether this DataSource supports aggregation/summarization and grouping of field values using the `summaryFunction` mechanism. All the `built-in DataSource types` support aggregation by default: SQL, Hibernate and JPA DataSources support aggregation inherently, using the underlying persistence engine's query language. Other server-side implementations support aggregation and grouping as a post-fetch, in-memory operation; and because this in-memory aggregation happens after the DataSource has fetched data, and is transparent to the DataSource, it will also automatically apply to your own custom DataSource implementations without any effort, unless you switch it off (see `suppressManualAggregation`).

    `clientOnly` DataSources also support aggregation and grouping, using a similar approach to the server-side post-fetch aggregation described above (but running on the client, obviously).

    This property is intended as a means of preventing attempts to run aggregations on a given DataSource. For example, if you know that running aggregations on a particular DataSource can cause performance problems, you can set this flag false to disallow all aggregations on that DataSource. The only meaningful place to specify this property is in a DataSource descriptor (`.ds.xml` file), which will cause it to be enforced on the server. This means that if you run a fetch involving summaryFunctions at the `DSRequest`, `OperationBinding` or `field` level, against a DataSource that advertises itself as `allowAggregation:false`, it will be rejected.

    Returns:
      Current allowAggregation value. Default value is null
    See Also:
      - `DataSource.suppressManualAggregation`

  - ### setAllowCriteriaSubqueries

    public DataSource setAllowCriteriaSubqueries(Boolean allowCriteriaSubqueries)
    Controls whether `AdvancedCriteria subqueries` are permitted for this `DataSource`. Set this value `true` to always permit subqueries in criteria on this dataSource, and set it false to always disallow them.

    The default value of null means that we use the global setting, controlled by setting the `allowCriteriaSubqueries` flag in your `server.properties` file (this global flag is true by default))

    On the client, this property is also applied to `clientOnly`, `MockDataSource`, and cached DataSources before processing `fieldQuery` or `valueQuery` criteria. When set to `false`, subquery criteria are ignored during client-side filtering.

    Parameters:
      `allowCriteriaSubqueries` - New allowCriteriaSubqueries value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `Advanced Filtering`

  - ### getAllowCriteriaSubqueries

    public Boolean getAllowCriteriaSubqueries()
    Controls whether `AdvancedCriteria subqueries` are permitted for this `DataSource`. Set this value `true` to always permit subqueries in criteria on this dataSource, and set it false to always disallow them.

    The default value of null means that we use the global setting, controlled by setting the `allowCriteriaSubqueries` flag in your `server.properties` file (this global flag is true by default))

    On the client, this property is also applied to `clientOnly`, `MockDataSource`, and cached DataSources before processing `fieldQuery` or `valueQuery` criteria. When set to `false`, subquery criteria are ignored during client-side filtering.

    Returns:
      Current allowCriteriaSubqueries value. Default value is null
    See Also:
      - `Advanced Filtering`

  - ### setAllowDynamicTreeJoins

    public DataSource setAllowDynamicTreeJoins(Boolean allowDynamicTreeJoins)
    By default, custom dataSource implementations are assumed to be unable to support `dynamic tree joins`. If you create a custom dataSource that can support such joins, set this flag to true

    Note : This is an advanced setting

    Parameters:
      `allowDynamicTreeJoins` - New allowDynamicTreeJoins value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getAllowDynamicTreeJoins

    public Boolean getAllowDynamicTreeJoins()
    By default, custom dataSource implementations are assumed to be unable to support `dynamic tree joins`. If you create a custom dataSource that can support such joins, set this flag to true
    Returns:
      Current allowDynamicTreeJoins value. Default value is null

  - ### setAllowRelatedFieldsInCriteria

    public DataSource setAllowRelatedFieldsInCriteria(Boolean allowRelatedFieldsInCriteria)
    This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries. See the `subquery filtering overview` for details. Note, only `AdvancedCriteria` can contain related fields.

    All server-side DataSource implementations provide a level of support for related fields in criteria, but only `SQL DataSources` can handle cases that require conditions to be considered simultaneously with a join to the outer dataSource.

    Note : This is an advanced setting

    Parameters:
      `allowRelatedFieldsInCriteria` - New allowRelatedFieldsInCriteria value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `setAllowRelatedFieldsInCriteria(java.lang.Boolean)`

  - ### getAllowRelatedFieldsInCriteria

    public Boolean getAllowRelatedFieldsInCriteria()
    This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries. See the `subquery filtering overview` for details. Note, only `AdvancedCriteria` can contain related fields.

    All server-side DataSource implementations provide a level of support for related fields in criteria, but only `SQL DataSources` can handle cases that require conditions to be considered simultaneously with a join to the outer dataSource.

    Returns:
      Current allowRelatedFieldsInCriteria value. Default value is null
    See Also:
      - `getAllowRelatedFieldsInCriteria()`

  - ### setArrayCriteriaForceExact

    public DataSource setArrayCriteriaForceExact(Boolean arrayCriteriaForceExact) throws IllegalStateException
    With ordinary `simple criteria`, it is possible to provide an array of values for a given field, which means "any of these values". For example:

           var criteria = {
             field1 : "value1",
             field2 : ["value2", "value3"]
          }

    At first glance, this criteria appears to mean "select records where 'field1' is 'value1' and 'field2' is one of 'value2' or 'value3'". However, if the prevailing `textMatchStyle` is "substring" - as it would be if, for example, you had issued a `filterData()` call - then this criteria means "select records where 'field1' contains 'value1' somewhere, and 'field2' contains either 'value2' or 'value3'"

    Depending on your requirement, this may or may not be what you want, and you can control it by setting the `textMatchStyle` on your `DSRequest`, or by setting a default `textMatchStyle` on the DataSource (`defaultTextMatchStyle`), or by specifying that the `textMatchStyle` should be ignored for certain fields (`DataSourceField.ignoreTextMatchStyle`)

    However, a common use case is that you want "substring" style filtering on one or more single-valued fields, but exact matching on a list-valued field. For example, say you want a list of customers based in certain cities, with a name matching the substring "software":

           var criteria = {
             name : "software",
             city : ["York", "Newport", "Orleans"]
          }

    Here, using substring matching on the "city" field is likely to give incorrect results, as it will match a number of US cities in addition to the three European cities intended (New York, Yorktown, New Orleans, Newport News, and probably others). And even if this is not an issue for your particular use case, and correct results can be obtained with a substring search, it is very likely to be more costly performance-wise than the exact value match that you really need (potentially much more costly).

    You could achieve exact matching in the above case by marking the "city" field as `ignoreTextMatchStyle:true`, but that would mean you couldn't perform substring searches on that field in other use cases where that might be desirable.

    In cases like this, Smart GWT by default treats list-valued simple criteria as if `ignoreTextMatchStyle` is in force for that field. If you want to switch this behavior off, and have list-valued simple criteria handled with the prevailing `textMatchStyle`, set `arrayCriteriaForceExact` to false. It is also possible to set this flag per-operationBinding and per-DSRequest - see `OperationBinding.arrayCriteriaForceExact` and `DSRequest.arrayCriteriaForceExact`

    If you want to switch this behavior off across the entire system, set the flag in your `server.properties` file:

              arrayCriteriaForceExact: false

    This will only have an effect for server-side DataSources; if you want to change this flag globally for `clientOnly` dataSources, change the default in the client-side `DataSource` class, like so:

              isc.DataSource.addProperties({arrayCriteriaForceExact: false});

    If you do change the global defaults, it is still possible to override per-dataSource or per-operationBinding, as described above.

    Note, all of this only applies to simple criteria. If your dataSource `supports AdvancedCriteria`, that gives you much finer and more complete control over the exact meaning of individual criterions.

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

  - ### getArrayCriteriaForceExact

    public Boolean getArrayCriteriaForceExact()
    With ordinary `simple criteria`, it is possible to provide an array of values for a given field, which means "any of these values". For example:

           var criteria = {
             field1 : "value1",
             field2 : ["value2", "value3"]
          }

    At first glance, this criteria appears to mean "select records where 'field1' is 'value1' and 'field2' is one of 'value2' or 'value3'". However, if the prevailing `textMatchStyle` is "substring" - as it would be if, for example, you had issued a `filterData()` call - then this criteria means "select records where 'field1' contains 'value1' somewhere, and 'field2' contains either 'value2' or 'value3'"

    Depending on your requirement, this may or may not be what you want, and you can control it by setting the `textMatchStyle` on your `DSRequest`, or by setting a default `textMatchStyle` on the DataSource (`defaultTextMatchStyle`), or by specifying that the `textMatchStyle` should be ignored for certain fields (`DataSourceField.ignoreTextMatchStyle`)

    However, a common use case is that you want "substring" style filtering on one or more single-valued fields, but exact matching on a list-valued field. For example, say you want a list of customers based in certain cities, with a name matching the substring "software":

           var criteria = {
             name : "software",
             city : ["York", "Newport", "Orleans"]
          }

    Here, using substring matching on the "city" field is likely to give incorrect results, as it will match a number of US cities in addition to the three European cities intended (New York, Yorktown, New Orleans, Newport News, and probably others). And even if this is not an issue for your particular use case, and correct results can be obtained with a substring search, it is very likely to be more costly performance-wise than the exact value match that you really need (potentially much more costly).

    You could achieve exact matching in the above case by marking the "city" field as `ignoreTextMatchStyle:true`, but that would mean you couldn't perform substring searches on that field in other use cases where that might be desirable.

    In cases like this, Smart GWT by default treats list-valued simple criteria as if `ignoreTextMatchStyle` is in force for that field. If you want to switch this behavior off, and have list-valued simple criteria handled with the prevailing `textMatchStyle`, set `arrayCriteriaForceExact` to false. It is also possible to set this flag per-operationBinding and per-DSRequest - see `OperationBinding.arrayCriteriaForceExact` and `DSRequest.arrayCriteriaForceExact`

    If you want to switch this behavior off across the entire system, set the flag in your `server.properties` file:

              arrayCriteriaForceExact: false

    This will only have an effect for server-side DataSources; if you want to change this flag globally for `clientOnly` dataSources, change the default in the client-side `DataSource` class, like so:

              isc.DataSource.addProperties({arrayCriteriaForceExact: false});

    If you do change the global defaults, it is still possible to override per-dataSource or per-operationBinding, as described above.

    Note, all of this only applies to simple criteria. If your dataSource `supports AdvancedCriteria`, that gives you much finer and more complete control over the exact meaning of individual criterions.

    Returns:
      Current arrayCriteriaForceExact value. Default value is null
    See Also:
      - `Server DataSource Integration`

  - ### setAutoCacheAllData

    public DataSource setAutoCacheAllData(Boolean autoCacheAllData) throws IllegalStateException
    When a DataSource is not `cacheAllData`:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch to `cacheAllData:true` and prevent further server-trips for fetch requests.

    `cacheAllData` is automatically enabled in either of these conditions:

    - The request has no criteria and no startRow/endRow request properties. The latter can be accomplished by disabling paging with a `dataFetchMode` setting of "basic" or "local" or by an explicit fetchData request with those request properties excluded.
    - The request has no criteria but has startRow/endRow specified and the response received has all data available (`startRow:0` and `endRow:totalRows`).
    Parameters:
      `autoCacheAllData` - New autoCacheAllData value. Default value is false
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getAutoCacheAllData

    public Boolean getAutoCacheAllData()
    When a DataSource is not `cacheAllData`:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch to `cacheAllData:true` and prevent further server-trips for fetch requests.

    `cacheAllData` is automatically enabled in either of these conditions:

    - The request has no criteria and no startRow/endRow request properties. The latter can be accomplished by disabling paging with a `dataFetchMode` setting of "basic" or "local" or by an explicit fetchData request with those request properties excluded.
    - The request has no criteria but has startRow/endRow specified and the response received has all data available (`startRow:0` and `endRow:totalRows`).
    Returns:
      Current autoCacheAllData value. Default value is false

  - ### setAutoConvertRelativeDates

    public DataSource setAutoConvertRelativeDates(Boolean autoConvertRelativeDates) throws IllegalStateException
    Whether to convert relative date values to concrete date values before sending to the server. Default value is true, which means that the server does not need to understand how to filter using relative dates - it receives all date values as absolute dates.

    If the server would receive relative date values from the client, by default they would be unchanged in DMI and automatically converted during the request execution. This may be changed via `server.properties` setting `datasources.autoConvertRelativeDates` which can be set to the following values:

    `postDMI` - the default value described above
    `preDMI` - relative date values will be converted to absolute date values right away, so they will be already converted in DMI
    `disabled` - relative date values will not be automatically converted, so it must be done completely manually or by calling the `DSRequest.convertRelativeDates()` server-side API.
    Normally there is no need to convert relative dates on the server, this is done by default on the client before the request is sent to the server. The primary purpose for converting relative dates on the server is when there is a need to store and use relative dates at a later point such as in an automated job without any involvement from the client. See more details in the javadoc for `DataSource.convertRelativeDates(Criterion)` server-side API.
    Parameters:
      `autoConvertRelativeDates` - New autoConvertRelativeDates value. Default value is true
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getAutoConvertRelativeDates

    public Boolean getAutoConvertRelativeDates()
    Whether to convert relative date values to concrete date values before sending to the server. Default value is true, which means that the server does not need to understand how to filter using relative dates - it receives all date values as absolute dates.

    If the server would receive relative date values from the client, by default they would be unchanged in DMI and automatically converted during the request execution. This may be changed via `server.properties` setting `datasources.autoConvertRelativeDates` which can be set to the following values:

    `postDMI` - the default value described above
    `preDMI` - relative date values will be converted to absolute date values right away, so they will be already converted in DMI
    `disabled` - relative date values will not be automatically converted, so it must be done completely manually or by calling the `DSRequest.convertRelativeDates()` server-side API.
    Normally there is no need to convert relative dates on the server, this is done by default on the client before the request is sent to the server. The primary purpose for converting relative dates on the server is when there is a need to store and use relative dates at a later point such as in an automated job without any involvement from the client. See more details in the javadoc for `DataSource.convertRelativeDates(Criterion)` server-side API.
    Returns:
      Current autoConvertRelativeDates value. Default value is true

  - ### setAutoDeriveTitles

    public DataSource setAutoDeriveTitles(boolean autoDeriveTitles) throws IllegalStateException
    If set, titles are automatically derived from `field.name` for any field that does not have a `field.title` and is not marked `hidden`:true, by calling the method `getAutoTitle()`.
    Parameters:
      `autoDeriveTitles` - New autoDeriveTitles value. Default value is true
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getAutoDeriveTitles

    public boolean getAutoDeriveTitles()
    If set, titles are automatically derived from `field.name` for any field that does not have a `field.title` and is not marked `hidden`:true, by calling the method `getAutoTitle()`.
    Returns:
      Current autoDeriveTitles value. Default value is true

  - ### setAutoDiscoverTree

    public DataSource setAutoDiscoverTree(boolean autoDiscoverTree) throws IllegalStateException
    Causes `Tree.discoverTree()` to be called on dsResponse.data in order to automatically discover tree structures in the response data.

    If autoDiscoverTree is set, discoverTree() is called after the default dsResponse.data has been derived (`recordXPath` and `valueXPath` have been applied) and after `transformResponse()` has been called.

    If a DataSourceField is declared with `childrenProperty:true`, discoverTree() will be invoked with `settings.newChildrenProperty` set to the name of the field marked as the childrenField. Similarly, if the DataSource has a `titleField` it will be used as the `settings.nameProperty`.

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

  - ### getAutoDiscoverTree

    public boolean getAutoDiscoverTree()
    Causes `Tree.discoverTree()` to be called on dsResponse.data in order to automatically discover tree structures in the response data.

    If autoDiscoverTree is set, discoverTree() is called after the default dsResponse.data has been derived (`recordXPath` and `valueXPath` have been applied) and after `transformResponse()` has been called.

    If a DataSourceField is declared with `childrenProperty:true`, discoverTree() will be invoked with `settings.newChildrenProperty` set to the name of the field marked as the childrenField. Similarly, if the DataSource has a `titleField` it will be used as the `settings.nameProperty`.

    Returns:
      Current autoDiscoverTree value. Default value is false

  - ### setCacheAcrossOperationIds

    public DataSource setCacheAcrossOperationIds(Boolean cacheAcrossOperationIds) throws IllegalStateException
    When `cacheAllData` mode is enabled and a `cacheAllOperationId` has been set, this flag affects whether cached results are used for all "fetch" requests regardless of their `DSRequest.operationId`, or are used only for "fetch" requests that use the `cacheAllOperationId`, allowing other requests to go to server normally.

    Default of `true` means that the `cacheAllOperationId` will be used to fetch all rows, but the resulting cache will be used for all "fetch" operations regardless of the `operationId` specified on the request.

    Switching to "false" effectively creates caching just for one specific `operationId` - the `cacheAllOperationId` - while allowing all other requests to go to the server normally.

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

  - ### getCacheAcrossOperationIds

    public Boolean getCacheAcrossOperationIds()
    When `cacheAllData` mode is enabled and a `cacheAllOperationId` has been set, this flag affects whether cached results are used for all "fetch" requests regardless of their `DSRequest.operationId`, or are used only for "fetch" requests that use the `cacheAllOperationId`, allowing other requests to go to server normally.

    Default of `true` means that the `cacheAllOperationId` will be used to fetch all rows, but the resulting cache will be used for all "fetch" operations regardless of the `operationId` specified on the request.

    Switching to "false" effectively creates caching just for one specific `operationId` - the `cacheAllOperationId` - while allowing all other requests to go to the server normally.

    Returns:
      Current cacheAcrossOperationIds value. Default value is true

  - ### setCacheAllData

    public DataSource setCacheAllData(Boolean cacheAllData)
    Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request. However, unlike a `clientOnly` DataSource, this DataSource will still save changes normally, sending remote requests.

    You can manually set this attribute after initialization by calling `setCacheAllData()`; setting `autoCacheAllData`:true causes a DataSource to automatically switch to `cacheAllData:true` when a fetch results in the entire dataset being brought client-side.

    To cause automatic cache updates, you can set `cacheMaxAge` to a number of seconds and once data has been client-side for that length of time, the next fetch causes the cache to be dropped and a new cache retrieved.

    Note that multiple `operationBindings` of type "fetch" which return distinct results will not work with `cacheAllData`: only one cache is created and is used for all fetch operations, regardless of whether `DSRequest.operationId` has been set. However, "fetch" operationBindings used as a `OperationBinding.cacheSyncOperation` will work normally, so long as they return all data fields that are returned by the default "fetch" operation, so that the cache can be updated.

    To specify which operationId to use for fetching all data, use `cacheAllOperationId`.

    To use the cache only for requests that have the `cacheAllOperationId`, allowing any other operationId (or absence of an operationId) to contact the server as normal, set `cacheAcrossOperationIds`.
    If this method is called after the component has been drawn/initialized: Call this method to switch cacheAllData on or off after initialization. Passing a `shouldCache` value of false clears any existing client-side cache, cancels any outstanding requests for a full cache and issues any other pending requests normally.

    Parameters:
      `cacheAllData` - New value for `cacheAllData`. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getCacheAllData

    public Boolean getCacheAllData()
    Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request. However, unlike a `clientOnly` DataSource, this DataSource will still save changes normally, sending remote requests.

    You can manually set this attribute after initialization by calling `setCacheAllData()`; setting `autoCacheAllData`:true causes a DataSource to automatically switch to `cacheAllData:true` when a fetch results in the entire dataset being brought client-side.

    To cause automatic cache updates, you can set `cacheMaxAge` to a number of seconds and once data has been client-side for that length of time, the next fetch causes the cache to be dropped and a new cache retrieved.

    Note that multiple `operationBindings` of type "fetch" which return distinct results will not work with `cacheAllData`: only one cache is created and is used for all fetch operations, regardless of whether `DSRequest.operationId` has been set. However, "fetch" operationBindings used as a `OperationBinding.cacheSyncOperation` will work normally, so long as they return all data fields that are returned by the default "fetch" operation, so that the cache can be updated.

    To specify which operationId to use for fetching all data, use `cacheAllOperationId`.

    To use the cache only for requests that have the `cacheAllOperationId`, allowing any other operationId (or absence of an operationId) to contact the server as normal, set `cacheAcrossOperationIds`.

    Returns:
      Current cacheAllData value. Default value is null

  - ### setCacheAllOperationId

    public DataSource setCacheAllOperationId(String cacheAllOperationId) throws IllegalStateException
    `DSRequest.operationId` to use for fetching data in case `cacheAllData` is true. By default a standard fetch operation is used (with no `operationId` specified).
    Parameters:
      `cacheAllOperationId` - New cacheAllOperationId value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCacheAllOperationId

    public String getCacheAllOperationId()
    `DSRequest.operationId` to use for fetching data in case `cacheAllData` is true. By default a standard fetch operation is used (with no `operationId` specified).
    Returns:
      Current cacheAllOperationId value. Default value is null

  - ### setCacheMaxAge

    public DataSource setCacheMaxAge(int cacheMaxAge)
    The maximum time, in seconds, to maintain the client-side cache. If a fetch occurs after the cacheMaxAge has expired, the current cache will be dropped and another complete cache fetched.
    Parameters:
      `cacheMaxAge` - New cacheMaxAge value. Default value is 60
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getCacheMaxAge

    public int getCacheMaxAge()
    The maximum time, in seconds, to maintain the client-side cache. If a fetch occurs after the cacheMaxAge has expired, the current cache will be dropped and another complete cache fetched.
    Returns:
      Current cacheMaxAge value. Default value is 60

  - ### setCallbackParam

    public DataSource setCallbackParam(String callbackParam) throws IllegalStateException
    Applies only to dataFormat: "json" and `dataTransport`:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response.
    Parameters:
      `callbackParam` - New callbackParam value. Default value is "callback"
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setDataFormat(com.smartgwt.client.types.DSDataFormat)`
      - `setOperationBindings(com.smartgwt.client.data.OperationBinding...)`
      - `OperationBinding.setCallbackParam(java.lang.String)`
      - `Client-side Data Integration`
      - Edit and Save Example

  - ### getCallbackParam

    public String getCallbackParam()
    Applies only to dataFormat: "json" and `dataTransport`:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response.
    Returns:
      Current callbackParam value. Default value is "callback"
    See Also:
      - `getDataFormat()`
      - `getOperationBindings()`
      - `OperationBinding.getCallbackParam()`
      - `Client-side Data Integration`
      - Edit and Save Example

  - ### setCanAggregate

    public DataSource setCanAggregate(Boolean canAggregate)
    By default, all DataSources are assumed to be capable of handling `ServerSummaries` on fetch or filter type operations. This property may be set to `false` to indicate that this dataSource does not support serverSummaries.

    NOTE: If you specify this property in a DataSource descriptor (`.ds.xml` file), it is enforced on the server. This means that if you run a request containing serverSummaries against a DataSource that advertises itself as `canAggregate:false`, it will be rejected.

    Note : This is an advanced setting

    Parameters:
      `canAggregate` - New canAggregate value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `Server Summaries`

  - ### getCanAggregate

    public Boolean getCanAggregate()
    By default, all DataSources are assumed to be capable of handling `ServerSummaries` on fetch or filter type operations. This property may be set to `false` to indicate that this dataSource does not support serverSummaries.

    NOTE: If you specify this property in a DataSource descriptor (`.ds.xml` file), it is enforced on the server. This means that if you run a request containing serverSummaries against a DataSource that advertises itself as `canAggregate:false`, it will be rejected.

    Returns:
      Current canAggregate value. Default value is null
    See Also:
      - `Server Summaries`

  - ### setCanMultiSort

    public DataSource setCanMultiSort(boolean canMultiSort) throws IllegalStateException
    When true, indicates that this DataSource supports multi-level sorting.
    Parameters:
      `canMultiSort` - New canMultiSort value. Default value is true
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCanMultiSort

    public boolean getCanMultiSort()
    When true, indicates that this DataSource supports multi-level sorting.
    Returns:
      Current canMultiSort value. Default value is true

  - ### setChildrenField

    public DataSource setChildrenField(String childrenField) throws IllegalStateException
    fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierarchical data structure, rather than a flat list of nodes linked by foreignKey.
    Note this is an alternative to setting `DataSourceField.childrenProperty` directly on the childrenField object.

    By default the children field will be assumed to be `multiple`, for XML databinding. This implies that child data should be delivered in the format:

               <childrenFieldName>
                   <item name="firstChild" ...>
                   <item name="secondChild" ...>
               </childrenFieldName>

    However data may also be delivered as a direct list of `childrenFieldName` elements:

               <childrenFieldName name="firstChild" ...>
               <childrenFieldName name="secondChild" ...>

    If you want to return your data in this format, you will need to explicitly set `multiple` to false in the appropriate dataSource field definition.
    Parameters:
      `childrenField` - New childrenField value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `DataSourceField.setChildrenProperty(java.lang.Boolean)`
      - `Relations`

  - ### getChildrenField

    public String getChildrenField()
    fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierarchical data structure, rather than a flat list of nodes linked by foreignKey.
    Note this is an alternative to setting `DataSourceField.childrenProperty` directly on the childrenField object.

    By default the children field will be assumed to be `multiple`, for XML databinding. This implies that child data should be delivered in the format:

               <childrenFieldName>
                   <item name="firstChild" ...>
                   <item name="secondChild" ...>
               </childrenFieldName>

    However data may also be delivered as a direct list of `childrenFieldName` elements:

               <childrenFieldName name="firstChild" ...>
               <childrenFieldName name="secondChild" ...>

    If you want to return your data in this format, you will need to explicitly set `multiple` to false in the appropriate dataSource field definition.
    Returns:
      Current childrenField value. Default value is null
    See Also:
      - `DataSourceField.getChildrenProperty()`
      - `Relations`

  - ### setClientOnly

    public DataSource setClientOnly(Boolean clientOnly) throws IllegalStateException
    A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as `DSRequests` are executed on it. Any changes are lost when the user reloads the page or navigates away.

    A clientOnly DataSource will return responses asynchronously, just as a DataSource accessing remote data does. This allows a clientOnly DataSource to be used as a temporary placeholder while a real DataSource is being implemented - if a clientOnly DataSource is replaced by a DataSource that accesses a remote data store, UI code for components that used the clientOnly DataSource will not need be changed.

    A clientOnly DataSource can also be used as a shared cache of modifiable data across multiple UI components when immediate saving is not desirable. In this case, several components may interact with a clientOnly DataSource and get the benefit of `ResultSet` behaviors such as automatic cache sync and in-browser data filtering and sorting. When it's finally time to save, `cacheData` can be inspected for changes and data can be saved to the original DataSource via `addData()`, `updateData()` and `removeData()`, possibly in a `transactional queue`. Note that `getClientOnlyDataSource()` lets you easily obtain a `clientOnly` DataSource representing a subset of the data available from a normal DataSource.

    See also `cacheAllData` - a `cacheAllData` behaves like a write-through cache, performing fetch and filter operations locally while still performing remote save operations immediately.

    ClientOnly DataSources can be populated programmatically via `cacheData` - see `this discussion` for other ways to populate a client-only DataSource with data.
    If this method is called after the component has been drawn/initialized: Switch into or out of clientOnly mode, taking the cache from the cacheAllData ResultSet if it exists.

    Parameters:
      `clientOnly` - New clientOnly value. Default value is false
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Client Only DataSources`
      - Local DataSource Example

  - ### getClientOnly

    public Boolean getClientOnly()
    A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as `DSRequests` are executed on it. Any changes are lost when the user reloads the page or navigates away.

    A clientOnly DataSource will return responses asynchronously, just as a DataSource accessing remote data does. This allows a clientOnly DataSource to be used as a temporary placeholder while a real DataSource is being implemented - if a clientOnly DataSource is replaced by a DataSource that accesses a remote data store, UI code for components that used the clientOnly DataSource will not need be changed.

    A clientOnly DataSource can also be used as a shared cache of modifiable data across multiple UI components when immediate saving is not desirable. In this case, several components may interact with a clientOnly DataSource and get the benefit of `ResultSet` behaviors such as automatic cache sync and in-browser data filtering and sorting. When it's finally time to save, `cacheData` can be inspected for changes and data can be saved to the original DataSource via `addData()`, `updateData()` and `removeData()`, possibly in a `transactional queue`. Note that `getClientOnlyDataSource()` lets you easily obtain a `clientOnly` DataSource representing a subset of the data available from a normal DataSource.

    See also `cacheAllData` - a `cacheAllData` behaves like a write-through cache, performing fetch and filter operations locally while still performing remote save operations immediately.

    ClientOnly DataSources can be populated programmatically via `cacheData` - see `this discussion` for other ways to populate a client-only DataSource with data.

    Returns:
      Current clientOnly value. Default value is false
    See Also:
      - `Client Only DataSources`
      - Local DataSource Example

  - ### setCriteriaPolicy

    public DataSource setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
    Decides under what conditions the `ResultSet` cache should be dropped when the `ResultSet.criteria` changes.

    Note : This is an advanced setting

    Parameters:
      `criteriaPolicy` - New criteriaPolicy value. Default value is "dropOnShortening"
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)`

  - ### getCriteriaPolicy

    public CriteriaPolicy getCriteriaPolicy()
    Decides under what conditions the `ResultSet` cache should be dropped when the `ResultSet.criteria` changes.
    Returns:
      Current criteriaPolicy value. Default value is "dropOnShortening"
    See Also:
      - `compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)`

  - ### setDataField

    public DataSource setDataField(String dataField) throws IllegalStateException
    Name of the field that has the most pertinent numeric, date, or enum value, for use when a `DataBoundComponent` needs to show a short summary of a record.

    For example, for a DataSource of employees, good choices might be the "salary" field, "hire date" or "status" (active, vacation, on leave, etc).

    Unlike `titleField`, dataField is not automatically determined in the absence of an explicit setting.

    Parameters:
      `dataField` - New dataField value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### getDataField

    public String getDataField()
    Name of the field that has the most pertinent numeric, date, or enum value, for use when a `DataBoundComponent` needs to show a short summary of a record.

    For example, for a DataSource of employees, good choices might be the "salary" field, "hire date" or "status" (active, vacation, on leave, etc).

    Unlike `titleField`, dataField is not automatically determined in the absence of an explicit setting.

    Returns:
      Current dataField value. Default value is null
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### setDataFormat

    public DataSource setDataFormat(DSDataFormat dataFormat) throws IllegalStateException
    Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when `fetchData()` is called).
    Parameters:
      `dataFormat` - New dataFormat value. Default value is "iscServer"
    Returns:
      `DataSource` 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()
    Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when `fetchData()` is called).
    Returns:
      Current dataFormat value. Default value is "iscServer"
    See Also:
      - `Server DataSource Integration`
      - JSON DataSource Example
      - Simple JSON Example

  - ### setDataTransport

    public DataSource setDataTransport(RPCTransport dataTransport) throws IllegalStateException
    Transport to use for all operations on this DataSource. Defaults to `defaultTransport`. This would typically only be set to enable "scriptInclude" transport for contacting `JSON` web services hosted on servers other than the origin server.

    When using the "scriptInclude" transport, be sure to set `callbackParam` or `OperationBinding.callbackParam` to match the name of the query parameter name expected by your JSON service provider.

    Parameters:
      `dataTransport` - New dataTransport value. Default value is RPCManager.defaultTransport
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `RPCTransport`
      - `setCallbackParam(java.lang.String)`
      - `Client-side Data Integration`

  - ### getDataTransport

    public RPCTransport getDataTransport()
    Transport to use for all operations on this DataSource. Defaults to `defaultTransport`. This would typically only be set to enable "scriptInclude" transport for contacting `JSON` web services hosted on servers other than the origin server.

    When using the "scriptInclude" transport, be sure to set `callbackParam` or `OperationBinding.callbackParam` to match the name of the query parameter name expected by your JSON service provider.

    Returns:
      Current dataTransport value. Default value is RPCManager.defaultTransport
    See Also:
      - `RPCTransport`
      - `getCallbackParam()`
      - `Client-side Data Integration`

  - ### setDataURL

    public DataSource setDataURL(String dataURL) throws IllegalStateException
    Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis via `OperationBinding.dataURL`.

    NOTE: Best practice is to use the same `dataURL` for all DataSources which fulfill DSRequests via the server-side RPCManager API. Otherwise, cross-DataSource `operation queuing` will not be possible.

    ### dataURL and `RestConnector`

    `dataURL` is also used to configure the address of the target REST server for a `RestConnector` DataSource. Typically this is done at the `operationBinding level`, because the URLs of REST services often encode things about the service itself, like whether it is a fetch or an update. However, if your REST service does use the same URL for every service, or most services, you can configure it here at the DataSource level.

    As discussed in the `RestConnector overview`, many elements of `RestConnector` config can be Velocity templates, and `dataURL` is one such element. For example:

            <operationBinding operationType="fetch" operationId="fetchByPK">
                <dataURL>$config['rest.server.base.url']/fetch/$criteria.pk</dataURL>
            </operationBinding>

    NOTE: Because the server-side `RestConnector` implementation uses the `dataURL` property to configure the address of the target REST server, and that property also has meaning on the client, if you are using a `RestConnector` DataSource, you should specify the `dataURL` of the target REST server inside the `serverConfig` block
    Parameters:
      `dataURL` - New dataURL value. Default value is null
    Returns:
      `DataSource` 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. Can also be set on a per-operationType basis via `OperationBinding.dataURL`.

    NOTE: Best practice is to use the same `dataURL` for all DataSources which fulfill DSRequests via the server-side RPCManager API. Otherwise, cross-DataSource `operation queuing` will not be possible.

    ### dataURL and `RestConnector`

    `dataURL` is also used to configure the address of the target REST server for a `RestConnector` DataSource. Typically this is done at the `operationBinding level`, because the URLs of REST services often encode things about the service itself, like whether it is a fetch or an update. However, if your REST service does use the same URL for every service, or most services, you can configure it here at the DataSource level.

    As discussed in the `RestConnector overview`, many elements of `RestConnector` config can be Velocity templates, and `dataURL` is one such element. For example:

            <operationBinding operationType="fetch" operationId="fetchByPK">
                <dataURL>$config['rest.server.base.url']/fetch/$criteria.pk</dataURL>
            </operationBinding>

    NOTE: Because the server-side `RestConnector` implementation uses the `dataURL` property to configure the address of the target REST server, and that property also has meaning on the client, if you are using a `RestConnector` DataSource, you should specify the `dataURL` of the target REST server inside the `serverConfig` block
    Returns:
      Current dataURL value. Default value is null
    See Also:
      - `URL`
      - `Client-side Data Integration`
      - JSON DataSource Example

  - ### setDeepCloneNonFieldValuesOnEdit

    public DataSource setDeepCloneNonFieldValuesOnEdit(Boolean deepCloneNonFieldValuesOnEdit)
    When editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or by `dataPath`). If this flag is not explicitly set, it defaults to the value of the same-named static property, `deepCloneNonFieldValuesOnEdit`. This flag can also be overridden per-component - see `DataBoundComponent.deepCloneNonFieldValuesOnEdit`.

    Note, a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays; a "shallow clone" is a copy created by simply copying the top-level attributes of an object; if you have nested objects that are copied like this, the "copies" are actual references to the original objects.

    Like the other `deepCloneOnEdit` settings, this flag only has an effect if you are editing a values object that contains nested objects or arrays.

    Note : This is an advanced setting

    Parameters:
      `deepCloneNonFieldValuesOnEdit` - New deepCloneNonFieldValuesOnEdit value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `Canvas.setDataPath(java.lang.String)`
      - `FormItem.setDataPath(java.lang.String)`
      - `ValuesManager.setDeepCloneOnEdit(java.lang.Boolean)`

  - ### getDeepCloneNonFieldValuesOnEdit

    public Boolean getDeepCloneNonFieldValuesOnEdit()
    When editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or by `dataPath`). If this flag is not explicitly set, it defaults to the value of the same-named static property, `deepCloneNonFieldValuesOnEdit`. This flag can also be overridden per-component - see `DataBoundComponent.deepCloneNonFieldValuesOnEdit`.

    Note, a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays; a "shallow clone" is a copy created by simply copying the top-level attributes of an object; if you have nested objects that are copied like this, the "copies" are actual references to the original objects.

    Like the other `deepCloneOnEdit` settings, this flag only has an effect if you are editing a values object that contains nested objects or arrays.

    Returns:
      Current deepCloneNonFieldValuesOnEdit value. Default value is null
    See Also:
      - `Canvas.getDataPath()`
      - `FormItem.getDataPath()`
      - `ValuesManager.getDeepCloneOnEdit()`

  - ### setDeepCloneOnEdit

    public DataSource setDeepCloneOnEdit(Boolean deepCloneOnEdit)
    Before we start editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays). If this flag is explicitly set to false, we perform a shallow clone of the underlying values before edit (a "shallow clone" is a copy created by simply copying the top-level attributes of an object). Note, this setting only affects deep-cloning of attributes that are bound to a field; for other, non-field values, see `deepCloneNonFieldValuesOnEdit`.

    If this flag is not explicitly set, it defaults to the value of the same-named static property, `deepCloneOnEdit`. This flag can also be overridden per-component and per-field - see `DataBoundComponent.deepCloneOnEdit` and `DataSourceField.deepCloneOnEdit`.

    Note, this flag only has an effect if you are editing a values object that contains nested objects or arrays, using `dataPath`s. When editing "flat" data - the mainstream case - there is no difference between a deep clone and a shallow clone.

    Note : This is an advanced setting

    Parameters:
      `deepCloneOnEdit` - New deepCloneOnEdit value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `Canvas.setDataPath(java.lang.String)`
      - `FormItem.setDataPath(java.lang.String)`
      - `DataSourceField.setDeepCloneOnEdit(java.lang.Boolean)`
      - `ValuesManager.setDeepCloneOnEdit(java.lang.Boolean)`

  - ### getDeepCloneOnEdit

    public Boolean getDeepCloneOnEdit()
    Before we start editing values in `DataBoundComponent`s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays). If this flag is explicitly set to false, we perform a shallow clone of the underlying values before edit (a "shallow clone" is a copy created by simply copying the top-level attributes of an object). Note, this setting only affects deep-cloning of attributes that are bound to a field; for other, non-field values, see `deepCloneNonFieldValuesOnEdit`.

    If this flag is not explicitly set, it defaults to the value of the same-named static property, `deepCloneOnEdit`. This flag can also be overridden per-component and per-field - see `DataBoundComponent.deepCloneOnEdit` and `DataSourceField.deepCloneOnEdit`.

    Note, this flag only has an effect if you are editing a values object that contains nested objects or arrays, using `dataPath`s. When editing "flat" data - the mainstream case - there is no difference between a deep clone and a shallow clone.

    Returns:
      Current deepCloneOnEdit value. Default value is null
    See Also:
      - `Canvas.getDataPath()`
      - `FormItem.getDataPath()`
      - `DataSourceField.getDeepCloneOnEdit()`
      - `ValuesManager.getDeepCloneOnEdit()`

  - ### setDefaultTextMatchStyle

    public DataSource setDefaultTextMatchStyle(TextMatchStyle defaultTextMatchStyle) throws IllegalStateException
    The default textMatchStyle to use for `DSRequest`s that do not explicitly state a `textMatchStyle`. Note, however, that DSRequests issued by `ListGrid`s and other `components` will generally have a setting for textMatchStyle on the component itself (see `ListGrid.autoFetchTextMatchStyle`, for example).
    Parameters:
      `defaultTextMatchStyle` - New defaultTextMatchStyle value. Default value is "exact"
    Returns:
      `DataSource` 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

  - ### getDefaultTextMatchStyle

    public TextMatchStyle getDefaultTextMatchStyle()
    The default textMatchStyle to use for `DSRequest`s that do not explicitly state a `textMatchStyle`. Note, however, that DSRequests issued by `ListGrid`s and other `components` will generally have a setting for textMatchStyle on the component itself (see `ListGrid.autoFetchTextMatchStyle`, for example).
    Returns:
      Current defaultTextMatchStyle value. Default value is "exact"
    See Also:
      - `Server DataSource Integration`
      - JSON DataSource Example
      - Simple JSON Example

  - ### setDescription

    public DataSource setDescription(String description) throws IllegalStateException
    An optional description of the DataSource's content. It is not automatically exposed on any component, but it is useful for developer documentation, and as such it is included on any `OpenAPI specification` generated by the framework. Markdown is a commonly-used syntax, but you may also embed HTML content. When embedding HTML in the description in a .ds.xml file (see `DataSourceDeclaration`), it is recommended to wrap the HTML in a CDATA tag.

    This description is also provided to AI when AI is asked to work with the data source. Best practices for the description are:

    - Start with a plain language explanation of what the data source and records within it represent, their business concept or core purpose.
    - Describe how the data source relates to other data sources in the application.
    - Mention the approximate size of the data source and whether/when records are updated, added, and removed, as well as the approximate rates of updates, additions, and removals.
    - Identify any known data issues or anomalies.

    In addition to the data source-level description, each field can be described via `DataSourceField.description`.

    Parameters:
      `description` - New description value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setSampleData(com.smartgwt.client.data.Record...)`

  - ### getDescription

    public String getDescription()
    An optional description of the DataSource's content. It is not automatically exposed on any component, but it is useful for developer documentation, and as such it is included on any `OpenAPI specification` generated by the framework. Markdown is a commonly-used syntax, but you may also embed HTML content. When embedding HTML in the description in a .ds.xml file (see `DataSourceDeclaration`), it is recommended to wrap the HTML in a CDATA tag.

    This description is also provided to AI when AI is asked to work with the data source. Best practices for the description are:

    - Start with a plain language explanation of what the data source and records within it represent, their business concept or core purpose.
    - Describe how the data source relates to other data sources in the application.
    - Mention the approximate size of the data source and whether/when records are updated, added, and removed, as well as the approximate rates of updates, additions, and removals.
    - Identify any known data issues or anomalies.

    In addition to the data source-level description, each field can be described via `DataSourceField.description`.

    Returns:
      Current description value. Default value is null
    See Also:
      - `getSampleData()`

  - ### setDescriptionField

    public DataSource setDescriptionField(String descriptionField) throws IllegalStateException
    Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.

    For example, for a DataSource representing employees, a field containing the employee's "bio" might be a good choice, or for an email message, the message body.

    If descriptionField is unset, it defaults to any field named "description" or "desc" in the record, or the first long text field (greater than 255 characters) in the record, or null if no such field exists.

    Parameters:
      `descriptionField` - New descriptionField value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### getDescriptionField

    public String getDescriptionField()
    Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.

    For example, for a DataSource representing employees, a field containing the employee's "bio" might be a good choice, or for an email message, the message body.

    If descriptionField is unset, it defaults to any field named "description" or "desc" in the record, or the first long text field (greater than 255 characters) in the record, or null if no such field exists.

    Returns:
      Current descriptionField value. Default value is null
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### setDiscoverTreeSettings

    public DataSource setDiscoverTreeSettings(DiscoverTreeSettings discoverTreeSettings) throws IllegalStateException
    Settings to use when discoverTree() is automatcially called because `autoDiscoverTree` is set to true for this DataSource
    Parameters:
      `discoverTreeSettings` - New discoverTreeSettings value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getDiscoverTreeSettings

    public DiscoverTreeSettings getDiscoverTreeSettings()
    Settings to use when discoverTree() is automatcially called because `autoDiscoverTree` is set to true for this DataSource
    Returns:
      Current discoverTreeSettings value. Default value is null

  - ### setDropExtraFields

    public DataSource setDropExtraFields(Boolean dropExtraFields) throws IllegalStateException
    Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.

    For `JSON` data, this means extra properties in selected objects are dropped.

    By default, for DMI DSResponses, DSResponse.data is filtered on the server to just the set of fields defined on the DataSource (see the overview in `DMI`).

    This type of filtering can also be enabled for non-DMI DSResponses. By default it is enabled for Hibernate and JPA datasources to avoid unintentional lazy loading too much of a data model. For the rest of datasources this is disabled by default.

    Explicitly setting this property to `false` disables (or to `true` enables) this filtering for this DataSource only. This setting overrides the configuration in `server.properties`. This setting can be overridden by `ServerObject.dropExtraFields`.

    Parameters:
      `dropExtraFields` - New dropExtraFields value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Client-side Data Integration`

  - ### getDropExtraFields

    public Boolean getDropExtraFields()
    Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.

    For `JSON` data, this means extra properties in selected objects are dropped.

    By default, for DMI DSResponses, DSResponse.data is filtered on the server to just the set of fields defined on the DataSource (see the overview in `DMI`).

    This type of filtering can also be enabled for non-DMI DSResponses. By default it is enabled for Hibernate and JPA datasources to avoid unintentional lazy loading too much of a data model. For the rest of datasources this is disabled by default.

    Explicitly setting this property to `false` disables (or to `true` enables) this filtering for this DataSource only. This setting overrides the configuration in `server.properties`. This setting can be overridden by `ServerObject.dropExtraFields`.

    Returns:
      Current dropExtraFields value. Default value is null
    See Also:
      - `Client-side Data Integration`

  - ### setDropUnknownCriteria

    public DataSource setDropUnknownCriteria(Boolean dropUnknownCriteria) throws IllegalStateException
    If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client. This property is useful for cases where you custom server logic makes use of criteria values to determine what set of records to return to the client, but the data does not actually have record values for these fields and as such the client-side filtering logic should ignore them.
    Parameters:
      `dropUnknownCriteria` - New dropUnknownCriteria value. Default value is true
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getDropUnknownCriteria

    public Boolean getDropUnknownCriteria()
    If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client. This property is useful for cases where you custom server logic makes use of criteria values to determine what set of records to return to the client, but the data does not actually have record values for these fields and as such the client-side filtering logic should ignore them.
    Returns:
      Current dropUnknownCriteria value. Default value is true

  - ### setEnforceSecurityOnClient

    public DataSource setEnforceSecurityOnClient(Boolean enforceSecurityOnClient) throws IllegalStateException
    Indicates that `DeclarativeSecurity` should be enforced on the client. This property only applies to `Client Only DataSources`. If property is unset for a clientOnly DataSource it will be set `true` automatically. Set this property to `false` to explicitly disable this feature for a clientOnly DataSource.

    Note that certain security features are not supported on the client like Velocity rules.

    Parameters:
      `enforceSecurityOnClient` - New enforceSecurityOnClient value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Declarative Security`

  - ### getEnforceSecurityOnClient

    public Boolean getEnforceSecurityOnClient()
    Indicates that `DeclarativeSecurity` should be enforced on the client. This property only applies to `Client Only DataSources`. If property is unset for a clientOnly DataSource it will be set `true` automatically. Set this property to `false` to explicitly disable this feature for a clientOnly DataSource.

    Note that certain security features are not supported on the client like Velocity rules.

    Returns:
      Current enforceSecurityOnClient value. Default value is null
    See Also:
      - `Declarative Security`

  - ### setEnumConstantProperty

    public DataSource setEnumConstantProperty(String enumConstantProperty) throws IllegalStateException
    The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean". Defaults to "_constant" if not set.

    This property is only applicable if you are using the Smart GWT server

    Note : This is an advanced setting

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

  - ### setEnumOrdinalProperty

    public DataSource setEnumOrdinalProperty(String enumOrdinalProperty) throws IllegalStateException
    The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean". Defaults to "_ordinal" if not set.

    This property is only applicable if you are using the Smart GWT server

    Note : This is an advanced setting

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

  - ### setEnumTranslateStrategy

    public DataSource setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy) throws IllegalStateException
    Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript. This property is only applicable if you are using the Smart GWT server

    Note : This is an advanced setting

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

  - ### setGlobalNamespaces

    public DataSource setGlobalNamespaces(Map globalNamespaces)
    Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.

    The default value is:

            globalNamespaces : {
               xsi: "http://www.w3.org/2001/XMLSchema-instance",
               xsd: "http://www.w3.org/2001/XMLSchema"
            },

    This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.

    Note that some web services will only accept specific revisions of the XML Schema URI. If xsi-namespaced attributes seem to be ignored by an older webservice, try the URI "http://www.w3.org/1999/XMLSchema-instance" instead.

    Parameters:
      `globalNamespaces` - New globalNamespaces value. Default value is ...
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getGlobalNamespaces

    public Map getGlobalNamespaces()
    Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.

    The default value is:

            globalNamespaces : {
               xsi: "http://www.w3.org/2001/XMLSchema-instance",
               xsd: "http://www.w3.org/2001/XMLSchema"
            },

    This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.

    Note that some web services will only accept specific revisions of the XML Schema URI. If xsi-namespaced attributes seem to be ignored by an older webservice, try the URI "http://www.w3.org/1999/XMLSchema-instance" instead.

    Returns:
      Current globalNamespaces value. Default value is ...

  - ### setIconField

    public DataSource setIconField(String iconField) throws IllegalStateException
    Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.

    For example, for a DataSource of employees, a "photo" field of type "image" should be designated as the iconField.

    If not explicitly set, iconField looks for fields named "picture", "thumbnail", "icon", "image" and "img", in that order, and will use any of these fields as the iconField if it exists and has type "image".

    To avoid any field being used as the iconField, set iconField to `null`.

    Parameters:
      `iconField` - New iconField value. Default value is see below
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### getIconField

    public String getIconField()
    Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.

    For example, for a DataSource of employees, a "photo" field of type "image" should be designated as the iconField.

    If not explicitly set, iconField looks for fields named "picture", "thumbnail", "icon", "image" and "img", in that order, and will use any of these fields as the iconField if it exists and has type "image".

    To avoid any field being used as the iconField, set iconField to `null`.

    Returns:
      Current iconField value. Default value is see below
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### setIgnoreTextMatchStyleCaseSensitive

    public DataSource setIgnoreTextMatchStyleCaseSensitive(Boolean ignoreTextMatchStyleCaseSensitive) throws IllegalStateException
    For fields on this dataSource that specify `ignoreTextMatchStyle` true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. This property dictates whether that match is case-sensitive like the "exactCase" textMatchStyle, or case-insensitive like the "exact" textMatchStyle (the default). Please see the `TextMatchStyle documentation` for a discussion of the nuances of case-sensitive matching.
    Parameters:
      `ignoreTextMatchStyleCaseSensitive` - New ignoreTextMatchStyleCaseSensitive value. Default value is false
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getIgnoreTextMatchStyleCaseSensitive

    public Boolean getIgnoreTextMatchStyleCaseSensitive()
    For fields on this dataSource that specify `ignoreTextMatchStyle` true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. This property dictates whether that match is case-sensitive like the "exactCase" textMatchStyle, or case-insensitive like the "exact" textMatchStyle (the default). Please see the `TextMatchStyle documentation` for a discussion of the nuances of case-sensitive matching.
    Returns:
      Current ignoreTextMatchStyleCaseSensitive value. Default value is false

  - ### setImplicitCriteria

    public DataSource setImplicitCriteria(Criteria implicitCriteria)
    Criteria that are implicitly applied to all fetches made through this DataSource. These criteria are never shown to or edited by the user and are cumulative with any other criteria provided on the DSRequest.

    For example, a DataSource might *always* implicitly limit its fetch results to records owned by the current user's department. Components and ResultSets requesting data from the DataSource can then apply further implicitCriteria of their own, separately from their regular, user-editable criteria.

    For instance, a grid bound to this dataSource might be further limited to implicitly show only the subset of records created by the current user. See `DataBoundComponent.implicitCriteria` and `ResultSet.implicitCriteria` for more on these localized options.

    Note that, while `implicitCriteria` can be declared in a server DataSource file using `Component XML`, it is an entirely client-side feature, added by client-side components. So it does not affect server-side requests, and will not be added to client-side requests that don't come from a Smart GWT UI (eg RestHandler).

    Parameters:
      `implicitCriteria` - New implicitCriteria value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getImplicitCriteria

    public Criteria getImplicitCriteria()
    Criteria that are implicitly applied to all fetches made through this DataSource. These criteria are never shown to or edited by the user and are cumulative with any other criteria provided on the DSRequest.

    For example, a DataSource might *always* implicitly limit its fetch results to records owned by the current user's department. Components and ResultSets requesting data from the DataSource can then apply further implicitCriteria of their own, separately from their regular, user-editable criteria.

    For instance, a grid bound to this dataSource might be further limited to implicitly show only the subset of records created by the current user. See `DataBoundComponent.implicitCriteria` and `ResultSet.implicitCriteria` for more on these localized options.

    Note that, while `implicitCriteria` can be declared in a server DataSource file using `Component XML`, it is an entirely client-side feature, added by client-side components. So it does not affect server-side requests, and will not be added to client-side requests that don't come from a Smart GWT UI (eg RestHandler).

    Returns:
      Current implicitCriteria value. Default value is null

  - ### setInfoField

    public DataSource setInfoField(String infoField) throws IllegalStateException
    Name of the field that has the second most pertinent piece of textual information in the record, for use when a `DataBoundComponent` needs to show a short summary of a record.

    For example, for a DataSource of employees, a "job title" field would probably be the second most pertinent text field aside from the employee's "full name".

    Unlike `titleField`, infoField is not automatically determined in the absence of an explicit setting.

    Parameters:
      `infoField` - New infoField value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### getInfoField

    public String getInfoField()
    Name of the field that has the second most pertinent piece of textual information in the record, for use when a `DataBoundComponent` needs to show a short summary of a record.

    For example, for a DataSource of employees, a "job title" field would probably be the second most pertinent text field aside from the employee's "full name".

    Unlike `titleField`, infoField is not automatically determined in the absence of an explicit setting.

    Returns:
      Current infoField value. Default value is null
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### setInheritsFrom

    public DataSource setInheritsFrom(String inheritsFrom) throws IllegalStateException
    ID of another DataSource this DataSource inherits its `fields` from.

    Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields. Fields with the same name are merged in the same way that `databound component fields` are merged with DataSource fields.

    The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can set `useParentFieldOrder` to instead use the parent's field order, with new local fields appearing last. You can set `showLocalFieldsOnly` to have all non-local fields hidden.

    Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other via `inheritsFrom`.

    This feature can be used for:

    - creating a customized view (eg, only certain fields shown) which will be used by multiple `databound components`.
    - adding presentation-specific attributes to metadata that has been automatically derived from `XML Schema` or other metadata formats
    - modeling object subclassing and extension in server-side code and storage systems
    - modeling relational database joins, and the equivalents in other systems
    - creating hooks for others to customize your application in a maintainable way. For example, if you have a dataSource "employee", you can create a dataSource "customizedEmployee" which inherits from "employee" but does not initially define any fields, and bind all `databound components` to "customizedEmployee". Customizations of fields (including appearance changes, field order, new fields, hiding of fields, and custom validation rules) can be added to "customizedEmployee", so that they are kept separately from the original field data and have the best possible chance of working with future versions of the "employee" dataSource.
    Parameters:
      `inheritsFrom` - New inheritsFrom value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - Schema Chaining Example

  - ### getInheritsFrom

    public String getInheritsFrom()
    ID of another DataSource this DataSource inherits its `fields` from.

    Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields. Fields with the same name are merged in the same way that `databound component fields` are merged with DataSource fields.

    The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can set `useParentFieldOrder` to instead use the parent's field order, with new local fields appearing last. You can set `showLocalFieldsOnly` to have all non-local fields hidden.

    Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other via `inheritsFrom`.

    This feature can be used for:

    - creating a customized view (eg, only certain fields shown) which will be used by multiple `databound components`.
    - adding presentation-specific attributes to metadata that has been automatically derived from `XML Schema` or other metadata formats
    - modeling object subclassing and extension in server-side code and storage systems
    - modeling relational database joins, and the equivalents in other systems
    - creating hooks for others to customize your application in a maintainable way. For example, if you have a dataSource "employee", you can create a dataSource "customizedEmployee" which inherits from "employee" but does not initially define any fields, and bind all `databound components` to "customizedEmployee". Customizations of fields (including appearance changes, field order, new fields, hiding of fields, and custom validation rules) can be added to "customizedEmployee", so that they are kept separately from the original field data and have the best possible chance of working with future versions of the "employee" dataSource.
    Returns:
      Current inheritsFrom value. Default value is null
    See Also:
      - Schema Chaining Example

  - ### setIsSampleDS

    public DataSource setIsSampleDS(Boolean isSampleDS) throws IllegalStateException
    Used by Reify to identify DataSources that are provided as samples. Reify will not automatically alter sample DataSource relations when removing DataSources from a project.
    Parameters:
      `isSampleDS` - New isSampleDS value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getIsSampleDS

    public Boolean getIsSampleDS()
    Used by Reify to identify DataSources that are provided as samples. Reify will not automatically alter sample DataSource relations when removing DataSources from a project.
    Returns:
      Current isSampleDS value. Default value is null

  - ### setJsonPrefix

    public DataSource setJsonPrefix(String jsonPrefix) throws IllegalStateException
    Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.

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

    Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.
    Note: If the prefix / suffix served by your backend is not a constant, you can use `dataFormat:"custom"` instead and explicitly parse the prefix out as part of `transformResponse()`.

    Note : This is an advanced setting

    Parameters:
      `jsonPrefix` - New jsonPrefix value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `OperationBinding.setDataFormat(com.smartgwt.client.types.DSDataFormat)`
      - `OperationBinding.setDataTransport(com.smartgwt.client.types.RPCTransport)`

  - ### 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 inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

    Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.
    Note: If the prefix / suffix served by your backend is not a constant, you can use `dataFormat:"custom"` instead and explicitly parse the prefix out as part of `transformResponse()`.

    Returns:
      Current jsonPrefix value. Default value is null
    See Also:
      - `OperationBinding.getDataFormat()`
      - `OperationBinding.getDataTransport()`

  - ### setJsonSuffix

    public DataSource setJsonSuffix(String jsonSuffix) throws IllegalStateException
    Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.

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

    Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.

    Note : This is an advanced setting

    Parameters:
      `jsonSuffix` - New jsonSuffix value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `OperationBinding.setDataFormat(com.smartgwt.client.types.DSDataFormat)`
      - `OperationBinding.setDataTransport(com.smartgwt.client.types.RPCTransport)`

  - ### 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 inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

    Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.

    Returns:
      Current jsonSuffix value. Default value is null
    See Also:
      - `OperationBinding.getDataFormat()`
      - `OperationBinding.getDataTransport()`

  - ### setMockDataCriteria

    public DataSource setMockDataCriteria(Criteria mockDataCriteria) throws IllegalStateException
    When `mockMode` is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.
    Parameters:
      `mockDataCriteria` - New mockDataCriteria value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getMockDataCriteria

    public Criteria getMockDataCriteria()
    When `mockMode` is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.
    Returns:
      Current mockDataCriteria value. Default value is null

  - ### setMockDataRows

    public DataSource setMockDataRows(Integer mockDataRows) throws IllegalStateException
    When `mockMode` is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data. Set to null to retrieve all available rows.
    Parameters:
      `mockDataRows` - New mockDataRows value. Default value is 75
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getMockDataRows

    public Integer getMockDataRows()
    When `mockMode` is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data. Set to null to retrieve all available rows.
    Returns:
      Current mockDataRows value. Default value is 75

  - ### setMockMode

    public DataSource setMockMode(Boolean mockMode)
    If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to a `clientOnly` DataSource, never writing changes back to the server.

    `mockMode` has no effect on `MockDataSource` or a `clientOnly` DataSource.

    For other DataSources, a one-time fetch will be performed to retrieve sample data, similar to a `cacheAllData` DataSource, except that changes will never be saved back to the server. Only a subset of data will be retrieved, based on `mockDataRows`. `mockDataCriteria` can optionally be set to retrieve specific data.

    Alternatively, mock data can be provided with `cacheData`.

    DataSources can be loaded in `mockMode` via passing settings to `load()`, or if loaded with a screen or project, by passing settings to `RPCManager.loadScreen()` or the server-side Project.load() API.

    Parameters:
      `mockMode` - New mockMode value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getMockMode

    public Boolean getMockMode()
    If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to a `clientOnly` DataSource, never writing changes back to the server.

    `mockMode` has no effect on `MockDataSource` or a `clientOnly` DataSource.

    For other DataSources, a one-time fetch will be performed to retrieve sample data, similar to a `cacheAllData` DataSource, except that changes will never be saved back to the server. Only a subset of data will be retrieved, based on `mockDataRows`. `mockDataCriteria` can optionally be set to retrieve specific data.

    Alternatively, mock data can be provided with `cacheData`.

    DataSources can be loaded in `mockMode` via passing settings to `load()`, or if loaded with a screen or project, by passing settings to `RPCManager.loadScreen()` or the server-side Project.load() API.

    Returns:
      Current mockMode value. Default value is null

  - ### setOperationBindings

    public DataSource setOperationBindings(OperationBinding... operationBindings) throws IllegalStateException
    Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.

    When using the Smart GWT Server, OperationBindings are specified in your DataSource descriptor (.ds.xml file) and control server-side behavior such as what Java object to route DSRequest to (`OperationBinding.serverObject`) or customizations to SQL, JQL and HQL queries (`OperationBinding.customSQL`, `OperationBinding.customJQL` and `OperationBinding.customHQL`). See the @see Java Integration samples.

    For DataSources bound to WSDL-described web services using `serviceNamespace`, OperationBindings are used to bind each DataSource `operationType` to an `operation` of a WSDL-described `web service`, so that a DataSource can both fetch and save data to a web service.

    For example, this code accomplishes part of the binding to the SalesForce partner web services

               DataSource dataSource = new DataSource();
               dataSource.setServiceNamespace("urn:partner.soap.sforce.com");
               OperationBinding fetch = new OperationBinding();
               fetch.setOperationType(DSOperationType.FETCH);
               fetch.setWsOperation("query");
               fetch.setRecordName("sObject");
               OperationBinding add = new OperationBinding();
               add.setOperationType(DSOperationType.ADD);
               add.setWsOperation("create");
               add.setRecordName("SaveResult");
               OperationBinding update = new OperationBinding();
               update.setOperationType(DSOperationType.UPDATE);
               update.setWsOperation("update");
               update.setRecordName("SaveResult");
               OperationBinding remove = new OperationBinding();
               remove.setOperationType(DSOperationType.REMOVE);
               remove.setWsOperation("delete");
               remove.setRecordName("DeleteResult");
               dataSource.setOperationBindings(fetch, add, update, remove);

    NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.

    For DataSources that contact non-WSDL-described XML or JSON services, OperationBindings can be used to separately configure the URL, HTTP method, input and output processing for each operationType. This makes it possible to fetch JSON data from one URL for the "fetch" operationType and save to a web service for the "update" operationType, while appearing as a single integrated DataSource to a `DataBoundComponent` such as an `editable ListGrid`.

    If no operationBinding is defined for a given DataSource operation, all of the properties which are valid on the operationBinding are checked for on the DataSource itself.

    This also means that for a read-only DataSource, that is, a DataSource only capable of fetch operations, operationBindings need not be specified, and instead all operationBinding properties can be set on the DataSource itself. In the RSS Feed sample, you can see an example of using OperationBinding properties directly on the DataSource in order to read an RSS feed.

    Parameters:
      `operationBindings` - New operationBindings value. Default value is null
    Returns:
      `DataSource` 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()
    Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.

    When using the Smart GWT Server, OperationBindings are specified in your DataSource descriptor (.ds.xml file) and control server-side behavior such as what Java object to route DSRequest to (`OperationBinding.serverObject`) or customizations to SQL, JQL and HQL queries (`OperationBinding.customSQL`, `OperationBinding.customJQL` and `OperationBinding.customHQL`). See the @see Java Integration samples.

    For DataSources bound to WSDL-described web services using `serviceNamespace`, OperationBindings are used to bind each DataSource `operationType` to an `operation` of a WSDL-described `web service`, so that a DataSource can both fetch and save data to a web service.

    For example, this code accomplishes part of the binding to the SalesForce partner web services

               DataSource dataSource = new DataSource();
               dataSource.setServiceNamespace("urn:partner.soap.sforce.com");
               OperationBinding fetch = new OperationBinding();
               fetch.setOperationType(DSOperationType.FETCH);
               fetch.setWsOperation("query");
               fetch.setRecordName("sObject");
               OperationBinding add = new OperationBinding();
               add.setOperationType(DSOperationType.ADD);
               add.setWsOperation("create");
               add.setRecordName("SaveResult");
               OperationBinding update = new OperationBinding();
               update.setOperationType(DSOperationType.UPDATE);
               update.setWsOperation("update");
               update.setRecordName("SaveResult");
               OperationBinding remove = new OperationBinding();
               remove.setOperationType(DSOperationType.REMOVE);
               remove.setWsOperation("delete");
               remove.setRecordName("DeleteResult");
               dataSource.setOperationBindings(fetch, add, update, remove);

    NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.

    For DataSources that contact non-WSDL-described XML or JSON services, OperationBindings can be used to separately configure the URL, HTTP method, input and output processing for each operationType. This makes it possible to fetch JSON data from one URL for the "fetch" operationType and save to a web service for the "update" operationType, while appearing as a single integrated DataSource to a `DataBoundComponent` such as an `editable ListGrid`.

    If no operationBinding is defined for a given DataSource operation, all of the properties which are valid on the operationBinding are checked for on the DataSource itself.

    This also means that for a read-only DataSource, that is, a DataSource only capable of fetch operations, operationBindings need not be specified, and instead all operationBinding properties can be set on the DataSource itself. In the RSS Feed sample, you can see an example of using OperationBinding properties directly on the DataSource in order to read an RSS feed.

    Returns:
      Current operationBindings value. Default value is null
    See Also:
      - `OperationBinding`

  - ### setPatternEscapeChar

    public DataSource setPatternEscapeChar(String patternEscapeChar) throws IllegalStateException
    When using the `pattern operators` `search operator`, character that escapes the `patternSingleWildcard` or `patternMultiWildcard` if placed before it, so that it is treated as a literal character.
    Parameters:
      `patternEscapeChar` - New patternEscapeChar value. Default value is "\"
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getPatternEscapeChar

    public String getPatternEscapeChar()
    When using the `pattern operators` `search operator`, character that escapes the `patternSingleWildcard` or `patternMultiWildcard` if placed before it, so that it is treated as a literal character.
    Returns:
      Current patternEscapeChar value. Default value is "\"

  - ### setPatternMultiWildcard

    public DataSource setPatternMultiWildcard(String patternMultiWildcard) throws IllegalStateException
    When using the `pattern operators` `search operator`, character that matches a series of one or more characters.

    Pass multiple strings to provide multiple alternative wildcards.

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

  - ### getPatternMultiWildcard

    public String getPatternMultiWildcard()
    When using the `pattern operators` `search operator`, character that matches a series of one or more characters.

    Pass multiple strings to provide multiple alternative wildcards.

    Returns:
      Current patternMultiWildcard value. Default value is "*"

  - ### setPatternMultiWildcard

    public DataSource setPatternMultiWildcard(String... patternMultiWildcard) throws IllegalStateException
    When using the `pattern operators` `search operator`, character that matches a series of one or more characters.

    Pass multiple strings to provide multiple alternative wildcards.

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

  - ### getPatternMultiWildcardAsStringArray

    public String[] getPatternMultiWildcardAsStringArray()
    When using the `pattern operators` `search operator`, character that matches a series of one or more characters.

    Pass multiple strings to provide multiple alternative wildcards.

    Returns:
      Current patternMultiWildcard value. Default value is "*"

  - ### setPatternSingleWildcard

    public DataSource setPatternSingleWildcard(String patternSingleWildcard) throws IllegalStateException
    When using the `pattern operators` `search operator`, character that matches any single character.

    Pass multiple strings to provide multiple alternative wildcards.

    Parameters:
      `patternSingleWildcard` - New patternSingleWildcard value. Default value is ["?","%"]
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getPatternSingleWildcard

    public String getPatternSingleWildcard()
    When using the `pattern operators` `search operator`, character that matches any single character.

    Pass multiple strings to provide multiple alternative wildcards.

    Returns:
      Current patternSingleWildcard value. Default value is ["?","%"]

  - ### setPatternSingleWildcard

    public DataSource setPatternSingleWildcard(String... patternSingleWildcard) throws IllegalStateException
    When using the `pattern operators` `search operator`, character that matches any single character.

    Pass multiple strings to provide multiple alternative wildcards.

    Parameters:
      `patternSingleWildcard` - New patternSingleWildcard value. Default value is ["?","%"]
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getPatternSingleWildcardAsStringArray

    public String[] getPatternSingleWildcardAsStringArray()
    When using the `pattern operators` `search operator`, character that matches any single character.

    Pass multiple strings to provide multiple alternative wildcards.

    Returns:
      Current patternSingleWildcard value. Default value is ["?","%"]

  - ### setPluralTitle

    public DataSource setPluralTitle(String pluralTitle) throws IllegalStateException
    User-visible plural name for this DataSource.

    For example, for the supplyItem DataSource, "Supply Items".

    Defaults to `dataSource.title` + "s".

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

  - ### getPluralTitle

    public String getPluralTitle()
    User-visible plural name for this DataSource.

    For example, for the supplyItem DataSource, "Supply Items".

    Defaults to `dataSource.title` + "s".

    Returns:
      Current pluralTitle value. Default value is dataSource.ID

  - ### setPreventHTTPCaching

    public DataSource setPreventHTTPCaching(Boolean preventHTTPCaching) throws IllegalStateException
    If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.

    Note that this does not disable caching at higher levels in the framework, for example, the caching performed by `ResultSet`.

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

  - ### getPreventHTTPCaching

    public Boolean getPreventHTTPCaching()
    If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.

    Note that this does not disable caching at higher levels in the framework, for example, the caching performed by `ResultSet`.

    Returns:
      Current preventHTTPCaching value. Default value is true

  - ### setProgressiveLoading

    public DataSource setProgressiveLoading(Boolean progressiveLoading)
    If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the `ResultSet documentation`. Essentially, this means that we avoid issuing a row count query and instead advertise total rows as being slightly more than the number of rows we have already read (see `endGap`). This allows users to load more of a dataset by scrolling past the end of the currently-loaded rows, but it prevents them from scrolling directly to the end of the dataset.

    Generally, progressive loading is appropriate when you have to deal with very large datasets. Note that by default, a dataSource will switch into progressive loading mode automatically when it detects that it is dealing with a dataset beyond a certain size - see `progressiveLoadingThreshold`.

    This setting can be overridden for individual fetch operations with the `OperationBinding.progressiveLoading` property, and also at the level of the individual `DSRequest`. You can also specify `progressiveLoading` on `DataBoundComponents` and certain types of `FormItem` - `SelectItem` and `ComboBoxItem`.

    Currently, this property only applies to users of the built-in SQLDataSource, but you could use it in custom DataSource implementations to trigger the server behavior described in the `ResultSet` documentation linked to above.

    Parameters:
      `progressiveLoading` - New progressiveLoading value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `OperationBinding.progressiveLoading`
      - `DataSource.progressiveLoadingThreshold`
      - `DataSource.lookAhead`
      - `DataSource.endGap`
      - `Progressive Loading`

  - ### getProgressiveLoading

    public Boolean getProgressiveLoading()
    If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the `ResultSet documentation`. Essentially, this means that we avoid issuing a row count query and instead advertise total rows as being slightly more than the number of rows we have already read (see `endGap`). This allows users to load more of a dataset by scrolling past the end of the currently-loaded rows, but it prevents them from scrolling directly to the end of the dataset.

    Generally, progressive loading is appropriate when you have to deal with very large datasets. Note that by default, a dataSource will switch into progressive loading mode automatically when it detects that it is dealing with a dataset beyond a certain size - see `progressiveLoadingThreshold`.

    This setting can be overridden for individual fetch operations with the `OperationBinding.progressiveLoading` property, and also at the level of the individual `DSRequest`. You can also specify `progressiveLoading` on `DataBoundComponents` and certain types of `FormItem` - `SelectItem` and `ComboBoxItem`.

    Currently, this property only applies to users of the built-in SQLDataSource, but you could use it in custom DataSource implementations to trigger the server behavior described in the `ResultSet` documentation linked to above.

    Returns:
      Current progressiveLoading value. Default value is null
    See Also:
      - `OperationBinding.progressiveLoading`
      - `DataSource.progressiveLoadingThreshold`
      - `DataSource.lookAhead`
      - `DataSource.endGap`
      - `Progressive Loading`

  - ### setQualifyColumnNames

    public DataSource setQualifyColumnNames(Boolean qualifyColumnNames) throws IllegalStateException
    For dataSources of `serverType` "sql", determines whether we qualify column names with table names in any SQL we generate. This property can be overridden on specific operationBindings.
    Parameters:
      `qualifyColumnNames` - New qualifyColumnNames value. Default value is true
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `OperationBinding.qualifyColumnNames`

  - ### getQualifyColumnNames

    public Boolean getQualifyColumnNames()
    For dataSources of `serverType` "sql", determines whether we qualify column names with table names in any SQL we generate. This property can be overridden on specific operationBindings.
    Returns:
      Current qualifyColumnNames value. Default value is true
    See Also:
      - `OperationBinding.qualifyColumnNames`

  - ### setRecordName

    public DataSource setRecordName(String recordName) throws IllegalStateException
    Provides a default value for `OperationBinding.recordName`.
    Parameters:
      `recordName` - New recordName value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Client-side Data Integration`

  - ### getRecordName

    public String getRecordName()
    Provides a default value for `OperationBinding.recordName`.
    Returns:
      Current recordName value. Default value is null
    See Also:
      - `Client-side Data Integration`

  - ### setRecordXPath

    public DataSource setRecordXPath(String recordXPath) throws IllegalStateException
    See `OperationBinding.recordXPath`. `recordXPath` can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations, on clientOnly DataSources using String, or on `RestConnector` dataSources
    Parameters:
      `recordXPath` - New recordXPath value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `XPathExpression`
      - `Client-side Data Integration`
      - XML DataSource Example
      - JSON XPath Binding Example

  - ### getRecordXPath

    public String getRecordXPath()
    See `OperationBinding.recordXPath`. `recordXPath` can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations, on clientOnly DataSources using String, or on `RestConnector` dataSources
    Returns:
      Current recordXPath value. Default value is null
    See Also:
      - `XPathExpression`
      - `Client-side Data Integration`
      - XML DataSource Example
      - JSON XPath Binding Example

  - ### setRequestProperties

    public DataSource setRequestProperties(DSRequest requestProperties)
    Additional properties to pass through to the `DSRequest`s made by this DataSource. This must be set before any `DSRequest`s are issued and before any component is bound to the DataSource.

    These properties are applied before `transformRequest()` is called.

    Parameters:
      `requestProperties` - New requestProperties value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `DSRequest`
      - `OperationBinding.setRequestProperties(com.smartgwt.client.data.DSRequest)`
      - `Server DataSource Integration`

  - ### getRequestProperties

    public DSRequest getRequestProperties()
    Additional properties to pass through to the `DSRequest`s made by this DataSource. This must be set before any `DSRequest`s are issued and before any component is bound to the DataSource.

    These properties are applied before `transformRequest()` is called.

    Returns:
      Current requestProperties value. Default value is null
    See Also:
      - `DSRequest`
      - `OperationBinding.getRequestProperties()`
      - `Server DataSource Integration`

  - ### setRequiredMessage

    public DataSource setRequiredMessage(String requiredMessage)
    The required message when a field that has been marked as `required` is not filled in by the user.

    Note that `DataSourceField.requiredMessage` wins over this setting if both are set.

    Parameters:
      `requiredMessage` - New requiredMessage value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `HTMLString`
      - `Form Titles`

  - ### getRequiredMessage

    public String getRequiredMessage()
    The required message when a field that has been marked as `required` is not filled in by the user.

    Note that `DataSourceField.requiredMessage` wins over this setting if both are set.

    Returns:
      Current requiredMessage value. Default value is null
    See Also:
      - `HTMLString`
      - `Form Titles`

  - ### setResultBatchSize

    public DataSource setResultBatchSize(int resultBatchSize)
    Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.

    If you have a relatively small number of records with a great deal of properties or subobjects on each record, and you have not set `dropExtraFields` to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this number lower.

    Note : This is an advanced setting

    Parameters:
      `resultBatchSize` - New resultBatchSize value. Default value is 150
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getResultBatchSize

    public int getResultBatchSize()
    Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.

    If you have a relatively small number of records with a great deal of properties or subobjects on each record, and you have not set `dropExtraFields` to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this number lower.

    Returns:
      Current resultBatchSize value. Default value is 150

  - ### setResultSetClass

    public DataSource setResultSetClass(String resultSetClass) throws IllegalStateException
    Class for ResultSets used by this datasource. If null, defaults to using `ResultSet`.

    This can be set to a custom subclass of ResultSet that, for example, hangs onto to extra information necessary for integration with web services.

    Note : This is an advanced setting

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

  - ### getResultSetClass

    public String getResultSetClass()
    Class for ResultSets used by this datasource. If null, defaults to using `ResultSet`.

    This can be set to a custom subclass of ResultSet that, for example, hangs onto to extra information necessary for integration with web services.

    Returns:
      Current resultSetClass value. Default value is null

  - ### setResultTreeClass

    public DataSource setResultTreeClass(String resultTreeClass) throws IllegalStateException
    Class for ResultTrees used by this datasource. If null, defaults to using `ResultTree`.

    This can be set to a custom subclass of ResultTree that, for example, hangs on to extra information necessary for integration with web services.

    Note : This is an advanced setting

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

  - ### getResultTreeClass

    public String getResultTreeClass()
    Class for ResultTrees used by this datasource. If null, defaults to using `ResultTree`.

    This can be set to a custom subclass of ResultTree that, for example, hangs on to extra information necessary for integration with web services.

    Returns:
      Current resultTreeClass value. Default value is null

  - ### setSampleData

    public DataSource setSampleData(Record... sampleData)
    An optional array of sample data records. These may be actual records from the data source or artificial data that is representative of records from the data source.

    AI may be provided this sample data when AI is asked to work with the data source, to give it a better idea of what the data in the data source "looks like".

    When defining the data source in a .ds.xml file (see `DataSourceDeclaration`), it will likely be helpful to use the XMLSchema-Instance `type` attribute to be able to change the value type from the default (string) to boolean, int, float, date, etc. For example:

          <sampleData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <country>
              <continent>North America</continent>
              <countryName>United States</countryName>
              <countryCode>US</countryCode>
              <area xsi:type="float">9372610</area>
              <population xsi:type="int">266476278</population>
              <gdp xsi:type="float">7247700</gdp>
              <independence xsi:type="date">1776-07-04</independence>
              <government>federal republic</government>
              <capital>Washington</capital>
              <member_g8 xsi:type="boolean">true</member_g8>
            </country>
          ...

    Parameters:
      `sampleData` - New sampleData value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `setDescription(java.lang.String)`
      - `DataSourceField.setDescription(java.lang.String)`

  - ### getSampleData

    public Record[] getSampleData()
    An optional array of sample data records. These may be actual records from the data source or artificial data that is representative of records from the data source.

    AI may be provided this sample data when AI is asked to work with the data source, to give it a better idea of what the data in the data source "looks like".

    When defining the data source in a .ds.xml file (see `DataSourceDeclaration`), it will likely be helpful to use the XMLSchema-Instance `type` attribute to be able to change the value type from the default (string) to boolean, int, float, date, etc. For example:

          <sampleData xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <country>
              <continent>North America</continent>
              <countryName>United States</countryName>
              <countryCode>US</countryCode>
              <area xsi:type="float">9372610</area>
              <population xsi:type="int">266476278</population>
              <gdp xsi:type="float">7247700</gdp>
              <independence xsi:type="date">1776-07-04</independence>
              <government>federal republic</government>
              <capital>Washington</capital>
              <member_g8 xsi:type="boolean">true</member_g8>
            </country>
          ...

    Returns:
      Current sampleData value. Default value is null
    See Also:
      - `getDescription()`
      - `DataSourceField.getDescription()`

  - ### getSchemaNamespace

    public String getSchemaNamespace() throws IllegalStateException
    For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to. This is a read-only attribute automatically present on DataSources returned from SchemaSet.getSchema() and `WebService.getSchema()`.

    Note : This method should be called only after the underlying component has been created.

    Returns:
      Current schemaNamespace value. Default value is null
    Throws:
      `IllegalStateException` - if the underlying component has not yet been created.
    See Also:
      - `Client-side Data Integration`

  - ### setSendExtraFields

    public DataSource setSendExtraFields(Boolean sendExtraFields) throws IllegalStateException
    Analogous to `dropExtraFields`, for data sent to the server. Setting this attribute to false ensures that for any records in the data object, only fields that correspond to declared dataSource fields will be present on the dsRequest data object passed to `transformRequest()` and ultimately sent to the server.
    Parameters:
      `sendExtraFields` - New sendExtraFields value. Default value is true
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Client-side Data Integration`

  - ### getSendExtraFields

    public Boolean getSendExtraFields()
    Analogous to `dropExtraFields`, for data sent to the server. Setting this attribute to false ensures that for any records in the data object, only fields that correspond to declared dataSource fields will be present on the dsRequest data object passed to `transformRequest()` and ultimately sent to the server.
    Returns:
      Current sendExtraFields value. Default value is true
    See Also:
      - `Client-side Data Integration`

  - ### setSendParentNode

    public DataSource setSendParentNode(Boolean sendParentNode)
    Set this attribute if you need to send the dsRequest.parentNode to the server-side.

    Note : This is an advanced setting

    Parameters:
      `sendParentNode` - New sendParentNode value. Default value is false
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getSendParentNode

    public Boolean getSendParentNode()
    Set this attribute if you need to send the dsRequest.parentNode to the server-side.
    Returns:
      Current sendParentNode value. Default value is false

  - ### setServiceNamespace

    public DataSource setServiceNamespace(String serviceNamespace) throws IllegalStateException
    For an XML DataSource, URN of the WebService to use to invoke operations. This URN comes from the "targetNamespace" attribute of the <wsdl:definitions> element in a WSDL (Web Service Description Language) document, and serves as the unique identifier of the service.

    Having loaded a WebService using `XMLTools.loadWSDL()`, setting `serviceNamespace` combined with specifying `operationBindings` that set `OperationBinding.wsOperation` will cause a DataSource to invoke web service operations to fulfill DataSource requests (`DSRequests`).

    Setting `serviceNamespace` also defaults `dataURL` to the service's location, `dataFormat` to "xml" and `dataProtocol` to "soap".

    Parameters:
      `serviceNamespace` - New serviceNamespace value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Client-side Data Integration`

  - ### getServiceNamespace

    public String getServiceNamespace()
    For an XML DataSource, URN of the WebService to use to invoke operations. This URN comes from the "targetNamespace" attribute of the <wsdl:definitions> element in a WSDL (Web Service Description Language) document, and serves as the unique identifier of the service.

    Having loaded a WebService using `XMLTools.loadWSDL()`, setting `serviceNamespace` combined with specifying `operationBindings` that set `OperationBinding.wsOperation` will cause a DataSource to invoke web service operations to fulfill DataSource requests (`DSRequests`).

    Setting `serviceNamespace` also defaults `dataURL` to the service's location, `dataFormat` to "xml" and `dataProtocol` to "soap".

    Returns:
      Current serviceNamespace value. Default value is null
    See Also:
      - `Client-side Data Integration`

  - ### setShowLocalFieldsOnly

    public DataSource setShowLocalFieldsOnly(Boolean showLocalFieldsOnly) throws IllegalStateException
    For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that only the fields listed in this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".
    Parameters:
      `showLocalFieldsOnly` - New showLocalFieldsOnly value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getShowLocalFieldsOnly

    public Boolean getShowLocalFieldsOnly()
    For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that only the fields listed in this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".
    Returns:
      Current showLocalFieldsOnly value. Default value is null

  - ### setShowPrompt

    public DataSource setShowPrompt(Boolean showPrompt)
    Whether RPCRequests sent by this DataSource should enable `RPCRequest.showPrompt` in order to block user interactions until the request completes.

    DataSource requests default to blocking UI interaction because, very often, if the user continues to interact with an application that is waiting for a server response, some kind of invalid or ambiguous situation can arise.

    Examples include pressing a "Save" button a second time before the first save completes, making further edits while edits are still being saved, or trying to initiate editing on a grid that hasn't loaded data.

    Defaulting to blocking the UI prevents these bad interactions, or alternatively, avoids the developer having to write repetitive code to block invalid interactions on every screen.

    If an operation should ever be non-blocking, methods that initiate DataSource requests (such as `fetchData()`) will generally have a `requestProperties` argument allowing `showPrompt` to be set to false for a specific request.

    Parameters:
      `showPrompt` - New showPrompt value. Default value is true
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getShowPrompt

    public Boolean getShowPrompt()
    Whether RPCRequests sent by this DataSource should enable `RPCRequest.showPrompt` in order to block user interactions until the request completes.

    DataSource requests default to blocking UI interaction because, very often, if the user continues to interact with an application that is waiting for a server response, some kind of invalid or ambiguous situation can arise.

    Examples include pressing a "Save" button a second time before the first save completes, making further edits while edits are still being saved, or trying to initiate editing on a grid that hasn't loaded data.

    Defaulting to blocking the UI prevents these bad interactions, or alternatively, avoids the developer having to write repetitive code to block invalid interactions on every screen.

    If an operation should ever be non-blocking, methods that initiate DataSource requests (such as `fetchData()`) will generally have a `requestProperties` argument allowing `showPrompt` to be set to false for a specific request.

    Returns:
      Current showPrompt value. Default value is true

  - ### setSkipJSONValidation

    public DataSource setSkipJSONValidation(SkipJSONValidation skipJSONValidation)
    Sets what level of JSON validation will apply for this DataSource.

    Note that the point of "partial" validation mode is that if the JSON ihat's delivered is correct, we'll still need to validate to get "date" and such in the correct time, but shouldn't need to for the rest.

    Parameters:
      `skipJSONValidation` - New skipJSONValidation value. Default value is "none"
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getSkipJSONValidation

    public SkipJSONValidation getSkipJSONValidation()
    Sets what level of JSON validation will apply for this DataSource.

    Note that the point of "partial" validation mode is that if the JSON ihat's delivered is correct, we'll still need to validate to get "date" and such in the correct time, but shouldn't need to for the rest.

    Returns:
      Current skipJSONValidation value. Default value is "none"

  - ### setStrictSQLFiltering

    public DataSource setStrictSQLFiltering(Boolean strictSQLFiltering) throws IllegalStateException
    If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:

             field == "someValue"  (normally false)
             field != "someValue"  (normally true)
             not (field == "someValue")   (normally true)
             not (field != "someValue")   (normally false)

    This property can be overridden per-query by specifying `strictSQLFiltering` directly as a property on the `AdvancedCriteria`.

    NOTE: On the server side, this property is only applicable if you are using the SQL DataSource; the other built-in types (Hibernate and JPA/JPA2) do not offer this mode.

    Note : This is an advanced setting

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

  - ### getStrictSQLFiltering

    public Boolean getStrictSQLFiltering()
    If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:

             field == "someValue"  (normally false)
             field != "someValue"  (normally true)
             not (field == "someValue")   (normally true)
             not (field != "someValue")   (normally false)

    This property can be overridden per-query by specifying `strictSQLFiltering` directly as a property on the `AdvancedCriteria`.

    NOTE: On the server side, this property is only applicable if you are using the SQL DataSource; the other built-in types (Hibernate and JPA/JPA2) do not offer this mode.

    Returns:
      Current strictSQLFiltering value. Default value is false

  - ### setTagName

    public DataSource setTagName(String tagName) throws IllegalStateException
    Tag name to use when serializing to XML. If unspecified, the `dataSource.ID` will be used.

    Note : This is an advanced setting

    Parameters:
      `tagName` - New tagName value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Client-side Data Integration`

  - ### getTagName

    public String getTagName()
    Tag name to use when serializing to XML. If unspecified, the `dataSource.ID` will be used.
    Returns:
      Current tagName value. Default value is null
    See Also:
      - `Client-side Data Integration`

  - ### setTitle

    public DataSource setTitle(String title)
    User-visible name for this DataSource.

    For example, for the supplyItem DataSource, "Supply Item".

    If is unset, `getAutoTitle()` method will be used with `dataSource.ID`. value in order to derive a default value for the title.

    For example "employee" ID will be derived to "Employee", "team_member" ID will be derived to "Team Member".

    Parameters:
      `title` - New title value. Default value is dataSource.ID
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getTitle

    public String getTitle()
    User-visible name for this DataSource.

    For example, for the supplyItem DataSource, "Supply Item".

    If is unset, `getAutoTitle()` method will be used with `dataSource.ID`. value in order to derive a default value for the title.

    For example "employee" ID will be derived to "Employee", "team_member" ID will be derived to "Team Member".

    Returns:
      Current title value. Default value is dataSource.ID

  - ### setTitleField

    public DataSource setTitleField(String titleField) throws IllegalStateException
    Best field to use for a user-visible title for an individual record from this dataSource.

    For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.

    If not explicitly set, the titleField is determined by looking for fields named "name", "dataSourceIdName", "title", "dataSourceIdTitle", "label", "dataSourceIdLabel", "id" and "dataSourceIdId". For example, for a DataSource with ID "customer", a field called customerName would be found if there were no "name" field. Search is case insensitive, and an underscore is allowed after dataSourceId (so that, for example, "CUSTOMER_NAME" would also be found and preferred).

    For purposes of this search, any trailing numerals in the DataSource ID are discarded, so a DataSource with ID "office2" will search for title fields as if the ID were just "office".

    If no field is found that matches any of the names above, then the first field is designated as the titleField.

    Parameters:
      `titleField` - New titleField value. Default value is see below
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### getTitleField

    public String getTitleField()
    Best field to use for a user-visible title for an individual record from this dataSource.

    For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.

    If not explicitly set, the titleField is determined by looking for fields named "name", "dataSourceIdName", "title", "dataSourceIdTitle", "label", "dataSourceIdLabel", "id" and "dataSourceIdId". For example, for a DataSource with ID "customer", a field called customerName would be found if there were no "name" field. Search is case insensitive, and an underscore is allowed after dataSourceId (so that, for example, "CUSTOMER_NAME" would also be found and preferred).

    For purposes of this search, any trailing numerals in the DataSource ID are discarded, so a DataSource with ID "office2" will search for title fields as if the ID were just "office".

    If no field is found that matches any of the names above, then the first field is designated as the titleField.

    Returns:
      Current titleField value. Default value is see below
    See Also:
      - `DsSpecialFields overview and related methods`

  - ### setTranslatePatternOperators

    public DataSource setTranslatePatternOperators(boolean translatePatternOperators) throws IllegalStateException
    `Search operators` like "matchesPattern" use patterns like "foo*txt" to match text values. The patterns are similar to the patterns you use to match names of files in a command-line interface, or to the pattern allowed for the SQL "LIKE" operator.

    `translatePatternOperators` controls whether these pattern operators should be translated to a nested series of "startsWith"/"endsWidth"/"contains" operators before being sent to the server. This allows a server that only implements simple operators like "startsWith" to support pattern operators such as "matchesPattern" and "containsPattern", but with caveats:

    - single-character wildcards are not supported
    - multiple wildcards are not truly order-dependent, for example *1*2*3* will match 1,2,3 as interior characters in any order.
    - may be less efficient than a direct server-side implementation that is able to translate the pattern directly to the underlying storage engine.

    Note that since "containsPattern" is essentially equivalent to "matchesPattern" but with "*" wildcards at the beginning and end of every pattern, the second limitation (pattern not really order dependent) may be fairly obvious to users when using this feature. For example, "m*t" will match "we meet" and "we teem".

    The following are examples of how patterns are translated to simpler operators. Note that the case sensitive version of the operator is referred to below, but of course "iMatchesPattern" and "iContainsPattern" will be translated to case-insensitive versions of these operators, such as "iStartsWith".

    *foo (endsWith)
    foo* (startsWith)
    *foo* (contains)
    *foo*bar (contains and endsWith)
    foo*bar* (startsWith and contains)
    foo*bar (startsWith and endsWith)
    *foo*bar* (multiple contains)

    Also supported: one startsWith, multiple contains, one endsWith.

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

  - ### getTranslatePatternOperators

    public boolean getTranslatePatternOperators()
    `Search operators` like "matchesPattern" use patterns like "foo*txt" to match text values. The patterns are similar to the patterns you use to match names of files in a command-line interface, or to the pattern allowed for the SQL "LIKE" operator.

    `translatePatternOperators` controls whether these pattern operators should be translated to a nested series of "startsWith"/"endsWidth"/"contains" operators before being sent to the server. This allows a server that only implements simple operators like "startsWith" to support pattern operators such as "matchesPattern" and "containsPattern", but with caveats:

    - single-character wildcards are not supported
    - multiple wildcards are not truly order-dependent, for example *1*2*3* will match 1,2,3 as interior characters in any order.
    - may be less efficient than a direct server-side implementation that is able to translate the pattern directly to the underlying storage engine.

    Note that since "containsPattern" is essentially equivalent to "matchesPattern" but with "*" wildcards at the beginning and end of every pattern, the second limitation (pattern not really order dependent) may be fairly obvious to users when using this feature. For example, "m*t" will match "we meet" and "we teem".

    The following are examples of how patterns are translated to simpler operators. Note that the case sensitive version of the operator is referred to below, but of course "iMatchesPattern" and "iContainsPattern" will be translated to case-insensitive versions of these operators, such as "iStartsWith".

    *foo (endsWith)
    foo* (startsWith)
    *foo* (contains)
    *foo*bar (contains and endsWith)
    foo*bar* (startsWith and contains)
    foo*bar (startsWith and endsWith)
    *foo*bar* (multiple contains)

    Also supported: one startsWith, multiple contains, one endsWith.

    Returns:
      Current translatePatternOperators value. Default value is false

  - ### setTrimMilliseconds

    public DataSource setTrimMilliseconds(Boolean trimMilliseconds) throws IllegalStateException
    For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa. By default, millisecond information is preserved (ie, it is not trimmed). You only need to consider trimming millisecond values if their presence causes a problem - for example, a custom server that is not expecting that extra information and so fails parsing.

    Note that there is no inherent support for millisecond precision in Smart GWT widgets; if you need millisecond-precise visibility and editability of values in your client, you must write custom formatters and editors (or sponsor the addition of such things to the framework). Server-side, millisecond-precise values are delivered to and obtained from DataSources, so DataSource implementations that are capable of persisting and reading millisecond values should work transparently. Of the built-in DataSource types, the JPA and Hibernate DataSources will transparently handle millisecond-precise values as long as the underlying database supports millisecond precision, and the underlying column is of an appropriate type. The SQLDataSource provides accuracy to the nearest second by default; you can switch on millisecond precision per-field with the `storeMilliseconds` attribute.

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

  - ### getTrimMilliseconds

    public Boolean getTrimMilliseconds()
    For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa. By default, millisecond information is preserved (ie, it is not trimmed). You only need to consider trimming millisecond values if their presence causes a problem - for example, a custom server that is not expecting that extra information and so fails parsing.

    Note that there is no inherent support for millisecond precision in Smart GWT widgets; if you need millisecond-precise visibility and editability of values in your client, you must write custom formatters and editors (or sponsor the addition of such things to the framework). Server-side, millisecond-precise values are delivered to and obtained from DataSources, so DataSource implementations that are capable of persisting and reading millisecond values should work transparently. Of the built-in DataSource types, the JPA and Hibernate DataSources will transparently handle millisecond-precise values as long as the underlying database supports millisecond precision, and the underlying column is of an appropriate type. The SQLDataSource provides accuracy to the nearest second by default; you can switch on millisecond precision per-field with the `storeMilliseconds` attribute.

    Returns:
      Current trimMilliseconds value. Default value is null

  - ### setUseFlatFields

    public DataSource setUseFlatFields(Boolean useFlatFields) throws IllegalStateException
    Like `DataBoundComponent.useFlatFields`, but applies to all DataBound components that bind to this DataSource.
    Parameters:
      `useFlatFields` - New useFlatFields value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getUseFlatFields

    public Boolean getUseFlatFields()
    Like `DataBoundComponent.useFlatFields`, but applies to all DataBound components that bind to this DataSource.
    Returns:
      Current useFlatFields value. Default value is null

  - ### setUseHttpProxy

    public DataSource setUseHttpProxy(Boolean useHttpProxy) throws IllegalStateException
    Like `OperationBinding.useHttpProxy`, but serves as a default for this DataSource that may be overridden by individual operationBindings.
    Parameters:
      `useHttpProxy` - New useHttpProxy value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Client-side Data Integration`

  - ### getUseHttpProxy

    public Boolean getUseHttpProxy()
    Like `OperationBinding.useHttpProxy`, but serves as a default for this DataSource that may be overridden by individual operationBindings.
    Returns:
      Current useHttpProxy value. Default value is null
    See Also:
      - `Client-side Data Integration`

  - ### setUseLocalValidators

    public DataSource setUseLocalValidators(Boolean useLocalValidators)
    Whether to attempt validation on the client at all for this DataSource. If unset (the default), client-side validation is enabled.

    Disabling client-side validation entirely is a good way to test server-side validation.

    Note : This is an advanced setting

    Parameters:
      `useLocalValidators` - New useLocalValidators value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    See Also:
      - `Validation overview and related methods`

  - ### getUseLocalValidators

    public Boolean getUseLocalValidators()
    Whether to attempt validation on the client at all for this DataSource. If unset (the default), client-side validation is enabled.

    Disabling client-side validation entirely is a good way to test server-side validation.

    Returns:
      Current useLocalValidators value. Default value is null
    See Also:
      - `Validation overview and related methods`

  - ### setUseOfflineStorage

    public DataSource setUseOfflineStorage(Boolean useOfflineStorage)
    Whether we store server responses for this DataSource into `browser-based offline storage`, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server). Note that by default we do NOT use offline storage for a dataSource.
    Parameters:
      `useOfflineStorage` - New useOfflineStorage value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getUseOfflineStorage

    public Boolean getUseOfflineStorage()
    Whether we store server responses for this DataSource into `browser-based offline storage`, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server). Note that by default we do NOT use offline storage for a dataSource.
    Returns:
      Current useOfflineStorage value. Default value is null

  - ### setUseParentFieldOrder

    public DataSource setUseParentFieldOrder(Boolean useParentFieldOrder) throws IllegalStateException
    For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource. New fields, if any, are placed at the end.
    Parameters:
      `useParentFieldOrder` - New useParentFieldOrder value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - Schema Chaining Example

  - ### getUseParentFieldOrder

    public Boolean getUseParentFieldOrder()
    For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource. New fields, if any, are placed at the end.
    Returns:
      Current useParentFieldOrder value. Default value is null
    See Also:
      - Schema Chaining Example

  - ### setUseStrictJSON

    public DataSource setUseStrictJSON(Boolean useStrictJSON) throws IllegalStateException
    Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.

    Only applies to dataSources which send requests to a server and have `dataFormat` set to "json" or "iscServer".

    Note: using strict JSON avoids a known issue in Internet Explorer 9 where datasource transactions can leak memory due to a browser behavior where the native `eval()` method fails to clean up references when the objects go out of scope. See `allowIE9Leak` for more on this.

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

  - ### getUseStrictJSON

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

    Only applies to dataSources which send requests to a server and have `dataFormat` set to "json" or "iscServer".

    Note: using strict JSON avoids a known issue in Internet Explorer 9 where datasource transactions can leak memory due to a browser behavior where the native `eval()` method fails to clean up references when the objects go out of scope. See `allowIE9Leak` for more on this.

    Returns:
      Current useStrictJSON value. Default value is null

  - ### setUseTestDataFetch

    public DataSource setUseTestDataFetch(Boolean useTestDataFetch)
    When set, causes a `client-only` or `cacheAllData` DataSource to create a second DataSource to perform it's one-time fetch. By default, this attribute will be considered true when clientOnly is true, cacheAllData is false or unset and a dataURL or testFileName is specified on the DataSource.
    Parameters:
      `useTestDataFetch` - New useTestDataFetch value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls

  - ### getUseTestDataFetch

    public Boolean getUseTestDataFetch()
    When set, causes a `client-only` or `cacheAllData` DataSource to create a second DataSource to perform it's one-time fetch. By default, this attribute will be considered true when clientOnly is true, cacheAllData is false or unset and a dataURL or testFileName is specified on the DataSource.
    Returns:
      Current useTestDataFetch value. Default value is null

  - ### setValidateRelatedRecords

    public DataSource setValidateRelatedRecords(Boolean validateRelatedRecords) throws IllegalStateException
    If true, indicates that the Smart GWT Server should automatically apply a `ValidatorType` of "hasRelatedRecord" to every field on this dataSource that has a `foreignKey` defined.
    Parameters:
      `validateRelatedRecords` - New validateRelatedRecords value. Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getValidateRelatedRecords

    public Boolean getValidateRelatedRecords()
    If true, indicates that the Smart GWT Server should automatically apply a `ValidatorType` of "hasRelatedRecord" to every field on this dataSource that has a `foreignKey` defined.
    Returns:
      Current validateRelatedRecords value. Default value is null

  - ### addData

    public void addData(Record newRecord)
    Perform an "add" DataSource operation against this DataSource, to create a new DataSource record. If a callback was provided, it will be invoked when the operation completes successfully.

    If the operation fails, the callback will not be invoked unless `DSRequest.willHandleError` is true. See the `error handling overview` for more information.

    NOTE: do not use repeated calls to `addData()` to provide the initial dataset for a `clientOnly` DataSource, instead, provide initial data via `cacheData`. Using `addData()` for subsequent, incremental updates from sources like user editing is fine.

    #### Batch inserting

    `addData()` can be passed a `List` of records to insert, rather than a single record. Actual support for this kind of multi-add is entirely dependent on the server-side DataSource implementation; only the built-in `SQLDataSource` has support for multi-add out-of-the-box. If you are using `SQLDataSource` (ie, your dataSource's `serverType` is "sql"), the default behavior of the server when it receives an "add" request with a list of records is to invoke a single-record add on the `DataSource` for each of the records in the provided list.

    However, you can also configure the server to generate a true "batch insert", and this will typically be significantly faster. Instead of generating multiple `INSERT` queries, `SQLDataSource` will generate a single `INSERT` with multiple `VALUES`, like so:

             INSERT INTO myDataSource (field1, field2, field3)
                 VALUES(97, 'test string', 117)
                 VALUES(1, 'Another test', 73)
                 . . .
                 VALUES(8056, 'Final record', 70707)

    Note, the Oracle database product does not support this syntax, so we implement batch insert in a different way - using subselects - with that one database. This difference is transparent from the perspective of a Smart GWT developer, and is only mentioned for completeness.

    Batch inserting can be configured at the `DSRequest`, `DataSource` and `OperationBinding` levels, and it can also be globally configured in `server.properties`. See the `multiInsertStrategy` documentation for details.

    #### Cache Synchronization and Audit

    This optimized batch insert style of multi-record add only supports `cache synchronization` in a limited way, because database products do not provide a reliable way to determine the generated keys of rows inserted in this way. We support cache synchronization of batch-inserted records only when
    - The DataSource does not specify any "sequence" fields, and
    - The `requestValuesPlusSequences` `cacheSyncStrategy` is in force
    We support `automatic audit` of batch-inserted records only when both of the above conditions are true, and the `sql.multi.insert.allowAudit` flag is set to `true` in your `server.properties` file.

    Additionally, be aware that any values missing from the original request data for whatever reason, will also be missing from both the cache-sync data and the audit records.

    "Simple" multi-record add, where each record is added with a discrete INSERT, does fully support cache-sync by default, but you may wish to consider turning it off when adding large numbers of records because the extra cache sync fetches can add significantly to the overall operation time (note, this only applies to the default "refetch" cache-sync strategy, so it does not affect the limited cache sync applicable to optimized batch inserts, described above). In fact, the elapsed time of a large multi-record `addData()` operation using "simple" multi-insert is more than doubled with "refecth" cache sync switched on, with all major databases, and it is significantly more than double on some of them. You can switch off cache sync for an operation by setting the `canSyncCache` flag to `false` on your `OperationBinding`; alternatively, you can switch to `cacheSyncStrategy` "requestValuesPlusSequences" if that is an option for your use case (ie, you do not have database-generated field values, or can live without them). Note, auditing is not possible if cache sync is completely switched off.

    #### Additional notes

    Please note a couple of provisos about batch inserting; since batch insert has a specialized and quite narrow set of use cases, we do not currently plan to remove any of these restrictions
    - It is not supported by all database products. The following databases have been tested and verified to work: MySQL/MariaDB, HSQLDB, Microsoft SQL Server, PostgreSQL Oracle and DB/2. Other databases may work, but we do not guaranteee it
    - It is not properly supported with `SQL templating`. If you try to make use of $valuesClause in a custom querying scenario where batch inserting is in force, you will only get the `valuesClause` applicable to the first valueSet. The same restriction applies to $values references in things like `custom SQL expressions`
    - It does not fully support binary fields. We do support values being sent from the client for fields of type "binary" as Base64-encoded strings, and we also support server-side Java code adding `InputStream` objects to valueSets before the SQL subsystem sees them (for example, by using a `DMI`). However, we do not support upload of real binary files in a multi-record "add" request, primarily because there is no clear way to discern which of the records the uploaded file(s) belong with
    Parameters:
      `newRecord` - new record
    See Also:
      - `Operations Overview`

  - ### addData

    public void addData(Record newRecord, DSCallback callback)
    See Also:
      - `addData(com.smartgwt.client.data.Record)`

  - ### addData

    public void addData(Record newRecord, DSCallback callback, DSRequest requestProperties)
    Perform an "add" DataSource operation against this DataSource, to create a new DataSource record. If a callback was provided, it will be invoked when the operation completes successfully.

    If the operation fails, the callback will not be invoked unless `DSRequest.willHandleError` is true. See the `error handling overview` for more information.

    NOTE: do not use repeated calls to `addData()` to provide the initial dataset for a `clientOnly` DataSource, instead, provide initial data via `cacheData`. Using `addData()` for subsequent, incremental updates from sources like user editing is fine.

    #### Batch inserting

    `addData()` can be passed a `List` of records to insert, rather than a single record. Actual support for this kind of multi-add is entirely dependent on the server-side DataSource implementation; only the built-in `SQLDataSource` has support for multi-add out-of-the-box. If you are using `SQLDataSource` (ie, your dataSource's `serverType` is "sql"), the default behavior of the server when it receives an "add" request with a list of records is to invoke a single-record add on the `DataSource` for each of the records in the provided list.

    However, you can also configure the server to generate a true "batch insert", and this will typically be significantly faster. Instead of generating multiple `INSERT` queries, `SQLDataSource` will generate a single `INSERT` with multiple `VALUES`, like so:

             INSERT INTO myDataSource (field1, field2, field3)
                 VALUES(97, 'test string', 117)
                 VALUES(1, 'Another test', 73)
                 . . .
                 VALUES(8056, 'Final record', 70707)

    Note, the Oracle database product does not support this syntax, so we implement batch insert in a different way - using subselects - with that one database. This difference is transparent from the perspective of a Smart GWT developer, and is only mentioned for completeness.

    Batch inserting can be configured at the `DSRequest`, `DataSource` and `OperationBinding` levels, and it can also be globally configured in `server.properties`. See the `multiInsertStrategy` documentation for details.

    #### Cache Synchronization and Audit

    This optimized batch insert style of multi-record add only supports `cache synchronization` in a limited way, because database products do not provide a reliable way to determine the generated keys of rows inserted in this way. We support cache synchronization of batch-inserted records only when
    - The DataSource does not specify any "sequence" fields, and
    - The `requestValuesPlusSequences` `cacheSyncStrategy` is in force
    We support `automatic audit` of batch-inserted records only when both of the above conditions are true, and the `sql.multi.insert.allowAudit` flag is set to `true` in your `server.properties` file.

    Additionally, be aware that any values missing from the original request data for whatever reason, will also be missing from both the cache-sync data and the audit records.

    "Simple" multi-record add, where each record is added with a discrete INSERT, does fully support cache-sync by default, but you may wish to consider turning it off when adding large numbers of records because the extra cache sync fetches can add significantly to the overall operation time (note, this only applies to the default "refetch" cache-sync strategy, so it does not affect the limited cache sync applicable to optimized batch inserts, described above). In fact, the elapsed time of a large multi-record `addData()` operation using "simple" multi-insert is more than doubled with "refecth" cache sync switched on, with all major databases, and it is significantly more than double on some of them. You can switch off cache sync for an operation by setting the `canSyncCache` flag to `false` on your `OperationBinding`; alternatively, you can switch to `cacheSyncStrategy` "requestValuesPlusSequences" if that is an option for your use case (ie, you do not have database-generated field values, or can live without them). Note, auditing is not possible if cache sync is completely switched off.

    #### Additional notes

    Please note a couple of provisos about batch inserting; since batch insert has a specialized and quite narrow set of use cases, we do not currently plan to remove any of these restrictions
    - It is not supported by all database products. The following databases have been tested and verified to work: MySQL/MariaDB, HSQLDB, Microsoft SQL Server, PostgreSQL Oracle and DB/2. Other databases may work, but we do not guaranteee it
    - It is not properly supported with `SQL templating`. If you try to make use of $valuesClause in a custom querying scenario where batch inserting is in force, you will only get the `valuesClause` applicable to the first valueSet. The same restriction applies to $values references in things like `custom SQL expressions`
    - It does not fully support binary fields. We do support values being sent from the client for fields of type "binary" as Base64-encoded strings, and we also support server-side Java code adding `InputStream` objects to valueSets before the SQL subsystem sees them (for example, by using a `DMI`). However, we do not support upload of real binary files in a multi-record "add" request, primarily because there is no clear way to discern which of the records the uploaded file(s) belong with
    Parameters:
      `newRecord` - new record
      `callback` - Callback to invoke on completion.
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    See Also:
      - `Operations Overview`

  - ### cloneDSRequest

    public DSRequest cloneDSRequest(DSRequest dsRequest)
    Creates a shallow copy of the given `DSRequest`. The request's `data`, if any, is shallow copied in the cloned request.

    The `callback` property of the given request is not copied into the cloned request.

    Parameters:
      `dsRequest` - the DSRequest to clone.
    Returns:
      a clone of the given DSRequest object.
    See Also:
      - `cloneDSResponse(com.smartgwt.client.data.DSResponse)`

  - ### cloneDSResponse

    public DSResponse cloneDSResponse(DSResponse dsResponse)
    Creates a shallow copy of the given `DSResponse`. All properties that would affect the processing of the response are copied into the resulting DSResponse so that the cloned response could substitute for the original response. The response's `data`, if any, is shallow copied in the cloned response.
    Parameters:
      `dsResponse` - the DSResponse to clone.
    Returns:
      a clone of the given DSResponse object.
    See Also:
      - `cloneDSRequest(com.smartgwt.client.data.DSRequest)`

  - ### compareCriteria

    public int compareCriteria(Criteria newCriteria, Criteria oldCriteria)
    Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.

    Comparisons between `AdvancedCriteria` are made via recursively calling `Operator.compareCriteria()` for all criteria involved.

    For simple `Criteria`, by default (`CriteriaPolicy`:"dropOnShortening"), returns:

    - -1 if the new criteria has fewer properties than the old criteria (indicating that it isn't more restrictive)
    - -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
    - -1 if the value for any given property in the old criteria is not an array, and the the value for the same property property in the new criteria is different
    - -1 if both values for a given property are strings and the new criteria value doesn't contain the old criteria value
    - 1 if none of the above are true and, for at least one of the properties, the respective criteria values are both strings, and the old criteria value is a substring of, and is shorter than, the new criteria value
    - 0 otherwise (indicating the sets of criteria are equivalent)

    For (`CriteriaPolicy`:"dropOnChange"), returns:

    - -1 if the two sets of criteria have a different number of properties
    - -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
    - -1 if the value for any given property in the old criteria is not an array, and the the value for the same property in the new criteria is different
    - 0 otherwise (indicating the sets of criteria are equivalent)
    This method is called by `ResultSet.compareCriteria()` to determine whether a change in criteria should cause the cache to be invalidated. You may want to override this method in order to mimic the filtering behavior that your server performs.
    Parameters:
      `newCriteria` - new filter criteria
      `oldCriteria` - previous filter criteria
    Returns:
      0 if the filters are equivalent, 1 if newCriteria is guaranteed more restrictive, and -1 if newCriteria is not guaranteed more restrictive
    See Also:
      - `CriteriaPolicy`

  - ### compareCriteria

    public int compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties)
    See Also:
      - `compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)`

  - ### compareCriteria

    public int compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties, String policy)
    Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.

    Comparisons between `AdvancedCriteria` are made via recursively calling `Operator.compareCriteria()` for all criteria involved.

    For simple `Criteria`, by default (`CriteriaPolicy`:"dropOnShortening"), returns:

    - -1 if the new criteria has fewer properties than the old criteria (indicating that it isn't more restrictive)
    - -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
    - -1 if the value for any given property in the old criteria is not an array, and the the value for the same property property in the new criteria is different
    - -1 if both values for a given property are strings and the new criteria value doesn't contain the old criteria value
    - 1 if none of the above are true and, for at least one of the properties, the respective criteria values are both strings, and the old criteria value is a substring of, and is shorter than, the new criteria value
    - 0 otherwise (indicating the sets of criteria are equivalent)

    For (`CriteriaPolicy`:"dropOnChange"), returns:

    - -1 if the two sets of criteria have a different number of properties
    - -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
    - -1 if the value for any given property in the old criteria is not an array, and the the value for the same property in the new criteria is different
    - 0 otherwise (indicating the sets of criteria are equivalent)
    This method is called by `ResultSet.compareCriteria()` to determine whether a change in criteria should cause the cache to be invalidated. You may want to override this method in order to mimic the filtering behavior that your server performs.
    Parameters:
      `newCriteria` - new filter criteria
      `oldCriteria` - previous filter criteria
      `requestProperties` - dataSource request properties
      `policy` - overrides `CriteriaPolicy`
    Returns:
      0 if the filters are equivalent, 1 if newCriteria is guaranteed more restrictive, and -1 if newCriteria is not guaranteed more restrictive
    See Also:
      - `CriteriaPolicy`

  - ### compareDates

    public int compareDates(Date date1, Date date2, String fieldName)
    Convenience method to compare two Date objects appropriately, depending on whether the passed-in fieldName refers to a field of `type` "datetime" or "date". In the former case, the dates are compared using `DateUtil.compareDates()`; in the latter case, or if the supplied fieldName is null or unknown to this DataSource, the dates are compared using `DateUtil.compareLogicalDates()`.
    Parameters:
      `date1` - First date in comparison
      `date2` - Second date in comparison
      `fieldName` - The name of the field for which the comparison is being run. See `FieldName`
    Returns:
      0 if equal, -1 if first date > second date, 1 if second date > first date

  - ### convertDataSourceCriteria

    public AdvancedCriteria convertDataSourceCriteria(Criteria criteria)
    Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object. This instance method differs from the class method `convertCriteria()` in that it makes use of the dataSource as schema to help in the conversion. For example, this method is able to honor `DataSourceField.ignoreTextMatchStyle` and use the dataSource's `defaultTextMatchStyle` rather than assuming "substring"
    Parameters:
      `criteria` - simple criteria
    Returns:
      equivalent AdvancedCriteria object

  - ### convertDataSourceCriteria

    public AdvancedCriteria convertDataSourceCriteria(Criteria criteria, TextMatchStyle textMatchStyle)
    Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object. This instance method differs from the class method `convertCriteria()` in that it makes use of the dataSource as schema to help in the conversion. For example, this method is able to honor `DataSourceField.ignoreTextMatchStyle` and use the dataSource's `defaultTextMatchStyle` rather than assuming "substring"
    Parameters:
      `criteria` - simple criteria
      `textMatchStyle` - default style of matching text. Defaults to the dataSource's defaultTextMatchStyle
    Returns:
      equivalent AdvancedCriteria object

  - ### convertRelativeDates

    public Criteria convertRelativeDates(Criteria criteria)
    Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.
    Parameters:
      `criteria` - criteria to convert
    Returns:
      new copy of the criteria with all relative dates converted

  - ### convertRelativeDates

    public Criteria convertRelativeDates(Criteria criteria, String timezoneOffset)
    See Also:
      - `convertRelativeDates(com.smartgwt.client.data.Criteria)`

  - ### convertRelativeDates

    public Criteria convertRelativeDates(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek)
    See Also:
      - `convertRelativeDates(com.smartgwt.client.data.Criteria)`

  - ### convertRelativeDates

    public Criteria convertRelativeDates(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek, Date baseDate)
    Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.
    Parameters:
      `criteria` - criteria to convert
      `timezoneOffset` - optional timezone offset. Defaults to the current timezone
      `firstDayOfWeek` - first day of the week (zero is Sunday). Defaults to `DateChooser.firstDayOfWeek`
      `baseDate` - base value for relative conversion - defaults to now
    Returns:
      new copy of the criteria with all relative dates converted

  - ### copyRecords

    public Record[] copyRecords(Record... records)
    Copies all DataSource field values of an (Array) of Records (including a TreeNode) to a new array of Records, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes. This method calls `copyRecord()` for each item in the array.
    Parameters:
      `records` - The array of Record objects to be copied.
    Returns:
      A new copy of each record provided in the array argument, with component-specific metata data removed.

  - ### createAlias

    public void createAlias(String alias)
    Assigns an alias to this DataSource
    Parameters:
      `alias` - The alias assigned to this DataSource.

  - ### addDataChangedHandler

    public HandlerRegistration addDataChangedHandler(DataChangedHandler handler)
    Add a dataChanged handler.

    Notification method fired when a DataSource operation such as an `add`, `remove` or `update` modifies the underlying data for a DataSource.

    This method is used by `ResultSet`s to keep the user-visible data up to date as changes are made.

    Specified by:
      `addDataChangedHandler` in interface `HasDataChangedHandlers`
    Parameters:
      `handler` - the dataChanged handler
    Returns:
      `HandlerRegistration` used to remove this handler

  - ### downloadFile

    public void downloadFile(Record data)
    Download a file stored in a field of type:"binary" in a DataSource record.

    This will trigger the browser's "Save As" dialog and allow the user to save the file associated with some record.

    Note that if this method is called for a record with no associated file, the download URL may not be functional. By default when dataSources encounter a `binary type fields`, an additional field, `<fieldName>_filename`, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to download a file.

    See the overview of `Binary Fields` for more details.

    Parameters:
      `data` - Record to download. Only required to have a value for the primary key field.

  - ### downloadFile

    public void downloadFile(Record data, String fieldName)
    See Also:
      - `downloadFile(com.smartgwt.client.data.Record)`

  - ### downloadFile

    public void downloadFile(Record data, String fieldName, DSRequest requestProperties)
    Download a file stored in a field of type:"binary" in a DataSource record.

    This will trigger the browser's "Save As" dialog and allow the user to save the file associated with some record.

    Note that if this method is called for a record with no associated file, the download URL may not be functional. By default when dataSources encounter a `binary type fields`, an additional field, `<fieldName>_filename`, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to download a file.

    See the overview of `Binary Fields` for more details.

    Parameters:
      `data` - Record to download. Only required to have a value for the primary key field.
      `fieldName` - Optional name of the binary field containing the file. If not provided, the first binary field is used. See `FieldName`
      `requestProperties` - Additional properties to set on the DSRequest that will be issued.

  - ### evaluateCriterion

    public boolean evaluateCriterion(Record record, Criterion criterion)
    Evaluate the given criterion with respect to the passed record.

    Typically called by the `condition` function of a custom `Operator` to evaluate `sub-criteria`.

    Parameters:
      `record` - record to evaluate
      `criterion` - criterion to use
    Returns:
      whether the record meets the supplied `Criterion`
    See Also:
      - `Advanced Filtering`

  - ### execute

    public void execute(DSRequest dsRequest)
    Executes the given DSRequest on this DataSource.

    This method is typically used by a DataSource whose `dataProtocol` is set to `DSProtocol.CLIENTCUSTOM`. Execution of a DSRequest can be delayed, either after a timeout or until some condition is met, by saving the DSRequest object passed to the `transformRequest()` override and calling execute() on the DSRequest at a later time.

    Parameters:
      `dsRequest` - the DSRequest to execute.

  - ### exportData

    public void exportData()
    Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results. See `OperationBinding.exportResults` or `DSRequest.exportResults` and for more information.
    See Also:
      - `Operations Overview`

  - ### exportData

    public void exportData(Criteria criteria)
    See Also:
      - `exportData()`

  - ### exportData

    public void exportData(Criteria criteria, DSRequest requestProperties)
    See Also:
      - `exportData()`

  - ### exportData

    public void exportData(Criteria criteria, DSRequest requestProperties, DSCallback callback)
    Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results. See `OperationBinding.exportResults` or `DSRequest.exportResults` and for more information.
    Parameters:
      `criteria` - search criteria
      `requestProperties` - additional properties to set on the DSRequest that will be issued
      `callback` - callback to invoke on completion. Note that this parameter only applies where `DSRequest.exportToClient` is explicitly set to false, because file downloads do not provide ordinary Smart GWT callbacks
    See Also:
      - `Operations Overview`

  - ### fetchData

    public void fetchData(Criteria criteria)
    See Also:
      - `fetchData(com.smartgwt.client.data.Criteria)`

  - ### fetchData

    public void fetchData(Criteria criteria, DSCallback callback)
    See Also:
      - `fetchData(com.smartgwt.client.data.Criteria)`

  - ### fetchData

    public void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
    Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

    NOTE: do not attempt to override this method to create a custom DataSource. For a server-side custom DataSource, use the `serverConstructor` attribute, and the @see Custom DataSource samples. For a client-side custom DataSource, see `dataProtocol:"custom"`.

    In contrast to `ListGrid.fetchData()`, which creates a `ResultSet` to manage the returned data, calling `dataSource.fetchData()` provides the returned data in the callback as a RecordList or simple Array of Record objects. Calling `dataSource.fetchData()` does not automatically update any visual components or caches: code in the callback passed to `fetchData()` decides what to do with the returned data.

    For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:

             DataSource.get("employees").fetchData(null, new DSCallback() {
                 public void execute(DSResponse response, Object rawData, DSRequest request) {
                     myGrid.setData(response.getData());
                 }
             });

    Unlike calling `myGrid.fetchData()`, which creates a `ResultSet`, the data provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.

    Disconnected datasets may be used to populate various visual components. For example, while an individual FormItem can be configured to fetch `valueMap` options from a DataSource via the `optionDataSource` property, the following code shows storing a dataset to derive valueMaps from later:

               // Assume GlobalStore.allCountries is a public static variable of type RecordList
               DataSource.get("countries").fetchData(null, new DSCallback(){
                  public void execute(DSResponse response, Object rawData, DSRequest request) {
                     GlobalStore.allCountries = response.getDataAsRecordList();
                  }
               });
               ... later, while a DynamicForm is being created ...
               SelectItem select = new SelectItem("country", "Pick Country");
               Map valueMap = GlobalStore.countries.getValueMap("countryId", "countryName");
               myItem.setValueMap(new LinkedHashMap(valueMap));

    You can also create a ResultSet from the data retrieved from `fetchData()`, like so:

             DataSource.get("countries").fetchData(null, new DSCallback() {
                 public void execute(DSResponse response, Object rawData, DSRequest request) {
                     ResultSet rs = new ResultSet(DataSource.get("countries"));
                     rs.setAllRows(response.getData());
                 }
             });

    This gives you a dataset that supports client-side filtering (via `setCriteria()`), can provide `filtered valueMaps`, will `automatically reflect updates` to the DataSource made via other components, and can be re-used with multiple visual components.

    See also `getClientOnlyDataSource()` and `cacheAllData` for similar capabilities for dealing with smaller datasets entirely within the browser, or working with modifiable caches representing subsets of the data available from a DataSource.

    See also the server-side com.isomorphic.js.JSTranslater class in the Java Server Reference for other, similar approaches involving dumping data into the page during initial page load. Note: care should be taken when using this approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets that may become very large.

    Data-Driven Visual Component Creation

    `DataSource.fetchData()` can also be used to create Smart GWT components in a data-driven way. For example, if you had a DataSource "myGridFields" whose fields included the basic properties of `ListGridField` (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:

            DataSource.get("myFormFields").fetchData(null, new DSCallback(){
                public void execute(DSResponse response, Object rawData, DSRequest request) {
                   Record[] records = response.getData();
                   ListGridField[] fields = new ListGridField[records.length];
                   for (Record record in records) {
                       ListGridField field = new ListGridField();
                       field.setName(record.getAttribute("name"));
                       field.setTitle(record.getAttribute("title"));
                       field.setType(ListGridFieldType.valueOf(record.getAttribute("type")));
                   }
                   ListGrid grid = new ListGrid();
                   grid.setFields(fields);
                }
            });

    This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also the server-side API com.isomorphic.datasource.DataSource.addDynamicDSGenerator() for dynamically creating DataSources supporting all server-side DataSource features, and `inheritsFrom` for sharing field definitions across multiple DataSources.
    Parameters:
      `criteria` - search criteria
      `callback` - callback to invoke on completion
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    See Also:
      - `Operations Overview`

  - ### fetchRecord

    public void fetchRecord(Object pkValue)
    Fetch a single record from the DataSource by `primary key`. This simply calls `fetchData()` after creating `Criteria` that contain the primary key field and value.

    If you call this method on a DataSource with a composite primary key - ie, one with multiple primaryKey fields - this method returns the first record where the first defined primary field matches the supplied pkValue; this may or may not be meaningful, depending on your use case. Generally, for DataSources with composite keys, it makes more sense to use `fetchData()` directly, rather than this convenience method.

    Parameters:
      `pkValue` - value for the field marked `primaryKey`:true in this DataSource (or the first field so marked if there is more than one)

  - ### fetchRecord

    public void fetchRecord(Object pkValue, DSCallback callback)
    See Also:
      - `fetchRecord(java.lang.Object)`

  - ### fetchRecord

    public void fetchRecord(Object pkValue, DSCallback callback, DSRequest requestProperties)
    Fetch a single record from the DataSource by `primary key`. This simply calls `fetchData()` after creating `Criteria` that contain the primary key field and value.

    If you call this method on a DataSource with a composite primary key - ie, one with multiple primaryKey fields - this method returns the first record where the first defined primary field matches the supplied pkValue; this may or may not be meaningful, depending on your use case. Generally, for DataSources with composite keys, it makes more sense to use `fetchData()` directly, rather than this convenience method.

    Parameters:
      `pkValue` - value for the field marked `primaryKey`:true in this DataSource (or the first field so marked if there is more than one)
      `callback` - callback to invoke on completion
      `requestProperties` - additional properties to set on the DSRequest that will be issued

  - ### fieldMatchesFilter

    public boolean fieldMatchesFilter(Object fieldValue, Object filterValue)
    Compares a criteria value to a field value and returns whether they match, as follows:
    - any non-String filter value is directly compared (==) to the field value
    - any String filter value is compared according to `DSRequest.textMatchStyle` in the passed `requestProperties`, regardless of the actual field type
    - if the filter value is an Array, the comparison is a logical OR. If textMatchStyle is "exact", it matches if fieldValue (or any of it's entries, if it's also an array) is contained in the filterValue Array. If textMatchStyle if substring, it matches if any of the entries in filterValue appear as a case-insensitive substring of any of the entries in fieldValue.
    - Dates are compared as logical dates if either the field value or the filter value is a logical date. Only if none of them is a logical date they will be compared as standard Dates
    Parameters:
      `fieldValue` - field value to be compared
      `filterValue` - filter value to be compared
    Returns:
      true if the filter and field values match, false otherwise

  - ### fieldMatchesFilter

    public boolean fieldMatchesFilter(Object fieldValue, Object filterValue, DSRequest requestProperties)
    Compares a criteria value to a field value and returns whether they match, as follows:
    - any non-String filter value is directly compared (==) to the field value
    - any String filter value is compared according to `DSRequest.textMatchStyle` in the passed `requestProperties`, regardless of the actual field type
    - if the filter value is an Array, the comparison is a logical OR. If textMatchStyle is "exact", it matches if fieldValue (or any of it's entries, if it's also an array) is contained in the filterValue Array. If textMatchStyle if substring, it matches if any of the entries in filterValue appear as a case-insensitive substring of any of the entries in fieldValue.
    - Dates are compared as logical dates if either the field value or the filter value is a logical date. Only if none of them is a logical date they will be compared as standard Dates
    Parameters:
      `fieldValue` - field value to be compared
      `filterValue` - filter value to be compared
      `requestProperties` - optional dataSource request properties
    Returns:
      true if the filter and field values match, false otherwise

  - ### filterData

    public void filterData()
    Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

    This is identical to `fetchData()` except that `DSRequest.textMatchStyle` is set to "substring" to cause case insensitive substring matching (if the server respects this setting).

    See Also:
      - `Operations Overview`

  - ### filterData

    public void filterData(Criteria criteria)
    See Also:
      - `filterData()`

  - ### filterData

    public void filterData(Criteria criteria, DSCallback callback)
    See Also:
      - `filterData()`

  - ### filterData

    public void filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
    Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

    This is identical to `fetchData()` except that `DSRequest.textMatchStyle` is set to "substring" to cause case insensitive substring matching (if the server respects this setting).

    Parameters:
      `criteria` - search criteria
      `callback` - callback to invoke on completion
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    See Also:
      - `Operations Overview`

  - ### formatFieldValue

    public String formatFieldValue(DataSourceField field, Object value)
    Formats the supplied value using the `SimpleType` derived from the field definition.

    Note that if `DataSourceField.format` is defined for a date, time or numeric-based value, or `DataSourceField.dateFormatter` or `DataSourceField.timeFormatter` is defined for a date or time-based value, that format is given priority and used to format the value rather than the `SimpleType`.

    Parameters:
      `field` - name of the field to use to format value
      `value` - raw value to be formatted
    Returns:
      formatted value or null

  - ### getAllPathsToRelation

    public RelationPath getAllPathsToRelation(String targetDS)
    Returns all known paths between this and the given targetDS.
    Parameters:
      `targetDS` - The DataSource at the relationship's other end.
    Returns:
      Array ofAll known paths between this and the given targetDS.

  - ### getAllPathsToRelation

    public RelationPath getAllPathsToRelation(DataSource targetDS)
    Returns all known paths between this and the given targetDS.
    Parameters:
      `targetDS` - The DataSource at the relationship's other end.
    Returns:
      Array ofAll known paths between this and the given targetDS.

  - ### getClientOnlyDataSource

    public void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback)
    Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that `inheritsFrom` the original DataSource.

    This clientOnly "copy" can be useful in situations where you want to allow a series of local changes without immediately committing to the server. See also `ListGrid.autoSaveEdits` for more fine-grained tracking of edits (eg, special styling for uncommitted changes).

    The new DataSource is returned via the "callback" argument. If `cacheAllData` is enabled and `hasAllData()` returns true, the new DataSource is synchronously returned as the result of the method. In this case, if a callback was passed, it also is executed synchronously.

    Parameters:
      `criteria` - The criteria for the clientOnly DS
      `callback` - The callback to fire passing the clientOnly DS

  - ### getClientOnlyDataSource

    public void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties)
    See Also:
      - `getClientOnlyDataSource(com.smartgwt.client.data.Criteria, com.smartgwt.client.callbacks.ClientOnlyDataSourceCallback)`

  - ### getClientOnlyDataSource

    public void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties, DataSource dataSourceProperties)
    Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that `inheritsFrom` the original DataSource.

    This clientOnly "copy" can be useful in situations where you want to allow a series of local changes without immediately committing to the server. See also `ListGrid.autoSaveEdits` for more fine-grained tracking of edits (eg, special styling for uncommitted changes).

    The new DataSource is returned via the "callback" argument. If `cacheAllData` is enabled and `hasAllData()` returns true, the new DataSource is synchronously returned as the result of the method. In this case, if a callback was passed, it also is executed synchronously.

    Parameters:
      `criteria` - The criteria for the clientOnly DS
      `callback` - The callback to fire passing the clientOnly DS
      `requestProperties` - optional properties to pass through to the DSRequest
      `dataSourceProperties` - optional properties to pass through to the clientOnly DS

  - ### getClientOnlyResponse

    protected DSResponse getClientOnlyResponse(DSRequest request, Record... serverData)
    Return a "spoofed" response for a `clientOnly` or `cacheAllData` DataSource.

    The default implementation will use `cacheData` to provide an appropriate response, by using `client-side filtering` for a "fetch" request, and by modifying the `cacheData` for other requests.

    Override this method to provide simulations of other server-side behavior, such as modifying other records, or to implement synchronous client-side data providers (such as Google Gears). For asynchronous third-party data providers, such as GWT-RPC, HTML5 sockets, or bridges to plug-in based protocols (Java, Flash, Silverlight..), use `dataProtocol:"clientCustom"` instead.

    Overriding this method is also a means of detecting that a normal DataSource (not clientOnly) would be contacting the server.

    Parameters:
      `request` - DataSource request to respond to
      `serverData` - for cacheAllData DataSources, the data from the local cache
    Returns:

  - ### getDefaultPathToRelation

    public RelationPath getDefaultPathToRelation(String targetDS)
    Returns the path having the shortest distance between this and the given targetDS, as determined by `getShortestPathToRelation()`.
    Parameters:
      `targetDS` - The DataSource at the relationship's other end.
    Returns:
      The path having the least number of 1:M relationships from this to the given targetDS.

  - ### getDefaultPathToRelation

    public RelationPath getDefaultPathToRelation(DataSource targetDS)
    Returns the path having the shortest distance between this and the given targetDS, as determined by `getShortestPathToRelation()`.
    Parameters:
      `targetDS` - The DataSource at the relationship's other end.
    Returns:
      The path having the least number of 1:M relationships from this to the given targetDS.

  - ### getDisplayValue

    public Object getDisplayValue(String fieldName, Object value)
    Given a fieldName and a dataValue, apply any `DataSourceField.valueMap` for the field and return the display value for the field
    Parameters:
      `fieldName` - name of the field to retrieve a value for. See `FieldName`
      `value` - data value for the field
    Returns:
      display value for the field

  - ### getFetchDataURL

    public String getFetchDataURL(Criteria criteria)
    Returns a URL to DataSource fetch operation. This API is intended to return media such as images or videos to the browser.

    Note that because the entirety of the request is encoded in the URL, there is an inherent limitation on the amount of data that you can send viat he criteria argument to the server. The actual length depends on your server configuration and other factors such as the size of cookies (if any) being sent to the server and other HTTP headers in use. Conservatively, assume that you have about 2 kilobytes to work with.

    Parameters:
      `criteria` - Criteria to be sent to server.
    Returns:
      a URL that targets the specified fetch operation.

  - ### getFetchDataURL

    public String getFetchDataURL(Criteria criteria, DSRequest requestProperties)
    Returns a URL to DataSource fetch operation. This API is intended to return media such as images or videos to the browser.

    Note that because the entirety of the request is encoded in the URL, there is an inherent limitation on the amount of data that you can send viat he criteria argument to the server. The actual length depends on your server configuration and other factors such as the size of cookies (if any) being sent to the server and other HTTP headers in use. Conservatively, assume that you have about 2 kilobytes to work with.

    Parameters:
      `criteria` - Criteria to be sent to server.
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    Returns:
      a URL that targets the specified fetch operation.

  - ### getField

    public DataSourceField getField(String fieldName)
    Return the field definition object.
    Parameters:
      `fieldName` - Name of the field to retrieve. See `FieldName`
    Returns:
      field object
    See Also:
      - `FieldName`

  - ### getFieldCriterion

    public Criteria getFieldCriterion(Criteria criterion, String fieldName)
    Returns the depth-first match of a criterion matching the given fieldName.
    Parameters:
      `criterion` - the criteria to search
      `fieldName` - the fieldName to find criteria for. See `FieldName`
    Returns:
      the depth-first matching criterion for the passed fieldName

  - ### getFieldDefaultOperator

    public OperatorId[] getFieldDefaultOperator(String field)
    Get the default `OperatorId` for this field.

    By default, if `field.defaultOperator` is set, returns that value, otherwise returns the data-type default from `SimpleType.defaultOperator`.

    Parameters:
      `field` - Field (or field name) to obtain the default operator for
    Returns:
      available Operators
    See Also:
      - `Advanced Filtering`

  - ### getFieldDefaultOperator

    public OperatorId[] getFieldDefaultOperator(DataSourceField field)
    Get the default `OperatorId` for this field.

    By default, if `field.defaultOperator` is set, returns that value, otherwise returns the data-type default from `SimpleType.defaultOperator`.

    Parameters:
      `field` - Field (or field name) to obtain the default operator for
    Returns:
      available Operators
    See Also:
      - `Advanced Filtering`

  - ### getFieldForDataPath

    public DataSourceField getFieldForDataPath(String dataPath)
    Return the field definition object corresponding to the supplied dataPath
    Parameters:
      `dataPath` - dataPath of the field to retrieve
    Returns:
      field object, or null if no field corresponds to the supplied dataPath

  - ### getFieldNames

    public String[] getFieldNames(boolean excludeHidden)
    Retrieves the list of fields declared on this DataSource.
    Parameters:
      `excludeHidden` - If true, returns only those fields that are not marked as hidden
    Returns:
      names of all fields declared on this DataSource

  - ### getFile

    public void getFile(FileSpec fileSpec, GetFileCallback callback)
    Gets the contents of a file stored in this DataSource.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.
      `callback` - Callback executed with the results. The `data` parameter is either a String with the contents of the file, or null to indicate error (such as file not found). You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### getFileURL

    public String getFileURL(Record data)
    Returns a direct URL to access a file stored in a field of type:"binary".

    This URL can be used as the "src" attribute of an Img widget or <img> tag (if the file is an image), or can be used in an ordinary HTML link (<a> tag) to download the file. However, for the latter use case, see also `downloadFile()` and `viewFile()`.

    The URL returned is not to a static file on disk, rather, the returned URL essentially encodes a DSRequest as URL parameters, in a format understood by the IDACall servlet that comes with the Server Framework.

    Hence, this URL will dynamically retrieve whatever file is currently stored in the binary field via executing a normal DSRequest server side. The request will run through normal security checks, so if your application requires authentication, the user must have a valid session and be authorized to access the binary field.

    Note that if this method is called for a record with no associated file, the returned URL may not be functional. By default when dataSources encounter a `binary type fields`, an additional field, `<fieldName>_filename`, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to retrieve a download URL.

    Parameters:
      `data` - Record containing at least the primary key field.
    Returns:
      a URL to directly access the stored file

  - ### getFileURL

    public String getFileURL(Record data, String fieldName)
    See Also:
      - `getFileURL(com.smartgwt.client.data.Record)`

  - ### getFileURL

    public String getFileURL(Record data, String fieldName, DSRequest requestProperties)
    Returns a direct URL to access a file stored in a field of type:"binary".

    This URL can be used as the "src" attribute of an Img widget or <img> tag (if the file is an image), or can be used in an ordinary HTML link (<a> tag) to download the file. However, for the latter use case, see also `downloadFile()` and `viewFile()`.

    The URL returned is not to a static file on disk, rather, the returned URL essentially encodes a DSRequest as URL parameters, in a format understood by the IDACall servlet that comes with the Server Framework.

    Hence, this URL will dynamically retrieve whatever file is currently stored in the binary field via executing a normal DSRequest server side. The request will run through normal security checks, so if your application requires authentication, the user must have a valid session and be authorized to access the binary field.

    Note that if this method is called for a record with no associated file, the returned URL may not be functional. By default when dataSources encounter a `binary type fields`, an additional field, `<fieldName>_filename`, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to retrieve a download URL.

    Parameters:
      `data` - Record containing at least the primary key field.
      `fieldName` - Optional name of the binary field containing the file. If not provided, the first binary field is used. See `FieldName`
      `requestProperties` - Additional properties to set on the DSRequest that will be issued.
    Returns:
      a URL to directly access the stored file

  - ### getFileVersion

    public void getFileVersion(FileSpec fileSpec, Date version, GetFileVersionCallback callback)
    Gets the contents of a particular file version stored in this DataSource.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.
      `version` - A version timestamp. This must exactly match the version timestamp recorded in the DataSource. You can obtain the list of versions for a given file with the `listFileVersions()` API.
      `callback` - Callback executed with the results. The `data` parameter is either a String with the contents of the file, or null to indicate error (such as file not found). You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### getLegalChildTags

    public void getLegalChildTags()
    For a DataSource that describes a DOM structure, the list of legal child elements that can be contained by the element described by this DataSource.

    For a DataSource described by XML schema, this is the list of legal subelements of complexType (elements of simpleType become DataSourceFields with atomic type).

    Note that currently, if an XML schema file contains ordering constraints, DataSources derived from XML Schema do not capture these constraints.

  - ### getPrimaryKeyField

    public DataSourceField getPrimaryKeyField()
    Returns a pointer to the primaryKey field for this DataSource. If this dataSource has a composite primary key (ie, multiple primaryKey fields), returns just the first primaryKey field.
    Returns:
      primary key field object
    See Also:
      - `getPrimaryKeyFields()`

  - ### getPrimaryKeyFieldName

    public String getPrimaryKeyFieldName()
    Returns the primary key fieldName for this DataSource. If this dataSource has a composite primary key (ie, multiple primaryKey fields), returns just the first primaryKey field name.
    Returns:
      primary key field name
    See Also:
      - `getPrimaryKeyFieldNames()`

  - ### getPrimaryKeyFieldNames

    public String[] getPrimaryKeyFieldNames()
    Returns a list of the names of this DataSource's `primaryKey` fields.
    Returns:
      The list of the names of this datasource's primaryKey fields
    See Also:
      - `getPrimaryKeyFields()`

  - ### getPrimaryKeyFields

    public Record getPrimaryKeyFields()
    Returns this DataSource's `primaryKey` fields as a map of fieldName to field.
    Returns:
      Javascript object containing all this datasource's primaryKey fields, as a map of field name to field
    See Also:
      - `getPrimaryKeyField()`
      - `getPrimaryKeyFieldNames()`

  - ### getShortestPathToRelation

    public RelationPath getShortestPathToRelation(String targetDS)
    Returns the path having the shortest distance between this and the given targetDS. In case of a tie, only the first as determined by depth-first search is returned.
    Parameters:
      `targetDS` - The DataSource at the relationship's other end.
    Returns:
      The path having the least number of 1:M relationships from this to the given targetDS.

  - ### getShortestPathToRelation

    public RelationPath getShortestPathToRelation(DataSource targetDS)
    Returns the path having the shortest distance between this and the given targetDS. In case of a tie, only the first as determined by depth-first search is returned.
    Parameters:
      `targetDS` - The DataSource at the relationship's other end.
    Returns:
      The path having the least number of 1:M relationships from this to the given targetDS.

  - ### getTypeOperators

    public OperatorId[] getTypeOperators()
    Get the list of `OperatorId`s available on this DataSource for the given `FieldType`.

    If `setTypeOperators()` has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for the `FieldType` as specified by `SimpleType.validOperators`, otherwise, the system-wide set of valid operators for the type as registered via `addSearchOperator()`.

    Returns:
      available Operators
    See Also:
      - `Advanced Filtering`

  - ### getTypeOperators

    public OperatorId[] getTypeOperators(FieldType typeName)
    Get the list of `OperatorId`s available on this DataSource for the given `FieldType`.

    If `setTypeOperators()` has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for the `FieldType` as specified by `SimpleType.validOperators`, otherwise, the system-wide set of valid operators for the type as registered via `addSearchOperator()`.

    Parameters:
      `typeName` - Defaults to "text" if not passed.
    Returns:
      available Operators
    See Also:
      - `Advanced Filtering`

  - ### getTypeOperators

    public OperatorId[] getTypeOperators(String typeName)
    Get the list of `OperatorId`s available on this DataSource for the given `FieldType`.

    If `setTypeOperators()` has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for the `FieldType` as specified by `SimpleType.validOperators`, otherwise, the system-wide set of valid operators for the type as registered via `addSearchOperator()`.

    Parameters:
      `typeName` - Defaults to "text" if not passed.
    Returns:
      available Operators
    See Also:
      - `Advanced Filtering`

  - ### setHandleErrorCallback

    public void setHandleErrorCallback(HandleErrorCallback callback)
    If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other than `STATUS_SUCCESS`. You can use this hook to do DataSource-specific error handling. Unless you call `ErrorEvent.cancel()`, `HandleErrorCallback.handleError()` will be called by Smart GWT right after this method completes.
    Parameters:
      `callback` - HandleErrorCallback the callback to set.
    See Also:
      - `HandleErrorCallback.handleError(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest)`

  - ### addHandleErrorHandler

    public HandlerRegistration addHandleErrorHandler(HandleErrorHandler handler)
    Add a handleError handler.

    If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other than `STATUS_SUCCESS`. You can use this hook to do DataSource-specific error handling. Unless you call `ErrorEvent.cancel()`, `HandleErrorCallback.handleError()` will be called by Smart GWT right after this method completes.

    Specified by:
      `addHandleErrorHandler` in interface `HasHandleErrorHandlers`
    Parameters:
      `handler` - the handleError handler
    Returns:
      `HandlerRegistration` used to remove this handler

  - ### hasAllData

    public Boolean hasAllData()
    When `cacheAllData` is true, has all the data been retrieved to the client?
    Returns:
      All data has been fetched from the server and is available client-side

  - ### hasCustomTypeOperators

    public void hasCustomTypeOperators(String typeName)
    Returns true if the operator list for the passed type has been customized via a call to `setTypeOperators()`.
    Parameters:
      `typeName` -
    See Also:
      - `Advanced Filtering`

  - ### hasCustomTypeOperators

    public void hasCustomTypeOperators(FieldType typeName)
    Returns true if the operator list for the passed type has been customized via a call to `setTypeOperators()`.
    Parameters:
      `typeName` -
    See Also:
      - `Advanced Filtering`

  - ### hasFile

    public void hasFile(FileSpec fileSpec, HasFileCallback callback)
    Indicates whether a file exists in this DataSource.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType or fileFormat are not provided, will indicate whether any file with the provided fileName exists.
      `callback` - Callback executed with the results. The `data` parameter is a boolean indicating whether the file is present. You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### hasFileVersion

    public void hasFileVersion(FileSpec fileSpec, Date version, HasFileCallback callback)
    Indicates whether a particular file version exists in this DataSource.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType or fileFormat are not provided, will indicate whether any file with the provided fileName exists.
      `version` - A version timestamp. This must exactly match the version timestamp recorded in the DataSource for `hasFileVersion` to return true. Note, you can obtain the list of versions for a given file with the `listFileVersions()` API.
      `callback` - Callback executed with the results. The `data` parameter is a boolean indicating whether the file version is present. You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### invalidateCache

    public void invalidateCache()
    Drop the current dataSource cache. This has two effects:
    - For DataSources `cacheAllData` or `clientOnly`, discard the current client-side cache data.
    - If `notify` is passed, cause all `data objects` associated with this dataSource to drop their caches. This occurs regardless of the dataSource type - and can be thought of as equivalent to processing a response with `DSResponse.invalidateCache` set.

  - ### invalidateCache

    public void invalidateCache(boolean notify)
    Drop the current dataSource cache. This has two effects:
    - For DataSources `cacheAllData` or `clientOnly`, discard the current client-side cache data.
    - If `notify` is passed, cause all `data objects` associated with this dataSource to drop their caches. This occurs regardless of the dataSource type - and can be thought of as equivalent to processing a response with `DSResponse.invalidateCache` set.
    Parameters:
      `notify` - Should data objects associated with this dataSource have their cache invalidated?

  - ### isCalculated

    public boolean isCalculated(DataSourceField field)
    Does the specified field have its value dynamically calculated via `DataSourceField.formula` or other similar attributes?

    This method will return true for fields with the following attributes:

    - `DataSourceField.formula`
    - `DataSourceField.template`
    - `DataSourceField.customSelectExpression`
    Or if the field has explicitly been marked as `calculated:true`.
    Parameters:
      `field` - Field or fieldName
    Returns:
      true if this is a field with dynamically calculated values

  - ### isCalculated

    public boolean isCalculated(String field)
    Does the specified field have its value dynamically calculated via `DataSourceField.formula` or other similar attributes?

    This method will return true for fields with the following attributes:

    - `DataSourceField.formula`
    - `DataSourceField.template`
    - `DataSourceField.customSelectExpression`
    Or if the field has explicitly been marked as `calculated:true`.
    Parameters:
      `field` - Field or fieldName
    Returns:
      true if this is a field with dynamically calculated values

  - ### listFiles

    public void listFiles(Criteria criteria, DSCallback callback)
    Get a list of files from the DataSource. Note, if `automatic file versioning` is switched on for the dataSource, the resulting list contains only the most recent version of each file.
    Parameters:
      `criteria` - Criteria to apply. References to `fileName`, `fileType` and `fileFormat` fields will be translated to the native field names configured for this DataSource.
      `callback` - Callback executed with the results. The `data` parameter is either an array of records, or null to indicate an error. The records will have the ``fileName``, ``fileType``, ``fileFormat``, ``fileLastModified``, and ``fileVersion`` fields populated, but not the ``fileContents`` field. (You can use `getFile()` to get the `fileContents`). You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `listFileVersions(com.smartgwt.client.data.FileSpec, com.smartgwt.client.data.DSCallback)`
      - `FileSource Operations`

  - ### listFileVersions

    public void listFileVersions(FileSpec fileSpec, DSCallback callback)
    Get the list of a given file's versions from the dataSource, sorted in version order (most recent version first). If the dataSource does not specify a `fileVersionField`, this API will return an error
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.
      `callback` - Callback executed with the results. The `data` parameter is either an array of records, or null to indicate an error. The records will have the ``fileName``, ``fileType``, ``fileFormat``, ``fileLastModified`` and ``fileVersion`` fields populated, but not the ``fileContents`` field. (You can use `getFileVersion()` to get the `fileContents`). You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### performCustomOperation

    public void performCustomOperation(String operationId)
    Invoke an operation declared with `OperationBinding.operationType` "custom".

    This is a rarely used API. If the operation you are performing can be thought of as one of the standard "CRUD" `operation types`, declare it with a CRUD operationType. For example, if your operation updates a record, declare it with operationType "update" and invoke it via `updateData()` - this will cause `cache sync` to work correctly.

    In particular:

    - do not use this API just because you need to add additional server-side logic to a CRUD operation (DMI allows this)
    - do not use this API to implement variants of core CRUD operations (`DSRequest.operationId` is the correct way to do this)
    - do not use this API just because an operation affects more than one record. Most kinds of multi-record operations should use `queuing`. However, a custom operation is appropriate for genuine "batch" updates, as opposed to just a number of ordinary updates by primaryKey - see `OperationBinding.allowMultiUpdate`
    - do not use this API just because you are calling a stored procedure in SQL - if the stored procedure performs some kind of CRUD operation on the records of this DataSource, use a standard CRUD operationType

    Instead, the specific purpose of this API is to bypass all checks and side effects that normally occur for CRUD operations, for example, that a "fetch" requires valid Criteria or that an "update" or "remove" operation contains a valid primary key, or that an "add" operation returns the newly added record. `performCustomOperation` allows you to pass an arbitrary Record to the server, act on it with custom code, and return arbitray results or even no results.

    The "data" parameter becomes `dsRequest.data`. With the Smart GWT Server Framework, the data is accessible server-side via DSRequest.getValues() and in `Velocity templates` (such as <customSQL>) as $values.

    Note that with SQLDataSource, `performCustomOperation` must be used if you plan to have a <customSQL> tag in your operationBinding that will execute SQL operations other than SELECT, UPDATE, INSERT, DELETE (such as creating a new table). By declaring `OperationBinding.operationType` "custom" in your .ds.xml file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.

    Parameters:
      `operationId` - the operation ID
    See Also:
      - `Operations Overview`

  - ### performCustomOperation

    public void performCustomOperation(String operationId, Record data)
    See Also:
      - `performCustomOperation(java.lang.String)`

  - ### performCustomOperation

    public void performCustomOperation(String operationId, Record data, DSCallback callback)
    See Also:
      - `performCustomOperation(java.lang.String)`

  - ### performCustomOperation

    public void performCustomOperation(String operationId, Record data, DSCallback callback, DSRequest requestProperties)
    Invoke an operation declared with `OperationBinding.operationType` "custom".

    This is a rarely used API. If the operation you are performing can be thought of as one of the standard "CRUD" `operation types`, declare it with a CRUD operationType. For example, if your operation updates a record, declare it with operationType "update" and invoke it via `updateData()` - this will cause `cache sync` to work correctly.

    In particular:

    - do not use this API just because you need to add additional server-side logic to a CRUD operation (DMI allows this)
    - do not use this API to implement variants of core CRUD operations (`DSRequest.operationId` is the correct way to do this)
    - do not use this API just because an operation affects more than one record. Most kinds of multi-record operations should use `queuing`. However, a custom operation is appropriate for genuine "batch" updates, as opposed to just a number of ordinary updates by primaryKey - see `OperationBinding.allowMultiUpdate`
    - do not use this API just because you are calling a stored procedure in SQL - if the stored procedure performs some kind of CRUD operation on the records of this DataSource, use a standard CRUD operationType

    Instead, the specific purpose of this API is to bypass all checks and side effects that normally occur for CRUD operations, for example, that a "fetch" requires valid Criteria or that an "update" or "remove" operation contains a valid primary key, or that an "add" operation returns the newly added record. `performCustomOperation` allows you to pass an arbitrary Record to the server, act on it with custom code, and return arbitray results or even no results.

    The "data" parameter becomes `dsRequest.data`. With the Smart GWT Server Framework, the data is accessible server-side via DSRequest.getValues() and in `Velocity templates` (such as <customSQL>) as $values.

    Note that with SQLDataSource, `performCustomOperation` must be used if you plan to have a <customSQL> tag in your operationBinding that will execute SQL operations other than SELECT, UPDATE, INSERT, DELETE (such as creating a new table). By declaring `OperationBinding.operationType` "custom" in your .ds.xml file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.

    Parameters:
      `operationId` - the operation ID
      `data` - data to pass to the server.
      `callback` - callback to invoke on completion
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    See Also:
      - `Operations Overview`

  - ### processResponse

    public void processResponse(String requestId, DSResponse dsResponse)
    Process a dsResponse for a request initiated by a DataSource with `dataProtocol:"clientCustom"`. `requestId` parameter should be dsRequest.requestId as found on the dsRequest passed to `transformRequest()`.

    You must provide a response for both error and non-error cases. For an error case, a sufficient response is:

          { status : -1 }

    Parameters:
      `requestId` - requestId attribute from the associated dataSource request object
      `dsResponse` - Configuration for the dsResponse

  - ### recordsAreEqual

    public boolean recordsAreEqual(Object record1, Object record2)
    Convenience method to test if two records are equal. Testing is done only for the fields defined in the DataSource, anything else is ignored.
    Parameters:
      `record1` - record to be compared against.
      `record2` - record to be compared.
    Returns:
      true if the records are equal, false otherwise.

  - ### recordsAsText

    public String recordsAsText(Record[] records)
    Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).

    In addition to the `settings` parameter for this method, `DataSourceField.exportForceText` can be set.

    If two or more different text exports are needed for the same DataSource creating a conflict for any DataSourceField setting, `inheritsFrom` can be used to create a child DataSource where these settings can be changed without recapitulating all field definitions.

    Parameters:
      `records` - records to convert
    Returns:
      records as CSV/TSV (separator can be specified)

  - ### recordsAsText

    public String recordsAsText(Record[] records, TextExportSettings settings)
    Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).

    In addition to the `settings` parameter for this method, `DataSourceField.exportForceText` can be set.

    If two or more different text exports are needed for the same DataSource creating a conflict for any DataSourceField setting, `inheritsFrom` can be used to create a child DataSource where these settings can be changed without recapitulating all field definitions.

    Parameters:
      `records` - records to convert
      `settings` - settings for the export
    Returns:
      records as CSV/TSV (separator can be specified)

  - ### recordsFromText

    public Record[] recordsFromText(String text)
    Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.

    If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.

    Parameters:
      `text` - records as CSV/TSV (separator can be specified)
    Returns:
      records derived from TSV

  - ### recordsFromText

    public Record[] recordsFromText(String text, TextImportSettings settings)
    Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.

    If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.

    Parameters:
      `text` - records as CSV/TSV (separator can be specified)
      `settings` - optional settings for the import
    Returns:
      records derived from TSV

  - ### removeData

    public void removeData(Record data)
    Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.

    If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless `DSRequest.willHandleError` is true. See the `error handling overview` for more information.

    Parameters:
      `data` - primary key values of record to delete, (or complete record)
    See Also:
      - `Operations Overview`

  - ### removeData

    public void removeData(Record data, DSCallback callback)
    See Also:
      - `removeData(com.smartgwt.client.data.Record)`

  - ### removeData

    public void removeData(Record data, DSCallback callback, DSRequest requestProperties)
    Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.

    If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless `DSRequest.willHandleError` is true. See the `error handling overview` for more information.

    Parameters:
      `data` - primary key values of record to delete, (or complete record)
      `callback` - callback to invoke on completion
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    See Also:
      - `Operations Overview`

  - ### removeFile

    public void removeFile(FileSpec fileSpec)
    Remove a file stored in this DataSource. Note, if `automatic file versioning` is switched on for the dataSource, all versions of the file are removed (to remove an individual file version, use the `removeFileVersion()` API).
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending the configuration of the DataSource, the fileType and fileFormat may be optional.
    See Also:
      - `FileSource Operations`

  - ### removeFile

    public void removeFile(String fileSpec)
    Remove a file stored in this DataSource. Note, if `automatic file versioning` is switched on for the dataSource, all versions of the file are removed (to remove an individual file version, use the `removeFileVersion()` API).
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending the configuration of the DataSource, the fileType and fileFormat may be optional.
    See Also:
      - `FileSource Operations`

  - ### removeFile

    public void removeFile(FileSpec fileSpec, DSCallback callback)
    Remove a file stored in this DataSource. Note, if `automatic file versioning` is switched on for the dataSource, all versions of the file are removed (to remove an individual file version, use the `removeFileVersion()` API).
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending the configuration of the DataSource, the fileType and fileFormat may be optional.
      `callback` - Callback executed with the results. The `data` parameter is either an array of records represening the removed file(s), or null to indicate an error. The records will have their `fileName` fields and `fileType` fields populated, but not the `fileContents` field. You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### removeFileVersion

    public void removeFileVersion(FileSpec fileSpec, Date version)
    Remove a particular file version stored in this DataSource. Any other versions of the file are left untouched.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.
      `version` - A version timestamp. This must exactly match the version timestamp recorded in the DataSource. You can obtain the list of versions for a given file with the `listFileVersions()` API.
    See Also:
      - `FileSource Operations`

  - ### removeFileVersion

    public void removeFileVersion(FileSpec fileSpec, Date version, DSCallback callback)
    Remove a particular file version stored in this DataSource. Any other versions of the file are left untouched.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.
      `version` - A version timestamp. This must exactly match the version timestamp recorded in the DataSource. You can obtain the list of versions for a given file with the `listFileVersions()` API.
      `callback` - Callback executed with the results. The `data` parameter is either a record representing the removed file version, or null to indicate an error. The record will have its ``fileName``, ``fileType``, ``fileFormat``, ``fileLastModified``, and ``fileVersion`` fields populated, but not the ``fileContents`` field. You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### renameFile

    public void renameFile(FileSpec oldFileSpec, FileSpec newFileSpec)
    Rename a file stored in this DataSource. Note, if `automatic file versioning` is switched on for the dataSource, all versions of the file are renamed.
    Parameters:
      `oldFileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat of the file to rename. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.
      `newFileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat to rename the file to. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If the fileType or fileFormat are not provided, then they will not be changed.
    See Also:
      - `FileSource Operations`

  - ### renameFile

    public void renameFile(FileSpec oldFileSpec, FileSpec newFileSpec, DSCallback callback)
    Rename a file stored in this DataSource. Note, if `automatic file versioning` is switched on for the dataSource, all versions of the file are renamed.
    Parameters:
      `oldFileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat of the file to rename. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.
      `newFileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat to rename the file to. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If the fileType or fileFormat are not provided, then they will not be changed.
      `callback` - Callback executed with the results. The `data` parameter is either an array of records represening the renamed file(s), or null to indicate an error. The records will have their `fileName` fields and `fileType` fields populated, but not the `fileContents` field. You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### saveFile

    public void saveFile(FileSpec fileSpec, String contents)
    Save a file to the DataSource.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.
      `contents` - The contents of the file
    See Also:
      - `FileSource Operations`

  - ### saveFile

    public void saveFile(FileSpec fileSpec, String contents, DSCallback callback)
    Save a file to the DataSource.
    Parameters:
      `fileSpec` - Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.
      `contents` - The contents of the file
      `callback` - Callback executed with the results. The `data` parameter is either a record represening the new file, or null to indicate an error. The record will have its `fileName`, `fileType` and `fileFormat` field populated, but not the `fileContents` field. You can examine ``dsResponse.status`` and ``dsResponse.data`` for additional information about any error.
    See Also:
      - `FileSource Operations`

  - ### setTypeOperators

    public void setTypeOperators(FieldType typeName, OperatorId[] operators)
    Set the list of `OperatorId`s valid for a given FieldType.
    Parameters:
      `typeName` -
      `operators` - available Operators
    See Also:
      - `Advanced Filtering`

  - ### splitCriteria

    public Criteria splitCriteria(Criteria criteria, String[] fields)
    Split a criteria apart based on `fields`.

    This method will take a simple or `Advanced` criteria object and extract the subcriteria that apply to the specified array of fields. If passed an AdvancedCriteria, the criteria should be `flat` and the outer operator must be `"and"`.

    A new criteria object is returned with any criteria applicable to the specified fields. The passed `criteria` is then modified to remove these fields resulting in two distinct criteria.

    To avoid modifying an original criteria, use `copyCriteria()` to make a copy to be passed in.

    By default the field-specific criteria returned will be in simple criteria format even if the criteria passed in was Advanced. Developers may suppress this conversion by passing in the `preserveAdvanced` parameter. Note that not every `criterion operator` can be converted to a simple format. This method will only to convert field level criterion with operators that correspond to one of the available `textMatchStyle` options - namely `"equals"`, `"iEquals"` `"iContains"` or `"startsWith"`.

    This method will return an empty criteria object if it was unable to split the specified criteria by the specified fields.

    Parameters:
      `criteria` - criteria to be split. May be modified if criteria is extracted.
      `fields` - list of fields to extract from criteria
    Returns:
      extracted criteria

  - ### splitCriteria

    public Criteria splitCriteria(Criteria criteria, String[] fields, Boolean preserveAdvanced)
    Split a criteria apart based on `fields`.

    This method will take a simple or `Advanced` criteria object and extract the subcriteria that apply to the specified array of fields. If passed an AdvancedCriteria, the criteria should be `flat` and the outer operator must be `"and"`.

    A new criteria object is returned with any criteria applicable to the specified fields. The passed `criteria` is then modified to remove these fields resulting in two distinct criteria.

    To avoid modifying an original criteria, use `copyCriteria()` to make a copy to be passed in.

    By default the field-specific criteria returned will be in simple criteria format even if the criteria passed in was Advanced. Developers may suppress this conversion by passing in the `preserveAdvanced` parameter. Note that not every `criterion operator` can be converted to a simple format. This method will only to convert field level criterion with operators that correspond to one of the available `textMatchStyle` options - namely `"equals"`, `"iEquals"` `"iContains"` or `"startsWith"`.

    This method will return an empty criteria object if it was unable to split the specified criteria by the specified fields.

    Parameters:
      `criteria` - criteria to be split. May be modified if criteria is extracted.
      `fields` - list of fields to extract from criteria
      `preserveAdvanced` - If passed an AdvancedCriteria, should the returned field-specific split criteria object also be an AdvancedCriteria.
    Returns:
      extracted criteria

  - ### supportsAdvancedCriteria

    public Boolean supportsAdvancedCriteria()
    Do fetch and filter operations on this dataSource support being passed `AdvancedCriteria`?

    For a DataSource to support being passed AdvancedCriteria, it must be `clientOnly:true` or `cacheAllData:true`, or have server side logic which can process AdvancedCriteria objects passed from the client.

    AdvancedCriteria are supported on the server for standard `SQL`, `Hibernate` and `JPA` DataSources in Smart GWT Enterprise or Power editions (not supported in Smart GWT Pro).

    The framework assumes that custom dataSources support AdvancedCriteria; if you have a a custom DataSource implementation that does not support AdvancedCriteria, you can set the `allowAdvancedCriteria` property to false.

    Returns:
      true if this dataSource supports being passed AdvancedCriteria in fetch and filter type operations, false otherwise.

  - ### supportsDynamicTreeJoins

    public Boolean supportsDynamicTreeJoins()
    This method returns true for dataSources that support both self-joins and `additionalOutputs`. A "self-join" is a relation from a dataSource back to itself - for example a relation between a worker and his manager, both of whom are Employees. DataSources that can handle self-joins are able to create and navigate these relations, which are mostly useful for tree-type structures.

    Out of the box, only the built-in `SQL DataSource` implementation supports self-joins, and thus dynamic tree joins; neither `clientOnly` nor the other server-side built-in DataSource implementations support them. If you create a custom DataSource implementation that can handle both of these features, you can set the `allowDynamicTreeJoins` flag to true, which will cause supportsDynamicTreeJoins() to return true (and equally, you can set that flag explicitly to false to prevent the system from using dynamic tree joins for a given dataSource, even if it is able to use them)

    This method is called by the automatic `ResultTree.keepParentsOnFilter` algorithm to decide if it is possible to use self-referencing `additionalOutputs` to improve efficiency, and possibly performance.

    Returns:
      true if this dataSource supports both `additionalOutputs` and self-joins, otherwise false

  - ### supportsTextMatchStyle

    public void supportsTextMatchStyle(TextMatchStyle textMatchStyle)
    Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.
    Parameters:
      `textMatchStyle` - textMatchStyle to check. If passed a null value, assume an exact match is being requested.

  - ### transformRequest

    protected Object transformRequest(DSRequest dsRequest)
    For a dataSource using `client-side data integration`, return the data that should be sent to the `dataURL`.

    By default, HTTP requests sent to non-Smart GWT servers do not include DSRequest metadata such as `DSRequest.startRow`, `endRow`, and `oldValues`. Only the core `datasource protocol data` is sent, such as the criteria passed to `fetchData()` or the updated values submitted by `form.saveData()`.

    transformRequest() allows you to transform dsRequest metadata into a format understood by your server and include it in the HTTP request, so that you can integrate DataSource features such as data paging with servers that support such features.

    How the data is actually sent to the URL is controlled by `OperationBinding.dataProtocol`. If using the "getParams" or "postParams" protocol, data is expected to be a JavaScript Object where each property will become a GET or POST'd parameter. If using dataProtocol:"soap" or "postXML", data will be serialized as an XML message by `xmlSerialize()`.

    As an example, if you have a dataURL that can return paged data given URL parameters "start" and "end", you could implement transformRequest like so:

               @Override
               protected Object transformRequest (DSRequest dsRequest) {
                   JavaScriptObject data = dsRequest.getData();
                   if (dsRequest.getOperationType () == DSOperationType.FETCH) {
                       JSOHelper.setAttribute (data, "start", dsRequest.getStartRow());
                       JSOHelper.setAttribute (data, "end", dsRequest.getEndRow());
                   }
                   return data;
               }

    Other reasons to implement transformRequest():
    - transform a `Criteria` object into the custom query language of a web service
    - add a session id to requests that require authentication
    - detect colliding updates by sending both updated values and the values the user originally retrieved before editing began (available as `DSRequest.oldValues`)
    Special case: If the `dataProtocol` is `"clientCustom"` the Smart GWT system will not attempt to send data to the server in any way. Instead transformRequest should be implemented such that it accesses or updates the underlying data-set and calls `processResponse()` when the operation is complete. This setting allows straightforward integration with non Smart GWT comm mechanisms that directly send requests to the server (such as GWT-RPC), or handle data manipulation without sending HTTP at all (such as Google Gears).
    Developers should not generate a response for a request and call `processResponse()` synchronously from within `transformRequest` as this can lead to unpredictable results. If you're integrating with a synchronous data provider or able to process requests synchronously from data in browser memory, we'd recommend using a `clientOnly dataSource` with a custom `getClientOnlyResponse()` implementation instead.

    A `transformRequest` override may also be used to set the `DSRequest.dataProtocol` to clientCustom at runtime, giving developers a way to intercept normal handling for some particular request, and provide entirely custom handling written on the client.

    Note: The `RestDataSource` class overrides transformRequest() to handle xml-serializing the request (including meta data) into a standard format.

    Parameters:
      `dsRequest` - the DSRequest being processed
    Returns:
      data to be sent to the dataURL

  - ### transformResponse

    protected void transformResponse(DSResponse dsResponse, DSRequest dsRequest, Object data)
    Modify the DSResponse object derived from the response returned from the `dataURL`.

    This is an override point that makes it possible to use DataSource features such as paging with web services that support such features, by allowing you to fill in metadata fields in the DSResponse object (such as `DSResponse.startRow`) based on service-specific metadata fields contained in the service's response.

    The DSResponse passed to this method already has `DSResponse.data`, which is derived differently depending on the `dataFormat` setting:

    - `dataFormat:"xml"` : either the `recordXPath` or `recordName` is used to select the XML elements that represent DataSource records. The selected XML elements are passed to `recordsFromXML()`, which transforms the XML elements to typed JavaScript data using the DataSource as a schema.
    - `dataFormat:"json"` : the `recordXPath`, if specified, is used to select records from the returned JSON data via `XMLTools.selectObjects()`. `DataSourceField.valueXPath` is used to derive correctly typed field values.
    - `dataFormat:"custom"` : `dsResponse.data` is the raw response in String form. It must be parsed into an Array of Objects for subsequent processing to work.

    In addition to `dsResponse.data`, `DSResponse.status` is defaulted to 0 (indicating no error), and `DSResponse.startRow` is assumed to be zero, with `endRow` and `totalRows` both set to `dsResponse.data.length - 1`, that is, the returned data is assumed to be all records that matched the filter criteria.

    Examples of using this API include:

    - setting `startRow`, `endRow` and `totalRows` to allow paging for a service that supports it. For example, if an XML service returns a "resultRow" tag that contained the row number of the first row of the returned results:

                 dsResponse.setStartRow(XMLTools.selectNumber(xmlData, "//resultRow"));

    - setting `DSResponse.status` to recognized ISC error values based on service-specific errors, in order to trigger standard ISC error handling. For example, setting `dsResponse.status` to `STATUS_VALIDATION_ERROR` and filling in `DSResponse.errors` in order to cause validation errors to be shown in forms and grids.
    - for services that either do not return cache update data, or return partial data, using `DSRequest.oldValues` to create cache update data (whether this is appropriate is application-specific), or setting `DSResponse.invalidateCache`.

    NOTE: this method is NOT an appropriate time to call methods on visual components such as grids, initiate new DSRequests or RPCRequests, or in general do anything other than fill in fields on the DSResponse based on data that is already available. Any actions that need to be taken as a result of the web service response should be implemented exactly as for a DataSource where `transformResponse()` has not been overridden, that is, use the callback passed to high-level methods such as ``grid.fetchData()``, and do error handling via either `DataSource.handleError()` or by setting `willHandleError`.

    Parameters:
      `dsResponse` - default DSResponse derived from the response data
      `dsRequest` - DSRequest object that initiated this request
      `data` - XML document or JSON objects returned by the web service

  - ### updateCaches

    public void updateCaches(DSResponse dsResponse)
    Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed. This will cause cache managers such as `ResultSet` or `ResultTree` to automatically update their caches, and components using such cache managers to visually update to show modified data.

    This API should be used when you have found out about changes made by other users or by automatic processes. For example, using the Smart GWT Messaging system to receive real-time updates via HTTP streaming, you may get updates that should affect a ListGrid which is using a ResultSet to view a portion of a large dataset.

    See the `ConcurrentEdits` overview for more on handling concurrent edits in Smart GWT DataSources.

    The provided `DSResponse` should have `operationType` "update", "add" or "remove" - there is no way for a "fetch" response to meaningfully update arbitrary caches. However, if you have a list of updated records (possibly retrieved via `fetchData()`) you can still call `updateCaches()`with DSResponses of type "update". Typically DataSource operations that manipulate data operate on a single record at a time, but if you explicitly set the `response.data` attribute to an array of records, framework code will handle this as it would multiple updates.

    Example usage: if you had a ListGrid bound to the `supplyItem` sample DataSource, and that ListGrid was showing a Record with `itemId` 23, and you wanted to update the `unitCost` field to a new value, you would use the following code:
    `// updatedRecord is the record we want to update
    Record record = supplyItemDS.copyRecord(updatedRecord);
    record.setAttribute("unitCost", 500);
    DSResponse dsResponse = new DSResponse();
    dsResponse.setData(record);
    dsResponse.setOperationType(DSOperationType.UPDATE);
    supplyItemDS.updateCaches(dsResponse);
    `

    To cause all components that have cache managers to drop their caches, provide a DSResponse with `DSResponse.invalidateCache` set.

    As an alternative to calling `updateCaches()` directly, if updates to other DataSources occur as a result of server-side logic, you can use the server-side API DSResponse.addRelatedUpdate(DSResponse) (Pro Edition and above), which ultimately calls `updateCaches()` for you - see that method's documentation for details.

    NOTE: if `updateCaches` is called for a `clientOnly` DataSource, it will update `cacheData` synchronously in addition to notifying all cache managers as normal.

    If a DataSource has `cacheAllData` set and a full cache has been obtained, calling `updateCaches` will automatically update the cache.

    Note that the DSResponse provided to this method will not go through `transformResponse()` or other processing that would normally occur for a DSResponse resulting from a DSRequest sent by the application in this page.

    Parameters:
      `dsResponse` - the provided DSResponse must minimally have dataSource, operationType, and data set

  - ### updateCaches

    public void updateCaches(DSResponse dsResponse, DSRequest dsRequest)
    Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed. This will cause cache managers such as `ResultSet` or `ResultTree` to automatically update their caches, and components using such cache managers to visually update to show modified data.

    This API should be used when you have found out about changes made by other users or by automatic processes. For example, using the Smart GWT Messaging system to receive real-time updates via HTTP streaming, you may get updates that should affect a ListGrid which is using a ResultSet to view a portion of a large dataset.

    See the `ConcurrentEdits` overview for more on handling concurrent edits in Smart GWT DataSources.

    The provided `DSResponse` should have `operationType` "update", "add" or "remove" - there is no way for a "fetch" response to meaningfully update arbitrary caches. However, if you have a list of updated records (possibly retrieved via `fetchData()`) you can still call `updateCaches()`with DSResponses of type "update". Typically DataSource operations that manipulate data operate on a single record at a time, but if you explicitly set the `response.data` attribute to an array of records, framework code will handle this as it would multiple updates.

    Example usage: if you had a ListGrid bound to the `supplyItem` sample DataSource, and that ListGrid was showing a Record with `itemId` 23, and you wanted to update the `unitCost` field to a new value, you would use the following code:
    `// updatedRecord is the record we want to update
    Record record = supplyItemDS.copyRecord(updatedRecord);
    record.setAttribute("unitCost", 500);
    DSResponse dsResponse = new DSResponse();
    dsResponse.setData(record);
    dsResponse.setOperationType(DSOperationType.UPDATE);
    supplyItemDS.updateCaches(dsResponse);
    `

    To cause all components that have cache managers to drop their caches, provide a DSResponse with `DSResponse.invalidateCache` set.

    As an alternative to calling `updateCaches()` directly, if updates to other DataSources occur as a result of server-side logic, you can use the server-side API DSResponse.addRelatedUpdate(DSResponse) (Pro Edition and above), which ultimately calls `updateCaches()` for you - see that method's documentation for details.

    NOTE: if `updateCaches` is called for a `clientOnly` DataSource, it will update `cacheData` synchronously in addition to notifying all cache managers as normal.

    If a DataSource has `cacheAllData` set and a full cache has been obtained, calling `updateCaches` will automatically update the cache.

    Note that the DSResponse provided to this method will not go through `transformResponse()` or other processing that would normally occur for a DSResponse resulting from a DSRequest sent by the application in this page.

    Parameters:
      `dsResponse` - the provided DSResponse must minimally have dataSource, operationType, and data set
      `dsRequest` - optional dsRequest. If not specified, a DSRequest will be automatically created based on the DataSource and operationType of the DSResponse

  - ### updateData

    public void updateData(Record updatedRecord)
    Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.

    If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless `DSRequest.willHandleError` is true. See the `error handling overview` for more information.

    Parameters:
      `updatedRecord` - updated record
    See Also:
      - `Operations Overview`

  - ### updateData

    public void updateData(Record updatedRecord, DSCallback callback)
    See Also:
      - `updateData(com.smartgwt.client.data.Record)`

  - ### updateData

    public void updateData(Record updatedRecord, DSCallback callback, DSRequest requestProperties)
    Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.

    If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless `DSRequest.willHandleError` is true. See the `error handling overview` for more information.

    Parameters:
      `updatedRecord` - updated record
      `callback` - callback to invoke on completion
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    See Also:
      - `Operations Overview`

  - ### validateData

    public void validateData(Record values)
    Contacts the server to run server-side validation on a DSRequest and either returns `DSResponse.errors` validation errors or a `DSResponse.status` code of 0.

    A "validate" dsRequest is effectively always `RPCRequest.willHandleError`:true. It is a normal condition for a "validate" DSResponse to have validation errors and the response will never go to system-wide handling for unexpected errors (`HandleErrorCallback.handleError()`).

    Parameters:
      `values` - record values to validate
    See Also:
      - `Operations Overview`

  - ### validateData

    public void validateData(Record values, DSCallback callback)
    See Also:
      - `validateData(com.smartgwt.client.data.Record)`

  - ### validateData

    public void validateData(Record values, DSCallback callback, DSRequest requestProperties)
    Contacts the server to run server-side validation on a DSRequest and either returns `DSResponse.errors` validation errors or a `DSResponse.status` code of 0.

    A "validate" dsRequest is effectively always `RPCRequest.willHandleError`:true. It is a normal condition for a "validate" DSResponse to have validation errors and the response will never go to system-wide handling for unexpected errors (`HandleErrorCallback.handleError()`).

    Parameters:
      `values` - record values to validate
      `callback` - callback to invoke on completion
      `requestProperties` - additional properties to set on the DSRequest that will be issued
    See Also:
      - `Operations Overview`

  - ### viewFile

    public void viewFile(Record data)
    Display a file stored in a field of type:"binary" in a new browser window.

    This will open a new browser window to show the file. Depending on the file type, the user's installed plugins and applications, and the user's browser settings, this may cause the file to be actually displayed in the new browser window, or may prompt the user to either launch an external application to view the file or save the file to disk.

    Note that if this method is called for a record with no associated file, the target window's new URL may not be functional. By default when dataSources encounter a `binary type fields`, an additional field, `<fieldName>_filename`, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to view a file.

    See the overview of `Binary Fields` for details.

    Parameters:
      `data` - Record to download. Only required to have a value for the primary key field.

  - ### viewFile

    public void viewFile(Record data, String fieldName)
    See Also:
      - `viewFile(com.smartgwt.client.data.Record)`

  - ### viewFile

    public void viewFile(Record data, String fieldName, DSRequest requestProperties)
    Display a file stored in a field of type:"binary" in a new browser window.

    This will open a new browser window to show the file. Depending on the file type, the user's installed plugins and applications, and the user's browser settings, this may cause the file to be actually displayed in the new browser window, or may prompt the user to either launch an external application to view the file or save the file to disk.

    Note that if this method is called for a record with no associated file, the target window's new URL may not be functional. By default when dataSources encounter a `binary type fields`, an additional field, `<fieldName>_filename`, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to view a file.

    See the overview of `Binary Fields` for details.

    Parameters:
      `data` - Record to download. Only required to have a value for the primary key field.
      `fieldName` - Optional name of the binary field containing the file. If not provided, the first binary field is used. See `FieldName`
      `requestProperties` - Additional properties to set on the DSRequest that will be issued.

  - ### canFlattenCriteria

    public static boolean canFlattenCriteria(AdvancedCriteria criteria)
    Returns true if calling `flattenCriteria()` on the passed criteria would produce logically equivalent criteria.
    Parameters:
      `criteria` - the AdvancedCriteria to check for flatness
    Returns:
      true if criteria can be flattened without logical change

  - ### combineCriteria

    public static Criteria combineCriteria(Criteria criteria1, Criteria criteria2)
    Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator". Note that the combined criteria object will be an AdvancedCriteria unless:
    - both input criteria objects are simple, and
    - the "outerOperator" is "and", and
    - there is no collision of key names on the two criteria
    Parameters:
      `criteria1` - first criteria object
      `criteria2` - second criteria object
    Returns:
      The combined criteria
    See Also:
      - Dynamic Reporting Example

  - ### combineCriteria

    public static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator)
    See Also:
      - `combineCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)`

  - ### combineCriteria

    public static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator, TextMatchStyle textMatchStyle)
    Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator". Note that the combined criteria object will be an AdvancedCriteria unless:
    - both input criteria objects are simple, and
    - the "outerOperator" is "and", and
    - there is no collision of key names on the two criteria
    Parameters:
      `criteria1` - first criteria object
      `criteria2` - second criteria object
      `outerOperator` - operator to use to combine the criteria. Defaults to "and"
      `textMatchStyle` - style of matching text, if it is necessary to convert a simple criteria object to an AdvancedCriteria. Defaults to "substring"
    Returns:
      The combined criteria
    See Also:
      - Dynamic Reporting Example

  - ### convertCriteria

    public static AdvancedCriteria convertCriteria(Criteria criteria)
    Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
    Parameters:
      `criteria` - simple criteria
    Returns:
      equivalent AdvancedCriteria object

  - ### convertCriteria

    public static AdvancedCriteria convertCriteria(Criteria criteria, TextMatchStyle textMatchStyle)
    Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
    Parameters:
      `criteria` - simple criteria
      `textMatchStyle` - default style of matching text. Defaults to "substring"
    Returns:
      equivalent AdvancedCriteria object

  - ### copyCriteria

    public static Criteria copyCriteria(Criteria criteria)
    Create a copy of a criteria.
    Parameters:
      `criteria` - criteria to copy
    Returns:
      copy of criteria

  - ### flattenCriteria

    public static AdvancedCriteria flattenCriteria(AdvancedCriteria criteria)
    Returns new criteria that has at most one top-level LogicalOperator ("and" or "or"). This new criteria will be considered "flat" by `isFlatCriteria()`.

    Not all AdvancedCriteria can be flattened and remain logically equivalent. When criteria will be logically modified by flattening, all criteria that appear anywhere in the AdvancedCriteria structure will appear under a single top-level operator, which will be the same top-level operator as the passed AdvancedCriteria.

    For example, given criteria like this (in the JSON representation of AdvancedCriteria):

               { operator: "and", criteria: [
                  { fieldName: "continent", operator: "equals", value: "Europe"},
                  { operator: "or", criteria: [
                     { fieldName: "countryName", operator: "iEndsWith", value: "land"},
                     { fieldName: "population", operator: "lessThan", value: 3000000}
                  ]}
                 ]
               }

    The returned criteria would be:

               { operator: "and", criteria: [
                  { fieldName: "continent", operator: "equals", value: "Europe"},
                  { fieldName: "countryName", operator: "iEndsWith", value: "land"},
                  { fieldName: "population", operator: "lessThan", value: 3000000}
                ]}

    This returned criteria is not logically equivalent to the passed criteria - the "iEndsWith" and "lessThan" criteria that were formerly nested under a logical "or" operator must now both be satisfied instead of either being satisfied. You can use `canFlattenCriteria()` to detect whether an AdvancedCriteria is going to be changed by `flattenCriteria()`.

    Because the returned criteria may not be logically equivalent, `flattenCriteria` should not be used as a means of simplifying criteria to make server implementation easier or anything of the kind. The primary purpose of returning logically different criteria is to enable an end user to switch from an interface for editing nested criteria to an interface that can't handle nested criteria and convert the criteria while preserving as much as possible.

    Parameters:
      `criteria` - the AdvancedCriteria to flatten
    Returns:
      flattened criteria

  - ### getAdvancedCriteriaDescription

    public static String getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource)
    Returns a human-readable string describing the clauses in this advanced criteria or criterion.
    Parameters:
      `criteria` - Criteria to convert to a readable string
      `dataSource` - DataSource to provide definitions of operators
    Returns:
      Human-readable string describing the clauses in the passed criteria

  - ### getAdvancedCriteriaDescription

    public static String getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource, CriteriaOutputSettings criteriaOutputSettings)
    Returns a human-readable string describing the clauses in this advanced criteria or criterion.
    Parameters:
      `criteria` - Criteria to convert to a readable string
      `dataSource` - DataSource to provide definitions of operators
      `criteriaOutputSettings` - optional configuration settings for the output
    Returns:
      Human-readable string describing the clauses in the passed criteria

  - ### getAggregationDescription

    public static String getAggregationDescription(AdvancedCriterionSubquery subquery, DataSource dataSource)
    Returns a human-readable string describing the aggregation properties in the request: `DSRequest.groupBy` and `DSRequest.summaryFunctions`.
    Parameters:
      `subquery` - Subquery with aggregation to convert to a readable string
      `dataSource` - DataSource to provide field properties
    Returns:
      Human-readable string describing the aggregation in the passed request

  - ### getDataSource

    public static DataSource getDataSource(String ID)
    Lookup a DataSource by ID.
    Parameters:
      `ID` - DataSource ID. See `GlobalId`
    Returns:
      the DataSource with this ID, if loaded, otherwise null.
    See Also:
      - `GlobalId`

  - ### getLoaderURL

    public static String getLoaderURL()
    Returns the `loaderURL`
    Returns:
      The loaderURL

  - ### getSortBy

    public static String[] getSortBy(SortSpecifier[] sortSpecifiers)
    Given an array of `SortSpecifier`s, return a simple list of Strings in the format expected by `DSRequest.sortBy`.
    Parameters:
      `sortSpecifiers` - The list of specifiers to return in sortBy format
    Returns:
      An array of sort-definitions in the format expected by `DSRequest.sortBy`

  - ### getSortSpecifiers

    public static SortSpecifier[] getSortSpecifiers(String[] sortBy)
    Return an array of `SortSpecifier`s, given an array of Strings in the format expected by `DSRequest.sortBy`.
    Parameters:
      `sortBy` - A list of sortBy strings in the format expected by `DSRequest.sortBy`
    Returns:
      An array of `SortSpecifier`s equivalent to the passed in string array

  - ### getSortSpecifiers

    public static SortSpecifier[] getSortSpecifiers(String[] sortBy, DataSource context)
    Return an array of `SortSpecifier`s, given an array of Strings in the format expected by `DSRequest.sortBy`.
    Parameters:
      `sortBy` - A list of sortBy strings in the format expected by `DSRequest.sortBy`
      `context` - Context dataSource or component.
    Returns:
      An array of `SortSpecifier`s equivalent to the passed in string array

  - ### hasCustomTypeOperators

    public static void hasCustomTypeOperators(String typeName, DataSource ds)
    Returns true if the operator list for the passed type has been customized via a call to `setTypeOperators()`.
    Parameters:
      `typeName` -
      `ds` -
    See Also:
      - `Advanced Filtering`

  - ### isAdvancedCriteria

    public static Boolean isAdvancedCriteria(Criteria criteria)
    Determines whether the passed criteria object is AdvancedCriteria or simple criteria.

    Criteria with an explicit `_constructor: "AdvancedCriteria"` property are always recognized as AdvancedCriteria. For criteria without this marker, heuristics are used to detect AdvancedCriteria based on properties like `fieldName`, `operator`, and `value`.

    When a `dataSource` is provided, additional validation is performed - a criterion with just a `fieldName` (no operator or value) is treated as AdvancedCriteria shorthand if that fieldName is a valid field on the DataSource. This supports the ruleScope shorthand format where `{fieldName: "someField"}` means "someField equals true".

    Without a DataSource, a criteria object must have a valid `operator` to be detected as AdvancedCriteria (unless explicitly marked with `_constructor`). This ensures that simple property-matching objects like `{fieldName: "X"}` used in Array.find() are not incorrectly treated as AdvancedCriteria.

    Parameters:
      `criteria` - the criteria object to examine
    Returns:
      true if the criteria is AdvancedCriteria, false otherwise
    See Also:
      - `isAdvancedCriteria(com.smartgwt.client.data.Criteria)`

  - ### isAdvancedCriteria

    public static Boolean isAdvancedCriteria(Criteria criteria, DataSource dataSource)
    Determines whether the passed criteria object is AdvancedCriteria or simple criteria.

    Criteria with an explicit `_constructor: "AdvancedCriteria"` property are always recognized as AdvancedCriteria. For criteria without this marker, heuristics are used to detect AdvancedCriteria based on properties like `fieldName`, `operator`, and `value`.

    When a `dataSource` is provided, additional validation is performed - a criterion with just a `fieldName` (no operator or value) is treated as AdvancedCriteria shorthand if that fieldName is a valid field on the DataSource. This supports the ruleScope shorthand format where `{fieldName: "someField"}` means "someField equals true".

    Without a DataSource, a criteria object must have a valid `operator` to be detected as AdvancedCriteria (unless explicitly marked with `_constructor`). This ensures that simple property-matching objects like `{fieldName: "X"}` used in Array.find() are not incorrectly treated as AdvancedCriteria.

    Parameters:
      `criteria` - the criteria object to examine
      `dataSource` - optional DataSource (or DataSource ID) for additional field validation
    Returns:
      true if the criteria is AdvancedCriteria, false otherwise
    See Also:
      - `isAdvancedCriteria(com.smartgwt.client.data.Criteria)`

  - ### isFlatCriteria

    public static boolean isFlatCriteria(AdvancedCriteria criteria)
    Returns true if a given AdvancedCriteria is "flat." That is, the criteria consists of either:
    - a top-level "and" or "or" `Criterion`, where none of the `subcriteria` use `logical operators`, hence have no subcriteria of their own
    - a single Criterion that is not a logical operator, hence has no subcriteria
    Parameters:
      `criteria` - the AdvancedCriteria to check for flatness
    Returns:
      true if criteria is flat

  - ### load

    public static void load(String dsID, Function callback)
    Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. The callback is passed a single parameter, the `dsID` list passed into the method. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired immediately.

    To force reloading of DataSources that have already been loaded, pass `true` for the forceReload parameter. Note that if a DataSource has been created locally with the specified ID, even if this is a `MockDataSource`, the `forceReload` parameter will be required to force the "real" dataSource to be loaded.

    Parameters:
      `dsID` - DataSource ID or Array of DataSource IDs
      `callback` - Callback to fire after DataSource loading completes

  - ### load

    public static void load(String dsID, Function callback, boolean forceReload)
    Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. The callback is passed a single parameter, the `dsID` list passed into the method. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired immediately.

    To force reloading of DataSources that have already been loaded, pass `true` for the forceReload parameter. Note that if a DataSource has been created locally with the specified ID, even if this is a `MockDataSource`, the `forceReload` parameter will be required to force the "real" dataSource to be loaded.

    Parameters:
      `dsID` - DataSource ID or Array of DataSource IDs
      `callback` - Callback to fire after DataSource loading completes
      `forceReload` - Forcibly reload a dataSource if it's already loaded

  - ### loadWithParents

    public static void loadWithParents(String dsID, Function callback)
    Variation of `load()` that will also automatically load any DataSources that the requested DataSources inherit from (via `inheritsFrom`).

    If the parent DataSource is already loaded, calling `loadWithParents` will not automatically reload them unless the forceReload parameter is passed.

    Parameters:
      `dsID` - DataSource ID or Array of DataSource IDs
      `callback` - Callback to fire after DataSource loading completes

  - ### loadWithParents

    public static void loadWithParents(String dsID, Function callback, boolean forceReload)
    Variation of `load()` that will also automatically load any DataSources that the requested DataSources inherit from (via `inheritsFrom`).

    If the parent DataSource is already loaded, calling `loadWithParents` will not automatically reload them unless the forceReload parameter is passed.

    Parameters:
      `dsID` - DataSource ID or Array of DataSource IDs
      `callback` - Callback to fire after DataSource loading completes
      `forceReload` - Forcibly reload a dataSource if it's already loaded

  - ### makeFileSpec

    public static FileSpec makeFileSpec(String path)
    Converts a file path to a `FileSpec`.
    Parameters:
      `path` - The path to convert, e.g. "employees.ds.xml"
    Returns:
      The equivalent FileSpec, e.g. {fileName: "employees", fileType: "ds", fileFormat: xml"}

  - ### setLoaderURL

    public static void setLoaderURL(String url)
    Sets the URL where the DataSourceLoader servlet has been installed; this is used by the `load()` method. Note, one reason you may wish to modify the loader URL is to include a Cross-Site Request Forgery (CSRF) token, as described `here`
    Parameters:
      `url` - The new loaderURL

  - ### setTypeOperators

    public static void setTypeOperators(String typeName, OperatorId[] operators)
    Set the list of valid `OperatorId`s for a given FieldType.
    Parameters:
      `typeName` -
      `operators` - available Operators
    See Also:
      - `Advanced Filtering`

  - ### verifyDataSourcePair

    public static Map[] verifyDataSourcePair(DataSource live, DataSource mock)
    A utility that checks for discrepancies between any two DataSources, typically used to warn about issues commonly found during the Reify design / development cycle, and logs its findings to the console. Similar to the server-side ReifyDataSourceValidator in scope, but with no support for server-only attributes (e.g., Declarative Security).

    INFO level messages are logged when any of the following conditions are discovered:

    - A field defined in "live" is not also present in mock
    - A field defined in "live" has a different title than mock (fields using i18n titles are not checked)
    WARN level messages are logged when any of the following conditions are discovered:
    - A field defined in mock is not also present in "live"
    - A field defined in mock has a different type than in live (and the live type is a not a sub-type of the mock type)
    - Fields in mock have a different order than in "live" (after ignoring any fields that mock lacks)

    Parameters:
      `live` - DataSource to compare using 'live' rules
      `mock` - DataSource to compare using 'mock' rules
    Returns:
      Each message logged, with its fieldName & severity level

  - ### setDefaultProperties

    public static void setDefaultProperties(DataSource dataSourceProperties)
    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:
      `dataSourceProperties` - properties that should be used as new defaults when instances of this class are created
    See Also:
      - `SGWTProperties`

  - ### onInit

    protected void onInit()
    Overrides:
      `onInit` in class `BaseClass`

  - ### registerID

    protected void registerID(String id, boolean skipUniqueJSIdentifierCheck)
    Overrides:
      `registerID` in class `BaseClass`

  - ### setID

    public DataSource setID(String id)
    Overrides:
      `setID` in class `BaseClass`

  - ### setAddGlobalId

    public void setAddGlobalId(Boolean addGlobalId) throws IllegalStateException
    Whether to make this DataSource available as a global variable for convenience.

    Note : This is an advanced setting

    Parameters:
      `addGlobalId` - addGlobalId Default value is true
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getAddGlobalId

    public Boolean getAddGlobalId()
    Whether to make this DataSource available as a global variable for convenience.
    Returns:
      Boolean

  - ### setDataProtocol

    public DataSource setDataProtocol(DSProtocol dataProtocol) throws IllegalStateException
    Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. May be overridden for individual request types using `dataProtocol`}
    Parameters:
      `dataProtocol` - dataProtocol Default value is null
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### setDefaultParams

    public void setDefaultParams(Map defaultParams)
    HTTP parameters that should be submitted with every DSRequest.
    Useful for authenticated services that require a sessionId with every request.
    Can be set for all operations of a given DataSource as DataSource.defaultParams.
    Parameters:
      `defaultParams` - the default params

  - ### getDefaultParams

    public Map getDefaultParams()
    HTTP parameters that should be submitted with every DSRequest.
    Useful for authenticated services that require a sessionId with every request.
    Can be set for all operations of a given DataSource as DataSource.defaultParams.
    Returns:
      the default params

  - ### getDataProtocol

    public DSProtocol getDataProtocol()
    Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. May be overridden for individual request types using `dataProtocol`}
    Returns:
      DSDataProtocol

  - ### get

    public static DataSource get(String ID)
    Synonym of `DataSource.getDataSource`: Lookup a DataSource by ID.
    Parameters:
      `ID` - DataSource ID
    Returns:
      the DataSource with this ID, if loaded, otherwise null.

  - ### get

    public static DataSource get(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)
    Synonym of `DataSource.getDataSource`: Lookup a DataSource by ID.
    Parameters:
      `ID` - DataSource ID
      `requestTransformer` - the request transformer. Pass null to use the default transform
      `responseTransformer` - the response transformer. Pass null to use the default transform
    Returns:
      the DataSource with this ID, if loaded, otherwise null.

  - ### getDataSource

    public static DataSource getDataSource(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)
    Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer. The RequestTransformer and ResponseTransformer parameters provide the equivalent functionality of overriding `transformRequest(DSRequest)` and `transformResponse(DSResponse, DSRequest, Object)` when instantiating a DataSource on the client. However when obtaining a DataSource instance from the server using this API, `transformRequest(DSRequest)` and `transformResponse(DSResponse, DSRequest, Object)` cannot be overridden and so the requestTransformer and responseTransformer parameters can be passed instead.
    Parameters:
      `ID` - DataSource ID
      `requestTransformer` - the request transformer. Pass null to use the default transform
      `responseTransformer` - the response transformer. Pass null to use the default transform
    Returns:
      the DataSource with this ID, if loaded, otherwise null.

  - ### useOfflineResponse

    protected boolean useOfflineResponse(DSRequest dsRequest, DSResponse dsResponse)
    Override point to allow application code to suppress use of a particular offline response. For example, application code may wish to examine the response's `offlineTimestamp` to make a decision about whether the response is too stale to be useful.

    This is an application override point only; there is no default implementation.

    Note: This is an override point

    Parameters:
      `dsRequest` - The dsRequest object
      `dsResponse` - The corresponding dsResponse object returned from offline cache
    Returns:
      true to allow this response to be used, false to prevent it

  - ### isCreated

    public boolean isCreated()
    Overrides:
      `isCreated` in class `BaseClass`

  - ### getJsObj

    public JavaScriptObject getJsObj()
    Overrides:
      `getJsObj` in class `BaseClass`

  - ### setInheritsFrom

    public void setInheritsFrom(DataSource inheritsFrom) throws IllegalStateException
    ID of another DataSource this DataSource inherits its DataSource fields from.
    Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields. Fields with the same name are merged in the same way that databound component fields are merged with DataSource fields.
    The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can set `useParentFieldOrder` to instead use the parent's field order, with new local fields appearing last.

    You can set `showLocalFieldsOnly` to have all non-local fields hidden.
    Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other via `inheritsFrom`
    This feature can be used for creating a customized view (eg, only certain fields shown) which will be used bymultiple databound components.adding presentation-specific attributes to metadata that has been automatically derived from `XMLTools.loadXMLSchema(String, XSDLoadCallback)` or other metadata formats modelling object subclassing and extension in server-side code and storage systems modelling relational database joins, and the equivalents in other systems creating hooks for others to customize your application in a maintainable way. For example, if you have a dataSource "employee", you can create a dataSource"customizedEmployee" which inherits from "employee" but does not initially define anyfields, and bind all databound components to"customizedEmployee". Customizations of fields (including appearance changes, fieldorder, new fields, hiding of fields, and custom validation rules) can be added to"customizedEmployee", so that they are kept separtely from the original field data and have the best possible chance of working with future versions of the "employee"dataSource.
    Parameters:
      `inheritsFrom` - the datasource to inherit from
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### setFields

    public void setFields(DataSourceField... fields) throws IllegalStateException
    The list of fields that compose records from this DataSource.

    Each DataSource field can have type, user-visible title, validators, and other metadata attached.

    Parameters:
      `fields` - fields Default value is null
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### addField

    public void addField(DataSourceField field) throws IllegalStateException
    Add a field to the DataSource
    Parameters:
      `field` - the datasource field
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getFields

    public DataSourceField[] getFields()
    The list of fields that compose records from this DataSource.

    Each DataSource field can have type, user-visible title, validators, and other metadata attached.

    Returns:
      array of DataSourceFields

  - ### xmlSerialize

    public String xmlSerialize(JavaScriptObject data)
    Serialize a JavaScript object as XML.&#010

    &#010 The JavaScript Object passed to `xmlSerialize(com.google.gwt.core.client.JavaScriptObject)` becomes an XML&#010 element named after the `tagName` (or `ID` if&#010 tagName is unset). Each property of the object becomes a subElement. For example,&#010 using a DataSource to serialize like this:&#010

              DSRequest inputObject = new DSRequest();
              inputObject.setStartRow(5);
              inputObject.setEndRow(50);

              Record records[] = new Record[2];
              records[0] = new Record();
              records[0].setAttribute("field1", "value1");
              records[0].setAttribute("field2", new Date());
              records[1] = new Record();
              records[1].setAttribute("field1", "value3");
              records[1].setAttribute("field2", (String)null);

              inputObject.setAttribute("data", records);

              DataSource myDS = new DataSource();
              myDS.setTagName("DSRequest");
              myDS.xmlSerialize(inputObject.getJsObj());

    &#010 .. produces the following XML:&#010

        &#010     <DSRequest>&#010         <startRow>5</startRow>&#010         <endRow>50</endRow>&#010         <data>&#010             <field1>value1</field1>&#010             <field2>2005-10-14T18:01:16</field2>&#010         </data>&#010         <data>&#010             <field1>value3</field1>&#010             <field2></field2>&#010         </data>&#010     </DSRequest>&#010

    &#010

    &#010 If you are working with a WSDL-described web service, XML serialization is performed&#010 automatically by APIs like `WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)` - you only need to&#010 know about serialization in order to understand how to put together JavaScript data that&#010 will fill in an XML message properly. &#010
    &#010 Note: when trying to send data to a web service, it is best to avoid putting&#010 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP&#010 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding&#010 Web Service messages are very complex and are subject to change with new versions of the&#010 web service you are contacting, whereas the data itself is easy to manipulate and less&#010 likely to change.&#010
    &#010 To troubleshoot message formation, you can set the log category "xmlComm" to &#010 `DEBUG` level in order to see the XML message formed by Smart GWT reported&#010 in log statements in the Developer Console.&#010&#010

    Parameters:
      `data` - data to be serialized
    Returns:
      data as serialized to XML

  - ### xmlSerialize

    public String xmlSerialize(JavaScriptObject data, SerializationContext flags)
    Serialize a JavaScript object as XML.&#010

    &#010 The JavaScript Object passed to `xmlSerialize(com.google.gwt.core.client.JavaScriptObject)` becomes an XML&#010 element named after the `tagName` (or `ID` if&#010 tagName is unset). Each property of the object becomes a subElement. For example,&#010 using a DataSource to serialize like this:&#010

              DSRequest inputObject = new DSRequest();
              inputObject.setStartRow(5);
              inputObject.setEndRow(50);

              Record records[] = new Record[2];
              records[0] = new Record();
              records[0].setAttribute("field1", "value1");
              records[0].setAttribute("field2", new Date());
              records[1] = new Record();
              records[1].setAttribute("field1", "value3");
              records[1].setAttribute("field2", (String)null);

              inputObject.setAttribute("data", records);

              DataSource myDS = new DataSource();
              myDS.setTagName("DSRequest");
              myDS.xmlSerialize(inputObject.getJsObj());

    &#010 .. produces the following XML:&#010

        &#010     <DSRequest>&#010         <startRow>5</startRow>&#010         <endRow>50</endRow>&#010         <data>&#010             <field1>value1</field1>&#010             <field2>2005-10-14T18:01:16</field2>&#010         </data>&#010         <data>&#010             <field1>value3</field1>&#010             <field2></field2>&#010         </data>&#010     </DSRequest>&#010

    &#010

    &#010 If you are working with a WSDL-described web service, XML serialization is performed&#010 automatically by APIs like `WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)` - you only need to&#010 know about serialization in order to understand how to put together JavaScript data that&#010 will fill in an XML message properly. &#010
    &#010 Note: when trying to send data to a web service, it is best to avoid putting&#010 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP&#010 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding&#010 Web Service messages are very complex and are subject to change with new versions of the&#010 web service you are contacting, whereas the data itself is easy to manipulate and less&#010 likely to change.&#010
    &#010 To troubleshoot message formation, you can set the log category "xmlComm" to &#010 `DEBUG` level in order to see the XML message formed by Smart GWT reported&#010 in log statements in the Developer Console.&#010&#010

    Parameters:
      `data` - data to be serialized
      `flags` - options for the serialization engine
    Returns:
      data as serialized to XML

  - ### xmlSerialize

    public String xmlSerialize(Record data, SerializationContext flags)
    Serialize a JavaScript object as XML.&#010

    &#010 The JavaScript Object passed to `xmlSerialize(com.google.gwt.core.client.JavaScriptObject)` becomes an XML&#010 element named after the `tagName` (or `ID` if&#010 tagName is unset). Each property of the object becomes a subElement. For example,&#010 using a DataSource to serialize like this:&#010

              DSRequest inputObject = new DSRequest();
              inputObject.setStartRow(5);
              inputObject.setEndRow(50);

              Record records[] = new Record[2];
              records[0] = new Record();
              records[0].setAttribute("field1", "value1");
              records[0].setAttribute("field2", new Date());
              records[1] = new Record();
              records[1].setAttribute("field1", "value3");
              records[1].setAttribute("field2", (String)null);

              inputObject.setAttribute("data", records);

              DataSource myDS = new DataSource();
              myDS.setTagName("DSRequest");
              myDS.xmlSerialize(inputObject.getJsObj());

    &#010 .. produces the following XML:&#010

        &#010     <DSRequest>&#010         <startRow>5</startRow>&#010         <endRow>50</endRow>&#010         <data>&#010             <field1>value1</field1>&#010             <field2>2005-10-14T18:01:16</field2>&#010         </data>&#010         <data>&#010             <field1>value3</field1>&#010             <field2></field2>&#010         </data>&#010     </DSRequest>&#010

    &#010

    &#010 If you are working with a WSDL-described web service, XML serialization is performed&#010 automatically by APIs like `WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)` - you only need to&#010 know about serialization in order to understand how to put together JavaScript data that&#010 will fill in an XML message properly. &#010
    &#010 Note: when trying to send data to a web service, it is best to avoid putting&#010 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP&#010 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding&#010 Web Service messages are very complex and are subject to change with new versions of the&#010 web service you are contacting, whereas the data itself is easy to manipulate and less&#010 likely to change.&#010
    &#010 To troubleshoot message formation, you can set the log category "xmlComm" to &#010 `DEBUG` level in order to see the XML message formed by Smart GWT reported&#010 in log statements in the Developer Console.&#010&#010

    Parameters:
      `data` - data to be serialized
      `flags` - options for the serialization engine
    Returns:
      data as serialized to XML

  - ### xmlSerialize

    public String xmlSerialize(Record[] data, SerializationContext flags)
    Serialize a JavaScript object as XML.&#010

    &#010 The JavaScript Object passed to `xmlSerialize(com.google.gwt.core.client.JavaScriptObject)` becomes an XML&#010 element named after the `tagName` (or `ID` if&#010 tagName is unset). Each property of the object becomes a subElement. For example,&#010 using a DataSource to serialize like this:&#010

              DSRequest inputObject = new DSRequest();
              inputObject.setStartRow(5);
              inputObject.setEndRow(50);

              Record records[] = new Record[2];
              records[0] = new Record();
              records[0].setAttribute("field1", "value1");
              records[0].setAttribute("field2", new Date());
              records[1] = new Record();
              records[1].setAttribute("field1", "value3");
              records[1].setAttribute("field2", (String)null);

              inputObject.setAttribute("data", records);

              DataSource myDS = new DataSource();
              myDS.setTagName("DSRequest");
              myDS.xmlSerialize(inputObject.getJsObj());

    &#010 .. produces the following XML:&#010

        &#010     <DSRequest>&#010         <startRow>5</startRow>&#010         <endRow>50</endRow>&#010         <data>&#010             <field1>value1</field1>&#010             <field2>2005-10-14T18:01:16</field2>&#010         </data>&#010         <data>&#010             <field1>value3</field1>&#010             <field2></field2>&#010         </data>&#010     </DSRequest>&#010

    &#010

    &#010 If you are working with a WSDL-described web service, XML serialization is performed&#010 automatically by APIs like `WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)` - you only need to&#010 know about serialization in order to understand how to put together JavaScript data that&#010 will fill in an XML message properly. &#010
    &#010 Note: when trying to send data to a web service, it is best to avoid putting&#010 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP&#010 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding&#010 Web Service messages are very complex and are subject to change with new versions of the&#010 web service you are contacting, whereas the data itself is easy to manipulate and less&#010 likely to change.&#010
    &#010 To troubleshoot message formation, you can set the log category "xmlComm" to &#010 `DEBUG` level in order to see the XML message formed by Smart GWT reported&#010 in log statements in the Developer Console.&#010&#010

    Parameters:
      `data` - data to be serialized
      `flags` - options for the serialization engine
    Returns:
      data as serialized to XML

  - ### xmlSerialize

    public String xmlSerialize(Map data, SerializationContext flags)
    Serialize a JavaScript object as XML.&#010

    &#010 The JavaScript Object passed to `xmlSerialize(com.google.gwt.core.client.JavaScriptObject)` becomes an XML&#010 element named after the `tagName` (or `ID` if&#010 tagName is unset). Each property of the object becomes a subElement. For example,&#010 using a DataSource to serialize like this:&#010

              DSRequest inputObject = new DSRequest();
              inputObject.setStartRow(5);
              inputObject.setEndRow(50);

              Record records[] = new Record[2];
              records[0] = new Record();
              records[0].setAttribute("field1", "value1");
              records[0].setAttribute("field2", new Date());
              records[1] = new Record();
              records[1].setAttribute("field1", "value3");
              records[1].setAttribute("field2", (String)null);

              inputObject.setAttribute("data", records);

              DataSource myDS = new DataSource();
              myDS.setTagName("DSRequest");
              myDS.xmlSerialize(inputObject.getJsObj());

    &#010 .. produces the following XML:&#010

        &#010     <DSRequest>&#010         <startRow>5</startRow>&#010         <endRow>50</endRow>&#010         <data>&#010             <field1>value1</field1>&#010             <field2>2005-10-14T18:01:16</field2>&#010         </data>&#010         <data>&#010             <field1>value3</field1>&#010             <field2></field2>&#010         </data>&#010     </DSRequest>&#010

    &#010

    &#010 If you are working with a WSDL-described web service, XML serialization is performed&#010 automatically by APIs like `WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)` - you only need to&#010 know about serialization in order to understand how to put together JavaScript data that&#010 will fill in an XML message properly. &#010
    &#010 Note: when trying to send data to a web service, it is best to avoid putting&#010 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP&#010 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding&#010 Web Service messages are very complex and are subject to change with new versions of the&#010 web service you are contacting, whereas the data itself is easy to manipulate and less&#010 likely to change.&#010
    &#010 To troubleshoot message formation, you can set the log category "xmlComm" to &#010 `DEBUG` level in order to see the XML message formed by Smart GWT reported&#010 in log statements in the Developer Console.&#010&#010

    Parameters:
      `data` - data to be serialized
      `flags` - options for the serialization engine
    Returns:
      data as serialized to XML

  - ### recordsFromXML

    public Record[] recordsFromXML(Object elements)
    Transform a list of XML elements to DataSource records.

    recordsFromXML() will return a List of DataSource Records. The value for each field is extracted from the XML according to the rules described under `valueXPath`.

    Parameters:
      `elements` - XML elements to transform, eg, the result of a call to `XMLTools.selectNodes(Object, String)`
    Returns:
      list of DataSource records derived from the XML elements

  - ### copyRecord

    public Record copyRecord(Record record)
    Copies all DataSource field values of a Record (including a TreeNode) to a new Record, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.
    Parameters:
      `record` - The record to be copied.
    Returns:
      A new copy of the record provided as an argument, with component-specific metata data removed.

  - ### getFieldNames

    public String[] getFieldNames()
    Retrieves the list of fields declared on this DataSource.
    Returns:
      names of all fields declared on this DataSource, including fields that are marked hidden

  - ### load

    public static void load(String[] dsID, Function callback, boolean forceReload)
    Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired.

    To force reloading of DataSources that have already been loaded, pass `true` in the forceReload parameter.

    Parameters:
      `dsID` - Array of DataSource IDs
      `callback` - Callback to fire after DataSource loading completes
      `forceReload` - Forcibly reload a dataSource if it's already loaded

  - ### load

    public static void load(String[] dsID, Function callback, DSLoadSettings settings)
    Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired.
    Parameters:
      `dsID` - Array of DataSource IDs
      `callback` - Callback to fire after DataSource loading completes
      `settings` - `DSLoadSettings` to control load features

  - ### loadWithParents

    public static void loadWithParents(String[] dsID, Function callback, boolean forceReload)
    Variation of `DataSource.load` that will also automatically load any DataSources that the requested DataSources inherit from (via `DataSource.inheritsFrom`)

    If the parent DataSource is already loaded, calling loadWithParents will not automatically reload them unless the forceReload parameter is passed.

    Parameters:
      `dsID` - DataSource ID
      `callback` - Callback to fire after DataSource loading completes
      `forceReload` - Forcibly reload a dataSource if it's already loaded

  - ### loadWithParents

    public static void loadWithParents(String[] dsID, Function callback, DSLoadSettings settings)
    Variation of `DataSource.load` that will also automatically load any DataSources that the requested DataSources inherit from (via `DataSource.inheritsFrom`).
    Parameters:
      `dsID` - DataSource ID
      `callback` - Callback to fire after DataSource loading completes
      `settings` - `DSLoadSettings` to control load features

  - ### exportClientData

    public void exportClientData(Object[] data, DSRequest requestProperties)
    Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users. This method can be used to export data formatted outside of any kind of visual component.

    If you do not specify an `operationId` in the `requestProperties` you pass to this method, it behaves exactly the same as the `exportClientDataStatic` static classMethod. If you do specify an `operationId`, the framework expects your DataSource to configure an `OperationBinding` of `operationType` `DSOperationType.CLIENTEXPORT`, with the same `operationId`. The framework will then send the `exportClientData` request via the ordinary `DSRequest` mechanism, which allows you to use normal framework features in the client data export. For example, you could add a `DMI declaration` to your `operationBinding`, which would allow you to write server-side code that intervenes in the export process - for instance, by calling the `getExportObject()` API to do something special with the export document, like saving it to a database table or sending it to an email list.

    When you use the specific `operationId` version of this API, both the SmartClient Server and server-side DataSources are required.

    To export unformatted data, see `exportData()` which does not include client-side formatters, but requires both the Smart GWT server and the presence of server-side DataSources.

    Parameters:
      `data` - Records to export, similar to ListGrid.data
      `requestProperties` - Request properties for the export

  - ### exportClientDataStatic

    public static void exportClientDataStatic(Object[] data, DSRequest requestProperties)
    Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users. This method can be used to export data formatted outside of any kind of visual component.

    Requires the SmartClient server, but does not rely on any server-side DataSources. If you need to intervene in the export process server-side - for example, if you need to do something not directly supported with the exported object, such as attach it to an email - use the `exportClientData` instance method with an appropriate `OperationBinding`, as described in the method documentation.

    To export unformatted data, see `exportData()`, which does not include client-side formatters, but requires both the SmartClient server and the presence of server-side DataSources.

    Note that field `displayFormat` is honored for "date" and "datetime" fields when exporting direct to Excel; see the displayFormat docs for details.

    NOTE: The "Static" in this method name merely indicates that it is the static version of this method, as opposed to the similar instance method `exportClientData`. Restrictions of the Java language itself prevent us from giving the instance method and the static method the same name.

  - ### setXmlNamespaces

    public DataSource setXmlNamespaces(XmlNamespaces xmlNamespaces) throws IllegalStateException
    Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions. xmlNamespaces should be specified as a map ping from namespace prefix to namespace URI, for example:

    xmlNamespaces : { az : "http://webservices.amazon.com/AWSECommerceService/2005-03-23" }
    By default, all namespaces declared on the document element (outermost element of the response) are made available with the prefix used in the document itself. Then, for non-WSDL-described XML results, if there i s a default namespace on the document element, it is made available with the special prefix "default".

    For results of WSDL-described operations, the prefix "service" means the service namespa ce, that is, the "targetNamespace" on the element from the WSDL file. The prefix "schema" means the names pace of the outermost element in the output message for the current operation. "default" will be the schema na mespace if there is one, otherwise the service namespace.
    For basic information on XML Namespaces and their use in XPath, try the following search: http://www.google.com/search?q=XPath+xml+namespaces
    Parameters:
      `xmlNamespaces` - xml namespaces
    Returns:
      `DataSource` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getFieldOperators

    public OperatorId[] getFieldOperators(String fieldName)
    Get the list of OperatorId's available for the passed field-name. By default, if validOperators is set on the DataSourceField, it returns that list, otherwise returns the result of `getTypeOperators(com.smartgwt.client.types.FieldType)`.
    Parameters:
      `fieldName` - the field name to obtain operators for
    Returns:
      the available Operators

  - ### getFieldOperators

    public OperatorId[] getFieldOperators(DataSourceField field)
    Get the list of OperatorId's available for the passed field. By default, if validOperators is set on the DataSourceField, it returns that list, otherwise returns the result of `getTypeOperators(com.smartgwt.client.types.FieldType)`.
    Parameters:
      `field` - the field to obtain operators for
    Returns:
      the available Operators

  - ### applyFilter

    public Record[] applyFilter(Record[] records, Criteria criteria, DSRequest requestProperties)
    Returns records in the passed Record that match the provided filter `Criteria`.

    By default:

    - any criteria that do not correspond to a DataSource field are ignored
    - any null or empty string criteria are ignored
    Parameters:
      `records` - (Record[]) the list of rows
      `criteria` - (Criteria) the filter criteria
      `requestProperties` - (DSRequest Properties) optional dataSource request properties
    Returns:
      Record[] the list of matching rows

  - ### applyFilter

    public Record[] applyFilter(Record[] records, Criteria criteria)
    Returns records in the passed Record that match the provided filter `Criteria`.

    By default:

    - any criteria that do not correspond to a DataSource field are ignored
    - any null or empty string criteria are ignored
    Parameters:
      `records` - (Record[]) the list of rows
      `criteria` - (Criteria) the filter criteria
    Returns:
      Record[] the list of matching rows

  - ### setCacheData

    public void setCacheData(Record... cacheData)
    For a `cacheAllData` or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.
    If this method is called after the component has been drawn/initialized: Call this method to set the data in the client-side cache after initialization.
    Parameters:
      `cacheData` - Array of records to apply as the client-side cache. Default value is null

  - ### getCacheData

    public Record[] getCacheData()
    For a `cacheAllData` or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.
    Returns:
      Returns the complete set of data cached by this dataSource. Note that this may have been supplied via `cacheData`, or may have been fetched from the server for dataSources with `cacheAllData` set to true.

  - ### setTestData

    public void setTestData(Record... cacheData)
    For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects. Deprecated in favor of `cacheData`.

    See `this discussion` for ways to populate a client-only DataSource with test data.
    If this method is called after the component has been drawn/initialized: Call this method to set the data in the client-side test-data after initialization. `setCacheData()` should be called instead and setTestData() is deprecated and will eventually be removed.

    Parameters:
      `testData` - Array of records to apply as the client-side test-data. Default value is null

  - ### getTestData

    public Record[] getTestData()
    For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects. Deprecated in favor of `cacheData`.

    See `this discussion` for ways to populate a client-only DataSource with test data.

    Returns:
      Record

  - ### getFieldAutoTitle

    public String getFieldAutoTitle(String identifier)
    Return a reasonable user-visible title given a fieldName. Called when `autoDeriveTitles` is true and by default, calls the class method `DataSource.getAutoTitle`. Override to provide a different policy for auto-deriving titles for a particular DataSource or subclass of DataSource.
    Parameters:
      `identifier` - identifier for which a title is desired.
    Returns:
      auto-derived title

  - ### getAutoTitle

    public static String getAutoTitle(String identifier)
    Utility method to derive a reasonable user-visible title from an identifier.

    The following approach is taken:

    - any underscores (_) or dollar signs ($) become spaces, except that there will never be either a leading or trailing space.
    - if the fieldName is either entirely uppercase or lowercase, all words separated by spaces are given a leading capital letter. Example USER_NAME or user_name -> "User Name".
    - if there is any use of mixed case, camelCaps convention is assumed, and the field name is split into separate words based on 1) everywhere an uppercase letter appears after a lowercase letter 2) everywhere a series of uppercase letters ends. Letter case will not be modified, with the exception that the first word will have its first letter capitalized. Example: useHTTPProxy -> "Use HTTP Proxy"
    Parameters:
      `identifier` - identifier for which a title is desired.
    Returns:
      auto-derived title

  - ### getFieldValue

    public static Object getFieldValue(ListGridField field, Record record)
    Given a field definition and a record object, this method will return the field value for the record.

    This method will follow any `dataPath` specified on the component field if necessary, and will extract `atomic values` from custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `record` - data object
    Returns:
      extracted field value

  - ### getFieldValue

    public static Object getFieldValue(DetailViewerField field, Record record)
    Given a field definition and a record object, this method will return the field value for the record.

    This method will follow any `dataPath` specified on the component field if necessary, and will extract `atomic values` from custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `record` - data object
    Returns:
      extracted field value

  - ### getFieldValue

    public static Object getFieldValue(FormItem field, Record record)
    Given a field definition and a record object, this method will return the field value for the record.

    This method will follow any `dataPath` specified on the component field if necessary, and will extract `atomic values` from custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `record` - data object
    Returns:
      extracted field value

  - ### getFieldValue

    public static Object getFieldValue(DataSourceField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)
    Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to obtain a field value from a flat record directly.

    If the dataPath is null, this method will follow any `dataPath` specified on the component field instead. In either case, it will also extract `atomic values` from custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `record` - data object
      `dataPath` - Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)
      `component` - Optional component to provide additional context for the dataPath search. This is typically required if the dataPath traverses a list
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)` method - see that API for details
      `convertResult` - If true, convert the field value to a native Java object before returning it
    Returns:
      extracted field value

  - ### getFieldValue

    public static Object getFieldValue(ListGridField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)
    Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to obtain a field value from a flat record directly.

    If the dataPath is null, this method will follow any `dataPath` specified on the component field instead. In either case, it will also extract `atomic values` from custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `record` - data object
      `dataPath` - Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)
      `component` - Optional component to provide additional context for the dataPath search. This is typically required if the dataPath traverses a list
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)` method - see that API for details
      `convertResult` - If true, convert the field value to a native Java object before returning it
    Returns:
      extracted field value

  - ### getFieldValue

    public static Object getFieldValue(DetailViewerField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)
    Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to obtain a field value from a flat record directly.

    If the dataPath is null, this method will follow any `dataPath` specified on the component field instead. In either case, it will also extract `atomic values` from custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `record` - data object
      `dataPath` - Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)
      `component` - Optional component to provide additional context for the dataPath search. This is typically required if the dataPath traverses a list
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)` method - see that API for details
      `convertResult` - If true, convert the field value to a native Java object before returning it
    Returns:
      extracted field value

  - ### getFieldValue

    public static Object getFieldValue(FormItem field, Record record, String dataPath, Canvas component, String reason, boolean convertResult)
    Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to obtain a field value from a flat record directly.

    If the dataPath is null, this method will follow any `dataPath` specified on the component field instead. In either case, it will also extract `atomic values` from custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `record` - data object
      `dataPath` - Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)
      `component` - Optional component to provide additional context for the dataPath search. This is typically required if the dataPath traverses a list
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)` method - see that API for details
      `convertResult` - If true, convert the field value to a native Java object before returning it
    Returns:
      extracted field value

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, String value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, String value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, String value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, String value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, Integer value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, Integer value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, Integer value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, Integer value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, Double value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, Double value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, Double value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, Double value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, Float value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, Float value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, Float value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, Float value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, Date value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, Date value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, Date value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, Date value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, Boolean value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, Boolean value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, Boolean value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, Boolean value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, JavaScriptObject value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, JavaScriptObject value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, JavaScriptObject value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, JavaScriptObject value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DataSourceField field, String dataPath, Map value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(ListGridField field, String dataPath, Map value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(DetailViewerField field, String dataPath, Map value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the get request, to be passed into any `SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)` method - see that API for details

  - ### saveValueViaDataPath

    public static void saveValueViaDataPath(FormItem field, String dataPath, Map value, Record values, String reason)
    Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to store a field value in a flat record directly.

    This method will call the `updateAtomicValue()` of custom `SimpleType` fields where this is required.

    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `value` - the field value to save
      `values` - data object to save into
      `reason` - Optional reason for the save, to be passed into any `com.smartgwt.client.data.SimpleType.SimpleTypeValueUpdaterr#pdateAtomicValue` method - see that API for details

  - ### clearValueAtDataPath

    public static void clearValueAtDataPath(FormItem field, String dataPath, Record values)
    Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to remove a field value from a flat record directly.
    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `values` - data object to save into

  - ### clearValueAtDataPath

    public static void clearValueAtDataPath(DetailViewerField field, String dataPath, Record values)
    Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to remove a field value from a flat record directly.
    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `values` - data object to save into

  - ### clearValueAtDataPath

    public static void clearValueAtDataPath(ListGridField field, String dataPath, Record values)
    Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to remove a field value from a flat record directly.
    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `values` - data object to save into

  - ### clearValueAtDataPath

    public static void clearValueAtDataPath(DataSourceField field, String dataPath, Record values)
    Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null. This method is only of real use when you are dealing with complex nested data via `dataPath`; it is obviously a trivial matter to remove a field value from a flat record directly.
    Parameters:
      `field` - Field definition from a dataSource or dataBoundComponent.
      `dataPath` - Optional dataPath to use (the field's dataPath is used if this is null)
      `values` - data object to save into

  - ### fetchData

    public void fetchData()
    Deprecated.
    When calling DataSource.fetchData(), no actions are automatically performed with the returned data; you must provide a callback that does something with the server's response. The exception is `setCacheAllData(true)` mode, in which case `fetchData()` populates the DataSource cache for use by subsequent fetches. To achieve this, use a signature of fetchData() that provides a callback, and pass criteria as null.

  - ### addSearchOperator

    public void addSearchOperator(Operator operator, FieldType[] types)
    Add a new search operator, only to this DataSource.

    If an existing `Operator` is passed, restricts the set of FieldTypes to which that operator can be applied in this DataSource.

    Parameters:
      `operator` - (Operator) definition of the operator to add
      `types` - (Array of FieldType) types to which this operator applies

  - ### getPatternMultiWildcardAsString

    public String[] getPatternMultiWildcardAsString()
    Deprecated.
    in favor of `getPatternMultiWildcardAsStringArray()`.
    See `getPatternMultiWildcardAsStringArray()`.

  - ### getPatternSingleWildcardAsString

    public String[] getPatternSingleWildcardAsString()
    Deprecated.
    in favor of `getPatternSingleWildcardAsStringArray()`.
    See `getPatternSingleWildcardAsStringArray()`.