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), for use with Smart GWT Pro Edition and
above.
See com.smartgwt.client.docs.serverds
for how to use this documentation.
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.
|
java.lang.String |
csvDelimiter
Applies to RestConnector dataSources (
serverType "rest") only. |
java.lang.String |
csvQuoteCharacter
Applies to RestConnector dataSources (
serverType "rest") only. |
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.String |
headers
Applies to RestConnector dataSources (
serverType "rest") only. |
java.lang.String |
httpMethod
Applies to RestConnector dataSources (
serverType "rest") only. |
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.String |
params
Applies to RestConnector dataSources (
serverType "rest") 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 , JSON or
RestConnector
DataSource, an XPath expression used to retrieve the objects that will become DataSource
records. |
RESTRequestFormat |
requestFormat
For a
RestConnector DataSource , the
request format to use for this specific operationBinding. |
DSRequest |
requestProperties
Additional properties to pass through to the
DSRequest created
for this operation. |
java.lang.String |
requestTemplate
Applies to RestConnector dataSources (
serverType "rest") only. |
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 |
requiresCompleteRESTResponse
Applies to RestConnector dataSources (
serverType "rest") only. |
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.
|
RESTResponseFormat |
responseFormat
For a
RestConnector DataSource , the
response format to use for this specific operationBinding. |
java.lang.String |
responseTemplate
Applies to RestConnector dataSources (
serverType "rest") only. |
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
|
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 |
suppressAutoMappings
Applies to RestConnector dataSources (
serverType "rest") only. |
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 |
transformRawResponseScript
Applicable to
server-side REST
DataSources only |
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.lang.Boolean |
wrapInList
Applies to RestConnector dataSources (
serverType "rest") only. |
java.util.Map |
xmlNamespaces
Optional object declaring namespace prefixes for use in
recordXPath and
DataSourceField.valueXPath
XPath expressions. |
java.lang.String |
xmlTag
Applies to RestConnector dataSources (
serverType "rest") only. |
Constructor and Description |
---|
OperationBinding() |
public java.lang.String requiredCriterion
STATUS_CRITERIA_REQUIRED_ERROR
from the server.
Default value is null
Client-side Data Integration
public java.lang.String headers
serverType
"rest") only. This is an
operationBinding-level override of DataSource.headers
- see that property's documentation for details
Default value is null
Server-side REST Connector
public java.lang.String recordName
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
Client-side Data Integration
public java.lang.String transformRawResponseScript
server-side REST
DataSources
only A scriptlet to be executed on the server after data has been fetched
from the REST service by this operation, but before it is processed through templating. See
DataSource.transformRawResponseScript
for further details.
Note, unlike many
OperationBinding-level properties, a transformRawResponseScript
at the
OperationBinding level does not hide a transformRawResponseScript
defined at the
DataSource level. Instead, if you define transformRawResponseScript
against both
the DataSource and the OperationBinding, both are run - first the DataSource-level
script, then the OperationBinding-level one.
Default value is null
Server Scripting
public java.lang.String outputs
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
DataSourceField.outputWhen
,
DSRequest.getOutputs()
public java.lang.Boolean preventHTTPCaching
DataSource.preventHTTPCaching
on a per-operationType basis.
Default value is null
public java.lang.String transformResponseScript
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
Server Scripting
public boolean qualifyColumnNames
DataSource.qualifyColumnNames
property. Only applicable to dataSources of serverType
"sql".
Default value is true
public java.lang.String description
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
public java.lang.String[] groupBy
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
summaryFunctions
,
Server Summaries
public java.lang.String lineBreakStyle
LineBreakStyle
for more information.
Default value is null
public MultiInsertNonMatchingStrategy multiInsertNonMatchingStrategy
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"
multiInsertStrategy
,
multiInsertBatchSize
public Mail mail
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
public DSProtocol dataProtocol
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"
DSProtocol
,
Client-side Data Integration
public java.lang.String responseTemplate
serverType
"rest") only. This is an
operationBinding-level override of the DataSource.responseTemplate
-
see that property's documentation for details
Default value is null
public java.lang.Boolean requiresAuthentication
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
Declarative Security
public java.lang.Boolean useHavingClause
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
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
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 > 10If
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
com.smartgwt.client.data.OperationBinding#getGroupWhereClause
public DSRequestModifier[] criteria
A list of DSRequestModifier
s that will be used to
modify the criteria of each
DSRequest
that uses this operationBinding. Note that the
criteria elements are
applied to DSRequest criteria as follows:
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 belowBelow 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
values
,
Transaction Chaining
public java.lang.String callbackParam
Typically
set once for the DataSource as a whole via DataSource.callbackParam
.
Default value is "callback"
public RESTResponseFormat responseFormat
RestConnector DataSource
, the
response format to use for this specific operationBinding. Overriddes any DataSource-level setting
. Note, if
responseFormat
is not specified at either the DataSource or OperationBinding
level, response processing will throw an exception.
Default value is null
Server-side REST Connector
public boolean exportResults
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
public ServerObject serverObject
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
DataSource.serverObject
public DSRequest requestProperties
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
public java.util.Map summaryFunctions
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
groupBy
,
Server Summaries
public java.lang.String requiresCompleteRESTResponse
serverType
"rest") only. This is an
operationBinding-level override of DataSource.requiresCompleteRESTResponse
- see that property's documentation for details
Default value is null
Server-side REST Connector
public java.lang.String methodArguments
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:
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"
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
ServerObject
public VelocityExpression requires
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
Declarative Security
public java.lang.String csvDelimiter
serverType
"rest") only. This is an
operationBinding-level override of DataSource.csvDelimiter
- see that
property's documentation for details
Default value is ","
Server-side REST Connector
public java.util.Map xmlNamespaces
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
Client-side Data Integration
public java.lang.String httpMethod
serverType
"rest") only. This is an
operationBinding-level override of DataSource.httpMethod
- see that
property's documentation for details
Default value is null
Server-side REST Connector
public java.lang.Boolean creatorOverrides
dataSource.creatorOverrides
.
This setting overrides dataSource.creatorOverrides
, for this operation only.
Default value is null
public java.lang.String transformRequestScript
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
Server Scripting
public java.lang.Boolean suppressAutoMappings
serverType
"rest") only. This is an
operationBinding-level override of DataSource.suppressAutoMappings
- see that property's documentation for details
Default value is false
Server-side REST Connector
public java.lang.Integer multiInsertBatchSize
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
public java.lang.String params
serverType
"rest") only. This is an
operationBinding-level override of DataSource.params
- see that property's documentation for details
Default value is null
Server-side REST Connector
public java.lang.String[] exportFields
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
public DataSource responseDataSchema
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
Client-side Data Integration
public java.lang.String forceSort
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
Server DataSource Integration
public java.lang.Boolean allowAdvancedCriteria
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
DataSource.allowAdvancedCriteria
public java.lang.Boolean invalidateCache
Default value is null
public java.lang.String requiresRole
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.
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
Declarative Security
public java.lang.String requestTemplate
serverType
"rest") only. This is an
operationBinding-level override of the DataSource.requestTemplate
- see
that property's documentation for details
Default value is null
public java.lang.String exportFilename
Default value is null
public boolean useFlatFields
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
Client-side Data Integration
public java.lang.String xmlTag
serverType
"rest") only. This is an
operationBinding-level override of DataSource.xmlTag
- see that property's documentation for details
Default value is null
Server-side REST Connector
public java.lang.String script
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:
automatic
transactions
are enabled, this
SQLConnection is in the context of the current transaction.
Scriptlets also have access to a set of contextual variables related to the Servlets API, as follows:
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
public java.lang.Boolean progressiveLoading
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
DataSource.progressiveLoading
,
Progressive Loading
public DSOperationType operationType
Default value is null
Client-side Data Integration
public java.lang.Boolean wrapInList
serverType
"rest") only. This is an
operationBinding-level override of DataSource.wrapInList
- see that
property's documentation for details
Default value is false
Server-side REST Connector
public java.lang.Boolean useSubselectForRowCount
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
DataSource.useSubselectForRowCount
,
com.smartgwt.client.data.OperationBinding#getCustomSQL
public MultiInsertStrategy multiInsertStrategy
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
public java.lang.String csvQuoteCharacter
serverType
"rest") only. This is an
operationBinding-level override of DataSource.csvQuoteCharacter
-
see that property's documentation for details
Default value is '"'
Server-side REST Connector
public java.lang.Boolean isDDL
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 myTableWhen
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
public java.lang.Boolean transformMultipleFields
multiple:true
fields, normally
controlled by DataSourceField.multipleStorage
, is instead disabled for this OperationBinding.
Default value is null
public java.lang.Boolean skipAudit
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
public java.lang.String beanClassName
Default value is null
public java.lang.String serverMethod
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
public java.lang.Boolean applyCriteriaBeforeAggregation
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
com.smartgwt.client.data.OperationBinding#getGroupWhereClause
public ExportFormat exportAs
ExportFormat
for more information.
Default value is "csv"
public java.util.Map defaultParams
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
Client-side Data Integration
public DSRequestModifier[] values
A list of
DSRequestModifier
s that will be used to modify the
values object of each DSRequest
that uses this
operationBinding. See this example: Master/Detail Add Example.
Below example of the xml as it should be
defined in ds.xml: <operationBinding operationType="add"> <values
fieldName="orderID" value="$responseData.last('queuedAdd_order','add').orderID" />
</operationBinding>
Default value is null
criteria
,
Transaction Chaining
public RESTRequestFormat requestFormat
RestConnector DataSource
, the
request format to use for this specific operationBinding. Overriddes any DataSource-level setting
. Note, if
requestFormat
is not specified at either the DataSource or OperationBinding
level, the request will be rejected.
Default value is null
Server-side REST Connector
public java.lang.String guestUserId
ownerIdField
if no one has authenticated. Overrides the same setting at the DataSource
level.
Default value is null
ownerIdField
,
DataSource.guestUserId
public XPathExpression recordXPath
RestConnector
DataSource, an XPath expression used to retrieve the objects that will become DataSource
records. For example, an "ItemSearch" web service might return a "Results" structure containing metadata along with the set of Items that one might want to display in a grid. An XPath expression like "/Results/Items" could be used to retrieve just the Items, which would then become DataSource records.
For a JSON web service, the recordXPath
is
applied to the returned JSON data via XMLTools.selectObjects()
. Only limited XPath syntax is allowed; see selectObjects()
for details.
For
processing XML results, see xmlNamespaces
for information
on the namespaces that are available in this XPath expression. If you are contacting a WSDL
web service, note that recordName
is an alternative way to specify which records should be selected by their tagName
or type, and this is usually simpler.
To learn about XPath, try the following search: http://www.google.com/search?q=xpath+tutorial
Default value is null
Client-side Data Integration
public java.lang.Boolean allowMultiUpdate
DataSource
s that have a primaryKey
, and all primary key
values are present in the request. This is because an update of a DataSource with no primary
key, or an update request that has missing primary key values, cannot be guaranteed to affect
only one record. Setting this property on an operationBinding circumvents this restriction for that operation only.
Warning: Be aware that this is a potentially dangerous setting and should be used with care. With this flag set, you have no guarantee that an update will not change or remove every row in a table.
Note, in the case of doing an update or delete operation with a primary key and additional criteria, allowMultiUpdate must be set or additional criteria will be dropped and just the primary key fields will be used in criteria.
Also, running allowMultiUpdate
operations directly from the
client is not straightforward because it requires the ability to specify criteria and values
separately in the request, which is not currently supported. This can be worked around in
various ways, but really allowMultiUpdate
is primarily intended for server-side
operations. Therefore, the recommended pattern is to use a custom operation
from the client to
invoke a DMI on the server which performs the multi-update operation via a second, server-side
DSRequest.
In any case, it's normally a good idea to set requiredCriterion
on the
multi-update operation to ensure that the alternative criteria is present as expected.
Default value is null
public boolean spoofResponses
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
Client-side Data Integration
public java.lang.Boolean sqlUsePagingHint
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
DataSource.sqlUsePagingHint
public java.lang.String dataURL
dataURL
is
typically set as DataSource.dataURL
rather than on each individual
operationBinding. However, when using dataURL
to configure the server side of a
RestConnector
, it is common to set
dataURL
at the operationBinding level, as described in the DataSource-level dataURL
documentation.
dataURL
can be omitted for a DataSource using a Web Service (DataSource.serviceNamespace
is
set).
Default value is null
Client-side Data Integration
public java.lang.String operationId
DSRequest.operationId
for usage.
Default value is null
Client-side Data Integration
public java.lang.String ownerIdField
DataSource
level, for this
operation only. See the dataSource-level documentation for details.
Default value is null
DataSource.ownerIdField
,
guestUserId
public java.lang.Boolean providesMissingKeys
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:
<customSQL
>
or
<whereClause
>
can provide missing key values from session storage or elsewhere in
the provided record<script
>
can provide arbitrary code to
manipulate the record in whatever way they like before executing the underlying built-in
functionality<criteria
>
to
provide missing keysfieldValueExpressions
, which
can be used to provide values for missing keysDMI
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
allowMultiUpdate
,
DataSourceField.autoGenerated
public java.lang.Boolean arrayCriteriaForceExact
arrayCriteriaForceExact
flag. See the documentation for that flag for details.
Default value is null
Server DataSource Integration
public SQLPagingStrategy sqlPaging
DataSource.sqlPaging
value, and the defaults described in the documentation for that property.
Default value is null
DataSource.sqlPaging