OperationBinding (Smart GWT LGPL Edition API 13.1p (2024-12-21))

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

```
public class OperationBinding
extends java.lang.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 and Description
`java.lang.Boolean`	`allowAdvancedCriteria` This property indicates whether this operation supports AdvancedCriteria.
`java.lang.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.
`java.lang.Boolean`	`applyCriteriaBeforeAggregation` If set to "true" all criteria are applied before aggregation and and the `groupWhereClause` is not generated.
`java.lang.Boolean`	`arrayCriteriaForceExact` Operation-level override for the DataSource-level `arrayCriteriaForceExact` flag.
`java.lang.String`	`beanClassName` A per-operationBinding setting for beanClassName, otherwise also settable at the top-level DataSource configuration.
`java.lang.String`	`callbackParam` Applies only to dataFormat: "json".
`java.lang.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.
`DSProtocol`	`dataProtocol` Controls the format in which inputs are sent to the dataURL.
`java.lang.String`	`dataURL` URL to contact to fulfill DSRequests for this operationBinding.
`java.util.Map`	`defaultParams` HTTP parameters that should be submitted with every DSRequest.
`java.lang.String`	`description` An optional description of the operationBinding's behavior.
`ExportFormat`	`exportAs` The format in which the data should be exported.
`java.lang.String[]`	`exportFields` The list of field-names to export.
`java.lang.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.
`java.lang.String`	`forceSort` For DataSources of `serverType` "sql" only, indicates whether we should automatically add a sort field for `paged fetches`.
`java.lang.String[]`	`groupBy` List of fields to group by when using `server-side summarization`.
`java.lang.String`	`guestUserId` Value to use for the `ownerIdField` if no one has authenticated.
`java.lang.Boolean`	`invalidateCache` If set, every invocation of this operationBinding will invalidate the local cache, forcing a server visit to refresh the data.
`java.lang.Boolean`	`isDDL` Only applicable to "sql" dataSources.
`java.lang.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.
`java.lang.String`	`methodArguments` You can explicitly declare the arguments to be passed to `serverMethod` using this attribute.
`java.lang.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`.
`java.lang.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.
`java.lang.String`	`outputs` Specifies, for this operationBinding only, the list of field names that should be returned to the client.
`java.lang.String`	`ownerIdField` Overrides the same setting at the `DataSource` level, for this operation only.
`java.lang.Boolean`	`preventHTTPCaching` Configures `DataSource.preventHTTPCaching` on a per-operationType basis.
`java.lang.Boolean`	`progressiveLoading` Sets `progressive loading mode` for this particular operation, overriding the DataSource-level setting.
`java.lang.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.
`java.lang.String`	`recordName` For an XML DataSource, tagName of the elements to be used as records.
`XPathExpression`	`recordXPath` For an XML or JSON DataSource, an XPath expression used to retrieve the objects that will become DataSource records.
`DSRequest`	`requestProperties` Additional properties to pass through to the `DSRequest` created for this operation.
`java.lang.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.
`java.lang.Boolean`	`requiresAuthentication` Whether a user must be authenticated in order to access this operation.
`java.lang.String`	`requiresRole` Comma-separated list of user roles that are allowed to invoke the operation described by this operationBinding.
`DataSource`	`responseDataSchema` Optional schema describing how to extract DataSource records from the XML elements selected.
`java.lang.String`	`script` Scriptlet to be executed prior to the DataSource operation which is configured by this operationBinding.
`java.lang.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.
`java.lang.Boolean`	`skipAudit` Setting `skipAudit` to `true` indicates that `auditing` must be skipped for this operationBinding.
`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.
`java.lang.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.
`java.util.Map`	`summaryFunctions` A mapping from field names to `summary functions` to be applied to each field.
`java.lang.Boolean`	`transformMultipleFields` If set to "false", transformation of values for `multiple:true` fields, normally controlled by `DataSourceField.multipleStorage`, is instead disabled for this OperationBinding.
`java.lang.String`	`transformRequestScript` Scriptlet to be executed prior to the DataSource operation which is configured by this operationBinding.
`java.lang.String`	`transformResponseScript` Scriptlet to be executed after the DataSource operation which is configured by this operationBinding.
`boolean`	`useFlatFields` Setting `useFlatFields` on an operationBinding is equivalent to setting `DSRequest.useFlatFields` on all DataSource requests with the same `operationType` as this `operationBinding`.
`java.lang.Boolean`	`useHavingClause` This setting switches between "having" clause and sub-select approaches when generating aggregated SQL queries.
`java.lang.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.
`java.util.Map`	`xmlNamespaces` Optional object declaring namespace prefixes for use in `recordXPath` and `DataSourceField.valueXPath` XPath expressions.

Constructor Summary

Constructors
Constructor and Description

OperationBinding()

Constructors
Constructor and Description
`OperationBinding()`

Method Summary
- Methods inherited from class java.lang.Object
  clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - requiredCriterion
```
public java.lang.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
  - recordName
```
public java.lang.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
  - outputs
```
public java.lang.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 java.lang.Boolean preventHTTPCaching
```
    Configures DataSource.preventHTTPCaching on a per-operationType basis.
    Default value is null
  - transformResponseScript
