DataSource

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.smartgwt.client.data
Class DataSource

java.lang.Object
  com.smartgwt.client.core.BaseClass
      com.smartgwt.client.data.DataSource

All Implemented Interfaces:: HasHandlers, HasHandleErrorHandlers

Direct Known Subclasses:: RestDataSource, WSDataSource, XJSONDataSource

public class DataSource
extends BaseClass
implements HasHandleErrorHandlers
extends BaseClass
implements HasHandleErrorHandlers

A DataSource is data-provider-independent description of a set of objects that will be loaded, edited and saved within the user interface of your application.

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 ${isc.DocUtils.linkForDocNode('QuickStartGuide', 'QuickStart Guide')}, Chapter 6, Data Binding.

Data Integration is the process by which a DataSource can be connected to server systems such as SQL DataBases, Java Object models, WSDL web services and other data providers. Data Integration comes in two variants: client-side and server-side. Server-side integration uses the Smart GWT Java-based server to connect to data represented by Java Objects or JDBC-accessible databases. Client-side integration connects Smart GWT DataSources to XML, JSON or other formats accessible via HTTP.

DataSources have a concept of 4 core operations ("fetch", "add", "update" and "remove") that can be performed on the set of objects represented by a DataSource. Once a DataSource has been integrated with your data store, databinding-capable UI components can leverage the 4 core DataSource operations to provide many complete user interactions without the need to configure how each individual component loads and saves data.

These interactions include grid views, tree views, detail views, form-based editing and saving, grid-based editing and saving, and custom interactions provided by Pattern Reuse Example custom databinding-capable components.

See Also:: DataBoundComponent

Field Summary

Fields inherited from class com.smartgwt.client.core.BaseClass
`config, id, scClassName`

Constructor Summary
`DataSource()`
`DataSource(JavaScriptObject jsObj)`
`DataSource(String dataURL)`

