public class DataSource extends BaseClass implements HasDataChangedHandlers, HasHandleErrorHandlers
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.
DataBoundComponent
,
FileSource Operations
config, configOnly, factoryCreated, factoryProperties, id, scClassName
Constructor and Description |
---|
DataSource() |
DataSource(com.google.gwt.core.client.JavaScriptObject jsObj) |
DataSource(java.lang.String dataURL) |
Modifier and Type | Method and Description |
---|---|
void |
addData(Record newRecord)
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.
|
com.google.gwt.event.shared.HandlerRegistration |
addDataChangedHandler(DataChangedHandler handler)
Add a dataChanged handler.
|
void |
addField(DataSourceField field)
Add a field to the DataSource
|
com.google.gwt.event.shared.HandlerRegistration |
addHandleErrorHandler(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 filter
Criteria . |
Record[] |
applyFilter(Record[] records,
Criteria criteria,
DSRequest requestProperties)
Returns records in the passed Record that match the provided filter
Criteria . |
static boolean |
canFlattenCriteria(AdvancedCriteria criteria)
Returns true if calling
flattenCriteria() on the passed
criteria would produce logically equivalent criteria. |
static void |
clearValueAtDataPath(DataSourceField field,
java.lang.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,
java.lang.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,
java.lang.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,
java.lang.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.
|
DSRequest |
cloneDSRequest(DSRequest dsRequest)
Creates a shallow copy of the given
DSRequest . |
DSResponse |
cloneDSResponse(DSResponse dsResponse)
Creates a shallow copy of the given
DSResponse . |
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,
java.lang.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(java.util.Date date1,
java.util.Date date2,
java.lang.String fieldName)
Convenience method to compare two Date objects appropriately, depending on whether the passed-in fieldName refers to a
field of
type "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.
|
AdvancedCriteria |
convertDataSourceCriteria(Criteria criteria)
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
|
AdvancedCriteria |
convertDataSourceCriteria(Criteria criteria,
TextMatchStyle textMatchStyle)
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
|
Criteria |
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.
|
Criteria |
convertRelativeDates(Criteria criteria,
java.lang.String timezoneOffset) |
Criteria |
convertRelativeDates(Criteria criteria,
java.lang.String timezoneOffset,
java.lang.Integer firstDayOfWeek) |
Criteria |
convertRelativeDates(Criteria criteria,
java.lang.String timezoneOffset,
java.lang.Integer firstDayOfWeek,
java.util.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.
|
Record |
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.
|
com.google.gwt.core.client.JavaScriptObject |
create() |
void |
createAlias(java.lang.String alias)
Assigns an alias to this DataSource
|
void |
downloadFile(Record data)
Download a file stored in a field of type:"binary" in a DataSource record.
|
void |
downloadFile(Record data,
java.lang.String fieldName) |
void |
downloadFile(Record data,
java.lang.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 |
execute(DSRequest dsRequest)
Executes the given DSRequest on this DataSource.
|
void |
exportClientData(java.lang.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(java.lang.Object[] data,
DSRequest requestProperties)
Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users.
|
void |
exportData()
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 |
fetchData()
Deprecated.
|
void |
fetchData(Criteria criteria) |
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(java.lang.Object pkValue)
Fetch a single record from the DataSource by
primary key . |
void |
fetchRecord(java.lang.Object pkValue,
DSCallback callback) |
void |
fetchRecord(java.lang.Object pkValue,
DSCallback callback,
DSRequest requestProperties)
Fetch a single record from the DataSource by
primary key . |
boolean |
fieldMatchesFilter(java.lang.Object fieldValue,
java.lang.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 to
DSRequest.textMatchStyle in the passed
requestProperties , regardless of the actual field type if the filter value is an Array, the
comparison is a logical OR. |
boolean |
fieldMatchesFilter(java.lang.Object fieldValue,
java.lang.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 passed
requestProperties , regardless of the actual field type if the filter value is an Array, the
comparison is a logical OR. |
void |
filterData()
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").
|
java.lang.String |
formatFieldValue(DataSourceField field,
java.lang.Object value)
Formats the supplied value using the
SimpleType derived from the field definition. |
static DataSource |
get(java.lang.String ID)
Synonym of
DataSource.getDataSource : Lookup a DataSource by
ID. |
static DataSource |
get(java.lang.String ID,
RequestTransformer requestTransformer,
ResponseTransformer responseTransformer)
Synonym of
DataSource.getDataSource : Lookup a DataSource by
ID. |
DataSourceField[] |
getAddedAuditFields()
The list of extra manually managed fields that will be added to the
fields of the
Audit DataSource . |
java.lang.Boolean |
getAddGlobalId()
Whether to make this DataSource available as a global variable for convenience.
|
static java.lang.String |
getAdvancedCriteriaDescription(AdvancedCriteria criteria,
DataSource dataSource)
Returns a human-readable string describing the clauses in this advanced criteria or criterion.
|
static java.lang.String |
getAdvancedCriteriaDescription(AdvancedCriteria criteria,
DataSource dataSource,
CriteriaOutputSettings criteriaOutputSettings)
Returns a human-readable string describing the clauses in this advanced criteria or criterion.
|
static java.lang.String |
getAggregationDescription(AdvancedCriterionSubquery subquery,
DataSource dataSource)
Returns a human-readable string describing the aggregation properties in the request:
DSRequest.groupBy and DSRequest.summaryFunctions . |
java.lang.Boolean |
getAllowAdvancedCriteria()
By default, all DataSources are assumed to be capable of handling
AdvancedCriteria on
fetch or filter type operations. |
java.lang.Boolean |
getAllowAggregation()
This property indicates whether this DataSource supports aggregation/summarization of field values using the
summaryFunction mechanism. |
java.lang.Boolean |
getAllowDynamicTreeJoins()
By default, custom dataSource implementations are assumed to be unable to support
dynamic tree joins . |
java.lang.Boolean |
getAllowRelatedFieldsInCriteria()
This property indicates whether this DataSource supports referencees to related fields in criteria, either using
qualified field names, or subqueries.
|
RelationPath |
getAllPathsToRelation(DataSource targetDS)
Returns all known paths between this and the given targetDS.
|
RelationPath |
getAllPathsToRelation(java.lang.String targetDS)
Returns all known paths between this and the given targetDS.
|
java.lang.Boolean |
getArrayCriteriaForceExact()
With ordinary
simple criteria , it is possible to provide an array
of values for a given field, which means "any of these values". |
java.lang.Boolean |
getAutoCacheAllData()
When a DataSource is not
cacheAllData :true and a fetch
results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically
switch to cacheAllData:true and prevent further server-trips for fetch requests. |
java.lang.Boolean |
getAutoConvertRelativeDates()
Whether to convert relative date values to concrete date values before sending to the server.
|
boolean |
getAutoDeriveTitles()
If set, titles are automatically derived from
field.name for
any field that does not have a field.title and is not marked
hidden :true, by calling the method getAutoTitle() . |
boolean |
getAutoDiscoverTree()
Causes
Tree.discoverTree() to be called on dsResponse.data in
order to automatically discover tree structures in the response data. |
static java.lang.String |
getAutoTitle(java.lang.String identifier)
Utility method to derive a reasonable user-visible title from an identifier.
|
java.lang.Boolean |
getCacheAcrossOperationIds()
When
cacheAllData mode is enabled and a cacheAllOperationId has been set, this flag affects whether
cached results are used for all "fetch" requests regardless of their DSRequest.operationId , or are used only for "fetch" requests that use
the cacheAllOperationId , allowing other requests to go to server normally. |
java.lang.Boolean |
getCacheAllData()
Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
|
java.lang.String |
getCacheAllOperationId()
DSRequest.operationId to use for fetching data in case cacheAllData is true. |
Record[] |
getCacheData()
For a
cacheAllData or client-only DataSource, a set of
records to use as a dataset, specified as an Array of JavaScript Objects representing records. |
int |
getCacheMaxAge()
The maximum time, in seconds, to maintain the client-side cache.
|
java.lang.String |
getCallbackParam()
Applies only to dataFormat: "json" and
dataTransport :"scriptInclude". |
java.lang.Boolean |
getCanAggregate()
By default, all DataSources are assumed to be capable of handling
ServerSummaries on
fetch or filter type operations. |
boolean |
getCanMultiSort()
When true, indicates that this DataSource supports multi-level sorting.
|
java.lang.String |
getChildrenField()
fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
|
java.lang.Boolean |
getClientOnly()
A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as
DSRequests 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 that
inheritsFrom 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 that
inheritsFrom the original DataSource. |
protected DSResponse |
getClientOnlyResponse(DSRequest request,
Record... serverData)
Return a "spoofed" response for a
clientOnly or cacheAllData DataSource. |
CriteriaPolicy |
getCriteriaPolicy()
Decides under what conditions the
ResultSet cache should be dropped when the ResultSet.criteria changes. |
java.lang.String |
getDataField()
Name of the field that has the most pertinent numeric, date, or enum value, for use when a
DataBoundComponent needs to show a short summary of a record. |
DSDataFormat |
getDataFormat()
Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when
fetchData() is called). |
DSProtocol |
getDataProtocol()
Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
|
static DataSource |
getDataSource(java.lang.String ID)
Lookup a DataSource by ID.
|
static DataSource |
getDataSource(java.lang.String ID,
RequestTransformer requestTransformer,
ResponseTransformer responseTransformer)
Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer.
|
RPCTransport |
getDataTransport()
Transport to use for all operations on this DataSource.
|
java.lang.String |
getDataURL()
Default URL to contact to fulfill all DSRequests.
|
java.lang.Boolean |
getDeepCloneNonFieldValuesOnEdit()
When editing values in
DataBoundComponent 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 by dataPath ). |
java.lang.Boolean |
getDeepCloneOnEdit()
Before we start editing values in
DataBoundComponent 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). |
java.util.Map |
getDefaultParams()
HTTP parameters that should be submitted with every DSRequest.
|
RelationPath |
getDefaultPathToRelation(DataSource targetDS)
Returns the path having the shortest distance between this and the given targetDS, as determined by
getShortestPathToRelation() . |
RelationPath |
getDefaultPathToRelation(java.lang.String targetDS)
Returns the path having the shortest distance between this and the given targetDS, as determined by
getShortestPathToRelation() . |
TextMatchStyle |
getDefaultTextMatchStyle()
The default textMatchStyle to use for
DSRequest s that do not explicitly state a textMatchStyle . |
java.lang.String |
getDescription()
An optional description of the DataSource's content.
|
java.lang.String |
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.
|
DiscoverTreeSettings |
getDiscoverTreeSettings()
Settings to use when discoverTree() is automatcially called because
autoDiscoverTree is set to true for this DataSource |
java.lang.Object |
getDisplayValue(java.lang.String fieldName,
java.lang.Object value)
Given a fieldName and a dataValue, apply any
DataSourceField.valueMap for the field and return the display value for the field |
java.lang.Boolean |
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.
|
java.lang.Boolean |
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.
|
java.lang.Boolean |
getEnforceSecurityOnClient()
Indicates that
DeclarativeSecurity should be enforced on the client. |
java.lang.String |
getFetchDataURL(Criteria criteria)
Returns a URL to DataSource fetch operation.
|
java.lang.String |
getFetchDataURL(Criteria criteria,
DSRequest requestProperties)
Returns a URL to DataSource fetch operation.
|
DataSourceField |
getField(java.lang.String fieldName)
Return the field definition object.
|
java.lang.String |
getFieldAutoTitle(java.lang.String identifier)
Return a reasonable user-visible title given a fieldName.
|
Criteria |
getFieldCriterion(Criteria criterion,
java.lang.String fieldName)
Returns the depth-first match of a criterion matching the given fieldName.
|
OperatorId[] |
getFieldDefaultOperator(DataSourceField field)
Get the default
OperatorId for this field. |
OperatorId[] |
getFieldDefaultOperator(java.lang.String field)
Get the default
OperatorId for this field. |
DataSourceField |
getFieldForDataPath(java.lang.String dataPath)
Return the field definition object corresponding to the supplied dataPath
|
java.lang.String[] |
getFieldNames()
Retrieves the list of fields declared on this DataSource.
|
java.lang.String[] |
getFieldNames(boolean excludeHidden)
Retrieves the list of fields declared on this DataSource.
|
OperatorId[] |
getFieldOperators(DataSourceField field)
Get the list of OperatorId's available for the passed field.
|
OperatorId[] |
getFieldOperators(java.lang.String fieldName)
Get the list of OperatorId's available for the passed field-name.
|
DataSourceField[] |
getFields()
The list of fields that compose records from this DataSource.
|
static java.lang.Object |
getFieldValue(DataSourceField field,
Record record,
java.lang.String dataPath,
Canvas component,
java.lang.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 java.lang.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 java.lang.Object |
getFieldValue(DetailViewerField field,
Record record,
java.lang.String dataPath,
Canvas component,
java.lang.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 java.lang.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 java.lang.Object |
getFieldValue(FormItem field,
Record record,
java.lang.String dataPath,
Canvas component,
java.lang.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 java.lang.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 java.lang.Object |
getFieldValue(ListGridField field,
Record record,
java.lang.String dataPath,
Canvas component,
java.lang.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.
|
java.lang.String |
getFileURL(Record data)
Returns a direct URL to access a file stored in a field of type:"binary".
|
java.lang.String |
getFileURL(Record data,
java.lang.String fieldName) |
java.lang.String |
getFileURL(Record data,
java.lang.String fieldName,
DSRequest requestProperties)
Returns a direct URL to access a file stored in a field of type:"binary".
|
void |
getFileVersion(FileSpec fileSpec,
java.util.Date version,
GetFileVersionCallback callback)
Gets the contents of a particular file version stored in this DataSource.
|
java.util.Map |
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.
|
java.lang.String |
getIconField()
|
java.lang.Boolean |
getIgnoreTextMatchStyleCaseSensitive()
For fields on this dataSource that specify
ignoreTextMatchStyle true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. |
Criteria |
getImplicitCriteria()
Criteria that are implicitly applied to all fetches made through this DataSource.
|
java.lang.String |
getInfoField()
Name of the field that has the second most pertinent piece of textual information in the record, for use when a
DataBoundComponent needs to show a short summary of a record. |
java.lang.String |
getInheritsFrom()
ID of another DataSource this DataSource inherits its
fields from. |
java.lang.Boolean |
getIsSampleDS()
Used by Reify to identify DataSources that are provided as samples.
|
com.google.gwt.core.client.JavaScriptObject |
getJsObj() |
java.lang.String |
getJsonPrefix()
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this
application.
|
java.lang.String |
getJsonSuffix()
Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this
application.
|
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.
|
static java.lang.String |
getLoaderURL()
Returns the
loaderURL |
Criteria |
getMockDataCriteria()
When
mockMode is enabled, criteria to use in an initial "fetch"
DSRequest to retrieve sample data. |
java.lang.Integer |
getMockDataRows()
When
mockMode is enabled, number of rows of data to retrieve via
an initial "fetch" DSRequest, for use as sample data. |
java.lang.Boolean |
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 a
clientOnly DataSource, never writing changes back to the server. |
OperationBinding[] |
getOperationBindings()
Optional array of OperationBindings, which provide instructions to the DataSource about how each
DSOperation is to be performed.
|
static DataSource |
getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj) |
java.lang.String |
getPatternEscapeChar()
When using the
pattern operators search operator , character that escapes the patternSingleWildcard or patternMultiWildcard if placed before it, so that it is
treated as a literal character. |
java.lang.String |
getPatternMultiWildcard()
When using the
pattern operators search operator , character that matches a series of one or more characters. |
java.lang.String[] |
getPatternMultiWildcardAsString()
Deprecated.
in favor of
getPatternMultiWildcardAsStringArray() . |
java.lang.String[] |
getPatternMultiWildcardAsStringArray()
When using the
pattern operators search operator , character that matches a series of one or more characters. |
java.lang.String |
getPatternSingleWildcard()
When using the
pattern operators search operator , character that matches any single character. |
java.lang.String[] |
getPatternSingleWildcardAsString()
Deprecated.
in favor of
getPatternSingleWildcardAsStringArray() . |
java.lang.String[] |
getPatternSingleWildcardAsStringArray()
When using the
pattern operators search operator , character that matches any single character. |
java.lang.String |
getPluralTitle()
User-visible plural name for this DataSource.
|
java.lang.Boolean |
getPreventHTTPCaching()
If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as
cacheable.
|
DataSourceField |
getPrimaryKeyField()
Returns a pointer to the primaryKey field for this DataSource.
|
java.lang.String |
getPrimaryKeyFieldName()
Returns the primary key fieldName for this DataSource.
|
java.lang.String[] |
getPrimaryKeyFieldNames()
Returns a list of the names of this DataSource's
primaryKey fields. |
Record |
getPrimaryKeyFields()
Returns this DataSource's
primaryKey fields as a map of
fieldName to field. |
java.lang.Boolean |
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 the
ResultSet
documentation . |
java.lang.Boolean |
getQualifyColumnNames()
For dataSources of
serverType "sql", determines whether
we qualify column names with table names in any SQL we generate. |
java.lang.String |
getRecordName()
Provides a default value for
OperationBinding.recordName . |
java.lang.String |
getRecordXPath()
|
DSRequest |
getRequestProperties()
Additional properties to pass through to the
DSRequest s made by this DataSource. |
java.lang.String |
getRequiredMessage()
The required message when a field that has been marked as
required is not filled in by the user. |
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.
|
java.lang.String |
getResultSetClass()
Class for ResultSets used by this datasource.
|
java.lang.String |
getResultTreeClass()
Class for ResultTrees used by this datasource.
|
java.lang.String |
getSchemaNamespace()
For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to.
|
java.lang.Boolean |
getSendExtraFields()
Analogous to
dropExtraFields , for data sent to the
server. |
java.lang.Boolean |
getSendParentNode()
Set this attribute if you need to send the dsRequest.parentNode to the server-side.
|
java.lang.String |
getServiceNamespace()
For an XML DataSource, URN of the WebService to use to invoke operations.
|
RelationPath |
getShortestPathToRelation(DataSource targetDS)
Returns the path having the shortest distance between this and the given targetDS.
|
RelationPath |
getShortestPathToRelation(java.lang.String targetDS)
Returns the path having the shortest distance between this and the given targetDS.
|
java.lang.Boolean |
getShowLocalFieldsOnly()
For a DataSource that inherits
fields from another DataSource
(via inheritsFrom ), indicates that only the fields listed in
this DataSource should be shown. |
java.lang.Boolean |
getShowPrompt()
Whether RPCRequests sent by this DataSource should enable
RPCRequest.showPrompt in order to block user interactions until the request completes. |
SkipJSONValidation |
getSkipJSONValidation()
Sets what level of JSON validation will apply for this DataSource.
|
static java.lang.String[] |
getSortBy(SortSpecifier[] sortSpecifiers)
Given an array of
SortSpecifier s, return a simple list of Strings in the format
expected by DSRequest.sortBy . |
static SortSpecifier[] |
getSortSpecifiers(java.lang.String[] sortBy)
Return an array of
SortSpecifier s, given an array of Strings in the format expected by
DSRequest.sortBy . |
java.lang.Boolean |
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.
|
java.lang.String |
getTagName()
Tag name to use when serializing to XML.
|
Record[] |
getTestData()
For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
|
java.lang.String |
getTitle()
User-visible name for this DataSource.
|
java.lang.String |
getTitleField()
Best field to use for a user-visible title for an individual record from this dataSource.
|
boolean |
getTranslatePatternOperators()
Search operators like "matchesPattern" use patterns like "foo*txt" to match
text values. |
java.lang.Boolean |
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.
|
OperatorId[] |
getTypeOperators()
Get the list of
OperatorId s available on this DataSource for the given FieldType . |
OperatorId[] |
getTypeOperators(FieldType typeName)
Get the list of
OperatorId s available on this DataSource for the given FieldType . |
OperatorId[] |
getTypeOperators(java.lang.String typeName)
Get the list of
OperatorId s available on this DataSource for the given FieldType . |
java.lang.Boolean |
getUseFlatFields()
Like
DataBoundComponent.useFlatFields , but
applies to all DataBound components that bind to this DataSource. |
java.lang.Boolean |
getUseHttpProxy()
Like
OperationBinding.useHttpProxy , but serves as a
default for this DataSource that may be overridden by individual operationBindings. |
java.lang.Boolean |
getUseLocalValidators()
Whether to attempt validation on the client at all for this DataSource.
|
java.lang.Boolean |
getUseOfflineStorage()
Whether we store server responses for this DataSource into
browser-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). |
java.lang.Boolean |
getUseParentFieldOrder()
For a DataSource that inherits
fields from another DataSource
(via inheritsFrom ), indicates that the parent's field order
should be used instead of the order of the fields as declared in this DataSource. |
java.lang.Boolean |
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.
|
java.lang.Boolean |
getUseTestDataFetch()
When set, causes a
client-only or cacheAllData DataSource to create a second DataSource to perform
it's one-time fetch. |
java.lang.Boolean |
getValidateRelatedRecords()
If true, indicates that the Smart GWT Server should automatically apply a
ValidatorType of "hasRelatedRecord" to every field on this dataSource that has a foreignKey defined. |
java.lang.Boolean |
hasAllData()
When
cacheAllData 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 to
setTypeOperators() . |
void |
hasCustomTypeOperators(java.lang.String typeName)
Returns true if the operator list for the passed type has been customized via a call to
setTypeOperators() . |
static void |
hasCustomTypeOperators(java.lang.String typeName,
DataSource ds)
Returns true if the operator list for the passed type has been customized via a call to
setTypeOperators() . |
void |
hasFile(FileSpec fileSpec,
HasFileCallback callback)
Indicates whether a file exists in this DataSource.
|
void |
hasFileVersion(FileSpec fileSpec,
java.util.Date version,
HasFileCallback callback)
Indicates whether a particular file version exists in this DataSource.
|
void |
invalidateCache()
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 via
DataSourceField.formula or other similar attributes? |
boolean |
isCalculated(java.lang.String field)
Does the specified field have its value dynamically calculated via
DataSourceField.formula or other similar attributes? |
boolean |
isCreated() |
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 the subcriteria use logical
operators , hence have no subcriteria of their own a single Criterion that is not a logical operator, hence
has no subcriteria |
void |
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(java.lang.String[] dsID,
Function callback,
boolean forceReload)
Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
|
static void |
load(java.lang.String[] dsID,
Function callback,
DSLoadSettings settings)
Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
|
static void |
load(java.lang.String dsID,
Function callback)
Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
|
static void |
load(java.lang.String dsID,
Function callback,
boolean forceReload)
Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
|
static void |
loadWithParents(java.lang.String[] dsID,
Function callback,
boolean forceReload)
Variation of
DataSource.load that will also automatically load any
DataSources that the requested DataSources inherit from
(via DataSource.inheritsFrom ) |
static void |
loadWithParents(java.lang.String[] dsID,
Function callback,
DSLoadSettings settings)
Variation of
DataSource.load that will also automatically load any
DataSources that the requested DataSources inherit from
(via DataSource.inheritsFrom ). |
static void |
loadWithParents(java.lang.String dsID,
Function callback)
Variation of
load() that will also automatically load any DataSources
that the requested DataSources inherit from (via inheritsFrom ). |
static void |
loadWithParents(java.lang.String dsID,
Function callback,
boolean forceReload)
Variation of
load() that will also automatically load any DataSources
that the requested DataSources inherit from (via inheritsFrom ). |
static FileSpec |
makeFileSpec(java.lang.String path)
Converts a file path to a
FileSpec . |
protected void |
onInit() |
void |
performCustomOperation(java.lang.String operationId)
Invoke an operation declared with
OperationBinding.operationType "custom". |
void |
performCustomOperation(java.lang.String operationId,
Record data) |
void |
performCustomOperation(java.lang.String operationId,
Record data,
DSCallback callback) |
void |
performCustomOperation(java.lang.String operationId,
Record data,
DSCallback callback,
DSRequest requestProperties)
Invoke an operation declared with
OperationBinding.operationType "custom". |
void |
processResponse(java.lang.String requestId,
DSResponse dsResponse)
Process a dsResponse for a request initiated by a DataSource with
dataProtocol:"clientCustom" . |
boolean |
recordsAreEqual(java.lang.Object record1,
java.lang.Object record2)
Convenience method to test if two records are equal.
|
java.lang.String |
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).
|
java.lang.String |
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(java.lang.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(java.lang.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(java.lang.Object elements)
Transform a list of XML elements to DataSource records.
|
protected void |
registerID(java.lang.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(java.lang.String fileSpec)
Remove a file stored in this DataSource.
|
void |
removeFileVersion(FileSpec fileSpec,
java.util.Date version)
Remove a particular file version stored in this DataSource.
|
void |
removeFileVersion(FileSpec fileSpec,
java.util.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 |
saveFile(FileSpec fileSpec,
java.lang.String contents)
Save a file to the DataSource.
|
void |
saveFile(FileSpec fileSpec,
java.lang.String contents,
DSCallback callback)
Save a file to the DataSource.
|
static void |
saveValueViaDataPath(DataSourceField field,
java.lang.String dataPath,
java.lang.Boolean value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Date value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Double value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Float value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Integer value,
Record values,
java.lang.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,
java.lang.String dataPath,
com.google.gwt.core.client.JavaScriptObject value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Map value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.String value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Boolean value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Date value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Double value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Float value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Integer value,
Record values,
java.lang.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,
java.lang.String dataPath,
com.google.gwt.core.client.JavaScriptObject value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Map value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.String value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Boolean value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Date value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Double value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Float value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Integer value,
Record values,
java.lang.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,
java.lang.String dataPath,
com.google.gwt.core.client.JavaScriptObject value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Map value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.String value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Boolean value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Date value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Double value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Float value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.Integer value,
Record values,
java.lang.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,
java.lang.String dataPath,
com.google.gwt.core.client.JavaScriptObject value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.util.Map value,
Record values,
java.lang.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,
java.lang.String dataPath,
java.lang.String value,
Record values,
java.lang.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.
|
DataSource |
setAddedAuditFields(DataSourceField... addedAuditFields)
The list of extra manually managed fields that will be added to the
fields of the
Audit DataSource . |
void |
setAddGlobalId(java.lang.Boolean addGlobalId)
Whether to make this DataSource available as a global variable for convenience.
|
DataSource |
setAllowAdvancedCriteria(java.lang.Boolean allowAdvancedCriteria)
By default, all DataSources are assumed to be capable of handling
AdvancedCriteria on
fetch or filter type operations. |
DataSource |
setAllowAggregation(java.lang.Boolean allowAggregation)
This property indicates whether this DataSource supports aggregation/summarization of field values using the
summaryFunction mechanism. |
DataSource |
setAllowDynamicTreeJoins(java.lang.Boolean allowDynamicTreeJoins)
By default, custom dataSource implementations are assumed to be unable to support
dynamic tree joins . |
DataSource |
setAllowRelatedFieldsInCriteria(java.lang.Boolean allowRelatedFieldsInCriteria)
This property indicates whether this DataSource supports referencees to related fields in criteria, either using
qualified field names, or subqueries.
|
DataSource |
setArrayCriteriaForceExact(java.lang.Boolean arrayCriteriaForceExact)
With ordinary
simple criteria , it is possible to provide an array
of values for a given field, which means "any of these values". |
DataSource |
setAutoCacheAllData(java.lang.Boolean autoCacheAllData)
When a DataSource is not
cacheAllData :true and a fetch
results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically
switch to cacheAllData:true and prevent further server-trips for fetch requests. |
DataSource |
setAutoConvertRelativeDates(java.lang.Boolean autoConvertRelativeDates)
Whether to convert relative date values to concrete date values before sending to the server.
|
DataSource |
setAutoDeriveTitles(boolean autoDeriveTitles)
If set, titles are automatically derived from
field.name for
any field that does not have a field.title and is not marked
hidden :true, by calling the method getAutoTitle() . |
DataSource |
setAutoDiscoverTree(boolean autoDiscoverTree)
Causes
Tree.discoverTree() to be called on dsResponse.data in
order to automatically discover tree structures in the response data. |
DataSource |
setCacheAcrossOperationIds(java.lang.Boolean cacheAcrossOperationIds)
When
cacheAllData mode is enabled and a cacheAllOperationId has been set, this flag affects whether
cached results are used for all "fetch" requests regardless of their DSRequest.operationId , or are used only for "fetch" requests that use
the cacheAllOperationId , allowing other requests to go to server normally. |
DataSource |
setCacheAllData(java.lang.Boolean cacheAllData)
Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
|
DataSource |
setCacheAllOperationId(java.lang.String cacheAllOperationId)
DSRequest.operationId to use for fetching data in case cacheAllData is true. |
void |
setCacheData(Record... cacheData)
For a
cacheAllData or client-only DataSource, a set of
records to use as a dataset, specified as an Array of JavaScript Objects representing records. |
DataSource |
setCacheMaxAge(int cacheMaxAge)
The maximum time, in seconds, to maintain the client-side cache.
|
DataSource |
setCallbackParam(java.lang.String callbackParam)
Applies only to dataFormat: "json" and
dataTransport :"scriptInclude". |
DataSource |
setCanAggregate(java.lang.Boolean canAggregate)
By default, all DataSources are assumed to be capable of handling
ServerSummaries on
fetch or filter type operations. |
DataSource |
setCanMultiSort(boolean canMultiSort)
When true, indicates that this DataSource supports multi-level sorting.
|
DataSource |
setChildrenField(java.lang.String childrenField)
fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
|
DataSource |
setClientOnly(java.lang.Boolean clientOnly)
A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as
DSRequests are executed on it. |
DataSource |
setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
Decides under what conditions the
ResultSet cache should be dropped when the ResultSet.criteria changes. |
DataSource |
setDataField(java.lang.String dataField)
Name of the field that has the most pertinent numeric, date, or enum value, for use when a
DataBoundComponent needs to show a short summary of a record. |
DataSource |
setDataFormat(DSDataFormat dataFormat)
Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when
fetchData() is called). |
DataSource |
setDataProtocol(DSProtocol dataProtocol)
Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
|
DataSource |
setDataTransport(RPCTransport dataTransport)
Transport to use for all operations on this DataSource.
|
DataSource |
setDataURL(java.lang.String dataURL)
Default URL to contact to fulfill all DSRequests.
|
DataSource |
setDeepCloneNonFieldValuesOnEdit(java.lang.Boolean deepCloneNonFieldValuesOnEdit)
When editing values in
DataBoundComponent 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 by dataPath ). |
DataSource |
setDeepCloneOnEdit(java.lang.Boolean deepCloneOnEdit)
Before we start editing values in
DataBoundComponent 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(java.util.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.
|
DataSource |
setDefaultTextMatchStyle(TextMatchStyle defaultTextMatchStyle)
The default textMatchStyle to use for
DSRequest s that do not explicitly state a textMatchStyle . |
DataSource |
setDescription(java.lang.String description)
An optional description of the DataSource's content.
|
DataSource |
setDescriptionField(java.lang.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.
|
DataSource |
setDiscoverTreeSettings(DiscoverTreeSettings discoverTreeSettings)
Settings to use when discoverTree() is automatcially called because
autoDiscoverTree is set to true for this DataSource |
DataSource |
setDropExtraFields(java.lang.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.
|
DataSource |
setDropUnknownCriteria(java.lang.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.
|
DataSource |
setEnforceSecurityOnClient(java.lang.Boolean enforceSecurityOnClient)
Indicates that
DeclarativeSecurity should be enforced on the client. |
DataSource |
setEnumConstantProperty(java.lang.String enumConstantProperty)
The name of the property this DataSource uses for constant name when translating Java enumerated types to and from
Javascript, if the
EnumTranslateStrategy is set to "bean". |
DataSource |
setEnumOrdinalProperty(java.lang.String enumOrdinalProperty)
The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from
Javascript, if the
EnumTranslateStrategy is set to "bean". |
DataSource |
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.
|
DataSource |
setGlobalNamespaces(java.util.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 than
STATUS_SUCCESS . |
DataSource |
setIconField(java.lang.String iconField)
|
DataSource |
setID(java.lang.String id) |
DataSource |
setIgnoreTextMatchStyleCaseSensitive(java.lang.Boolean ignoreTextMatchStyleCaseSensitive)
For fields on this dataSource that specify
ignoreTextMatchStyle true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. |
DataSource |
setImplicitCriteria(Criteria implicitCriteria)
Criteria that are implicitly applied to all fetches made through this DataSource.
|
DataSource |
setInfoField(java.lang.String infoField)
Name of the field that has the second most pertinent piece of textual information in the record, for use when a
DataBoundComponent 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. |
DataSource |
setInheritsFrom(java.lang.String inheritsFrom)
ID of another DataSource this DataSource inherits its
fields from. |
DataSource |
setIsSampleDS(java.lang.Boolean isSampleDS)
Used by Reify to identify DataSources that are provided as samples.
|
DataSource |
setJsonPrefix(java.lang.String jsonPrefix)
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this
application.
|
DataSource |
setJsonSuffix(java.lang.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(java.lang.String url)
Sets the URL where the DataSourceLoader servlet has been installed; this is used by the
load() method. |
DataSource |
setMockDataCriteria(Criteria mockDataCriteria)
When
mockMode is enabled, criteria to use in an initial "fetch"
DSRequest to retrieve sample data. |
DataSource |
setMockDataRows(java.lang.Integer mockDataRows)
When
mockMode is enabled, number of rows of data to retrieve via
an initial "fetch" DSRequest, for use as sample data. |
DataSource |
setMockMode(java.lang.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 a
clientOnly DataSource, never writing changes back to the server. |
DataSource |
setOperationBindings(OperationBinding... operationBindings)
Optional array of OperationBindings, which provide instructions to the DataSource about how each
DSOperation is to be performed.
|
DataSource |
setPatternEscapeChar(java.lang.String patternEscapeChar)
When using the
pattern operators search operator , character that escapes the patternSingleWildcard or patternMultiWildcard if placed before it, so that it is
treated as a literal character. |
DataSource |
setPatternMultiWildcard(java.lang.String... patternMultiWildcard)
When using the
pattern operators search operator , character that matches a series of one or more characters. |
DataSource |
setPatternMultiWildcard(java.lang.String patternMultiWildcard)
When using the
pattern operators search operator , character that matches a series of one or more characters. |
DataSource |
setPatternSingleWildcard(java.lang.String... patternSingleWildcard)
When using the
pattern operators search operator , character that matches any single character. |
DataSource |
setPatternSingleWildcard(java.lang.String patternSingleWildcard)
When using the
pattern operators search operator , character that matches any single character. |
DataSource |
setPluralTitle(java.lang.String pluralTitle)
User-visible plural name for this DataSource.
|
DataSource |
setPreventHTTPCaching(java.lang.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.
|
DataSource |
setProgressiveLoading(java.lang.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 the
ResultSet
documentation . |
DataSource |
setQualifyColumnNames(java.lang.Boolean qualifyColumnNames)
For dataSources of
serverType "sql", determines whether
we qualify column names with table names in any SQL we generate. |
DataSource |
setRecordName(java.lang.String recordName)
Provides a default value for
OperationBinding.recordName . |
DataSource |
setRecordXPath(java.lang.String recordXPath)
|
DataSource |
setRequestProperties(DSRequest requestProperties)
Additional properties to pass through to the
DSRequest s made by this DataSource. |
DataSource |
setRequiredMessage(java.lang.String requiredMessage)
The required message when a field that has been marked as
required is not filled in by the user. |
DataSource |
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.
|
DataSource |
setResultSetClass(java.lang.String resultSetClass)
Class for ResultSets used by this datasource.
|
DataSource |
setResultTreeClass(java.lang.String resultTreeClass)
Class for ResultTrees used by this datasource.
|
DataSource |
setSendExtraFields(java.lang.Boolean sendExtraFields)
Analogous to
dropExtraFields , for data sent to the
server. |
DataSource |
setSendParentNode(java.lang.Boolean sendParentNode)
Set this attribute if you need to send the dsRequest.parentNode to the server-side.
|
DataSource |
setServiceNamespace(java.lang.String serviceNamespace)
For an XML DataSource, URN of the WebService to use to invoke operations.
|
DataSource |
setShowLocalFieldsOnly(java.lang.Boolean showLocalFieldsOnly)
For a DataSource that inherits
fields from another DataSource
(via inheritsFrom ), indicates that only the fields listed in
this DataSource should be shown. |
DataSource |
setShowPrompt(java.lang.Boolean showPrompt)
Whether RPCRequests sent by this DataSource should enable
RPCRequest.showPrompt in order to block user interactions until the request completes. |
DataSource |
setSkipJSONValidation(SkipJSONValidation skipJSONValidation)
Sets what level of JSON validation will apply for this DataSource.
|
DataSource |
setStrictSQLFiltering(java.lang.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.
|
DataSource |
setTagName(java.lang.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.
|
DataSource |
setTitle(java.lang.String title)
User-visible name for this DataSource.
|
DataSource |
setTitleField(java.lang.String titleField)
Best field to use for a user-visible title for an individual record from this dataSource.
|
DataSource |
setTranslatePatternOperators(boolean translatePatternOperators)
Search operators like "matchesPattern" use patterns like "foo*txt" to match
text values. |
DataSource |
setTrimMilliseconds(java.lang.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 of
OperatorId s valid for a given FieldType. |
static void |
setTypeOperators(java.lang.String typeName,
OperatorId[] operators)
Set the list of valid
OperatorId s for a given FieldType. |
DataSource |
setUseFlatFields(java.lang.Boolean useFlatFields)
Like
DataBoundComponent.useFlatFields , but
applies to all DataBound components that bind to this DataSource. |
DataSource |
setUseHttpProxy(java.lang.Boolean useHttpProxy)
Like
OperationBinding.useHttpProxy , but serves as a
default for this DataSource that may be overridden by individual operationBindings. |
DataSource |
setUseLocalValidators(java.lang.Boolean useLocalValidators)
Whether to attempt validation on the client at all for this DataSource.
|
DataSource |
setUseOfflineStorage(java.lang.Boolean useOfflineStorage)
Whether we store server responses for this DataSource into
browser-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). |
DataSource |
setUseParentFieldOrder(java.lang.Boolean useParentFieldOrder)
For a DataSource that inherits
fields from another DataSource
(via inheritsFrom ), indicates that the parent's field order
should be used instead of the order of the fields as declared in this DataSource. |
DataSource |
setUseStrictJSON(java.lang.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.
|
DataSource |
setUseTestDataFetch(java.lang.Boolean useTestDataFetch)
When set, causes a
client-only or cacheAllData DataSource to create a second DataSource to perform
it's one-time fetch. |
DataSource |
setValidateRelatedRecords(java.lang.Boolean validateRelatedRecords)
If true, indicates that the Smart GWT Server should automatically apply a
ValidatorType of "hasRelatedRecord" to every field on this dataSource that has a foreignKey defined. |
DataSource |
setXmlNamespaces(XmlNamespaces xmlNamespaces)
Optional object declaring namespace prefixes for use in
OperationBinding.recordXPath and DataSourceField.valueXPath XPath
expressions.
|
Criteria |
splitCriteria(Criteria criteria,
java.lang.String[] fields)
Split a criteria apart based on
fields . |
Criteria |
splitCriteria(Criteria criteria,
java.lang.String[] fields,
java.lang.Boolean preserveAdvanced)
Split a criteria apart based on
fields . |
java.lang.Boolean |
supportsAdvancedCriteria()
Do fetch and filter operations on this dataSource support being passed
AdvancedCriteria ? |
java.lang.Boolean |
supportsDynamicTreeJoins()
This method returns true for dataSources that support both self-joins and
additionalOutputs . |
void |
supportsTextMatchStyle(TextMatchStyle textMatchStyle)
Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.
|
protected java.lang.Object |
transformRequest(DSRequest dsRequest)
For a dataSource using
client-side data integration ,
return the data that should be sent to the dataURL . |
protected void |
transformResponse(DSResponse dsResponse,
DSRequest dsRequest,
java.lang.Object data)
Modify the DSResponse object derived from the response returned from the
dataURL . |
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 returns
DSResponse.errors validation errors or a DSResponse.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 returns
DSResponse.errors validation errors or a DSResponse.status code of 0. |
static java.util.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 |
viewFile(Record data)
Display a file stored in a field of type:"binary" in a new browser window.
|
void |
viewFile(Record data,
java.lang.String fieldName) |
void |
viewFile(Record data,
java.lang.String fieldName,
DSRequest requestProperties)
Display a file stored in a field of type:"binary" in a new browser window.
|
java.lang.String |
xmlSerialize(com.google.gwt.core.client.JavaScriptObject data)
Serialize a JavaScript object as XML.
|
java.lang.String |
xmlSerialize(com.google.gwt.core.client.JavaScriptObject data,
SerializationContext flags)
Serialize a JavaScript object as XML.
|
java.lang.String |
xmlSerialize(java.util.Map data,
SerializationContext flags)
Serialize a JavaScript object as XML.
|
java.lang.String |
xmlSerialize(Record[] data,
SerializationContext flags)
Serialize a JavaScript object as XML.
|
java.lang.String |
xmlSerialize(Record data,
SerializationContext flags)
Serialize a JavaScript object as XML.
|
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
public DataSource()
public DataSource(com.google.gwt.core.client.JavaScriptObject jsObj)
public DataSource(java.lang.String dataURL)
public static DataSource getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
public com.google.gwt.core.client.JavaScriptObject create()
public DataSource setAddedAuditFields(DataSourceField... addedAuditFields) throws java.lang.IllegalStateException
fields
of the
Audit 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 declare auditDSConstructor
referring custom serverConstructor
, so that all
requests to add data to the Audit DataSource
could be intercepted allowing to make changes to the new records (obtained using DSRequest.getValues()
server-side API). In this particular use case values for the addedAuditFields
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); } }
addedAuditFields
- New addedAuditFields value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDataSourceField
public DataSourceField[] getAddedAuditFields()
fields
of the
Audit 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 declare auditDSConstructor
referring custom serverConstructor
, so that all
requests to add data to the Audit DataSource
could be intercepted allowing to make changes to the new records (obtained using DSRequest.getValues()
server-side API). In this particular use case values for the addedAuditFields
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); } }
DataSourceField
public DataSource setAllowAdvancedCriteria(java.lang.Boolean allowAdvancedCriteria)
AdvancedCriteria
on
fetch or filter type operations. This property may be set to false
to indicate that this dataSource does
not support advancedCriteria. See supportsAdvancedCriteria()
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 as allowAdvancedCriteria:false
, it
will be rejected.
Note : This is an advanced setting
allowAdvancedCriteria
- New allowAdvancedCriteria value. Default value is nullDataSource
instance, for chaining setter callsOperationBinding.setAllowAdvancedCriteria(java.lang.Boolean)
public java.lang.Boolean getAllowAdvancedCriteria()
AdvancedCriteria
on
fetch or filter type operations. This property may be set to false
to indicate that this dataSource does
not support advancedCriteria. See supportsAdvancedCriteria()
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 as allowAdvancedCriteria:false
, it
will be rejected.
OperationBinding.getAllowAdvancedCriteria()
public DataSource setAllowAggregation(java.lang.Boolean allowAggregation)
summaryFunction
mechanism. Of the built-in DataSource types
, SQL, Hibernate and JPA DataSources
allow aggregation, as do clientOnly
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
allowAggregation
- New allowAggregation value. Default value is nullDataSource
instance, for chaining setter callssetAllowAdvancedCriteria(java.lang.Boolean)
public java.lang.Boolean getAllowAggregation()
summaryFunction
mechanism. Of the built-in DataSource types
, SQL, Hibernate and JPA DataSources
allow aggregation, as do clientOnly
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
.
getAllowAdvancedCriteria()
public DataSource setAllowDynamicTreeJoins(java.lang.Boolean allowDynamicTreeJoins)
dynamic tree joins
. If you create a custom dataSource
that can support such joins, set this flag to true
Note : This is an advanced setting
allowDynamicTreeJoins
- New allowDynamicTreeJoins value. Default value is nullDataSource
instance, for chaining setter callspublic java.lang.Boolean getAllowDynamicTreeJoins()
dynamic tree joins
. If you create a custom dataSource
that can support such joins, set this flag to truepublic DataSource setAllowRelatedFieldsInCriteria(java.lang.Boolean allowRelatedFieldsInCriteria)
subquery
filtering overview
for details. Note, only AdvancedCriteria
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
allowRelatedFieldsInCriteria
- New allowRelatedFieldsInCriteria value. Default value is nullDataSource
instance, for chaining setter callssetAllowRelatedFieldsInCriteria(java.lang.Boolean)
public java.lang.Boolean getAllowRelatedFieldsInCriteria()
subquery
filtering overview
for details. Note, only AdvancedCriteria
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.
getAllowRelatedFieldsInCriteria()
public DataSource setArrayCriteriaForceExact(java.lang.Boolean arrayCriteriaForceExact) throws java.lang.IllegalStateException
simple 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 prevailing
textMatchStyle
is "substring" - as it would be if, for
example, you had issued a filterData()
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 your DSRequest
, or by
setting a default textMatchStyle
on the DataSource
(defaultTextMatchStyle
), or by specifying that the
textMatchStyle
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 prevailing
textMatchStyle
, set arrayCriteriaForceExact
to false. It is also possible to set this flag per-operationBinding and
per-DSRequest - see OperationBinding.arrayCriteriaForceExact
and
DSRequest.arrayCriteriaForceExact
If you want to switch this behavior off across the entire system, set the flag in your
server.properties
file:
arrayCriteriaForceExact: falseThis will only have an effect for server-side DataSources; if you want to change this flag globally for
clientOnly
dataSources, change the
default in the client-side DataSource
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.
arrayCriteriaForceExact
- New arrayCriteriaForceExact value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdServer DataSource Integration
public java.lang.Boolean getArrayCriteriaForceExact()
simple 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 prevailing
textMatchStyle
is "substring" - as it would be if, for
example, you had issued a filterData()
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 your DSRequest
, or by
setting a default textMatchStyle
on the DataSource
(defaultTextMatchStyle
), or by specifying that the
textMatchStyle
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 prevailing
textMatchStyle
, set arrayCriteriaForceExact
to false. It is also possible to set this flag per-operationBinding and
per-DSRequest - see OperationBinding.arrayCriteriaForceExact
and
DSRequest.arrayCriteriaForceExact
If you want to switch this behavior off across the entire system, set the flag in your
server.properties
file:
arrayCriteriaForceExact: falseThis will only have an effect for server-side DataSources; if you want to change this flag globally for
clientOnly
dataSources, change the
default in the client-side DataSource
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.
Server DataSource Integration
public DataSource setAutoCacheAllData(java.lang.Boolean autoCacheAllData) throws java.lang.IllegalStateException
cacheAllData
:true and a fetch
results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically
switch to cacheAllData:true
and prevent further server-trips for fetch requests. cacheAllData
is automatically enabled in either of these
conditions:
dataFetchMode
setting of "basic" or "local" or by an explicit fetchData request with those request properties
excluded. startRow:0
and endRow:totalRows
). autoCacheAllData
- New autoCacheAllData value. Default value is falseDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getAutoCacheAllData()
cacheAllData
:true and a fetch
results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically
switch to cacheAllData:true
and prevent further server-trips for fetch requests. cacheAllData
is automatically enabled in either of these
conditions:
dataFetchMode
setting of "basic" or "local" or by an explicit fetchData request with those request properties
excluded. startRow:0
and endRow:totalRows
). public DataSource setAutoConvertRelativeDates(java.lang.Boolean autoConvertRelativeDates) throws java.lang.IllegalStateException
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
setting datasources.autoConvertRelativeDates
which can be set to the
following values:
postDMI
- the default value described above preDMI
- relative
date values will be converted to absolute date values right away, so they will be already converted in DMI
disabled
- relative date values will not be automatically converted, so it must be done completely
manually or by calling the DSRequest.convertRelativeDates()
server-side API. DataSource.convertRelativeDates(Criterion)
server-side API.autoConvertRelativeDates
- New autoConvertRelativeDates value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getAutoConvertRelativeDates()
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
setting datasources.autoConvertRelativeDates
which can be set to the
following values:
postDMI
- the default value described above preDMI
- relative
date values will be converted to absolute date values right away, so they will be already converted in DMI
disabled
- relative date values will not be automatically converted, so it must be done completely
manually or by calling the DSRequest.convertRelativeDates()
server-side API. DataSource.convertRelativeDates(Criterion)
server-side API.public DataSource setAutoDeriveTitles(boolean autoDeriveTitles) throws java.lang.IllegalStateException
field.name
for
any field that does not have a field.title
and is not marked
hidden
:true, by calling the method getAutoTitle()
.autoDeriveTitles
- New autoDeriveTitles value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic boolean getAutoDeriveTitles()
field.name
for
any field that does not have a field.title
and is not marked
hidden
:true, by calling the method getAutoTitle()
.public DataSource setAutoDiscoverTree(boolean autoDiscoverTree) throws java.lang.IllegalStateException
Tree.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
and valueXPath
have been applied) and after transformResponse()
has been called.
If a DataSourceField is
declared with childrenProperty:true
, discoverTree()
will be invoked with settings.newChildrenProperty
set to the name of the field marked as the childrenField. Similarly, if the DataSource
has a titleField
it will be used as the settings.nameProperty
.
autoDiscoverTree
- New autoDiscoverTree value. Default value is falseDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic boolean getAutoDiscoverTree()
Tree.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
and valueXPath
have been applied) and after transformResponse()
has been called.
If a DataSourceField is
declared with childrenProperty:true
, discoverTree()
will be invoked with settings.newChildrenProperty
set to the name of the field marked as the childrenField. Similarly, if the DataSource
has a titleField
it will be used as the settings.nameProperty
.
public DataSource setCacheAcrossOperationIds(java.lang.Boolean cacheAcrossOperationIds) throws java.lang.IllegalStateException
cacheAllData
mode is enabled and a cacheAllOperationId
has been set, this flag affects whether
cached results are used for all "fetch" requests regardless of their DSRequest.operationId
, or are used only for "fetch" requests that use
the cacheAllOperationId
, allowing other requests to go to server normally. Default of true
means that the cacheAllOperationId
will be used to fetch all rows, but the resulting cache will be used for
all "fetch" operations regardless of the operationId
specified on the request.
Switching to "false"
effectively creates caching just for one specific operationId
- the cacheAllOperationId
-
while allowing all other requests to go to the server normally.
cacheAcrossOperationIds
- New cacheAcrossOperationIds value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getCacheAcrossOperationIds()
cacheAllData
mode is enabled and a cacheAllOperationId
has been set, this flag affects whether
cached results are used for all "fetch" requests regardless of their DSRequest.operationId
, or are used only for "fetch" requests that use
the cacheAllOperationId
, allowing other requests to go to server normally. Default of true
means that the cacheAllOperationId
will be used to fetch all rows, but the resulting cache will be used for
all "fetch" operations regardless of the operationId
specified on the request.
Switching to "false"
effectively creates caching just for one specific operationId
- the cacheAllOperationId
-
while allowing all other requests to go to the server normally.
public DataSource setCacheAllData(java.lang.Boolean cacheAllData)
clientOnly
DataSource, this DataSource will still
save changes normally, sending remote requests. You can manually set this attribute after initialization by calling
setCacheAllData()
; setting autoCacheAllData
:true causes a DataSource to automatically
switch to cacheAllData: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 with cacheAllData
: only one cache is created and is used for all fetch operations,
regardless of whether DSRequest.operationId
has been set.
However, "fetch" operationBindings used as a OperationBinding.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, set cacheAcrossOperationIds
.
If this method is called after the component has been drawn/initialized:
Call this method to switch cacheAllData on or off after initialization. Passing a shouldCache
value of false clears any existing client-side cache, cancels any outstanding requests for a full cache and issues any other pending requests normally.
cacheAllData
- New value for cacheAllData
. Default value is nullDataSource
instance, for chaining setter callspublic java.lang.Boolean getCacheAllData()
clientOnly
DataSource, this DataSource will still
save changes normally, sending remote requests. You can manually set this attribute after initialization by calling
setCacheAllData()
; setting autoCacheAllData
:true causes a DataSource to automatically
switch to cacheAllData: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 with cacheAllData
: only one cache is created and is used for all fetch operations,
regardless of whether DSRequest.operationId
has been set.
However, "fetch" operationBindings used as a OperationBinding.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, set cacheAcrossOperationIds
.
public DataSource setCacheAllOperationId(java.lang.String cacheAllOperationId) throws java.lang.IllegalStateException
DSRequest.operationId
to use for fetching data in case cacheAllData
is true. By default a standard fetch operation is
used (with no operationId
specified).cacheAllOperationId
- New cacheAllOperationId value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getCacheAllOperationId()
DSRequest.operationId
to use for fetching data in case cacheAllData
is true. By default a standard fetch operation is
used (with no operationId
specified).public DataSource setCacheMaxAge(int cacheMaxAge)
cacheMaxAge
- New cacheMaxAge value. Default value is 60DataSource
instance, for chaining setter callspublic int getCacheMaxAge()
public DataSource setCallbackParam(java.lang.String callbackParam) throws java.lang.IllegalStateException
dataTransport
:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to
call as part of the response.callbackParam
- New callbackParam value. Default value is "callback"DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdsetDataFormat(com.smartgwt.client.types.DSDataFormat)
,
setOperationBindings(com.smartgwt.client.data.OperationBinding...)
,
OperationBinding.setCallbackParam(java.lang.String)
,
Client-side Data Integration
,
Edit and Save Examplepublic java.lang.String getCallbackParam()
dataTransport
:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to
call as part of the response.getDataFormat()
,
getOperationBindings()
,
OperationBinding.getCallbackParam()
,
Client-side Data Integration
,
Edit and Save Examplepublic DataSource setCanAggregate(java.lang.Boolean canAggregate)
ServerSummaries
on
fetch or filter type operations. This property may be set to false
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 as canAggregate:false
, it will be rejected.
Note : This is an advanced setting
canAggregate
- New canAggregate value. Default value is nullDataSource
instance, for chaining setter callsServer Summaries
public java.lang.Boolean getCanAggregate()
ServerSummaries
on
fetch or filter type operations. This property may be set to false
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 as canAggregate:false
, it will be rejected.
Server Summaries
public DataSource setCanMultiSort(boolean canMultiSort) throws java.lang.IllegalStateException
canMultiSort
- New canMultiSort value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic boolean getCanMultiSort()
public DataSource setChildrenField(java.lang.String childrenField) throws java.lang.IllegalStateException
DataSourceField.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 of
childrenFieldName
elements:
<childrenFieldName name="firstChild" ...> <childrenFieldName name="secondChild" ...>If you want to return your data in this format, you will need to explicitly set
multiple
to false in the appropriate dataSource field definition.childrenField
- New childrenField value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDataSourceField.setChildrenProperty(java.lang.Boolean)
,
Relations
public java.lang.String getChildrenField()
DataSourceField.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 of
childrenFieldName
elements:
<childrenFieldName name="firstChild" ...> <childrenFieldName name="secondChild" ...>If you want to return your data in this format, you will need to explicitly set
multiple
to false in the appropriate dataSource field definition.DataSourceField.getChildrenProperty()
,
Relations
public DataSource setClientOnly(java.lang.Boolean clientOnly) throws java.lang.IllegalStateException
DSRequests
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 via addData()
, updateData()
and removeData()
, possibly in a transactional queue
. Note that getClientOnlyDataSource()
lets you easily obtain a
clientOnly
DataSource representing a subset of the data available from a normal DataSource.
See also
cacheAllData
- a cacheAllData
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
- see this 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.
clientOnly
- New clientOnly value. Default value is falseDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdClient Only DataSources
,
Local DataSource Examplepublic java.lang.Boolean getClientOnly()
DSRequests
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 via addData()
, updateData()
and removeData()
, possibly in a transactional queue
. Note that getClientOnlyDataSource()
lets you easily obtain a
clientOnly
DataSource representing a subset of the data available from a normal DataSource.
See also
cacheAllData
- a cacheAllData
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
- see this discussion
for other ways to populate a client-only DataSource with data.
Client Only DataSources
,
Local DataSource Examplepublic DataSource setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
ResultSet
cache should be dropped when the ResultSet.criteria
changes.
Note : This is an advanced setting
criteriaPolicy
- New criteriaPolicy value. Default value is "dropOnShortening"DataSource
instance, for chaining setter callscompareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)
public CriteriaPolicy getCriteriaPolicy()
ResultSet
cache should be dropped when the ResultSet.criteria
changes.compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)
public DataSource setDataField(java.lang.String dataField) throws java.lang.IllegalStateException
DataBoundComponent
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.
dataField
- New dataField value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDsSpecialFields overview and related methods
public java.lang.String getDataField()
DataBoundComponent
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.
DsSpecialFields overview and related methods
public DataSource setDataFormat(DSDataFormat dataFormat) throws java.lang.IllegalStateException
fetchData()
is called).dataFormat
- New dataFormat value. Default value is "iscServer"DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdServer DataSource Integration
,
JSON DataSource Example,
Simple JSON Examplepublic DSDataFormat getDataFormat()
fetchData()
is called).Server DataSource Integration
,
JSON DataSource Example,
Simple JSON Examplepublic DataSource setDataTransport(RPCTransport dataTransport) throws java.lang.IllegalStateException
defaultTransport
. This would typically only be set to enable
"scriptInclude" transport for contacting JSON
web services
hosted on servers other than the origin server. When using the "scriptInclude" transport, be sure to set callbackParam
or OperationBinding.callbackParam
to match the name of the
query parameter name expected by your JSON service provider.
dataTransport
- New dataTransport value. Default value is RPCManager.defaultTransportDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdRPCTransport
,
setCallbackParam(java.lang.String)
,
Client-side Data Integration
public RPCTransport getDataTransport()
defaultTransport
. This would typically only be set to enable
"scriptInclude" transport for contacting JSON
web services
hosted on servers other than the origin server. When using the "scriptInclude" transport, be sure to set callbackParam
or OperationBinding.callbackParam
to match the name of the
query parameter name expected by your JSON service provider.
RPCTransport
,
getCallbackParam()
,
Client-side Data Integration
public DataSource setDataURL(java.lang.String dataURL) throws java.lang.IllegalStateException
OperationBinding.dataURL
.
NOTE: Best practice is to use the same dataURL
for all DataSources which
fulfill DSRequests via the server-side RPCManager API. Otherwise, cross-DataSource
operation queuing
will not be possible.
RestConnector
dataURL
is also used to configure the address of the target REST server
for a RestConnector
DataSource. Typically this is done at the
operationBinding 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
of RestConnector
config can be Velocity templates, and dataURL
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-side
RestConnector
implementation
uses the dataURL
property to configure the address of the target REST
server, and that property also has meaning on the client, if you are using a
RestConnector
DataSource, you should specify the dataURL
of
the target REST server inside the serverConfig
blockdataURL
- New dataURL value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdURL
,
Client-side Data Integration
,
JSON DataSource Examplepublic java.lang.String getDataURL()
OperationBinding.dataURL
.
NOTE: Best practice is to use the same dataURL
for all DataSources which
fulfill DSRequests via the server-side RPCManager API. Otherwise, cross-DataSource
operation queuing
will not be possible.
RestConnector
dataURL
is also used to configure the address of the target REST server
for a RestConnector
DataSource. Typically this is done at the
operationBinding 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
of RestConnector
config can be Velocity templates, and dataURL
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-side
RestConnector
implementation
uses the dataURL
property to configure the address of the target REST
server, and that property also has meaning on the client, if you are using a
RestConnector
DataSource, you should specify the dataURL
of
the target REST server inside the serverConfig
blockURL
,
Client-side Data Integration
,
JSON DataSource Examplepublic DataSource setDeepCloneNonFieldValuesOnEdit(java.lang.Boolean deepCloneNonFieldValuesOnEdit)
DataBoundComponent
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 by dataPath
). 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 - see DataBoundComponent.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
deepCloneNonFieldValuesOnEdit
- New deepCloneNonFieldValuesOnEdit value. Default value is nullDataSource
instance, for chaining setter callsCanvas.setDataPath(java.lang.String)
,
FormItem.setDataPath(java.lang.String)
,
ValuesManager.setDeepCloneOnEdit(java.lang.Boolean)
public java.lang.Boolean getDeepCloneNonFieldValuesOnEdit()
DataBoundComponent
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 by dataPath
). 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 - see DataBoundComponent.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.
Canvas.getDataPath()
,
FormItem.getDataPath()
,
ValuesManager.getDeepCloneOnEdit()
public DataSource setDeepCloneOnEdit(java.lang.Boolean deepCloneOnEdit)
DataBoundComponent
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, see deepCloneNonFieldValuesOnEdit
. 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 - see DataBoundComponent.deepCloneOnEdit
and DataSourceField.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
deepCloneOnEdit
- New deepCloneOnEdit value. Default value is nullDataSource
instance, for chaining setter callsCanvas.setDataPath(java.lang.String)
,
FormItem.setDataPath(java.lang.String)
,
DataSourceField.setDeepCloneOnEdit(java.lang.Boolean)
,
ValuesManager.setDeepCloneOnEdit(java.lang.Boolean)
public java.lang.Boolean getDeepCloneOnEdit()
DataBoundComponent
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, see deepCloneNonFieldValuesOnEdit
. 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 - see DataBoundComponent.deepCloneOnEdit
and DataSourceField.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.
Canvas.getDataPath()
,
FormItem.getDataPath()
,
DataSourceField.getDeepCloneOnEdit()
,
ValuesManager.getDeepCloneOnEdit()
public DataSource setDefaultTextMatchStyle(TextMatchStyle defaultTextMatchStyle) throws java.lang.IllegalStateException
DSRequest
s that do not explicitly state a textMatchStyle
. Note, however, that DSRequests issued by
ListGrid
s and other components
will generally have a setting for textMatchStyle on the component itself (see ListGrid.autoFetchTextMatchStyle
, for example).defaultTextMatchStyle
- New defaultTextMatchStyle value. Default value is "exact"DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdServer DataSource Integration
,
JSON DataSource Example,
Simple JSON Examplepublic TextMatchStyle getDefaultTextMatchStyle()
DSRequest
s that do not explicitly state a textMatchStyle
. Note, however, that DSRequests issued by
ListGrid
s and other components
will generally have a setting for textMatchStyle on the component itself (see ListGrid.autoFetchTextMatchStyle
, for example).Server DataSource Integration
,
JSON DataSource Example,
Simple JSON Examplepublic DataSource setDescription(java.lang.String description) throws java.lang.IllegalStateException
OpenAPI
specification
generated by the framework. Markdown is a commonly used syntax, but you may also embed HTML content in a
CDATA tag.description
- New description value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getDescription()
OpenAPI
specification
generated by the framework. Markdown is a commonly used syntax, but you may also embed HTML content in a
CDATA tag.public DataSource setDescriptionField(java.lang.String descriptionField) throws java.lang.IllegalStateException
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.
descriptionField
- New descriptionField value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDsSpecialFields overview and related methods
public java.lang.String getDescriptionField()
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.
DsSpecialFields overview and related methods
public DataSource setDiscoverTreeSettings(DiscoverTreeSettings discoverTreeSettings) throws java.lang.IllegalStateException
autoDiscoverTree
is set to true for this DataSourcediscoverTreeSettings
- New discoverTreeSettings value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DiscoverTreeSettings getDiscoverTreeSettings()
autoDiscoverTree
is set to true for this DataSourcepublic DataSource setDropExtraFields(java.lang.Boolean dropExtraFields) throws java.lang.IllegalStateException
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 to true
enables) this filtering for
this DataSource only. This setting overrides the configuration in server.properties
. This setting can be overridden by ServerObject.dropExtraFields
.
dropExtraFields
- New dropExtraFields value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdClient-side Data Integration
public java.lang.Boolean getDropExtraFields()
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 to true
enables) this filtering for
this DataSource only. This setting overrides the configuration in server.properties
. This setting can be overridden by ServerObject.dropExtraFields
.
Client-side Data Integration
public DataSource setDropUnknownCriteria(java.lang.Boolean dropUnknownCriteria) throws java.lang.IllegalStateException
dropUnknownCriteria
- New dropUnknownCriteria value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getDropUnknownCriteria()
public DataSource setEnforceSecurityOnClient(java.lang.Boolean enforceSecurityOnClient) throws java.lang.IllegalStateException
DeclarativeSecurity
should be enforced on the client. This property only
applies to Client Only DataSources
. If property is unset for a
clientOnly DataSource it will be set true
automatically. Set this property to false
to
explicitly disable this feature for a clientOnly DataSource. Note that certain security features are not supported on the client like Velocity rules.
enforceSecurityOnClient
- New enforceSecurityOnClient value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDeclarative Security
public java.lang.Boolean getEnforceSecurityOnClient()
DeclarativeSecurity
should be enforced on the client. This property only
applies to Client Only DataSources
. If property is unset for a
clientOnly DataSource it will be set true
automatically. Set this property to false
to
explicitly disable this feature for a clientOnly DataSource. Note that certain security features are not supported on the client like Velocity rules.
Declarative Security
public DataSource setEnumConstantProperty(java.lang.String enumConstantProperty) throws java.lang.IllegalStateException
EnumTranslateStrategy
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
enumConstantProperty
- New enumConstantProperty value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DataSource setEnumOrdinalProperty(java.lang.String enumOrdinalProperty) throws java.lang.IllegalStateException
EnumTranslateStrategy
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
enumOrdinalProperty
- New enumOrdinalProperty value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DataSource setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy) throws java.lang.IllegalStateException
Note : This is an advanced setting
enumTranslateStrategy
- New enumTranslateStrategy value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DataSource setGlobalNamespaces(java.util.Map globalNamespaces)
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.
globalNamespaces
- New globalNamespaces value. Default value is ...DataSource
instance, for chaining setter callspublic java.util.Map getGlobalNamespaces()
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.
public DataSource setIconField(java.lang.String iconField) throws java.lang.IllegalStateException
type
:"image" as the field to use when rendering a
record as an image, for example, in a TileGrid
. 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
.
iconField
- New iconField value. Default value is see belowDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDsSpecialFields overview and related methods
public java.lang.String getIconField()
type
:"image" as the field to use when rendering a
record as an image, for example, in a TileGrid
. 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
.
DsSpecialFields overview and related methods
public DataSource setIgnoreTextMatchStyleCaseSensitive(java.lang.Boolean ignoreTextMatchStyleCaseSensitive) throws java.lang.IllegalStateException
ignoreTextMatchStyle
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 the TextMatchStyle
documentation
for a discussion of the nuances of case-sensitive matching.ignoreTextMatchStyleCaseSensitive
- New ignoreTextMatchStyleCaseSensitive value. Default value is falseDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getIgnoreTextMatchStyleCaseSensitive()
ignoreTextMatchStyle
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 the TextMatchStyle
documentation
for a discussion of the nuances of case-sensitive matching.public DataSource setImplicitCriteria(Criteria implicitCriteria)
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
and ResultSet.implicitCriteria
for more on these localized options.
Note that, while implicitCriteria
can be declared in a server DataSource file using Component 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).
implicitCriteria
- New implicitCriteria value. Default value is nullDataSource
instance, for chaining setter callspublic Criteria getImplicitCriteria()
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
and ResultSet.implicitCriteria
for more on these localized options.
Note that, while implicitCriteria
can be declared in a server DataSource file using Component 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).
public DataSource setInfoField(java.lang.String infoField) throws java.lang.IllegalStateException
DataBoundComponent
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.
infoField
- New infoField value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDsSpecialFields overview and related methods
public java.lang.String getInfoField()
DataBoundComponent
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.
DsSpecialFields overview and related methods
public DataSource setInheritsFrom(java.lang.String inheritsFrom) throws java.lang.IllegalStateException
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 set useParentFieldOrder
to instead use the parent's field order,
with new local fields appearing last. You can set showLocalFieldsOnly
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:
databound components
. XML Schema
or other metadata formats 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. inheritsFrom
- New inheritsFrom value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getInheritsFrom()
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 set useParentFieldOrder
to instead use the parent's field order,
with new local fields appearing last. You can set showLocalFieldsOnly
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:
databound components
. XML Schema
or other metadata formats 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. public DataSource setIsSampleDS(java.lang.Boolean isSampleDS) throws java.lang.IllegalStateException
isSampleDS
- New isSampleDS value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getIsSampleDS()
public DataSource setJsonPrefix(java.lang.String jsonPrefix) throws java.lang.IllegalStateException
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 use dataFormat:"custom"
instead and
explicitly parse the prefix out as part of transformResponse()
.
Note : This is an advanced setting
jsonPrefix
- New jsonPrefix value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdOperationBinding.setDataFormat(com.smartgwt.client.types.DSDataFormat)
,
OperationBinding.setDataTransport(com.smartgwt.client.types.RPCTransport)
public java.lang.String getJsonPrefix()
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 use dataFormat:"custom"
instead and
explicitly parse the prefix out as part of transformResponse()
.
OperationBinding.getDataFormat()
,
OperationBinding.getDataTransport()
public DataSource setJsonSuffix(java.lang.String jsonSuffix) throws java.lang.IllegalStateException
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
jsonSuffix
- New jsonSuffix value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdOperationBinding.setDataFormat(com.smartgwt.client.types.DSDataFormat)
,
OperationBinding.setDataTransport(com.smartgwt.client.types.RPCTransport)
public java.lang.String getJsonSuffix()
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.
OperationBinding.getDataFormat()
,
OperationBinding.getDataTransport()
public DataSource setMockDataCriteria(Criteria mockDataCriteria) throws java.lang.IllegalStateException
mockMode
is enabled, criteria to use in an initial "fetch"
DSRequest to retrieve sample data.mockDataCriteria
- New mockDataCriteria value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Criteria getMockDataCriteria()
mockMode
is enabled, criteria to use in an initial "fetch"
DSRequest to retrieve sample data.public DataSource setMockDataRows(java.lang.Integer mockDataRows) throws java.lang.IllegalStateException
mockMode
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.mockDataRows
- New mockDataRows value. Default value is 75DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Integer getMockDataRows()
mockMode
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.public DataSource setMockMode(java.lang.Boolean mockMode)
clientOnly
DataSource, never writing changes back to the server.
mockMode
has no effect on MockDataSource
or a clientOnly
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 on mockDataRows
. 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 to load()
, or if loaded with a screen or project, by passing settings to RPCManager.loadScreen()
or the server-side Project.load() API.
mockMode
- New mockMode value. Default value is nullDataSource
instance, for chaining setter callspublic java.lang.Boolean getMockMode()
clientOnly
DataSource, never writing changes back to the server.
mockMode
has no effect on MockDataSource
or a clientOnly
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 on mockDataRows
. 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 to load()
, or if loaded with a screen or project, by passing settings to RPCManager.loadScreen()
or the server-side Project.load() API.
public DataSource setOperationBindings(OperationBinding... operationBindings) throws java.lang.IllegalStateException
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
and OperationBinding.customHQL
).
See the @see Java
Integration samples.
For DataSources bound to WSDL-described web services using
serviceNamespace
, OperationBindings are used to bind
each DataSource
operationType
to an
operation
of a WSDL-described
web 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 an
editable 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.
operationBindings
- New operationBindings value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdOperationBinding
public OperationBinding[] getOperationBindings()
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
and OperationBinding.customHQL
).
See the @see Java
Integration samples.
For DataSources bound to WSDL-described web services using
serviceNamespace
, OperationBindings are used to bind
each DataSource
operationType
to an
operation
of a WSDL-described
web 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 an
editable 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.
OperationBinding
public DataSource setPatternEscapeChar(java.lang.String patternEscapeChar) throws java.lang.IllegalStateException
pattern operators
search operator
, character that escapes the patternSingleWildcard
or patternMultiWildcard
if placed before it, so that it is
treated as a literal character.patternEscapeChar
- New patternEscapeChar value. Default value is "\"DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getPatternEscapeChar()
pattern operators
search operator
, character that escapes the patternSingleWildcard
or patternMultiWildcard
if placed before it, so that it is
treated as a literal character.public DataSource setPatternMultiWildcard(java.lang.String patternMultiWildcard) throws java.lang.IllegalStateException
pattern operators
search operator
, character that matches a series of one or more characters. Pass multiple strings to provide multiple alternative wildcards.
patternMultiWildcard
- New patternMultiWildcard value. Default value is "*"DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getPatternMultiWildcard()
pattern operators
search operator
, character that matches a series of one or more characters. Pass multiple strings to provide multiple alternative wildcards.
public DataSource setPatternMultiWildcard(java.lang.String... patternMultiWildcard) throws java.lang.IllegalStateException
pattern operators
search operator
, character that matches a series of one or more characters. Pass multiple strings to provide multiple alternative wildcards.
patternMultiWildcard
- New patternMultiWildcard value. Default value is "*"DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String[] getPatternMultiWildcardAsStringArray()
pattern operators
search operator
, character that matches a series of one or more characters. Pass multiple strings to provide multiple alternative wildcards.
public DataSource setPatternSingleWildcard(java.lang.String patternSingleWildcard) throws java.lang.IllegalStateException
pattern operators
search operator
, character that matches any single character. Pass multiple strings to provide multiple alternative wildcards.
patternSingleWildcard
- New patternSingleWildcard value. Default value is ["?","%"]DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getPatternSingleWildcard()
pattern operators
search operator
, character that matches any single character. Pass multiple strings to provide multiple alternative wildcards.
public DataSource setPatternSingleWildcard(java.lang.String... patternSingleWildcard) throws java.lang.IllegalStateException
pattern operators
search operator
, character that matches any single character. Pass multiple strings to provide multiple alternative wildcards.
patternSingleWildcard
- New patternSingleWildcard value. Default value is ["?","%"]DataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String[] getPatternSingleWildcardAsStringArray()
pattern operators
search operator
, character that matches any single character. Pass multiple strings to provide multiple alternative wildcards.
public DataSource setPluralTitle(java.lang.String pluralTitle) throws java.lang.IllegalStateException
For example, for the supplyItem DataSource, "Supply Items".
Defaults to dataSource.title
+ "s".
pluralTitle
- New pluralTitle value. Default value is dataSource.IDDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getPluralTitle()
For example, for the supplyItem DataSource, "Supply Items".
Defaults to dataSource.title
+ "s".
public DataSource setPreventHTTPCaching(java.lang.Boolean preventHTTPCaching) throws java.lang.IllegalStateException
Note that this does not disable caching at higher levels in the framework, for example, the caching
performed by ResultSet
.
preventHTTPCaching
- New preventHTTPCaching value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getPreventHTTPCaching()
Note that this does not disable caching at higher levels in the framework, for example, the caching
performed by ResultSet
.
public DataSource setProgressiveLoading(java.lang.Boolean progressiveLoading)
ResultSet
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 (see endGap
). 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 individual DSRequest
. You can
also specify progressiveLoading
on DataBoundComponents
and certain types of
FormItem
- SelectItem
and
ComboBoxItem
.
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.
progressiveLoading
- New progressiveLoading value. Default value is nullDataSource
instance, for chaining setter callsOperationBinding.progressiveLoading
,
DataSource.progressiveLoadingThreshold
,
DataSource.lookAhead
,
DataSource.endGap
,
Progressive Loading
public java.lang.Boolean getProgressiveLoading()
ResultSet
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 (see endGap
). 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 individual DSRequest
. You can
also specify progressiveLoading
on DataBoundComponents
and certain types of
FormItem
- SelectItem
and
ComboBoxItem
.
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.
OperationBinding.progressiveLoading
,
DataSource.progressiveLoadingThreshold
,
DataSource.lookAhead
,
DataSource.endGap
,
Progressive Loading
public DataSource setQualifyColumnNames(java.lang.Boolean qualifyColumnNames) throws java.lang.IllegalStateException
serverType
"sql", determines whether
we qualify column names with table names in any SQL we generate. This property can be overridden on specific
operationBindings.qualifyColumnNames
- New qualifyColumnNames value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdOperationBinding.qualifyColumnNames
public java.lang.Boolean getQualifyColumnNames()
serverType
"sql", determines whether
we qualify column names with table names in any SQL we generate. This property can be overridden on specific
operationBindings.OperationBinding.qualifyColumnNames
public DataSource setRecordName(java.lang.String recordName) throws java.lang.IllegalStateException
OperationBinding.recordName
.recordName
- New recordName value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdClient-side Data Integration
public java.lang.String getRecordName()
OperationBinding.recordName
.Client-side Data Integration
public DataSource setRecordXPath(java.lang.String recordXPath) throws java.lang.IllegalStateException
OperationBinding.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 on RestConnector
dataSourcesrecordXPath
- New recordXPath value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdXPathExpression
,
Client-side Data Integration
,
XML DataSource Example,
JSON XPath Binding Examplepublic java.lang.String getRecordXPath()
OperationBinding.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 on RestConnector
dataSourcesXPathExpression
,
Client-side Data Integration
,
XML DataSource Example,
JSON XPath Binding Examplepublic DataSource setRequestProperties(DSRequest requestProperties)
DSRequest
s made by this DataSource. This
must be set before any DSRequest
s are issued and before any component is bound to the
DataSource. These properties are applied before transformRequest()
is called.
requestProperties
- New requestProperties value. Default value is nullDataSource
instance, for chaining setter callsDSRequest
,
OperationBinding.setRequestProperties(com.smartgwt.client.data.DSRequest)
,
Server DataSource Integration
public DSRequest getRequestProperties()
DSRequest
s made by this DataSource. This
must be set before any DSRequest
s are issued and before any component is bound to the
DataSource. These properties are applied before transformRequest()
is called.
DSRequest
,
OperationBinding.getRequestProperties()
,
Server DataSource Integration
public DataSource setRequiredMessage(java.lang.String requiredMessage)
required
is not filled in by the user. Note that DataSourceField.requiredMessage
wins over this setting if both are set.
requiredMessage
- New requiredMessage value. Default value is nullDataSource
instance, for chaining setter callsHTMLString
,
Form Titles
public java.lang.String getRequiredMessage()
required
is not filled in by the user. Note that DataSourceField.requiredMessage
wins over this setting if both are set.
HTMLString
,
Form Titles
public DataSource setResultBatchSize(int resultBatchSize)
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
resultBatchSize
- New resultBatchSize value. Default value is 150DataSource
instance, for chaining setter callspublic int getResultBatchSize()
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.
public DataSource setResultSetClass(java.lang.String resultSetClass) throws java.lang.IllegalStateException
ResultSet
.
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
resultSetClass
- New resultSetClass value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getResultSetClass()
ResultSet
.
This can be set to a custom subclass of ResultSet that, for example, hangs onto to extra information necessary for integration with web services.
public DataSource setResultTreeClass(java.lang.String resultTreeClass) throws java.lang.IllegalStateException
ResultTree
. 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
resultTreeClass
- New resultTreeClass value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getResultTreeClass()
ResultTree
. This can be set to a custom subclass of ResultTree that, for example, hangs on to extra information necessary for integration with web services.
public java.lang.String getSchemaNamespace() throws java.lang.IllegalStateException
WebService.getSchema()
.
Note : This method should be called only after the underlying component has been created.
java.lang.IllegalStateException
- if the underlying component has not yet been created.Client-side Data Integration
public DataSource setSendExtraFields(java.lang.Boolean sendExtraFields) throws java.lang.IllegalStateException
dropExtraFields
, 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 to transformRequest()
and ultimately sent to the server.sendExtraFields
- New sendExtraFields value. Default value is trueDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdClient-side Data Integration
public java.lang.Boolean getSendExtraFields()
dropExtraFields
, 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 to transformRequest()
and ultimately sent to the server.Client-side Data Integration
public DataSource setSendParentNode(java.lang.Boolean sendParentNode)
Note : This is an advanced setting
sendParentNode
- New sendParentNode value. Default value is falseDataSource
instance, for chaining setter callspublic java.lang.Boolean getSendParentNode()
public DataSource setServiceNamespace(java.lang.String serviceNamespace) throws java.lang.IllegalStateException
Having loaded a WebService using XMLTools.loadWSDL()
, setting serviceNamespace
combined with
specifying operationBindings
that set OperationBinding.wsOperation
will cause a DataSource to invoke
web service operations to fulfill DataSource requests (DSRequests
).
Setting serviceNamespace
also defaults dataURL
to
the service's location, dataFormat
to "xml" and dataProtocol
to "soap".
serviceNamespace
- New serviceNamespace value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdClient-side Data Integration
public java.lang.String getServiceNamespace()
Having loaded a WebService using XMLTools.loadWSDL()
, setting serviceNamespace
combined with
specifying operationBindings
that set OperationBinding.wsOperation
will cause a DataSource to invoke
web service operations to fulfill DataSource requests (DSRequests
).
Setting serviceNamespace
also defaults dataURL
to
the service's location, dataFormat
to "xml" and dataProtocol
to "soap".
Client-side Data Integration
public DataSource setShowLocalFieldsOnly(java.lang.Boolean showLocalFieldsOnly) throws java.lang.IllegalStateException
fields
from another DataSource
(via inheritsFrom
), indicates that only the fields listed in
this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".showLocalFieldsOnly
- New showLocalFieldsOnly value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getShowLocalFieldsOnly()
fields
from another DataSource
(via inheritsFrom
), indicates that only the fields listed in
this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".public DataSource setShowPrompt(java.lang.Boolean showPrompt)
RPCRequest.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 a requestProperties
argument allowing showPrompt
to be set to false for a specific request.
showPrompt
- New showPrompt value. Default value is trueDataSource
instance, for chaining setter callspublic java.lang.Boolean getShowPrompt()
RPCRequest.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 a requestProperties
argument allowing showPrompt
to be set to false for a specific request.
public DataSource setSkipJSONValidation(SkipJSONValidation skipJSONValidation)
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.
skipJSONValidation
- New skipJSONValidation value. Default value is "none"DataSource
instance, for chaining setter callspublic SkipJSONValidation getSkipJSONValidation()
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.
public DataSource setStrictSQLFiltering(java.lang.Boolean strictSQLFiltering) throws java.lang.IllegalStateException
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 specifying
strictSQLFiltering
directly as a property on the AdvancedCriteria
.
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
strictSQLFiltering
- New strictSQLFiltering value. Default value is falseDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getStrictSQLFiltering()
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 specifying
strictSQLFiltering
directly as a property on the AdvancedCriteria
.
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.
public DataSource setTagName(java.lang.String tagName) throws java.lang.IllegalStateException
dataSource.ID
will be used.
Note : This is an advanced setting
tagName
- New tagName value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdClient-side Data Integration
public java.lang.String getTagName()
dataSource.ID
will be used.Client-side Data Integration
public DataSource setTitle(java.lang.String title)
For example, for the supplyItem DataSource, "Supply Item".
If is unset,
getAutoTitle()
method will be used with dataSource.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".
title
- New title value. Default value is dataSource.IDDataSource
instance, for chaining setter callspublic java.lang.String getTitle()
For example, for the supplyItem DataSource, "Supply Item".
If is unset,
getAutoTitle()
method will be used with dataSource.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".
public DataSource setTitleField(java.lang.String titleField) throws java.lang.IllegalStateException
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.
titleField
- New titleField value. Default value is see belowDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdDsSpecialFields overview and related methods
public java.lang.String getTitleField()
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.
DsSpecialFields overview and related methods
public DataSource setTranslatePatternOperators(boolean translatePatternOperators) throws java.lang.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:
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.
translatePatternOperators
- New translatePatternOperators value. Default value is falseDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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:
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.
public DataSource setTrimMilliseconds(java.lang.Boolean trimMilliseconds) throws java.lang.IllegalStateException
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.
trimMilliseconds
- New trimMilliseconds value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getTrimMilliseconds()
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.
public DataSource setUseFlatFields(java.lang.Boolean useFlatFields) throws java.lang.IllegalStateException
DataBoundComponent.useFlatFields
, but
applies to all DataBound components that bind to this DataSource.useFlatFields
- New useFlatFields value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getUseFlatFields()
DataBoundComponent.useFlatFields
, but
applies to all DataBound components that bind to this DataSource.public DataSource setUseHttpProxy(java.lang.Boolean useHttpProxy) throws java.lang.IllegalStateException
OperationBinding.useHttpProxy
, but serves as a
default for this DataSource that may be overridden by individual operationBindings.useHttpProxy
- New useHttpProxy value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdClient-side Data Integration
public java.lang.Boolean getUseHttpProxy()
OperationBinding.useHttpProxy
, but serves as a
default for this DataSource that may be overridden by individual operationBindings.Client-side Data Integration
public DataSource setUseLocalValidators(java.lang.Boolean useLocalValidators)
Disabling client-side validation entirely is a good way to test server-side validation.
Note : This is an advanced setting
useLocalValidators
- New useLocalValidators value. Default value is nullDataSource
instance, for chaining setter callsValidation overview and related methods
public java.lang.Boolean getUseLocalValidators()
Disabling client-side validation entirely is a good way to test server-side validation.
Validation overview and related methods
public DataSource setUseOfflineStorage(java.lang.Boolean useOfflineStorage)
browser-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.useOfflineStorage
- New useOfflineStorage value. Default value is nullDataSource
instance, for chaining setter callspublic java.lang.Boolean getUseOfflineStorage()
browser-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.public DataSource setUseParentFieldOrder(java.lang.Boolean useParentFieldOrder) throws java.lang.IllegalStateException
fields
from another DataSource
(via inheritsFrom
), 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.useParentFieldOrder
- New useParentFieldOrder value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getUseParentFieldOrder()
fields
from another DataSource
(via inheritsFrom
), 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.public DataSource setUseStrictJSON(java.lang.Boolean useStrictJSON) throws java.lang.IllegalStateException
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. See allowIE9Leak
for more on this.
useStrictJSON
- New useStrictJSON value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getUseStrictJSON()
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. See allowIE9Leak
for more on this.
public DataSource setUseTestDataFetch(java.lang.Boolean useTestDataFetch)
client-only
or cacheAllData
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.useTestDataFetch
- New useTestDataFetch value. Default value is nullDataSource
instance, for chaining setter callspublic java.lang.Boolean getUseTestDataFetch()
client-only
or cacheAllData
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.public DataSource setValidateRelatedRecords(java.lang.Boolean validateRelatedRecords) throws java.lang.IllegalStateException
ValidatorType
of "hasRelatedRecord" to every field on this dataSource that has a foreignKey
defined.validateRelatedRecords
- New validateRelatedRecords value. Default value is nullDataSource
instance, for chaining setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getValidateRelatedRecords()
ValidatorType
of "hasRelatedRecord" to every field on this dataSource that has a foreignKey
defined.public void addData(Record newRecord)
If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See the
error handling overview
for more information.
NOTE: do not use repeated calls to addData()
to provide the initial
dataset for a clientOnly
DataSource, instead, provide
initial data via cacheData
. Using addData()
for
subsequent,
incremental updates from sources like user editing is fine.
addData()
can be passed a List
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-in
SQLDataSource
has support for multi-add out-of-the-box. If you are using
SQLDataSource
(ie, your dataSource's serverType
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 the DataSource
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 single INSERT
with
multiple VALUES
, 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
and OperationBinding
levels, and it can also be globally configured in server.properties
. See
the multiInsertStrategy
documentation for
details.
cache 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 whenrequestValuesPlusSequences
cacheSyncStrategy
is in forceautomatic audit
of batch-inserted records only
when
both of the above conditions are true, and the sql.multi.insert.allowAudit
flag is set to true
in your server.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 the canSyncCache
flag to
false
on your OperationBinding
; alternatively, you can switch
to cacheSyncStrategy
"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.
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 the valuesClause
applicable
to the first valueSet. The same restriction applies to $values references in
things like custom SQL expressions
InputStream
objects to valueSets before the
SQL subsystem sees them (for example, by using a DMI
).
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 withnewRecord
- new recordOperations Overview
public void addData(Record newRecord, DSCallback callback)
addData(com.smartgwt.client.data.Record)
public void addData(Record newRecord, DSCallback callback, DSRequest requestProperties)
If the operation fails, the callback will not be invoked unless
DSRequest.willHandleError
is true. See the
error handling overview
for more information.
NOTE: do not use repeated calls to addData()
to provide the initial
dataset for a clientOnly
DataSource, instead, provide
initial data via cacheData
. Using addData()
for
subsequent,
incremental updates from sources like user editing is fine.
addData()
can be passed a List
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-in
SQLDataSource
has support for multi-add out-of-the-box. If you are using
SQLDataSource
(ie, your dataSource's serverType
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 the DataSource
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 single INSERT
with
multiple VALUES
, 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
and OperationBinding
levels, and it can also be globally configured in server.properties
. See
the multiInsertStrategy
documentation for
details.
cache 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 whenrequestValuesPlusSequences
cacheSyncStrategy
is in forceautomatic audit
of batch-inserted records only
when
both of the above conditions are true, and the sql.multi.insert.allowAudit
flag is set to true
in your server.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 the canSyncCache
flag to
false
on your OperationBinding
; alternatively, you can switch
to cacheSyncStrategy
"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.
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 the valuesClause
applicable
to the first valueSet. The same restriction applies to $values references in
things like custom SQL expressions
InputStream
objects to valueSets before the
SQL subsystem sees them (for example, by using a DMI
).
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 withnewRecord
- new recordcallback
- Callback to invoke on completion.requestProperties
- additional properties to set on the DSRequest that will be issuedOperations Overview
public DSRequest cloneDSRequest(DSRequest dsRequest)
DSRequest
. The request's data
, if any, is shallow copied in the cloned request. The callback
property of the given request is not copied into the cloned
request.
dsRequest
- the DSRequest to clone.cloneDSResponse(com.smartgwt.client.data.DSResponse)
public DSResponse cloneDSResponse(DSResponse dsResponse)
DSResponse
. 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's data
, if any, is shallow copied in
the cloned response.dsResponse
- the DSResponse to clone.cloneDSRequest(com.smartgwt.client.data.DSRequest)
public int compareCriteria(Criteria newCriteria, Criteria oldCriteria)
Comparisons between AdvancedCriteria
are made via recursively calling Operator.compareCriteria()
for all criteria involved.
For simple
Criteria
, by default (CriteriaPolicy
:"dropOnShortening"), returns:
For (CriteriaPolicy
:"dropOnChange"), returns:
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.newCriteria
- new filter criteriaoldCriteria
- previous filter criteriaCriteriaPolicy
public int compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties)
public int compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties, java.lang.String policy)
Comparisons between AdvancedCriteria
are made via recursively calling Operator.compareCriteria()
for all criteria involved.
For simple
Criteria
, by default (CriteriaPolicy
:"dropOnShortening"), returns:
For (CriteriaPolicy
:"dropOnChange"), returns:
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.newCriteria
- new filter criteriaoldCriteria
- previous filter criteriarequestProperties
- dataSource request propertiespolicy
- overrides CriteriaPolicy
CriteriaPolicy
public int compareDates(java.util.Date date1, java.util.Date date2, java.lang.String fieldName)
type
"datetime" or "date". In the former case, the dates are
compared using DateUtil.compareDates()
; in the latter case, or if
the supplied fieldName is null or unknown to this DataSource, the dates are compared using DateUtil.compareLogicalDates()
.date1
- First date in comparisondate2
- Second date in comparisonfieldName
- The name of the field for which the comparison is being run.
See FieldName
public AdvancedCriteria convertDataSourceCriteria(Criteria criteria)
convertCriteria()
in that it
makes use of the dataSource as schema to help in the conversion. For example, this method is able to honor DataSourceField.ignoreTextMatchStyle
and use the
dataSource's defaultTextMatchStyle
rather than
assuming "substring"criteria
- simple criteriapublic AdvancedCriteria convertDataSourceCriteria(Criteria criteria, TextMatchStyle textMatchStyle)
convertCriteria()
in that it
makes use of the dataSource as schema to help in the conversion. For example, this method is able to honor DataSourceField.ignoreTextMatchStyle
and use the
dataSource's defaultTextMatchStyle
rather than
assuming "substring"criteria
- simple criteriatextMatchStyle
- default style of matching text. Defaults to the dataSource's
defaultTextMatchStylepublic Criteria convertRelativeDates(Criteria criteria)
criteria
- criteria to convertpublic Criteria convertRelativeDates(Criteria criteria, java.lang.String timezoneOffset)
public Criteria convertRelativeDates(Criteria criteria, java.lang.String timezoneOffset, java.lang.Integer firstDayOfWeek)
public Criteria convertRelativeDates(Criteria criteria, java.lang.String timezoneOffset, java.lang.Integer firstDayOfWeek, java.util.Date baseDate)
criteria
- criteria to converttimezoneOffset
- optional timezone offset. Defaults to the current timezonefirstDayOfWeek
- first day of the week (zero is Sunday). Defaults to DateChooser.firstDayOfWeek
baseDate
- base value for relative conversion - defaults to nowpublic Record[] copyRecords(Record... records)
copyRecord()
for each item in the array.records
- The array of Record objects to be copied.public void createAlias(java.lang.String alias)
alias
- The alias assigned to this DataSource.public com.google.gwt.event.shared.HandlerRegistration addDataChangedHandler(DataChangedHandler handler)
Notification method fired when a DataSource operation such as an add
, remove
or update
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.
addDataChangedHandler
in interface HasDataChangedHandlers
handler
- the dataChanged handlerHandlerRegistration
used to remove this handlerpublic void downloadFile(Record data)
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.
data
- Record to download. Only required to have a value for the primary key field.public void downloadFile(Record data, java.lang.String fieldName)
public void downloadFile(Record data, java.lang.String fieldName, DSRequest requestProperties)
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.
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.
See FieldName
requestProperties
- Additional properties to set on the DSRequest that will be issued.public boolean evaluateCriterion(Record record, Criterion criterion)
Typically called by the condition
function of a custom Operator
to
evaluate sub-criteria
.
record
- record to evaluatecriterion
- criterion to useCriterion
Advanced Filtering
public void execute(DSRequest dsRequest)
This method is typically used by a DataSource whose dataProtocol
is set to DSProtocol.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 the transformRequest()
override and calling execute() on the DSRequest
at a later time.
dsRequest
- the DSRequest to execute.public void exportData()
OperationBinding.exportResults
or DSRequest.exportResults
and for more information.Operations Overview
public void exportData(Criteria criteria)
exportData()
public void exportData(Criteria criteria, DSRequest requestProperties)
exportData()
public void exportData(Criteria criteria, DSRequest requestProperties, DSCallback callback)
OperationBinding.exportResults
or DSRequest.exportResults
and for more information.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 where DSRequest.exportToClient
is
explicitly set to false, because file downloads do not provide ordinary Smart GWT
callbacksOperations Overview
public void fetchData(Criteria criteria)
public void fetchData(Criteria criteria, DSCallback callback)
public void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
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, see dataProtocol:"custom"
.
In contrast to ListGrid.fetchData()
, which creates a ResultSet
to manage
the returned data, calling dataSource.fetchData()
provides the returned
data in the callback as a
RecordList or simple Array of Record objects. Calling
dataSource.fetchData()
does not automatically update any visual components or
caches: code in the callback passed to fetchData()
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 calling
myGrid.fetchData()
, which creates a ResultSet
, 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 the
optionDataSource
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 provide
filtered valueMaps
, will
automatically reflect updates
to the DataSource made via
other components, and can be re-used with multiple visual components.
See also getClientOnlyDataSource()
and cacheAllData
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 of ListGridField
(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, and
inheritsFrom
for sharing field definitions across multiple
DataSources.criteria
- search criteriacallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedOperations Overview
public void fetchRecord(java.lang.Object pkValue)
primary key
.
This simply calls fetchData()
after creating Criteria
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.
pkValue
- value for the field marked primaryKey
:true in this DataSource (or the first field so marked if there is more than one)public void fetchRecord(java.lang.Object pkValue, DSCallback callback)
fetchRecord(java.lang.Object)
public void fetchRecord(java.lang.Object pkValue, DSCallback callback, DSRequest requestProperties)
primary key
.
This simply calls fetchData()
after creating Criteria
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.
pkValue
- value for the field marked primaryKey
: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 issuedpublic boolean fieldMatchesFilter(java.lang.Object fieldValue, java.lang.Object filterValue)
DSRequest.textMatchStyle
in the passed
requestProperties
, regardless of the actual field type fieldValue
- field value to be comparedfilterValue
- filter value to be comparedpublic boolean fieldMatchesFilter(java.lang.Object fieldValue, java.lang.Object filterValue, DSRequest requestProperties)
DSRequest.textMatchStyle
in the passed
requestProperties
, regardless of the actual field type fieldValue
- field value to be comparedfilterValue
- filter value to be comparedrequestProperties
- optional dataSource request propertiespublic void filterData()
This is identical to fetchData()
except that DSRequest.textMatchStyle
is set to "substring" to cause case
insensitive substring matching (if the server respects this setting).
Operations Overview
public void filterData(Criteria criteria)
filterData()
public void filterData(Criteria criteria, DSCallback callback)
filterData()
public void filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
This is identical to fetchData()
except that DSRequest.textMatchStyle
is set to "substring" to cause case
insensitive substring matching (if the server respects this setting).
criteria
- search criteriacallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedOperations Overview
public java.lang.String formatFieldValue(DataSourceField field, java.lang.Object value)
SimpleType
derived from the field definition.
Note that if DataSourceField.format
is defined for a date,
time or numeric-based value, or DataSourceField.dateFormatter
or DataSourceField.timeFormatter
is defined for a date or time-based value, that format is given priority and used to
format the value rather than the SimpleType
.
field
- name of the field to use to format valuevalue
- raw value to be formattedpublic RelationPath getAllPathsToRelation(java.lang.String targetDS)
targetDS
- The DataSource at the relationship's other end.public RelationPath getAllPathsToRelation(DataSource targetDS)
targetDS
- The DataSource at the relationship's other end.public void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback)
inheritsFrom
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 and hasAllData()
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.
criteria
- The criteria for the clientOnly DScallback
- The callback to fire passing the clientOnly DSpublic void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties)
public void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties, DataSource dataSourceProperties)
inheritsFrom
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 and hasAllData()
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.
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 DSprotected DSResponse getClientOnlyResponse(DSRequest request, Record... serverData)
clientOnly
or cacheAllData
DataSource. The default implementation will use
cacheData
to provide an appropriate response, by using client-side filtering
for a "fetch" request, and by modifying the
cacheData
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.
request
- DataSource request to respond toserverData
- for cacheAllData DataSources, the data from the local cachepublic RelationPath getDefaultPathToRelation(java.lang.String targetDS)
getShortestPathToRelation()
.targetDS
- The DataSource at the relationship's other end.public RelationPath getDefaultPathToRelation(DataSource targetDS)
getShortestPathToRelation()
.targetDS
- The DataSource at the relationship's other end.public java.lang.Object getDisplayValue(java.lang.String fieldName, java.lang.Object value)
DataSourceField.valueMap
for the field and return the display value for the fieldfieldName
- name of the field to retrieve a value for.
See FieldName
value
- data value for the fieldpublic java.lang.String getFetchDataURL(Criteria criteria)
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.
criteria
- Criteria to be sent to server.public java.lang.String getFetchDataURL(Criteria criteria, DSRequest requestProperties)
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.
criteria
- Criteria to be sent to server.requestProperties
- additional properties to set on the DSRequest that will be issuedpublic DataSourceField getField(java.lang.String fieldName)
public Criteria getFieldCriterion(Criteria criterion, java.lang.String fieldName)
criterion
- the criteria to searchfieldName
- the fieldName to find criteria for.
See FieldName
public OperatorId[] getFieldDefaultOperator(java.lang.String field)
OperatorId
for this field. By default, if field.defaultOperator
is set, returns that value, otherwise
returns the data-type default from SimpleType.defaultOperator
.
field
- Field (or field name) to obtain the default operator forAdvanced Filtering
public OperatorId[] getFieldDefaultOperator(DataSourceField field)
OperatorId
for this field. By default, if field.defaultOperator
is set, returns that value, otherwise
returns the data-type default from SimpleType.defaultOperator
.
field
- Field (or field name) to obtain the default operator forAdvanced Filtering
public DataSourceField getFieldForDataPath(java.lang.String dataPath)
dataPath
- dataPath of the field to retrievepublic java.lang.String[] getFieldNames(boolean excludeHidden)
excludeHidden
- If true, returns only those fields that are not marked as hiddenpublic void getFile(FileSpec fileSpec, GetFileCallback callback)
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. The data
parameter is either a String with the
contents of the file, or null to indicate error (such as file not found). You can
examine dsResponse.status
and
dsResponse.data
for additional
information about any error.FileSource Operations
public java.lang.String getFileURL(Record data)
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()
and viewFile()
.
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.
data
- Record containing at least the primary key field.public java.lang.String getFileURL(Record data, java.lang.String fieldName)
public java.lang.String getFileURL(Record data, java.lang.String fieldName, DSRequest requestProperties)
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()
and viewFile()
.
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.
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.
See FieldName
requestProperties
- Additional properties to set on the DSRequest that will be issued.public void getFileVersion(FileSpec fileSpec, java.util.Date version, GetFileVersionCallback callback)
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 the listFileVersions()
API.callback
- Callback executed with the results. The data
parameter is either a String with the
contents of the file, or null to indicate error (such as file not found). You can
examine dsResponse.status
and
dsResponse.data
for additional
information about any error.FileSource Operations
public void getLegalChildTags()
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.
public DataSourceField getPrimaryKeyField()
getPrimaryKeyFields()
public java.lang.String getPrimaryKeyFieldName()
getPrimaryKeyFieldNames()
public java.lang.String[] getPrimaryKeyFieldNames()
primaryKey
fields.getPrimaryKeyFields()
public Record getPrimaryKeyFields()
primaryKey
fields as a map of
fieldName to field.getPrimaryKeyField()
,
getPrimaryKeyFieldNames()
public RelationPath getShortestPathToRelation(java.lang.String targetDS)
targetDS
- The DataSource at the relationship's other end.public RelationPath getShortestPathToRelation(DataSource targetDS)
targetDS
- The DataSource at the relationship's other end.public OperatorId[] getTypeOperators()
OperatorId
s available on this DataSource for the given FieldType
. If setTypeOperators()
has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of
valid operators for the FieldType
as specified by SimpleType.validOperators
, otherwise, the system-wide set of
valid operators for the type as registered via addSearchOperator()
.
Advanced Filtering
public OperatorId[] getTypeOperators(FieldType typeName)
OperatorId
s available on this DataSource for the given FieldType
. If setTypeOperators()
has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of
valid operators for the FieldType
as specified by SimpleType.validOperators
, otherwise, the system-wide set of
valid operators for the type as registered via addSearchOperator()
.
typeName
- Defaults to "text" if not passed.Advanced Filtering
public OperatorId[] getTypeOperators(java.lang.String typeName)
OperatorId
s available on this DataSource for the given FieldType
. If setTypeOperators()
has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of
valid operators for the FieldType
as specified by SimpleType.validOperators
, otherwise, the system-wide set of
valid operators for the type as registered via addSearchOperator()
.
typeName
- Defaults to "text" if not passed.Advanced Filtering
public void setHandleErrorCallback(HandleErrorCallback callback)
STATUS_SUCCESS
. You can use this hook to do
DataSource-specific error handling. Unless you call ErrorEvent.cancel()
,
HandleErrorCallback.handleError()
will be called by
Smart GWT right after this method completes.callback
- HandleErrorCallback the callback to set.HandleErrorCallback.handleError(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest)
public com.google.gwt.event.shared.HandlerRegistration addHandleErrorHandler(HandleErrorHandler 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 call ErrorEvent.cancel()
,
HandleErrorCallback.handleError()
will be called by
Smart GWT right after this method completes.
addHandleErrorHandler
in interface HasHandleErrorHandlers
handler
- the handleError handlerHandlerRegistration
used to remove this handlerpublic java.lang.Boolean hasAllData()
cacheAllData
is true, has all the data been retrieved
to the client?public void hasCustomTypeOperators(java.lang.String typeName)
setTypeOperators()
.typeName
- Advanced Filtering
public void hasCustomTypeOperators(FieldType typeName)
setTypeOperators()
.typeName
- Advanced Filtering
public void hasFile(FileSpec fileSpec, HasFileCallback callback)
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. The data
parameter is a boolean indicating
whether the file is present. You can examine dsResponse.status
and dsResponse.data
for additional information about any error.FileSource Operations
public void hasFileVersion(FileSpec fileSpec, java.util.Date version, HasFileCallback callback)
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 for
hasFileVersion
to return true. Note, you can obtain the list of versions for a given
file with the listFileVersions()
API.callback
- Callback executed with the results. The data
parameter is a boolean
indicating whether the file version is present. You can examine dsResponse.status
and dsResponse.data
for additional information about any
error.FileSource Operations
public void invalidateCache()
cacheAllData
or clientOnly
, discard the current client-side cache data.notify
is passed, cause all data 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 with DSResponse.invalidateCache
set.public void invalidateCache(boolean notify)
cacheAllData
or clientOnly
, discard the current client-side cache data.notify
is passed, cause all data 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 with DSResponse.invalidateCache
set.notify
- Should data objects associated with this dataSource have their cache invalidated?public boolean isCalculated(DataSourceField field)
DataSourceField.formula
or other similar attributes? This method will return true for fields with the following attributes:
DataSourceField.formula
DataSourceField.template
DataSourceField.customSelectExpression
calculated:true
.field
- Field or fieldNamepublic boolean isCalculated(java.lang.String field)
DataSourceField.formula
or other similar attributes? This method will return true for fields with the following attributes:
DataSourceField.formula
DataSourceField.template
DataSourceField.customSelectExpression
calculated:true
.field
- Field or fieldNamepublic void listFiles(Criteria criteria, DSCallback callback)
automatic file versioning
is switched on for the dataSource, the resulting list contains only the most recent version
of each file.criteria
- Criteria to apply. References to fileName
, fileType
and
fileFormat
fields will be translated to the native field names configured for
this DataSource.callback
- Callback executed with the results. The data
parameter is either an array of records,
or null to indicate an error. The records will have the fileName
, fileType
, fileFormat
, fileLastModified
, and
fileVersion
fields populated, but
not the fileContents
field. (You
can use getFile()
to get the fileContents
).
You can examine dsResponse.status
and
dsResponse.data
for additional
information about any error.listFileVersions(com.smartgwt.client.data.FileSpec, com.smartgwt.client.data.DSCallback)
,
FileSource Operations
public void listFileVersions(FileSpec fileSpec, DSCallback callback)
fileVersionField
, this API will return an errorfileSpec
- 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. The data
parameter is either an array of records,
or null to indicate an error. The records will have the fileName
, fileType
, fileFormat
, fileLastModified
and
fileVersion
fields populated, but
not the fileContents
field. (You
can use getFileVersion()
to get the
fileContents
). You can examine dsResponse.status
and dsResponse.data
for additional information about any error.FileSource Operations
public void performCustomOperation(java.lang.String operationId)
OperationBinding.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 via updateData()
- this will cause cache sync
to work correctly.
In particular:
DSRequest.operationId
is the correct way to do this) queuing
. However, a custom operation is appropriate for genuine "batch" updates, as opposed to just a
number of ordinary updates by primaryKey - see OperationBinding.allowMultiUpdate
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 in Velocity
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 declaring OperationBinding.operationType
"custom" in your .ds.xml
file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.
operationId
- the operation IDOperations Overview
public void performCustomOperation(java.lang.String operationId, Record data)
performCustomOperation(java.lang.String)
public void performCustomOperation(java.lang.String operationId, Record data, DSCallback callback)
performCustomOperation(java.lang.String)
public void performCustomOperation(java.lang.String operationId, Record data, DSCallback callback, DSRequest requestProperties)
OperationBinding.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 via updateData()
- this will cause cache sync
to work correctly.
In particular:
DSRequest.operationId
is the correct way to do this) queuing
. However, a custom operation is appropriate for genuine "batch" updates, as opposed to just a
number of ordinary updates by primaryKey - see OperationBinding.allowMultiUpdate
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 in Velocity
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 declaring OperationBinding.operationType
"custom" in your .ds.xml
file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.
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 issuedOperations Overview
public void processResponse(java.lang.String requestId, DSResponse dsResponse)
dataProtocol:"clientCustom"
.
requestId
parameter should be dsRequest.requestId as found on the dsRequest
passed to transformRequest()
.
You must provide a response for both error and non-error cases. For an error case, a sufficient response is:
{ status : -1 }
requestId
- requestId attribute from the associated dataSource request objectdsResponse
- Configuration for the dsResponsepublic boolean recordsAreEqual(java.lang.Object record1, java.lang.Object record2)
record1
- record to be compared against.record2
- record to be compared.public java.lang.String recordsAsText(Record[] records)
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.
records
- records to convertpublic java.lang.String recordsAsText(Record[] records, TextExportSettings settings)
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.
records
- records to convertsettings
- settings for the exportpublic Record[] recordsFromText(java.lang.String text)
If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.
text
- records as CSV/TSV (separator can be specified)public Record[] recordsFromText(java.lang.String text, TextImportSettings settings)
If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.
text
- records as CSV/TSV (separator can be specified)settings
- optional settings for the importpublic void removeData(Record data)
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 the error handling overview
for
more information.
data
- primary key values of record to delete, (or complete record)Operations Overview
public void removeData(Record data, DSCallback callback)
public void removeData(Record data, DSCallback callback, DSRequest requestProperties)
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 the error handling overview
for
more information.
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 issuedOperations Overview
public void removeFile(FileSpec fileSpec)
automatic file versioning
is switched on for the dataSource, all versions of the file are removed (to remove an
individual file version, use the removeFileVersion()
API).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.FileSource Operations
public void removeFile(java.lang.String fileSpec)
automatic file versioning
is switched on for the dataSource, all versions of the file are removed (to remove an
individual file version, use the removeFileVersion()
API).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.FileSource Operations
public void removeFile(FileSpec fileSpec, DSCallback callback)
automatic file versioning
is switched on for the dataSource, all versions of the file are removed (to remove an
individual file version, use the removeFileVersion()
API).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. The data
parameter is either an array of
records represening the removed file(s), or null to indicate an error. The records will
have their fileName
fields and fileType
fields populated, but not the
fileContents
field. You can examine dsResponse.status
and dsResponse.data
for additional information about any
error.FileSource Operations
public void removeFileVersion(FileSpec fileSpec, java.util.Date version)
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 the listFileVersions()
API.FileSource Operations
public void removeFileVersion(FileSpec fileSpec, java.util.Date version, DSCallback callback)
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 the listFileVersions()
API.callback
- Callback executed with the results. The data
parameter is either a record representing the
removed file version, or null to indicate an error. The record will have its fileName
, fileType
, fileFormat
, fileLastModified
, and
fileVersion
fields populated, but
not the fileContents
field.
You can examine dsResponse.status
and
dsResponse.data
for additional
information about any error.FileSource Operations
public void renameFile(FileSpec oldFileSpec, FileSpec newFileSpec)
automatic file versioning
is switched on for the dataSource, all versions of the file are renamed.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.FileSource Operations
public void renameFile(FileSpec oldFileSpec, FileSpec newFileSpec, DSCallback callback)
automatic file versioning
is switched on for the dataSource, all versions of the file are renamed.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. The data
parameter is either an array of
records represening the renamed file(s), or null to indicate an error. The records will
have their fileName
fields and fileType
fields populated, but not the
fileContents
field. You can examine dsResponse.status
and dsResponse.data
for additional information about any
error.FileSource Operations
public void saveFile(FileSpec fileSpec, java.lang.String contents)
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 fileFileSource Operations
public void saveFile(FileSpec fileSpec, java.lang.String contents, DSCallback callback)
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. The data
parameter is either a record represening
the new file, or null to indicate an error. The record will have its fileName
,
fileType
and fileFormat
field populated, but not the fileContents
field. You can examine dsResponse.status
and dsResponse.data
for additional information about any error.FileSource Operations
public void setTypeOperators(FieldType typeName, OperatorId[] operators)
OperatorId
s valid for a given FieldType.typeName
- operators
- available OperatorsAdvanced Filtering
public Criteria splitCriteria(Criteria criteria, java.lang.String[] fields)
fields
. 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 be flat
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 every criterion 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 available textMatchStyle
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.
criteria
- criteria to be split. May be modified if criteria is extracted.fields
- list of fields to extract from criteriapublic Criteria splitCriteria(Criteria criteria, java.lang.String[] fields, java.lang.Boolean preserveAdvanced)
fields
. 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 be flat
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 every criterion 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 available textMatchStyle
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.
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.public java.lang.Boolean supportsAdvancedCriteria()
AdvancedCriteria
? For a DataSource to support being passed AdvancedCriteria, it must be
clientOnly:true
or cacheAllData: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
and JPA
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.
public java.lang.Boolean supportsDynamicTreeJoins()
additionalOutputs
. 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; neither clientOnly
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 the allowDynamicTreeJoins
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-referencing
additionalOutputs
to improve efficiency, and possibly performance.
additionalOutputs
and self-joins, otherwise falsepublic void supportsTextMatchStyle(TextMatchStyle textMatchStyle)
textMatchStyle
- textMatchStyle to check. If passed a null value, assume an exact match is being requested.protected java.lang.Object transformRequest(DSRequest dsRequest)
client-side data integration
,
return the data that should be sent to the dataURL
.
By default, HTTP requests sent to non-Smart GWT servers do not include DSRequest
metadata such as DSRequest.startRow
, endRow
,
and oldValues
. Only the core
datasource protocol data
is sent, such as the criteria
passed to fetchData()
or the updated values submitted by
form.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 by xmlSerialize()
.
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():
Criteria
object into the custom query language of a web
service
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 calls processResponse()
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).processResponse()
synchronously from within transformRequest
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 a
clientOnly dataSource
with a custom
getClientOnlyResponse()
implementation instead.
A transformRequest
override may also be used to set the DSRequest.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.
dsRequest
- the DSRequest being processedprotected void transformResponse(DSResponse dsResponse, DSRequest dsRequest, java.lang.Object data)
dataURL
.
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 the dataFormat
setting:
dataFormat:"xml"
: either the
recordXPath
or
recordName
is used to select the XML elements
that represent DataSource records. The selected XML elements are passed to
recordsFromXML()
, which transforms the XML elements to typed
JavaScript data using the DataSource as a schema.
dataFormat:"json"
: the
recordXPath
, if specified, is used to select
records from the returned JSON data via XMLTools.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), and DSResponse.startRow
is assumed
to be zero,
with endRow
and totalRows
both set to dsResponse.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:
startRow
,
endRow
and totalRows
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"));
DSResponse.status
to recognized ISC error values
based on
service-specific errors, in order to trigger standard ISC error handling. For
example, setting dsResponse.status
to
STATUS_VALIDATION_ERROR
and filling in
DSResponse.errors
in order to cause validation errors to be shown
in
forms and grids.
DSRequest.oldValues
to create cache update data (whether
this is
appropriate is application-specific), or setting
DSResponse.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 either grid.fetchData()
DataSource.handleError()
or by
setting
willHandleError
.
dsResponse
- default DSResponse derived from the response datadsRequest
- DSRequest object that initiated this requestdata
- XML document or JSON objects returned by the web servicepublic void updateCaches(DSResponse dsResponse)
ResultSet
or ResultTree
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 have operationType
"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 via fetchData()
) you can still call updateCaches()
with
DSResponses of type "update". Typically DataSource operations that manipulate data operate on a single record at a time,
but if you explicitly set the response.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 with itemId
23, and you wanted to update the
unitCost
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 calls
updateCaches()
for you - see that method's documentation for details.
NOTE:: if
updateCaches
is called for a clientOnly
DataSource, it will update cacheData
synchronously in addition
to notifying all cache managers as normal.
If a DataSource has cacheAllData
set and a full cache has been obtained, calling
updateCaches
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.
dsResponse
- the provided DSResponse must minimally have dataSource, operationType, and data setpublic void updateCaches(DSResponse dsResponse, DSRequest dsRequest)
ResultSet
or ResultTree
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 have operationType
"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 via fetchData()
) you can still call updateCaches()
with
DSResponses of type "update". Typically DataSource operations that manipulate data operate on a single record at a time,
but if you explicitly set the response.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 with itemId
23, and you wanted to update the
unitCost
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 calls
updateCaches()
for you - see that method's documentation for details.
NOTE:: if
updateCaches
is called for a clientOnly
DataSource, it will update cacheData
synchronously in addition
to notifying all cache managers as normal.
If a DataSource has cacheAllData
set and a full cache has been obtained, calling
updateCaches
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.
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 DSResponsepublic void updateData(Record updatedRecord)
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 the error handling overview
for
more information.
updatedRecord
- updated recordOperations Overview
public void updateData(Record updatedRecord, DSCallback callback)
public void updateData(Record updatedRecord, DSCallback callback, DSRequest requestProperties)
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 the error handling overview
for
more information.
updatedRecord
- updated recordcallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedOperations Overview
public void validateData(Record values)
DSResponse.errors
validation errors or a DSResponse.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()
).
values
- record values to validateOperations Overview
public void validateData(Record values, DSCallback callback)
public void validateData(Record values, DSCallback callback, DSRequest requestProperties)
DSResponse.errors
validation errors or a DSResponse.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()
).
values
- record values to validatecallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedOperations Overview
public void viewFile(Record data)
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.
data
- Record to download. Only required to have a value for the primary key field.public void viewFile(Record data, java.lang.String fieldName)
public void viewFile(Record data, java.lang.String fieldName, DSRequest requestProperties)
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.
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.
See FieldName
requestProperties
- Additional properties to set on the DSRequest that will be issued.public static boolean canFlattenCriteria(AdvancedCriteria criteria)
flattenCriteria()
on the passed
criteria would produce logically equivalent criteria.criteria
- the AdvancedCriteria to check for flatnesspublic static Criteria combineCriteria(Criteria criteria1, Criteria criteria2)
criteria1
- first criteria objectcriteria2
- second criteria objectpublic static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator)
public static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator, TextMatchStyle textMatchStyle)
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"public static AdvancedCriteria convertCriteria(Criteria criteria)
criteria
- simple criteriapublic static AdvancedCriteria convertCriteria(Criteria criteria, TextMatchStyle textMatchStyle)
criteria
- simple criteriatextMatchStyle
- default style of matching text. Defaults to "substring"public static Criteria copyCriteria(Criteria criteria)
criteria
- criteria to copypublic static AdvancedCriteria flattenCriteria(AdvancedCriteria criteria)
isFlatCriteria()
.
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 use
canFlattenCriteria()
to detect whether an
AdvancedCriteria is going
to be changed by flattenCriteria()
.
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.
criteria
- the AdvancedCriteria to flattenpublic static java.lang.String getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource)
criteria
- Criteria to convert to a readable stringdataSource
- DataSource to provide definitions of operatorspublic static java.lang.String getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource, CriteriaOutputSettings criteriaOutputSettings)
criteria
- Criteria to convert to a readable stringdataSource
- DataSource to provide definitions of operatorscriteriaOutputSettings
- optional configuration settings for the outputpublic static java.lang.String getAggregationDescription(AdvancedCriterionSubquery subquery, DataSource dataSource)
DSRequest.groupBy
and DSRequest.summaryFunctions
.subquery
- Subquery with aggregation to convert to a readable stringdataSource
- DataSource to provide field propertiespublic static DataSource getDataSource(java.lang.String ID)
public static java.lang.String getLoaderURL()
loaderURL
public static java.lang.String[] getSortBy(SortSpecifier[] sortSpecifiers)
SortSpecifier
s, return a simple list of Strings in the format
expected by DSRequest.sortBy
.sortSpecifiers
- The list of specifiers to return in sortBy formatDSRequest.sortBy
public static SortSpecifier[] getSortSpecifiers(java.lang.String[] sortBy)
SortSpecifier
s, given an array of Strings in the format expected by
DSRequest.sortBy
.sortBy
- A list of sortBy strings in the format expected by DSRequest.sortBy
SortSpecifier
s equivalent to the passed in string arraypublic static void hasCustomTypeOperators(java.lang.String typeName, DataSource ds)
setTypeOperators()
.typeName
- ds
- Advanced Filtering
public static boolean isFlatCriteria(AdvancedCriteria criteria)
Criterion
, where none of the subcriteria
use logical
operators
, hence have no subcriteria of their own criteria
- the AdvancedCriteria to check for flatnesspublic static void load(java.lang.String dsID, Function callback)
dsID
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 a MockDataSource
, the forceReload
parameter will be
required to force the "real" dataSource to be loaded.
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completespublic static void load(java.lang.String dsID, Function callback, boolean forceReload)
dsID
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 a MockDataSource
, the forceReload
parameter will be
required to force the "real" dataSource to be loaded.
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loadedpublic static void loadWithParents(java.lang.String dsID, Function callback)
load()
that will also automatically load any DataSources
that the requested DataSources inherit from (via inheritsFrom
). If the parent DataSource is already loaded, calling loadWithParents
will not
automatically reload them unless the forceReload parameter is passed.
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completespublic static void loadWithParents(java.lang.String dsID, Function callback, boolean forceReload)
load()
that will also automatically load any DataSources
that the requested DataSources inherit from (via inheritsFrom
). If the parent DataSource is already loaded, calling loadWithParents
will not
automatically reload them unless the forceReload parameter is passed.
dsID
- DataSource ID or Array of DataSource IDscallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loadedpublic static FileSpec makeFileSpec(java.lang.String path)
FileSpec
.path
- The path to convert, e.g. "employees.ds.xml"public static void setLoaderURL(java.lang.String url)
load()
method. Note, one reason you may wish to modify the loader URL is to
include a Cross-Site Request Forgery (CSRF) token, as described here
url
- The new loaderURLpublic static void setTypeOperators(java.lang.String typeName, OperatorId[] operators)
OperatorId
s for a given FieldType.typeName
- operators
- available OperatorsAdvanced Filtering
public static java.util.Map[] verifyDataSourcePair(DataSource live, DataSource mock)
INFO level messages are logged when any of the following conditions are discovered:
live
- DataSource to compare using 'live' rulesmock
- DataSource to compare using 'mock' rulespublic static void setDefaultProperties(DataSource dataSourceProperties)
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.
dataSourceProperties
- properties that should be used as new defaults when instances of this class are createdSGWTProperties
protected void registerID(java.lang.String id, boolean skipUniqueJSIdentifierCheck)
registerID
in class BaseClass
public DataSource setID(java.lang.String id)
public void setAddGlobalId(java.lang.Boolean addGlobalId) throws java.lang.IllegalStateException
Note : This is an advanced setting
addGlobalId
- addGlobalId Default value is truejava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getAddGlobalId()
public DataSource setDataProtocol(DSProtocol dataProtocol) throws java.lang.IllegalStateException
dataProtocol
}dataProtocol
- dataProtocol Default value is nullDataSource
instance, for chaining
setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setDefaultParams(java.util.Map defaultParams)
defaultParams
- the default paramspublic java.util.Map getDefaultParams()
public DSProtocol getDataProtocol()
dataProtocol
}public static DataSource get(java.lang.String ID)
DataSource.getDataSource
: Lookup a DataSource by
ID.ID
- DataSource IDpublic static DataSource get(java.lang.String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)
DataSource.getDataSource
: Lookup a DataSource by
ID.ID
- DataSource IDrequestTransformer
- the request transformer. Pass null to use the default transformresponseTransformer
- the response transformer. Pass null to use the default transformpublic static DataSource getDataSource(java.lang.String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)
transformRequest(DSRequest)
and transformResponse(DSResponse, DSRequest, Object)
when
instantiating a DataSource on the client. However when obtaining a DataSource instance from the server using this API, transformRequest(DSRequest)
and transformResponse(DSResponse, DSRequest, Object)
cannot be overridden and so the requestTransformer and responseTransformer parameters can be passed instead.ID
- DataSource IDrequestTransformer
- the request transformer. Pass null to use the default transformresponseTransformer
- the response transformer. Pass null to use the default transformprotected boolean useOfflineResponse(DSRequest dsRequest, DSResponse dsResponse)
offlineTimestamp
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
dsRequest
- The dsRequest objectdsResponse
- The corresponding dsResponse object returned from offline cachepublic com.google.gwt.core.client.JavaScriptObject getJsObj()
public void setInheritsFrom(DataSource inheritsFrom) throws java.lang.IllegalStateException
useParentFieldOrder
to instead use the
parent's field order, with new local fields appearing last.showLocalFieldsOnly
to
have all non-local fields hidden.inheritsFrom
XMLTools.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.inheritsFrom
- the datasource to inherit fromjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setFields(DataSourceField... fields) throws java.lang.IllegalStateException
Each DataSource field can have type, user-visible title, validators, and other metadata attached.
fields
- fields Default value is nulljava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void addField(DataSourceField field) throws java.lang.IllegalStateException
field
- the datasource fieldjava.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DataSourceField[] getFields()
Each DataSource field can have type, user-visible title, validators, and other metadata attached.
public java.lang.String xmlSerialize(com.google.gwt.core.client.JavaScriptObject data)
The JavaScript Object passed to xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
element named after the tagName
(or ID
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.
data
- data to be serializedpublic java.lang.String xmlSerialize(com.google.gwt.core.client.JavaScriptObject data, SerializationContext flags)
The JavaScript Object passed to xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
element named after the tagName
(or ID
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.
data
- data to be serializedflags
- options for the serialization enginepublic java.lang.String xmlSerialize(Record data, SerializationContext flags)
The JavaScript Object passed to xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
element named after the tagName
(or ID
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.
data
- data to be serializedflags
- options for the serialization enginepublic java.lang.String xmlSerialize(Record[] data, SerializationContext flags)
The JavaScript Object passed to xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
element named after the tagName
(or ID
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.
data
- data to be serializedflags
- options for the serialization enginepublic java.lang.String xmlSerialize(java.util.Map data, SerializationContext flags)
The JavaScript Object passed to xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
element named after the tagName
(or ID
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.
data
- data to be serializedflags
- options for the serialization enginepublic Record[] recordsFromXML(java.lang.Object elements)
recordsFromXML() will return a List of DataSource Records. The value for each field is extracted from the XML according
to the rules described under valueXPath
.
elements
- XML elements to transform, eg, the result of a call to XMLTools.selectNodes(Object, String)
public Record copyRecord(Record record)
record
- The record to be copied.public java.lang.String[] getFieldNames()
public static void load(java.lang.String[] dsID, Function callback, boolean forceReload)
To force reloading of DataSources that have already been loaded, pass
true
in the forceReload parameter.
dsID
- Array of DataSource IDscallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loadedpublic static void load(java.lang.String[] dsID, Function callback, DSLoadSettings settings)
dsID
- Array of DataSource IDscallback
- Callback to fire after DataSource loading completessettings
- DSLoadSettings
to control load featurespublic static void loadWithParents(java.lang.String[] dsID, Function callback, boolean forceReload)
DataSource.load
that will also automatically load any
DataSources that the requested DataSources inherit from
(via DataSource.inheritsFrom
)
If the parent DataSource is already loaded, calling loadWithParents will not automatically reload them unless the forceReload parameter is passed.
dsID
- DataSource IDcallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loadedpublic static void loadWithParents(java.lang.String[] dsID, Function callback, DSLoadSettings settings)
DataSource.load
that will also automatically load any
DataSources that the requested DataSources inherit from
(via DataSource.inheritsFrom
).dsID
- DataSource IDcallback
- Callback to fire after DataSource loading completessettings
- DSLoadSettings
to control load featurespublic void exportClientData(java.lang.Object[] data, DSRequest requestProperties)
If you do not specify an
operationId
in the requestProperties
you pass to this method, it behaves
exactly the same as the exportClientDataStatic
static classMethod.
If you do specify an operationId
, the framework expects your DataSource to configure an OperationBinding
of operationType
DSOperationType.CLIENTEXPORT
, with the same
operationId
. The framework will then send the exportClientData
request via the ordinary
DSRequest
mechanism, which allows you to use normal framework features in the client data export. For example,
you could add a DMI declaration
to your operationBinding
, which would allow you to write
server-side code that intervenes in the export process - for instance, by calling the getExportObject()
API to
do something special with the export document, like saving it to a database table or sending it to an email list.
When you use the specific operationId
version of this API, both the SmartClient Server and server-side DataSources are required.
To export unformatted data, see exportData()
which does not include client-side formatters, but requires both the
Smart GWT server and the presence of server-side DataSources.
data
- Records to export, similar to ListGrid.datarequestProperties
- Request properties for the exportpublic static void exportClientDataStatic(java.lang.Object[] data, DSRequest requestProperties)
Requires the SmartClient server, but
does not rely on any server-side DataSources. If you need to intervene in the export process server-side - for example, if
you need to do something not directly supported with the exported object, such as attach it to an email - use the
exportClientData
instance method with an appropriate
OperationBinding
, as described in the method documentation.
To export unformatted data,
see exportData()
, which does not include client-side formatters, but requires both
the SmartClient server and the presence of server-side DataSources.
Note that field
displayFormat
is honored for "date" and "datetime" fields when exporting
direct to Excel; see the displayFormat docs for details.
NOTE: The "Static" in this method name merely indicates that it is the static version of this method, as opposed to the
similar instance method exportClientData
. Restrictions of the Java language
itself prevent us from giving the instance method and the static method the same name.
public DataSource setXmlNamespaces(XmlNamespaces xmlNamespaces) throws java.lang.IllegalStateException
xmlNamespaces
- xml namespacesDataSource
instance, for chaining
setter callsjava.lang.IllegalStateException
- this property cannot be changed after the underlying
component has been createdpublic OperatorId[] getFieldOperators(java.lang.String fieldName)
getTypeOperators(com.smartgwt.client.types.FieldType)
.fieldName
- the field name to obtain operators forpublic OperatorId[] getFieldOperators(DataSourceField field)
getTypeOperators(com.smartgwt.client.types.FieldType)
.field
- the field to obtain operators forpublic Record[] applyFilter(Record[] records, Criteria criteria, DSRequest requestProperties)
Criteria
.
By default:
records
- (Record[]) the list of rowscriteria
- (Criteria) the filter criteriarequestProperties
- (DSRequest Properties) optional dataSource request propertiespublic Record[] applyFilter(Record[] records, Criteria criteria)
Criteria
.
By default:
records
- (Record[]) the list of rowscriteria
- (Criteria) the filter criteriapublic void setCacheData(Record... cacheData)
cacheAllData
or client-only DataSource, a set of
records to use as a dataset, specified as an Array of JavaScript Objects representing records.
cacheData
- Array of records to apply as the client-side cache. Default value is nullpublic Record[] getCacheData()
cacheAllData
or client-only DataSource, a set of
records to use as a dataset, specified as an Array of JavaScript Objects representing records.cacheData
, or may have been fetched from the server for dataSources
with cacheAllData
set to true.public void setTestData(Record... cacheData)
cacheData
. See this discussion
for ways to populate a client-only DataSource with test
data.
If this method is called after the component has been drawn/initialized:
Call this method to set the data in the client-side test-data after initialization. setCacheData()
should be called instead and setTestData() is deprecated and will eventually be removed.
testData
- Array of records to apply as the client-side test-data. Default value is nullpublic Record[] getTestData()
cacheData
. See this discussion
for ways to populate a client-only DataSource with test
data.
public java.lang.String getFieldAutoTitle(java.lang.String identifier)
autoDeriveTitles
is true and by default, calls the class method
DataSource.getAutoTitle
. Override to provide a different
policy for auto-deriving titles for a particular DataSource or subclass of DataSource.identifier
- identifier for which a title is desired.public static java.lang.String getAutoTitle(java.lang.String identifier)
The following approach is taken:
identifier
- identifier for which a title is desired.public static java.lang.Object getFieldValue(ListGridField field, Record record)
This method
will follow any dataPath
specified on the component
field if necessary, and will extract atomic values
from
custom SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.record
- data objectpublic static java.lang.Object getFieldValue(DetailViewerField field, Record record)
This method
will follow any dataPath
specified on the component
field if necessary, and will extract atomic values
from
custom SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.record
- data objectpublic static java.lang.Object getFieldValue(FormItem field, Record record)
This method
will follow any dataPath
specified on the component
field if necessary, and will extract atomic values
from
custom SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.record
- data objectpublic static java.lang.Object getFieldValue(DataSourceField field, Record record, java.lang.String dataPath, Canvas component, java.lang.String reason, boolean convertResult)
dataPath
; it is obviously a trivial matter to obtain a field
value from a flat record directly.
If the dataPath is null, this method will follow any dataPath
specified on the component field instead. In either case, it will also extract
atomic values
from custom SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.record
- data objectdataPath
- Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)component
- Optional component to provide additional context for the dataPath search. This is typically
required if the dataPath traverses a listreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)
method - see that API for detailsconvertResult
- If true, convert the field value to a native Java object before returning itpublic static java.lang.Object getFieldValue(ListGridField field, Record record, java.lang.String dataPath, Canvas component, java.lang.String reason, boolean convertResult)
dataPath
; it is obviously a trivial matter to obtain a field
value from a flat record directly.
If the dataPath is null, this method will follow any dataPath
specified on the component field instead. In either case, it will also extract
atomic values
from custom SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.record
- data objectdataPath
- Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)component
- Optional component to provide additional context for the dataPath search. This is typically
required if the dataPath traverses a listreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)
method - see that API for detailsconvertResult
- If true, convert the field value to a native Java object before returning itpublic static java.lang.Object getFieldValue(DetailViewerField field, Record record, java.lang.String dataPath, Canvas component, java.lang.String reason, boolean convertResult)
dataPath
; it is obviously a trivial matter to obtain a field
value from a flat record directly.
If the dataPath is null, this method will follow any dataPath
specified on the component field instead. In either case, it will also extract
atomic values
from custom SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.record
- data objectdataPath
- Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)component
- Optional component to provide additional context for the dataPath search. This is typically
required if the dataPath traverses a listreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)
method - see that API for detailsconvertResult
- If true, convert the field value to a native Java object before returning itpublic static java.lang.Object getFieldValue(FormItem field, Record record, java.lang.String dataPath, Canvas component, java.lang.String reason, boolean convertResult)
dataPath
; it is obviously a trivial matter to obtain a field
value from a flat record directly.
If the dataPath is null, this method will follow any dataPath
specified on the component field instead. In either case, it will also extract
atomic values
from custom SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.record
- data objectdataPath
- Optional dataPath to use; if not supplied, the field's dataPath is used (or its name if the field has no dataPath)component
- Optional component to provide additional context for the dataPath search. This is typically
required if the dataPath traverses a listreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueExtractor.getAtomicValue(java.lang.Object)
method - see that API for detailsconvertResult
- If true, convert the field value to a native Java object before returning itpublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, java.lang.String value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, java.lang.String value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, java.lang.String value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, java.lang.String value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, java.lang.Integer value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, java.lang.Integer value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, java.lang.Integer value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, java.lang.Integer value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, java.lang.Double value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, java.lang.Double value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, java.lang.Double value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, java.lang.Double value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, java.lang.Float value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, java.lang.Float value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, java.lang.Float value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, java.lang.Float value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, java.util.Date value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, java.util.Date value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, java.util.Date value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, java.util.Date value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, java.lang.Boolean value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, java.lang.Boolean value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, java.lang.Boolean value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, java.lang.Boolean value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, com.google.gwt.core.client.JavaScriptObject value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, com.google.gwt.core.client.JavaScriptObject value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, com.google.gwt.core.client.JavaScriptObject value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, com.google.gwt.core.client.JavaScriptObject value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DataSourceField field, java.lang.String dataPath, java.util.Map value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(ListGridField field, java.lang.String dataPath, java.util.Map value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(DetailViewerField field, java.lang.String dataPath, java.util.Map value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the get request, to be passed into any SimpleType.SimpleTypeValueUpdater.updateAtomicValue(java.lang.Object, java.lang.Object)
method - see that API for detailspublic static void saveValueViaDataPath(FormItem field, java.lang.String dataPath, java.util.Map value, Record values, java.lang.String reason)
dataPath
; it is obviously a trivial matter
to store a field value in a flat record directly.
This method will call the updateAtomicValue()
of custom
SimpleType
fields where this is required.
field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)value
- the field value to savevalues
- data object to save intoreason
- Optional reason for the save, to be passed into any com.smartgwt.client.data.SimpleType.SimpleTypeValueUpdaterr#pdateAtomicValue
method - see that API for detailspublic static void clearValueAtDataPath(FormItem field, java.lang.String dataPath, Record values)
dataPath
;
it is obviously a trivial matter to remove a field value from a flat record directly.field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)values
- data object to save intopublic static void clearValueAtDataPath(DetailViewerField field, java.lang.String dataPath, Record values)
dataPath
;
it is obviously a trivial matter to remove a field value from a flat record directly.field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)values
- data object to save intopublic static void clearValueAtDataPath(ListGridField field, java.lang.String dataPath, Record values)
dataPath
;
it is obviously a trivial matter to remove a field value from a flat record directly.field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)values
- data object to save intopublic static void clearValueAtDataPath(DataSourceField field, java.lang.String dataPath, Record values)
dataPath
;
it is obviously a trivial matter to remove a field value from a flat record directly.field
- Field definition from a dataSource or dataBoundComponent.dataPath
- Optional dataPath to use (the field's dataPath is used if this is null)values
- data object to save intopublic void fetchData()
setCacheAllData(true)
mode, in
which case fetchData()
populates the DataSource cache for use by subsequent fetches. To achieve
this, use a signature of fetchData() that provides a callback, and pass criteria as null.public void addSearchOperator(Operator operator, FieldType[] types)
If an existing Operator
is passed, restricts the set
of FieldTypes to which that operator can be applied in this DataSource.
operator
- (Operator) definition of the operator to addtypes
- (Array of FieldType) types to which this operator appliespublic java.lang.String[] getPatternMultiWildcardAsString()
getPatternMultiWildcardAsStringArray()
.public java.lang.String[] getPatternSingleWildcardAsString()
getPatternSingleWildcardAsStringArray()
.