```
public java.lang.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 java.lang.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
  - groupBy
```
public java.lang.String[] groupBy
```
    List of fields to group by when using server-side summarization.
    Valid only for an operation of type "fetch". See the Server Summaries overview for details and examples of usage.
    Default value is null
    
    See Also:
    
    summaryFunctions, Server Summaries
  - lineBreakStyle
```
public java.lang.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
  - 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
  - requiresAuthentication
```
public java.lang.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
  - useHavingClause
```
public java.lang.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 groupWhereClause
    - 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 <groupWhereClause>
  
```
    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 <groupWhereClause>
  
```
    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:
    
    com.smartgwt.client.data.OperationBinding#getGroupWhereClause
  - 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 DSRequestModifiers 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 java.lang.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
  - 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
  - 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
  - summaryFunctions
```
public java.util.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
  - methodArguments
```
public java.lang.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
  - xmlNamespaces
```
public java.util.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
  - creatorOverrides
```
public java.lang.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
  - transformRequestScript
```
public java.lang.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
  - multiInsertBatchSize
```
public java.lang.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
  - exportFields
```
public java.lang.String[] exportFields
```
    The list of field-names to export. If provided, the field-list in the exported output is limited and sorted as per the list.
    If exportFields is not provided, the exported output includes all visible fields from the DataSource (field.hidden=false), sorted in the order they're defined.
    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 java.lang.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 java.lang.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
  - invalidateCache
```
public java.lang.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
  - requiresRole
```
public java.lang.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
  - exportFilename
```
public java.lang.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
  - script
```
public java.lang.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
  - progressiveLoading
```
public java.lang.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
  - 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
  - useSubselectForRowCount
```
public java.lang.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, com.smartgwt.client.data.OperationBinding#getCustomSQL
  - 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
  - isDDL
```
public java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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
  - applyCriteriaBeforeAggregation
```
public java.lang.Boolean applyCriteriaBeforeAggregation
```
    If set to "true" all criteria are applied before aggregation and and the groupWhereClause is not generated.
    This property is only applicable if you are using the SQL DataSource, the other built-in types (Hibernate and JPA/JPA2) always perform filtering before summarization.
    NOTE this property exists principally for backcompat, as the results of apply criteria before aggregation are usually senseless, and in this mode client-side filtering will not match server-side filtering (since client-side filtering is always post-aggregation), so the ability to filter on those fields would need to be disabled in the UI.
    Still, if you have this flag was set to "true" and the "avg" function is being applied to a "price" field, criteria like "price < 5" will eliminate records where price is less than 5 before the average price is calculated. Note that this means that client-side filtering may not work as expected with summarized results: client-side filter criteria are necessarily applied after summary functions have been applied, so may not match the server's behavior. You can set ResultSet.useClientFiltering to disable client-side filtering on a grid via ListGrid.dataProperties. Or individual fields can be marked canFilter:false.
    Note that using CustomQuerying is an ultimate approach to make all kinds of modifications to the way SQL query is generated and with new $sql.partialWhere(fieldNames), $sql.whereWithout(fieldNames), $sql.partialHaving(fieldNames) and $sql.havingWithout(fieldNames) Velocity context APIs you have complete control over the automatically generated criteria.
    Default value is null
    
    See Also:
    
    com.smartgwt.client.data.OperationBinding#getGroupWhereClause
  - 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 java.util.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 DSRequestModifiers 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
  - guestUserId
```
public java.lang.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 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 java.lang.Boolean allowMultiUpdate
```
    Ordinarily, "update" and "remove" operations are only allowed for DataSources 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 java.lang.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 java.lang.String dataURL
```
    URL to contact to fulfill DSRequests for this operationBinding.
    dataURL is typically set as DataSource.dataURL rather than on each individual operationBinding.
    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
  - operationId
```
public java.lang.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 java.lang.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 java.lang.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
  - arrayCriteriaForceExact
```
public java.lang.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 Detail
  - OperationBinding
```
public OperationBinding()
```

Class OperationBinding

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

requiredCriterion

recordName

outputs

preventHTTPCaching

transformResponseScript

qualifyColumnNames

description

groupBy

lineBreakStyle

multiInsertNonMatchingStrategy

mail

dataProtocol

requiresAuthentication

useHavingClause

useHavingClause=true (default)

useHavingClause=false

criteria

callbackParam

exportResults

serverObject

requestProperties

summaryFunctions

methodArguments

requires

xmlNamespaces

creatorOverrides

transformRequestScript

multiInsertBatchSize

exportFields

responseDataSchema

forceSort

allowAdvancedCriteria

invalidateCache

requiresRole

Special rules for cache sync

exportFilename

useFlatFields

script

progressiveLoading

operationType

useSubselectForRowCount

multiInsertStrategy

isDDL

transformMultipleFields

skipAudit

beanClassName

serverMethod

applyCriteriaBeforeAggregation

exportAs

defaultParams

values

guestUserId

recordXPath

allowMultiUpdate

spoofResponses

sqlUsePagingHint

dataURL

operationId

ownerIdField

providesMissingKeys

arrayCriteriaForceExact

sqlPaging

Constructor Detail

OperationBinding