Package com.smartgwt.client.docs.serverds

# Class OperationBinding

java.lang.Object
com.smartgwt.client.docs.serverds.OperationBinding

public class OperationBinding extends Object
An operationBinding tells a DataSource how to execute one of the basic DS operations: fetch, add, update, remove.

This class is not meant to be created and used, it is actually documentation of settings allowed in a DataSource descriptor (.ds.xml file), for use with Smart GWT Pro Edition and above. See `com.smartgwt.client.docs.serverds` for how to use this documentation.

See `DataSource.operationBindings`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `VelocityExpression`
  `afterWhereClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `Boolean`
  `allowAdvancedCriteria`
  This property indicates whether this operation supports AdvancedCriteria.
  `Boolean`
  `allowMultiUpdate`
  Ordinarily, "update" and "remove" operations are only allowed for `DataSource`s that have a `primaryKey`, and all primary key values are present in the request.
  `VelocityExpression`
  `ansiJoinClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `Boolean`
  `applyCriteriaBeforeAggregation`
  Default value is null
  `Boolean`
  `applySqlPrefixToRowCount`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `Boolean`
  `applySqlSuffixToRowCount`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `Boolean`
  `arrayCriteriaForceExact`
  Operation-level override for the DataSource-level `arrayCriteriaForceExact` flag.
  `Boolean`
  `autoJoinTransactions`
  If true, causes requests against this operation to automatically start or join a transaction.
  `String`
  `beanClassName`
  A per-operationBinding setting for beanClassName, otherwise also settable at the top-level DataSource configuration.
  `String`
  `cacheSyncOperation`
  For an operationBinding of `operationType` "add" or "update", this property is the `operationId` of a "fetch" operationBinding to use for cache synchronization purposes (ie, to fetch the row most recently added or changed).
  `CacheSyncStrategy`
  `cacheSyncStrategy`
  The `cacheSyncStrategy` to use for this operation.
  `CacheSyncTiming`
  `cacheSyncTiming`
  The `cacheSyncTiming` to use for this operation.
  `String`
  `callbackParam`
  Applies only to dataFormat: "json".
  `Boolean`
  `canSyncCache`
  For an operation of type "add" or "update", a SQLDataSource will normally obtain data to return to the client by performing the "cacheSyncOperation": a SELECT statement that retrieves the modified record by primary key.
  `String`
  `contextFiles`
  Comma-separated list of JavaScript files to pre-load into a pooled Graal JavaScript context for this OperationBinding's `server-side scriptlet`.
  `Integer`
  `contextPoolSize`
  Maximum number of pooled Graal JavaScript contexts to maintain for this OperationBinding's `contextFiles` configuration.
  `Boolean`
  `creatorOverrides`
  Indicates that field-level declarative security rules are waived for rows that were created by the current user, as described in the discussion of `dataSource.creatorOverrides`.
  `DSRequestModifier[]`
  `criteria`
  Elements of this feature are only available with Power or better licenses. See smartclient.com/product for details.
  `String`
  `csvDelimiter`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `String`
  `csvQuoteCharacter`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `String`
  `customCriteriaFields`
  Indicates that the listed fields should be included in the default `whereClause` generated for this operationBinding, even if they are marked `customSQL="true"`.
  `String`
  `customFields`
  Indicates that the listed fields should be included in the default `selectClause` and `whereClause` generated for this operationBinding, even if they are marked `customSQL`="true".
  `String`
  `customHQL`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `String`
  `customJQL`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `VelocityExpression`
  `customSQL`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `String`
  `customValueFields`
  Indicates that the listed fields should be included in the default `selectClause` and `valuesClause` generated for this operationBinding, even if they are marked `customSQL`="true".
  `DSProtocol`
  `dataProtocol`
  Controls the format in which inputs are sent to the dataURL.
  `String`
  `dataSources`
  Comma-separated list of DataSource IDs to make available in the server-side scripting context when executing an `process` or `script`.
  `String`
  `dataURL`
  URL to contact to fulfill DSRequests for this operationBinding.
  `Map`
  `defaultParams`
  HTTP parameters that should be submitted with every DSRequest.
  `String`
  `description`
  An optional description of the operationBinding's behavior.
  `String`
  `excludeCriteriaFields`
  Indicates that the listed fields should be excluded from the default `whereClause` generated for this operationBinding.
  `ExportFormat`
  `exportAs`
  The format in which the data should be exported.
  `String[]`
  `exportFields`
  The list of field-names to export.
  `String`
  `exportFilename`
  The name of the file to save the exported data into.
  `boolean`
  `exportResults`
  When set, causes the results of the DataSource Operation to be exported to a file, whose name and format are indicated by `exportFilename` and `exportAs` respectively.
  `Boolean`
  `filterBeforeGrouping`
  When true, all criteria for a `ServerSummaries` request are applied before aggregation (SQL `WHERE`) rather than being automatically split between `WHERE` and `HAVING`.
  `String`
  `forceSort`
  For DataSources of `serverType` "sql" only, indicates whether we should automatically add a sort field for `paged fetches`.
  `String`
  `groupBy`
  Field or list of fields to group by when using `server-side summarization`.
  `VelocityExpression`
  `groupClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `VelocityExpression`
  `groupWhereClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `String`
  `guestUserId`
  Value to use for the `ownerIdField` if no one has authenticated.
  `String`
  `headers`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `String`
  `httpMethod`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `Boolean`
  `includeAnsiJoinsInTableClause`
  This setting makes difference if `ANSI-style joins` are in use.
  `Boolean`
  `invalidateCache`
  If set, every invocation of this operationBinding will invalidate the local cache, forcing a server visit to refresh the data.
  `Boolean`
  `isDDL`
  Only applicable to "sql" dataSources.
  `String`
  `lineBreakStyle`
  The style of line-breaks to use in the exported output.
  `Mail`
  `mail`
  Definition of an email message that will be sent as an after-effect of selecting or updating data.
  `Boolean`
  `makeKeysAvailable`
  For an operation of type "add" or "update", a SQLDataSource will normally obtain data to return to the client by performing the `cacheSyncOperation`.
  `String`
  `methodArguments`
  You can explicitly declare the arguments to be passed to `serverMethod` using this attribute.
  `Integer`
  `multiInsertBatchSize`
  For "add" operations on dataSources of `serverType` "sql" only, this property sets the multi-insert batch size for this `operation`.
  `MultiInsertNonMatchingStrategy`
  `multiInsertNonMatchingStrategy`
  For "add" operations on dataSources of `serverType` "sql" only, this property sets the multi-insert "non matching" strategy for this `operation`.
  `MultiInsertStrategy`
  `multiInsertStrategy`
  For "add" operations on dataSources of `serverType` "sql" only, this property sets the multi-insert strategy for this `operation`.
  `String`
  `namedQuery`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `String`
  `operationFiles`
  Comma-separated list of JavaScript files to execute on every request for this OperationBinding's pooled Graal JavaScript context.
  `String`
  `operationId`
  Optional operationId if this DataSource supports two or more variants of one of the basic DataSource operations, for instance, a "fetch" that uses full text search and a "fetch" that accepts per-field search criteria.
  `DSOperationType`
  `operationType`
  Which operationType this operationBinding is for.
  `VelocityExpression`
  `orderClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `String`
  `outputs`
  Specifies, for this operationBinding only, the list of field names that should be returned to the client.
  `String`
  `ownerIdField`
  Overrides the same setting at the `DataSource` level, for this operation only.
  `String`
  `params`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `Boolean`
  `poolJSContext`
  Controls whether a Graal JavaScript context can be pooled and reused for `server-side JavaScript scriptlets` that use `contextFiles`.
  `Boolean`
  `preventHTTPCaching`
  Configures `DataSource.preventHTTPCaching` on a per-operationType basis.
  `Process`
  `process`
  Declares a server-side workflow `Process` to execute for this operation, as a declarative alternative to `script` or a `DMI`.
  `Boolean`
  `progressiveLoading`
  Sets `progressive loading mode` for this particular operation, overriding the DataSource-level setting.
  `Boolean`
  `providesMissingKeys`
  Ordinarily, "update" and "remove" operations are only allowed if all primary key values are present in the request.
  `boolean`
  `qualifyColumnNames`
  Specifies, for this specific operationBinding, whether to qualify column names with table names in any SQL we generate.
  `String`
  `recordName`
  For an XML DataSource, tagName of the elements to be used as records.
  `XPathExpression`
  `recordXPath`
  For an XML or JSON, JSON or `RestConnector` DataSource, an XPath expression used to retrieve the objects that will become DataSource records.
  `RESTRequestFormat`
  `requestFormat`
  For a `RestConnector DataSource`, the request format to use for this specific operationBinding.
  `DSRequest`
  `requestProperties`
  Additional properties to pass through to the `DSRequest` created for this operation.
  `String`
  `requestTemplate`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `String`
  `requiredCriterion`
  A comma-separated list of field names that must be present in criteria / advancedCriteria provided by the caller.
  `VelocityExpression`
  `requires`
  Indicates that the specified `VelocityExpression` must be true for a user to access this operationBinding.
  `Boolean`
  `requiresAuthentication`
  Whether a user must be authenticated in order to access this operation.
  `String`
  `requiresCompleteRESTResponse`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `String`
  `requiresRole`
  Comma-separated list of user roles that are allowed to invoke the operation described by this operationBinding.
  `AdvancedCriteria`
  `requiresWhen`
  ServerDynamicCriteria evaluated server-side to determine whether the current operation is allowed.
  `DataSource`
  `responseDataSchema`
  Optional schema describing how to extract DataSource records from the XML elements selected.
  `RESTResponseFormat`
  `responseFormat`
  For a `RestConnector DataSource`, the response format to use for this specific operationBinding.
  `String`
  `responseTemplate`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `String`
  `script`
  Scriptlet to be executed prior to the DataSource operation which is configured by this operationBinding.
  `VelocityExpression`
  `selectClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `String`
  `serverMethod`
  The name of the method to invoke on the `ServerObject` for this operationBinding.
  `ServerObject`
  `serverObject`
  Optional ServerObject declaration that specifies the ServerObject configuration for this operationBinding.
  `Boolean`
  `skipAudit`
  Setting `skipAudit` to `true` indicates that `auditing` must be skipped for this operationBinding.
  `Boolean`
  `skipRowCount`
  A SQLDataSource will normally issue two queries for a "fetch" operation when paging is enabled: one to determine the total rows available (the "row count query"), and one to fetch the specific range of rows requested.
  `boolean`
  `spoofResponses`
  For a DataSource contacting a `WSDL web service`, setting this flag means the DataSource doesn't actually attempt to contact the server but generates a sample response instead, based on the XML Schema of the response message embedded in the WSDL.
  `SQLPagingStrategy`
  `sqlPaging`
  The paging strategy to use for this specific OperationBinding.
  `VelocityExpression`
  `sqlPrefix`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `VelocityExpression`
  `sqlSuffix`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `SQLType`
  `sqlType`
  For dataSources of `serverType` "sql" and "hibernate" only, this property determines whether "custom" operations have their custom SQL or HQL sent to the underlying database via a JDBC `executeQuery()` or a JDBC `executeUpdate()`.
  `Boolean`
  `sqlUsePagingHint`
  If explicitly set true or false, forces the use of a "hint" in the SQL we generate for paged queries on or off as appropriate.
  `Map`
  `summaryFunctions`
  A mapping from field names to `summary functions` to be applied to each field.
  `Boolean`
  `suppressAutoMappings`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `VelocityExpression`
  `tableClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `Boolean`
  `transformMultipleFields`
  If set to "false", transformation of values for `multiple:true` fields, normally controlled by `DataSourceField.multipleStorage`, is instead disabled for this OperationBinding.
  `String`
  `transformRawResponseScript`
  Applicable to `server-side REST DataSources` only
  `String`
  `transformRequestScript`
  Scriptlet to be executed prior to the DataSource operation which is configured by this operationBinding.
  `String`
  `transformResponseScript`
  Scriptlet to be executed after the DataSource operation which is configured by this operationBinding.
  `String`
  `unionFields`
  Only applicable to "union" dataSources, this is a comma-separated list of the names of the dataSource fields that make up the union.
  `Boolean`
  `useContextFiles`
  Controls whether context pooling is enabled when `contextFiles` is specified.
  `boolean`
  `useFlatFields`
  Setting `useFlatFields` on an operationBinding is equivalent to setting `DSRequest.useFlatFields` on all DataSource requests with the same `operationType` as this `operationBinding`.
  `boolean`
  `useForCacheSync`
  For an operationBinding of `operationType` "fetch" which specifies no `operationId`, this property determines whether the operationBinding should be used for cache synchronization purposes (ie, to retrieve the record most recently added or changed).
  `Boolean`
  `useHavingClause`
  This setting switches between "having" clause and sub-select approaches when generating aggregated SQL queries.
  `Boolean`
  `useSpringTransaction`
  Sets or clears the `useSpringTransaction` flag for this specific operation.
  `Boolean`
  `useSubselectForRowCount`
  Whether to use the subselect technique (see `DataSource.useSubselectForRowCount` for details) to derive a rowcount query for this operation.
  `DSRequestModifier[]`
  `values`
  Elements of this feature are only available with Power or better licenses. See smartclient.com/product for details.
  `VelocityExpression`
  `valuesClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `VelocityExpression`
  `whereClause`
  This feature is available with Power or better licenses only. See smartclient.com/product for details.
  `Boolean`
  `wrapInList`
  Applies to RestConnector dataSources (`serverType` "rest") only.
  `Map`
  `xmlNamespaces`
  Optional object declaring namespace prefixes for use in `recordXPath` and `DataSourceField.valueXPath` XPath expressions.
  `String`
  `xmlTag`
  Applies to RestConnector dataSources (`serverType` "rest") only.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `OperationBinding()`

