Class DataSource
- All Implemented Interfaces:
HasHandlers
,HasDataChangedHandlers
,HasHandleErrorHandlers
- Direct Known Subclasses:
FacadeDataSource
,MockDataSource
,RestDataSource
,WSDataSource
,XJSONDataSource
Each DataSource consists of a list of fields
that make up a DataSource record
, along with field types
, validation rules
, relationships
to other DataSources, and other metadata.
The abstract object description provided by a DataSource is easily mapped to a variety of backend object models and storage schemes. The following table shows analogous terminology across systems.
Isomorphic Smart GWT | Relational Database | Enterprise Java Beans (EJB) | Entity/Relationship Modeling | OO/UML | XML Schema/WSDL | LDAP |
DataSource | Table | EJB class | Entity | Class | Element Schema (ComplexType) | Objectclass |
Record | Row | EJB instance | Entity instance | Class instance/Object | Element instance (ComplexType) | Entry |
Field | Column | Property | Attribute | Property/Attribute | Attribute or Element (SimpleType) | Attribute |
DataSources can be declared
in either JavaScript or XML format, and can also be imported
from existing metadata formats, including XML Schema.
Data Binding is the process by
which Data Binding-capable UI components
can automatically
configure themselves for viewing, editing and saving data described by DataSources. DataBinding is covered in the
'QuickStart Guide', Chapter 6, Data Binding.
Data
Integration
is the process by which a DataSource can be connected to server systems such as SQL DataBases, Java Object
models, WSDL web services and other data providers. Data Integration comes in two variants: client-side and
server-side. Server-side integration
uses the Smart GWT
Java-based server to connect to data represented by Java Objects or JDBC-accessible databases. Client-side integration
connects Smart GWT DataSources to XML, JSON or
other formats accessible via HTTP.
DataSources have a concept of 4 core operations
("fetch", "add", "update" and "remove") that can be
performed on the set of objects represented by a DataSource. Once a DataSource has been integrated with your data
store, databinding-capable UI components can leverage the 4 core DataSource operations to provide many complete user
interactions without the need to configure how each individual component loads and saves data.
These interactions
include grid views
, tree views
, detail views
, form
-based editing
and saving
, grid-based editing
and saving
, and custom interactions provided by Pattern Reuse
Example custom databinding-capable components.
- See Also:
-
Field Summary
Fields inherited from class com.smartgwt.client.core.BaseClass
config, configOnly, factoryCreated, factoryProperties, id, scClassName
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.void
addData
(Record newRecord, DSCallback callback) void
addData
(Record newRecord, DSCallback callback, DSRequest requestProperties) Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.addDataChangedHandler
(DataChangedHandler handler) Add a dataChanged handler.void
addField
(DataSourceField field) Add a field to the DataSourceaddHandleErrorHandler
(HandleErrorHandler handler) Add a handleError handler.void
addSearchOperator
(Operator operator, FieldType[] types) Add a new search operator, only to this DataSource.Record[]
applyFilter
(Record[] records, Criteria criteria) Returns records in the passed Record that match the provided filterCriteria
.Record[]
applyFilter
(Record[] records, Criteria criteria, DSRequest requestProperties) Returns records in the passed Record that match the provided filterCriteria
.static boolean
canFlattenCriteria
(AdvancedCriteria criteria) Returns true if callingflattenCriteria()
on the passed criteria would produce logically equivalent criteria.static void
clearValueAtDataPath
(DataSourceField field, String dataPath, Record values) Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.static void
clearValueAtDataPath
(FormItem field, String dataPath, Record values) Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.static void
clearValueAtDataPath
(ListGridField field, String dataPath, Record values) Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.static void
clearValueAtDataPath
(DetailViewerField field, String dataPath, Record values) Helper method to remove the value at the supplied dataPath inside the argument values record, or at the field's declared dataPath if the argument dataPath is null.cloneDSRequest
(DSRequest dsRequest) Creates a shallow copy of the givenDSRequest
.cloneDSResponse
(DSResponse dsResponse) Creates a shallow copy of the givenDSResponse
.static Criteria
combineCriteria
(Criteria criteria1, Criteria criteria2) Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator".static Criteria
combineCriteria
(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator) static Criteria
combineCriteria
(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator, TextMatchStyle textMatchStyle) Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator".int
compareCriteria
(Criteria newCriteria, Criteria oldCriteria) Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.int
compareCriteria
(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties) int
compareCriteria
(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties, String policy) Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.int
compareDates
(Date date1, Date date2, String fieldName) Convenience method to compare two Date objects appropriately, depending on whether the passed-in fieldName refers to a field oftype
"datetime" or "date".static AdvancedCriteria
convertCriteria
(Criteria criteria) Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.static AdvancedCriteria
convertCriteria
(Criteria criteria, TextMatchStyle textMatchStyle) Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.convertDataSourceCriteria
(Criteria criteria) Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.convertDataSourceCriteria
(Criteria criteria, TextMatchStyle textMatchStyle) Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.convertRelativeDates
(Criteria criteria) Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.convertRelativeDates
(Criteria criteria, String timezoneOffset) convertRelativeDates
(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek) convertRelativeDates
(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek, Date baseDate) Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.static Criteria
copyCriteria
(Criteria criteria) Create a copy of a criteria.copyRecord
(Record record) Copies all DataSource field values of a Record (including a TreeNode) to a new Record, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.Record[]
copyRecords
(Record... records) Copies all DataSource field values of an (Array) of Records (including a TreeNode) to a new array of Records, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.create()
void
createAlias
(String alias) Assigns an alias to this DataSourcevoid
downloadFile
(Record data) Download a file stored in a field of type:"binary" in a DataSource record.void
downloadFile
(Record data, String fieldName) void
downloadFile
(Record data, String fieldName, DSRequest requestProperties) Download a file stored in a field of type:"binary" in a DataSource record.boolean
evaluateCriterion
(Record record, Criterion criterion) Evaluate the given criterion with respect to the passed record.void
Executes the given DSRequest on this DataSource.void
exportClientData
(Object[] data, DSRequest requestProperties) Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users.static void
exportClientDataStatic
(Object[] data, DSRequest requestProperties) Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users.void
Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results.void
exportData
(Criteria criteria) void
exportData
(Criteria criteria, DSRequest requestProperties) void
exportData
(Criteria criteria, DSRequest requestProperties, DSCallback callback) Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results.void
Deprecated.void
void
fetchData
(Criteria criteria, DSCallback callback) void
fetchData
(Criteria criteria, DSCallback callback, DSRequest requestProperties) Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.void
fetchRecord
(Object pkValue) Fetch a single record from the DataSource byprimary key
.void
fetchRecord
(Object pkValue, DSCallback callback) void
fetchRecord
(Object pkValue, DSCallback callback, DSRequest requestProperties) Fetch a single record from the DataSource byprimary key
.boolean
fieldMatchesFilter
(Object fieldValue, Object filterValue) Compares a criteria value to a field value and returns whether they match, as follows: any non-String filter value is directly compared (==) to the field value any String filter value is compared according toDSRequest.textMatchStyle
in the passedrequestProperties
, regardless of the actual field type if the filter value is an Array, the comparison is a logical OR.boolean
fieldMatchesFilter
(Object fieldValue, Object filterValue, DSRequest requestProperties) Compares a criteria value to a field value and returns whether they match, as follows: any non-String filter value is directly compared (==) to the field value any String filter value is compared according toDSRequest.textMatchStyle
in the passedrequestProperties
, regardless of the actual field type if the filter value is an Array, the comparison is a logical OR.void
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.void
filterData
(Criteria criteria) void
filterData
(Criteria criteria, DSCallback callback) void
filterData
(Criteria criteria, DSCallback callback, DSRequest requestProperties) Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.static AdvancedCriteria
flattenCriteria
(AdvancedCriteria criteria) Returns new criteria that has at most one top-level LogicalOperator ("and" or "or").formatFieldValue
(DataSourceField field, Object value) Formats the supplied value using theSimpleType
derived from the field definition.static DataSource
Synonym ofDataSource.getDataSource
: Lookup a DataSource by ID.static DataSource
get
(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer) Synonym ofDataSource.getDataSource
: Lookup a DataSource by ID.The list of extra manually managed fields that will be added to thefields
of theAudit DataSource
.Whether to make this DataSource available as a global variable for convenience.static String
getAdvancedCriteriaDescription
(AdvancedCriteria criteria, DataSource dataSource) Returns a human-readable string describing the clauses in this advanced criteria or criterion.static String
getAdvancedCriteriaDescription
(AdvancedCriteria criteria, DataSource dataSource, CriteriaOutputSettings criteriaOutputSettings) Returns a human-readable string describing the clauses in this advanced criteria or criterion.static String
getAggregationDescription
(AdvancedCriterionSubquery subquery, DataSource dataSource) Returns a human-readable string describing the aggregation properties in the request:DSRequest.groupBy
andDSRequest.summaryFunctions
.By default, all DataSources are assumed to be capable of handlingAdvancedCriteria
on fetch or filter type operations.This property indicates whether this DataSource supports aggregation/summarization of field values using thesummaryFunction
mechanism.By default, custom dataSource implementations are assumed to be unable to supportdynamic tree joins
.This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries.getAllPathsToRelation
(DataSource targetDS) Returns all known paths between this and the given targetDS.getAllPathsToRelation
(String targetDS) Returns all known paths between this and the given targetDS.With ordinarysimple criteria
, it is possible to provide an array of values for a given field, which means "any of these values".When a DataSource is notcacheAllData
:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch tocacheAllData:true
and prevent further server-trips for fetch requests.Whether to convert relative date values to concrete date values before sending to the server.boolean
If set, titles are automatically derived fromfield.name
for any field that does not have afield.title
and is not markedhidden
:true, by calling the methodgetAutoTitle()
.boolean
CausesTree.discoverTree()
to be called on dsResponse.data in order to automatically discover tree structures in the response data.static String
getAutoTitle
(String identifier) Utility method to derive a reasonable user-visible title from an identifier.WhencacheAllData
mode is enabled and acacheAllOperationId
has been set, this flag affects whether cached results are used for all "fetch" requests regardless of theirDSRequest.operationId
, or are used only for "fetch" requests that use thecacheAllOperationId
, allowing other requests to go to server normally.Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.DSRequest.operationId
to use for fetching data in casecacheAllData
is true.Record[]
For acacheAllData
or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.int
The maximum time, in seconds, to maintain the client-side cache.Applies only to dataFormat: "json" anddataTransport
:"scriptInclude".By default, all DataSources are assumed to be capable of handlingServerSummaries
on fetch or filter type operations.boolean
When true, indicates that this DataSource supports multi-level sorting.fieldName for a field in the dataSource expected to contain an explicit array of child nodes.A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory asDSRequests
are executed on it.void
getClientOnlyDataSource
(Criteria criteria, ClientOnlyDataSourceCallback callback) Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource thatinheritsFrom
the original DataSource.void
getClientOnlyDataSource
(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties) void
getClientOnlyDataSource
(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties, DataSource dataSourceProperties) Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource thatinheritsFrom
the original DataSource.protected DSResponse
getClientOnlyResponse
(DSRequest request, Record... serverData) Return a "spoofed" response for aclientOnly
orcacheAllData
DataSource.Decides under what conditions theResultSet
cache should be dropped when theResultSet.criteria
changes.Name of the field that has the most pertinent numeric, date, or enum value, for use when aDataBoundComponent
needs to show a short summary of a record.Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, whenfetchData()
is called).Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.static DataSource
getDataSource
(String ID) Lookup a DataSource by ID.static DataSource
getDataSource
(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer) Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer.Transport to use for all operations on this DataSource.Default URL to contact to fulfill all DSRequests.When editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or bydataPath
).Before we start editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays).HTTP parameters that should be submitted with every DSRequest.getDefaultPathToRelation
(DataSource targetDS) Returns the path having the shortest distance between this and the given targetDS, as determined bygetShortestPathToRelation()
.getDefaultPathToRelation
(String targetDS) Returns the path having the shortest distance between this and the given targetDS, as determined bygetShortestPathToRelation()
.The default textMatchStyle to use forDSRequest
s that do not explicitly state atextMatchStyle
.An optional description of the DataSource's content.Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.Settings to use when discoverTree() is automatcially called becauseautoDiscoverTree
is set to true for this DataSourcegetDisplayValue
(String fieldName, Object value) Given a fieldName and a dataValue, apply anyDataSourceField.valueMap
for the field and return the display value for the fieldIndicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client.Indicates thatDeclarativeSecurity
should be enforced on the client.getFetchDataURL
(Criteria criteria) Returns a URL to DataSource fetch operation.getFetchDataURL
(Criteria criteria, DSRequest requestProperties) Returns a URL to DataSource fetch operation.Return the field definition object.getFieldAutoTitle
(String identifier) Return a reasonable user-visible title given a fieldName.getFieldCriterion
(Criteria criterion, String fieldName) Returns the depth-first match of a criterion matching the given fieldName.Get the defaultOperatorId
for this field.getFieldDefaultOperator
(String field) Get the defaultOperatorId
for this field.getFieldForDataPath
(String dataPath) Return the field definition object corresponding to the supplied dataPathString[]
Retrieves the list of fields declared on this DataSource.String[]
getFieldNames
(boolean excludeHidden) Retrieves the list of fields declared on this DataSource.getFieldOperators
(DataSourceField field) Get the list of OperatorId's available for the passed field.getFieldOperators
(String fieldName) Get the list of OperatorId's available for the passed field-name.The list of fields that compose records from this DataSource.static Object
getFieldValue
(DataSourceField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult) Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.static Object
getFieldValue
(FormItem field, Record record) Given a field definition and a record object, this method will return the field value for the record.static Object
getFieldValue
(FormItem field, Record record, String dataPath, Canvas component, String reason, boolean convertResult) Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.static Object
getFieldValue
(ListGridField field, Record record) Given a field definition and a record object, this method will return the field value for the record.static Object
getFieldValue
(ListGridField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult) Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.static Object
getFieldValue
(DetailViewerField field, Record record) Given a field definition and a record object, this method will return the field value for the record.static Object
getFieldValue
(DetailViewerField field, Record record, String dataPath, Canvas component, String reason, boolean convertResult) Helper method to return the value of the supplied field from within the supplied record, looking up the value from the supplied dataPath.void
getFile
(FileSpec fileSpec, GetFileCallback callback) Gets the contents of a file stored in this DataSource.getFileURL
(Record data) Returns a direct URL to access a file stored in a field of type:"binary".getFileURL
(Record data, String fieldName) getFileURL
(Record data, String fieldName, DSRequest requestProperties) Returns a direct URL to access a file stored in a field of type:"binary".void
getFileVersion
(FileSpec fileSpec, Date version, GetFileVersionCallback callback) Gets the contents of a particular file version stored in this DataSource.Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.For fields on this dataSource that specifyignoreTextMatchStyle
true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values.Criteria that are implicitly applied to all fetches made through this DataSource.Name of the field that has the second most pertinent piece of textual information in the record, for use when aDataBoundComponent
needs to show a short summary of a record.ID of another DataSource this DataSource inherits itsfields
from.Used by Reify to identify DataSources that are provided as samples.getJsObj()
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.void
For a DataSource that describes a DOM structure, the list of legal child elements that can be contained by the element described by this DataSource.static String
Returns theloaderURL
WhenmockMode
is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.WhenmockMode
is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data.If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to aclientOnly
DataSource, never writing changes back to the server.Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.static DataSource
getOrCreateRef
(JavaScriptObject jsObj) When using thepattern operators
search operator
, character that escapes thepatternSingleWildcard
orpatternMultiWildcard
if placed before it, so that it is treated as a literal character.When using thepattern operators
search operator
, character that matches a series of one or more characters.String[]
Deprecated.String[]
When using thepattern operators
search operator
, character that matches a series of one or more characters.When using thepattern operators
search operator
, character that matches any single character.String[]
Deprecated.in favor ofgetPatternSingleWildcardAsStringArray()
.String[]
When using thepattern operators
search operator
, character that matches any single character.User-visible plural name for this DataSource.If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.Returns a pointer to the primaryKey field for this DataSource.Returns the primary key fieldName for this DataSource.String[]
Returns a list of the names of this DataSource'sprimaryKey
fields.Returns this DataSource'sprimaryKey
fields as a map of fieldName to field.If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of theResultSet documentation
.For dataSources ofserverType
"sql", determines whether we qualify column names with table names in any SQL we generate.Provides a default value forOperationBinding.recordName
.Additional properties to pass through to theDSRequest
s made by this DataSource.The required message when a field that has been marked asrequired
is not filled in by the user.int
Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.Class for ResultSets used by this datasource.Class for ResultTrees used by this datasource.For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to.Analogous todropExtraFields
, for data sent to the server.Set this attribute if you need to send the dsRequest.parentNode to the server-side.For an XML DataSource, URN of the WebService to use to invoke operations.getShortestPathToRelation
(DataSource targetDS) Returns the path having the shortest distance between this and the given targetDS.getShortestPathToRelation
(String targetDS) Returns the path having the shortest distance between this and the given targetDS.For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that only the fields listed in this DataSource should be shown.Whether RPCRequests sent by this DataSource should enableRPCRequest.showPrompt
in order to block user interactions until the request completes.Sets what level of JSON validation will apply for this DataSource.static String[]
getSortBy
(SortSpecifier[] sortSpecifiers) Given an array ofSortSpecifier
s, return a simple list of Strings in the format expected byDSRequest.sortBy
.static SortSpecifier[]
getSortSpecifiers
(String[] sortBy) Return an array ofSortSpecifier
s, given an array of Strings in the format expected byDSRequest.sortBy
.static SortSpecifier[]
getSortSpecifiers
(String[] sortBy, DataSource context) Return an array ofSortSpecifier
s, given an array of Strings in the format expected byDSRequest.sortBy
.If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.Tag name to use when serializing to XML.Record[]
For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.getTitle()
User-visible name for this DataSource.Best field to use for a user-visible title for an individual record from this dataSource.boolean
Search operators
like "matchesPattern" use patterns like "foo*txt" to match text values.For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa.Get the list ofOperatorId
s available on this DataSource for the givenFieldType
.getTypeOperators
(FieldType typeName) Get the list ofOperatorId
s available on this DataSource for the givenFieldType
.getTypeOperators
(String typeName) Get the list ofOperatorId
s available on this DataSource for the givenFieldType
.LikeDataBoundComponent.useFlatFields
, but applies to all DataBound components that bind to this DataSource.LikeOperationBinding.useHttpProxy
, but serves as a default for this DataSource that may be overridden by individual operationBindings.Whether to attempt validation on the client at all for this DataSource.Whether we store server responses for this DataSource intobrowser-based offline storage
, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server).For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.When set, causes aclient-only
orcacheAllData
DataSource to create a second DataSource to perform it's one-time fetch.If true, indicates that the Smart GWT Server should automatically apply aValidatorType
of "hasRelatedRecord" to every field on this dataSource that has aforeignKey
defined.WhencacheAllData
is true, has all the data been retrieved to the client?void
hasCustomTypeOperators
(FieldType typeName) Returns true if the operator list for the passed type has been customized via a call tosetTypeOperators()
.void
hasCustomTypeOperators
(String typeName) Returns true if the operator list for the passed type has been customized via a call tosetTypeOperators()
.static void
hasCustomTypeOperators
(String typeName, DataSource ds) Returns true if the operator list for the passed type has been customized via a call tosetTypeOperators()
.void
hasFile
(FileSpec fileSpec, HasFileCallback callback) Indicates whether a file exists in this DataSource.void
hasFileVersion
(FileSpec fileSpec, Date version, HasFileCallback callback) Indicates whether a particular file version exists in this DataSource.void
Drop the current dataSource cache.void
invalidateCache
(boolean notify) Drop the current dataSource cache.boolean
isCalculated
(DataSourceField field) Does the specified field have its value dynamically calculated viaDataSourceField.formula
or other similar attributes?boolean
isCalculated
(String field) Does the specified field have its value dynamically calculated viaDataSourceField.formula
or other similar attributes?boolean
static boolean
isFlatCriteria
(AdvancedCriteria criteria) Returns true if a given AdvancedCriteria is "flat." That is, the criteria consists of either: a top-level "and" or "or"Criterion
, where none of thesubcriteria
uselogical operators
, hence have no subcriteria of their own a single Criterion that is not a logical operator, hence has no subcriteriavoid
listFiles
(Criteria criteria, DSCallback callback) Get a list of files from the DataSource.void
listFileVersions
(FileSpec fileSpec, DSCallback callback) Get the list of a given file's versions from the dataSource, sorted in version order (most recent version first).static void
Load a DataSource or an array of DataSources using the DataSourceLoader servlet.static void
load
(String[] dsID, Function callback, DSLoadSettings settings) Load a DataSource or an array of DataSources using the DataSourceLoader servlet.static void
Load a DataSource or an array of DataSources using the DataSourceLoader servlet.static void
Load a DataSource or an array of DataSources using the DataSourceLoader servlet.static void
loadWithParents
(String[] dsID, Function callback, boolean forceReload) Variation ofDataSource.load
that will also automatically load any DataSources that the requested DataSources inherit from (viaDataSource.inheritsFrom
)static void
loadWithParents
(String[] dsID, Function callback, DSLoadSettings settings) Variation ofDataSource.load
that will also automatically load any DataSources that the requested DataSources inherit from (viaDataSource.inheritsFrom
).static void
loadWithParents
(String dsID, Function callback) Variation ofload()
that will also automatically load any DataSources that the requested DataSources inherit from (viainheritsFrom
).static void
loadWithParents
(String dsID, Function callback, boolean forceReload) Variation ofload()
that will also automatically load any DataSources that the requested DataSources inherit from (viainheritsFrom
).static FileSpec
makeFileSpec
(String path) Converts a file path to aFileSpec
.protected void
onInit()
void
performCustomOperation
(String operationId) Invoke an operation declared withOperationBinding.operationType
"custom".void
performCustomOperation
(String operationId, Record data) void
performCustomOperation
(String operationId, Record data, DSCallback callback) void
performCustomOperation
(String operationId, Record data, DSCallback callback, DSRequest requestProperties) Invoke an operation declared withOperationBinding.operationType
"custom".void
processResponse
(String requestId, DSResponse dsResponse) Process a dsResponse for a request initiated by a DataSource withdataProtocol:"clientCustom"
.boolean
recordsAreEqual
(Object record1, Object record2) Convenience method to test if two records are equal.recordsAsText
(Record[] records) Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).recordsAsText
(Record[] records, TextExportSettings settings) Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).Record[]
recordsFromText
(String text) Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.Record[]
recordsFromText
(String text, TextImportSettings settings) Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.Record[]
recordsFromXML
(Object elements) Transform a list of XML elements to DataSource records.protected void
registerID
(String id, boolean skipUniqueJSIdentifierCheck) void
removeData
(Record data) Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.void
removeData
(Record data, DSCallback callback) void
removeData
(Record data, DSCallback callback, DSRequest requestProperties) Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.void
removeFile
(FileSpec fileSpec) Remove a file stored in this DataSource.void
removeFile
(FileSpec fileSpec, DSCallback callback) Remove a file stored in this DataSource.void
removeFile
(String fileSpec) Remove a file stored in this DataSource.void
removeFileVersion
(FileSpec fileSpec, Date version) Remove a particular file version stored in this DataSource.void
removeFileVersion
(FileSpec fileSpec, Date version, DSCallback callback) Remove a particular file version stored in this DataSource.void
renameFile
(FileSpec oldFileSpec, FileSpec newFileSpec) Rename a file stored in this DataSource.void
renameFile
(FileSpec oldFileSpec, FileSpec newFileSpec, DSCallback callback) Rename a file stored in this DataSource.void
Save a file to the DataSource.void
saveFile
(FileSpec fileSpec, String contents, DSCallback callback) Save a file to the DataSource.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, JavaScriptObject value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, Boolean value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, Double value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, Float value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, Integer value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, String value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, Date value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DataSourceField field, String dataPath, Map value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(FormItem field, String dataPath, JavaScriptObject value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, JavaScriptObject value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, Boolean value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, Double value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, Float value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, Integer value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, String value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, Date value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(ListGridField field, String dataPath, Map value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, JavaScriptObject value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, Boolean value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, Double value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, Float value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, Integer value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, String value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, Date value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.static void
saveValueViaDataPath
(DetailViewerField field, String dataPath, Map value, Record values, String reason) Helper method to save the argument value inside the argument values record, storing the value at the supplied dataPath, or at the field's declared dataPath if the argument dataPath is null.setAddedAuditFields
(DataSourceField... addedAuditFields) The list of extra manually managed fields that will be added to thefields
of theAudit DataSource
.void
setAddGlobalId
(Boolean addGlobalId) Whether to make this DataSource available as a global variable for convenience.setAllowAdvancedCriteria
(Boolean allowAdvancedCriteria) By default, all DataSources are assumed to be capable of handlingAdvancedCriteria
on fetch or filter type operations.setAllowAggregation
(Boolean allowAggregation) This property indicates whether this DataSource supports aggregation/summarization of field values using thesummaryFunction
mechanism.setAllowDynamicTreeJoins
(Boolean allowDynamicTreeJoins) By default, custom dataSource implementations are assumed to be unable to supportdynamic tree joins
.setAllowRelatedFieldsInCriteria
(Boolean allowRelatedFieldsInCriteria) This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries.setArrayCriteriaForceExact
(Boolean arrayCriteriaForceExact) With ordinarysimple criteria
, it is possible to provide an array of values for a given field, which means "any of these values".setAutoCacheAllData
(Boolean autoCacheAllData) When a DataSource is notcacheAllData
:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch tocacheAllData:true
and prevent further server-trips for fetch requests.setAutoConvertRelativeDates
(Boolean autoConvertRelativeDates) Whether to convert relative date values to concrete date values before sending to the server.setAutoDeriveTitles
(boolean autoDeriveTitles) If set, titles are automatically derived fromfield.name
for any field that does not have afield.title
and is not markedhidden
:true, by calling the methodgetAutoTitle()
.setAutoDiscoverTree
(boolean autoDiscoverTree) CausesTree.discoverTree()
to be called on dsResponse.data in order to automatically discover tree structures in the response data.setCacheAcrossOperationIds
(Boolean cacheAcrossOperationIds) WhencacheAllData
mode is enabled and acacheAllOperationId
has been set, this flag affects whether cached results are used for all "fetch" requests regardless of theirDSRequest.operationId
, or are used only for "fetch" requests that use thecacheAllOperationId
, allowing other requests to go to server normally.setCacheAllData
(Boolean cacheAllData) Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.setCacheAllOperationId
(String cacheAllOperationId) DSRequest.operationId
to use for fetching data in casecacheAllData
is true.void
setCacheData
(Record... cacheData) For acacheAllData
or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.setCacheMaxAge
(int cacheMaxAge) The maximum time, in seconds, to maintain the client-side cache.setCallbackParam
(String callbackParam) Applies only to dataFormat: "json" anddataTransport
:"scriptInclude".setCanAggregate
(Boolean canAggregate) By default, all DataSources are assumed to be capable of handlingServerSummaries
on fetch or filter type operations.setCanMultiSort
(boolean canMultiSort) When true, indicates that this DataSource supports multi-level sorting.setChildrenField
(String childrenField) fieldName for a field in the dataSource expected to contain an explicit array of child nodes.setClientOnly
(Boolean clientOnly) A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory asDSRequests
are executed on it.setCriteriaPolicy
(CriteriaPolicy criteriaPolicy) Decides under what conditions theResultSet
cache should be dropped when theResultSet.criteria
changes.setDataField
(String dataField) Name of the field that has the most pertinent numeric, date, or enum value, for use when aDataBoundComponent
needs to show a short summary of a record.setDataFormat
(DSDataFormat dataFormat) Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, whenfetchData()
is called).setDataProtocol
(DSProtocol dataProtocol) Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.setDataTransport
(RPCTransport dataTransport) Transport to use for all operations on this DataSource.setDataURL
(String dataURL) Default URL to contact to fulfill all DSRequests.setDeepCloneNonFieldValuesOnEdit
(Boolean deepCloneNonFieldValuesOnEdit) When editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or bydataPath
).setDeepCloneOnEdit
(Boolean deepCloneOnEdit) Before we start editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays).void
setDefaultParams
(Map defaultParams) HTTP parameters that should be submitted with every DSRequest.static void
setDefaultProperties
(DataSource dataSourceProperties) Class level method to set the default properties of this class.setDefaultTextMatchStyle
(TextMatchStyle defaultTextMatchStyle) The default textMatchStyle to use forDSRequest
s that do not explicitly state atextMatchStyle
.setDescription
(String description) An optional description of the DataSource's content.setDescriptionField
(String descriptionField) Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.setDiscoverTreeSettings
(DiscoverTreeSettings discoverTreeSettings) Settings to use when discoverTree() is automatcially called becauseautoDiscoverTree
is set to true for this DataSourcesetDropExtraFields
(Boolean dropExtraFields) Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.setDropUnknownCriteria
(Boolean dropUnknownCriteria) If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client.setEnforceSecurityOnClient
(Boolean enforceSecurityOnClient) Indicates thatDeclarativeSecurity
should be enforced on the client.setEnumConstantProperty
(String enumConstantProperty) The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if theEnumTranslateStrategy
is set to "bean".setEnumOrdinalProperty
(String enumOrdinalProperty) The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if theEnumTranslateStrategy
is set to "bean".setEnumTranslateStrategy
(EnumTranslateStrategy enumTranslateStrategy) Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript.void
setFields
(DataSourceField... fields) The list of fields that compose records from this DataSource.setGlobalNamespaces
(Map globalNamespaces) Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.void
setHandleErrorCallback
(HandleErrorCallback callback) If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other thanSTATUS_SUCCESS
.setIconField
(String iconField) setIgnoreTextMatchStyleCaseSensitive
(Boolean ignoreTextMatchStyleCaseSensitive) For fields on this dataSource that specifyignoreTextMatchStyle
true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values.setImplicitCriteria
(Criteria implicitCriteria) Criteria that are implicitly applied to all fetches made through this DataSource.setInfoField
(String infoField) Name of the field that has the second most pertinent piece of textual information in the record, for use when aDataBoundComponent
needs to show a short summary of a record.void
setInheritsFrom
(DataSource inheritsFrom) ID of another DataSource this DataSource inherits its DataSource fields from.
Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields.setInheritsFrom
(String inheritsFrom) ID of another DataSource this DataSource inherits itsfields
from.setIsSampleDS
(Boolean isSampleDS) Used by Reify to identify DataSources that are provided as samples.setJsonPrefix
(String jsonPrefix) Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.setJsonSuffix
(String jsonSuffix) Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.static void
setLoaderURL
(String url) Sets the URL where the DataSourceLoader servlet has been installed; this is used by theload()
method.setMockDataCriteria
(Criteria mockDataCriteria) WhenmockMode
is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.setMockDataRows
(Integer mockDataRows) WhenmockMode
is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data.setMockMode
(Boolean mockMode) If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to aclientOnly
DataSource, never writing changes back to the server.setOperationBindings
(OperationBinding... operationBindings) Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.setPatternEscapeChar
(String patternEscapeChar) When using thepattern operators
search operator
, character that escapes thepatternSingleWildcard
orpatternMultiWildcard
if placed before it, so that it is treated as a literal character.setPatternMultiWildcard
(String patternMultiWildcard) When using thepattern operators
search operator
, character that matches a series of one or more characters.setPatternMultiWildcard
(String... patternMultiWildcard) When using thepattern operators
search operator
, character that matches a series of one or more characters.setPatternSingleWildcard
(String patternSingleWildcard) When using thepattern operators
search operator
, character that matches any single character.setPatternSingleWildcard
(String... patternSingleWildcard) When using thepattern operators
search operator
, character that matches any single character.setPluralTitle
(String pluralTitle) User-visible plural name for this DataSource.setPreventHTTPCaching
(Boolean preventHTTPCaching) If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.setProgressiveLoading
(Boolean progressiveLoading) If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of theResultSet documentation
.setQualifyColumnNames
(Boolean qualifyColumnNames) For dataSources ofserverType
"sql", determines whether we qualify column names with table names in any SQL we generate.setRecordName
(String recordName) Provides a default value forOperationBinding.recordName
.setRecordXPath
(String recordXPath) setRequestProperties
(DSRequest requestProperties) Additional properties to pass through to theDSRequest
s made by this DataSource.setRequiredMessage
(String requiredMessage) The required message when a field that has been marked asrequired
is not filled in by the user.setResultBatchSize
(int resultBatchSize) Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.setResultSetClass
(String resultSetClass) Class for ResultSets used by this datasource.setResultTreeClass
(String resultTreeClass) Class for ResultTrees used by this datasource.setSendExtraFields
(Boolean sendExtraFields) Analogous todropExtraFields
, for data sent to the server.setSendParentNode
(Boolean sendParentNode) Set this attribute if you need to send the dsRequest.parentNode to the server-side.setServiceNamespace
(String serviceNamespace) For an XML DataSource, URN of the WebService to use to invoke operations.setShowLocalFieldsOnly
(Boolean showLocalFieldsOnly) For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that only the fields listed in this DataSource should be shown.setShowPrompt
(Boolean showPrompt) Whether RPCRequests sent by this DataSource should enableRPCRequest.showPrompt
in order to block user interactions until the request completes.setSkipJSONValidation
(SkipJSONValidation skipJSONValidation) Sets what level of JSON validation will apply for this DataSource.setStrictSQLFiltering
(Boolean strictSQLFiltering) If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.setTagName
(String tagName) Tag name to use when serializing to XML.void
setTestData
(Record... cacheData) For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.User-visible name for this DataSource.setTitleField
(String titleField) Best field to use for a user-visible title for an individual record from this dataSource.setTranslatePatternOperators
(boolean translatePatternOperators) Search operators
like "matchesPattern" use patterns like "foo*txt" to match text values.setTrimMilliseconds
(Boolean trimMilliseconds) For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa.void
setTypeOperators
(FieldType typeName, OperatorId[] operators) Set the list ofOperatorId
s valid for a given FieldType.static void
setTypeOperators
(String typeName, OperatorId[] operators) Set the list of validOperatorId
s for a given FieldType.setUseFlatFields
(Boolean useFlatFields) LikeDataBoundComponent.useFlatFields
, but applies to all DataBound components that bind to this DataSource.setUseHttpProxy
(Boolean useHttpProxy) LikeOperationBinding.useHttpProxy
, but serves as a default for this DataSource that may be overridden by individual operationBindings.setUseLocalValidators
(Boolean useLocalValidators) Whether to attempt validation on the client at all for this DataSource.setUseOfflineStorage
(Boolean useOfflineStorage) Whether we store server responses for this DataSource intobrowser-based offline storage
, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server).setUseParentFieldOrder
(Boolean useParentFieldOrder) For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.setUseStrictJSON
(Boolean useStrictJSON) Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.setUseTestDataFetch
(Boolean useTestDataFetch) When set, causes aclient-only
orcacheAllData
DataSource to create a second DataSource to perform it's one-time fetch.setValidateRelatedRecords
(Boolean validateRelatedRecords) If true, indicates that the Smart GWT Server should automatically apply aValidatorType
of "hasRelatedRecord" to every field on this dataSource that has aforeignKey
defined.setXmlNamespaces
(XmlNamespaces xmlNamespaces) Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions.splitCriteria
(Criteria criteria, String[] fields) Split a criteria apart based onfields
.splitCriteria
(Criteria criteria, String[] fields, Boolean preserveAdvanced) Split a criteria apart based onfields
.Do fetch and filter operations on this dataSource support being passedAdvancedCriteria
?This method returns true for dataSources that support both self-joins andadditionalOutputs
.void
supportsTextMatchStyle
(TextMatchStyle textMatchStyle) Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.protected Object
transformRequest
(DSRequest dsRequest) For a dataSource usingclient-side data integration
, return the data that should be sent to thedataURL
.protected void
transformResponse
(DSResponse dsResponse, DSRequest dsRequest, Object data) Modify the DSResponse object derived from the response returned from thedataURL
.void
updateCaches
(DSResponse dsResponse) Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed.void
updateCaches
(DSResponse dsResponse, DSRequest dsRequest) Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed.void
updateData
(Record updatedRecord) Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.void
updateData
(Record updatedRecord, DSCallback callback) void
updateData
(Record updatedRecord, DSCallback callback, DSRequest requestProperties) Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.protected boolean
useOfflineResponse
(DSRequest dsRequest, DSResponse dsResponse) Override point to allow application code to suppress use of a particular offline response.void
validateData
(Record values) Contacts the server to run server-side validation on a DSRequest and either returnsDSResponse.errors
validation errors or aDSResponse.status
code of 0.void
validateData
(Record values, DSCallback callback) void
validateData
(Record values, DSCallback callback, DSRequest requestProperties) Contacts the server to run server-side validation on a DSRequest and either returnsDSResponse.errors
validation errors or aDSResponse.status
code of 0.static Map[]
verifyDataSourcePair
(DataSource live, DataSource mock) A utility that checks for discrepancies between any two DataSources, typically used to warn about issues commonly found during the Reify design / development cycle, and logs its findings to the console.void
Display a file stored in a field of type:"binary" in a new browser window.void
void
Display a file stored in a field of type:"binary" in a new browser window.xmlSerialize
(JavaScriptObject data) Serialize a JavaScript object as XML.
xmlSerialize
(JavaScriptObject data, SerializationContext flags) Serialize a JavaScript object as XML.
xmlSerialize
(Record[] data, SerializationContext flags) Serialize a JavaScript object as XML.
xmlSerialize
(Record data, SerializationContext flags) Serialize a JavaScript object as XML.
xmlSerialize
(Map data, SerializationContext flags) Serialize a JavaScript object as XML.
Methods inherited from class com.smartgwt.client.core.BaseClass
addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getRuleScope, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setConfigOnly, setFactoryCreated, setJavaScriptObject, setProperty, setProperty, setProperty, setProperty, setRuleScope, setScClassName
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
-
Constructor Details
-
DataSource
public DataSource() -
DataSource
-
DataSource
-
-
Method Details
-
getOrCreateRef
-
create
-
setAddedAuditFields
public DataSource setAddedAuditFields(DataSourceField... addedAuditFields) throws IllegalStateException The list of extra manually managed fields that will be added to thefields
of theAudit DataSource
.This feature enables the storage of additional information in the
Audit DataSource
alongside the standard audit data. In order to do that the audited DataSource needs to declareauditDSConstructor
referring customserverConstructor
, so that all requests to add data to the Audit DataSource could be intercepted allowing to make changes to the new records (obtained usingDSRequest.getValues()
server-side API). In this particular use case values for theaddedAuditFields
need to be provided.Example of an audited DataSource (schematically):
<DataSource audit="true" auditDSConstructor="package.AuditDS"> <fields>....</fields> <addedAuditFields> <addedAuditField name="altitude" type="float" /> <addedAuditField name="longitude" type="float" /> <addedAuditField name="logCorrelationId" type="text" /> </addedAuditFields> </DataSource>
An example implementation of AuditDS could be as follows:public class AuditDS extends SQLDataSource { public DSResponse executeAdd(DSRequest req) throws Exception { // populate additional fields Map values = req.getValues(); values.put("altitude", 54.685); values.put("longitude", 25.286); values.put("logCorrelationId", "foobar"); // execute "add" request return super.executeAdd(req); } }
- Parameters:
addedAuditFields
- New addedAuditFields value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getAddedAuditFields
The list of extra manually managed fields that will be added to thefields
of theAudit DataSource
.This feature enables the storage of additional information in the
Audit DataSource
alongside the standard audit data. In order to do that the audited DataSource needs to declareauditDSConstructor
referring customserverConstructor
, so that all requests to add data to the Audit DataSource could be intercepted allowing to make changes to the new records (obtained usingDSRequest.getValues()
server-side API). In this particular use case values for theaddedAuditFields
need to be provided.Example of an audited DataSource (schematically):
<DataSource audit="true" auditDSConstructor="package.AuditDS"> <fields>....</fields> <addedAuditFields> <addedAuditField name="altitude" type="float" /> <addedAuditField name="longitude" type="float" /> <addedAuditField name="logCorrelationId" type="text" /> </addedAuditFields> </DataSource>
An example implementation of AuditDS could be as follows:public class AuditDS extends SQLDataSource { public DSResponse executeAdd(DSRequest req) throws Exception { // populate additional fields Map values = req.getValues(); values.put("altitude", 54.685); values.put("longitude", 25.286); values.put("logCorrelationId", "foobar"); // execute "add" request return super.executeAdd(req); } }
- Returns:
- Current addedAuditFields value. Default value is null
- See Also:
-
setAllowAdvancedCriteria
By default, all DataSources are assumed to be capable of handlingAdvancedCriteria
on fetch or filter type operations. This property may be set tofalse
to indicate that this dataSource does not support advancedCriteria. SeesupportsAdvancedCriteria()
for further information on this.NOTE: If you specify this property in a DataSource descriptor (
.ds.xml
file), it is enforced on the server. This means that if you run a request containing AdvancedCriteria against a DataSource that advertises itself asallowAdvancedCriteria:false
, it will be rejected.Note : This is an advanced setting
- Parameters:
allowAdvancedCriteria
- New allowAdvancedCriteria value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getAllowAdvancedCriteria
By default, all DataSources are assumed to be capable of handlingAdvancedCriteria
on fetch or filter type operations. This property may be set tofalse
to indicate that this dataSource does not support advancedCriteria. SeesupportsAdvancedCriteria()
for further information on this.NOTE: If you specify this property in a DataSource descriptor (
.ds.xml
file), it is enforced on the server. This means that if you run a request containing AdvancedCriteria against a DataSource that advertises itself asallowAdvancedCriteria:false
, it will be rejected.- Returns:
- Current allowAdvancedCriteria value. Default value is null
- See Also:
-
setAllowAggregation
This property indicates whether this DataSource supports aggregation/summarization of field values using thesummaryFunction
mechanism. Of thebuilt-in DataSource types
, SQL, Hibernate and JPA DataSources allow aggregation, as doclientOnly
DataSources.If you create a custom DataSource type that can handle the summary functions described in the overview linked above, you should set this flag true to indicate to Smart GWT that summary functions should be allowed - for example, in the
FilterBuilder
.Note : This is an advanced setting
- Parameters:
allowAggregation
- New allowAggregation value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getAllowAggregation
This property indicates whether this DataSource supports aggregation/summarization of field values using thesummaryFunction
mechanism. Of thebuilt-in DataSource types
, SQL, Hibernate and JPA DataSources allow aggregation, as doclientOnly
DataSources.If you create a custom DataSource type that can handle the summary functions described in the overview linked above, you should set this flag true to indicate to Smart GWT that summary functions should be allowed - for example, in the
FilterBuilder
.- Returns:
- Current allowAggregation value. Default value is null
- See Also:
-
setAllowDynamicTreeJoins
By default, custom dataSource implementations are assumed to be unable to supportdynamic tree joins
. If you create a custom dataSource that can support such joins, set this flag to trueNote : This is an advanced setting
- Parameters:
allowDynamicTreeJoins
- New allowDynamicTreeJoins value. Default value is null- Returns:
DataSource
instance, for chaining setter calls
-
getAllowDynamicTreeJoins
By default, custom dataSource implementations are assumed to be unable to supportdynamic tree joins
. If you create a custom dataSource that can support such joins, set this flag to true- Returns:
- Current allowDynamicTreeJoins value. Default value is null
-
setAllowRelatedFieldsInCriteria
This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries. See thesubquery filtering overview
for details. Note, onlyAdvancedCriteria
can contain related fields.All server-side DataSource implementations provide a level of support for related fields in criteria, but only
SQL DataSources
can handle cases that require conditions to be considered simultaneously with a join to the outer dataSource.Note : This is an advanced setting
- Parameters:
allowRelatedFieldsInCriteria
- New allowRelatedFieldsInCriteria value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getAllowRelatedFieldsInCriteria
This property indicates whether this DataSource supports referencees to related fields in criteria, either using qualified field names, or subqueries. See thesubquery filtering overview
for details. Note, onlyAdvancedCriteria
can contain related fields.All server-side DataSource implementations provide a level of support for related fields in criteria, but only
SQL DataSources
can handle cases that require conditions to be considered simultaneously with a join to the outer dataSource.- Returns:
- Current allowRelatedFieldsInCriteria value. Default value is null
- See Also:
-
setArrayCriteriaForceExact
public DataSource setArrayCriteriaForceExact(Boolean arrayCriteriaForceExact) throws IllegalStateException With ordinarysimple criteria
, it is possible to provide an array of values for a given field, which means "any of these values". For example:var criteria = { field1 : "value1", field2 : ["value2", "value3"] }
At first glance, this criteria appears to mean "select records where 'field1' is 'value1' and 'field2' is one of 'value2' or 'value3'". However, if the prevailingtextMatchStyle
is "substring" - as it would be if, for example, you had issued afilterData()
call - then this criteria means "select records where 'field1' contains 'value1' somewhere, and 'field2' contains either 'value2' or 'value3'"Depending on your requirement, this may or may not be what you want, and you can control it by setting the
textMatchStyle
on yourDSRequest
, or by setting a defaulttextMatchStyle
on the DataSource (defaultTextMatchStyle
), or by specifying that thetextMatchStyle
should be ignored for certain fields (DataSourceField.ignoreTextMatchStyle
)However, a common use case is that you want "substring" style filtering on one or more single-valued fields, but exact matching on a list-valued field. For example, say you want a list of customers based in certain cities, with a name matching the substring "software":
var criteria = { name : "software", city : ["York", "Newport", "Orleans"] }
Here, using substring matching on the "city" field is likely to give incorrect results, as it will match a number of US cities in addition to the three European cities intended (New York, Yorktown, New Orleans, Newport News, and probably others). And even if this is not an issue for your particular use case, and correct results can be obtained with a substring search, it is very likely to be more costly performance-wise than the exact value match that you really need (potentially much more costly).You could achieve exact matching in the above case by marking the "city" field as
ignoreTextMatchStyle:true
, but that would mean you couldn't perform substring searches on that field in other use cases where that might be desirable.In cases like this, Smart GWT by default treats list-valued simple criteria as if
ignoreTextMatchStyle
is in force for that field. If you want to switch this behavior off, and have list-valued simple criteria handled with the prevailingtextMatchStyle
, setarrayCriteriaForceExact
to false. It is also possible to set this flag per-operationBinding and per-DSRequest - seeOperationBinding.arrayCriteriaForceExact
andDSRequest.arrayCriteriaForceExact
If you want to switch this behavior off across the entire system, set the flag in your
server.properties
file:arrayCriteriaForceExact: false
This will only have an effect for server-side DataSources; if you want to change this flag globally forclientOnly
dataSources, change the default in the client-sideDataSource
class, like so:isc.DataSource.addProperties({arrayCriteriaForceExact: false});
If you do change the global defaults, it is still possible to override per-dataSource or per-operationBinding, as described above.Note, all of this only applies to simple criteria. If your dataSource
supports AdvancedCriteria
, that gives you much finer and more complete control over the exact meaning of individual criterions.- Parameters:
arrayCriteriaForceExact
- New arrayCriteriaForceExact value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getArrayCriteriaForceExact
With ordinarysimple criteria
, it is possible to provide an array of values for a given field, which means "any of these values". For example:var criteria = { field1 : "value1", field2 : ["value2", "value3"] }
At first glance, this criteria appears to mean "select records where 'field1' is 'value1' and 'field2' is one of 'value2' or 'value3'". However, if the prevailingtextMatchStyle
is "substring" - as it would be if, for example, you had issued afilterData()
call - then this criteria means "select records where 'field1' contains 'value1' somewhere, and 'field2' contains either 'value2' or 'value3'"Depending on your requirement, this may or may not be what you want, and you can control it by setting the
textMatchStyle
on yourDSRequest
, or by setting a defaulttextMatchStyle
on the DataSource (defaultTextMatchStyle
), or by specifying that thetextMatchStyle
should be ignored for certain fields (DataSourceField.ignoreTextMatchStyle
)However, a common use case is that you want "substring" style filtering on one or more single-valued fields, but exact matching on a list-valued field. For example, say you want a list of customers based in certain cities, with a name matching the substring "software":
var criteria = { name : "software", city : ["York", "Newport", "Orleans"] }
Here, using substring matching on the "city" field is likely to give incorrect results, as it will match a number of US cities in addition to the three European cities intended (New York, Yorktown, New Orleans, Newport News, and probably others). And even if this is not an issue for your particular use case, and correct results can be obtained with a substring search, it is very likely to be more costly performance-wise than the exact value match that you really need (potentially much more costly).You could achieve exact matching in the above case by marking the "city" field as
ignoreTextMatchStyle:true
, but that would mean you couldn't perform substring searches on that field in other use cases where that might be desirable.In cases like this, Smart GWT by default treats list-valued simple criteria as if
ignoreTextMatchStyle
is in force for that field. If you want to switch this behavior off, and have list-valued simple criteria handled with the prevailingtextMatchStyle
, setarrayCriteriaForceExact
to false. It is also possible to set this flag per-operationBinding and per-DSRequest - seeOperationBinding.arrayCriteriaForceExact
andDSRequest.arrayCriteriaForceExact
If you want to switch this behavior off across the entire system, set the flag in your
server.properties
file:arrayCriteriaForceExact: false
This will only have an effect for server-side DataSources; if you want to change this flag globally forclientOnly
dataSources, change the default in the client-sideDataSource
class, like so:isc.DataSource.addProperties({arrayCriteriaForceExact: false});
If you do change the global defaults, it is still possible to override per-dataSource or per-operationBinding, as described above.Note, all of this only applies to simple criteria. If your dataSource
supports AdvancedCriteria
, that gives you much finer and more complete control over the exact meaning of individual criterions.- Returns:
- Current arrayCriteriaForceExact value. Default value is null
- See Also:
-
setAutoCacheAllData
When a DataSource is notcacheAllData
:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch tocacheAllData:true
and prevent further server-trips for fetch requests.cacheAllData
is automatically enabled in either of these conditions:- The request has no criteria and no startRow/endRow request properties. The latter can be
accomplished by disabling paging with a
dataFetchMode
setting of "basic" or "local" or by an explicit fetchData request with those request properties excluded. - The request has no criteria but has startRow/endRow specified and the response received has
all data available (
startRow:0
andendRow:totalRows
).
- Parameters:
autoCacheAllData
- New autoCacheAllData value. Default value is false- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
- The request has no criteria and no startRow/endRow request properties. The latter can be
accomplished by disabling paging with a
-
getAutoCacheAllData
When a DataSource is notcacheAllData
:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch tocacheAllData:true
and prevent further server-trips for fetch requests.cacheAllData
is automatically enabled in either of these conditions:- The request has no criteria and no startRow/endRow request properties. The latter can be
accomplished by disabling paging with a
dataFetchMode
setting of "basic" or "local" or by an explicit fetchData request with those request properties excluded. - The request has no criteria but has startRow/endRow specified and the response received has
all data available (
startRow:0
andendRow:totalRows
).
- Returns:
- Current autoCacheAllData value. Default value is false
- The request has no criteria and no startRow/endRow request properties. The latter can be
accomplished by disabling paging with a
-
setAutoConvertRelativeDates
public DataSource setAutoConvertRelativeDates(Boolean autoConvertRelativeDates) throws IllegalStateException Whether to convert relative date values to concrete date values before sending to the server. Default value is true, which means that the server does not need to understand how to filter using relative dates - it receives all date values as absolute dates.If the server would receive relative date values from the client, by default they would be unchanged in DMI and automatically converted during the request execution. This may be changed via
server.properties
settingdatasources.autoConvertRelativeDates
which can be set to the following values:postDMI
- the default value described abovepreDMI
- relative date values will be converted to absolute date values right away, so they will be already converted in DMIdisabled
- relative date values will not be automatically converted, so it must be done completely manually or by calling theDSRequest.convertRelativeDates()
server-side API.DataSource.convertRelativeDates(Criterion)
server-side API.- Parameters:
autoConvertRelativeDates
- New autoConvertRelativeDates value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getAutoConvertRelativeDates
Whether to convert relative date values to concrete date values before sending to the server. Default value is true, which means that the server does not need to understand how to filter using relative dates - it receives all date values as absolute dates.If the server would receive relative date values from the client, by default they would be unchanged in DMI and automatically converted during the request execution. This may be changed via
server.properties
settingdatasources.autoConvertRelativeDates
which can be set to the following values:postDMI
- the default value described abovepreDMI
- relative date values will be converted to absolute date values right away, so they will be already converted in DMIdisabled
- relative date values will not be automatically converted, so it must be done completely manually or by calling theDSRequest.convertRelativeDates()
server-side API.DataSource.convertRelativeDates(Criterion)
server-side API.- Returns:
- Current autoConvertRelativeDates value. Default value is true
-
setAutoDeriveTitles
If set, titles are automatically derived fromfield.name
for any field that does not have afield.title
and is not markedhidden
:true, by calling the methodgetAutoTitle()
.- Parameters:
autoDeriveTitles
- New autoDeriveTitles value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getAutoDeriveTitles
public boolean getAutoDeriveTitles()If set, titles are automatically derived fromfield.name
for any field that does not have afield.title
and is not markedhidden
:true, by calling the methodgetAutoTitle()
.- Returns:
- Current autoDeriveTitles value. Default value is true
-
setAutoDiscoverTree
CausesTree.discoverTree()
to be called on dsResponse.data in order to automatically discover tree structures in the response data.If autoDiscoverTree is set, discoverTree() is called after the default dsResponse.data has been derived (
recordXPath
andvalueXPath
have been applied) and aftertransformResponse()
has been called.If a DataSourceField is declared with
childrenProperty:true
, discoverTree() will be invoked withsettings.newChildrenProperty
set to the name of the field marked as the childrenField. Similarly, if the DataSource has atitleField
it will be used as thesettings.nameProperty
.- Parameters:
autoDiscoverTree
- New autoDiscoverTree value. Default value is false- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getAutoDiscoverTree
public boolean getAutoDiscoverTree()CausesTree.discoverTree()
to be called on dsResponse.data in order to automatically discover tree structures in the response data.If autoDiscoverTree is set, discoverTree() is called after the default dsResponse.data has been derived (
recordXPath
andvalueXPath
have been applied) and aftertransformResponse()
has been called.If a DataSourceField is declared with
childrenProperty:true
, discoverTree() will be invoked withsettings.newChildrenProperty
set to the name of the field marked as the childrenField. Similarly, if the DataSource has atitleField
it will be used as thesettings.nameProperty
.- Returns:
- Current autoDiscoverTree value. Default value is false
-
setCacheAcrossOperationIds
public DataSource setCacheAcrossOperationIds(Boolean cacheAcrossOperationIds) throws IllegalStateException WhencacheAllData
mode is enabled and acacheAllOperationId
has been set, this flag affects whether cached results are used for all "fetch" requests regardless of theirDSRequest.operationId
, or are used only for "fetch" requests that use thecacheAllOperationId
, allowing other requests to go to server normally.Default of
true
means that thecacheAllOperationId
will be used to fetch all rows, but the resulting cache will be used for all "fetch" operations regardless of theoperationId
specified on the request.Switching to "false" effectively creates caching just for one specific
operationId
- thecacheAllOperationId
- while allowing all other requests to go to the server normally.- Parameters:
cacheAcrossOperationIds
- New cacheAcrossOperationIds value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getCacheAcrossOperationIds
WhencacheAllData
mode is enabled and acacheAllOperationId
has been set, this flag affects whether cached results are used for all "fetch" requests regardless of theirDSRequest.operationId
, or are used only for "fetch" requests that use thecacheAllOperationId
, allowing other requests to go to server normally.Default of
true
means that thecacheAllOperationId
will be used to fetch all rows, but the resulting cache will be used for all "fetch" operations regardless of theoperationId
specified on the request.Switching to "false" effectively creates caching just for one specific
operationId
- thecacheAllOperationId
- while allowing all other requests to go to the server normally.- Returns:
- Current cacheAcrossOperationIds value. Default value is true
-
setCacheAllData
Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request. However, unlike aclientOnly
DataSource, this DataSource will still save changes normally, sending remote requests.You can manually set this attribute after initialization by calling
setCacheAllData()
; settingautoCacheAllData
:true causes a DataSource to automatically switch tocacheAllData:true
when a fetch results in the entire dataset being brought client-side.To cause automatic cache updates, you can set
cacheMaxAge
to a number of seconds and once data has been client-side for that length of time, the next fetch causes the cache to be dropped and a new cache retrieved.Note that multiple
operationBindings
of type "fetch" which return distinct results will not work withcacheAllData
: only one cache is created and is used for all fetch operations, regardless of whetherDSRequest.operationId
has been set. However, "fetch" operationBindings used as aOperationBinding.cacheSyncOperation
will work normally, so long as they return all data fields that are returned by the default "fetch" operation, so that the cache can be updated.To specify which operationId to use for fetching all data, use
cacheAllOperationId
.To use the cache only for requests that have the
cacheAllOperationId
, allowing any other operationId (or absence of an operationId) to contact the server as normal, setcacheAcrossOperationIds
.
If this method is called after the component has been drawn/initialized: Call this method to switch cacheAllData on or off after initialization. Passing ashouldCache
value of false clears any existing client-side cache, cancels any outstanding requests for a full cache and issues any other pending requests normally.- Parameters:
cacheAllData
- New value forcacheAllData
. Default value is null- Returns:
DataSource
instance, for chaining setter calls
-
getCacheAllData
Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request. However, unlike aclientOnly
DataSource, this DataSource will still save changes normally, sending remote requests.You can manually set this attribute after initialization by calling
setCacheAllData()
; settingautoCacheAllData
:true causes a DataSource to automatically switch tocacheAllData:true
when a fetch results in the entire dataset being brought client-side.To cause automatic cache updates, you can set
cacheMaxAge
to a number of seconds and once data has been client-side for that length of time, the next fetch causes the cache to be dropped and a new cache retrieved.Note that multiple
operationBindings
of type "fetch" which return distinct results will not work withcacheAllData
: only one cache is created and is used for all fetch operations, regardless of whetherDSRequest.operationId
has been set. However, "fetch" operationBindings used as aOperationBinding.cacheSyncOperation
will work normally, so long as they return all data fields that are returned by the default "fetch" operation, so that the cache can be updated.To specify which operationId to use for fetching all data, use
cacheAllOperationId
.To use the cache only for requests that have the
cacheAllOperationId
, allowing any other operationId (or absence of an operationId) to contact the server as normal, setcacheAcrossOperationIds
.- Returns:
- Current cacheAllData value. Default value is null
-
setCacheAllOperationId
DSRequest.operationId
to use for fetching data in casecacheAllData
is true. By default a standard fetch operation is used (with nooperationId
specified).- Parameters:
cacheAllOperationId
- New cacheAllOperationId value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getCacheAllOperationId
DSRequest.operationId
to use for fetching data in casecacheAllData
is true. By default a standard fetch operation is used (with nooperationId
specified).- Returns:
- Current cacheAllOperationId value. Default value is null
-
setCacheMaxAge
The maximum time, in seconds, to maintain the client-side cache. If a fetch occurs after the cacheMaxAge has expired, the current cache will be dropped and another complete cache fetched.- Parameters:
cacheMaxAge
- New cacheMaxAge value. Default value is 60- Returns:
DataSource
instance, for chaining setter calls
-
getCacheMaxAge
public int getCacheMaxAge()The maximum time, in seconds, to maintain the client-side cache. If a fetch occurs after the cacheMaxAge has expired, the current cache will be dropped and another complete cache fetched.- Returns:
- Current cacheMaxAge value. Default value is 60
-
setCallbackParam
Applies only to dataFormat: "json" anddataTransport
:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response.- Parameters:
callbackParam
- New callbackParam value. Default value is "callback"- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getCallbackParam
Applies only to dataFormat: "json" anddataTransport
:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response.- Returns:
- Current callbackParam value. Default value is "callback"
- See Also:
-
setCanAggregate
By default, all DataSources are assumed to be capable of handlingServerSummaries
on fetch or filter type operations. This property may be set tofalse
to indicate that this dataSource does not support serverSummaries.NOTE: If you specify this property in a DataSource descriptor (
.ds.xml
file), it is enforced on the server. This means that if you run a request containing serverSummaries against a DataSource that advertises itself ascanAggregate:false
, it will be rejected.Note : This is an advanced setting
- Parameters:
canAggregate
- New canAggregate value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getCanAggregate
By default, all DataSources are assumed to be capable of handlingServerSummaries
on fetch or filter type operations. This property may be set tofalse
to indicate that this dataSource does not support serverSummaries.NOTE: If you specify this property in a DataSource descriptor (
.ds.xml
file), it is enforced on the server. This means that if you run a request containing serverSummaries against a DataSource that advertises itself ascanAggregate:false
, it will be rejected.- Returns:
- Current canAggregate value. Default value is null
- See Also:
-
setCanMultiSort
When true, indicates that this DataSource supports multi-level sorting.- Parameters:
canMultiSort
- New canMultiSort value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getCanMultiSort
public boolean getCanMultiSort()When true, indicates that this DataSource supports multi-level sorting.- Returns:
- Current canMultiSort value. Default value is true
-
setChildrenField
fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierarchical data structure, rather than a flat list of nodes linked by foreignKey.
Note this is an alternative to settingDataSourceField.childrenProperty
directly on the childrenField object.By default the children field will be assumed to be
multiple
, for XML databinding. This implies that child data should be delivered in the format:<childrenFieldName> <item name="firstChild" ...> <item name="secondChild" ...> </childrenFieldName>
However data may also be delivered as a direct list ofchildrenFieldName
elements:<childrenFieldName name="firstChild" ...> <childrenFieldName name="secondChild" ...>
If you want to return your data in this format, you will need to explicitly setmultiple
to false in the appropriate dataSource field definition.- Parameters:
childrenField
- New childrenField value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getChildrenField
fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierarchical data structure, rather than a flat list of nodes linked by foreignKey.
Note this is an alternative to settingDataSourceField.childrenProperty
directly on the childrenField object.By default the children field will be assumed to be
multiple
, for XML databinding. This implies that child data should be delivered in the format:<childrenFieldName> <item name="firstChild" ...> <item name="secondChild" ...> </childrenFieldName>
However data may also be delivered as a direct list ofchildrenFieldName
elements:<childrenFieldName name="firstChild" ...> <childrenFieldName name="secondChild" ...>
If you want to return your data in this format, you will need to explicitly setmultiple
to false in the appropriate dataSource field definition.- Returns:
- Current childrenField value. Default value is null
- See Also:
-
setClientOnly
A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory asDSRequests
are executed on it. Any changes are lost when the user reloads the page or navigates away.A clientOnly DataSource will return responses asynchronously, just as a DataSource accessing remote data does. This allows a clientOnly DataSource to be used as a temporary placeholder while a real DataSource is being implemented - if a clientOnly DataSource is replaced by a DataSource that accesses a remote data store, UI code for components that used the clientOnly DataSource will not need be changed.
A clientOnly DataSource can also be used as a shared cache of modifiable data across multiple UI components when immediate saving is not desirable. In this case, several components may interact with a clientOnly DataSource and get the benefit of
ResultSet
behaviors such as automatic cache sync and in-browser data filtering and sorting. When it's finally time to save,cacheData
can be inspected for changes and data can be saved to the original DataSource viaaddData()
,updateData()
andremoveData()
, possibly in atransactional queue
. Note thatgetClientOnlyDataSource()
lets you easily obtain aclientOnly
DataSource representing a subset of the data available from a normal DataSource.See also
cacheAllData
- acacheAllData
behaves like a write-through cache, performing fetch and filter operations locally while still performing remote save operations immediately.ClientOnly DataSources can be populated programmatically via
cacheData
- seethis discussion
for other ways to populate a client-only DataSource with data.
If this method is called after the component has been drawn/initialized: Switch into or out of clientOnly mode, taking the cache from the cacheAllData ResultSet if it exists.- Parameters:
clientOnly
- New clientOnly value. Default value is false- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getClientOnly
A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory asDSRequests
are executed on it. Any changes are lost when the user reloads the page or navigates away.A clientOnly DataSource will return responses asynchronously, just as a DataSource accessing remote data does. This allows a clientOnly DataSource to be used as a temporary placeholder while a real DataSource is being implemented - if a clientOnly DataSource is replaced by a DataSource that accesses a remote data store, UI code for components that used the clientOnly DataSource will not need be changed.
A clientOnly DataSource can also be used as a shared cache of modifiable data across multiple UI components when immediate saving is not desirable. In this case, several components may interact with a clientOnly DataSource and get the benefit of
ResultSet
behaviors such as automatic cache sync and in-browser data filtering and sorting. When it's finally time to save,cacheData
can be inspected for changes and data can be saved to the original DataSource viaaddData()
,updateData()
andremoveData()
, possibly in atransactional queue
. Note thatgetClientOnlyDataSource()
lets you easily obtain aclientOnly
DataSource representing a subset of the data available from a normal DataSource.See also
cacheAllData
- acacheAllData
behaves like a write-through cache, performing fetch and filter operations locally while still performing remote save operations immediately.ClientOnly DataSources can be populated programmatically via
cacheData
- seethis discussion
for other ways to populate a client-only DataSource with data.- Returns:
- Current clientOnly value. Default value is false
- See Also:
-
setCriteriaPolicy
Decides under what conditions theResultSet
cache should be dropped when theResultSet.criteria
changes.Note : This is an advanced setting
- Parameters:
criteriaPolicy
- New criteriaPolicy value. Default value is "dropOnShortening"- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getCriteriaPolicy
Decides under what conditions theResultSet
cache should be dropped when theResultSet.criteria
changes.- Returns:
- Current criteriaPolicy value. Default value is "dropOnShortening"
- See Also:
-
setDataField
Name of the field that has the most pertinent numeric, date, or enum value, for use when aDataBoundComponent
needs to show a short summary of a record.For example, for a DataSource of employees, good choices might be the "salary" field, "hire date" or "status" (active, vacation, on leave, etc).
Unlike
titleField
, dataField is not automatically determined in the absence of an explicit setting.- Parameters:
dataField
- New dataField value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getDataField
Name of the field that has the most pertinent numeric, date, or enum value, for use when aDataBoundComponent
needs to show a short summary of a record.For example, for a DataSource of employees, good choices might be the "salary" field, "hire date" or "status" (active, vacation, on leave, etc).
Unlike
titleField
, dataField is not automatically determined in the absence of an explicit setting.- Returns:
- Current dataField value. Default value is null
- See Also:
-
setDataFormat
Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, whenfetchData()
is called).- Parameters:
dataFormat
- New dataFormat value. Default value is "iscServer"- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getDataFormat
Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, whenfetchData()
is called).- Returns:
- Current dataFormat value. Default value is "iscServer"
- See Also:
-
setDataTransport
Transport to use for all operations on this DataSource. Defaults todefaultTransport
. This would typically only be set to enable "scriptInclude" transport for contactingJSON
web services hosted on servers other than the origin server.When using the "scriptInclude" transport, be sure to set
callbackParam
orOperationBinding.callbackParam
to match the name of the query parameter name expected by your JSON service provider.- Parameters:
dataTransport
- New dataTransport value. Default value is RPCManager.defaultTransport- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getDataTransport
Transport to use for all operations on this DataSource. Defaults todefaultTransport
. This would typically only be set to enable "scriptInclude" transport for contactingJSON
web services hosted on servers other than the origin server.When using the "scriptInclude" transport, be sure to set
callbackParam
orOperationBinding.callbackParam
to match the name of the query parameter name expected by your JSON service provider.- Returns:
- Current dataTransport value. Default value is RPCManager.defaultTransport
- See Also:
-
setDataURL
Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis viaOperationBinding.dataURL
.NOTE: Best practice is to use the same
dataURL
for all DataSources which fulfill DSRequests via the server-side RPCManager API. Otherwise, cross-DataSourceoperation queuing
will not be possible.dataURL and
RestConnector
dataURL
is also used to configure the address of the target REST server for aRestConnector
DataSource. Typically this is done at theoperationBinding level
, because the URLs of REST services often encode things about the service itself, like whether it is a fetch or an update. However, if your REST service does use the same URL for every service, or most services, you can configure it here at the DataSource level.As discussed in the
RestConnector overview
, many elements ofRestConnector
config can be Velocity templates, anddataURL
is one such element. For example:<operationBinding operationType="fetch" operationId="fetchByPK"> <dataURL>$config['rest.server.base.url']/fetch/$criteria.pk</dataURL> </operationBinding>
NOTE: Because the server-sideRestConnector
implementation uses thedataURL
property to configure the address of the target REST server, and that property also has meaning on the client, if you are using aRestConnector
DataSource, you should specify thedataURL
of the target REST server inside theserverConfig
block- Parameters:
dataURL
- New dataURL value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getDataURL
Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis viaOperationBinding.dataURL
.NOTE: Best practice is to use the same
dataURL
for all DataSources which fulfill DSRequests via the server-side RPCManager API. Otherwise, cross-DataSourceoperation queuing
will not be possible.dataURL and
RestConnector
dataURL
is also used to configure the address of the target REST server for aRestConnector
DataSource. Typically this is done at theoperationBinding level
, because the URLs of REST services often encode things about the service itself, like whether it is a fetch or an update. However, if your REST service does use the same URL for every service, or most services, you can configure it here at the DataSource level.As discussed in the
RestConnector overview
, many elements ofRestConnector
config can be Velocity templates, anddataURL
is one such element. For example:<operationBinding operationType="fetch" operationId="fetchByPK"> <dataURL>$config['rest.server.base.url']/fetch/$criteria.pk</dataURL> </operationBinding>
NOTE: Because the server-sideRestConnector
implementation uses thedataURL
property to configure the address of the target REST server, and that property also has meaning on the client, if you are using aRestConnector
DataSource, you should specify thedataURL
of the target REST server inside theserverConfig
block- Returns:
- Current dataURL value. Default value is null
- See Also:
-
setDeepCloneNonFieldValuesOnEdit
When editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or bydataPath
). If this flag is not explicitly set, it defaults to the value of the same-named static property,deepCloneNonFieldValuesOnEdit
. This flag can also be overridden per-component - seeDataBoundComponent.deepCloneNonFieldValuesOnEdit
.Note, a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays; a "shallow clone" is a copy created by simply copying the top-level attributes of an object; if you have nested objects that are copied like this, the "copies" are actual references to the original objects.
Like the other
deepCloneOnEdit
settings, this flag only has an effect if you are editing a values object that contains nested objects or arrays.Note : This is an advanced setting
- Parameters:
deepCloneNonFieldValuesOnEdit
- New deepCloneNonFieldValuesOnEdit value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getDeepCloneNonFieldValuesOnEdit
When editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of values that are not associated with a field (ie, attributes on the record that do not map to a component field either directly by name, or bydataPath
). If this flag is not explicitly set, it defaults to the value of the same-named static property,deepCloneNonFieldValuesOnEdit
. This flag can also be overridden per-component - seeDataBoundComponent.deepCloneNonFieldValuesOnEdit
.Note, a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays; a "shallow clone" is a copy created by simply copying the top-level attributes of an object; if you have nested objects that are copied like this, the "copies" are actual references to the original objects.
Like the other
deepCloneOnEdit
settings, this flag only has an effect if you are editing a values object that contains nested objects or arrays.- Returns:
- Current deepCloneNonFieldValuesOnEdit value. Default value is null
- See Also:
-
setDeepCloneOnEdit
Before we start editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays). If this flag is explicitly set to false, we perform a shallow clone of the underlying values before edit (a "shallow clone" is a copy created by simply copying the top-level attributes of an object). Note, this setting only affects deep-cloning of attributes that are bound to a field; for other, non-field values, seedeepCloneNonFieldValuesOnEdit
.If this flag is not explicitly set, it defaults to the value of the same-named static property,
deepCloneOnEdit
. This flag can also be overridden per-component and per-field - seeDataBoundComponent.deepCloneOnEdit
andDataSourceField.deepCloneOnEdit
.Note, this flag only has an effect if you are editing a values object that contains nested objects or arrays, using
dataPath
s. When editing "flat" data - the mainstream case - there is no difference between a deep clone and a shallow clone.Note : This is an advanced setting
- Parameters:
deepCloneOnEdit
- New deepCloneOnEdit value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getDeepCloneOnEdit
Before we start editing values inDataBoundComponent
s bound to this dataSource, should we perform a deep clone of the underlying values (a "deep clone" is one created by traversing the original values object recursively, cloning the contents of nested objects and arrays). If this flag is explicitly set to false, we perform a shallow clone of the underlying values before edit (a "shallow clone" is a copy created by simply copying the top-level attributes of an object). Note, this setting only affects deep-cloning of attributes that are bound to a field; for other, non-field values, seedeepCloneNonFieldValuesOnEdit
.If this flag is not explicitly set, it defaults to the value of the same-named static property,
deepCloneOnEdit
. This flag can also be overridden per-component and per-field - seeDataBoundComponent.deepCloneOnEdit
andDataSourceField.deepCloneOnEdit
.Note, this flag only has an effect if you are editing a values object that contains nested objects or arrays, using
dataPath
s. When editing "flat" data - the mainstream case - there is no difference between a deep clone and a shallow clone.- Returns:
- Current deepCloneOnEdit value. Default value is null
- See Also:
-
setDefaultTextMatchStyle
public DataSource setDefaultTextMatchStyle(TextMatchStyle defaultTextMatchStyle) throws IllegalStateException The default textMatchStyle to use forDSRequest
s that do not explicitly state atextMatchStyle
. Note, however, that DSRequests issued byListGrid
s and othercomponents
will generally have a setting for textMatchStyle on the component itself (seeListGrid.autoFetchTextMatchStyle
, for example).- Parameters:
defaultTextMatchStyle
- New defaultTextMatchStyle value. Default value is "exact"- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getDefaultTextMatchStyle
The default textMatchStyle to use forDSRequest
s that do not explicitly state atextMatchStyle
. Note, however, that DSRequests issued byListGrid
s and othercomponents
will generally have a setting for textMatchStyle on the component itself (seeListGrid.autoFetchTextMatchStyle
, for example).- Returns:
- Current defaultTextMatchStyle value. Default value is "exact"
- See Also:
-
setDescription
An optional description of the DataSource's content. Not automatically exposed on any component, but useful for developer documentation, and as such is included on anyOpenAPI specification
generated by the framework. Markdown is a commonly used syntax, but you may also embed HTML content in a CDATA tag.- Parameters:
description
- New description value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getDescription
An optional description of the DataSource's content. Not automatically exposed on any component, but useful for developer documentation, and as such is included on anyOpenAPI specification
generated by the framework. Markdown is a commonly used syntax, but you may also embed HTML content in a CDATA tag.- Returns:
- Current description value. Default value is null
-
setDescriptionField
Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.For example, for a DataSource representing employees, a field containing the employee's "bio" might be a good choice, or for an email message, the message body.
If descriptionField is unset, it defaults to any field named "description" or "desc" in the record, or the first long text field (greater than 255 characters) in the record, or null if no such field exists.
- Parameters:
descriptionField
- New descriptionField value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getDescriptionField
Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.For example, for a DataSource representing employees, a field containing the employee's "bio" might be a good choice, or for an email message, the message body.
If descriptionField is unset, it defaults to any field named "description" or "desc" in the record, or the first long text field (greater than 255 characters) in the record, or null if no such field exists.
- Returns:
- Current descriptionField value. Default value is null
- See Also:
-
setDiscoverTreeSettings
public DataSource setDiscoverTreeSettings(DiscoverTreeSettings discoverTreeSettings) throws IllegalStateException Settings to use when discoverTree() is automatcially called becauseautoDiscoverTree
is set to true for this DataSource- Parameters:
discoverTreeSettings
- New discoverTreeSettings value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getDiscoverTreeSettings
Settings to use when discoverTree() is automatcially called becauseautoDiscoverTree
is set to true for this DataSource- Returns:
- Current discoverTreeSettings value. Default value is null
-
setDropExtraFields
Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.For
JSON
data, this means extra properties in selected objects are dropped.By default, for DMI DSResponses, DSResponse.data is filtered on the server to just the set of fields defined on the DataSource (see the overview in
DMI
).This type of filtering can also be enabled for non-DMI DSResponses. By default it is enabled for Hibernate and JPA datasources to avoid unintentional lazy loading too much of a data model. For the rest of datasources this is disabled by default.
Explicitly setting this property to
false
disables (or totrue
enables) this filtering for this DataSource only. This setting overrides the configuration inserver.properties
. This setting can be overridden byServerObject.dropExtraFields
.- Parameters:
dropExtraFields
- New dropExtraFields value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getDropExtraFields
Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.For
JSON
data, this means extra properties in selected objects are dropped.By default, for DMI DSResponses, DSResponse.data is filtered on the server to just the set of fields defined on the DataSource (see the overview in
DMI
).This type of filtering can also be enabled for non-DMI DSResponses. By default it is enabled for Hibernate and JPA datasources to avoid unintentional lazy loading too much of a data model. For the rest of datasources this is disabled by default.
Explicitly setting this property to
false
disables (or totrue
enables) this filtering for this DataSource only. This setting overrides the configuration inserver.properties
. This setting can be overridden byServerObject.dropExtraFields
.- Returns:
- Current dropExtraFields value. Default value is null
- See Also:
-
setDropUnknownCriteria
If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client. This property is useful for cases where you custom server logic makes use of criteria values to determine what set of records to return to the client, but the data does not actually have record values for these fields and as such the client-side filtering logic should ignore them.- Parameters:
dropUnknownCriteria
- New dropUnknownCriteria value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getDropUnknownCriteria
If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client. This property is useful for cases where you custom server logic makes use of criteria values to determine what set of records to return to the client, but the data does not actually have record values for these fields and as such the client-side filtering logic should ignore them.- Returns:
- Current dropUnknownCriteria value. Default value is true
-
setEnforceSecurityOnClient
public DataSource setEnforceSecurityOnClient(Boolean enforceSecurityOnClient) throws IllegalStateException Indicates thatDeclarativeSecurity
should be enforced on the client. This property only applies toClient Only DataSources
. If property is unset for a clientOnly DataSource it will be settrue
automatically. Set this property tofalse
to explicitly disable this feature for a clientOnly DataSource.Note that certain security features are not supported on the client like Velocity rules.
- Parameters:
enforceSecurityOnClient
- New enforceSecurityOnClient value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getEnforceSecurityOnClient
Indicates thatDeclarativeSecurity
should be enforced on the client. This property only applies toClient Only DataSources
. If property is unset for a clientOnly DataSource it will be settrue
automatically. Set this property tofalse
to explicitly disable this feature for a clientOnly DataSource.Note that certain security features are not supported on the client like Velocity rules.
- Returns:
- Current enforceSecurityOnClient value. Default value is null
- See Also:
-
setEnumConstantProperty
The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if theEnumTranslateStrategy
is set to "bean". Defaults to "_constant" if not set.This property is only applicable if you are using the Smart GWT server
Note : This is an advanced setting
- Parameters:
enumConstantProperty
- New enumConstantProperty value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
setEnumOrdinalProperty
The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if theEnumTranslateStrategy
is set to "bean". Defaults to "_ordinal" if not set.This property is only applicable if you are using the Smart GWT server
Note : This is an advanced setting
- Parameters:
enumOrdinalProperty
- New enumOrdinalProperty value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
setEnumTranslateStrategy
public DataSource setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy) throws IllegalStateException Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript. This property is only applicable if you are using the Smart GWT serverNote : This is an advanced setting
- Parameters:
enumTranslateStrategy
- New enumTranslateStrategy value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
setGlobalNamespaces
Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.The default value is:
globalNamespaces : { xsi: "http://www.w3.org/2001/XMLSchema-instance", xsd: "http://www.w3.org/2001/XMLSchema" },
This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.Note that some web services will only accept specific revisions of the XML Schema URI. If xsi-namespaced attributes seem to be ignored by an older webservice, try the URI "http://www.w3.org/1999/XMLSchema-instance" instead.
- Parameters:
globalNamespaces
- New globalNamespaces value. Default value is ...- Returns:
DataSource
instance, for chaining setter calls
-
getGlobalNamespaces
Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.The default value is:
globalNamespaces : { xsi: "http://www.w3.org/2001/XMLSchema-instance", xsd: "http://www.w3.org/2001/XMLSchema" },
This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.Note that some web services will only accept specific revisions of the XML Schema URI. If xsi-namespaced attributes seem to be ignored by an older webservice, try the URI "http://www.w3.org/1999/XMLSchema-instance" instead.
- Returns:
- Current globalNamespaces value. Default value is ...
-
setIconField
Designates a field oftype
:"image" as the field to use when rendering a record as an image, for example, in aTileGrid
.For example, for a DataSource of employees, a "photo" field of type "image" should be designated as the iconField.
If not explicitly set, iconField looks for fields named "picture", "thumbnail", "icon", "image" and "img", in that order, and will use any of these fields as the iconField if it exists and has type "image".
To avoid any field being used as the iconField, set iconField to
null
.- Parameters:
iconField
- New iconField value. Default value is see below- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getIconField
Designates a field oftype
:"image" as the field to use when rendering a record as an image, for example, in aTileGrid
.For example, for a DataSource of employees, a "photo" field of type "image" should be designated as the iconField.
If not explicitly set, iconField looks for fields named "picture", "thumbnail", "icon", "image" and "img", in that order, and will use any of these fields as the iconField if it exists and has type "image".
To avoid any field being used as the iconField, set iconField to
null
.- Returns:
- Current iconField value. Default value is see below
- See Also:
-
setIgnoreTextMatchStyleCaseSensitive
public DataSource setIgnoreTextMatchStyleCaseSensitive(Boolean ignoreTextMatchStyleCaseSensitive) throws IllegalStateException For fields on this dataSource that specifyignoreTextMatchStyle
true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. This property dictates whether that match is case-sensitive like the "exactCase" textMatchStyle, or case-insensitive like the "exact" textMatchStyle (the default). Please see theTextMatchStyle documentation
for a discussion of the nuances of case-sensitive matching.- Parameters:
ignoreTextMatchStyleCaseSensitive
- New ignoreTextMatchStyleCaseSensitive value. Default value is false- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getIgnoreTextMatchStyleCaseSensitive
For fields on this dataSource that specifyignoreTextMatchStyle
true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. This property dictates whether that match is case-sensitive like the "exactCase" textMatchStyle, or case-insensitive like the "exact" textMatchStyle (the default). Please see theTextMatchStyle documentation
for a discussion of the nuances of case-sensitive matching.- Returns:
- Current ignoreTextMatchStyleCaseSensitive value. Default value is false
-
setImplicitCriteria
Criteria that are implicitly applied to all fetches made through this DataSource. These criteria are never shown to or edited by the user and are cumulative with any other criteria provided on the DSRequest.For example, a DataSource might *always* implicitly limit its fetch results to records owned by the current user's department. Components and ResultSets requesting data from the DataSource can then apply further implicitCriteria of their own, separately from their regular, user-editable criteria.
For instance, a grid bound to this dataSource might be further limited to implicitly show only the subset of records created by the current user. See
DataBoundComponent.implicitCriteria
andResultSet.implicitCriteria
for more on these localized options.Note that, while
implicitCriteria
can be declared in a server DataSource file usingComponent XML
, it is an entirely client-side feature, added by client-side components. So it does not affect server-side requests, and will not be added to client-side requests that don't come from a Smart GWT UI (eg RestHandler).- Parameters:
implicitCriteria
- New implicitCriteria value. Default value is null- Returns:
DataSource
instance, for chaining setter calls
-
getImplicitCriteria
Criteria that are implicitly applied to all fetches made through this DataSource. These criteria are never shown to or edited by the user and are cumulative with any other criteria provided on the DSRequest.For example, a DataSource might *always* implicitly limit its fetch results to records owned by the current user's department. Components and ResultSets requesting data from the DataSource can then apply further implicitCriteria of their own, separately from their regular, user-editable criteria.
For instance, a grid bound to this dataSource might be further limited to implicitly show only the subset of records created by the current user. See
DataBoundComponent.implicitCriteria
andResultSet.implicitCriteria
for more on these localized options.Note that, while
implicitCriteria
can be declared in a server DataSource file usingComponent XML
, it is an entirely client-side feature, added by client-side components. So it does not affect server-side requests, and will not be added to client-side requests that don't come from a Smart GWT UI (eg RestHandler).- Returns:
- Current implicitCriteria value. Default value is null
-
setInfoField
Name of the field that has the second most pertinent piece of textual information in the record, for use when aDataBoundComponent
needs to show a short summary of a record.For example, for a DataSource of employees, a "job title" field would probably be the second most pertinent text field aside from the employee's "full name".
Unlike
titleField
, infoField is not automatically determined in the absence of an explicit setting.- Parameters:
infoField
- New infoField value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getInfoField
Name of the field that has the second most pertinent piece of textual information in the record, for use when aDataBoundComponent
needs to show a short summary of a record.For example, for a DataSource of employees, a "job title" field would probably be the second most pertinent text field aside from the employee's "full name".
Unlike
titleField
, infoField is not automatically determined in the absence of an explicit setting.- Returns:
- Current infoField value. Default value is null
- See Also:
-
setInheritsFrom
ID of another DataSource this DataSource inherits itsfields
from.Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields. Fields with the same name are merged in the same way that
databound component fields
are merged with DataSource fields.The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can set
useParentFieldOrder
to instead use the parent's field order, with new local fields appearing last. You can setshowLocalFieldsOnly
to have all non-local fields hidden.Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other via
inheritsFrom
.This feature can be used for:
- creating a customized view (eg,
only certain fields shown) which will be used by multiple
databound components
. - adding presentation-specific attributes to metadata that has been automatically derived from
XML Schema
or other metadata formats - modeling object subclassing and extension in server-side code and storage systems
- modeling relational database joins, and the equivalents in other systems
- creating hooks for others to customize your application in a maintainable way. For
example, if you have a dataSource "employee", you can create a dataSource "customizedEmployee" which inherits from
"employee" but does not initially define any fields, and bind all
databound components
to "customizedEmployee". Customizations of fields (including appearance changes, field order, new fields, hiding of fields, and custom validation rules) can be added to "customizedEmployee", so that they are kept separately from the original field data and have the best possible chance of working with future versions of the "employee" dataSource.
- Parameters:
inheritsFrom
- New inheritsFrom value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
- creating a customized view (eg,
only certain fields shown) which will be used by multiple
-
getInheritsFrom
ID of another DataSource this DataSource inherits itsfields
from.Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields. Fields with the same name are merged in the same way that
databound component fields
are merged with DataSource fields.The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can set
useParentFieldOrder
to instead use the parent's field order, with new local fields appearing last. You can setshowLocalFieldsOnly
to have all non-local fields hidden.Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other via
inheritsFrom
.This feature can be used for:
- creating a customized view (eg,
only certain fields shown) which will be used by multiple
databound components
. - adding presentation-specific attributes to metadata that has been automatically derived from
XML Schema
or other metadata formats - modeling object subclassing and extension in server-side code and storage systems
- modeling relational database joins, and the equivalents in other systems
- creating hooks for others to customize your application in a maintainable way. For
example, if you have a dataSource "employee", you can create a dataSource "customizedEmployee" which inherits from
"employee" but does not initially define any fields, and bind all
databound components
to "customizedEmployee". Customizations of fields (including appearance changes, field order, new fields, hiding of fields, and custom validation rules) can be added to "customizedEmployee", so that they are kept separately from the original field data and have the best possible chance of working with future versions of the "employee" dataSource.
- Returns:
- Current inheritsFrom value. Default value is null
- See Also:
- creating a customized view (eg,
only certain fields shown) which will be used by multiple
-
setIsSampleDS
Used by Reify to identify DataSources that are provided as samples. Reify will not automatically alter sample DataSource relations when removing DataSources from a project.- Parameters:
isSampleDS
- New isSampleDS value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getIsSampleDS
Used by Reify to identify DataSources that are provided as samples. Reify will not automatically alter sample DataSource relations when removing DataSources from a project.- Returns:
- Current isSampleDS value. Default value is null
-
setJsonPrefix
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.
Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.
Note: If the prefix / suffix served by your backend is not a constant, you can usedataFormat:"custom"
instead and explicitly parse the prefix out as part oftransformResponse()
.Note : This is an advanced setting
- Parameters:
jsonPrefix
- New jsonPrefix value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getJsonPrefix
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.
Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.
Note: If the prefix / suffix served by your backend is not a constant, you can usedataFormat:"custom"
instead and explicitly parse the prefix out as part oftransformResponse()
.- Returns:
- Current jsonPrefix value. Default value is null
- See Also:
-
setJsonSuffix
Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.
Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.
Note : This is an advanced setting
- Parameters:
jsonSuffix
- New jsonSuffix value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getJsonSuffix
Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.
Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.
- Returns:
- Current jsonSuffix value. Default value is null
- See Also:
-
setMockDataCriteria
WhenmockMode
is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.- Parameters:
mockDataCriteria
- New mockDataCriteria value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getMockDataCriteria
WhenmockMode
is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.- Returns:
- Current mockDataCriteria value. Default value is null
-
setMockDataRows
WhenmockMode
is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data. Set to null to retrieve all available rows.- Parameters:
mockDataRows
- New mockDataRows value. Default value is 75- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getMockDataRows
WhenmockMode
is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data. Set to null to retrieve all available rows.- Returns:
- Current mockDataRows value. Default value is 75
-
setMockMode
If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to aclientOnly
DataSource, never writing changes back to the server.mockMode
has no effect onMockDataSource
or aclientOnly
DataSource.For other DataSources, a one-time fetch will be performed to retrieve sample data, similar to a
cacheAllData
DataSource, except that changes will never be saved back to the server. Only a subset of data will be retrieved, based onmockDataRows
.mockDataCriteria
can optionally be set to retrieve specific data.Alternatively, mock data can be provided with
cacheData
.DataSources can be loaded in
mockMode
via passing settings toload()
, or if loaded with a screen or project, by passing settings toRPCManager.loadScreen()
or the server-side Project.load() API.- Parameters:
mockMode
- New mockMode value. Default value is null- Returns:
DataSource
instance, for chaining setter calls
-
getMockMode
If set, causes this DataSource to use a read-only "mock" or "test" dataset, if specified, or if no test data is available, then to load data normally but then operate similarly to aclientOnly
DataSource, never writing changes back to the server.mockMode
has no effect onMockDataSource
or aclientOnly
DataSource.For other DataSources, a one-time fetch will be performed to retrieve sample data, similar to a
cacheAllData
DataSource, except that changes will never be saved back to the server. Only a subset of data will be retrieved, based onmockDataRows
.mockDataCriteria
can optionally be set to retrieve specific data.Alternatively, mock data can be provided with
cacheData
.DataSources can be loaded in
mockMode
via passing settings toload()
, or if loaded with a screen or project, by passing settings toRPCManager.loadScreen()
or the server-side Project.load() API.- Returns:
- Current mockMode value. Default value is null
-
setOperationBindings
public DataSource setOperationBindings(OperationBinding... operationBindings) throws IllegalStateException Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.When using the Smart GWT Server, OperationBindings are specified in your DataSource descriptor (.ds.xml file) and control server-side behavior such as what Java object to route DSRequest to (
OperationBinding.serverObject
) or customizations to SQL, JQL and HQL queries (OperationBinding.customSQL
,OperationBinding.customJQL
andOperationBinding.customHQL
). See the @see Java Integration samples.For DataSources bound to WSDL-described web services using
serviceNamespace
, OperationBindings are used to bind each DataSourceoperationType
to anoperation
of a WSDL-describedweb service
, so that a DataSource can both fetch and save data to a web service.For example, this code accomplishes part of the binding to the SalesForce partner web services
DataSource dataSource = new DataSource(); dataSource.setServiceNamespace("urn:partner.soap.sforce.com"); OperationBinding fetch = new OperationBinding(); fetch.setOperationType(DSOperationType.FETCH); fetch.setWsOperation("query"); fetch.setRecordName("sObject"); OperationBinding add = new OperationBinding(); add.setOperationType(DSOperationType.ADD); add.setWsOperation("create"); add.setRecordName("SaveResult"); OperationBinding update = new OperationBinding(); update.setOperationType(DSOperationType.UPDATE); update.setWsOperation("update"); update.setRecordName("SaveResult"); OperationBinding remove = new OperationBinding(); remove.setOperationType(DSOperationType.REMOVE); remove.setWsOperation("delete"); remove.setRecordName("DeleteResult"); dataSource.setOperationBindings(fetch, add, update, remove);
NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.For DataSources that contact non-WSDL-described XML or JSON services, OperationBindings can be used to separately configure the URL, HTTP method, input and output processing for each operationType. This makes it possible to fetch JSON data from one URL for the "fetch" operationType and save to a web service for the "update" operationType, while appearing as a single integrated DataSource to a
DataBoundComponent
such as aneditable ListGrid
.If no operationBinding is defined for a given DataSource operation, all of the properties which are valid on the operationBinding are checked for on the DataSource itself.
This also means that for a read-only DataSource, that is, a DataSource only capable of fetch operations, operationBindings need not be specified, and instead all operationBinding properties can be set on the DataSource itself. In the RSS Feed sample, you can see an example of using OperationBinding properties directly on the DataSource in order to read an RSS feed.
- Parameters:
operationBindings
- New operationBindings value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getOperationBindings
Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.When using the Smart GWT Server, OperationBindings are specified in your DataSource descriptor (.ds.xml file) and control server-side behavior such as what Java object to route DSRequest to (
OperationBinding.serverObject
) or customizations to SQL, JQL and HQL queries (OperationBinding.customSQL
,OperationBinding.customJQL
andOperationBinding.customHQL
). See the @see Java Integration samples.For DataSources bound to WSDL-described web services using
serviceNamespace
, OperationBindings are used to bind each DataSourceoperationType
to anoperation
of a WSDL-describedweb service
, so that a DataSource can both fetch and save data to a web service.For example, this code accomplishes part of the binding to the SalesForce partner web services
DataSource dataSource = new DataSource(); dataSource.setServiceNamespace("urn:partner.soap.sforce.com"); OperationBinding fetch = new OperationBinding(); fetch.setOperationType(DSOperationType.FETCH); fetch.setWsOperation("query"); fetch.setRecordName("sObject"); OperationBinding add = new OperationBinding(); add.setOperationType(DSOperationType.ADD); add.setWsOperation("create"); add.setRecordName("SaveResult"); OperationBinding update = new OperationBinding(); update.setOperationType(DSOperationType.UPDATE); update.setWsOperation("update"); update.setRecordName("SaveResult"); OperationBinding remove = new OperationBinding(); remove.setOperationType(DSOperationType.REMOVE); remove.setWsOperation("delete"); remove.setRecordName("DeleteResult"); dataSource.setOperationBindings(fetch, add, update, remove);
NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.For DataSources that contact non-WSDL-described XML or JSON services, OperationBindings can be used to separately configure the URL, HTTP method, input and output processing for each operationType. This makes it possible to fetch JSON data from one URL for the "fetch" operationType and save to a web service for the "update" operationType, while appearing as a single integrated DataSource to a
DataBoundComponent
such as aneditable ListGrid
.If no operationBinding is defined for a given DataSource operation, all of the properties which are valid on the operationBinding are checked for on the DataSource itself.
This also means that for a read-only DataSource, that is, a DataSource only capable of fetch operations, operationBindings need not be specified, and instead all operationBinding properties can be set on the DataSource itself. In the RSS Feed sample, you can see an example of using OperationBinding properties directly on the DataSource in order to read an RSS feed.
- Returns:
- Current operationBindings value. Default value is null
- See Also:
-
setPatternEscapeChar
When using thepattern operators
search operator
, character that escapes thepatternSingleWildcard
orpatternMultiWildcard
if placed before it, so that it is treated as a literal character.- Parameters:
patternEscapeChar
- New patternEscapeChar value. Default value is "\"- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getPatternEscapeChar
When using thepattern operators
search operator
, character that escapes thepatternSingleWildcard
orpatternMultiWildcard
if placed before it, so that it is treated as a literal character.- Returns:
- Current patternEscapeChar value. Default value is "\"
-
setPatternMultiWildcard
When using thepattern operators
search operator
, character that matches a series of one or more characters.Pass multiple strings to provide multiple alternative wildcards.
- Parameters:
patternMultiWildcard
- New patternMultiWildcard value. Default value is "*"- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getPatternMultiWildcard
When using thepattern operators
search operator
, character that matches a series of one or more characters.Pass multiple strings to provide multiple alternative wildcards.
- Returns:
- Current patternMultiWildcard value. Default value is "*"
-
setPatternMultiWildcard
public DataSource setPatternMultiWildcard(String... patternMultiWildcard) throws IllegalStateException When using thepattern operators
search operator
, character that matches a series of one or more characters.Pass multiple strings to provide multiple alternative wildcards.
- Parameters:
patternMultiWildcard
- New patternMultiWildcard value. Default value is "*"- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getPatternMultiWildcardAsStringArray
When using thepattern operators
search operator
, character that matches a series of one or more characters.Pass multiple strings to provide multiple alternative wildcards.
- Returns:
- Current patternMultiWildcard value. Default value is "*"
-
setPatternSingleWildcard
public DataSource setPatternSingleWildcard(String patternSingleWildcard) throws IllegalStateException When using thepattern operators
search operator
, character that matches any single character.Pass multiple strings to provide multiple alternative wildcards.
- Parameters:
patternSingleWildcard
- New patternSingleWildcard value. Default value is ["?","%"]- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getPatternSingleWildcard
When using thepattern operators
search operator
, character that matches any single character.Pass multiple strings to provide multiple alternative wildcards.
- Returns:
- Current patternSingleWildcard value. Default value is ["?","%"]
-
setPatternSingleWildcard
public DataSource setPatternSingleWildcard(String... patternSingleWildcard) throws IllegalStateException When using thepattern operators
search operator
, character that matches any single character.Pass multiple strings to provide multiple alternative wildcards.
- Parameters:
patternSingleWildcard
- New patternSingleWildcard value. Default value is ["?","%"]- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getPatternSingleWildcardAsStringArray
When using thepattern operators
search operator
, character that matches any single character.Pass multiple strings to provide multiple alternative wildcards.
- Returns:
- Current patternSingleWildcard value. Default value is ["?","%"]
-
setPluralTitle
User-visible plural name for this DataSource.For example, for the supplyItem DataSource, "Supply Items".
Defaults to
dataSource.title
+ "s".- Parameters:
pluralTitle
- New pluralTitle value. Default value is dataSource.ID- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getPluralTitle
User-visible plural name for this DataSource.For example, for the supplyItem DataSource, "Supply Items".
Defaults to
dataSource.title
+ "s".- Returns:
- Current pluralTitle value. Default value is dataSource.ID
-
setPreventHTTPCaching
If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.Note that this does not disable caching at higher levels in the framework, for example, the caching performed by
ResultSet
.- Parameters:
preventHTTPCaching
- New preventHTTPCaching value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getPreventHTTPCaching
If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.Note that this does not disable caching at higher levels in the framework, for example, the caching performed by
ResultSet
.- Returns:
- Current preventHTTPCaching value. Default value is true
-
setProgressiveLoading
If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of theResultSet documentation
. Essentially, this means that we avoid issuing a row count query and instead advertise total rows as being slightly more than the number of rows we have already read (seeendGap
). This allows users to load more of a dataset by scrolling past the end of the currently-loaded rows, but it prevents them from scrolling directly to the end of the dataset.Generally, progressive loading is appropriate when you have to deal with very large datasets. Note that by default, a dataSource will switch into progressive loading mode automatically when it detects that it is dealing with a dataset beyond a certain size - see
progressiveLoadingThreshold
.This setting can be overridden for individual fetch operations with the
OperationBinding.progressiveLoading
property, and also at the level of the individualDSRequest
. You can also specifyprogressiveLoading
onDataBoundComponents
and certain types ofFormItem
-SelectItem
andComboBoxItem
.Currently, this property only applies to users of the built-in SQLDataSource, but you could use it in custom DataSource implementations to trigger the server behavior described in the
ResultSet
documentation linked to above.- Parameters:
progressiveLoading
- New progressiveLoading value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getProgressiveLoading
If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of theResultSet documentation
. Essentially, this means that we avoid issuing a row count query and instead advertise total rows as being slightly more than the number of rows we have already read (seeendGap
). This allows users to load more of a dataset by scrolling past the end of the currently-loaded rows, but it prevents them from scrolling directly to the end of the dataset.Generally, progressive loading is appropriate when you have to deal with very large datasets. Note that by default, a dataSource will switch into progressive loading mode automatically when it detects that it is dealing with a dataset beyond a certain size - see
progressiveLoadingThreshold
.This setting can be overridden for individual fetch operations with the
OperationBinding.progressiveLoading
property, and also at the level of the individualDSRequest
. You can also specifyprogressiveLoading
onDataBoundComponents
and certain types ofFormItem
-SelectItem
andComboBoxItem
.Currently, this property only applies to users of the built-in SQLDataSource, but you could use it in custom DataSource implementations to trigger the server behavior described in the
ResultSet
documentation linked to above.- Returns:
- Current progressiveLoading value. Default value is null
- See Also:
-
setQualifyColumnNames
For dataSources ofserverType
"sql", determines whether we qualify column names with table names in any SQL we generate. This property can be overridden on specific operationBindings.- Parameters:
qualifyColumnNames
- New qualifyColumnNames value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getQualifyColumnNames
For dataSources ofserverType
"sql", determines whether we qualify column names with table names in any SQL we generate. This property can be overridden on specific operationBindings.- Returns:
- Current qualifyColumnNames value. Default value is true
- See Also:
-
setRecordName
Provides a default value forOperationBinding.recordName
.- Parameters:
recordName
- New recordName value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getRecordName
Provides a default value forOperationBinding.recordName
.- Returns:
- Current recordName value. Default value is null
- See Also:
-
setRecordXPath
SeeOperationBinding.recordXPath
.recordXPath
can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations, on clientOnly DataSources using String, or onRestConnector
dataSources- Parameters:
recordXPath
- New recordXPath value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getRecordXPath
SeeOperationBinding.recordXPath
.recordXPath
can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations, on clientOnly DataSources using String, or onRestConnector
dataSources- Returns:
- Current recordXPath value. Default value is null
- See Also:
-
setRequestProperties
Additional properties to pass through to theDSRequest
s made by this DataSource. This must be set before anyDSRequest
s are issued and before any component is bound to the DataSource.These properties are applied before
transformRequest()
is called.- Parameters:
requestProperties
- New requestProperties value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getRequestProperties
Additional properties to pass through to theDSRequest
s made by this DataSource. This must be set before anyDSRequest
s are issued and before any component is bound to the DataSource.These properties are applied before
transformRequest()
is called.- Returns:
- Current requestProperties value. Default value is null
- See Also:
-
setRequiredMessage
The required message when a field that has been marked asrequired
is not filled in by the user.Note that
DataSourceField.requiredMessage
wins over this setting if both are set.- Parameters:
requiredMessage
- New requiredMessage value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getRequiredMessage
The required message when a field that has been marked asrequired
is not filled in by the user.Note that
DataSourceField.requiredMessage
wins over this setting if both are set.- Returns:
- Current requiredMessage value. Default value is null
- See Also:
-
setResultBatchSize
Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.If you have a relatively small number of records with a great deal of properties or subobjects on each record, and you have not set
dropExtraFields
to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this number lower.Note : This is an advanced setting
- Parameters:
resultBatchSize
- New resultBatchSize value. Default value is 150- Returns:
DataSource
instance, for chaining setter calls
-
getResultBatchSize
public int getResultBatchSize()Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.If you have a relatively small number of records with a great deal of properties or subobjects on each record, and you have not set
dropExtraFields
to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this number lower.- Returns:
- Current resultBatchSize value. Default value is 150
-
setResultSetClass
Class for ResultSets used by this datasource. If null, defaults to usingResultSet
.This can be set to a custom subclass of ResultSet that, for example, hangs onto to extra information necessary for integration with web services.
Note : This is an advanced setting
- Parameters:
resultSetClass
- New resultSetClass value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getResultSetClass
Class for ResultSets used by this datasource. If null, defaults to usingResultSet
.This can be set to a custom subclass of ResultSet that, for example, hangs onto to extra information necessary for integration with web services.
- Returns:
- Current resultSetClass value. Default value is null
-
setResultTreeClass
Class for ResultTrees used by this datasource. If null, defaults to usingResultTree
.This can be set to a custom subclass of ResultTree that, for example, hangs on to extra information necessary for integration with web services.
Note : This is an advanced setting
- Parameters:
resultTreeClass
- New resultTreeClass value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getResultTreeClass
Class for ResultTrees used by this datasource. If null, defaults to usingResultTree
.This can be set to a custom subclass of ResultTree that, for example, hangs on to extra information necessary for integration with web services.
- Returns:
- Current resultTreeClass value. Default value is null
-
getSchemaNamespace
For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to. This is a read-only attribute automatically present on DataSources returned from SchemaSet.getSchema() andWebService.getSchema()
.Note : This method should be called only after the underlying component has been created.
- Returns:
- Current schemaNamespace value. Default value is null
- Throws:
IllegalStateException
- if the underlying component has not yet been created.- See Also:
-
setSendExtraFields
Analogous todropExtraFields
, for data sent to the server. Setting this attribute to false ensures that for any records in the data object, only fields that correspond to declared dataSource fields will be present on the dsRequest data object passed totransformRequest()
and ultimately sent to the server.- Parameters:
sendExtraFields
- New sendExtraFields value. Default value is true- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getSendExtraFields
Analogous todropExtraFields
, for data sent to the server. Setting this attribute to false ensures that for any records in the data object, only fields that correspond to declared dataSource fields will be present on the dsRequest data object passed totransformRequest()
and ultimately sent to the server.- Returns:
- Current sendExtraFields value. Default value is true
- See Also:
-
setSendParentNode
Set this attribute if you need to send the dsRequest.parentNode to the server-side.Note : This is an advanced setting
- Parameters:
sendParentNode
- New sendParentNode value. Default value is false- Returns:
DataSource
instance, for chaining setter calls
-
getSendParentNode
Set this attribute if you need to send the dsRequest.parentNode to the server-side.- Returns:
- Current sendParentNode value. Default value is false
-
setServiceNamespace
For an XML DataSource, URN of the WebService to use to invoke operations. This URN comes from the "targetNamespace" attribute of the <wsdl:definitions> element in a WSDL (Web Service Description Language) document, and serves as the unique identifier of the service.Having loaded a WebService using
XMLTools.loadWSDL()
, settingserviceNamespace
combined with specifyingoperationBindings
that setOperationBinding.wsOperation
will cause a DataSource to invoke web service operations to fulfill DataSource requests (DSRequests
).Setting
serviceNamespace
also defaultsdataURL
to the service's location,dataFormat
to "xml" anddataProtocol
to "soap".- Parameters:
serviceNamespace
- New serviceNamespace value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getServiceNamespace
For an XML DataSource, URN of the WebService to use to invoke operations. This URN comes from the "targetNamespace" attribute of the <wsdl:definitions> element in a WSDL (Web Service Description Language) document, and serves as the unique identifier of the service.Having loaded a WebService using
XMLTools.loadWSDL()
, settingserviceNamespace
combined with specifyingoperationBindings
that setOperationBinding.wsOperation
will cause a DataSource to invoke web service operations to fulfill DataSource requests (DSRequests
).Setting
serviceNamespace
also defaultsdataURL
to the service's location,dataFormat
to "xml" anddataProtocol
to "soap".- Returns:
- Current serviceNamespace value. Default value is null
- See Also:
-
setShowLocalFieldsOnly
For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that only the fields listed in this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".- Parameters:
showLocalFieldsOnly
- New showLocalFieldsOnly value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getShowLocalFieldsOnly
For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that only the fields listed in this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".- Returns:
- Current showLocalFieldsOnly value. Default value is null
-
setShowPrompt
Whether RPCRequests sent by this DataSource should enableRPCRequest.showPrompt
in order to block user interactions until the request completes.DataSource requests default to blocking UI interaction because, very often, if the user continues to interact with an application that is waiting for a server response, some kind of invalid or ambiguous situation can arise.
Examples include pressing a "Save" button a second time before the first save completes, making further edits while edits are still being saved, or trying to initiate editing on a grid that hasn't loaded data.
Defaulting to blocking the UI prevents these bad interactions, or alternatively, avoids the developer having to write repetitive code to block invalid interactions on every screen.
If an operation should ever be non-blocking, methods that initiate DataSource requests (such as
fetchData()
) will generally have arequestProperties
argument allowingshowPrompt
to be set to false for a specific request.- Parameters:
showPrompt
- New showPrompt value. Default value is true- Returns:
DataSource
instance, for chaining setter calls
-
getShowPrompt
Whether RPCRequests sent by this DataSource should enableRPCRequest.showPrompt
in order to block user interactions until the request completes.DataSource requests default to blocking UI interaction because, very often, if the user continues to interact with an application that is waiting for a server response, some kind of invalid or ambiguous situation can arise.
Examples include pressing a "Save" button a second time before the first save completes, making further edits while edits are still being saved, or trying to initiate editing on a grid that hasn't loaded data.
Defaulting to blocking the UI prevents these bad interactions, or alternatively, avoids the developer having to write repetitive code to block invalid interactions on every screen.
If an operation should ever be non-blocking, methods that initiate DataSource requests (such as
fetchData()
) will generally have arequestProperties
argument allowingshowPrompt
to be set to false for a specific request.- Returns:
- Current showPrompt value. Default value is true
-
setSkipJSONValidation
Sets what level of JSON validation will apply for this DataSource.Note that the point of "partial" validation mode is that if the JSON ihat's delivered is correct, we'll still need to validate to get "date" and such in the correct time, but shouldn't need to for the rest.
- Parameters:
skipJSONValidation
- New skipJSONValidation value. Default value is "none"- Returns:
DataSource
instance, for chaining setter calls
-
getSkipJSONValidation
Sets what level of JSON validation will apply for this DataSource.Note that the point of "partial" validation mode is that if the JSON ihat's delivered is correct, we'll still need to validate to get "date" and such in the correct time, but shouldn't need to for the rest.
- Returns:
- Current skipJSONValidation value. Default value is "none"
-
setStrictSQLFiltering
If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:field == "someValue" (normally false) field != "someValue" (normally true) not (field == "someValue") (normally true) not (field != "someValue") (normally false)
This property can be overridden per-query by specifyingstrictSQLFiltering
directly as a property on theAdvancedCriteria
.NOTE: On the server side, this property is only applicable if you are using the SQL DataSource; the other built-in types (Hibernate and JPA/JPA2) do not offer this mode.
Note : This is an advanced setting
- Parameters:
strictSQLFiltering
- New strictSQLFiltering value. Default value is false- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getStrictSQLFiltering
If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:field == "someValue" (normally false) field != "someValue" (normally true) not (field == "someValue") (normally true) not (field != "someValue") (normally false)
This property can be overridden per-query by specifyingstrictSQLFiltering
directly as a property on theAdvancedCriteria
.NOTE: On the server side, this property is only applicable if you are using the SQL DataSource; the other built-in types (Hibernate and JPA/JPA2) do not offer this mode.
- Returns:
- Current strictSQLFiltering value. Default value is false
-
setTagName
Tag name to use when serializing to XML. If unspecified, thedataSource.ID
will be used.Note : This is an advanced setting
- Parameters:
tagName
- New tagName value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getTagName
Tag name to use when serializing to XML. If unspecified, thedataSource.ID
will be used.- Returns:
- Current tagName value. Default value is null
- See Also:
-
setTitle
User-visible name for this DataSource.For example, for the supplyItem DataSource, "Supply Item".
If is unset,
getAutoTitle()
method will be used withdataSource.ID
. value in order to derive a default value for the title.For example "employee" ID will be derived to "Employee", "team_member" ID will be derived to "Team Member".
- Parameters:
title
- New title value. Default value is dataSource.ID- Returns:
DataSource
instance, for chaining setter calls
-
getTitle
User-visible name for this DataSource.For example, for the supplyItem DataSource, "Supply Item".
If is unset,
getAutoTitle()
method will be used withdataSource.ID
. value in order to derive a default value for the title.For example "employee" ID will be derived to "Employee", "team_member" ID will be derived to "Team Member".
- Returns:
- Current title value. Default value is dataSource.ID
-
setTitleField
Best field to use for a user-visible title for an individual record from this dataSource.For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.
If not explicitly set, the titleField is determined by looking for fields named "name", "dataSourceIdName", "title", "dataSourceIdTitle", "label", "dataSourceIdLabel", "id" and "dataSourceIdId". For example, for a DataSource with ID "customer", a field called customerName would be found if there were no "name" field. Search is case insensitive, and an underscore is allowed after dataSourceId (so that, for example, "CUSTOMER_NAME" would also be found and preferred).
For purposes of this search, any trailing numerals in the DataSource ID are discarded, so a DataSource with ID "office2" will search for title fields as if the ID were just "office".
If no field is found that matches any of the names above, then the first field is designated as the titleField.
- Parameters:
titleField
- New titleField value. Default value is see below- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getTitleField
Best field to use for a user-visible title for an individual record from this dataSource.For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.
If not explicitly set, the titleField is determined by looking for fields named "name", "dataSourceIdName", "title", "dataSourceIdTitle", "label", "dataSourceIdLabel", "id" and "dataSourceIdId". For example, for a DataSource with ID "customer", a field called customerName would be found if there were no "name" field. Search is case insensitive, and an underscore is allowed after dataSourceId (so that, for example, "CUSTOMER_NAME" would also be found and preferred).
For purposes of this search, any trailing numerals in the DataSource ID are discarded, so a DataSource with ID "office2" will search for title fields as if the ID were just "office".
If no field is found that matches any of the names above, then the first field is designated as the titleField.
- Returns:
- Current titleField value. Default value is see below
- See Also:
-
setTranslatePatternOperators
public DataSource setTranslatePatternOperators(boolean translatePatternOperators) throws IllegalStateException Search operators
like "matchesPattern" use patterns like "foo*txt" to match text values. The patterns are similar to the patterns you use to match names of files in a command-line interface, or to the pattern allowed for the SQL "LIKE" operator.translatePatternOperators
controls whether these pattern operators should be translated to a nested series of "startsWith"/"endsWidth"/"contains" operators before being sent to the server. This allows a server that only implements simple operators like "startsWith" to support pattern operators such as "matchesPattern" and "containsPattern", but with caveats:- single-character wildcards are not supported
- multiple wildcards are not truly order-dependent, for example *1*2*3* will match 1,2,3 as interior characters in any order.
- may be less efficient than a direct server-side implementation that is able to translate the pattern directly to the underlying storage engine.
Note that since "containsPattern" is essentially equivalent to "matchesPattern" but with "*" wildcards at the beginning and end of every pattern, the second limitation (pattern not really order dependent) may be fairly obvious to users when using this feature. For example, "m*t" will match "we meet" and "we teem".
The following are examples of how patterns are translated to simpler operators. Note that the case sensitive version of the operator is referred to below, but of course "iMatchesPattern" and "iContainsPattern" will be translated to case-insensitive versions of these operators, such as "iStartsWith".
*foo (endsWith)
foo* (startsWith)
*foo* (contains)
*foo*bar (contains and endsWith)
foo*bar* (startsWith and contains)
foo*bar (startsWith and endsWith)
*foo*bar* (multiple contains)Also supported: one startsWith, multiple contains, one endsWith.
- Parameters:
translatePatternOperators
- New translatePatternOperators value. Default value is false- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getTranslatePatternOperators
public boolean getTranslatePatternOperators()Search operators
like "matchesPattern" use patterns like "foo*txt" to match text values. The patterns are similar to the patterns you use to match names of files in a command-line interface, or to the pattern allowed for the SQL "LIKE" operator.translatePatternOperators
controls whether these pattern operators should be translated to a nested series of "startsWith"/"endsWidth"/"contains" operators before being sent to the server. This allows a server that only implements simple operators like "startsWith" to support pattern operators such as "matchesPattern" and "containsPattern", but with caveats:- single-character wildcards are not supported
- multiple wildcards are not truly order-dependent, for example *1*2*3* will match 1,2,3 as interior characters in any order.
- may be less efficient than a direct server-side implementation that is able to translate the pattern directly to the underlying storage engine.
Note that since "containsPattern" is essentially equivalent to "matchesPattern" but with "*" wildcards at the beginning and end of every pattern, the second limitation (pattern not really order dependent) may be fairly obvious to users when using this feature. For example, "m*t" will match "we meet" and "we teem".
The following are examples of how patterns are translated to simpler operators. Note that the case sensitive version of the operator is referred to below, but of course "iMatchesPattern" and "iContainsPattern" will be translated to case-insensitive versions of these operators, such as "iStartsWith".
*foo (endsWith)
foo* (startsWith)
*foo* (contains)
*foo*bar (contains and endsWith)
foo*bar* (startsWith and contains)
foo*bar (startsWith and endsWith)
*foo*bar* (multiple contains)Also supported: one startsWith, multiple contains, one endsWith.
- Returns:
- Current translatePatternOperators value. Default value is false
-
setTrimMilliseconds
For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa. By default, millisecond information is preserved (ie, it is not trimmed). You only need to consider trimming millisecond values if their presence causes a problem - for example, a custom server that is not expecting that extra information and so fails parsing.Note that there is no inherent support for millisecond precision in Smart GWT widgets; if you need millisecond-precise visibility and editability of values in your client, you must write custom formatters and editors (or sponsor the addition of such things to the framework). Server-side, millisecond-precise values are delivered to and obtained from DataSources, so DataSource implementations that are capable of persisting and reading millisecond values should work transparently. Of the built-in DataSource types, the JPA and Hibernate DataSources will transparently handle millisecond-precise values as long as the underlying database supports millisecond precision, and the underlying column is of an appropriate type. The SQLDataSource provides accuracy to the nearest second by default; you can switch on millisecond precision per-field with the
storeMilliseconds
attribute.- Parameters:
trimMilliseconds
- New trimMilliseconds value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getTrimMilliseconds
For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa. By default, millisecond information is preserved (ie, it is not trimmed). You only need to consider trimming millisecond values if their presence causes a problem - for example, a custom server that is not expecting that extra information and so fails parsing.Note that there is no inherent support for millisecond precision in Smart GWT widgets; if you need millisecond-precise visibility and editability of values in your client, you must write custom formatters and editors (or sponsor the addition of such things to the framework). Server-side, millisecond-precise values are delivered to and obtained from DataSources, so DataSource implementations that are capable of persisting and reading millisecond values should work transparently. Of the built-in DataSource types, the JPA and Hibernate DataSources will transparently handle millisecond-precise values as long as the underlying database supports millisecond precision, and the underlying column is of an appropriate type. The SQLDataSource provides accuracy to the nearest second by default; you can switch on millisecond precision per-field with the
storeMilliseconds
attribute.- Returns:
- Current trimMilliseconds value. Default value is null
-
setUseFlatFields
LikeDataBoundComponent.useFlatFields
, but applies to all DataBound components that bind to this DataSource.- Parameters:
useFlatFields
- New useFlatFields value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getUseFlatFields
LikeDataBoundComponent.useFlatFields
, but applies to all DataBound components that bind to this DataSource.- Returns:
- Current useFlatFields value. Default value is null
-
setUseHttpProxy
LikeOperationBinding.useHttpProxy
, but serves as a default for this DataSource that may be overridden by individual operationBindings.- Parameters:
useHttpProxy
- New useHttpProxy value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getUseHttpProxy
LikeOperationBinding.useHttpProxy
, but serves as a default for this DataSource that may be overridden by individual operationBindings.- Returns:
- Current useHttpProxy value. Default value is null
- See Also:
-
setUseLocalValidators
Whether to attempt validation on the client at all for this DataSource. If unset (the default), client-side validation is enabled.Disabling client-side validation entirely is a good way to test server-side validation.
Note : This is an advanced setting
- Parameters:
useLocalValidators
- New useLocalValidators value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- See Also:
-
getUseLocalValidators
Whether to attempt validation on the client at all for this DataSource. If unset (the default), client-side validation is enabled.Disabling client-side validation entirely is a good way to test server-side validation.
- Returns:
- Current useLocalValidators value. Default value is null
- See Also:
-
setUseOfflineStorage
Whether we store server responses for this DataSource intobrowser-based offline storage
, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server). Note that by default we do NOT use offline storage for a dataSource.- Parameters:
useOfflineStorage
- New useOfflineStorage value. Default value is null- Returns:
DataSource
instance, for chaining setter calls
-
getUseOfflineStorage
Whether we store server responses for this DataSource intobrowser-based offline storage
, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server). Note that by default we do NOT use offline storage for a dataSource.- Returns:
- Current useOfflineStorage value. Default value is null
-
setUseParentFieldOrder
For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource. New fields, if any, are placed at the end.- Parameters:
useParentFieldOrder
- New useParentFieldOrder value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created- See Also:
-
getUseParentFieldOrder
For a DataSource that inheritsfields
from another DataSource (viainheritsFrom
), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource. New fields, if any, are placed at the end.- Returns:
- Current useParentFieldOrder value. Default value is null
- See Also:
-
setUseStrictJSON
Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.Only applies to dataSources which send requests to a server and have
dataFormat
set to "json" or "iscServer".Note: using strict JSON avoids a known issue in Internet Explorer 9 where datasource transactions can leak memory due to a browser behavior where the native
eval()
method fails to clean up references when the objects go out of scope. SeeallowIE9Leak
for more on this.- Parameters:
useStrictJSON
- New useStrictJSON value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getUseStrictJSON
Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.Only applies to dataSources which send requests to a server and have
dataFormat
set to "json" or "iscServer".Note: using strict JSON avoids a known issue in Internet Explorer 9 where datasource transactions can leak memory due to a browser behavior where the native
eval()
method fails to clean up references when the objects go out of scope. SeeallowIE9Leak
for more on this.- Returns:
- Current useStrictJSON value. Default value is null
-
setUseTestDataFetch
When set, causes aclient-only
orcacheAllData
DataSource to create a second DataSource to perform it's one-time fetch. By default, this attribute will be considered true when clientOnly is true, cacheAllData is false or unset and a dataURL or testFileName is specified on the DataSource.- Parameters:
useTestDataFetch
- New useTestDataFetch value. Default value is null- Returns:
DataSource
instance, for chaining setter calls
-
getUseTestDataFetch
When set, causes aclient-only
orcacheAllData
DataSource to create a second DataSource to perform it's one-time fetch. By default, this attribute will be considered true when clientOnly is true, cacheAllData is false or unset and a dataURL or testFileName is specified on the DataSource.- Returns:
- Current useTestDataFetch value. Default value is null
-
setValidateRelatedRecords
public DataSource setValidateRelatedRecords(Boolean validateRelatedRecords) throws IllegalStateException If true, indicates that the Smart GWT Server should automatically apply aValidatorType
of "hasRelatedRecord" to every field on this dataSource that has aforeignKey
defined.- Parameters:
validateRelatedRecords
- New validateRelatedRecords value. Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getValidateRelatedRecords
If true, indicates that the Smart GWT Server should automatically apply aValidatorType
of "hasRelatedRecord" to every field on this dataSource that has aforeignKey
defined.- Returns:
- Current validateRelatedRecords value. Default value is null
-
addData
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record. If a callback was provided, it will be invoked when the operation completes successfully.If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See theerror handling overview
for more information.NOTE: do not use repeated calls to
addData()
to provide the initial dataset for aclientOnly
DataSource, instead, provide initial data viacacheData
. UsingaddData()
for subsequent, incremental updates from sources like user editing is fine.Batch inserting
addData()
can be passed aList
of records to insert, rather than a single record. Actual support for this kind of multi-add is entirely dependent on the server-side DataSource implementation; only the built-inSQLDataSource
has support for multi-add out-of-the-box. If you are usingSQLDataSource
(ie, your dataSource'sserverType
is "sql"), the default behavior of the server when it receives an "add" request with a list of records is to invoke a single-record add on theDataSource
for each of the records in the provided list.However, you can also configure the server to generate a true "batch insert", and this will typically be significantly faster. Instead of generating multiple
INSERT
queries,SQLDataSource
will generate a singleINSERT
with multipleVALUES
, like so:INSERT INTO myDataSource (field1, field2, field3) VALUES(97, 'test string', 117) VALUES(1, 'Another test', 73) . . . VALUES(8056, 'Final record', 70707)
Note, the Oracle database product does not support this syntax, so we implement batch insert in a different way - using subselects - with that one database. This difference is transparent from the perspective of a Smart GWT developer, and is only mentioned for completeness.Batch inserting can be configured at the
DSRequest
,DataSource
andOperationBinding
levels, and it can also be globally configured inserver.properties
. See themultiInsertStrategy
documentation for details.Cache Synchronization and Audit
This optimized batch insert style of multi-record add only supportscache synchronization
in a limited way, because database products do not provide a reliable way to determine the generated keys of rows inserted in this way. We support cache synchronization of batch-inserted records only when- The DataSource does not specify any "sequence" fields, and
- The
requestValuesPlusSequences
cacheSyncStrategy
is in force
automatic audit
of batch-inserted records only when both of the above conditions are true, and thesql.multi.insert.allowAudit
flag is set totrue
in yourserver.properties
file.Additionally, be aware that any values missing from the original request data for whatever reason, will also be missing from both the cache-sync data and the audit records.
"Simple" multi-record add, where each record is added with a discrete INSERT, does fully support cache-sync by default, but you may wish to consider turning it off when adding large numbers of records because the extra cache sync fetches can add significantly to the overall operation time (note, this only applies to the default "refetch" cache-sync strategy, so it does not affect the limited cache sync applicable to optimized batch inserts, described above). In fact, the elapsed time of a large multi-record
addData()
operation using "simple" multi-insert is more than doubled with "refecth" cache sync switched on, with all major databases, and it is significantly more than double on some of them. You can switch off cache sync for an operation by setting thecanSyncCache
flag tofalse
on yourOperationBinding
; alternatively, you can switch tocacheSyncStrategy
"requestValuesPlusSequences" if that is an option for your use case (ie, you do not have database-generated field values, or can live without them). Note, auditing is not possible if cache sync is completely switched off.Additional notes
Please note a couple of provisos about batch inserting; since batch insert has a specialized and quite narrow set of use cases, we do not currently plan to remove any of these restrictions- It is not supported by all database products. The following databases have been tested and verified to work: MySQL/MariaDB, HSQLDB, Microsoft SQL Server, PostgreSQL Oracle and DB/2. Other databases may work, but we do not guaranteee it
- It is not properly supported with
SQL templating
. If you try to make use of $valuesClause in a custom querying scenario where batch inserting is in force, you will only get thevaluesClause
applicable to the first valueSet. The same restriction applies to $values references in things likecustom SQL expressions
- It does not fully support binary fields. We do support values being sent from the
client for fields of type "binary" as Base64-encoded strings, and we also support
server-side Java code adding
InputStream
objects to valueSets before the SQL subsystem sees them (for example, by using aDMI
). However, we do not support upload of real binary files in a multi-record "add" request, primarily because there is no clear way to discern which of the records the uploaded file(s) belong with
- Parameters:
newRecord
- new record- See Also:
-
addData
- See Also:
-
addData
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record. If a callback was provided, it will be invoked when the operation completes successfully.If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See theerror handling overview
for more information.NOTE: do not use repeated calls to
addData()
to provide the initial dataset for aclientOnly
DataSource, instead, provide initial data viacacheData
. UsingaddData()
for subsequent, incremental updates from sources like user editing is fine.Batch inserting
addData()
can be passed aList
of records to insert, rather than a single record. Actual support for this kind of multi-add is entirely dependent on the server-side DataSource implementation; only the built-inSQLDataSource
has support for multi-add out-of-the-box. If you are usingSQLDataSource
(ie, your dataSource'sserverType
is "sql"), the default behavior of the server when it receives an "add" request with a list of records is to invoke a single-record add on theDataSource
for each of the records in the provided list.However, you can also configure the server to generate a true "batch insert", and this will typically be significantly faster. Instead of generating multiple
INSERT
queries,SQLDataSource
will generate a singleINSERT
with multipleVALUES
, like so:INSERT INTO myDataSource (field1, field2, field3) VALUES(97, 'test string', 117) VALUES(1, 'Another test', 73) . . . VALUES(8056, 'Final record', 70707)
Note, the Oracle database product does not support this syntax, so we implement batch insert in a different way - using subselects - with that one database. This difference is transparent from the perspective of a Smart GWT developer, and is only mentioned for completeness.Batch inserting can be configured at the
DSRequest
,DataSource
andOperationBinding
levels, and it can also be globally configured inserver.properties
. See themultiInsertStrategy
documentation for details.Cache Synchronization and Audit
This optimized batch insert style of multi-record add only supportscache synchronization
in a limited way, because database products do not provide a reliable way to determine the generated keys of rows inserted in this way. We support cache synchronization of batch-inserted records only when- The DataSource does not specify any "sequence" fields, and
- The
requestValuesPlusSequences
cacheSyncStrategy
is in force
automatic audit
of batch-inserted records only when both of the above conditions are true, and thesql.multi.insert.allowAudit
flag is set totrue
in yourserver.properties
file.Additionally, be aware that any values missing from the original request data for whatever reason, will also be missing from both the cache-sync data and the audit records.
"Simple" multi-record add, where each record is added with a discrete INSERT, does fully support cache-sync by default, but you may wish to consider turning it off when adding large numbers of records because the extra cache sync fetches can add significantly to the overall operation time (note, this only applies to the default "refetch" cache-sync strategy, so it does not affect the limited cache sync applicable to optimized batch inserts, described above). In fact, the elapsed time of a large multi-record
addData()
operation using "simple" multi-insert is more than doubled with "refecth" cache sync switched on, with all major databases, and it is significantly more than double on some of them. You can switch off cache sync for an operation by setting thecanSyncCache
flag tofalse
on yourOperationBinding
; alternatively, you can switch tocacheSyncStrategy
"requestValuesPlusSequences" if that is an option for your use case (ie, you do not have database-generated field values, or can live without them). Note, auditing is not possible if cache sync is completely switched off.Additional notes
Please note a couple of provisos about batch inserting; since batch insert has a specialized and quite narrow set of use cases, we do not currently plan to remove any of these restrictions- It is not supported by all database products. The following databases have been tested and verified to work: MySQL/MariaDB, HSQLDB, Microsoft SQL Server, PostgreSQL Oracle and DB/2. Other databases may work, but we do not guaranteee it
- It is not properly supported with
SQL templating
. If you try to make use of $valuesClause in a custom querying scenario where batch inserting is in force, you will only get thevaluesClause
applicable to the first valueSet. The same restriction applies to $values references in things likecustom SQL expressions
- It does not fully support binary fields. We do support values being sent from the
client for fields of type "binary" as Base64-encoded strings, and we also support
server-side Java code adding
InputStream
objects to valueSets before the SQL subsystem sees them (for example, by using aDMI
). However, we do not support upload of real binary files in a multi-record "add" request, primarily because there is no clear way to discern which of the records the uploaded file(s) belong with
- Parameters:
newRecord
- new recordcallback
- Callback to invoke on completion.requestProperties
- additional properties to set on the DSRequest that will be issued- See Also:
-
cloneDSRequest
Creates a shallow copy of the givenDSRequest
. The request'sdata
, if any, is shallow copied in the cloned request.The
callback
property of the given request is not copied into the cloned request.- Parameters:
dsRequest
- the DSRequest to clone.- Returns:
- a clone of the given DSRequest object.
- See Also:
-
cloneDSResponse
Creates a shallow copy of the givenDSResponse
. All properties that would affect the processing of the response are copied into the resulting DSResponse so that the cloned response could substitute for the original response. The response'sdata
, if any, is shallow copied in the cloned response.- Parameters:
dsResponse
- the DSResponse to clone.- Returns:
- a clone of the given DSResponse object.
- See Also:
-
compareCriteria
Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.Comparisons between
AdvancedCriteria
are made via recursively callingOperator.compareCriteria()
for all criteria involved.For simple
Criteria
, by default (CriteriaPolicy
:"dropOnShortening"), returns:- -1 if the new criteria has fewer properties than the old criteria (indicating that it isn't more restrictive)
- -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
- -1 if the value for any given property in the old criteria is not an array, and the the value for the same property property in the new criteria is different
- -1 if both values for a given property are strings and the new criteria value doesn't contain the old criteria value
- 1 if none of the above are true and, for at least one of the properties, the respective criteria values are both strings, and the old criteria value is a substring of, and is shorter than, the new criteria value
- 0 otherwise (indicating the sets of criteria are equivalent)
For (
CriteriaPolicy
:"dropOnChange"), returns:- -1 if the two sets of criteria have a different number of properties
- -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
- -1 if the value for any given property in the old criteria is not an array, and the the value for the same property in the new criteria is different
- 0 otherwise (indicating the sets of criteria are equivalent)
ResultSet.compareCriteria()
to determine whether a change in criteria should cause the cache to be invalidated. You may want to override this method in order to mimic the filtering behavior that your server performs.- Parameters:
newCriteria
- new filter criteriaoldCriteria
- previous filter criteria- Returns:
- 0 if the filters are equivalent, 1 if newCriteria is guaranteed more restrictive, and -1 if newCriteria is not guaranteed more restrictive
- See Also:
-
compareCriteria
-
compareCriteria
public int compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties, String policy) Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.Comparisons between
AdvancedCriteria
are made via recursively callingOperator.compareCriteria()
for all criteria involved.For simple
Criteria
, by default (CriteriaPolicy
:"dropOnShortening"), returns:- -1 if the new criteria has fewer properties than the old criteria (indicating that it isn't more restrictive)
- -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
- -1 if the value for any given property in the old criteria is not an array, and the the value for the same property property in the new criteria is different
- -1 if both values for a given property are strings and the new criteria value doesn't contain the old criteria value
- 1 if none of the above are true and, for at least one of the properties, the respective criteria values are both strings, and the old criteria value is a substring of, and is shorter than, the new criteria value
- 0 otherwise (indicating the sets of criteria are equivalent)
For (
CriteriaPolicy
:"dropOnChange"), returns:- -1 if the two sets of criteria have a different number of properties
- -1 if the value for any property in the old criteria is an array and 1) the value for the same property in the new criteria isn't an array, or 2) is an array but of different length, or 3) the arrays do not contain the exact same set of objects (order can be different)
- -1 if the value for any given property in the old criteria is not an array, and the the value for the same property in the new criteria is different
- 0 otherwise (indicating the sets of criteria are equivalent)
ResultSet.compareCriteria()
to determine whether a change in criteria should cause the cache to be invalidated. You may want to override this method in order to mimic the filtering behavior that your server performs.- Parameters:
newCriteria
- new filter criteriaoldCriteria
- previous filter criteriarequestProperties
- dataSource request propertiespolicy
- overridesCriteriaPolicy
- Returns:
- 0 if the filters are equivalent, 1 if newCriteria is guaranteed more restrictive, and -1 if newCriteria is not guaranteed more restrictive
- See Also:
-
compareDates
Convenience method to compare two Date objects appropriately, depending on whether the passed-in fieldName refers to a field oftype
"datetime" or "date". In the former case, the dates are compared usingDateUtil.compareDates()
; in the latter case, or if the supplied fieldName is null or unknown to this DataSource, the dates are compared usingDateUtil.compareLogicalDates()
.- Parameters:
date1
- First date in comparisondate2
- Second date in comparisonfieldName
- The name of the field for which the comparison is being run. SeeFieldName
- Returns:
- 0 if equal, -1 if first date > second date, 1 if second date > first date
-
convertDataSourceCriteria
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object. This instance method differs from the class methodconvertCriteria()
in that it makes use of the dataSource as schema to help in the conversion. For example, this method is able to honorDataSourceField.ignoreTextMatchStyle
and use the dataSource'sdefaultTextMatchStyle
rather than assuming "substring"- Parameters:
criteria
- simple criteria- Returns:
- equivalent AdvancedCriteria object
-
convertDataSourceCriteria
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object. This instance method differs from the class methodconvertCriteria()
in that it makes use of the dataSource as schema to help in the conversion. For example, this method is able to honorDataSourceField.ignoreTextMatchStyle
and use the dataSource'sdefaultTextMatchStyle
rather than assuming "substring"- Parameters:
criteria
- simple criteriatextMatchStyle
- default style of matching text. Defaults to the dataSource's defaultTextMatchStyle- Returns:
- equivalent AdvancedCriteria object
-
convertRelativeDates
Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.- Parameters:
criteria
- criteria to convert- Returns:
- new copy of the criteria with all relative dates converted
-
convertRelativeDates
-
convertRelativeDates
-
convertRelativeDates
public Criteria convertRelativeDates(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek, Date baseDate) Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.- Parameters:
criteria
- criteria to converttimezoneOffset
- optional timezone offset. Defaults to the current timezonefirstDayOfWeek
- first day of the week (zero is Sunday). Defaults toDateChooser.firstDayOfWeek
baseDate
- base value for relative conversion - defaults to now- Returns:
- new copy of the criteria with all relative dates converted
-
copyRecords
Copies all DataSource field values of an (Array) of Records (including a TreeNode) to a new array of Records, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes. This method callscopyRecord()
for each item in the array.- Parameters:
records
- The array of Record objects to be copied.- Returns:
- A new copy of each record provided in the array argument, with component-specific metata data removed.
-
createAlias
Assigns an alias to this DataSource- Parameters:
alias
- The alias assigned to this DataSource.
-
addDataChangedHandler
Add a dataChanged handler.Notification method fired when a DataSource operation such as an
add
,remove
orupdate
modifies the underlying data for a DataSource.This method is used by
ResultSet
s to keep the user-visible data up to date as changes are made.- Specified by:
addDataChangedHandler
in interfaceHasDataChangedHandlers
- Parameters:
handler
- the dataChanged handler- Returns:
HandlerRegistration
used to remove this handler
-
downloadFile
Download a file stored in a field of type:"binary" in a DataSource record.This will trigger the browser's "Save As" dialog and allow the user to save the file associated with some record.
Note that if this method is called for a record with no associated file, the download URL may not be functional. By default when dataSources encounter a
binary type fields
, an additional field,<fieldName>_filename
, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to download a file.See the overview of
Binary Fields
for more details.- Parameters:
data
- Record to download. Only required to have a value for the primary key field.
-
downloadFile
-
downloadFile
Download a file stored in a field of type:"binary" in a DataSource record.This will trigger the browser's "Save As" dialog and allow the user to save the file associated with some record.
Note that if this method is called for a record with no associated file, the download URL may not be functional. By default when dataSources encounter a
binary type fields
, an additional field,<fieldName>_filename
, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to download a file.See the overview of
Binary Fields
for more details.- Parameters:
data
- Record to download. Only required to have a value for the primary key field.fieldName
- Optional name of the binary field containing the file. If not provided, the first binary field is used. SeeFieldName
requestProperties
- Additional properties to set on the DSRequest that will be issued.
-
evaluateCriterion
Evaluate the given criterion with respect to the passed record.Typically called by the
condition
function of a customOperator
to evaluatesub-criteria
.- Parameters:
record
- record to evaluatecriterion
- criterion to use- Returns:
- whether the record meets the supplied
Criterion
- See Also:
-
execute
Executes the given DSRequest on this DataSource.This method is typically used by a DataSource whose
dataProtocol
is set toDSProtocol.CLIENTCUSTOM
. Execution of a DSRequest can be delayed, either after a timeout or until some condition is met, by saving the DSRequest object passed to thetransformRequest()
override and calling execute() on the DSRequest at a later time.- Parameters:
dsRequest
- the DSRequest to execute.
-
exportData
public void exportData()Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results. SeeOperationBinding.exportResults
orDSRequest.exportResults
and for more information.- See Also:
-
exportData
- See Also:
-
exportData
- See Also:
-
exportData
Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results. SeeOperationBinding.exportResults
orDSRequest.exportResults
and for more information.- Parameters:
criteria
- search criteriarequestProperties
- additional properties to set on the DSRequest that will be issuedcallback
- callback to invoke on completion. Note that this parameter only applies whereDSRequest.exportToClient
is explicitly set to false, because file downloads do not provide ordinary Smart GWT callbacks- See Also:
-
fetchData
-
fetchData
-
fetchData
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.NOTE: do not attempt to override this method to create a custom DataSource. For a server-side custom DataSource, use the
serverConstructor
attribute, and the @see Custom DataSource samples. For a client-side custom DataSource, seedataProtocol:"custom"
.In contrast to
ListGrid.fetchData()
, which creates aResultSet
to manage the returned data, callingdataSource.fetchData()
provides the returned data in the callback as a RecordList or simple Array of Record objects. CallingdataSource.fetchData()
does not automatically update any visual components or caches: code in the callback passed tofetchData()
decides what to do with the returned data.For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:
DataSource.get("employees").fetchData(null, new DSCallback() { public void execute(DSResponse response, Object rawData, DSRequest request) { myGrid.setData(response.getData()); } });
Unlike callingmyGrid.fetchData()
, which creates aResultSet
, the data provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.Disconnected datasets may be used to populate various visual components. For example, while an individual FormItem can be configured to fetch
valueMap
options from a DataSource via theoptionDataSource
property, the following code shows storing a dataset to derive valueMaps from later:// Assume GlobalStore.allCountries is a public static variable of type RecordList DataSource.get("countries").fetchData(null, new DSCallback(){ public void execute(DSResponse response, Object rawData, DSRequest request) { GlobalStore.allCountries = response.getDataAsRecordList(); } }); ... later, while a DynamicForm is being created ... SelectItem select = new SelectItem("country", "Pick Country"); Map valueMap = GlobalStore.countries.getValueMap("countryId", "countryName"); myItem.setValueMap(new LinkedHashMap(valueMap));
You can also create a ResultSet from the data retrieved from
fetchData()
, like so:DataSource.get("countries").fetchData(null, new DSCallback() { public void execute(DSResponse response, Object rawData, DSRequest request) { ResultSet rs = new ResultSet(DataSource.get("countries")); rs.setAllRows(response.getData()); } });
This gives you a dataset that supports client-side filtering (via
setCriteria()
), can providefiltered valueMaps
, willautomatically reflect updates
to the DataSource made via other components, and can be re-used with multiple visual components.See also
getClientOnlyDataSource()
andcacheAllData
for similar capabilities for dealing with smaller datasets entirely within the browser, or working with modifiable caches representing subsets of the data available from a DataSource.See also the server-side com.isomorphic.js.JSTranslater class in the Java Server Reference for other, similar approaches involving dumping data into the page during initial page load. Note: care should be taken when using this approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets that may become very large.
Data-Driven Visual Component Creation
DataSource.fetchData()
can also be used to create Smart GWT components in a data-driven way. For example, if you had a DataSource "myGridFields" whose fields included the basic properties ofListGridField
(name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:DataSource.get("myFormFields").fetchData(null, new DSCallback(){ public void execute(DSResponse response, Object rawData, DSRequest request) { Record[] records = response.getData(); ListGridField[] fields = new ListGridField[records.length]; for (Record record in records) { ListGridField field = new ListGridField(); field.setName(record.getAttribute("name")); field.setTitle(record.getAttribute("title")); field.setType(ListGridFieldType.valueOf(record.getAttribute("type"))); } ListGrid grid = new ListGrid(); grid.setFields(fields); } });
This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also the server-side API com.isomorphic.datasource.DataSource.addDynamicDSGenerator() for dynamically creating DataSources supporting all server-side DataSource features, andinheritsFrom
for sharing field definitions across multiple DataSources.- Parameters:
criteria
- search criteriacallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issued- See Also:
-
fetchRecord
Fetch a single record from the DataSource byprimary key
. This simply callsfetchData()
after creatingCriteria
that contain the primary key field and value.If you call this method on a DataSource with a composite primary key - ie, one with multiple primaryKey fields - this method returns the first record where the first defined primary field matches the supplied pkValue; this may or may not be meaningful, depending on your use case. Generally, for DataSources with composite keys, it makes more sense to use
fetchData()
directly, rather than this convenience method.- Parameters:
pkValue
- value for the field markedprimaryKey
:true in this DataSource (or the first field so marked if there is more than one)
-
fetchRecord
- See Also:
-
fetchRecord
Fetch a single record from the DataSource byprimary key
. This simply callsfetchData()
after creatingCriteria
that contain the primary key field and value.If you call this method on a DataSource with a composite primary key - ie, one with multiple primaryKey fields - this method returns the first record where the first defined primary field matches the supplied pkValue; this may or may not be meaningful, depending on your use case. Generally, for DataSources with composite keys, it makes more sense to use
fetchData()
directly, rather than this convenience method.- Parameters:
pkValue
- value for the field markedprimaryKey
:true in this DataSource (or the first field so marked if there is more than one)callback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issued
-
fieldMatchesFilter
Compares a criteria value to a field value and returns whether they match, as follows:- any non-String filter value is directly compared (==) to the field value
- any String filter value is compared according to
DSRequest.textMatchStyle
in the passedrequestProperties
, regardless of the actual field type - if the filter value is an Array, the comparison is a logical OR. If textMatchStyle is "exact", it matches if fieldValue (or any of it's entries, if it's also an array) is contained in the filterValue Array. If textMatchStyle if substring, it matches if any of the entries in filterValue appear as a case-insensitive substring of any of the entries in fieldValue.
- Dates are compared as logical dates if either the field value or the filter value is a logical date. Only if none of them is a logical date they will be compared as standard Dates
- Parameters:
fieldValue
- field value to be comparedfilterValue
- filter value to be compared- Returns:
- true if the filter and field values match, false otherwise
-
fieldMatchesFilter
public boolean fieldMatchesFilter(Object fieldValue, Object filterValue, DSRequest requestProperties) Compares a criteria value to a field value and returns whether they match, as follows:- any non-String filter value is directly compared (==) to the field value
- any String filter value is compared according to
DSRequest.textMatchStyle
in the passedrequestProperties
, regardless of the actual field type - if the filter value is an Array, the comparison is a logical OR. If textMatchStyle is "exact", it matches if fieldValue (or any of it's entries, if it's also an array) is contained in the filterValue Array. If textMatchStyle if substring, it matches if any of the entries in filterValue appear as a case-insensitive substring of any of the entries in fieldValue.
- Dates are compared as logical dates if either the field value or the filter value is a logical date. Only if none of them is a logical date they will be compared as standard Dates
- Parameters:
fieldValue
- field value to be comparedfilterValue
- filter value to be comparedrequestProperties
- optional dataSource request properties- Returns:
- true if the filter and field values match, false otherwise
-
filterData
public void filterData()Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.This is identical to
fetchData()
except thatDSRequest.textMatchStyle
is set to "substring" to cause case insensitive substring matching (if the server respects this setting).- See Also:
-
filterData
- See Also:
-
filterData
- See Also:
-
filterData
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.This is identical to
fetchData()
except thatDSRequest.textMatchStyle
is set to "substring" to cause case insensitive substring matching (if the server respects this setting).- Parameters:
criteria
- search criteriacallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issued- See Also:
-
formatFieldValue
Formats the supplied value using theSimpleType
derived from the field definition.Note that if
DataSourceField.format
is defined for a date, time or numeric-based value, orDataSourceField.dateFormatter
orDataSourceField.timeFormatter
is defined for a date or time-based value, that format is given priority and used to format the value rather than theSimpleType
.- Parameters:
field
- name of the field to use to format valuevalue
- raw value to be formatted- Returns:
- formatted value or null
-
getAllPathsToRelation
Returns all known paths between this and the given targetDS.- Parameters:
targetDS
- The DataSource at the relationship's other end.- Returns:
- Array ofAll known paths between this and the given targetDS.
-
getAllPathsToRelation
Returns all known paths between this and the given targetDS.- Parameters:
targetDS
- The DataSource at the relationship's other end.- Returns:
- Array ofAll known paths between this and the given targetDS.
-
getClientOnlyDataSource
Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource thatinheritsFrom
the original DataSource.This clientOnly "copy" can be useful in situations where you want to allow a series of local changes without immediately committing to the server. See also
ListGrid.autoSaveEdits
for more fine-grained tracking of edits (eg, special styling for uncommitted changes).The new DataSource is returned via the "callback" argument. If
cacheAllData
is enabled andhasAllData()
returns true, the new DataSource is synchronously returned as the result of the method. In this case, if a callback was passed, it also is executed synchronously.- Parameters:
criteria
- The criteria for the clientOnly DScallback
- The callback to fire passing the clientOnly DS
-
getClientOnlyDataSource
public void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties) -
getClientOnlyDataSource
public void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties, DataSource dataSourceProperties) Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource thatinheritsFrom
the original DataSource.This clientOnly "copy" can be useful in situations where you want to allow a series of local changes without immediately committing to the server. See also
ListGrid.autoSaveEdits
for more fine-grained tracking of edits (eg, special styling for uncommitted changes).The new DataSource is returned via the "callback" argument. If
cacheAllData
is enabled andhasAllData()
returns true, the new DataSource is synchronously returned as the result of the method. In this case, if a callback was passed, it also is executed synchronously.- Parameters:
criteria
- The criteria for the clientOnly DScallback
- The callback to fire passing the clientOnly DSrequestProperties
- optional properties to pass through to the DSRequestdataSourceProperties
- optional properties to pass through to the clientOnly DS
-
getClientOnlyResponse
Return a "spoofed" response for aclientOnly
orcacheAllData
DataSource.The default implementation will use
cacheData
to provide an appropriate response, by usingclient-side filtering
for a "fetch" request, and by modifying thecacheData
for other requests.Override this method to provide simulations of other server-side behavior, such as modifying other records, or to implement synchronous client-side data providers (such as Google Gears). For asynchronous third-party data providers, such as GWT-RPC, HTML5 sockets, or bridges to plug-in based protocols (Java, Flash, Silverlight..), use
dataProtocol:"clientCustom"
instead.Overriding this method is also a means of detecting that a normal DataSource (not clientOnly) would be contacting the server.
- Parameters:
request
- DataSource request to respond toserverData
- for cacheAllData DataSources, the data from the local cache- Returns:
-
getDefaultPathToRelation
Returns the path having the shortest distance between this and the given targetDS, as determined bygetShortestPathToRelation()
.- Parameters:
targetDS
- The DataSource at the relationship's other end.- Returns:
- The path having the least number of 1:M relationships from this to the given targetDS.
-
getDefaultPathToRelation
Returns the path having the shortest distance between this and the given targetDS, as determined bygetShortestPathToRelation()
.- Parameters:
targetDS
- The DataSource at the relationship's other end.- Returns:
- The path having the least number of 1:M relationships from this to the given targetDS.
-
getDisplayValue
Given a fieldName and a dataValue, apply anyDataSourceField.valueMap
for the field and return the display value for the field- Parameters:
fieldName
- name of the field to retrieve a value for. SeeFieldName
value
- data value for the field- Returns:
- display value for the field
-
getFetchDataURL
Returns a URL to DataSource fetch operation. This API is intended to return media such as images or videos to the browser.Note that because the entirety of the request is encoded in the URL, there is an inherent limitation on the amount of data that you can send viat he criteria argument to the server. The actual length depends on your server configuration and other factors such as the size of cookies (if any) being sent to the server and other HTTP headers in use. Conservatively, assume that you have about 2 kilobytes to work with.
- Parameters:
criteria
- Criteria to be sent to server.- Returns:
- a URL that targets the specified fetch operation.
-
getFetchDataURL
Returns a URL to DataSource fetch operation. This API is intended to return media such as images or videos to the browser.Note that because the entirety of the request is encoded in the URL, there is an inherent limitation on the amount of data that you can send viat he criteria argument to the server. The actual length depends on your server configuration and other factors such as the size of cookies (if any) being sent to the server and other HTTP headers in use. Conservatively, assume that you have about 2 kilobytes to work with.
- Parameters:
criteria
- Criteria to be sent to server.requestProperties
- additional properties to set on the DSRequest that will be issued- Returns:
- a URL that targets the specified fetch operation.
-
getField
Return the field definition object. -
getFieldCriterion
Returns the depth-first match of a criterion matching the given fieldName.- Parameters:
criterion
- the criteria to searchfieldName
- the fieldName to find criteria for. SeeFieldName
- Returns:
- the depth-first matching criterion for the passed fieldName
-
getFieldDefaultOperator
Get the defaultOperatorId
for this field.By default, if
field.defaultOperator
is set, returns that value, otherwise returns the data-type default fromSimpleType.defaultOperator
.- Parameters:
field
- Field (or field name) to obtain the default operator for- Returns:
- available Operators
- See Also:
-
getFieldDefaultOperator
Get the defaultOperatorId
for this field.By default, if
field.defaultOperator
is set, returns that value, otherwise returns the data-type default fromSimpleType.defaultOperator
.- Parameters:
field
- Field (or field name) to obtain the default operator for- Returns:
- available Operators
- See Also:
-
getFieldForDataPath
Return the field definition object corresponding to the supplied dataPath- Parameters:
dataPath
- dataPath of the field to retrieve- Returns:
- field object, or null if no field corresponds to the supplied dataPath
-
getFieldNames
Retrieves the list of fields declared on this DataSource.- Parameters:
excludeHidden
- If true, returns only those fields that are not marked as hidden- Returns:
- names of all fields declared on this DataSource
-
getFile
Gets the contents of a file stored in this DataSource.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.callback
- Callback executed with the results. Thedata
parameter is either a String with the contents of the file, or null to indicate error (such as file not found). You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
getFileURL
Returns a direct URL to access a file stored in a field of type:"binary".This URL can be used as the "src" attribute of an Img widget or <img> tag (if the file is an image), or can be used in an ordinary HTML link (<a> tag) to download the file. However, for the latter use case, see also
downloadFile()
andviewFile()
.The URL returned is not to a static file on disk, rather, the returned URL essentially encodes a DSRequest as URL parameters, in a format understood by the IDACall servlet that comes with the Server Framework.
Hence, this URL will dynamically retrieve whatever file is currently stored in the binary field via executing a normal DSRequest server side. The request will run through normal security checks, so if your application requires authentication, the user must have a valid session and be authorized to access the binary field.
Note that if this method is called for a record with no associated file, the returned URL may not be functional. By default when dataSources encounter a
binary type fields
, an additional field,<fieldName>_filename
, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to retrieve a download URL.- Parameters:
data
- Record containing at least the primary key field.- Returns:
- a URL to directly access the stored file
-
getFileURL
-
getFileURL
Returns a direct URL to access a file stored in a field of type:"binary".This URL can be used as the "src" attribute of an Img widget or <img> tag (if the file is an image), or can be used in an ordinary HTML link (<a> tag) to download the file. However, for the latter use case, see also
downloadFile()
andviewFile()
.The URL returned is not to a static file on disk, rather, the returned URL essentially encodes a DSRequest as URL parameters, in a format understood by the IDACall servlet that comes with the Server Framework.
Hence, this URL will dynamically retrieve whatever file is currently stored in the binary field via executing a normal DSRequest server side. The request will run through normal security checks, so if your application requires authentication, the user must have a valid session and be authorized to access the binary field.
Note that if this method is called for a record with no associated file, the returned URL may not be functional. By default when dataSources encounter a
binary type fields
, an additional field,<fieldName>_filename
, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to retrieve a download URL.- Parameters:
data
- Record containing at least the primary key field.fieldName
- Optional name of the binary field containing the file. If not provided, the first binary field is used. SeeFieldName
requestProperties
- Additional properties to set on the DSRequest that will be issued.- Returns:
- a URL to directly access the stored file
-
getFileVersion
Gets the contents of a particular file version stored in this DataSource.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.version
- A version timestamp. This must exactly match the version timestamp recorded in the DataSource. You can obtain the list of versions for a given file with thelistFileVersions()
API.callback
- Callback executed with the results. Thedata
parameter is either a String with the contents of the file, or null to indicate error (such as file not found). You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
getLegalChildTags
public void getLegalChildTags()For a DataSource that describes a DOM structure, the list of legal child elements that can be contained by the element described by this DataSource.For a DataSource described by XML schema, this is the list of legal subelements of complexType (elements of simpleType become DataSourceFields with atomic type).
Note that currently, if an XML schema file contains ordering constraints, DataSources derived from XML Schema do not capture these constraints.
-
getPrimaryKeyField
Returns a pointer to the primaryKey field for this DataSource. If this dataSource has a composite primary key (ie, multiple primaryKey fields), returns just the first primaryKey field.- Returns:
- primary key field object
- See Also:
-
getPrimaryKeyFieldName
Returns the primary key fieldName for this DataSource. If this dataSource has a composite primary key (ie, multiple primaryKey fields), returns just the first primaryKey field name.- Returns:
- primary key field name
- See Also:
-
getPrimaryKeyFieldNames
Returns a list of the names of this DataSource'sprimaryKey
fields.- Returns:
- The list of the names of this datasource's primaryKey fields
- See Also:
-
getPrimaryKeyFields
Returns this DataSource'sprimaryKey
fields as a map of fieldName to field.- Returns:
- Javascript object containing all this datasource's primaryKey fields, as a map of field name to field
- See Also:
-
getShortestPathToRelation
Returns the path having the shortest distance between this and the given targetDS. In case of a tie, only the first as determined by depth-first search is returned.- Parameters:
targetDS
- The DataSource at the relationship's other end.- Returns:
- The path having the least number of 1:M relationships from this to the given targetDS.
-
getShortestPathToRelation
Returns the path having the shortest distance between this and the given targetDS. In case of a tie, only the first as determined by depth-first search is returned.- Parameters:
targetDS
- The DataSource at the relationship's other end.- Returns:
- The path having the least number of 1:M relationships from this to the given targetDS.
-
getTypeOperators
Get the list ofOperatorId
s available on this DataSource for the givenFieldType
.If
setTypeOperators()
has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for theFieldType
as specified bySimpleType.validOperators
, otherwise, the system-wide set of valid operators for the type as registered viaaddSearchOperator()
.- Returns:
- available Operators
- See Also:
-
getTypeOperators
Get the list ofOperatorId
s available on this DataSource for the givenFieldType
.If
setTypeOperators()
has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for theFieldType
as specified bySimpleType.validOperators
, otherwise, the system-wide set of valid operators for the type as registered viaaddSearchOperator()
.- Parameters:
typeName
- Defaults to "text" if not passed.- Returns:
- available Operators
- See Also:
-
getTypeOperators
Get the list ofOperatorId
s available on this DataSource for the givenFieldType
.If
setTypeOperators()
has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for theFieldType
as specified bySimpleType.validOperators
, otherwise, the system-wide set of valid operators for the type as registered viaaddSearchOperator()
.- Parameters:
typeName
- Defaults to "text" if not passed.- Returns:
- available Operators
- See Also:
-
setHandleErrorCallback
If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other thanSTATUS_SUCCESS
. You can use this hook to do DataSource-specific error handling. Unless you callErrorEvent.cancel()
,HandleErrorCallback.handleError()
will be called by Smart GWT right after this method completes.- Parameters:
callback
- HandleErrorCallback the callback to set.- See Also:
-
addHandleErrorHandler
Add a handleError handler.If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other than
STATUS_SUCCESS
. You can use this hook to do DataSource-specific error handling. Unless you callErrorEvent.cancel()
,HandleErrorCallback.handleError()
will be called by Smart GWT right after this method completes.- Specified by:
addHandleErrorHandler
in interfaceHasHandleErrorHandlers
- Parameters:
handler
- the handleError handler- Returns:
HandlerRegistration
used to remove this handler
-
hasAllData
WhencacheAllData
is true, has all the data been retrieved to the client?- Returns:
- All data has been fetched from the server and is available client-side
-
hasCustomTypeOperators
Returns true if the operator list for the passed type has been customized via a call tosetTypeOperators()
.- Parameters:
typeName
-- See Also:
-
hasCustomTypeOperators
Returns true if the operator list for the passed type has been customized via a call tosetTypeOperators()
.- Parameters:
typeName
-- See Also:
-
hasFile
Indicates whether a file exists in this DataSource.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType or fileFormat are not provided, will indicate whether any file with the provided fileName exists.callback
- Callback executed with the results. Thedata
parameter is a boolean indicating whether the file is present. You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
hasFileVersion
Indicates whether a particular file version exists in this DataSource.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType or fileFormat are not provided, will indicate whether any file with the provided fileName exists.version
- A version timestamp. This must exactly match the version timestamp recorded in the DataSource forhasFileVersion
to return true. Note, you can obtain the list of versions for a given file with thelistFileVersions()
API.callback
- Callback executed with the results. Thedata
parameter is a boolean indicating whether the file version is present. You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
invalidateCache
public void invalidateCache()Drop the current dataSource cache. This has two effects:- For DataSources
cacheAllData
orclientOnly
, discard the current client-side cache data. - If
notify
is passed, cause alldata objects
associated with this dataSource to drop their caches. This occurs regardless of the dataSource type - and can be thought of as equivalent to processing a response withDSResponse.invalidateCache
set.
- For DataSources
-
invalidateCache
public void invalidateCache(boolean notify) Drop the current dataSource cache. This has two effects:- For DataSources
cacheAllData
orclientOnly
, discard the current client-side cache data. - If
notify
is passed, cause alldata objects
associated with this dataSource to drop their caches. This occurs regardless of the dataSource type - and can be thought of as equivalent to processing a response withDSResponse.invalidateCache
set.
- Parameters:
notify
- Should data objects associated with this dataSource have their cache invalidated?
- For DataSources
-
isCalculated
Does the specified field have its value dynamically calculated viaDataSourceField.formula
or other similar attributes?This method will return true for fields with the following attributes:
DataSourceField.formula
DataSourceField.template
DataSourceField.customSelectExpression
calculated:true
.- Parameters:
field
- Field or fieldName- Returns:
- true if this is a field with dynamically calculated values
-
isCalculated
Does the specified field have its value dynamically calculated viaDataSourceField.formula
or other similar attributes?This method will return true for fields with the following attributes:
DataSourceField.formula
DataSourceField.template
DataSourceField.customSelectExpression
calculated:true
.- Parameters:
field
- Field or fieldName- Returns:
- true if this is a field with dynamically calculated values
-
listFiles
Get a list of files from the DataSource. Note, ifautomatic file versioning
is switched on for the dataSource, the resulting list contains only the most recent version of each file.- Parameters:
criteria
- Criteria to apply. References tofileName
,fileType
andfileFormat
fields will be translated to the native field names configured for this DataSource.callback
- Callback executed with the results. Thedata
parameter is either an array of records, or null to indicate an error. The records will have the
,fileName
,fileType
,fileFormat
, andfileLastModified
fields populated, but not thefileVersion
field. (You can usefileContents
getFile()
to get thefileContents
). You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
listFileVersions
Get the list of a given file's versions from the dataSource, sorted in version order (most recent version first). If the dataSource does not specify afileVersionField
, this API will return an error- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.callback
- Callback executed with the results. Thedata
parameter is either an array of records, or null to indicate an error. The records will have the
,fileName
,fileType
,fileFormat
andfileLastModified
fields populated, but not thefileVersion
field. (You can usefileContents
getFileVersion()
to get thefileContents
). You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
performCustomOperation
Invoke an operation declared withOperationBinding.operationType
"custom".This is a rarely used API. If the operation you are performing can be thought of as one of the standard "CRUD"
operation types
, declare it with a CRUD operationType. For example, if your operation updates a record, declare it with operationType "update" and invoke it viaupdateData()
- this will causecache sync
to work correctly.In particular:
- do not use this API just because you need to add additional server-side logic to a CRUD operation (DMI allows this)
- do not use this API to
implement variants of core CRUD operations (
DSRequest.operationId
is the correct way to do this) - do not use this API just because an operation affects more
than one record. Most kinds of multi-record operations should use
queuing
. However, a custom operation is appropriate for genuine "batch" updates, as opposed to just a number of ordinary updates by primaryKey - seeOperationBinding.allowMultiUpdate
- do not use this API just because you are calling a stored procedure in SQL - if the stored procedure performs some kind of CRUD operation on the records of this DataSource, use a standard CRUD operationType
Instead, the specific purpose of this API is to bypass all checks and side effects that normally occur for CRUD operations, for example, that a "fetch" requires valid Criteria or that an "update" or "remove" operation contains a valid primary key, or that an "add" operation returns the newly added record.
performCustomOperation
allows you to pass an arbitrary Record to the server, act on it with custom code, and return arbitray results or even no results.The "data" parameter becomes
dsRequest.data
. With the Smart GWT Server Framework, the data is accessible server-side via DSRequest.getValues() and inVelocity templates
(such as <customSQL>) as $values.Note that with SQLDataSource,
performCustomOperation
must be used if you plan to have a <customSQL> tag in your operationBinding that will execute SQL operations other than SELECT, UPDATE, INSERT, DELETE (such as creating a new table). By declaringOperationBinding.operationType
"custom" in your .ds.xml file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.- Parameters:
operationId
- the operation ID- See Also:
-
performCustomOperation
- See Also:
-
performCustomOperation
- See Also:
-
performCustomOperation
public void performCustomOperation(String operationId, Record data, DSCallback callback, DSRequest requestProperties) Invoke an operation declared withOperationBinding.operationType
"custom".This is a rarely used API. If the operation you are performing can be thought of as one of the standard "CRUD"
operation types
, declare it with a CRUD operationType. For example, if your operation updates a record, declare it with operationType "update" and invoke it viaupdateData()
- this will causecache sync
to work correctly.In particular:
- do not use this API just because you need to add additional server-side logic to a CRUD operation (DMI allows this)
- do not use this API to
implement variants of core CRUD operations (
DSRequest.operationId
is the correct way to do this) - do not use this API just because an operation affects more
than one record. Most kinds of multi-record operations should use
queuing
. However, a custom operation is appropriate for genuine "batch" updates, as opposed to just a number of ordinary updates by primaryKey - seeOperationBinding.allowMultiUpdate
- do not use this API just because you are calling a stored procedure in SQL - if the stored procedure performs some kind of CRUD operation on the records of this DataSource, use a standard CRUD operationType
Instead, the specific purpose of this API is to bypass all checks and side effects that normally occur for CRUD operations, for example, that a "fetch" requires valid Criteria or that an "update" or "remove" operation contains a valid primary key, or that an "add" operation returns the newly added record.
performCustomOperation
allows you to pass an arbitrary Record to the server, act on it with custom code, and return arbitray results or even no results.The "data" parameter becomes
dsRequest.data
. With the Smart GWT Server Framework, the data is accessible server-side via DSRequest.getValues() and inVelocity templates
(such as <customSQL>) as $values.Note that with SQLDataSource,
performCustomOperation
must be used if you plan to have a <customSQL> tag in your operationBinding that will execute SQL operations other than SELECT, UPDATE, INSERT, DELETE (such as creating a new table). By declaringOperationBinding.operationType
"custom" in your .ds.xml file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.- Parameters:
operationId
- the operation IDdata
- data to pass to the server.callback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issued- See Also:
-
processResponse
Process a dsResponse for a request initiated by a DataSource withdataProtocol:"clientCustom"
.requestId
parameter should be dsRequest.requestId as found on the dsRequest passed totransformRequest()
.You must provide a response for both error and non-error cases. For an error case, a sufficient response is:
{ status : -1 }
- Parameters:
requestId
- requestId attribute from the associated dataSource request objectdsResponse
- Configuration for the dsResponse
-
recordsAreEqual
Convenience method to test if two records are equal. Testing is done only for the fields defined in the DataSource, anything else is ignored.- Parameters:
record1
- record to be compared against.record2
- record to be compared.- Returns:
- true if the records are equal, false otherwise.
-
recordsAsText
Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).In addition to the
settings
parameter for this method,DataSourceField.exportForceText
can be set.If two or more different text exports are needed for the same DataSource creating a conflict for any DataSourceField setting,
inheritsFrom
can be used to create a child DataSource where these settings can be changed without recapitulating all field definitions.- Parameters:
records
- records to convert- Returns:
- records as CSV/TSV (separator can be specified)
-
recordsAsText
Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).In addition to the
settings
parameter for this method,DataSourceField.exportForceText
can be set.If two or more different text exports are needed for the same DataSource creating a conflict for any DataSourceField setting,
inheritsFrom
can be used to create a child DataSource where these settings can be changed without recapitulating all field definitions.- Parameters:
records
- records to convertsettings
- settings for the export- Returns:
- records as CSV/TSV (separator can be specified)
-
recordsFromText
Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.
- Parameters:
text
- records as CSV/TSV (separator can be specified)- Returns:
- records derived from TSV
-
recordsFromText
Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.
- Parameters:
text
- records as CSV/TSV (separator can be specified)settings
- optional settings for the import- Returns:
- records derived from TSV
-
removeData
Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See theerror handling overview
for more information.- Parameters:
data
- primary key values of record to delete, (or complete record)- See Also:
-
removeData
-
removeData
Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See theerror handling overview
for more information.- Parameters:
data
- primary key values of record to delete, (or complete record)callback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issued- See Also:
-
removeFile
Remove a file stored in this DataSource. Note, ifautomatic file versioning
is switched on for the dataSource, all versions of the file are removed (to remove an individual file version, use theremoveFileVersion()
API).- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending the configuration of the DataSource, the fileType and fileFormat may be optional.- See Also:
-
removeFile
Remove a file stored in this DataSource. Note, ifautomatic file versioning
is switched on for the dataSource, all versions of the file are removed (to remove an individual file version, use theremoveFileVersion()
API).- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending the configuration of the DataSource, the fileType and fileFormat may be optional.- See Also:
-
removeFile
Remove a file stored in this DataSource. Note, ifautomatic file versioning
is switched on for the dataSource, all versions of the file are removed (to remove an individual file version, use theremoveFileVersion()
API).- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending the configuration of the DataSource, the fileType and fileFormat may be optional.callback
- Callback executed with the results. Thedata
parameter is either an array of records represening the removed file(s), or null to indicate an error. The records will have theirfileName
fields andfileType
fields populated, but not thefileContents
field. You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
removeFileVersion
Remove a particular file version stored in this DataSource. Any other versions of the file are left untouched.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.version
- A version timestamp. This must exactly match the version timestamp recorded in the DataSource. You can obtain the list of versions for a given file with thelistFileVersions()
API.- See Also:
-
removeFileVersion
Remove a particular file version stored in this DataSource. Any other versions of the file are left untouched.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If fileType and fileFormat are not provided, will return the first file with the specified fileName.version
- A version timestamp. This must exactly match the version timestamp recorded in the DataSource. You can obtain the list of versions for a given file with thelistFileVersions()
API.callback
- Callback executed with the results. Thedata
parameter is either a record representing the removed file version, or null to indicate an error. The record will have its
,fileName
,fileType
,fileFormat
, andfileLastModified
fields populated, but not thefileVersion
field. You can examinefileContents
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
renameFile
Rename a file stored in this DataSource. Note, ifautomatic file versioning
is switched on for the dataSource, all versions of the file are renamed.- Parameters:
oldFileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat of the file to rename. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.newFileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat to rename the file to. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If the fileType or fileFormat are not provided, then they will not be changed.- See Also:
-
renameFile
Rename a file stored in this DataSource. Note, ifautomatic file versioning
is switched on for the dataSource, all versions of the file are renamed.- Parameters:
oldFileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat of the file to rename. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.newFileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat to rename the file to. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. If the fileType or fileFormat are not provided, then they will not be changed.callback
- Callback executed with the results. Thedata
parameter is either an array of records represening the renamed file(s), or null to indicate an error. The records will have theirfileName
fields andfileType
fields populated, but not thefileContents
field. You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
saveFile
Save a file to the DataSource.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.contents
- The contents of the file- See Also:
-
saveFile
Save a file to the DataSource.- Parameters:
fileSpec
- Either a FileSpec, or a String which will be parsed to determine the fileName, fileType and fileFormat. For instance, "employees.ds.xml" would be parsed as {fileName: "employees", fileType: "ds", fileFormat: "xml"}. Depending on the configuration of the DataSource, the fileType and fileFormat may be optional.contents
- The contents of the filecallback
- Callback executed with the results. Thedata
parameter is either a record represening the new file, or null to indicate an error. The record will have itsfileName
,fileType
andfileFormat
field populated, but not thefileContents
field. You can examine
anddsResponse.status
for additional information about any error.dsResponse.data
- See Also:
-
setTypeOperators
Set the list ofOperatorId
s valid for a given FieldType.- Parameters:
typeName
-operators
- available Operators- See Also:
-
splitCriteria
Split a criteria apart based onfields
.This method will take a simple or
Advanced
criteria object and extract the subcriteria that apply to the specified array of fields. If passed an AdvancedCriteria, the criteria should beflat
and the outer operator must be"and"
.A new criteria object is returned with any criteria applicable to the specified fields. The passed
criteria
is then modified to remove these fields resulting in two distinct criteria.To avoid modifying an original criteria, use
copyCriteria()
to make a copy to be passed in.By default the field-specific criteria returned will be in simple criteria format even if the criteria passed in was Advanced. Developers may suppress this conversion by passing in the
preserveAdvanced
parameter. Note that not everycriterion operator
can be converted to a simple format. This method will only to convert field level criterion with operators that correspond to one of the availabletextMatchStyle
options - namely"equals"
,"iEquals"
"iContains"
or"startsWith"
.This method will return an empty criteria object if it was unable to split the specified criteria by the specified fields.
- Parameters:
criteria
- criteria to be split. May be modified if criteria is extracted.fields
- list of fields to extract from criteria- Returns:
- extracted criteria
-
splitCriteria
Split a criteria apart based onfields
.This method will take a simple or
Advanced
criteria object and extract the subcriteria that apply to the specified array of fields. If passed an AdvancedCriteria, the criteria should beflat
and the outer operator must be"and"
.A new criteria object is returned with any criteria applicable to the specified fields. The passed
criteria
is then modified to remove these fields resulting in two distinct criteria.To avoid modifying an original criteria, use
copyCriteria()
to make a copy to be passed in.By default the field-specific criteria returned will be in simple criteria format even if the criteria passed in was Advanced. Developers may suppress this conversion by passing in the
preserveAdvanced
parameter. Note that not everycriterion operator
can be converted to a simple format. This method will only to convert field level criterion with operators that correspond to one of the availabletextMatchStyle
options - namely"equals"
,"iEquals"
"iContains"
or"startsWith"
.This method will return an empty criteria object if it was unable to split the specified criteria by the specified fields.
- Parameters:
criteria
- criteria to be split. May be modified if criteria is extracted.fields
- list of fields to extract from criteriapreserveAdvanced
- If passed an AdvancedCriteria, should the returned field-specific split criteria object also be an AdvancedCriteria.- Returns:
- extracted criteria
-
supportsAdvancedCriteria
Do fetch and filter operations on this dataSource support being passedAdvancedCriteria
?For a DataSource to support being passed AdvancedCriteria, it must be
clientOnly:true
orcacheAllData:true
, or have server side logic which can process AdvancedCriteria objects passed from the client.AdvancedCriteria are supported on the server for standard
SQL
,Hibernate
andJPA
DataSources in Smart GWT Enterprise or Power editions (not supported in Smart GWT Pro).The framework assumes that custom dataSources support AdvancedCriteria; if you have a a custom DataSource implementation that does not support AdvancedCriteria, you can set the
allowAdvancedCriteria
property to false.- Returns:
- true if this dataSource supports being passed AdvancedCriteria in fetch and filter type operations, false otherwise.
-
supportsDynamicTreeJoins
This method returns true for dataSources that support both self-joins andadditionalOutputs
. A "self-join" is a relation from a dataSource back to itself - for example a relation between a worker and his manager, both of whom are Employees. DataSources that can handle self-joins are able to create and navigate these relations, which are mostly useful for tree-type structures.Out of the box, only the built-in
SQL DataSource
implementation supports self-joins, and thus dynamic tree joins; neitherclientOnly
nor the other server-side built-in DataSource implementations support them. If you create a custom DataSource implementation that can handle both of these features, you can set theallowDynamicTreeJoins
flag to true, which will cause supportsDynamicTreeJoins() to return true (and equally, you can set that flag explicitly to false to prevent the system from using dynamic tree joins for a given dataSource, even if it is able to use them)This method is called by the automatic
ResultTree.keepParentsOnFilter
algorithm to decide if it is possible to use self-referencingadditionalOutputs
to improve efficiency, and possibly performance.- Returns:
- true if this dataSource supports both
additionalOutputs
and self-joins, otherwise false
-
supportsTextMatchStyle
Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.- Parameters:
textMatchStyle
- textMatchStyle to check. If passed a null value, assume an exact match is being requested.
-
transformRequest
For a dataSource usingclient-side data integration
, return the data that should be sent to thedataURL
.By default, HTTP requests sent to non-Smart GWT servers do not include DSRequest metadata such as
DSRequest.startRow
,endRow
, andoldValues
. Only the coredatasource protocol data
is sent, such as the criteria passed tofetchData()
or the updated values submitted byform.saveData()
.transformRequest() allows you to transform dsRequest metadata into a format understood by your server and include it in the HTTP request, so that you can integrate DataSource features such as data paging with servers that support such features.
How the data is actually sent to the URL is controlled by
OperationBinding.dataProtocol
. If using the "getParams" or "postParams" protocol, data is expected to be a JavaScript Object where each property will become a GET or POST'd parameter. If using dataProtocol:"soap" or "postXML", data will be serialized as an XML message byxmlSerialize()
.As an example, if you have a dataURL that can return paged data given URL parameters "start" and "end", you could implement transformRequest like so:
@Override protected Object transformRequest (DSRequest dsRequest) { JavaScriptObject data = dsRequest.getData(); if (dsRequest.getOperationType () == DSOperationType.FETCH) { JSOHelper.setAttribute (data, "start", dsRequest.getStartRow()); JSOHelper.setAttribute (data, "end", dsRequest.getEndRow()); } return data; }
Other reasons to implement transformRequest():- transform a
Criteria
object into the custom query language of a web service - add a session id to requests that require authentication
- detect colliding updates by sending both updated values and the values the user
originally retrieved before editing began (available as
DSRequest.oldValues
)
dataProtocol
is"clientCustom"
the Smart GWT system will not attempt to send data to the server in any way. Instead transformRequest should be implemented such that it accesses or updates the underlying data-set and callsprocessResponse()
when the operation is complete. This setting allows straightforward integration with non Smart GWT comm mechanisms that directly send requests to the server (such as GWT-RPC), or handle data manipulation without sending HTTP at all (such as Google Gears).
Developers should not generate a response for a request and callprocessResponse()
synchronously from withintransformRequest
as this can lead to unpredictable results. If you're integrating with a synchronous data provider or able to process requests synchronously from data in browser memory, we'd recommend using aclientOnly dataSource
with a customgetClientOnlyResponse()
implementation instead.A
transformRequest
override may also be used to set theDSRequest.dataProtocol
to clientCustom at runtime, giving developers a way to intercept normal handling for some particular request, and provide entirely custom handling written on the client.Note: The
RestDataSource
class overrides transformRequest() to handle xml-serializing the request (including meta data) into a standard format.- Parameters:
dsRequest
- the DSRequest being processed- Returns:
- data to be sent to the dataURL
- transform a
-
transformResponse
Modify the DSResponse object derived from the response returned from thedataURL
.This is an override point that makes it possible to use DataSource features such as paging with web services that support such features, by allowing you to fill in metadata fields in the DSResponse object (such as
DSResponse.startRow
) based on service-specific metadata fields contained in the service's response.The DSResponse passed to this method already has
DSResponse.data
, which is derived differently depending on thedataFormat
setting:-
dataFormat:"xml"
: either therecordXPath
orrecordName
is used to select the XML elements that represent DataSource records. The selected XML elements are passed torecordsFromXML()
, which transforms the XML elements to typed JavaScript data using the DataSource as a schema. -
dataFormat:"json"
: therecordXPath
, if specified, is used to select records from the returned JSON data viaXMLTools.selectObjects()
.DataSourceField.valueXPath
is used to derive correctly typed field values. -
dataFormat:"custom"
:dsResponse.data
is the raw response in String form. It must be parsed into an Array of Objects for subsequent processing to work.
In addition to
dsResponse.data
,DSResponse.status
is defaulted to 0 (indicating no error), andDSResponse.startRow
is assumed to be zero, withendRow
andtotalRows
both set todsResponse.data.length - 1
, that is, the returned data is assumed to be all records that matched the filter criteria.Examples of using this API include:
- setting
startRow
,endRow
andtotalRows
to allow paging for a service that supports it. For example, if an XML service returns a "resultRow" tag that contained the row number of the first row of the returned results:dsResponse.setStartRow(XMLTools.selectNumber(xmlData, "//resultRow"));
- setting
DSResponse.status
to recognized ISC error values based on service-specific errors, in order to trigger standard ISC error handling. For example, settingdsResponse.status
toSTATUS_VALIDATION_ERROR
and filling inDSResponse.errors
in order to cause validation errors to be shown in forms and grids. - for services that either do not return cache update data, or return partial data,
using
DSRequest.oldValues
to create cache update data (whether this is appropriate is application-specific), or settingDSResponse.invalidateCache
.
NOTE: this method is NOT an appropriate time to call methods on visual components such as grids, initiate new DSRequests or RPCRequests, or in general do anything other than fill in fields on the DSResponse based on data that is already available. Any actions that need to be taken as a result of the web service response should be implemented exactly as for a DataSource where
transformResponse()
has not been overridden, that is, use the callback passed to high-level methods such as
, and do error handling via eithergrid.fetchData()
DataSource.handleError()
or by settingwillHandleError
.- Parameters:
dsResponse
- default DSResponse derived from the response datadsRequest
- DSRequest object that initiated this requestdata
- XML document or JSON objects returned by the web service
-
-
updateCaches
Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed. This will cause cache managers such asResultSet
orResultTree
to automatically update their caches, and components using such cache managers to visually update to show modified data.This API should be used when you have found out about changes made by other users or by automatic processes. For example, using the Smart GWT Messaging system to receive real-time updates via HTTP streaming, you may get updates that should affect a ListGrid which is using a ResultSet to view a portion of a large dataset.
See the
ConcurrentEdits
overview for more on handling concurrent edits in Smart GWT DataSources.The provided
DSResponse
should haveoperationType
"update", "add" or "remove" - there is no way for a "fetch" response to meaningfully update arbitrary caches. However, if you have a list of updated records (possibly retrieved viafetchData()
) you can still callupdateCaches()
with DSResponses of type "update". Typically DataSource operations that manipulate data operate on a single record at a time, but if you explicitly set theresponse.data
attribute to an array of records, framework code will handle this as it would multiple updates.Example usage: if you had a ListGrid bound to the
supplyItem
sample DataSource, and that ListGrid was showing a Record withitemId
23, and you wanted to update theunitCost
field to a new value, you would use the following code:
// updatedRecord is the record we want to update
Record record = supplyItemDS.copyRecord(updatedRecord);
record.setAttribute("unitCost", 500);
DSResponse dsResponse = new DSResponse();
dsResponse.setData(record);
dsResponse.setOperationType(DSOperationType.UPDATE);
supplyItemDS.updateCaches(dsResponse);
To cause all components that have cache managers to drop their caches, provide a DSResponse with
DSResponse.invalidateCache
set.As an alternative to calling
updateCaches()
directly, if updates to other DataSources occur as a result of server-side logic, you can use the server-side API DSResponse.addRelatedUpdate(DSResponse) (Pro Edition and above), which ultimately callsupdateCaches()
for you - see that method's documentation for details.NOTE:: if
updateCaches
is called for aclientOnly
DataSource, it will updatecacheData
synchronously in addition to notifying all cache managers as normal.If a DataSource has
cacheAllData
set and a full cache has been obtained, callingupdateCaches
will automatically update the cache.Note that the DSResponse provided to this method will not go through
transformResponse()
or other processing that would normally occur for a DSResponse resulting from a DSRequest sent by the application in this page.- Parameters:
dsResponse
- the provided DSResponse must minimally have dataSource, operationType, and data set
-
updateCaches
Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed. This will cause cache managers such asResultSet
orResultTree
to automatically update their caches, and components using such cache managers to visually update to show modified data.This API should be used when you have found out about changes made by other users or by automatic processes. For example, using the Smart GWT Messaging system to receive real-time updates via HTTP streaming, you may get updates that should affect a ListGrid which is using a ResultSet to view a portion of a large dataset.
See the
ConcurrentEdits
overview for more on handling concurrent edits in Smart GWT DataSources.The provided
DSResponse
should haveoperationType
"update", "add" or "remove" - there is no way for a "fetch" response to meaningfully update arbitrary caches. However, if you have a list of updated records (possibly retrieved viafetchData()
) you can still callupdateCaches()
with DSResponses of type "update". Typically DataSource operations that manipulate data operate on a single record at a time, but if you explicitly set theresponse.data
attribute to an array of records, framework code will handle this as it would multiple updates.Example usage: if you had a ListGrid bound to the
supplyItem
sample DataSource, and that ListGrid was showing a Record withitemId
23, and you wanted to update theunitCost
field to a new value, you would use the following code:
// updatedRecord is the record we want to update
Record record = supplyItemDS.copyRecord(updatedRecord);
record.setAttribute("unitCost", 500);
DSResponse dsResponse = new DSResponse();
dsResponse.setData(record);
dsResponse.setOperationType(DSOperationType.UPDATE);
supplyItemDS.updateCaches(dsResponse);
To cause all components that have cache managers to drop their caches, provide a DSResponse with
DSResponse.invalidateCache
set.As an alternative to calling
updateCaches()
directly, if updates to other DataSources occur as a result of server-side logic, you can use the server-side API DSResponse.addRelatedUpdate(DSResponse) (Pro Edition and above), which ultimately callsupdateCaches()
for you - see that method's documentation for details.NOTE:: if
updateCaches
is called for aclientOnly
DataSource, it will updatecacheData
synchronously in addition to notifying all cache managers as normal.If a DataSource has
cacheAllData
set and a full cache has been obtained, callingupdateCaches
will automatically update the cache.Note that the DSResponse provided to this method will not go through
transformResponse()
or other processing that would normally occur for a DSResponse resulting from a DSRequest sent by the application in this page.- Parameters:
dsResponse
- the provided DSResponse must minimally have dataSource, operationType, and data setdsRequest
- optional dsRequest. If not specified, a DSRequest will be automatically created based on the DataSource and operationType of the DSResponse
-
updateData
Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See theerror handling overview
for more information.- Parameters:
updatedRecord
- updated record- See Also:
-
updateData
-
updateData
Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.If a callback was provided, it will be invoked when the operation completes successfully. If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See theerror handling overview
for more information.- Parameters:
updatedRecord
- updated recordcallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issued- See Also:
-
validateData
Contacts the server to run server-side validation on a DSRequest and either returnsDSResponse.errors
validation errors or aDSResponse.status
code of 0.A "validate" dsRequest is effectively always
RPCRequest.willHandleError
:true. It is a normal condition for a "validate" DSResponse to have validation errors and the response will never go to system-wide handling for unexpected errors (HandleErrorCallback.handleError()
).- Parameters:
values
- record values to validate- See Also:
-
validateData
-
validateData
Contacts the server to run server-side validation on a DSRequest and either returnsDSResponse.errors
validation errors or aDSResponse.status
code of 0.A "validate" dsRequest is effectively always
RPCRequest.willHandleError
:true. It is a normal condition for a "validate" DSResponse to have validation errors and the response will never go to system-wide handling for unexpected errors (HandleErrorCallback.handleError()
).- Parameters:
values
- record values to validatecallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issued- See Also:
-
viewFile
Display a file stored in a field of type:"binary" in a new browser window.This will open a new browser window to show the file. Depending on the file type, the user's installed plugins and applications, and the user's browser settings, this may cause the file to be actually displayed in the new browser window, or may prompt the user to either launch an external application to view the file or save the file to disk.
Note that if this method is called for a record with no associated file, the target window's new URL may not be functional. By default when dataSources encounter a
binary type fields
, an additional field,<fieldName>_filename
, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to view a file.See the overview of
Binary Fields
for details.- Parameters:
data
- Record to download. Only required to have a value for the primary key field.
-
viewFile
-
viewFile
Display a file stored in a field of type:"binary" in a new browser window.This will open a new browser window to show the file. Depending on the file type, the user's installed plugins and applications, and the user's browser settings, this may cause the file to be actually displayed in the new browser window, or may prompt the user to either launch an external application to view the file or save the file to disk.
Note that if this method is called for a record with no associated file, the target window's new URL may not be functional. By default when dataSources encounter a
binary type fields
, an additional field,<fieldName>_filename
, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to view a file.See the overview of
Binary Fields
for details.- Parameters:
data
- Record to download. Only required to have a value for the primary key field.fieldName
- Optional name of the binary field containing the file. If not provided, the first binary field is used. SeeFieldName
requestProperties
- Additional properties to set on the DSRequest that will be issued.
-
canFlattenCriteria
Returns true if callingflattenCriteria()
on the passed criteria would produce logically equivalent criteria.- Parameters:
criteria
- the AdvancedCriteria to check for flatness- Returns:
- true if criteria can be flattened without logical change
-
combineCriteria
Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator". Note that the combined criteria object will be an AdvancedCriteria unless:- both input criteria objects are simple, and
- the "outerOperator" is "and", and
- there is no collision of key names on the two criteria
- Parameters:
criteria1
- first criteria objectcriteria2
- second criteria object- Returns:
- The combined criteria
- See Also:
-
combineCriteria
public static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator) -
combineCriteria
public static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator, TextMatchStyle textMatchStyle) Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator". Note that the combined criteria object will be an AdvancedCriteria unless:- both input criteria objects are simple, and
- the "outerOperator" is "and", and
- there is no collision of key names on the two criteria
- Parameters:
criteria1
- first criteria objectcriteria2
- second criteria objectouterOperator
- operator to use to combine the criteria. Defaults to "and"textMatchStyle
- style of matching text, if it is necessary to convert a simple criteria object to an AdvancedCriteria. Defaults to "substring"- Returns:
- The combined criteria
- See Also:
-
convertCriteria
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.- Parameters:
criteria
- simple criteria- Returns:
- equivalent AdvancedCriteria object
-
convertCriteria
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.- Parameters:
criteria
- simple criteriatextMatchStyle
- default style of matching text. Defaults to "substring"- Returns:
- equivalent AdvancedCriteria object
-
copyCriteria
Create a copy of a criteria.- Parameters:
criteria
- criteria to copy- Returns:
- copy of criteria
-
flattenCriteria
Returns new criteria that has at most one top-level LogicalOperator ("and" or "or"). This new criteria will be considered "flat" byisFlatCriteria()
.Not all AdvancedCriteria can be flattened and remain logically equivalent. When criteria will be logically modified by flattening, all criteria that appear anywhere in the AdvancedCriteria structure will appear under a single top-level operator, which will be the same top-level operator as the passed AdvancedCriteria.
For example, given criteria like this (in the JSON representation of AdvancedCriteria):
{ operator: "and", criteria: [ { fieldName: "continent", operator: "equals", value: "Europe"}, { operator: "or", criteria: [ { fieldName: "countryName", operator: "iEndsWith", value: "land"}, { fieldName: "population", operator: "lessThan", value: 3000000} ]} ] }
The returned criteria would be:{ operator: "and", criteria: [ { fieldName: "continent", operator: "equals", value: "Europe"}, { fieldName: "countryName", operator: "iEndsWith", value: "land"}, { fieldName: "population", operator: "lessThan", value: 3000000} ]}
This returned criteria is not logically equivalent to the passed criteria - the "iEndsWith" and "lessThan" criteria that were formerly nested under a logical "or" operator must now both be satisfied instead of either being satisfied. You can usecanFlattenCriteria()
to detect whether an AdvancedCriteria is going to be changed byflattenCriteria()
.Because the returned criteria may not be logically equivalent,
flattenCriteria
should not be used as a means of simplifying criteria to make server implementation easier or anything of the kind. The primary purpose of returning logically different criteria is to enable an end user to switch from an interface for editing nested criteria to an interface that can't handle nested criteria and convert the criteria while preserving as much as possible.- Parameters:
criteria
- the AdvancedCriteria to flatten- Returns:
- flattened criteria
-
getAdvancedCriteriaDescription
public static String getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource) Returns a human-readable string describing the clauses in this advanced criteria or criterion.- Parameters:
criteria
- Criteria to convert to a readable stringdataSource
- DataSource to provide definitions of operators- Returns:
- Human-readable string describing the clauses in the passed criteria
-
getAdvancedCriteriaDescription
public static String getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource, CriteriaOutputSettings criteriaOutputSettings) Returns a human-readable string describing the clauses in this advanced criteria or criterion.- Parameters:
criteria
- Criteria to convert to a readable stringdataSource
- DataSource to provide definitions of operatorscriteriaOutputSettings
- optional configuration settings for the output- Returns:
- Human-readable string describing the clauses in the passed criteria
-
getAggregationDescription
public static String getAggregationDescription(AdvancedCriterionSubquery subquery, DataSource dataSource) Returns a human-readable string describing the aggregation properties in the request:DSRequest.groupBy
andDSRequest.summaryFunctions
.- Parameters:
subquery
- Subquery with aggregation to convert to a readable stringdataSource
- DataSource to provide field properties- Returns:
- Human-readable string describing the aggregation in the passed request
-
getDataSource
Lookup a DataSource by ID. -
getLoaderURL
Returns theloaderURL
- Returns:
- The loaderURL
-
getSortBy
Given an array ofSortSpecifier
s, return a simple list of Strings in the format expected byDSRequest.sortBy
.- Parameters:
sortSpecifiers
- The list of specifiers to return in sortBy format- Returns:
- An array of sort-definitions in the format expected by
DSRequest.sortBy
-
getSortSpecifiers
Return an array ofSortSpecifier
s, given an array of Strings in the format expected byDSRequest.sortBy
.- Parameters:
sortBy
- A list of sortBy strings in the format expected byDSRequest.sortBy
- Returns:
- An array of
SortSpecifier
s equivalent to the passed in string array
-
getSortSpecifiers
Return an array ofSortSpecifier
s, given an array of Strings in the format expected byDSRequest.sortBy
.- Parameters:
sortBy
- A list of sortBy strings in the format expected byDSRequest.sortBy
context
- Context dataSource or component.- Returns:
- An array of
SortSpecifier
s equivalent to the passed in string array
-
hasCustomTypeOperators
Returns true if the operator list for the passed type has been customized via a call tosetTypeOperators()
.- Parameters:
typeName
-ds
-- See Also:
-
isFlatCriteria
Returns true if a given AdvancedCriteria is "flat." That is, the criteria consists of either:- a top-level
"and" or "or"
Criterion
, where none of thesubcriteria
uselogical operators
, hence have no subcriteria of their own - a single Criterion that is not a logical operator, hence has no subcriteria
- Parameters:
criteria
- the AdvancedCriteria to check for flatness- Returns:
- true if criteria is flat
- a top-level
"and" or "or"
-
load
Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. The callback is passed a single parameter, thedsID
list passed into the method. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired immediately.To force reloading of DataSources that have already been loaded, pass
true
for the forceReload parameter. Note that if a DataSource has been created locally with the specified ID, even if this is aMockDataSource
, theforceReload
parameter will be required to force the "real" dataSource to be loaded.- Parameters:
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completes
-
load
Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. The callback is passed a single parameter, thedsID
list passed into the method. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired immediately.To force reloading of DataSources that have already been loaded, pass
true
for the forceReload parameter. Note that if a DataSource has been created locally with the specified ID, even if this is aMockDataSource
, theforceReload
parameter will be required to force the "real" dataSource to be loaded.- Parameters:
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loaded
-
loadWithParents
Variation ofload()
that will also automatically load any DataSources that the requested DataSources inherit from (viainheritsFrom
).If the parent DataSource is already loaded, calling
loadWithParents
will not automatically reload them unless the forceReload parameter is passed.- Parameters:
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completes
-
loadWithParents
Variation ofload()
that will also automatically load any DataSources that the requested DataSources inherit from (viainheritsFrom
).If the parent DataSource is already loaded, calling
loadWithParents
will not automatically reload them unless the forceReload parameter is passed.- Parameters:
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loaded
-
makeFileSpec
Converts a file path to aFileSpec
.- Parameters:
path
- The path to convert, e.g. "employees.ds.xml"- Returns:
- The equivalent FileSpec, e.g. {fileName: "employees", fileType: "ds", fileFormat: xml"}
-
setLoaderURL
Sets the URL where the DataSourceLoader servlet has been installed; this is used by theload()
method. Note, one reason you may wish to modify the loader URL is to include a Cross-Site Request Forgery (CSRF) token, as describedhere
- Parameters:
url
- The new loaderURL
-
setTypeOperators
Set the list of validOperatorId
s for a given FieldType.- Parameters:
typeName
-operators
- available Operators- See Also:
-
verifyDataSourcePair
A utility that checks for discrepancies between any two DataSources, typically used to warn about issues commonly found during the Reify design / development cycle, and logs its findings to the console. Similar to the server-side ReifyDataSourceValidator in scope, but with no support for server-only attributes (e.g., Declarative Security).INFO level messages are logged when any of the following conditions are discovered:
- A field defined in "live" is not also present in mock
- A field defined in "live" has a different title than mock (fields using i18n titles are not checked)
- A field defined in mock is not also present in "live"
- A field defined in mock has a different type than in live (and the live type is a not a sub-type of the mock type)
- Fields in mock have a different order than in "live" (after ignoring any fields that mock lacks)
- Parameters:
live
- DataSource to compare using 'live' rulesmock
- DataSource to compare using 'mock' rules- Returns:
- Each message logged, with its fieldName & severity level
-
setDefaultProperties
Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.
- Parameters:
dataSourceProperties
- properties that should be used as new defaults when instances of this class are created- See Also:
-
onInit
protected void onInit() -
registerID
- Overrides:
registerID
in classBaseClass
-
setID
-
setAddGlobalId
Whether to make this DataSource available as a global variable for convenience.Note : This is an advanced setting
- Parameters:
addGlobalId
- addGlobalId Default value is true- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getAddGlobalId
Whether to make this DataSource available as a global variable for convenience.- Returns:
- Boolean
-
setDataProtocol
Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. May be overridden for individual request types usingdataProtocol
}- Parameters:
dataProtocol
- dataProtocol Default value is null- Returns:
DataSource
instance, for chaining setter calls- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
setDefaultParams
HTTP parameters that should be submitted with every DSRequest.
Useful for authenticated services that require a sessionId with every request.
Can be set for all operations of a given DataSource as DataSource.defaultParams.- Parameters:
defaultParams
- the default params
-
getDefaultParams
HTTP parameters that should be submitted with every DSRequest.
Useful for authenticated services that require a sessionId with every request.
Can be set for all operations of a given DataSource as DataSource.defaultParams.- Returns:
- the default params
-
getDataProtocol
Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. May be overridden for individual request types usingdataProtocol
}- Returns:
- DSDataProtocol
-
get
Synonym ofDataSource.getDataSource
: Lookup a DataSource by ID.- Parameters:
ID
- DataSource ID- Returns:
- the DataSource with this ID, if loaded, otherwise null.
-
get
public static DataSource get(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer) Synonym ofDataSource.getDataSource
: Lookup a DataSource by ID.- Parameters:
ID
- DataSource IDrequestTransformer
- the request transformer. Pass null to use the default transformresponseTransformer
- the response transformer. Pass null to use the default transform- Returns:
- the DataSource with this ID, if loaded, otherwise null.
-
getDataSource
public static DataSource getDataSource(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer) Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer. The RequestTransformer and ResponseTransformer parameters provide the equivalent functionality of overridingtransformRequest(DSRequest)
andtransformResponse(DSResponse, DSRequest, Object)
when instantiating a DataSource on the client. However when obtaining a DataSource instance from the server using this API,transformRequest(DSRequest)
andtransformResponse(DSResponse, DSRequest, Object)
cannot be overridden and so the requestTransformer and responseTransformer parameters can be passed instead.- Parameters:
ID
- DataSource IDrequestTransformer
- the request transformer. Pass null to use the default transformresponseTransformer
- the response transformer. Pass null to use the default transform- Returns:
- the DataSource with this ID, if loaded, otherwise null.
-
useOfflineResponse
Override point to allow application code to suppress use of a particular offline response. For example, application code may wish to examine the response'sofflineTimestamp
to make a decision about whether the response is too stale to be useful.This is an application override point only; there is no default implementation.
Note: This is an override point
- Parameters:
dsRequest
- The dsRequest objectdsResponse
- The corresponding dsResponse object returned from offline cache- Returns:
- true to allow this response to be used, false to prevent it
-
isCreated
public boolean isCreated() -
getJsObj
-
setInheritsFrom
ID of another DataSource this DataSource inherits its DataSource fields from.
Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields. Fields with the same name are merged in the same way that databound component fields are merged with DataSource fields.
The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can setuseParentFieldOrder
to instead use the parent's field order, with new local fields appearing last.
You can setshowLocalFieldsOnly
to have all non-local fields hidden.
Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other viainheritsFrom
This feature can be used for creating a customized view (eg, only certain fields shown) which will be used bymultiple databound components.adding presentation-specific attributes to metadata that has been automatically derived fromXMLTools.loadXMLSchema(String, XSDLoadCallback)
or other metadata formats modelling object subclassing and extension in server-side code and storage systems modelling relational database joins, and the equivalents in other systems creating hooks for others to customize your application in a maintainable way. For example, if you have a dataSource "employee", you can create a dataSource"customizedEmployee" which inherits from "employee" but does not initially define anyfields, and bind all databound components to"customizedEmployee". Customizations of fields (including appearance changes, fieldorder, new fields, hiding of fields, and custom validation rules) can be added to"customizedEmployee", so that they are kept separtely from the original field data and have the best possible chance of working with future versions of the "employee"dataSource.- Parameters:
inheritsFrom
- the datasource to inherit from- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
setFields
The list of fields that compose records from this DataSource.Each DataSource field can have type, user-visible title, validators, and other metadata attached.
- Parameters:
fields
- fields Default value is null- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
addField
Add a field to the DataSource- Parameters:
field
- the datasource field- Throws:
IllegalStateException
- this property cannot be changed after the underlying component has been created
-
getFields
The list of fields that compose records from this DataSource.Each DataSource field can have type, user-visible title, validators, and other metadata attached.
- Returns:
- array of DataSourceFields
-
xmlSerialize
Serialize a JavaScript object as XML.

 The JavaScript Object passed to
xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
 element named after thetagName
(orID
if
 tagName is unset). Each property of the object becomes a subElement. For example,
 using a DataSource to serialize like this:
DSRequest inputObject = new DSRequest(); inputObject.setStartRow(5); inputObject.setEndRow(50); Record records[] = new Record[2]; records[0] = new Record(); records[0].setAttribute("field1", "value1"); records[0].setAttribute("field2", new Date()); records[1] = new Record(); records[1].setAttribute("field1", "value3"); records[1].setAttribute("field2", (String)null); inputObject.setAttribute("data", records); DataSource myDS = new DataSource(); myDS.setTagName("DSRequest"); myDS.xmlSerialize(inputObject.getJsObj());

 .. produces the following XML:

 <DSRequest>
 <startRow>5</startRow>
 <endRow>50</endRow>
 <data>
 <field1>value1</field1>
 <field2>2005-10-14T18:01:16</field2>
 </data>
 <data>
 <field1>value3</field1>
 <field2></field2>
 </data>
 </DSRequest>



 If you are working with a WSDL-described web service, XML serialization is performed
 automatically by APIs like
WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)
- you only need to
 know about serialization in order to understand how to put together JavaScript data that
 will fill in an XML message properly. 


 Note: when trying to send data to a web service, it is best to avoid putting
 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP
 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding
 Web Service messages are very complex and are subject to change with new versions of the
 web service you are contacting, whereas the data itself is easy to manipulate and less
 likely to change.


 To troubleshoot message formation, you can set the log category "xmlComm" to 