Method Summary
`void`	`addData(Record record)` Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
`void`	`addData(Record record, DSCallback callback)` Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
`void`	`addData(Record record, DSCallback callback, DSRequest requestProperties)` Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
`void`	`addField(DataSourceField field)` Add a field to the DataSource
`HandlerRegistration`	`addHandleErrorHandler(HandleErrorHandler handler)` Add a handleError handler.
`static Criteria`	`combineCriteria(Criteria criteria1, Criteria criteria2)` Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator".
`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, String timezoneOffset, int firstDayOfWeek)` Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.
`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 `Record`s (including a TreeNode) to a new array of `Record`s, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.
`JavaScriptObject`	`create()`
`void`	`downloadFile(Record data)` Download a file stored in a field of type:"binary" in a DataSource record.
`void`	`downloadFile(Record data, String fieldName, DSRequest requestProperties)` Download a file stored in a field of type:"binary" in a DataSource record.
`void`	`exportClientData(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, DSRequest requestProperties)` Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results.
`void`	`fetchData(Criteria criteria, DSCallback callback)` See `fetchData(Criteria,DSCallback,DSRequest)`.
`void`	`fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)` Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
`void`	`filterData(Criteria criteria, DSCallback callback)` Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
`void`	`filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)`
`static DataSource`	`get(String ID)` Synonym of `DataSource.getDataSource`: Lookup a DataSource by ID.
`static DataSource`	`get(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)` Synonym of `DataSource.getDataSource`: Lookup a DataSource by ID.
`Boolean`	`getAddGlobalId()` Whether to make this DataSource available as a global variable for convenience.
`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.
`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 `DataSource.getAutoTitle`.
`Boolean`	`getCacheAllData()` Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
`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.
`String`	`getCallbackParam()` Applies only to dataFormat: "json" and `dataTransport`:"scriptInclude".
`Boolean`	`getCanMultiSort()` When true, indicates that this DataSource supports multi-level sorting.
`String`	`getChildrenField()` fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
`Boolean`	`getClientOnly()` Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might.
`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 `criteria` changes.
`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 `DataSource.fetchData` is called).
`DSProtocol`	`getDataProtocol()` Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
`static DataSource`	`getDataSource(String ID)` Lookup a DataSource by ID.
`static DataSource`	`getDataSource(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)` Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer.
`RPCTransport`	`getDataTransport()` Transport to use for all operations on this DataSource.
`String`	`getDataURL()` Default URL to contact to fulfill all DSRequests.
`Map`	`getDefaultParams()` HTTP parameters that should be submitted with every DSRequest.
`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.
`Object`	`getDisplayValue(String fieldName, Object value)` Given a fieldName and a dataValue, apply any `valueMap` for the field and return the display value for the field.
`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.
`DataSourceField`	`getField(String fieldName)` Return the field definition object.
`DataSourceField`	`getFieldForDataPath(String dataPath)` Return the field definition object corresponding to the supplied dataPath
`String[]`	`getFieldNames()` Retrieves the list of fields declared on this DataSource.
`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 this field.
`OperatorId[]`	`getFieldOperators(String fieldName)` Get the list of OperatorId's available for this field.
`DataSourceField[]`	`getFields()` The list of fields that compose records from this DataSource.
`void`	`getFileURL(Record data)` Returns a direct URL to access a file stored in a field of type:"binary".
`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.
`String`	`getIconField()` Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.
`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.
`String`	`getInheritsFrom()` ID of another DataSource this DataSource inherits its `fields` from.
`JavaScriptObject`	`getJsObj()`
`String`	`getJsonPrefix()` Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
`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.
`OperationBinding[]`	`getOperationBindings()` Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
`static DataSource`	`getOrCreateRef(JavaScriptObject jsObj)`
`String`	`getPluralTitle()` User-visible plural name for this DataSource.
`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
`String`	`getPrimaryKeyFieldName()` Returns the primary key fieldName for this DataSource
`Boolean`	`getQualifyColumnNames()` For dataSources of `serverType` "sql", determines whether we qualify column names with table names in any SQL we generate.
`String`	`getRecordXPath()` See `recordXPath`.
`DSRequest`	`getRequestProperties()` Additional properties to pass through to the `DSRequest`s made by this DataSource.
`String`	`getRequiredMessage()` The required message for required field errors.
`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.
`String`	`getResultSetClass()` Class for ResultSets used by this datasource.
`String`	`getSchemaNamespace()` For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to.
`Boolean`	`getSendExtraFields()` Analogous to `dropExtraFields`, for data sent to the server.
`String`	`getServiceNamespace()` For an XML DataSource, URN of the WebService to use to invoke operations.
`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.
`Boolean`	`getShowPrompt()` Whether RPCRequests sent by this DataSource should enable `showPrompt` if it's unset.
`static String[]`	`getSortBy(String[] sortSpecifiers)` Given an array of ${isc.DocUtils.linkForRef('object:SortSpecifier')}s, return a simple list of Strings in the format expected by `sortBy`.
`static String[]`	`getSortSpecifiers(String[] sortBy)` Return a an array of ${isc.DocUtils.linkForRef('object:SortSpecifier')}s, given an array of Strings in the format expected by `sortBy`.
`Boolean`	`getStrictSQLFiltering()` [A] 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.
`String`	`getTagName()` Tag name to use when serializing to XML.
`DataClass[]`	`getTestData()` For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
`String`	`getTitle()` User-visible name for this DataSource.
`String`	`getTitleField()` Best field to use for a user-visible title for an individual record from this dataSource.
`OperatorId[]`	`getTypeOperators(FieldType fieldType)` Get the list of OperatorIds available on this DataSource for the given FieldType.
`Boolean`	`getUseFlatFields()` Like `useFlatFields`, but applies to all DataBound components that bind to this DataSource.
`Boolean`	`getUseHttpProxy()` Like `useHttpProxy`, but serves as a default for this DataSource that may be overridden by individual operationBindings.
`Boolean`	`getUseLocalValidators()` Whether to attempt validation on the client at all for this DataSource.
`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).
`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.
`Boolean`	`getUseTestDataFetch()` When set, causes a `client-only` or `cacheAllData` DataSource to create a second DataSource to perform it's one-time fetch.
`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.
`Boolean`	`getWillHandleAdvancedCriteria()` This property may be set to `true` to indicate that this dataSource supports advancedCriteria on fetch or filter type operations.
`Boolean`	`hasAllData()` When `cacheAllData` is true, has all the data been retrieved to the client?
`void`	`invalidateCache()` Invalidate the cache when `cacheAllData` or `clientOnly` are true.
`boolean`	`isCreated()`
`static void`	`load(String[] dsID, Function callback, boolean forceReload)` Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
`static void`	`load(String dsID, Function callback, boolean forceReload)` Load a DataSource or an array of DataSources using the DataSourceLoader servlet.
`protected void`	`onInit()`
`void`	`performCustomOperation(String operationId, Record data, DSCallback callback, DSRequest requestProperties)` Invoke an operation declared with OperationBinding.operationType "custom".
`void`	`processResponse(String requestId, DSResponse responseProperties)` Process a dsResponse for a request initiated by a DataSource with `dataProtocol`.
`Record[]`	`recordsFromXML(Object elements)` Transform a list of XML elements to DataSource records.
`void`	`removeData(Record record)` Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
`void`	`removeData(Record record, DSCallback callback)` Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
`void`	`removeData(Record record, DSCallback callback, DSRequest requestProperties)` Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
`void`	`setAddGlobalId(Boolean addGlobalId)` Whether to make this DataSource available as a global variable for convenience.
`void`	`setAutoCacheAllData(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.
`void`	`setAutoConvertRelativeDates(Boolean autoConvertRelativeDates)` Whether to convert relative date values to concrete date values before sending to the server.
`void`	`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 `DataSource.getAutoTitle`.
`void`	`setCacheAllData(Boolean cacheAllData)` Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
`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.
`void`	`setCacheMaxAge(int cacheMaxAge)` The maximum time, in seconds, to maintain the client-side cache.
`void`	`setCallbackParam(String callbackParam)` Applies only to dataFormat: "json" and `dataTransport`:"scriptInclude".
`void`	`setCanMultiSort(Boolean canMultiSort)` When true, indicates that this DataSource supports multi-level sorting.
`void`	`setChildrenField(String childrenField)` fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
`void`	`setClientOnly(Boolean clientOnly)` Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might.
`void`	`setCriteriaPolicy(CriteriaPolicy criteriaPolicy)` Decides under what conditions the `ResultSet` cache should be dropped when the `criteria` changes.
`void`	`setDataField(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.
`void`	`setDataFormat(DSDataFormat dataFormat)` Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when `DataSource.fetchData` is called).
`void`	`setDataProtocol(DSProtocol dataProtocol)` Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
`void`	`setDataTransport(RPCTransport dataTransport)` Transport to use for all operations on this DataSource.
`void`	`setDataURL(String dataURL)` Default URL to contact to fulfill all DSRequests.
`void`	`setDefaultParams(Map defaultParams)` HTTP parameters that should be submitted with every DSRequest.
`void`	`setDescriptionField(String descriptionField)` Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.
`void`	`setDropExtraFields(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.
`void`	`setEnumConstantProperty(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".
`void`	`setEnumOrdinalProperty(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".
`void`	`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.
`void`	`setGlobalNamespaces(Map globalNamespaces)` Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.
`void`	`setIconField(String iconField)` Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.
`void`	`setID(String id)`
`void`	`setInfoField(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.
`void`	`setInheritsFrom(String inheritsFrom)` ID of another DataSource this DataSource inherits its `fields` from.
`void`	`setJsonPrefix(String jsonPrefix)` Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
`void`	`setJsonSuffix(String jsonSuffix)` Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
`void`	`setOperationBindings(OperationBinding... operationBindings)` Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
`void`	`setPluralTitle(String pluralTitle)` User-visible plural name for this DataSource.
`void`	`setPreventHTTPCaching(Boolean preventHTTPCaching)` If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.
`void`	`setQualifyColumnNames(Boolean qualifyColumnNames)` For dataSources of `serverType` "sql", determines whether we qualify column names with table names in any SQL we generate.
`void`	`setRecordName(String recordName)` See `recordName`.
`void`	`setRecordXPath(String recordXPath)` See `recordXPath`.
`void`	`setRequestProperties(DSRequest requestProperties)` Additional properties to pass through to the `DSRequest`s made by this DataSource.
`void`	`setRequiredMessage(String requiredMessage)` The required message for required field errors.
`void`	`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.
`void`	`setResultSetClass(String resultSetClass)` Class for ResultSets used by this datasource.
`void`	`setSendExtraFields(Boolean sendExtraFields)` Analogous to `dropExtraFields`, for data sent to the server.
`void`	`setServiceNamespace(String serviceNamespace)` For an XML DataSource, URN of the WebService to use to invoke operations.
`void`	`setShowLocalFieldsOnly(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.
`void`	`setShowPrompt(Boolean showPrompt)` Whether RPCRequests sent by this DataSource should enable `showPrompt` if it's unset.
`void`	`setStrictSQLFiltering(Boolean strictSQLFiltering)` [A] 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.
`void`	`setTagName(String tagName)` Tag name to use when serializing to XML.
`void`	`setTestData(DataClass[] testData)` For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
`void`	`setTitle(String title)` User-visible name for this DataSource.
`void`	`setTitleField(String titleField)` Best field to use for a user-visible title for an individual record from this dataSource.
`void`	`setTypeOperators(FieldType fieldType, OperatorId[] operators)` Set the list of `OperatorIds` valid for a given FieldType.
`void`	`setUseFlatFields(Boolean useFlatFields)` Like `useFlatFields`, but applies to all DataBound components that bind to this DataSource.
`void`	`setUseHttpProxy(Boolean useHttpProxy)` Like `useHttpProxy`, but serves as a default for this DataSource that may be overridden by individual operationBindings.
`void`	`setUseLocalValidators(Boolean useLocalValidators)` Whether to attempt validation on the client at all for this DataSource.
`void`	`setUseOfflineStorage(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).
`void`	`setUseParentFieldOrder(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.
`void`	`setUseTestDataFetch(Boolean useTestDataFetch)` When set, causes a `client-only` or `cacheAllData` DataSource to create a second DataSource to perform it's one-time fetch.
`void`	`setValidateRelatedRecords(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.
`void`	`setWillHandleAdvancedCriteria(Boolean willHandleAdvancedCriteria)` This property may be set to `true` to indicate that this dataSource supports advancedCriteria on fetch or filter type operations.
`void`	`setXmlNamespaces(XmlNamespaces xmlNamespaces)` Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions.
`Boolean`	`supportsAdvancedCriteria()` Do fetch and filter operations on this dataSource support being passed `AdvancedCriteria`?
`void`	`supportsTextMatchStyle(TextMatchStyle textMatchStyle)` Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.
`protected Object`	`transformRequest(DSRequest dsRequest)` For a dataSource using client-side data integration, return the data that should be sent to the DataSource.dataURL.
`protected void`	`transformResponse(DSResponse response, DSRequest request, 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 record)` Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
`void`	`updateData(Record record, DSCallback callback)` Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
`void`	`updateData(Record record, 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 `errors` validation errors or a `status` code of 0.
`void`	`validateData(Record values, DSCallback callback, DSRequest requestProperties)` Contacts the server to run server-side validation on a DSRequest and either returns `errors` validation errors or a `status` code of 0.
`void`	`viewFile(Record data)` Display a file stored in a field of type:"binary" in a new browser window.
`void`	`viewFile(Record data, String fieldName, DSRequest requestProperties)` Display a file stored in a field of type:"binary" in a new browser window.
`String`	`xmlSerialize(JavaScriptObject data)` Serialize a JavaScript object as XML.
`String`	`xmlSerialize(JavaScriptObject data, SerializationContext flags)` Serialize a JavaScript object as XML.
`String`	`xmlSerialize(Map data, SerializationContext flags)` Serialize a JavaScript object as XML.
`String`	`xmlSerialize(Record[] data, SerializationContext flags)` Serialize a JavaScript object as XML.
`String`	`xmlSerialize(Record data, SerializationContext flags)` Serialize a JavaScript object as XML.

Methods inherited from class com.smartgwt.client.core.BaseClass
destroy, doAddHandler, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getScClassName, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setProperty, setProperty, setProperty, setProperty, setScClassName

Methods inherited from class com.smartgwt.client.core.BaseClass

destroy, doAddHandler, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getScClassName, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setProperty, setProperty, setProperty, setProperty, setScClassName

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

Methods inherited from interface com.google.gwt.event.shared.HasHandlers
`fireEvent`

Constructor Detail

DataSource

public DataSource()

DataSource

public DataSource(JavaScriptObject jsObj)

DataSource

public DataSource(String dataURL)

Method Detail

getOrCreateRef

public static DataSource getOrCreateRef(JavaScriptObject jsObj)

create

public JavaScriptObject create()

Specified by:: create in class BaseClass

setAutoCacheAllData

public void setAutoCacheAllData(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.

Parameters:: autoCacheAllData - autoCacheAllData Default value is false

getAutoCacheAllData

public Boolean getAutoCacheAllData()

Returns:: Boolean

setAutoConvertRelativeDates

public void setAutoConvertRelativeDates(Boolean autoConvertRelativeDates)
                                 throws IllegalStateException

Whether to convert relative date values to concrete date values before sending to the server. Default value is true, which means that the server does not need to understand how to filter using relative dates - it receives all date values as absolute dates.

Parameters:: autoConvertRelativeDates - autoConvertRelativeDates Default value is true
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getAutoConvertRelativeDates

public Boolean getAutoConvertRelativeDates()

Returns:: Boolean

setAutoDeriveTitles

public void setAutoDeriveTitles(Boolean autoDeriveTitles)
                         throws IllegalStateException

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

Parameters:: autoDeriveTitles - autoDeriveTitles Default value is true
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getAutoDeriveTitles

public 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 DataSource.getAutoTitle.

Returns:: Boolean

setCacheAllData

public void setCacheAllData(Boolean cacheAllData)

Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request. However, unlike a clientOnly DataSource, this DataSource will still save changes normally, sending remote requests.

You can manually set this attribute after initialization by calling DataSource.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.

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.

Parameters:: cacheAllData - New value for cacheAllData. Default value is null

getCacheAllData

public Boolean getCacheAllData()

Returns:: Boolean

setCacheData

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

If this method is called after the component has been drawn/initialized: Call this method to set the data in the client-side cache after initialization.

Parameters:: cacheData - Array of records to apply as the client-side cache. Default value is null

getCacheData

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

Returns:: Record

setCacheMaxAge

public void setCacheMaxAge(int cacheMaxAge)

The maximum time, in seconds, to maintain the client-side cache. If a fetch occurs after the cacheMaxAge has expired, the current cache will be dropped and another complete cache fetched.

Parameters:: cacheMaxAge - cacheMaxAge Default value is 60

getCacheMaxAge

public int getCacheMaxAge()

The maximum time, in seconds, to maintain the client-side cache. If a fetch occurs after the cacheMaxAge has expired, the current cache will be dropped and another complete cache fetched.

Returns:: int

setCallbackParam

public void setCallbackParam(String callbackParam)
                      throws IllegalStateException

Applies only to dataFormat: "json" and dataTransport:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response.

Parameters:: callbackParam - callbackParam Default value is "callback"
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: setDataFormat(com.smartgwt.client.types.DSDataFormat), setOperationBindings(com.smartgwt.client.data.OperationBinding...), OperationBinding.setCallbackParam(java.lang.String), ClientDataIntegration overview and related methods, Edit and Save Example

getCallbackParam

public String getCallbackParam()

Applies only to dataFormat: "json" and dataTransport:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response.

Returns:: String
See Also:: getDataFormat(), getOperationBindings(), OperationBinding.getCallbackParam(), ClientDataIntegration overview and related methods, Edit and Save Example

setCanMultiSort

public void setCanMultiSort(Boolean canMultiSort)
                     throws IllegalStateException

When true, indicates that this DataSource supports multi-level sorting.

Parameters:: canMultiSort - canMultiSort Default value is true
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getCanMultiSort

public Boolean getCanMultiSort()

When true, indicates that this DataSource supports multi-level sorting.

Returns:: Boolean

setChildrenField

public void setChildrenField(String childrenField)
                      throws IllegalStateException

fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierarchical data structure, rather than a flat list of nodes linked by foreignKey.
Note this is an alternative to setting 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.

Parameters:: childrenField - childrenField Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: DataSourceField.setChildrenProperty(java.lang.Boolean), DataSourceRelations overview and related methods

getChildrenField

public String getChildrenField()

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.

Returns:: String
See Also:: DataSourceField.getChildrenProperty(), DataSourceRelations overview and related methods

setClientOnly

public void setClientOnly(Boolean clientOnly)
                   throws IllegalStateException

Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might.

Note that a client-only DataSource is an entirely client-side variant of a cacheAllData DataSource, where all operations are performed on client-side data, not just fetches.

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: Switch into clientOnly mode, taking the cache from the cacheAllData ResultSet if it exists.

Parameters:: clientOnly - clientOnly Default value is false
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientOnlyDataSources overview and related methods, Local DataSource Example

getClientOnly

public Boolean getClientOnly()

Note that a client-only DataSource is an entirely client-side variant of a cacheAllData DataSource, where all operations are performed on client-side data, not just fetches.

See this discussion for ways to populate a client-only DataSource with test data.

Returns:: Boolean
See Also:: ClientOnlyDataSources overview and related methods, Local DataSource Example

setCriteriaPolicy

public void setCriteriaPolicy(CriteriaPolicy criteriaPolicy)

Decides under what conditions the ResultSet cache should be dropped when the criteria changes.

Note : This is an advanced setting

Parameters:: criteriaPolicy - criteriaPolicy Default value is "dropOnShortening"
See Also:: com.smartgwt.client.data.DataSource#compareCriteria

getCriteriaPolicy

public CriteriaPolicy getCriteriaPolicy()

Decides under what conditions the ResultSet cache should be dropped when the criteria changes.

Returns:: CriteriaPolicy
See Also:: com.smartgwt.client.data.DataSource#compareCriteria

setDataField

public void setDataField(String dataField)
                  throws IllegalStateException

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.

For example, for a DataSource of employees, good choices might be the "salary" field, "hire date" or "status" (active, vacation, on leave, etc).

Unlike titleField, dataField is not automatically determined in the absence of an explicit setting.

Parameters:: dataField - dataField Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: DsSpecialFields overview and related methods

getDataField

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

For example, for a DataSource of employees, good choices might be the "salary" field, "hire date" or "status" (active, vacation, on leave, etc).

Unlike titleField, dataField is not automatically determined in the absence of an explicit setting.

Returns:: String
See Also:: DsSpecialFields overview and related methods

setDataFormat

public void setDataFormat(DSDataFormat dataFormat)
                   throws IllegalStateException

Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when DataSource.fetchData is called).

Parameters:: dataFormat - dataFormat Default value is "iscServer"
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientDataIntegration overview and related methods, JSON DataSource Example, Simple JSON Example

getDataFormat

public DSDataFormat getDataFormat()

Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when DataSource.fetchData is called).

Returns:: DSDataFormat
See Also:: ClientDataIntegration overview and related methods, JSON DataSource Example, Simple JSON Example

setDataTransport

public void setDataTransport(RPCTransport dataTransport)
                      throws IllegalStateException

Transport to use for all operations on this DataSource. Defaults to 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 callbackParam to match the name of the query parameter name expected by your JSON service provider.

Parameters:: dataTransport - dataTransport Default value is RPCManager.defaultTransport
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: RPCTransport, setCallbackParam(java.lang.String), ClientDataIntegration overview and related methods

getDataTransport

public RPCTransport getDataTransport()

When using the "scriptInclude" transport, be sure to set callbackParam or callbackParam to match the name of the query parameter name expected by your JSON service provider.

Returns:: RPCTransport
See Also:: RPCTransport, getCallbackParam(), ClientDataIntegration overview and related methods

setDataURL

public void setDataURL(String dataURL)
                throws IllegalStateException

Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis via 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.

Parameters:: dataURL - dataURL Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientDataIntegration overview and related methods, JSON DataSource Example

getDataURL

public String getDataURL()

Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis via 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.

Returns:: String
See Also:: ClientDataIntegration overview and related methods, JSON DataSource Example

setDescriptionField

public void setDescriptionField(String descriptionField)
                         throws IllegalStateException

Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.

For example, for a DataSource representing employees, a field containing the employee's "bio" might be a good choice, or for an email message, the message body.

If descriptionField is unset, it defaults to any field named "description" or "desc" in the record, or the first long text field (greater than 255 characters) in the record, or null if no such field exists.

Parameters:: descriptionField - descriptionField Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: DsSpecialFields overview and related methods

getDescriptionField

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

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.

Returns:: String
See Also:: DsSpecialFields overview and related methods

setDropExtraFields

public void setDropExtraFields(Boolean dropExtraFields)
                        throws IllegalStateException

Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.

For JSON data, this means extra properties in selected objects are dropped.

By default, for DMI DSResponses, DSResponse.data is filtered on the server to just the set of fields defined on the DataSource. This type of filtering can also be enabled for non-DMI DSResponses (see the overview in DMI). Setting this property to false disables this filtering for this DataSource only. This setting overrides the configuration in server.properties. This setting can be overridden by dropExtraFields.

Parameters:: dropExtraFields - dropExtraFields Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientDataIntegration overview and related methods

getDropExtraFields

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

For JSON data, this means extra properties in selected objects are dropped.

Returns:: Boolean
See Also:: ClientDataIntegration overview and related methods

setEnumConstantProperty

public void setEnumConstantProperty(String enumConstantProperty)
                             throws IllegalStateException

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". Defaults to "_constant" if not set.

This property is only applicable if you are using the Smart GWT server

Note : This is an advanced setting

Parameters:: enumConstantProperty - enumConstantProperty Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

setEnumOrdinalProperty

public void setEnumOrdinalProperty(String enumOrdinalProperty)
                            throws IllegalStateException

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". Defaults to "_ordinal" if not set.

This property is only applicable if you are using the Smart GWT server

Note : This is an advanced setting

Parameters:: enumOrdinalProperty - enumOrdinalProperty Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

setEnumTranslateStrategy

public void setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy)
                              throws IllegalStateException

Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript. This property is only applicable if you are using the Smart GWT server

Note : This is an advanced setting

Parameters:: enumTranslateStrategy - enumTranslateStrategy Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

setGlobalNamespaces

public void setGlobalNamespaces(Map globalNamespaces)

Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.

The default value is:

    globalNamespaces : {
       xsi: "http://www.w3.org/2001/XMLSchema-instance",
       xsd: "http://www.w3.org/2001/XMLSchema"
    },

This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.

Note that some web services will only accept specific revisions of the XML Schema URI. If xsi-namespaced attributes seem to be ignored by an older webservice, try the URI "http://www.w3.org/1999/XMLSchema-instance" instead.

Parameters:: globalNamespaces - globalNamespaces Default value is ...

getGlobalNamespaces

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

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.

Returns:: Map

setIconField

public void setIconField(String iconField)
                  throws IllegalStateException

Designates a field of 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.

Parameters:: iconField - iconField Default value is see below
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: DsSpecialFields overview and related methods

getIconField

public String getIconField()

Designates a field of 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.

To avoid any field being used as the iconField, set iconField to null.

Returns:: String
See Also:: DsSpecialFields overview and related methods

setInfoField

public void setInfoField(String infoField)
                  throws IllegalStateException

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.

For example, for a DataSource of employees, a "job title" field would probably be the second most pertinent text field aside from the employee's "full name".

Unlike titleField, infoField is not automatically determined in the absence of an explicit setting.

Parameters:: infoField - infoField Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: DsSpecialFields overview and related methods

getInfoField

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

For example, for a DataSource of employees, a "job title" field would probably be the second most pertinent text field aside from the employee's "full name".

Unlike titleField, infoField is not automatically determined in the absence of an explicit setting.

Returns:: String
See Also:: DsSpecialFields overview and related methods

setInheritsFrom

public void setInheritsFrom(String inheritsFrom)
                     throws IllegalStateException

ID of another DataSource this DataSource inherits its 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:

creating a customized view (eg, only certain fields shown) which will be used by multiple databound components.
adding presentation-specific attributes to metadata that has been automatically derived from XML Schema or other metadata formats
modeling object subclassing and extension in server-side code and storage systems
modeling relational database joins, and the equivalents in other systems
creating hooks for others to customize your application in a maintainable way. For example, if you have a dataSource "employee", you can create a dataSource "customizedEmployee" which inherits from "employee" but does not initially define any fields, and bind all databound components to "customizedEmployee". Customizations of fields (including appearance changes, field order, new fields, hiding of fields, and custom validation rules) can be added to "customizedEmployee", so that they are kept separately from the original field data and have the best possible chance of working with future versions of the "employee" dataSource.

Parameters:: inheritsFrom - inheritsFrom Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: Schema Chaining Example

getInheritsFrom

public String getInheritsFrom()

ID of another DataSource this DataSource inherits its fields from.

This feature can be used for:

creating a customized view (eg, only certain fields shown) which will be used by multiple databound components.
adding presentation-specific attributes to metadata that has been automatically derived from XML Schema or other metadata formats
modeling object subclassing and extension in server-side code and storage systems
modeling relational database joins, and the equivalents in other systems
creating hooks for others to customize your application in a maintainable way. For example, if you have a dataSource "employee", you can create a dataSource "customizedEmployee" which inherits from "employee" but does not initially define any fields, and bind all databound components to "customizedEmployee". Customizations of fields (including appearance changes, field order, new fields, hiding of fields, and custom validation rules) can be added to "customizedEmployee", so that they are kept separately from the original field data and have the best possible chance of working with future versions of the "employee" dataSource.

Returns:: String
See Also:: Schema Chaining Example

setJsonPrefix

public void setJsonPrefix(String jsonPrefix)
                   throws IllegalStateException

Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.

The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.
Note: If the prefix / suffix served by your backend is not a constant, you can use dataFormat:"custom" instead and explicitly parse the prefix out as part of transformResponse().

Note : This is an advanced setting

Parameters:: jsonPrefix - jsonPrefix Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: OperationBinding.setDataFormat(com.smartgwt.client.types.DSDataFormat), OperationBinding.setDataTransport(com.smartgwt.client.types.RPCTransport)

getJsonPrefix

public String getJsonPrefix()

Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.

The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

Returns:: String
See Also:: OperationBinding.getDataFormat(), OperationBinding.getDataTransport()

setJsonSuffix

public void setJsonSuffix(String jsonSuffix)
                   throws IllegalStateException

Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.

The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.

Note : This is an advanced setting

Parameters:: jsonSuffix - jsonSuffix Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: OperationBinding.setDataFormat(com.smartgwt.client.types.DSDataFormat), OperationBinding.setDataTransport(com.smartgwt.client.types.RPCTransport)

getJsonSuffix

public String getJsonSuffix()

Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.

The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventative measure against javascript hijacking.

Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.

Returns:: String
See Also:: OperationBinding.getDataFormat(), OperationBinding.getDataTransport()

setOperationBindings

public void setOperationBindings(OperationBinding... operationBindings)
                          throws IllegalStateException

Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.

When using the Smart GWT Server, OperationBindings are specified in your DataSource descriptor (.ds.xml file) and control server-side behavior such as what Java object to route DSRequest to (serverObject) or customizations to SQL / HQL queries (customSQL and customHQL). See the

Parameters:

operationBindings - operationBindings Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

Java Integration samples.

For DataSources bound to WSDL-described web services using {@link com.smartgwt.client.data.DataSource#getServiceNamespace serviceNamespace}, OperationBindings are used to bind each DataSource {@link com.smartgwt.client.data.OperationBinding#getOperationType operationType} to an {@link com.smartgwt.client.data.OperationBinding#getWsOperation operation} of a WSDL-described {@link com.smartgwt.client.data.WebService 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

  isc.DataSource.create({
     serviceNamespace : "urn:partner.soap.sforce.com",
     operationBindings : [
         { operationType:"fetch", wsOperation:"query", recordName: "sObject" },
         { operationType:"update", wsOperation:"update", recordName: "SaveResult" },
         { operationType:"add", wsOperation:"create", recordName: "SaveResult" },
         { operationType:"remove", wsOperation:"delete", recordName: "DeleteResult" }
     ],
     ...
  });

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 {@link com.smartgwt.client.widgets.DataBoundComponent} such as an {@link com.smartgwt.client.widgets.grid.ListGrid#getCanEdit 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. An example of using OperationBinding properties directly on the DataSource in order to read an RSS feed can be found here:

${isc.DocUtils.linkForStandaloneExample('/examples/databinding/rss_databinding.html', '/examples/databinding/rss_databinding.html')}, OperationBinding

getOperationBindings

public OperationBinding[] getOperationBindings()

Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.

Returns:

OperationBinding

See Also:

Java Integration samples.

For example, this code accomplishes part of the binding to the SalesForce partner web services

  isc.DataSource.create({
     serviceNamespace : "urn:partner.soap.sforce.com",
     operationBindings : [
         { operationType:"fetch", wsOperation:"query", recordName: "sObject" },
         { operationType:"update", wsOperation:"update", recordName: "SaveResult" },
         { operationType:"add", wsOperation:"create", recordName: "SaveResult" },
         { operationType:"remove", wsOperation:"delete", recordName: "DeleteResult" }
     ],
     ...
  });

NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.

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.

${isc.DocUtils.linkForStandaloneExample('/examples/databinding/rss_databinding.html', '/examples/databinding/rss_databinding.html')}, OperationBinding

setPluralTitle

public void setPluralTitle(String pluralTitle)
                    throws IllegalStateException

User-visible plural name for this DataSource.

For example, for the supplyItem DataSource, "Supply Items".

Defaults to (dataSource.title or dataSource.ID) + "s".

Parameters:: pluralTitle - pluralTitle Default value is dataSource.ID
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getPluralTitle

public String getPluralTitle()

User-visible plural name for this DataSource.

For example, for the supplyItem DataSource, "Supply Items".

Defaults to (dataSource.title or dataSource.ID) + "s".

Returns:: String

setPreventHTTPCaching

public void setPreventHTTPCaching(Boolean preventHTTPCaching)
                           throws IllegalStateException

If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.

Note that this does not disable caching at higher levels in the framework, for example, the caching performed by ResultSet.

Parameters:: preventHTTPCaching - preventHTTPCaching Default value is true
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getPreventHTTPCaching

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

Note that this does not disable caching at higher levels in the framework, for example, the caching performed by ResultSet.

Returns:: Boolean

setQualifyColumnNames

public void setQualifyColumnNames(Boolean qualifyColumnNames)
                           throws IllegalStateException

For dataSources of serverType "sql", determines whether we qualify column names with table names in any SQL we generate. This property can be overridden on specific operationBindings.

Parameters:: qualifyColumnNames - qualifyColumnNames Default value is true
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: com.smartgwt.client.docs.serverds.OperationBinding#qualifyColumnNames

getQualifyColumnNames

public Boolean getQualifyColumnNames()

For dataSources of serverType "sql", determines whether we qualify column names with table names in any SQL we generate. This property can be overridden on specific operationBindings.

Returns:: Boolean
See Also:: com.smartgwt.client.docs.serverds.OperationBinding#qualifyColumnNames

setRecordXPath

public void setRecordXPath(String recordXPath)
                    throws IllegalStateException

See recordXPath. recordXPath can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations.

Parameters:: recordXPath - recordXPath Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientDataIntegration overview and related methods, XML DataSource Example, JSON XPath Binding Example

getRecordXPath

public String getRecordXPath()

See recordXPath. recordXPath can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations.

Returns:: String
See Also:: ClientDataIntegration overview and related methods, XML DataSource Example, JSON XPath Binding Example

setRequestProperties

public void setRequestProperties(DSRequest requestProperties)
                          throws IllegalStateException

Additional properties to pass through to the DSRequests made by this DataSource.

These properties are applied before DataSource.transformRequest is called.

Parameters:: requestProperties - requestProperties Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: DSRequest, OperationBinding.setRequestProperties(com.smartgwt.client.data.DSRequest), ClientDataIntegration overview and related methods

getRequestProperties

public DSRequest getRequestProperties()

Additional properties to pass through to the DSRequests made by this DataSource.

These properties are applied before DataSource.transformRequest is called.

Returns:: DSRequest
See Also:: DSRequest, OperationBinding.getRequestProperties(), ClientDataIntegration overview and related methods

setRequiredMessage

public void setRequiredMessage(String requiredMessage)

The required message for required field errors.

Parameters:: requiredMessage - requiredMessage Default value is null
See Also:: FormTitles overview and related methods

getRequiredMessage

public String getRequiredMessage()

The required message for required field errors.

Returns:: String
See Also:: FormTitles overview and related methods

setResultBatchSize

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

If you have a relatively small number of records with a great deal of properties or subobjects on each record, and you have not set dropExtraFields to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this number lower.

Note : This is an advanced setting

Parameters:: resultBatchSize - resultBatchSize Default value is 150

getResultBatchSize

public int getResultBatchSize()

Returns:: int

setResultSetClass

public void setResultSetClass(String resultSetClass)
                       throws IllegalStateException

Class for ResultSets used by this datasource. If null, defaults to using 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

Parameters:: resultSetClass - resultSetClass Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getResultSetClass

public String getResultSetClass()

Class for ResultSets used by this datasource. If null, defaults to using 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.

Returns:: String

getSchemaNamespace

public String getSchemaNamespace()
                          throws IllegalStateException

For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to. This is a read-only attribute automatically present on DataSources returned from SchemaSet.getSchema and WebService.getSchema. Note : This method should be called only after the underlying component has been created.

Returns:: String
Throws:: IllegalStateException - if underlying component has not yet been created.
See Also:: WsdlBinding overview and related methods

setSendExtraFields

public void setSendExtraFields(Boolean sendExtraFields)
                        throws IllegalStateException

Analogous to 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 DataSource.transformRequest and ultimately sent to the server.

Parameters:: sendExtraFields - sendExtraFields Default value is true
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientDataIntegration overview and related methods

getSendExtraFields

public Boolean getSendExtraFields()

Returns:: Boolean
See Also:: ClientDataIntegration overview and related methods

setServiceNamespace

public void setServiceNamespace(String serviceNamespace)
                         throws IllegalStateException

For an XML DataSource, URN of the WebService to use to invoke operations. This URN comes from the "targetNamespace" attribute of the <wsdl:definitions> element in a WSDL (Web Service Description Language) document, and serves as the unique identifier of the service.

Having loaded a WebService using XMLTools.loadWSDL, setting serviceNamespace combined with specifying operationBindings that set 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".

Parameters:: serviceNamespace - serviceNamespace Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: WsdlBinding overview and related methods, Weather SOAP Search Example

getServiceNamespace

public String getServiceNamespace()

Setting serviceNamespace also defaults dataURL to the service's location, dataFormat to "xml" and dataProtocol to "soap".

Returns:: String
See Also:: WsdlBinding overview and related methods, Weather SOAP Search Example

setShowLocalFieldsOnly

public void setShowLocalFieldsOnly(Boolean showLocalFieldsOnly)
                            throws IllegalStateException

For a DataSource that inherits 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".

Parameters:: showLocalFieldsOnly - showLocalFieldsOnly Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getShowLocalFieldsOnly

public Boolean getShowLocalFieldsOnly()

Returns:: Boolean

setShowPrompt

public void setShowPrompt(Boolean showPrompt)

Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset.

Parameters:: showPrompt - showPrompt Default value is true

getShowPrompt

public Boolean getShowPrompt()

Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset.

Returns:: Boolean

setStrictSQLFiltering

public void setStrictSQLFiltering(Boolean strictSQLFiltering)
                           throws IllegalStateException

[A] If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:

     field == "someValue"  (normally false)
     field != "someValue"  (normally true)
     not (field == "someValue")   (normally true)
     not (field != "someValue")   (normally false)

Parameters:: strictSQLFiltering - strictSQLFiltering Default value is false
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getStrictSQLFiltering

public Boolean getStrictSQLFiltering()

     field == "someValue"  (normally false)
     field != "someValue"  (normally true)
     not (field == "someValue")   (normally true)
     not (field != "someValue")   (normally false)

Returns:: Boolean

setTagName

public void setTagName(String tagName)
                throws IllegalStateException

Tag name to use when serializing to XML. If unspecified, the dataSource.ID will be used.

Note : This is an advanced setting

Parameters:: tagName - tagName Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientDataIntegration overview and related methods

getTagName

public String getTagName()

Tag name to use when serializing to XML. If unspecified, the dataSource.ID will be used.

Returns:: String
See Also:: ClientDataIntegration overview and related methods

setTitle

public void setTitle(String title)

User-visible name for this DataSource.

For example, for the supplyItem DataSource, "Supply Item".

Defaults to dataSource.ID.

Parameters:: title - title Default value is dataSource.ID

getTitle

public String getTitle()

User-visible name for this DataSource.

For example, for the supplyItem DataSource, "Supply Item".

Defaults to dataSource.ID.

Returns:: String

setTitleField

public void setTitleField(String titleField)
                   throws IllegalStateException

Best field to use for a user-visible title for an individual record from this dataSource.

For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.

If not explicitly set, titleField looks for fields named "title", "label", "name", and "id" in that order. If a field exists with one of those names, it becomes the titleField. If not, then the first field is designated as the titleField.

Parameters:: titleField - titleField Default value is see below
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: DsSpecialFields overview and related methods

getTitleField

public String getTitleField()

Best field to use for a user-visible title for an individual record from this dataSource.

For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.

Returns:: String
See Also:: DsSpecialFields overview and related methods

setUseFlatFields

public void setUseFlatFields(Boolean useFlatFields)
                      throws IllegalStateException

Like useFlatFields, but applies to all DataBound components that bind to this DataSource.

Parameters:: useFlatFields - useFlatFields Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getUseFlatFields

public Boolean getUseFlatFields()

Like useFlatFields, but applies to all DataBound components that bind to this DataSource.

Returns:: Boolean

setUseHttpProxy

public void setUseHttpProxy(Boolean useHttpProxy)
                     throws IllegalStateException

Like useHttpProxy, but serves as a default for this DataSource that may be overridden by individual operationBindings.

Parameters:: useHttpProxy - useHttpProxy Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: ClientDataIntegration overview and related methods

getUseHttpProxy

public Boolean getUseHttpProxy()

Like useHttpProxy, but serves as a default for this DataSource that may be overridden by individual operationBindings.

Returns:: Boolean
See Also:: ClientDataIntegration overview and related methods

setUseLocalValidators

public void setUseLocalValidators(Boolean useLocalValidators)

Whether to attempt validation on the client at all for this DataSource. If unset (the default), client-side validation is enabled.

Disabling client-side validation entirely is a good way to test server-side validation.

Note : This is an advanced setting

Parameters:: useLocalValidators - useLocalValidators Default value is null
See Also:: Validation overview and related methods

getUseLocalValidators

public Boolean getUseLocalValidators()

Whether to attempt validation on the client at all for this DataSource. If unset (the default), client-side validation is enabled.

Disabling client-side validation entirely is a good way to test server-side validation.

Returns:: Boolean
See Also:: Validation overview and related methods

setUseOfflineStorage

public void setUseOfflineStorage(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). Note that by default we do NOT use offline storage for a dataSource.

Parameters:: useOfflineStorage - useOfflineStorage Default value is null

getUseOfflineStorage

public 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). Note that by default we do NOT use offline storage for a dataSource.

Returns:: Boolean

setUseParentFieldOrder

public void setUseParentFieldOrder(Boolean useParentFieldOrder)
                            throws IllegalStateException

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. New fields, if any, are placed at the end.

Parameters:: useParentFieldOrder - useParentFieldOrder Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:: Schema Chaining Example

getUseParentFieldOrder

public Boolean getUseParentFieldOrder()

Returns:: Boolean
See Also:: Schema Chaining Example

setUseTestDataFetch

public void setUseTestDataFetch(Boolean useTestDataFetch)

When set, causes a 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 testDataFileName is specified on the DataSource.

Parameters:: useTestDataFetch - useTestDataFetch Default value is null

getUseTestDataFetch

public Boolean getUseTestDataFetch()

Returns:: Boolean

setValidateRelatedRecords

public void setValidateRelatedRecords(Boolean validateRelatedRecords)
                               throws IllegalStateException

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.

Parameters:: validateRelatedRecords - validateRelatedRecords Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getValidateRelatedRecords

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

Returns:: Boolean

setWillHandleAdvancedCriteria

public void setWillHandleAdvancedCriteria(Boolean willHandleAdvancedCriteria)

This property may be set to true to indicate that this dataSource supports advancedCriteria on fetch or filter type operations. See DataSource.supportsAdvancedCriteria for further information on this.

Note : This is an advanced setting

Parameters:: willHandleAdvancedCriteria - willHandleAdvancedCriteria Default value is null

getWillHandleAdvancedCriteria

public Boolean getWillHandleAdvancedCriteria()

Returns:: Boolean

convertRelativeDates

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

Parameters:: criteria - criteria to convert
Returns:: new copy of the criteria with all relative dates converted

convertRelativeDates

public Criteria convertRelativeDates(Criteria criteria,
                                     String timezoneOffset,
                                     int firstDayOfWeek)

Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.

Parameters:: criteria - criteria to convert; timezoneOffset - optional timezone offset. Defaults to the current timezone; firstDayOfWeek - first day of the week (zero is Sunday). Defaults to firstDayOfWeek
Returns:: new copy of the criteria with all relative dates converted

exportData

public void exportData()

Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results. See exportResults or exportResults and for more information.

exportData

public void exportData(Criteria criteria,
                       DSRequest requestProperties)

Parameters:: criteria - search criteria; requestProperties - additional properties to set on the DSRequest that will be issued
See Also:: Operations overview and related methods

getField

public DataSourceField getField(String fieldName)

Return the field definition object.

Parameters:: fieldName - Name of the field to retrieve
Returns:: field object

getFieldForDataPath

public DataSourceField getFieldForDataPath(String dataPath)

Return the field definition object corresponding to the supplied dataPath

Parameters:: dataPath - dataPath of the field to retrieve
Returns:: field object, or null if no field corresponds to the supplied dataPath

getLegalChildTags

public void getLegalChildTags()

For a DataSource that describes a DOM structure, the list of legal child elements that can be contained by the element described by this DataSource.

For a DataSource described by XML schema, this is the list of legal subelements of complexType (elements of simpleType become DataSourceFields with atomic type).

Note that currently, if an XML schema file contains ordering constraints, DataSources derived from XML Schema do not capture these constraints.

getPrimaryKeyField

public DataSourceField getPrimaryKeyField()

Returns a pointer to the primaryKey field for this DataSource

Returns:: primary key field object

getPrimaryKeyFieldName

public String getPrimaryKeyFieldName()

Returns the primary key fieldName for this DataSource

Returns:: primary key field name

addHandleErrorHandler

public HandlerRegistration addHandleErrorHandler(HandleErrorHandler handler)

Add a handleError handler.

If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other than STATUS_SUCCESS. You can use this hook to do DataSource-specific error handling. Unless you return false from this method, RPCManager.handleError will be called by Smart GWT right after this method completes.

Specified by:: addHandleErrorHandler in interface HasHandleErrorHandlers

Parameters:: handler - the handleError handler
Returns:: HandlerRegistration used to remove this handler

hasAllData

public Boolean hasAllData()

When cacheAllData is true, has all the data been retrieved to the client?

Returns:: All data has been fetched from the server and is available client-side

invalidateCache

public void invalidateCache()

Invalidate the cache when cacheAllData or clientOnly are true.

supportsAdvancedCriteria

public Boolean supportsAdvancedCriteria()

Do fetch and filter operations on this dataSource support being passed 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 and Hibernate DataSources in Smart GWT Enterprise or Power editions (not supported in Smart GWT Pro).

For custom dataSources which support AdvancedCriteria, a developer can set the willHandleAdvancedCriteria property to true.

Returns:: true if this dataSource supports being passed AdvancedCriteria in fetch and filter type operations, false otherwise.

supportsTextMatchStyle

public void supportsTextMatchStyle(TextMatchStyle textMatchStyle)

Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.

Parameters:: textMatchStyle - textMatchStyle to check. If passed a null value, assume an exact match is being requested.

updateCaches

public 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. This will cause cache managers such as 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.

Alternatively, an operation that removes a record from one DataSource may cause a new record to be added to another DataSource (such as Lead -> Account conversion in CRM applications). This could be accomplished by using the callback from the "remove" operation to call updateCaches with a DSResponse representing an "add" operation on the related DataSource.

NOTE:: this API should not be used with a clientOnly DataSource, because in this case, the "remote dataset" is actually within the browser. Instead, DataSource.updateData, addData() or removeData() can be called in order to both change the dataset stored inside the browser and notify all cache managers.

If a DataSource has cacheAllData set and a full cache has been obtained, calling updateCaches will automatically update the cache.

Note that this DSResponse will not go through DataSource.transformResponse or other processing that would normally occur for a DSResponse resulting from a DSRequest sent by the application in this page.

Parameters:: dsResponse -

updateCaches

public void updateCaches(DSResponse dsResponse,
                         DSRequest dsRequest)

If a DataSource has cacheAllData set and a full cache has been obtained, calling updateCaches will automatically update the cache.

Parameters:: dsResponse -; dsRequest -

validateData

public void validateData(Record values)

Contacts the server to run server-side validation on a DSRequest and either returns errors validation errors or a status code of 0.

A "validate" dsRequest is effectively always 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 (RPCManager.handleError).

Parameters:: values - record values to validate

validateData

public void validateData(Record values,
                         DSCallback callback,
                         DSRequest requestProperties)

Contacts the server to run server-side validation on a DSRequest and either returns errors validation errors or a status code of 0.

Parameters:: values - record values to validate; callback - callback to invoke on completion; requestProperties - additional properties to set on the DSRequest that will be issued
See Also:: Operations overview and related methods

onInit

protected void onInit()

Overrides:: onInit in class BaseClass

setID

public void setID(String id)

Overrides:: setID in class BaseClass

setAddGlobalId

public void setAddGlobalId(Boolean addGlobalId)
                    throws IllegalStateException

Whether to make this DataSource available as a global variable for convenience.

Note : This is an advanced setting

Parameters:: addGlobalId - addGlobalId Default value is true
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getAddGlobalId

public Boolean getAddGlobalId()

Whether to make this DataSource available as a global variable for convenience.

Returns:: Boolean

setDataProtocol

public void setDataProtocol(DSProtocol dataProtocol)
                     throws IllegalStateException

Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. May be overridden for individual request types using dataProtocol}

Parameters:: dataProtocol - dataProtocol Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

setDefaultParams

public void setDefaultParams(Map defaultParams)

HTTP parameters that should be submitted with every DSRequest.
Useful for authenticated services that require a sessionId with every request.
Can be set for all operations of a given DataSource as DataSource.defaultParams.

Parameters:: defaultParams - the default params

getDefaultParams

public Map getDefaultParams()

Returns:: the default params

getDataProtocol

public DSProtocol getDataProtocol()

Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. May be overridden for individual request types using dataProtocol}

Returns:: DSDataProtocol

transformRequest

protected Object transformRequest(DSRequest dsRequest)

For a dataSource using client-side data integration, return the data that should be sent to the DataSource.dataURL.

When using the Smart GWT Server Framework, use get(String,RequestTransformer,ResponseTransformer) instead of this API. Note that when using the Smart GWT Server Framework, there is no need to adapt the request data to the server (this is automatic), however the ability to modify the request before it is sent to the server is still valuable for use cases such as having an implicit criteria value that is always sent with all requests.

When contacting non-Smart GWT servers, an override of 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 but have their own protocol for how parameters must be passed.

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

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 DataSource.xmlSerialize().
Other reasons to implement transformRequest():

transform a Criteria object into the custom query language of a web service
add a session id to requests that require authentication
detect colliding updates by sending both updated values and the values the user originally retrieved before editing began (available as DSRequest.oldValues)

Note: This is an override point

Parameters:: dsRequest - the DSRequest being processed
Returns:: data to be sent to the dataURL (JavaScriptObject, String or Record)

transformResponse

protected void transformResponse(DSResponse response,
                                 DSRequest request,
                                 Object data)

Modify the DSResponse object derived from the response returned from the dataURL.

When using the Smart GWT Server Framework, use get(String,RequestTransformer,ResponseTransformer) instead of this API. Note that when using the Smart GWT Server Framework, there is no need to adapt the response data to the DSResponse (this is automatic), however the ability to modify response data before components receive it is still valuable for use cases such as doing expensive data transform client-side in order to reduce server load.

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 startRow) based on service-specific metadata fields contained in the service's response.

The dataFormat setting will govern whether the DSResponse passed to this method already has data set up as an array of records and how those records are derived:

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(java.lang.Object), 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 com.smartgwt.client.util.XMLTools#selectObjects. valueXPath is used to derive correctly typed field values.
dataFormat:"custom" : For custom dataSources, data is not already populated when this method runs. In this case the developer is responsible for taking the raw string value returned by the server (available as the data parameter to this method), parsing it into an array of records, and calling setData() on the response for subsequent processing to work.

In addition to dsResponse.data, status is defaulted to 0 (indicating no error), and 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:

setting 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:
```
 response.setStartRow(parseInt(XMLTools.selectString(data, "//resultRow")));
 
```
setting 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 RPCResponse.STATUS_VALIDATION_ERROR and filling in errors in order to cause validation errors to be shown in forms and grids.
for services that either do not return cache update data, or return partial data, using oldValues to create cache update data (whether this is appropriate is application-specific), or setting 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 overriden, that is, use the callback passed to high-level methods such as grid.fetchData(), and do error handling via either com.smartgwt.client.data.DataSource#handleError or by setting willHandleError.

Note: This is an override point

Parameters:: response - the response; request - the request; data - the raw data parameter. The type of this object depends on the specified dataFormat. if the dataFormat is custom, this will be a String. Otherwise this will be a JavaScript object. If the dataFormat is "json", the JavaScriptObject will be the raw JSON object(s) returned by the web service. If dataFormat is XML the JavaScriptObject will be the raw XML document object. Note that the JSOHelper and com.smartgwt.client.util.XMLTools utility classes can be used to work with these raw objects.

get

public static DataSource get(String ID)

Synonym of DataSource.getDataSource: Lookup a DataSource by ID.

Parameters:: ID - DataSource ID
Returns:: the DataSource with this ID, if loaded, otherwise null.

get

public static DataSource get(String ID,
                             RequestTransformer requestTransformer,
                             ResponseTransformer responseTransformer)

Synonym of DataSource.getDataSource: Lookup a DataSource by ID.

Parameters:: ID - DataSource ID; requestTransformer - the request transformer. Pass null to use the default transform; responseTransformer - the response transformer. Pass null to use the default transform
Returns:: the DataSource with this ID, if loaded, otherwise null.

getDataSource

public static DataSource getDataSource(String ID)

Lookup a DataSource by ID.

Parameters:: ID - DataSource ID
Returns:: the DataSource with this ID, if loaded, otherwise null.

getDataSource

public static DataSource getDataSource(String ID,
                                       RequestTransformer requestTransformer,
                                       ResponseTransformer responseTransformer)

Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer. The RequestTransformer and ResponseTransformer parameters provide the equivalent functionality of overriding 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.

Parameters:: ID - DataSource ID; requestTransformer - the request transformer. Pass null to use the default transform; responseTransformer - the response transformer. Pass null to use the default transform
Returns:: the DataSource with this ID, if loaded, otherwise null.

useOfflineResponse

protected boolean useOfflineResponse(DSRequest dsRequest,
                                     DSResponse dsResponse)

Override point to allow application code to suppress use of a particular offline response. For example, application code may wish to examine the response's 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

Parameters:: dsRequest - The dsRequest object; dsResponse - The corresponding dsResponse object returned from offline cache
Returns:: true to allow this response to be used, false to prevent it

getClientOnlyResponse

protected DSResponse getClientOnlyResponse(DSRequest request,
                                           Record[] serverData)

Return a "spoofed" response for a clientOnly or cacheAllData DataSource.

The default implementation will use DataSource.cacheData or testData 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 com.smartgwt.client.types.DSProtocol,'dataProtocol:"clientCustom"') instead.

Overriding this method is also a means of detecting that a normal DataSource (not clientOnly) would be contacting the server.

Note: This is an override point

Parameters:: request - DataSource request to respond to; for - cacheAllData DataSources, the data from the local cache
Returns:: DSResponse

isCreated

public boolean isCreated()

Overrides:: isCreated in class BaseClass

getJsObj

public JavaScriptObject getJsObj()

Overrides:: getJsObj in class BaseClass

setInheritsFrom

public void setInheritsFrom(DataSource inheritsFrom)
                     throws IllegalStateException

ID of another DataSource this DataSource inherits its DataSource fields from.

Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields. Fields with the same name are merged in the same way that databound component fields are merged with DataSource fields.

The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can 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 creating a customized view (eg, only certain fields shown) which will be used bymultiple databound components.adding presentation-specific attributes to metadata that has been automatically derived from 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.

Parameters:: inheritsFrom - the datasource to inherit from
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

setFields

public void setFields(DataSourceField... fields)
               throws IllegalStateException

The list of fields that compose records from this DataSource.

Each DataSource field can have type, user-visible title, validators, and other metadata attached.

Parameters:: fields - fields Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

addField

public void addField(DataSourceField field)
              throws IllegalStateException

Add a field to the DataSource

Parameters:: field - the datasource field
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

getFields

public DataSourceField[] getFields()

The list of fields that compose records from this DataSource.

Each DataSource field can have type, user-visible title, validators, and other metadata attached.

Returns:: array of DataSourceFields

getDisplayValue

public Object getDisplayValue(String fieldName,
                              Object value)

Given a fieldName and a dataValue, apply any valueMap for the field and return the display value for the field. If the field has no specified valueMap or the value does not resolve to an entry in the valueMap it will be returned unaltered.

Parameters:: fieldName - name of the field to retrieve a value for; value - data value for the field
Returns:: display value for the field

setTestData

public void setTestData(DataClass[] testData)

For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.

See this discussion for ways to populate a client-only DataSource with test data.

Parameters:: testData - testData Default value is null

getTestData

public DataClass[] getTestData()

For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.

See this discussion for ways to populate a client-only DataSource with test data.

Returns:: the test data

setRecordName

public void setRecordName(String recordName)
                   throws IllegalStateException

See recordName. recordName can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations.

Parameters:: recordName - Default value is null
Throws:: IllegalStateException - this property cannot be changed after the underlying component has been created

fetchData

public void fetchData(Criteria criteria,
                      DSCallback callback)

See fetchData(Criteria,DSCallback,DSRequest).

Parameters:: criteria - search criteria; callback - callback to invoke on completion

fetchData

public void fetchData(Criteria criteria,
                      DSCallback callback,
                      DSRequest requestProperties)

Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

In contrast to ListGrid.fetchData(), which populates the ListGrid with data, calling dataSource.fetchData() does not automatically update any visual components or caches: code in the DSCallback passed to fetchData() decides what to do with the returned data.

A DSResponse object is provided via the DSCallback - the DSResponse allows you to get the returned data as simple Record Array or RecordList collection.

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 as a static variable, 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.allCountries.getValueMap("countryId", "countryName");
   select.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.data());
      }
   });

This gives you a dataset that supports client-side filtering (via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)), can provide valueMaps, will automatically update cache when changes are saved and can be re-used with multiple visual components.

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

Parameters:: criteria - search criteria; callback - callback to invoke on completion; requestProperties - additional properties to set on the DSRequest that will be issued

filterData

public void filterData(Criteria criteria,
                       DSCallback callback)

Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

This is identical to fetchData(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.DSCallback) except that textMatchStyle is set to "substring" to cause case insensitive substring matching (if the server respects this setting).

Parameters:: criteria - search criteria; callback - callback to invoke on completion

filterData

public void filterData(Criteria criteria,
                       DSCallback callback,
                       DSRequest requestProperties)

addData

public void addData(Record record)

Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.

Parameters:: record - new record

addData

public void addData(Record record,
                    DSCallback callback)

Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.

Parameters:: record - new record; callback - callback to invoke on completion

addData

public void addData(Record record,
                    DSCallback callback,
                    DSRequest requestProperties)

Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.

Parameters:: record - new record; callback - callback to invoke on completion; requestProperties - additional properties to set on the DSRequest that will be issued

updateData

public void updateData(Record record)

Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.

Parameters:: record - updated record

updateData

public void updateData(Record record,
                       DSCallback callback)

Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.

Parameters:: record - updated record; callback - callback to invoke on completion

updateData

public void updateData(Record record,
                       DSCallback callback,
                       DSRequest requestProperties)

Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.

Parameters:: record - updated record; callback - callback to invoke on completion; requestProperties - additional properties to set on the DSRequest that will be issued

removeData

public void removeData(Record record)

Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.

Parameters:: record - primary key values of record to delete, (or complete record)

removeData

public void removeData(Record record,
                       DSCallback callback)

Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.

Parameters:: record - primary key values of record to delete, (or complete record); callback - callback to invoke on completion

removeData

public void removeData(Record record,
                       DSCallback callback,
                       DSRequest requestProperties)

Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.

Parameters:: record - primary key values of record to delete,(or complete record); callback - callback to invoke on completion; requestProperties - additional properties to set on the DSRequest that will be issued

copyRecords

public 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. This method calls DataSource#copyRecord() for each item in the array.

Parameters:: records -
Returns:: Record[]

copyRecord

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

Parameters:: record - to be copied
Returns:: Record

xmlSerialize

public String xmlSerialize(JavaScriptObject data)

Serialize a JavaScript object as XML.

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:


     var inputObject = {
        startRow : 5,
        endRow : 50,
        data : [
           { field1 : "value1", field2: new Date() },
           { field1 : "value3", field2: null }
        ]
     };
     var myDS = isc.DataSource.create({ tagName:"DSRequest" });
     myDS.xmlSerialize(inputObject);

.. produces the following XML:


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

If you are working with a WSDL-described web service, XML serialization is performed automatically by APIs like WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback) - you only need to know about serialization in order to understand how to put together JavaScript data that will fill in an XML message properly.
Note: when trying to send data to a web service, it is best to avoid putting together any XML yourself, instead modify the JavaScript data being fed to ISC's SOAP engine. This is because the WSDL and SOAP rules for correctly namespacing and encoding Web Service messages are very complex and are subject to change with new versions of the web service you are contacting, whereas the data itself is easy to manipulate and less likely to change.
To troubleshoot message formation, you can set the log category "xmlComm" to DEBUG level in order to see the XML message formed by Smart GWT reported in log statements in the Developer Console.

Parameters:: data - data to be serialized
Returns:: data as serialized to XML

xmlSerialize

public String xmlSerialize(JavaScriptObject data,
                           SerializationContext flags)

Serialize a JavaScript object as XML.


     var inputObject = {
        startRow : 5,
        endRow : 50,
        data : [
           { field1 : "value1", field2: new Date() },
           { field1 : "value3", field2: null }
        ]
     };
     var myDS = isc.DataSource.create({ tagName:"DSRequest" });
     myDS.xmlSerialize(inputObject);

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

Parameters:: data - data to be serialized; flags - options for the serialization engine
Returns:: data as serialized to XML

xmlSerialize

public String xmlSerialize(Record data,
                           SerializationContext flags)

Serialize a JavaScript object as XML.


     var inputObject = {
        startRow : 5,
        endRow : 50,
        data : [
           { field1 : "value1", field2: new Date() },
           { field1 : "value3", field2: null }
        ]
     };
     var myDS = isc.DataSource.create({ tagName:"DSRequest" });
     myDS.xmlSerialize(inputObject);

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

Parameters:: data - data to be serialized; flags - options for the serialization engine
Returns:: data as serialized to XML

xmlSerialize

public String xmlSerialize(Record[] data,
                           SerializationContext flags)

Serialize a JavaScript object as XML.


     var inputObject = {
        startRow : 5,
        endRow : 50,
        data : [
           { field1 : "value1", field2: new Date() },
           { field1 : "value3", field2: null }
        ]
     };
     var myDS = isc.DataSource.create({ tagName:"DSRequest" });
     myDS.xmlSerialize(inputObject);

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

Parameters:: data - data to be serialized; flags - options for the serialization engine
Returns:: data as serialized to XML

xmlSerialize

public String xmlSerialize(Map data,
                           SerializationContext flags)

Serialize a JavaScript object as XML.


     var inputObject = {
        startRow : 5,
        endRow : 50,
        data : [
           { field1 : "value1", field2: new Date() },
           { field1 : "value3", field2: null }
        ]
     };
     var myDS = isc.DataSource.create({ tagName:"DSRequest" });
     myDS.xmlSerialize(inputObject);

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

Parameters:: data - data to be serialized; flags - options for the serialization engine
Returns:: data as serialized to XML

processResponse

public void processResponse(String requestId,
                            DSResponse responseProperties)

Process a dsResponse for a request initiated by a DataSource with dataProtocol. requestId parameter should be dsRequest.requestId as found on the dsRequest passed to transformRequest(com.smartgwt.client.data.DSRequest).

You must provide a response for both error and non-error cases. For an error case, a sufficient response is:

 { status : -1 }

Parameters:: requestId - requestId attribute from the associated dataSource request object; responseProperties - Configuration for the dsResponse

recordsFromXML

public Record[] recordsFromXML(Object elements)

Transform a list of XML elements to DataSource records.

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.

Parameters:: elements - XML elements to transform, eg, the result of a call to XMLTools.selectNodes(Object, String)
Returns:: list of DataSource records derived from the XML elements

getFieldNames

public String[] getFieldNames()

Retrieves the list of fields declared on this DataSource.

Returns:: names of all fields declared on this DataSource, including fields that are marked hidden

getFieldNames

public String[] getFieldNames(boolean excludeHidden)

Retrieves the list of fields declared on this DataSource.

Parameters:: excludeHidden - If true, returns only those fields that are not marked as hidden
Returns:: names of all fields declared on this DataSource

downloadFile

public void downloadFile(Record data)

Download a file stored in a field of type:"binary" in a DataSource record.

This will trigger the browser's "Save As" dialog and allow the user to save the file.

Parameters:: data - primary key values of record containing the file to download (or the complete record)

downloadFile

public void downloadFile(Record data,
                         String fieldName,
                         DSRequest requestProperties)

Download a file stored in a field of type:"binary" in a DataSource record.

This will trigger the browser's "Save As" dialog and allow the user to save the file.

Parameters:: data - primary key values of record containing the file to download (or the complete record); fieldName - optional name of the binary field containing the file. If not provided, the first binary field is used; requestProperties - additional properties to set on the DSRequest that will be issued

viewFile

public void viewFile(Record data)

Display a file stored in a field of type:"binary" in a new browser window.

This will open a new browser window to show the file. Depending on the file type, the user's installed plugins and applications, and the user's browser settings, this may cause the file to be actually displayed in the new browser window, or may prompt the user to either launch an external application to view the file or save the file to disk.

Parameters:: data - primary key values of record containing the file to view (or the complete record)

viewFile

public void viewFile(Record data,
                     String fieldName,
                     DSRequest requestProperties)

Display a file stored in a field of type:"binary" in a new browser window.

Parameters:: data - primary key values of record containing the file to view (or the complete record); fieldName - optional name of the binary field containing the file. If not provided, the first binary field is used; requestProperties - additional properties to set on the DSRequest that will be issued

load

public static void load(String dsID,
                        Function callback,
                        boolean forceReload)

Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired.

To force reloading of DataSources that have already been loaded, pass true in the forceReload parameter.

Parameters:: dsID - DataSource ID; callback - Callback to fire after DataSource loading completes; forceReload - Forcibly reload a dataSource if it's already loaded

load

public static void load(String[] dsID,
                        Function callback,
                        boolean forceReload)

To force reloading of DataSources that have already been loaded, pass true in the forceReload parameter.

Parameters:: dsID - Array of DataSource IDs; callback - Callback to fire after DataSource loading completes; forceReload - Forcibly reload a dataSource if it's already loaded

getSortBy

public static String[] getSortBy(String[] sortSpecifiers)

Given an array of ${isc.DocUtils.linkForRef('object:SortSpecifier')}s, return a simple list of Strings in the format expected by sortBy.

Parameters:: sortSpecifiers - The list of specifiers to return in sortBy format
Returns:: An array of sort-definitions in the format expected by sortBy

getSortSpecifiers

public static String[] getSortSpecifiers(String[] sortBy)

Return a an array of ${isc.DocUtils.linkForRef('object:SortSpecifier')}s, given an array of Strings in the format expected by sortBy.

Parameters:: sortBy - A list of sortBy strings in the format expected by sortBy
Returns:: An array of ${isc.DocUtils.linkForRef('SortSpecifiers')} equivalent to the passed in string array

exportClientData

public void exportClientData(Object[] data,
                             DSRequest requestProperties)

Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users. This method can be used to export data formatted outside of any kind of visual component.

Requires the Smart GWT server, but does not rely on any server-side DataSources.

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.

Parameters:: data - Records to export, similar to ListGrid.data; requestProperties - Request properties for the export

performCustomOperation

public void performCustomOperation(String operationId,
                                   Record data,
                                   DSCallback callback,
                                   DSRequest requestProperties)

Invoke an operation declared with 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" com.smartgwt.client.types.DSOperationType,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(Record, DSCallback, DSRequest) - this will cause com.smartgwt.client.data.ResultSet,cache sync to work correctly.

In particular:

do not use this API just because you need to add additional server-side logic to a CRUD operation (com.smartgwt.client.docs.DmiOverview,DMI allows this)
do not use this API to implement variants of core CRUD operations (DSRequest.setOperationId(java.lang.String) is the correct way to do this)
do not use this API just because an operation affects more than one record. Most kinds of multi-record operations should use com.smartgwt.client.data.RPCManager#startQueue(),queuing.
do not use this API just because you are calling a stored procedure in SQL - if the stored procedure performs some kind of CRUD operation on the records of this DataSource, use a standard CRUD operationType

The primary purpose of this API is to allow operations on a SQLDataSource where com.smartgwt.client.data.OperationBinding.setCustomSQL(),customSQL is defined which performs a SQL operation other than SELECT, UPDATE, INSERT, DELETE (such as creating a new table). In this case, actions that the SQLDataSource normally takes for CRUD operations (such as requiring primary keys to be passed for updates, or retrieving the updated row to return to the client) are inappropriate. By declaring OperationBinding.operationType "custom" in your .ds.xml file, you cause these actions to be skipped and your <customSQL> can do arbitrary things.

The "data" parameter becomes com.smartgwt.client.data.DSRequest#getData(),DSRequest.data. With the SmartClient Server Framework, the data is accessible server-side via DSRequest.getValues() and in Velocity templates (such as <customSQL>) as $values.

Parameters:: operationId - the operation ID; data - data to pass to the server; callback - callback to invoke on completion; requestProperties - additional properties to set on the DSRequest that will be issued
See Also:: Operations overview and related methods

getFileURL

public void getFileURL(Record data)

Returns a direct URL to access a file stored in a field of type:"binary".

This URL as 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 DataSource.downloadFile and DataSource.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.

Similarly, accessing this URL has the same performance as using DataSource.downloadFile.

Parameters:: data - Record (including primary key value) containing the file to view.

setXmlNamespaces

public void setXmlNamespaces(XmlNamespaces xmlNamespaces)
                      throws IllegalStateException

Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions. xmlNamespaces should be specified as a map ping from namespace prefix to namespace URI, for example:

xmlNamespaces : { az : "http://webservices.amazon.com/AWSECommerceService/2005-03-23" }
By default, all namespaces declared on the document element (outermost element of the response) are made available with the prefix used in the document itself. Then, for non-WSDL-described XML results, if there i s a default namespace on the document element, it is made available with the special prefix "default".

For results of WSDL-described operations, the prefix "service" means the service namespa ce, that is, the "targetNamespace" on the element from the WSDL file. The prefix "schema" means the names pace of the outermost element in the output message for the current operation. "default" will be the schema na mespace if there is one, otherwise the service namespace.
For basic information on XML Namespaces and their use in XPath, try the following search: http://www.google.com/search?q=XPath+xml+namespaces

Parameters:: xmlNamespaces - xml namespaces
Throws:: IllegalStateException - this property cannot be changed after the underlying compo nent has been created

setTypeOperators

public void setTypeOperators(FieldType fieldType,
                             OperatorId[] operators)

Set the list of OperatorIds valid for a given FieldType.

Parameters:: fieldType - the field type; operators - available Operators

getTypeOperators

public OperatorId[] getTypeOperators(FieldType fieldType)

Get the list of OperatorIds available on this DataSource for the given FieldType.

If DataSource.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 DataSource.addSearchOperator().

Parameters:: fieldType - the field type
Returns:: the available Operators

getFieldOperators

public OperatorId[] getFieldOperators(String fieldName)

Get the list of OperatorId's available for this field. By default if the validOperators is set on the DataSourceField, it returns the list, otherwise returns the result of getTypeOperators(com.smartgwt.client.types.FieldType).

Parameters:: fieldName - the field name to obtain operators for
Returns:: the available Operators

getFieldOperators

public OperatorId[] getFieldOperators(DataSourceField field)

Parameters:: field - the field to obtain operators for
Returns:: the available Operators

combineCriteria

public static Criteria combineCriteria(Criteria criteria1,
                                       Criteria criteria2)

Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator". Note that the combined criteria object will be an AdvancedCriteria unless:

both input criteria objects are simple, and
the "outerOperator" is "and", and
there is no collision of key names on the two criteria

Parameters:: criteria1 - first criteria object; criteria2 - second criteria object
Returns:: The combined criteria
See Also:: Dynamic Reporting Example

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.smartgwt.client.data Class DataSource

DataSource

DataSource

DataSource

getOrCreateRef

create

setAutoCacheAllData

getAutoCacheAllData

setAutoConvertRelativeDates

getAutoConvertRelativeDates

setAutoDeriveTitles

getAutoDeriveTitles

setCacheAllData

getCacheAllData

setCacheData

getCacheData

setCacheMaxAge

getCacheMaxAge

setCallbackParam

getCallbackParam

setCanMultiSort

getCanMultiSort

setChildrenField

getChildrenField

setClientOnly

getClientOnly

setCriteriaPolicy

getCriteriaPolicy

setDataField

getDataField

setDataFormat

getDataFormat

setDataTransport

getDataTransport

setDataURL

getDataURL

setDescriptionField

getDescriptionField

setDropExtraFields

getDropExtraFields

setEnumConstantProperty

setEnumOrdinalProperty

setEnumTranslateStrategy

setGlobalNamespaces

getGlobalNamespaces

setIconField

getIconField

setInfoField

getInfoField

setInheritsFrom

getInheritsFrom

setJsonPrefix

getJsonPrefix

setJsonSuffix

getJsonSuffix

setOperationBindings

getOperationBindings

setPluralTitle

getPluralTitle

setPreventHTTPCaching

getPreventHTTPCaching

setQualifyColumnNames

getQualifyColumnNames

setRecordXPath

getRecordXPath

setRequestProperties

getRequestProperties

setRequiredMessage

getRequiredMessage

setResultBatchSize

getResultBatchSize

setResultSetClass

getResultSetClass

getSchemaNamespace

setSendExtraFields

getSendExtraFields

setServiceNamespace

getServiceNamespace

setShowLocalFieldsOnly

getShowLocalFieldsOnly

com.smartgwt.client.data
Class DataSource