- ## Method Summary

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

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

- ## Field Details

  - ### requiredCriterion

    public String requiredCriterion
    A comma-separated list of field names that must be present in criteria / advancedCriteria provided by the caller. Failure to provide any one of these will yield a `STATUS_CRITERIA_REQUIRED_ERROR` from the server.

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### headers

    public String headers
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.headers` - see that property's documentation for details

    Default value is null

    See Also:
      - `Server-side REST Connector`

  - ### recordName

    public String recordName
    For an XML DataSource, tagName of the elements to be used as records.

    This is a simple alternative to `recordXPath` when the elements to be used as records all share a tagName.

    When a DataSource has a WebService, `recordName` can also be set to the name of any `complexType` declared within the WebService's WSDL file.

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### transformRawResponseScript

    public String transformRawResponseScript
    Applicable to `server-side REST DataSources` only

    A scriptlet to be executed on the server after data has been fetched from the REST service by this operation, but before it is processed through templating. See `DataSource.transformRawResponseScript` for further details.

    Note, unlike many OperationBinding-level properties, a `transformRawResponseScript` at the OperationBinding level does not hide a `transformRawResponseScript` defined at the DataSource level. Instead, if you define `transformRawResponseScript` against both the DataSource and the OperationBinding, both are run - first the DataSource-level script, then the OperationBinding-level one.

    Default value is null

    See Also:
      - `Server Scripting`

  - ### outputs

    public String outputs
    Specifies, for this operationBinding only, the list of field names that should be returned to the client. Typically this will be a subset of the `DataSource.fields`, but note that this is not a requirement; `outputs` can include fields that are not defined in the DataSource's field list. In this case, the server will return extra fields even if `DataSource.dropExtraFields` is true.

    You specify this property as a string containing a comma-separated list of field names (eg, "foo, bar, baz")

    Note that this setting overrides `DSRequest.outputs` and `DataSourceField.outputWhen` setting, meaning fields listed in operationBinding.outputs will be returned to the client regardless of those settings.

    Default value is null

    See Also:
      - `DataSourceField.outputWhen`
      - `DSRequest.getOutputs()`

  - ### preventHTTPCaching

    public Boolean preventHTTPCaching
    Configures `DataSource.preventHTTPCaching` on a per-operationType basis.

    Default value is null

  - ### ansiJoinClause

    public VelocityExpression ansiJoinClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke ANSI-style joins clause to use when constructing the SQL query to perform this operation. The property should be a set of joins implemented with JOIN directives (as opposed to additional join expressions in the where clause), joining related tables to the main table or view defined in `tableClause`. The server will insert the text of this property immediately after the `tableClause`.

    See the documentation for `customSQL` for usage examples

    Default value is null

    See Also:
      - `customSQL`
      - `DataSource.useAnsiJoins`
      - `includeAnsiJoinsInTableClause`
      - `Custom Querying Overview`

  - ### transformResponseScript

    public String transformResponseScript
    Scriptlet to be executed after the DataSource operation which is configured by this operationBinding. See `DataSource.transformResponseScript` for further details.

    Note, unlike many OperationBinding-level properties, a `transformResponseScript` at the OperationBinding level does not hide a `transformResponseScript` defined at the DataSource level. Instead, if you define `transformResponseScript` against both the DataSource and the OperationBinding, both are run - first the DataSource-level script, then the OperationBinding-level one.

    Default value is null

    See Also:
      - `Server Scripting`

  - ### qualifyColumnNames

    public boolean qualifyColumnNames
    Specifies, for this specific operationBinding, whether to qualify column names with table names in any SQL we generate. Overrides the `DataSource.qualifyColumnNames` property. Only applicable to dataSources of `serverType` "sql".

    Default value is true

  - ### description

    public String description
    An optional description of the operationBinding's behavior. Not automatically exposed on any component, but useful for developer documentation, and as such is included on any `OpenAPI specification` generated by the framework. Markdown is a commonly used syntax, but you may also embed HTML content in a CDATA tag.

    Default value is null

  - ### customValueFields

    public String customValueFields
    Indicates that the listed fields should be included in the default `selectClause` and `valuesClause` generated for this operationBinding, even if they are marked `customSQL`="true".

    You can specify this property as a comma-separated list (eg, "foo, bar, baz") or by just repeating the <customValueFields> tag multiple times with one field each.

    This property is only applicable to DataSources of `"sql"`.

    Default value is null

    See Also:
      - `customFields`
      - `customCriteriaFields`
      - `Custom Querying Overview`

  - ### groupBy

    public String groupBy
    Field or list of fields to group by when using `server-side summarization`.

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

    Default value is null

    See Also:
      - `summaryFunctions`
      - `Server Summaries`

  - ### lineBreakStyle

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

    Default value is null

  - ### multiInsertNonMatchingStrategy

    public MultiInsertNonMatchingStrategy multiInsertNonMatchingStrategy
    For "add" operations on dataSources of `serverType` "sql" only, this property sets the multi-insert "non matching" strategy for this `operation`. Only has an effect if the `add request` specifies a list of records as the data, and only if `multiInsertStrategy` is set to "multipleValues" either globally or at the `DSRequest`, `OperationBinding`, or `DataSource` level.

    Note that this setting overrides the equivalent `dataSource setting`, and can in turn be overridden at the `DSRequest level`

    Default value is "padWithNulls"

    See Also:
      - `multiInsertStrategy`
      - `multiInsertBatchSize`

  - ### mail

    public Mail mail
    Definition of an email message that will be sent as an after-effect of selecting or updating data.

    Note that if a fixed number of different messages need to be sent, multiple `<mail>` tags may be specified. For example, one mail could be sent to an admin address, and a different message to every member of a user group.

    Default value is null

  - ### contextFiles

    public String contextFiles
    Comma-separated list of JavaScript files to pre-load into a pooled Graal JavaScript context for this OperationBinding's `server-side scriptlet`.

    Files are evaluated once when each pooled context is created. Contexts are created lazily as requests need them, then reused across requests, eliminating the repeated overhead of loading common modules or libraries.

    Supports path variables `[SCROOT]` and `[WEBROOT]`, as well as shortcuts for common Smart GWT server module combinations:

    - `"core"` - ISC_Core_Server.js only
    - `"databinding"` - ISC_Core_Server.js + ISC_DataBinding_Server.js
    - `"grids"` - Core + DataBinding + ISC_Grids_Server.js
    - `"full"` - Core + DataBinding + Grids + ISC_Forms_Server.js

    The server canonicalizes the order of `contextFiles` before identifying the shared context pool: `ISC_Core_Server.js` (if present) is loaded first, then other Smart GWT Server modules in the order first added, then application-specific files in the order first added. Duplicate files are ignored. For example, these configurations are equivalent and share a pool:

            contextFiles="databinding, app/calculations.js"
            contextFiles="app/calculations.js, databinding"

    These are also equivalent because `"databinding"` first includes `"core"`:

            contextFiles="core, databinding"
            contextFiles="databinding, core"
            contextFiles="databinding"

    Application-specific file order is still significant. These configurations are not equivalent and do not share a pool:

            contextFiles="databinding, app/base.js, app/customGlobals.js"
            contextFiles="databinding, app/customGlobals.js, app/base.js"

    Likewise, adding another application-specific context file creates a different configuration and a separate pool:

            contextFiles="databinding, app/calculations.js"
            contextFiles="databinding, app/calculations.js, app/customGlobals.js"

    When listing application-specific files, include an appropriate Smart GWT shortcut such as `"databinding"`, so Smart GWT server APIs are available before those files are loaded.

    When `contextFiles` is specified, context pooling is automatically enabled because `useContextFiles` defaults to true. When a context file changes, cached contexts created from the previous file contents are discarded rather than reused. A context already executing may complete its current request, but it is closed when returned to the pool.

    Note: Pooled contexts are not cleared between requests. `contextFiles` should define reusable functions or modules, and `operationFiles` or the scriptlet should overwrite any request-handling-specific globals or state they create or use. Conversely, `operationFiles` and the scriptlet should not overwrite shared globals initialized by `contextFiles`, because `contextFiles` are not re-run after the context is created. If there is a need to customize the shared globals initialized by `contextFiles`, add such customization as another context file.

    Pool sharing: Pooled contexts are created for each canonically distinct `contextFiles` configuration, not for a particular DataSource, OperationBinding, operationId, scriptlet, or `operationFiles` setting. Thus, different OperationBindings, even on different DataSources, may reuse the same context to execute their scripts if they have the same canonical `contextFiles` configuration. This is why request-handling-specific globals or state must be overwritten by `operationFiles` or the scriptlet, and why operations that require separate context pools should use canonically distinct `contextFiles` configurations.

    Example usage:

            <operationBinding operationType="fetch" contextFiles="databinding,/path/to/myModule.js">
              <script language="graal.js">
                // Pre-loaded modules are already available
                var result = isc.DataSource.get("myDS").fetchData();
              </script>
            </operationBinding>

    Default value is null

    See Also:
      - `useContextFiles`
      - `operationFiles`

  - ### dataProtocol

    public DSProtocol dataProtocol
    Controls the format in which inputs are sent to the dataURL.

    When a DataSource operation such as fetchData() is invoked on this DataSource or a component bound to this DataSource, the data passed to the operation, if any, will be sent to the `dataURL`. The `dataProtocol` property controls the format in which the data is sent: SOAP message, HTTP GET or POST of parameters, etc.

    The `dataProtocol` property need not be set for a DataSource with a WebService ( `DataSource.serviceNamespace` is set), in this case, SOAP messaging is used by default.

    Developers may completely bypass the Smart GWT comm system by setting dataProtocol to `"clientCustom"`. In this case Smart GWT will not attempt to send any data to the server after calling `DataSource.transformRequest()`. Instead the developer is expected to implement `transformRequest()` such that it performs the necessary data action outside of Smart GWT, and then calls `DataSource.processResponse()`, passing in the `DSRequest.requestId` and an appropriate set of DSResponse properties to indicate the result of the action.

    NOTE: when `dataFormat` is "iscServer", `dataProtocol` is not consulted. Instead, Smart GWT uses a proprietary wire format to communicate with the Smart GWT server, and the server-side DSRequest and DSResponse objects should be used to access request data and form responses.

    Default value is "getParams"

    See Also:
      - `DSProtocol`
      - `Client-side Data Integration`

  - ### groupWhereClause

    public VelocityExpression groupWhereClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    Alias for `afterWhereClause`. Kept for backward compatibility. Same semantics and SQL insertion point. See the new attribute for full docs and examples.

    If both `groupWhereClause` and `afterWhereClause` are set, `afterWhereClause` is used.

    Default value is null

    See Also:
      - `afterWhereClause`
      - `useHavingClause`
      - `customSQL`

  - ### responseTemplate

    public String responseTemplate
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of the `DataSource.responseTemplate` - see that property's documentation for details

    Default value is null

    See Also:
      - `DataSource.responseTemplate`
      - `transformResponseScript`
      - `requestTemplate`
      - `Server-side REST Connector`

  - ### requiresAuthentication

    public Boolean requiresAuthentication
    Whether a user must be authenticated in order to access this operation. For details of what is meant by "authenticated", see `DataSource.requiresAuthentication`.

    To protect access to an entire operationType (eg, all "fetch" operations), declare an operationBinding with `requiresAuthentication="true"`, `operationType` set to the operationType to be protected, but no `operationId`. This will then prevent access to the "fetch" operationType unless another `OperationBinding` declares requiresAuthentication="false" with a specific `operationId`.

    Default value is null

    See Also:
      - `Declarative Security`

  - ### filterBeforeGrouping

    public Boolean filterBeforeGrouping
    When true, all criteria for a `ServerSummaries` request are applied before aggregation (SQL `WHERE`) rather than being automatically split between `WHERE` and `HAVING`. In this mode, `afterWhereClause` is not auto-generated.

    This setting applies consistently across built-in SQL, Hibernate, and JPA DataSources, with the same semantics for controlling whether criteria are applied before or after aggregation.

    NOTE: when this flag is true, client-side filtering will not match server-side filtering for aggregated fields, because the client always filters post-aggregation. You can set `ResultSet.useClientFiltering` to disable client-side filtering via `ListGrid.dataProperties`, or mark individual fields `canFilter:false`.

    For example, with `filterBeforeGrouping:true` and the "avg" function on a "price" field, criteria "price < 5" eliminates records where price is less than 5 before the average is calculated.

    Explicit `DSRequest.afterCriteria` is still honored, allowing both pre- and post-aggregation criteria to be applied to the same request.

    `SQL Templating` offers full control via $sql.partialWhere(), $sql.whereWithout(), $sql.partialHaving() and $sql.havingWithout().

    To apply this per-request rather than per-operationBinding, use `DSRequest.filterBeforeGrouping`.

    Default value is null

    See Also:
      - `afterWhereClause`
      - `com.smartgwt.client.data.DSRequest#getFilterBeforeGrouping`
      - `com.smartgwt.client.data.DSRequest#getAfterCriteria`

  - ### useHavingClause

    public Boolean useHavingClause
    This setting switches between "having" clause and sub-select approaches when generating aggregated SQL queries. It also affects how aggregated fields are referred in:
    generated `afterWhereClause`
    expressions generated by `SQLDataSource.getPartialHaving(...)` and `SQLDataSource.getHavingWithout(...)` server-side API
    expressions generated by `$sql.partialHaving(...)` and `$sql.havingWithout(...)` `Velocity context` variables used in `SQL Temlating`

    ### useHavingClause=true (default)

    SQL query is generated using traditional "having" clause approach:

            select <selectClause>
              from ...
             where ...
          group by <groupClause>
            having <afterWhereClause>

    Aggregated fields are referred by SQL expressions:

            select customer, sum(quantity * price) as amount
              from ...
             where ...
          group by customer
            having sum(quantity * price) > 10

    ### useHavingClause=false

    SQL query is generated using sub-select approach when main query becomes sub-select and then it is filtered in outer "where" clause:

          select *
          from (select <selectClause> from ... where ... group by <groupClause>) work
          where <afterWhereClause>

    Aggregated fields are referred by aliases they are selected by:

            select *
              from (select customer, sum(quantity * price) as amount
                      from ...
                     where ...
                  group by customer) work
             where amount > 10

    If `operationBinding.useHavingClause` is omitted this may be controlled by `sql.MyDatabase.useHavingClause` setting in `server.properties` on a per-database basis.

    Default value is null

    See Also:
      - `afterWhereClause`

  - ### customHQL

    public String customHQL
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "hibernate", this property can be specified on an operationBinding to indicate that the server should run user-specified HQL (Hibernate Query Language), rather than the Hibernate criteria query or `saveOrUpdate` call it would normally generate to satisfy a dataSource operation via Hibernate.

    Note that inserting new records via HQL is often impractical, due to intentional restrictions in the language (it is only possible to perform an insert expressed in terms of a SELECT; the "VALUES" construct commonly used when inserting new rows singly is not supported). If you are intending to use customHQL, we recommend that you avoid doing so for `OperationBinding`s with `operationType` "add", unless you have a special requirement such as a bulk insert; if you need custom queries to perform inserts on "hibernate" dataSources, we recommend you use `customSQL`, which is valid for "hibernate" DataSources as well as "sql" dataSources.

    For other operations on "hibernate" dataSources, however, HQL has the advantage of being more portable across different database engines than is plain SQL.

    Note that using customHQL affects paging implementation. If you use it, full data set is fetched from Hibernate and records that aren't in the requested range are dropped at the server side.

    Default value is null

    See Also:
      - `customSQL`
      - `namedQuery`
      - `DataSourceField.customSQL`
      - `Custom Querying Overview`

  - ### criteria

    public DSRequestModifier[] criteria
    Elements of this feature are only available with Power or better licenses. See smartclient.com/product for details.

    A list of `DSRequestModifier`s that will be used to modify the criteria of each `DSRequest` that uses this operationBinding. Note that the criteria elements are applied to DSRequest criteria as follows:

    - Simple criteria: The field and value are just applied as an extra key/value pair in the criteria map, as long as the `operator` attribute is left unset, or is set to "equals". For any other setting of `operator`, the criteria is first converted to the equivalent AdvancedCriteria and then processed as described below
    - AdvancedCriteria: If the topmost operator is "and", we add the new criterion as an additional criterion directly in the existing list. Otherwise, we create a new top-level AdvancedCriteria with an operator of "and". This is then set to have two elements in its criteria: the previous top-level criteria and the new criterion.
    The effect of this is to apply any criteria specifed here as additional constraints on top of what the user has specified, and of course, the user is unable to affect this. Thus, this is a suitable and convenient place to enforce rules such as "Users can only ever see their own records".

    Below is an example of the XML as it should be defined in your ds.xml, datasource definitions.

          <operationBindings>
            <operationBinding operationType="fetch" operationId="...">
              <criteria fieldName="USER_ROLE" value="ADMIN" operator="equals" />
            </operationBinding>
          </operationBindings>

    Default value is null

    See Also:
      - `values`
      - `Transaction Chaining`

  - ### callbackParam

    public String callbackParam
    Applies only to dataFormat: "json". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response for this operation.

    Typically set once for the DataSource as a whole via `DataSource.callbackParam`.

    Default value is "callback"

    See Also:
      - `DataSource.callbackParam`
      - `Client-side Data Integration`

  - ### responseFormat

    public RESTResponseFormat responseFormat
    For a `RestConnector DataSource`, the response format to use for this specific operationBinding. Overriddes any `DataSource-level setting`. Note, if `responseFormat` is not specified at either the DataSource or OperationBinding level, response processing will throw an exception.

    Default value is null

    See Also:
      - `Server-side REST Connector`

  - ### exportResults

    public boolean exportResults
    When set, causes the results of the DataSource Operation to be exported to a file, whose name and format are indicated by `exportFilename` and `exportAs` respectively. When no exportFilename is provided, the default is Results and the default value of exportAs is csv. Once the Operation completes, `DSRequest.exportDisplay` specifies whether the exported data will be downloaded to the file-system or displayed in a new window. The default value of exportDisplay is "download" which displays the Save As dialog. See `ExportDisplay` for more information.

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

    You can also configure the style of line-breaks to use when generating the output. See `LineBreakStyle` for more information.

    As well as setting this and other properties on the `OperationBinding`, Exports can be initiated in two other ways. You can set properties on the dsRequest by passing requestProperties into `DataSource.exportData()`. Note that this method does not support exporting to JSON format (see this post for more detail). Additionally, custom server code may set export-related properties on the `DSResponse`.

    Format Examples

    XML format

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

    JSON Format

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

    CSV Format

              id,displayName
              10101,"Record 10101"

    Default value is false

  - ### serverObject

    public ServerObject serverObject
    Optional ServerObject declaration that specifies the ServerObject configuration for this operationBinding. In the absence of a serverObject specification here, the one specified on the DataSource itself is used by default, if present (`DataSource.serverObject`). If neither is present, then Direct Method Invocation will not be enabled for this operationBinding.

    Note that if a dataSource configuration has both a `<script>` block and a specified `serverObject` for some operation, the script block will be executed, and the serverObject ignored.

    Default value is null

    See Also:
      - `DataSource.serverObject`

  - ### customJQL

    public String customJQL
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "jpa", this property can be specified on an operationBinding to indicate that the server should run user-specified JQL (Java Persistence Query Language).

    Note that inserting new records via JQL is often impractical, due to intentional restrictions in the language (it is only possible to perform an insert expressed in terms of a SELECT; the "VALUES" construct commonly used when inserting new rows singly is not supported). If you are intending to use customJQL, we recommend that you avoid doing so for `OperationBinding`s with `operationType` "add", unless you have a special requirement such as a bulk insert; if you need custom queries to perform inserts on "jpa" dataSources, we recommend you use `customSQL`, which is valid for "jpa" DataSources as well as "sql" dataSources.

    For other operations on "jpa" dataSources, however, JQL has the advantage of being more portable across different database engines than is plain SQL.

    Note that using customJQL affects paging implementation. If you use it, full data set is fetched from JPA and records that aren't in the requested range are dropped at the server side.

    Default value is null

    See Also:
      - `customSQL`
      - `namedQuery`
      - `DataSourceField.customSQL`
      - `Custom Querying Overview`

  - ### requestProperties

    public DSRequest requestProperties
    Additional properties to pass through to the `DSRequest` created for this operation. Note that these will be cumulative with and will override on a per-property basis any properties set via `DataSource.requestProperties`.

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

    Default value is null

    See Also:
      - `DSRequest`
      - `DataSource.requestProperties`
      - `Server DataSource Integration`

  - ### selectClause

    public VelocityExpression selectClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke SELECT clause to use when constructing the SQL query to perform this operation. The property should be a comma-separated list of column names and/or expressions, and you can refer to any scalar function supported by the underlying database. The server will insert the text of this property immediately after the "SELECT" token.

    Note that if you also specify a `groupClause`, you can use aggregate functions such as SUM and COUNT in the selectClause.

    This property is only applicable to operationBindings of `operationType` "fetch".

    See the documentation for `customSQL` for usage examples

    Default value is null

    See Also:
      - `customSQL`
      - `Custom Querying Overview`

  - ### summaryFunctions

    public Map summaryFunctions
    A mapping from field names to `summary functions` to be applied to each field.

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

    Default value is null

    See Also:
      - `groupBy`
      - `Server Summaries`

  - ### applySqlSuffixToRowCount

    public Boolean applySqlSuffixToRowCount
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For operations on DataSources of `serverType` "sql" only, if `sqlSuffix` is specified at either operation or DataSource level, should that prefix also be applied to the rowcount query, if one is run? This property is true by default, meaning we will apply the suffix to both rowcount and main queries

    This property is ignored for non-SQL dataSources

    This property can also be specified at the `DataSource level`; any such value acts as a default for the dataSource, and will be overridden by an operationBinding-level setting

    Default value is true

    See Also:
      - `applySqlPrefixToRowCount`
      - `Custom Querying Overview`

  - ### cacheSyncTiming

    public CacheSyncTiming cacheSyncTiming
    The `cacheSyncTiming` to use for this operation. Overrides any `dataSource-level cacheSyncTiming`

    Default value is null

    See Also:
      - `cacheSyncStrategy`
      - `DataSource.cacheSyncTiming`
      - `com.smartgwt.client.data.DSRequest#getCacheSyncTiming`
      - `Automatic Cache Synchronization`

  - ### operationFiles

    public String operationFiles
    Comma-separated list of JavaScript files to execute on every request for this OperationBinding's pooled Graal JavaScript context.

    This setting is used with `contextFiles`. Unlike `contextFiles`, which are evaluated when a pooled context is created and then retained in that context, operation files are executed fresh on each request. Use this for per-request logic like loading request-specific data or invoking calculations with that data. This setting only has an effect when the pooled Graal context path is active, which requires `contextFiles`.

    Operation files must be idempotent: safe to execute multiple times with the same result. They typically:

    - Load or define request-specific data, such as dataset files
    - Invoke calculation functions using that data
    - Prepare request-specific values or globals that the inline OperationBinding script then uses or returns

    The direct return value of an operation file is ignored.

    Supports webroot-relative paths, for example `"path/to/file.js"`, or absolute paths with `[SCROOT]` or `[WEBROOT]` path variables.

    Example usage:

            <operationBinding operationType="fetch"
                             contextFiles="databinding,/path/to/calculations.js"
                             operationFiles="/path/to/load-and-execute.js">
              <script language="graal.js">
                // Operation files have already been executed
                // Just return the result they prepared
                response;
              </script>
            </operationBinding>

    Default value is null

    See Also:
      - `contextFiles`

  - ### requiresCompleteRESTResponse

    public String requiresCompleteRESTResponse
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.requiresCompleteRESTResponse` - see that property's documentation for details

    Default value is null

    See Also:
      - `Server-side REST Connector`

  - ### methodArguments

    public String methodArguments
    You can explicitly declare the arguments to be passed to `serverMethod` using this attribute. This isn't required - in the absence of `methodArguments`, the DMI implementation will still automatically pass a stock set of arguments to your method (see the overview in `ServerObject`), but specifying arguments gives you the ability to call pre-existing methods without adding Smart GWT-specific code.

    The format for specifying `methodArguments` is as a comma separated list of VTL (Velocity Template Language) expressions. See the VTL Reference and Velocity User Guide for an overview of how to use VTL.

    The Velocity context is pre-populated with the following variables - you can pass these verbatim as arguments, or call methods on these objects and pass the resulting values:

    - dsRequest: instance of the current DSRequest
    - request: the current HttpServletRequest
    - response: the current HttpServletResponse
    - rpcManager: the instance of RPCManager for this request
    - dataSource: a DataSource instance for this request
    So, for example, if you had a method signature like the following:

    `public DSResponse fetch(SupplyItem criteria, long startRow, long endRow)`

    You can invoke it by specifying `methodArguments` as follows:

    `methodArguments="$dsRequest.criteria, $dsRequest.startRow, $dsRequest.endRow"`

    Without `methodArguments`, there would be no way for you to specify `startRow/endRow` as arguments. You could, of course, simply declare the method to take a `DSRequest` object and call `getStartRow()/getEndRow()` in the body of the method.

    Default value is null

    See Also:
      - `ServerObject`

  - ### requires

    public VelocityExpression requires
    Indicates that the specified `VelocityExpression` must be true for a user to access this operationBinding.

    As with `requiresRole`, if there an operationBinding that is the default operationBinding for the operationType, its `requires` expression is assumed to apply to all other operationBindings of the same type unless they explicitly set `requires=""`

    `DataSource.requires`, if specified, applies before `operationBinding.requires` is evaluated. In this case, both `requires` expressions must be true for the request to be accepted.

    Default value is null

    See Also:
      - `Declarative Security`

  - ### customCriteriaFields

    public String customCriteriaFields
    Indicates that the listed fields should be included in the default `whereClause` generated for this operationBinding, even if they are marked `customSQL="true"`.

    You can specify this property as a comma-separated list (eg, "foo, bar, baz") or by just repeating the <customCriteriaFields> tag multiple times with one field each.

    This property is only applicable to DataSources of `"sql"`.

    Default value is null

    See Also:
      - `customFields`
      - `customValueFields`
      - `excludeCriteriaFields`
      - `Custom Querying Overview`

  - ### csvDelimiter

    public String csvDelimiter
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.csvDelimiter` - see that property's documentation for details

    Default value is ","

    See Also:
      - `Server-side REST Connector`

  - ### excludeCriteriaFields

    public String excludeCriteriaFields
    Indicates that the listed fields should be excluded from the default `whereClause` generated for this operationBinding.

    This enables you to use these fields in a `custom query` while still allowing the $defaultWhereClause to be generated for all other fields. For example, you might take a particular field and apply it in the WHERE clause of a subquery.

    You can specify this property as a comma-separated list (eg, "foo, bar, baz") or by just repeating the <customCriteriaFields> tag multiple times with one field each. Note that if a field is included in both excludeCriteriaFields and `customCriteriaFields`, customCriteriaFields wins.

    This property is only applicable to DataSources of `"sql"`.

    Default value is null

    See Also:
      - `customCriteriaFields`
      - `Custom Querying Overview`

  - ### xmlNamespaces

    public Map xmlNamespaces
    Optional object declaring namespace prefixes for use in `recordXPath` and `DataSourceField.valueXPath` XPath expressions.

    `xmlNamespaces` should be specified as a mapping 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 is 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 namespace, that is, the "targetNamespace" on the <definitions> element from the WSDL file. The prefix "schema" means the namespace of the outermost element in the output message for the current operation. "default" will be the schema namespace 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

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### httpMethod

    public String httpMethod
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.httpMethod` - see that property's documentation for details

    Default value is null

    See Also:
      - `Server-side REST Connector`

  - ### useForCacheSync

    public boolean useForCacheSync
    For an operationBinding of `operationType` "fetch" which specifies no `operationId`, this property determines whether the operationBinding should be used for cache synchronization purposes (ie, to retrieve the record most recently added or changed). This property has no effect on an operationBinding that specifies an operationId - see `cacheSyncOperation`.

    In order to work correctly with Smart GWT's cache synchronization system, an operationBinding marked useForCacheSync should have the following properties:

    - Able to complete its retrieval using no context other than the values of the primary key fields declared in the dataSource (these will be provided in the $criteria object passed to the operation)
    - Returns the entire record, including any values that may require joins to other tables or other complexities
    This property is not applicable to the built-in `Hibernate` and `JPA` DataSources.

    Please also read the overview article on `CacheSynchronization` for full details of all the cache sync options

    Default value is true

    See Also:
      - `cacheSyncOperation`
      - `Automatic Cache Synchronization`

  - ### creatorOverrides

    public Boolean creatorOverrides
    Indicates that field-level declarative security rules are waived for rows that were created by the current user, as described in the discussion of `dataSource.creatorOverrides`. This setting overrides `dataSource.creatorOverrides`, for this operation only.

    Default value is null

    See Also:
      - `DataSourceField.editRequires`
      - `DataSourceField.viewRequires`
      - `DataSource.creatorOverrides`
      - `Field-Level Security`

  - ### sqlSuffix

    public VelocityExpression sqlSuffix
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For operations on DataSources of `serverType` "sql" only, some text to add right at the end of the query generated for this specific operation, after all other text. This can be plain text or a `Velocity template`. Like `sqlPrefix`, this property allows for non-standard SQL extensions that may be required to obtain some special, database-specific behavior. For example, Progress OpenEdge database can be given hints like `"WITH (NOLOCK)"`, that must appear after all other text.

    This property is ignored for non-SQL dataSources

    `sqlSuffix` can also be specified at the `DataSource level`; any such value acts as a default for the dataSource, and will be overridden by an operationBinding-level setting

    You can alternatively provide SQL suffix text programmatically, by overriding `getSQLSuffix()` in a `custom DataSource implementation`

    Default value is null

    See Also:
      - `Custom Querying Overview`

  - ### dataSources

    public String dataSources
    Comma-separated list of DataSource IDs to make available in the server-side scripting context when executing an `process` or `script`.

    When a `Process` runs server-side, its `DS*Tasks` resolve DataSources by ID automatically. However, DataSources referenced via dynamic expressions (e.g. `$values.targetDS`) or used directly in `ScriptTask` code must be pre-loaded. `dataSources` ensures they are available as DataSource instances and as same-named local variables.

    DataSources referenced directly in DS*Task `dataSource` attributes are auto-resolved and do NOT need to be listed here.

    Example:

          <operationBinding operationType="update"
              dataSources="auditLog,notification">
              <process>
                  <Process startElement="step1">
                      ...
                      <ScriptTask ID="customAudit">
                          <script>
                              var ds = isc.DataSource.get("auditLog");
                              ds.addData({ action: "update", ... });
                          </script>
                      </ScriptTask>
                  </Process>
              </process>
          </operationBinding>

    The legacy attribute name `graalDS` is also accepted for backward compatibility, but `dataSources` is preferred because it is engine-neutral.

    Default value is null

    See Also:
      - `process`
      - `script`

  - ### transformRequestScript

    public String transformRequestScript
    Scriptlet to be executed prior to the DataSource operation which is configured by this operationBinding. See `DataSource.transformRequestScript` for further details.

    Note, unlike many OperationBinding-level properties, a `transformRequestScript` at the OperationBinding level does not hide a `transformRequestScript` defined at the DataSource level. Instead, if you define `transformRequestScript` against both the DataSource and the OperationBinding, both are run - first the DataSource-level script, then the OperationBinding-level one.

    Default value is null

    See Also:
      - `Server Scripting`

  - ### afterWhereClause

    public VelocityExpression afterWhereClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke HAVING clause to use when constructing the SQL query to perform this operation. The property should be a valid expression in the syntax of the underlying database. The server will insert the text of this property immediately after the outer "HAVING" token:

            select <selectClause>
              from ...
             where ...
          group by <groupClause>
            having <afterWhereClause>

    or after outer "WHERE" token if `useHavingClause` was set to `false`:

          select *
          from (select <selectClause> from ... where ... group by <groupClause>) work
          where <afterWhereClause>

    Note that care is required when using afterWhereClause to ensure that the selectClause contains all the fields you are filtering by. Failure to do this correctly will result in a runtime SQL error.

    This property is only applicable to operationBindings of `operationType` "fetch".

    It fully supports `SQL Templating` feature, for example:

          <afterWhereClause>$defaultAfterWhereClause AND field_name = value </afterWhereClause>

    See the documentation for `SQL Templating` for more details and `Server Summaries` for how criteria is applied to aggregated fields. Also, see "Filtered summaries", "Aggregation & Custom SQL" and "Custom Aggregation Query" Server Summaries samples in Smartclient Showcase.

    ### "Standalone" afterWhereClause usage

    Normally afterWhereClause is used in the context of the Server Summaries feature, but it is possible to use it in non aggregated fetches as well. For example:

          <DataSource ID="order" serverType="sql" tableName="order">
              <fields>
                  <field name="orderID" primaryKey="true" ... />
                  ...
              </fields>
              <operationBinding operationType="fetch">
                  <tableClause>$defaultTableClause JOIN orderItem oi on order.orderID = oi.orderID</tableClause>
                  <groupClause>$defaultSelectClause</groupClause>
                  <afterWhereClause>count(oi.orderID) > 1 AND sum(oi.unitPrice * oi.quantity) > 100</afterWhereClause>
              <operationBinding>
          </DataSource>

    There's no builtin aggregation used in `operationBinding` above, but the regular "fetch" is limited by requiring every order to have multiple order items with amount greater than 100.

    Default value is null

    See Also:
      - `customSQL`
      - `selectClause`
      - `useHavingClause`
      - `filterBeforeGrouping`
      - `com.smartgwt.client.data.DSRequest#getAfterCriteria`
      - `Custom Querying Overview`

  - ### suppressAutoMappings

    public Boolean suppressAutoMappings
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.suppressAutoMappings` - see that property's documentation for details

    Default value is false

    See Also:
      - `Server-side REST Connector`

  - ### customFields

    public String customFields
    Indicates that the listed fields should be included in the default `selectClause` and `whereClause` generated for this operationBinding, even if they are marked `customSQL`="true".

    If you need to apply different sets of overrides for the `selectClause` and the `whereClause`, use `customValueFields` and/or `customCriteriaFields` instead. If you specify both `customFields` and `customCriteriaFields` or `customValueFields`, the more specific variant wins. If you specify both `customFields` and `excludeCriteriaFields`, `customFields` wins (this is another use case when you may wish to use `customValueFields` instead)

    You can specify this property as a comma-separated list (eg, "foo, bar, baz") or by just repeating the <customFields> tag multiple times with one field each.

    This property is only applicable to DataSources of `"sql"`.

    Default value is null

    See Also:
      - `customValueFields`
      - `customCriteriaFields`
      - `excludeCriteriaFields`
      - `Custom Querying Overview`

  - ### multiInsertBatchSize

    public Integer multiInsertBatchSize
    For "add" operations on dataSources of `serverType` "sql" only, this property sets the multi-insert batch size for this `operation`. Only has an effect if the `add request` specifies a list of records as the data, and only if `multiInsertStrategy` is set to "multipleValues" either globally or at the `DSRequest`, `OperationBinding`, or `DataSource` level.

    Note that this setting overrides the equivalent `dataSource setting`, and can in turn be overridden at the `DSRequest level`

    Default value is null

    See Also:
      - `multiInsertStrategy`
      - `multiInsertNonMatchingStrategy`

  - ### params

    public String params
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.params` - see that property's documentation for details

    Default value is null

    See Also:
      - `Server-side REST Connector`

  - ### exportFields

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

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

    Default value is null

  - ### responseDataSchema

    public DataSource responseDataSchema
    Optional schema describing how to extract DataSource records from the XML elements selected.

    Once a set of XML elements have been selected via `recordXPath` or `recordName`, those elements are normally transformed to JavaScript objects using the `fields` of the DataSource that owns the operationBinding. A `responseDataSchema` can be specified instead if the XML differs in some way between different DataSource operations, such that different values for `field.valueXPath` may be necessary to extract the same DataSource record from slightly different XML structures.

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### forceSort

    public String forceSort
    For DataSources of `serverType` "sql" only, indicates whether we should automatically add a sort field for `paged fetches`. Only applies to `"fetch" operations`. If left unset, this property defaults first to the `dataSource-level setting`, and then to one of the global values described in the `defaultSortField` documentation.

    Note, the ability to set this property per-operation is only provided to allow for complete configurability in unusual cases. See the `defaultSortField` docs for details of why use of this property should be considered a red flag.

    Default value is null

    See Also:
      - `Server DataSource Integration`

  - ### allowAdvancedCriteria

    public Boolean allowAdvancedCriteria
    This property indicates whether this operation supports AdvancedCriteria. This setting overrides `DataSource.allowAdvancedCriteria` for this operation only. See `DataSource.supportsAdvancedCriteria()` for further information.

    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 an OperationBinding that advertises itself as `allowAdvancedCriteria:false`, it will be rejected.

    Default value is null

    See Also:
      - `DataSource.allowAdvancedCriteria`

  - ### useContextFiles

    public Boolean useContextFiles
    Controls whether context pooling is enabled when `contextFiles` is specified.

    This property is primarily useful for sub-DataSource inheritance scenarios where a parent DataSource defines `contextFiles`, but a child needs to disable pooling. In most cases, you should not need to set this property - it defaults appropriately based on whether `contextFiles` is specified.

    Default behavior:

    - If `contextFiles` is specified: `useContextFiles` defaults to true
    - If `contextFiles` is not specified: `useContextFiles` defaults to false

    This is an advanced option. Most applications should rely on the default auto-enabling behavior and never need to explicitly set this property.

    Default value is *see documentation*

    See Also:
      - `contextFiles`

  - ### invalidateCache

    public Boolean invalidateCache
    If set, every invocation of this operationBinding will invalidate the local cache, forcing a server visit to refresh the data.

    Default value is null

  - ### cacheSyncOperation

    public String cacheSyncOperation
    For an operationBinding of `operationType` "add" or "update", this property is the `operationId` of a "fetch" operationBinding to use for cache synchronization purposes (ie, to fetch the row most recently added or changed). This property, along with `useForCacheSync` and `canSyncCache` is provided so that you can use custom database operations without sacrificing the benefits of Smart GWT's automatic cache synchronization.

    This property is not applicable to the built-in `Hibernate` and `JPA` DataSources.

    Please also read the overview article on `CacheSynchronization` for full details of all the cache sync options

    Default value is null

    See Also:
      - `useForCacheSync`
      - `canSyncCache`
      - `Automatic Cache Synchronization`

  - ### requiresRole

    public String requiresRole
    Comma-separated list of user roles that are allowed to invoke the operation described by this operationBinding. If the current user has any of the roles listed, they can invoke the operation. Also note that `authentication.superuserRole` can be specified in the `server.properties` file. If set this denotes a "super user" role - any user with that role will have access to all operations, regardless of the "requiresRole" settings for the operation.

    Whether the current user has a given role is determined by calling the standard Java servlets method `httpServletRequest.isUserInRole()`, hence works with both simple J2EE security (realms and form-based authentication) and JAAS (Java Authentication & Authorization Service).

    If you wish to use a role-based security scheme that does not make use of the servlet API's standards, Smart GWT Server also implements the `setAuthenticated` and `setUserRoles` methods on `RPCManager`. You can use this API to tell Smart GWT that all the requests in the queue currently being processed are associated with a user who has the roles you supply; in this case, Smart GWT will not attempt to resolve the user's roles via `httpServletRequest.isUserInRole()`. When taking this approach, the `rpcManager.setUserRoles()` method should be called on the server for each transaction received from the client. We recommend doing this by overriding the special IDACall servlet and checking server side state to determine the current user's roles, calling the API, and then calling `handleDSRequest()` or `handleRPCRequest()` directly to handle the request(s) passed in.
    Here's an example of this approach which assumes the current user's roles has been set directly on the HttpSession object as a comma-separated-string attribute "roles":

           public class SecureIDACall extends IDACall {

               public void processRequest(HttpServletRequest request,
                       HttpServletResponse response)
                throws ServletException, IOException
               {
                   HttpSession session = request.getSession();
                   Object roles = session == null ? null : session.getAttribute("roles");

                   if (roles != null) {
                       try {
                           RequestContext context = RequestContext.instance(this, request, response);
                           RPCManager rpc = new RPCManager(request, response);
                           rpc.setAuthenticated(true);
                           rpc.setUserRoles((String) roles);

                           // call processRPCTransaction() to iterate through all RPCRequests and
                           // DSRequests and execute them
                           processRPCTransaction(rpc, context);

                       } catch (Throwable e) {
                           handleError(response, e);
                       }
                   } else {
                       super.processRequest(request, response);
                   }
               }
           }

    If there is an operationBinding declared for a given operationType which does not have an `operationId`, that is, it is the default operationBinding for the type, then any other operationBinding of the same type is assumed to have the same setting for `requiresRole` as the default operationBinding for the operationType. For example, given these declarations:

              <operationBinding operationType="fetch" requiresRole="manager">
                    ... settings ...
               </operationBinding>
              <operationBinding operationType="fetch" operationId="fetchWithExtraFields">
                    ... settings ...
               </operationBinding>

    The second operationBinding requires the "manager" role even though there is no explicit `requiresRole` declaration. To prevent the "manager" role being required by the second operationBinding, add `requireRole=""`.

    Note that if `DataSource.requiresRole` is set, all operations on the DataSource require the roles set for the DataSource as a whole, even if they declare individual `requiresRole` attributes.

    This property is valid only for a server-side DataSource when using the Smart GWT Server.

    ### Special rules for cache sync

    After successfull "add" or "update" operation cache sync request is performed, which is using "fetch" operation of the same datasource. It may happen that user is allowed to add records, but is not allowed to fetch them, for example:

              <operationBinding operationType="fetch" requiresRole="admin">
                    ... settings ...
              </operationBinding>
              <operationBinding operationType="add">
                    ... settings ...
              </operationBinding>

    User without "admin" role will be able to successfully add record, but the cache sync operation will fail due to security violation. In this case the record will be saved to database, but the added record will not be fetched from database, instead just `old values` overlaid with submitted values will be returned. So, any changes made to the new record during request execution, including generated values for primary key fields of "sequence" type, will not be returned to the client.

    However, if "add" or "update" operation explicitly declares `cacheSyncOperation`, cache sync request will be executed even if the user does not meet the security checks for the operationBinding. Note that field-level security still will be respected and disallowed fields will be excluded from returned data.

    Default value is null

    See Also:
      - `Declarative Security`

  - ### requestTemplate

    public String requestTemplate
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of the `DataSource.requestTemplate` - see that property's documentation for details

    Default value is null

    See Also:
      - `DataSource.requestTemplate`
      - `transformRequestScript`
      - `responseTemplate`
      - `Server-side REST Connector`

  - ### exportFilename

    public String exportFilename
    The name of the file to save the exported data into.

    Default value is null

  - ### useFlatFields

    public boolean useFlatFields
    Setting `useFlatFields` on an operationBinding is equivalent to setting `DSRequest.useFlatFields` on all DataSource requests with the same `operationType` as this `operationBinding`.

    Typical usage is to combine operationBinding.useFlatFields with `searchForm.useFlatFields`, with the `SearchForm` bound to the `input message` of the web service operation set as `wsOperation`. This allows gratuitous nesting to be consistently bypassed in both the user presentation and in the actual XML messaging.

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

    Default value is false

    See Also:
      - `Client-side Data Integration`

  - ### process

    public Process process
    Declares a server-side workflow `Process` to execute for this operation, as a declarative alternative to `script` or a `DMI`.

    The process can be specified as:

    - Inline Process definition: XML Process element within the operationBinding (editable by `com.smartgwt.client.tools.WorkflowEditor`)
    - Process ID: String ID resolved via `Process.loadProcess()` from .proc.xml files

    The process receives automatic input state derived from the DSRequest (see `ServerProcess` for full mapping).

    Response: If `process.state.dsResponse` is set, it becomes the operation response. Otherwise, the output of the last `DSRequestTask` is used. See `ServerProcess` for the full precedence order.

    Error Handling: If any task fails and has no `DSRequestTask.failureElement`, the operation returns STATUS_FAILURE. If the operation participates in a transaction (`autoJoinTransactions`), it rolls back.

    Only synchronous task types are supported (DS*Tasks, ScriptTask, DecisionTask, SubProcessTask, etc.). UI-interaction tasks are not applicable in the server-side context.

    Default value is null

    See Also:
      - `script`
      - `Process`
      - `com.smartgwt.client.tools.WorkflowEditor`
      - `Server-Side Process Execution`

  - ### cacheSyncStrategy

    public CacheSyncStrategy cacheSyncStrategy
    The `cacheSyncStrategy` to use for this operation. Overrides any `dataSource-level cacheSyncStrategy`

    Default value is null

    See Also:
      - `DataSource.cacheSyncStrategy`
      - `com.smartgwt.client.data.DSRequest#getCacheSyncStrategy`
      - `Automatic Cache Synchronization`

  - ### xmlTag

    public String xmlTag
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.xmlTag` - see that property's documentation for details

    Default value is null

    See Also:
      - `Server-side REST Connector`

  - ### canSyncCache

    public Boolean canSyncCache
    For an operation of type "add" or "update", a SQLDataSource will normally obtain data to return to the client by performing the "cacheSyncOperation": a SELECT statement that retrieves the modified record by primary key. This accommodates sequence columns, columns with default values, database triggers and other database features that may modify data after insertion or update.

    Certain major SQL customizations can prevent the SQLDataSource from authoritatively determining the primary key used in the SQL statement, such that re-selecting the saved record may fail. By default, when `canSyncCache` has not been explicitly set, in the following cases it is assumed that the normal cacheSyncOperation cannot be used:

    - <customSQL> has been used to define an entirely custom query
    - a custom <whereClause> has been defined for an "update" or "remove" operation
    - a custom <valuesClause> has been defined for an "add" operation
    If any of these cases apply or if `canSyncCache` has been set false, the server will skip the cacheSyncOperation and return a DSResponse where `DSResponse.invalidateCache` has been set to true to notify client-side components that they may need to refresh their entire cache.

    Alternatively, if the default re-selection behavior will not work but a customized SQL query would work, you can define that SQL operation as another operationBinding and use `cacheSyncOperation` to declare that it should be used. Setting `cacheSyncOperation` implicitly sets `canCacheSync` to true.

    Note, setting this property to false inhibits cache synchronization for most DataSource types - it is not specific to SQL DataSources. However, it is not applicable to the built-in `Hibernate` and `JPA` DataSources. See the `cache sync overview` for further details.

    Default value is null

    See Also:
      - `useForCacheSync`
      - `cacheSyncOperation`
      - `Automatic Cache Synchronization`

  - ### script

    public String script
    Scriptlet to be executed prior to the DataSource operation which is configured by this operationBinding. This setting overrides any `script specified at the DataSource level` for this operation.

    Scriptlets are used similarly to DMIs configured via `serverObject` - they can add business logic by modifying the DSRequest before it's executed, modifying the default DSResponse, or taking other, unrelated actions.

    Scriptlets are used similarly to DMIs configured via `DataSource.serverObject` or `serverObject` - they can add business logic by modifying the DSRequest before it's executed, modifying the default DSResponse, or taking other, unrelated actions.

    For example:

             <operationBindings>
                <operationBinding operationType="add">
                    <script language="groovy">
                       ... Groovy code ...
                    </script>
                </operationBinding>
             </operationBindings>

    Scriptlets can be written in any language supported by the "JSR 223" standard, including Java itself. See the `DMI Script Overview` for rules on how to return data, add additional imports, and other settings.

    The following variables are available for DMI scriptlets:

    - dataSource: the current DataSource
    - dsRequest: the current DSRequest
    - criteria: shortcut to DSRequest.getCriteria() (a Map)
    - values: shortcut to DSRequest.getValues() (a Map)
    - oldValues: shortcut to DSRequest.getOldValues() (a Map)
    - sqlConnection: SQLDataSource only: the current SQLConnection object. If using `automatic transactions` are enabled, this SQLConnection is in the context of the current transaction.
    - beanFactory: the spring BeanFactory (when applicable)
    - cdiBeanManager: the CDI BeanManager (when applicable)

    Scriptlets also have access to a set of contextual variables related to the Servlets API, as follows:

    - servletRequest: the current ServletRequest
    - session: the current HttpSession
    - rpcManager: the current RPCManager
    - servletResponse: the current ServletResponse (advanced use only)
    - servletContext: the current ServletContext(advanced use only)
    As with DMI in general, be aware that if you write scriptlets that depend upon these variables, you preclude your DataSource from being used in the widest possible variety of circumstances. For example, adding a scriptlet that relies on the `HttpSession` prevents your DataSource from being used in a command-line process.

    Note that if a dataSource configuration has both a `<script>` block and a specified `serverObject` for some operation, the script block will be executed, and the serverObject ignored.

    Default value is null

  - ### autoJoinTransactions

    public Boolean autoJoinTransactions
    If true, causes requests against this operation to automatically start or join a transaction. if false, causes requests against this operation to be committed individually. If null, falls back to `DataSource.autoJoinTransactions`.

    See `DataSource.autoJoinTransactions` for further details of Smart GWT's automatic transaction control.

    Default value is null

  - ### progressiveLoading

    public Boolean progressiveLoading
    Sets `progressive loading mode` for this particular operation, overriding the DataSource-level setting. Note that this setting applies only to fetch operations - it has no effect if specified on any other kind of operation.

    Default value is null

    See Also:
      - `DataSource.progressiveLoading`
      - `Progressive Loading`

  - ### useSpringTransaction

    public Boolean useSpringTransaction
    Sets or clears the `useSpringTransaction` flag for this specific operation.

    See `DataSource.useSpringTransaction` for details of the Spring transaction integration feature

    Default value is null

  - ### valuesClause

    public VelocityExpression valuesClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke set of values to add or update, for use when constructing the SQL query to perform this operation. The property should be one of the following, depending on the `operationType`:

    For "add" operations, the syntax that would be valid for an INSERT INTO query: a comma-separated list of column names enclosed in parentheses, followed by a comma-separated list of new values, enclosed in parentheses and preceded by the token "VALUES". For example:

    `<valuesClause>(name, age) VALUES("Jane Doe", 48)</valuesClause>`

    For "update" operations, the syntax that would be valid for an UPDATE query: a comma-separated list of expressions equating a column name to its new value. For example:

    `<valuesClause>name="Jane Doe", age=48</valuesClause>`

    You may find the Smart GWT-provided $values variable of particular use with this property.

    See the documentation for `customSQL` for usage examples

    Default value is null

    See Also:
      - `customSQL`
      - `Custom Querying Overview`

  - ### applySqlPrefixToRowCount

    public Boolean applySqlPrefixToRowCount
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For operations on DataSources of `serverType` "sql" only, if `sqlPrefix` is specified at either operation or DataSource level, should that prefix also be applied to the rowcount query, if one is run? This property is true by default, meaning we will apply the prefix to both rowcount and main queries

    This property is ignored for non-SQL dataSources

    This property can also be specified at the `DataSource level`; any such value acts as a default for the dataSource, and will be overridden by an operationBinding-level setting

    Default value is true

    See Also:
      - `applySqlSuffixToRowCount`
      - `Custom Querying Overview`

  - ### skipRowCount

    public Boolean skipRowCount
    A SQLDataSource will normally issue two queries for a "fetch" operation when paging is enabled: one to determine the total rows available (the "row count query"), and one to fetch the specific range of rows requested.

    Setting skipRowCount="true" will avoid the "row count query", but as a consequence `DSResponse.totalRows` will be set to match the requested `DSRequest.endRow` since the totalRows is unknown. You can avoid this by using a `paging strategy` of "jdbcScroll" or "dropAtServer", but be aware that these paging strategies can introduce significant delays when used with potentially large datasets (in fact, "dropAtServer" is almost guaranteed to do so if used with datasets of more than 1000 or so rows)

    As an alternative, consider enabling `progressive loading`, which avoids doing a query for row counts, but will still allow the user to load more results using the scrollbar if viewing results in a ListGrid.

    Default value is null

  - ### whereClause

    public VelocityExpression whereClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke WHERE clause to use when constructing the SQL query to perform this operation. The property should be a valid expression in the syntax of the underlying database. The server will insert the text of this property immediately after the "WHERE" token.

    You may find the Smart GWT-provided $criteria variable of particular use with this property.

    See the documentation for `customSQL` for usage examples

    Default value is null

    See Also:
      - `customSQL`
      - `Custom Querying Overview`

  - ### operationType

    public DSOperationType operationType
    Which operationType this operationBinding is for. This property is only settable on an operationBinding, not a DataSource as a whole.

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### orderClause

    public VelocityExpression orderClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke ORDER BY clause to use when constructing the SQL query to perform this operation. The property should be a comma-separated list of column names and/or expressions, forming a valid ORDER BY clause in the syntax of the underlying database. The server will insert the text of this property immediately after the "ORDER BY" token.

    This property is only applicable to operationBindings of `operationType` "fetch".

    See the documentation for `customSQL` for usage examples

    Default value is null

    See Also:
      - `customSQL`
      - `Custom Querying Overview`

  - ### wrapInList

    public Boolean wrapInList
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.wrapInList` - see that property's documentation for details

    Default value is false

    See Also:
      - `Server-side REST Connector`

  - ### unionFields

    public String unionFields
    Only applicable to "union" dataSources, this is a comma-separated list of the names of the dataSource fields that make up the union. This property overrides the DataSource-level setting of the same name.

    Note, this property can only be used to narrow the list of fields in the union, not to widen it. In other words, only fields that are included at the dataSource level - either by specifying an explicit `unionFields` property or by automatically deriving a list of fields according to the `DataSource.defaultUnionFieldsStrategy` - can be named in the operationBinding-level `unionFields` declaration.

    Default value is null

    See Also:
      - `DataSource.unionFields`
      - `Union DataSources`

  - ### requiresWhen

    public AdvancedCriteria requiresWhen
    ServerDynamicCriteria evaluated server-side to determine whether the current operation is allowed. Unlike `requiresRole` (which checks the user's static roles) and `requires` (which evaluates a Velocity expression), `requiresWhen` can reference record field values, authentication context, and related records.

    When both `requiresRole` and `requiresWhen` are set, both must pass — `requiresRole` is evaluated first (cheap static check), and `requiresWhen` only runs if the role check passes.

    Behavior by operation type:

    - fetch: the criteria are merged into the request as an additional filter — non-matching rows are silently excluded from the response.
    - add: the criteria are evaluated against the submitted record values. If they don't match, the add is denied.
    - update / remove (single-record): the criteria are evaluated against the existing record (pre-modification state, fetched from the database — client-sent oldValues are not trusted for security). If they don't match, the operation is denied.
    - update / remove (with `allowMultiUpdate`): the criteria are merged into the operation's criteria as an additional filter. Only rows matching the `requiresWhen` criteria are affected; non-matching rows are silently skipped. This prevents a multi-update from bypassing per-record access control.

    When a single-record operation is denied, the server returns a generic authorization-failure message that does not reveal which criteria failed or what field values were checked.

    Example: allow updates only when the record is not locked:

          <operationBinding operationType="update">
            <requiresWhen fieldName="status" operator="notEqual"
                           value="locked"/>
          </operationBinding>

    Example: only users with the "editor" role can update records whose related Order is still in process:

          <operationBinding operationType="update">
            <requiresWhen operator="and">
              <criteria fieldName="auth.roles" operator="contains"
                        value="editor"/>
              <criteria fieldName="Order.status" operator="equals"
                        value="In Process"/>
            </requiresWhen>
          </operationBinding>

    Default value is null

    See Also:
      - `requiresRole`
      - `requires`
      - `Declarative Security`

  - ### useSubselectForRowCount

    public Boolean useSubselectForRowCount
    Whether to use the subselect technique (see `DataSource.useSubselectForRowCount` for details) to derive a rowcount query for this operation. If this property is not set, we fall back to the `useSubselectForRowCount` setting on the DataSource, and the defaults described in the documentation for that property.

    Default value is null

    See Also:
      - `DataSource.useSubselectForRowCount`
      - `customSQL`

  - ### includeAnsiJoinsInTableClause

    public Boolean includeAnsiJoinsInTableClause
    This setting makes difference if `ANSI-style joins` are in use. If true, causes ansi joins to be included in `$defaultTableClause`, otherwise ansi joins will be put into separate `$defaultAnsiJoinClause`.

    If omitted, system-wide `sql.includeAnsiJoinsInTableClause` setting from `server.properties` will be used. If it is missing as well, `false` is the default.

    Default value is null

    See Also:
      - `DataSource.useAnsiJoins`
      - `ansiJoinClause`

  - ### sqlType

    public SQLType sqlType
    For dataSources of `serverType` "sql" and "hibernate" only, this property determines whether "custom" operations have their custom SQL or HQL sent to the underlying database via a JDBC `executeQuery()` or a JDBC `executeUpdate()`. The default value of null means the same as "query", so you only need to use this property when your custom SQL or HQL updates data.

    Default value is null

    See Also:
      - `Custom Querying Overview`

  - ### multiInsertStrategy

    public MultiInsertStrategy multiInsertStrategy
    For "add" operations on dataSources of `serverType` "sql" only, this property sets the multi-insert strategy for this `operation`. Only has an effect if the `add request` specifies a list of records as the data.

    Note that this setting overrides the equivalent `dataSource setting`, and can in turn be overridden at the `DSRequest level`

    Default value is null

    See Also:
      - `multiInsertBatchSize`
      - `multiInsertNonMatchingStrategy`

  - ### csvQuoteCharacter

    public String csvQuoteCharacter
    Applies to RestConnector dataSources (`serverType` "rest") only. This is an operationBinding-level override of `DataSource.csvQuoteCharacter` - see that property's documentation for details

    Default value is '"'

    See Also:
      - `Server-side REST Connector`

  - ### isDDL

    public Boolean isDDL
    Only applicable to "sql" dataSources. This property should be set to `true` if your operation runs Data Definition Language (DDL) statements rather than Data Manipulation Language (DML) statements. DDL statements are concerned with creating, altering and dropping database objects, rather than fetching and updating data. Some examples of DDL statements:

             CREATE VIEW myView ...
             ALTER TABLE myTable DROP CONSTRAINT PK_myTable
             DROP DATABASE xyz
             TRUNCATE TABLE myTable

    When `isDDL` is true, we switch off certain JDBC flags to inhibit the return of generated key information. This generated key information is very important in supporting Smart GWT's automatic cache-synchronization features, but it is never needed for DDL statements. In fact, the concept of generated keys makes no sense in the context of DDL, and asking for this information anyway causes broken behavior in some cases, with some databases (PostgreSQL and Microsoft SQL Server are the two products known to exhibit problems at the time of writing, but there may be others)

    The default value of `null` is equivalent to `false`, and means that this is an ordinary DML (data fetch or update) operation.

    Default value is null

  - ### transformMultipleFields

    public Boolean transformMultipleFields
    If set to "false", transformation of values for `multiple:true` fields, normally controlled by `DataSourceField.multipleStorage`, is instead disabled for this OperationBinding.

    Default value is null

  - ### skipAudit

    public Boolean skipAudit
    Setting `skipAudit` to `true` indicates that `auditing` must be skipped for this operationBinding.

    Note, that this setting can be overridden by server-side API `DSRequest.setSkipAudit()`.

    Default value is null

  - ### beanClassName

    public String beanClassName
    A per-operationBinding setting for beanClassName, otherwise also settable at the top-level DataSource configuration.

    Default value is null

    See Also:
      - `DataSource.beanClassName`
      - `Client-side Data Integration`

  - ### serverMethod

    public String serverMethod
    The name of the method to invoke on the `ServerObject` for this operationBinding.

    NOTE: If you have a `DataSource-level ServerObject` and wish to override this operation so that it simply calls a different method on the same server object, it is sufficient to specify just this property on the operationBinding: there is no need to redefine the serverObject at the operationBinding level.

    Default value is null

  - ### contextPoolSize

    public Integer contextPoolSize
    Maximum number of pooled Graal JavaScript contexts to maintain for this OperationBinding's `contextFiles` configuration.

    OperationBindings with the same canonical `contextFiles` configuration share a context pool. If a later request for the same pool specifies a larger `contextPoolSize`, the pool size is increased to that larger value and a server warning is logged. Smaller values do not shrink an existing pool.

    When all contexts in the pool are in use, additional requests will block until a context becomes available. Higher values support more concurrent requests, but consume more memory because each context holds loaded JavaScript modules in memory.

    Typical values range from 3 to 10 depending on expected concurrency and available memory. The default value of 5 is appropriate for most applications.

    Can also be configured globally via `server.properties`:

            scripting.graal.contextPool.maxPoolSize: 5

    Default value is 5

  - ### namedQuery

    public String namedQuery
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "jpa" or "hibernate", this property can be specified on an operationBinding to indicate that the server should execute a named query which has already been defined on an entity.

             @Entity
             @Table (name="Countries")
             @NamedQuery(name = "Country.withPopulationLessThan", query = "SELECT country FROM Country country WHERE country.population < :population")
             public class Country { ... }

             <operationBindings>
                 <operationBinding operationType="custom" operationId="withPopulationLessThan" namedQuery="Country.withPopulationLessThan"/>
             </operationBindings>

    Substitution values can be used in order to build more dynamic named queries. When calling `DataSource.performCustomOperation()` the values are passed in using the data argument.

    Note that value substitution for named queries is slightly different to other custom queries. Because of the way the persistence API works the JQL query written in the @NamedQuery annotation can only contain basic parameter names such as "population". Therefore the value substitution becomes a simple name based mapping.

    ### Examples

    Using Simple Criteria
    An example using a simple criteria for the above defined Country entity. In this case the named query parameter ":population" will be swapped out for the value of the criteria objects "population" field.

             var criteria = {
                 population: 596000
             };

             countryDataSource.performCustomOperation("withPopulationLessThan", criteria);

    Using Advanced Criteria
    If an advanced criteria is detected, access to all "fieldName" variables and their values will be provided but still using simple name based mapping. In the below case only the deep-first occurrence of the "population" fieldName will available. The operator is effectively ignored.

             var criteria = {
                 _constructor: "AdvancedCriteria",
                 operator:"or",
                 criteria:[
                     {
                         fieldName:"population",
                         operator:"lessThan",
                         value: 12000
                     },
                     {
                         fieldName:"name",
                         operator:"equals",
                         value: "Sweden"
                     },
                     {
                         _constructor: "AdvancedCriteria",
                         operator:"and",
                         criteria:[
                             {
                                 fieldName:"population",
                                 operator:"lessThan",
                                 value: 0
                             }
                         ]
                     }
                 ]
             };

             countryDataSource.performCustomOperation("withPopulationLessThan", criteria);

    Note
    Using namedQuery affects paging implementation. If you use it, full data set is fetched from JPA and records that aren't in the requested range are dropped at the server side.

    Default value is null

    See Also:
      - `customSQL`
      - `DataSourceField.customSQL`
      - `Custom Querying Overview`

  - ### applyCriteriaBeforeAggregation

    public Boolean applyCriteriaBeforeAggregation

    Default value is null

    See Also:
      - `filterBeforeGrouping`

  - ### tableClause

    public VelocityExpression tableClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke table clause to use when constructing the SQL query to perform this operation. The property should be a comma-separated list of tables and views, and you can use any special language constructs supported by the underlying database. The server will insert the text of this property immediately after the "FROM" token.

    See the documentation for `customSQL` for usage examples

    Default value is null

    See Also:
      - `customSQL`
      - `includeAnsiJoinsInTableClause`
      - `Custom Querying Overview`

  - ### exportAs

    public ExportFormat exportAs
    The format in which the data should be exported. Default is "csv". See `ExportFormat` for more information.

    Default value is "csv"

  - ### defaultParams

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

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### values

    public DSRequestModifier[] values
    Elements of this feature are only available with Power or better licenses. See smartclient.com/product for details.

    A list of `DSRequestModifier`s that will be used to modify the values object of each `DSRequest` that uses this operationBinding. See this example: Master/Detail Add Example.

    Below example of the xml as it should be defined in ds.xml: `<operationBinding operationType="add"> <values fieldName="orderID" value="$responseData.last('queuedAdd_order','add').orderID" /> </operationBinding>`

    Default value is null

    See Also:
      - `criteria`
      - `Transaction Chaining`

  - ### requestFormat

    public RESTRequestFormat requestFormat
    For a `RestConnector DataSource`, the request format to use for this specific operationBinding. Overriddes any `DataSource-level setting`. Note, if `requestFormat` is not specified at either the DataSource or OperationBinding level, the request will be rejected.

    Default value is null

    See Also:
      - `Server-side REST Connector`

  - ### makeKeysAvailable

    public Boolean makeKeysAvailable
    For an operation of type "add" or "update", a SQLDataSource will normally obtain data to return to the client by performing the `cacheSyncOperation`. In certain edge cases this is either not possible or causes problems (such as record locks); in this case, you mark the operation with `canSyncCache`: false to inhibit this automatic behavior. However, this gives you an operation that does not properly cooperate with the client in keeping client-side caches fresh, which in turn leads to an application that must perform more server turnarounds and explicit database fetches.

    It is possible that the data needed for cache synchronization could be obtained by application code running in a DMI or `server script`, even if the normal automatic cache synchronization will not work. However, such application code is almost certainly going to need to know the primary key(s) of any newly added record(s).

    When `makeKeysAvailable` is true, Smart GWT Server will go through the process of obtaining generated keys in accordance with the `SequenceMode`, even if `canSyncCache` is false (note, "in accordance with the `sequenceMode`" implies that we do not attempt to get keys if the `sequenceMode` is "none"). The keys used in the operation (both generated keys, if any, and any keys provided in the operation's criteria or values) will be stored on the `DSResponse` and your server-side DMI or script will have access to them via the server API `dsResponse.getKeys()`. Please see the server-side documentation for that method for further details.

    Note, if you are using `SequenceMode` "jdbcDriver", the keys are available to Smart GWT Server at no cost, so `makeKeysAvailable` is always true. If you are using `sequenceMode` "native", a separate native query must be run to obtain the keys. The overhead of this native query is likely to be insignificant, but because it is an extra step that you may not want or need, `makeKeysAvailable` defaults to false in this case. You can override this by adding setting `sql.always.makeKeysAvailable:true` to your `server.properties` file.

    This property is only applicable to DataSources of type "sql".

    Default value is See below

    See Also:
      - `canSyncCache`
      - `cacheSyncOperation`
      - `Custom Querying Overview`

  - ### poolJSContext

    public Boolean poolJSContext
    Controls whether a Graal JavaScript context can be pooled and reused for `server-side JavaScript scriptlets` that use `contextFiles`.

    When true (the default), contexts are returned to a pool after script execution and can be reused by subsequent requests. When false, this OperationBinding uses the normal server-side JavaScript script evaluation path; `contextFiles` and `operationFiles` are not applied.

    Setting this to false disables the performance benefit of context pooling, but may be useful for debugging scenarios where you want to avoid reusing a pooled execution environment.

    This is an advanced option. Most applications should leave this at the default value of true for optimal performance.

    Default value is true

  - ### guestUserId

    public String guestUserId
    Value to use for the `ownerIdField` if no one has authenticated.

    Overrides the same setting at the `DataSource` level.

    Default value is null

    See Also:
      - `ownerIdField`
      - `DataSource.guestUserId`

  - ### recordXPath

    public XPathExpression recordXPath
    For an XML or JSON, JSON or `RestConnector` DataSource, an XPath expression used to retrieve the objects that will become DataSource records.

    For example, an "ItemSearch" web service might return a "Results" structure containing metadata along with the set of Items that one might want to display in a grid. An XPath expression like "/Results/Items" could be used to retrieve just the Items, which would then become DataSource records.

    For a JSON web service, the `recordXPath` is applied to the returned JSON data via `XMLTools.selectObjects()`. Only limited XPath syntax is allowed; see `selectObjects()` for details.

    For processing XML results, see `xmlNamespaces` for information on the namespaces that are available in this XPath expression. If you are contacting a WSDL web service, note that `recordName` is an alternative way to specify which records should be selected by their tagName or type, and this is usually simpler.

    To learn about XPath, try the following search: http://www.google.com/search?q=xpath+tutorial

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### allowMultiUpdate

    public Boolean allowMultiUpdate
    Ordinarily, "update" and "remove" operations are only allowed for `DataSource`s that have a `primaryKey`, and all primary key values are present in the request. This is because an update of a DataSource with no primary key, or an update request that has missing primary key values, cannot be guaranteed to affect only one record.

    Setting this property on an operationBinding circumvents this restriction for that operation only.

    Warning: Be aware that this is a potentially dangerous setting and should be used with care. With this flag set, you have no guarantee that an update will not change or remove every row in a table.

    Note, in the case of doing an update or delete operation with a primary key and additional criteria, allowMultiUpdate must be set or additional criteria will be dropped and just the primary key fields will be used in criteria.

    Also, running `allowMultiUpdate` operations directly from the client is not straightforward because it requires the ability to specify criteria and values separately in the request, which is not currently supported. This can be worked around in various ways, but really `allowMultiUpdate` is primarily intended for server-side operations. Therefore, the recommended pattern is to use a `custom operation` from the client to invoke a DMI on the server which performs the multi-update operation via a second, server-side DSRequest.

    In any case, it's normally a good idea to set `requiredCriterion` on the multi-update operation to ensure that the alternative criteria is present as expected.

    Default value is null

    See Also:
      - `providesMissingKeys`
      - `DataSource.defaultMultiUpdatePolicy`

  - ### spoofResponses

    public boolean spoofResponses
    For a DataSource contacting a `WSDL web service`, setting this flag means the DataSource doesn't actually attempt to contact the server but generates a sample response instead, based on the XML Schema of the response message embedded in the WSDL.

    The spoofed response will include all complexType elements and will fill in appropriate values by type for all simpleType elements, although the spoofed data will not conform to all xs:restriction declarations (eg xs:pattern).

    Note that if your WSDL does not fully describe the response format (some WSDL services just have a placeholder <xs:any> element), Smart GWT can only produce a partial response. To use a hand-generated sample response, just save an XML file to disk and use the `dataURL` setting to point to it.

    Default value is false

    See Also:
      - `Client-side Data Integration`

  - ### sqlUsePagingHint

    public Boolean sqlUsePagingHint
    If explicitly set true or false, forces the use of a "hint" in the SQL we generate for paged queries on or off as appropriate. If not set, defaults to the `DataSource.sqlUsePagingHint` value. Note this property is only applicable to `SQL` DataSources, only when a `paging strategy` of "sqlLimit" is in force, and it only has an effect for those specific database products where we employ a native hint in the generated SQL in an attempt to improve performance.

    Default value is null

    See Also:
      - `DataSource.sqlUsePagingHint`

  - ### dataURL

    public String dataURL
    URL to contact to fulfill DSRequests for this operationBinding.

    `dataURL` is typically set as `DataSource.dataURL` rather than on each individual operationBinding. However, when using `dataURL` to configure the server side of a `RestConnector`, it is common to set `dataURL` at the operationBinding level, as described in the `DataSource-level dataURL` documentation.

    `dataURL` can be omitted for a DataSource using a Web Service (`DataSource.serviceNamespace` is set).

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### sqlPrefix

    public VelocityExpression sqlPrefix
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For operations on DataSources of `serverType` "sql" only, some text to add right at the beginning of the query generated for this specific operation, before all other text. This can be plain text or a `Velocity template`. Like `DataSource.sqlSuffix`, this property allows for non-standard SQL extensions that may be required to obtain some special, database-specific behavior. For example, Oracle database supports hints specified in comments that appear before the main query text, like this:

             /* ALL_ROWS */  SELECT * FROM MyTable

    This property is ignored for non-SQL dataSources

    `sqlPrefix` can also be specified at the `DataSource level`; any such value acts as a default for the dataSource, and will be overridden by an operationBinding-level setting

    You can alternatively provide SQL prefix text programmatically, by overriding `getSQLPrefix()` in a `custom DataSource implementation`

    Default value is null

    See Also:
      - `Custom Querying Overview`

  - ### operationId

    public String operationId
    Optional operationId if this DataSource supports two or more variants of one of the basic DataSource operations, for instance, a "fetch" that uses full text search and a "fetch" that accepts per-field search criteria. See `DSRequest.operationId` for usage.

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### ownerIdField

    public String ownerIdField
    Overrides the same setting at the `DataSource` level, for this operation only. See the dataSource-level documentation for details.

    Default value is null

    See Also:
      - `DataSource.ownerIdField`
      - `guestUserId`

  - ### providesMissingKeys

    public Boolean providesMissingKeys
    Ordinarily, "update" and "remove" operations are only allowed if all primary key values are present in the request. This is because an update request that has missing primary key values cannot be guaranteed to affect only one record.

    Setting this property on an operationBinding circumvents this restriction for that operation only. Note, this property differs from `allowMultiUpdate` in its intent: `allowMultiUpdate` tells the framework that this operation deliberately affects multiple records; `providesMissingKeys` tells the framework that this operation will only affect one record, and will ensure this by providing values for missing keys during its operation. Unlike `allowMultiUpdate`, setting this flag does not cause component caches to be `invalidated`

    Providing values for missing keys can be done in various ways:

    - Operations that specify `<`customSQL`>` or `<`whereClause`>` can provide missing key values from session storage or elsewhere in the provided record
    - Operations that specify `<`script`>` can provide arbitrary code to manipulate the record in whatever way they like before executing the underlying built-in functionality
    - Operations can specify `<`criteria`>` to provide missing keys
    - A request can contain `fieldValueExpressions`, which can be used to provide values for missing keys
    Note, you can also use a regular `DMI` to arbitrarily manipulate the record sent from the client, including providing values for any missing keys. If you do this, you do not need to specify `providesMissingKeys` because the request is not validated for the presence of key values until after the DMI has run.

    Warning: Be aware that this is a potentially dangerous setting and should be used with care. With this flag set, the framework cannot guarantee that an update will not change or remove every row in a table: it becomes your code's responsibility to ensure that all PK values are provided to the operation by the time it actually needs them.

    Default value is null

    See Also:
      - `allowMultiUpdate`
      - `DataSourceField.autoGenerated`

  - ### groupClause

    public VelocityExpression groupClause
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", this property can be specified on an operationBinding to provide the server with a bespoke GROUP BY clause to use when constructing the SQL query to perform this operation. The property should be a comma-separated list of column names and/or expressions, forming a valid GROUP BY clause in the syntax of the underlying database. The server will insert the text of this property immediately after the "GROUP BY" token.

    Note that specifying this property enables you to use aggregate functions (such as COUNT and SUM) in your `selectClause`. Also note that care is required when using groupClause to ensure that the selectClause contains the fields you are grouping by. Failure to do this correctly will result in a runtime SQL error.

    This property is only applicable to operationBindings of `operationType` "fetch".

    See the documentation for `customSQL` for usage examples

    Default value is null

    See Also:
      - `customSQL`
      - `selectClause`
      - `Custom Querying Overview`

  - ### customSQL

    public VelocityExpression customSQL
    This feature is available with Power or better licenses only. See smartclient.com/product for details.

    For a dataSource of `serverType` "sql", "hibernate" or "jpa", this property can be specified on an operationBinding to indicate that the server should run user-specified SQL, rather than the query it would normally generate to satisfy a dataSource operation. This property allows you to provide a fully-customized query.

    Hibernate and JPA dataSources also support customizing the query via `customHQL` or `customJQL` respectively.

    For SQL dataSources, as an alternative to `customSQL` you can provide custom "pieces" to the query generator, via properties such `whereClause` and `valuesClause`.
    This feature is not available for Hibernate or JPA DataSources.
    See the `CustomQuerying` for more details.

    For a dataSource of type "sql", the Smart GWT server generates a number of useful `query "pieces"`, and makes them available to your custom SQL code via the Velocity templating language (note that this is not available for "hibernate" dataSources).

    We also make the template variables $criteria and $values available, to give you direct access to the supplied criteria, and to the new field values for update and add operations. These variables are available to both "sql" and "hibernate" dataSources.

    Note that you should use this feature with care. In particular, writing customSQL code that makes use of a particular database engine's features or syntax will make your application less portable.

    See `CustomQuerying` for an overview of writing custom queries and clauses.

    ### Examples

    An example using the Smart GWT-supplied query pieces. This custom query will give exactly the same result as the Smart GWT-generated query:

    `<operationBinding operationId="customFetch" operationType="fetch">
    <customSQL>
    SELECT $defaultSelectClause FROM $defaultTableClause WHERE $defaultWhereClause ORDER BY $defaultOrderClause
    </customSQL>
    </operationBinding>
    `

    An example using the Smart GWT-supplied $criteria template variable:

    `<operationBinding operationId="customFetch" operationType="fetch">
    <customSQL>
    SELECT foo, bar, baz FROM MyTable WHERE bar > $criteria.someValue
    </customSQL>
    </operationBinding>
    `

    An update example:

    `<operationBinding operationId="myUpdateOp" operationType="update">
    <customSQL>
    UPDATE $defaultTableClause SET $defaultValuesClause WHERE bar <= $criteria.someValue
    </customSQL>
    </operationBinding>
    `

    Default value is null

    See Also:
      - `customHQL`
      - `namedQuery`
      - `DataSourceField.customSQL`
      - `Custom Querying Overview`

  - ### arrayCriteriaForceExact

    public Boolean arrayCriteriaForceExact
    Operation-level override for the DataSource-level `arrayCriteriaForceExact` flag. See the documentation for that flag for details.

    Default value is null

    See Also:
      - `Server DataSource Integration`

  - ### sqlPaging

    public SQLPagingStrategy sqlPaging
    The paging strategy to use for this specific OperationBinding. If this property is not set, we fall back to the `DataSource.sqlPaging` value, and the defaults described in the documentation for that property.

    Default value is null

    See Also:
      - `DataSource.sqlPaging`

- ## Constructor Details

  - ### OperationBinding

    public OperationBinding()