DEBUG
level in order to see the XML message formed by Smart GWT reported
 in log statements in the Developer Console.

- Parameters:
data
- data to be serialized- Returns:
- data as serialized to XML
-
xmlSerialize
Serialize a JavaScript object as XML.

 The JavaScript Object passed to
xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
 element named after thetagName
(orID
if
 tagName is unset). Each property of the object becomes a subElement. For example,
 using a DataSource to serialize like this:
DSRequest inputObject = new DSRequest(); inputObject.setStartRow(5); inputObject.setEndRow(50); Record records[] = new Record[2]; records[0] = new Record(); records[0].setAttribute("field1", "value1"); records[0].setAttribute("field2", new Date()); records[1] = new Record(); records[1].setAttribute("field1", "value3"); records[1].setAttribute("field2", (String)null); inputObject.setAttribute("data", records); DataSource myDS = new DataSource(); myDS.setTagName("DSRequest"); myDS.xmlSerialize(inputObject.getJsObj());

 .. produces the following XML:

 <DSRequest>
 <startRow>5</startRow>
 <endRow>50</endRow>
 <data>
 <field1>value1</field1>
 <field2>2005-10-14T18:01:16</field2>
 </data>
 <data>
 <field1>value3</field1>
 <field2></field2>
 </data>
 </DSRequest>



 If you are working with a WSDL-described web service, XML serialization is performed
 automatically by APIs like
WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)
- you only need to
 know about serialization in order to understand how to put together JavaScript data that
 will fill in an XML message properly. 


 Note: when trying to send data to a web service, it is best to avoid putting
 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP
 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding
 Web Service messages are very complex and are subject to change with new versions of the
 web service you are contacting, whereas the data itself is easy to manipulate and less
 likely to change.


 To troubleshoot message formation, you can set the log category "xmlComm" to 
DEBUG
level in order to see the XML message formed by Smart GWT reported
 in log statements in the Developer Console.

- Parameters:
data
- data to be serializedflags
- options for the serialization engine- Returns:
- data as serialized to XML
-
xmlSerialize
Serialize a JavaScript object as XML.

 The JavaScript Object passed to
xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
 element named after thetagName
(orID
if
 tagName is unset). Each property of the object becomes a subElement. For example,
 using a DataSource to serialize like this:
DSRequest inputObject = new DSRequest(); inputObject.setStartRow(5); inputObject.setEndRow(50); Record records[] = new Record[2]; records[0] = new Record(); records[0].setAttribute("field1", "value1"); records[0].setAttribute("field2", new Date()); records[1] = new Record(); records[1].setAttribute("field1", "value3"); records[1].setAttribute("field2", (String)null); inputObject.setAttribute("data", records); DataSource myDS = new DataSource(); myDS.setTagName("DSRequest"); myDS.xmlSerialize(inputObject.getJsObj());

 .. produces the following XML:

 <DSRequest>
 <startRow>5</startRow>
 <endRow>50</endRow>
 <data>
 <field1>value1</field1>
 <field2>2005-10-14T18:01:16</field2>
 </data>
 <data>
 <field1>value3</field1>
 <field2></field2>
 </data>
 </DSRequest>



 If you are working with a WSDL-described web service, XML serialization is performed
 automatically by APIs like
WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)
- you only need to
 know about serialization in order to understand how to put together JavaScript data that
 will fill in an XML message properly. 


 Note: when trying to send data to a web service, it is best to avoid putting
 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP
 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding
 Web Service messages are very complex and are subject to change with new versions of the
 web service you are contacting, whereas the data itself is easy to manipulate and less
 likely to change.


 To troubleshoot message formation, you can set the log category "xmlComm" to 
DEBUG
level in order to see the XML message formed by Smart GWT reported
 in log statements in the Developer Console.

- Parameters:
data
- data to be serializedflags
- options for the serialization engine- Returns:
- data as serialized to XML
-
xmlSerialize
Serialize a JavaScript object as XML.

 The JavaScript Object passed to
xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
 element named after thetagName
(orID
if
 tagName is unset). Each property of the object becomes a subElement. For example,
 using a DataSource to serialize like this:
DSRequest inputObject = new DSRequest(); inputObject.setStartRow(5); inputObject.setEndRow(50); Record records[] = new Record[2]; records[0] = new Record(); records[0].setAttribute("field1", "value1"); records[0].setAttribute("field2", new Date()); records[1] = new Record(); records[1].setAttribute("field1", "value3"); records[1].setAttribute("field2", (String)null); inputObject.setAttribute("data", records); DataSource myDS = new DataSource(); myDS.setTagName("DSRequest"); myDS.xmlSerialize(inputObject.getJsObj());

 .. produces the following XML:

 <DSRequest>
 <startRow>5</startRow>
 <endRow>50</endRow>
 <data>
 <field1>value1</field1>
 <field2>2005-10-14T18:01:16</field2>
 </data>
 <data>
 <field1>value3</field1>
 <field2></field2>
 </data>
 </DSRequest>



 If you are working with a WSDL-described web service, XML serialization is performed
 automatically by APIs like
WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)
- you only need to
 know about serialization in order to understand how to put together JavaScript data that
 will fill in an XML message properly. 


 Note: when trying to send data to a web service, it is best to avoid putting
 together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP
 engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding
 Web Service messages are very complex and are subject to change with new versions of the
 web service you are contacting, whereas the data itself is easy to manipulate and less
 likely to change.


 To troubleshoot message formation, you can set the log category "xmlComm" to 
DEBUG
level in order to see the XML message formed by Smart GWT reported
 in log statements in the Developer Console.

- Parameters:
data
- data to be serializedflags
- options for the serialization engine- Returns:
- data as serialized to XML
-
xmlSerialize
Serialize a JavaScript object as XML.

 The JavaScript Object passed to
xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
-
getPatternMultiWildcardAsStringArray()
.