com.smartgwt.client.docs.serverds
Class OperationBinding

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

public class OperationBinding
extends java.lang.Object

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

An operationBinding tells a DataSource how to execute one of the basic DS operations: fetch, add, update, remove. See operationBindings.


Field Summary
 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 DataSources that have a primaryKey, and all primary key values are present in the request.
 java.lang.Boolean autoJoinTransactions
          If true, causes requests against this operation to automatically start or join a transaction.
 java.lang.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).
 java.lang.String callbackParam
          Applies only to dataFormat: "json".
 java.lang.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.
 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.
 java.lang.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".
 java.lang.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".
 java.lang.String customHQL
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 java.lang.String customJQL
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 java.lang.String customSQL
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 java.lang.String[] customValueFields
          Indicates that the listed fields should be included in the default selectClause generated for this operationBinding, even if they are marked customSQL="true".
 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[] 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.
 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[] groupBy
          List of fields to group by when using server-side summarization.
 java.lang.String groupClause
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 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.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.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 orderClause
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 java.lang.String outputs
          Specifies, for this operationBinding only, the list of field names that should be returned to the client.
 java.lang.Boolean preventHTTPCaching
          Configures preventHTTPCaching on a per-operationType basis.
 java.lang.Boolean progressiveLoading
          Sets progressive loading mode for this particular operation, overriding the DataSource-level setting.
 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, 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.
 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 selectClause
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 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 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.
 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().
 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.String tableClause
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 java.lang.Boolean transformMultipleFields
          If set to "false", transformation of values for multiple:true fields, normally controlled by multipleStorage, is instead disabled for this OperationBinding.
 boolean useFlatFields
          Setting useFlatFields on an operationBinding is equivalent to setting 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).
 java.lang.Boolean useSubselectForRowCount
          Whether to use the subselect technique (see 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.lang.String valuesClause
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 java.lang.String whereClause
          This feature is available with Power or better licenses only. See smartclient.com/product for details.
 java.util.Map xmlNamespaces
          Optional object declaring namespace prefixes for use in recordXPath and valueXPath XPath expressions.
 
Constructor Summary
OperationBinding()
           
 
Method Summary
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

customValueFields

public java.lang.String[] customValueFields
Indicates that the listed fields should be included in the default selectClause 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, CustomQuerying overview and related methods

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


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


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

Default value is "callback"

See Also:
DataSource.callbackParam, ClientDataIntegration overview and related methods

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


customFields

public java.lang.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, CustomQuerying overview and related methods

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, ServerSummaries overview and related methods

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


cacheSyncOperation

public java.lang.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 only applicable to DataSources of type "sql".

Default value is null

See Also:
useForCacheSync, canSyncCache, CustomQuerying overview and related methods

customHQL

public java.lang.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 OperationBindings 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, DataSourceField.customSQL, CustomQuerying overview and related methods

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 (serverObject). If neither is present, then Direct Method Invocation will not be enabled for this operationBinding.

Default value is null

See Also:
DataSource.serverObject

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:

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

Default value is true

See Also:
cacheSyncOperation, CustomQuerying overview and related methods

valuesClause

public java.lang.String 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, CustomQuerying overview and related methods

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:

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

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

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


script

public java.lang.String script
Scriptlet to be executed prior to the DataSource operation which is configured by this operationBinding.

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.

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:

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

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.

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, ServerSummaries overview and related methods

sqlPaging

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

Default value is null

See Also:
DataSource.sqlPaging

groupClause

public java.lang.String 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, CustomQuerying overview and related methods

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 ( 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 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, ClientDataIntegration overview and related methods

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

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.

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.

Default value is null


recordXPath

public XPathExpression recordXPath
For an XML or JSON DataSource, 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:
ClientDataIntegration overview and related methods

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

Default value is null


customCriteriaFields

public java.lang.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, CustomQuerying overview and related methods

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


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:
ClientDataIntegration overview and related methods

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:
ClientDataIntegration overview and related methods

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

These properties are applied before DataSource.transformRequest is called.

Default value is null

See Also:
DSRequest, DataSource.requestProperties, ClientDataIntegration overview and related methods

tableClause

public java.lang.String 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, CustomQuerying overview and related methods

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:
CustomQuerying overview and related methods

customJQL

public java.lang.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 OperationBindings 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, DataSourceField.customSQL, CustomQuerying overview and related methods

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:
ClientDataIntegration overview and related methods

allowAdvancedCriteria

public java.lang.Boolean allowAdvancedCriteria
This property indicates whether this operation supports AdvancedCriteria. This setting overrides 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

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"


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:
ClientDataIntegration overview and related methods

preventHTTPCaching

public java.lang.Boolean preventHTTPCaching
Configures preventHTTPCaching on a per-operationType basis.

Default value is null


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, FieldLevelAuth overview and related methods

qualifyColumnNames

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

Default value is true


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 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 dropExtraFields is true.

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

Default value is null


autoJoinTransactions

public java.lang.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 autoJoinTransactions.

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

Default value is null


whereClause

public java.lang.String 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, CustomQuerying overview and related methods

excludeCriteriaFields

public java.lang.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, CustomQuerying overview and related methods

useFlatFields

public boolean useFlatFields
Setting useFlatFields on an operationBinding is equivalent to setting 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:
ClientDataIntegration overview and related methods

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:
ClientDataIntegration overview and related methods

transformMultipleFields

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

Default value is null


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


exportFilename

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

Default value is null


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

selectClause

public java.lang.String 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, CustomQuerying overview and related methods

customSQL

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

For a dataSource of serverType "sql" or "hibernate", 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; an alternative is to provide custom "pieces" to the query generator, via properties such as whereClause and valuesClause. 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, DataSourceField.customSQL, CustomQuerying overview and related methods

skipRowCount

public java.lang.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 totalRows will be set to match the requested endRow since the totalRows is unknown.

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


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:

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

canSyncCache

public java.lang.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:

If any of these cases apply or if canSyncCache has been set false, the server will skip the cacheSyncOperation and return a DSResponse where 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.

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

Default value is null

See Also:
useForCacheSync, cacheSyncOperation, CustomQuerying overview and related methods

xmlNamespaces

public java.util.Map xmlNamespaces
Optional object declaring namespace prefixes for use in recordXPath and 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:
ClientDataIntegration overview and related methods

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 (serviceNamespace is set).

Default value is null

See Also:
ClientDataIntegration overview and related methods

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


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 operationId for usage.

Default value is null

See Also:
ClientDataIntegration overview and related methods

useSubselectForRowCount

public java.lang.Boolean useSubselectForRowCount
Whether to use the subselect technique (see 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

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, ProgressiveLoading overview and related methods

orderClause

public java.lang.String 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, CustomQuerying overview and related methods
Constructor Detail

OperationBinding

public OperationBinding()