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 custom databinding-capable components.

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".
`static Criteria`	`combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator, TextMatchStyle textMatchStyle)` 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.
`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`	`fetchData()` Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
`void`	`fetchData(Criteria criteria)` Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
`void`	`fetchData(Criteria criteria, DSCallback callback)` Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
`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)` 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.
`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`	`getAutoDeriveSchema()` For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from the SQL table specified in `tableName`.
`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`.
`String`	`getBeanClassName()` This property has different meanings depending on the `serverType`:
`Boolean`	`getCacheAllData()` Set this property to true to have a DataSource fetch all of it's 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".
`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. 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.
`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)` Return a "spoofed" response for a `clientOnly` DataSource.
`CriteriaPolicy`	`getCriteriaPolicy()` Decides under what conditions the `ResultSet` cache should be dropped when the `criteria` changes.
`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.
`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.
`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.
`String[]`	`getFieldNames()` Retrieves the list of fields declared on this DataSource.
`String[]`	`getFieldNames(boolean excludeHidden)` Retrieves the list of fields declared on this DataSource.
`DataSourceField[]`	`getFields()` The list of fields that compose records from this DataSource.
`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`.
`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.
`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`.
`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`	`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`	`getServerConstructor()` Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource.
`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. Specifically, when a field has NULL value, all of the following expressions are false:
`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.
`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`	`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`	`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)` Perform a custom DataSource operation against this DataSource.
`void`	`performCustomOperation(String operationId, Record data, DSCallback callback, DSRequest requestProperties)` Perform a custom DataSource operation against this DataSource.
`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`	`setAutoDeriveSchema(Boolean autoDeriveSchema)` For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from the SQL table specified in `tableName`.
`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`	`setBeanClassName(String beanClassName)` This property has different meanings depending on the `serverType`:
`void`	`setCacheAllData(Boolean cacheAllData)` Set this property to true to have a DataSource fetch all of it's 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".
`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. 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.
`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`	`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`	`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`	`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`	`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`	`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`	`setSendExtraFields(Boolean sendExtraFields)` Analogous to `dropExtraFields`, for data sent to the server.
`void`	`setServerConstructor(String serverConstructor)` Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource.
`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. Specifically, when a field has NULL value, all of the following expressions are false:
`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`	`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`	`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`	`setXmlNamespaces(XmlNamespaces xmlNamespaces)` Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions.
`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.
`void`	`validateData()` 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.

Methods inherited from class com.smartgwt.client.core.BaseClass
destroy, doAddHandler, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getScClassName, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setID, 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, getAttributeAsString, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getScClassName, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setID, 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

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

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

setAutoDeriveSchema

public void setAutoDeriveSchema(Boolean autoDeriveSchema)
                         throws IllegalStateException

For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from the SQL table specified in tableName. This causes Smart GWT to create a "super" DataSource, which this dataSource then automatically inheritsFrom. This allows you to override auto-derived schema as required.

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

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

getAutoDeriveSchema

public Boolean getAutoDeriveSchema()

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

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

setBeanClassName

public void setBeanClassName(String beanClassName)
                      throws IllegalStateException

This property has different meanings depending on the serverType:

For DataSources with serverType "hibernate"
The name of the Java bean or POJO class that is mapped in Hibernate. This will typically be the fully-qualified class name - eg com.foo.MyClass - but it may be the simple class name - just MyClass - or it may be some other value. It all depends on how your classes have been mapped in Hibernate.

Note: If you are intending to use Hibernate as a data-access layer only, you do not need to create Hibernate mappings or Java objects: Smart GWT will generate everything it needs on the fly.

For DataSources with serverType "sql"
If set, results from the database will be used to create one instance of the indicated Java bean per database row. Otherwise a Map is used to represent each row retrieved from SQL.

With this feature active, a DSResponse from this DataSource will contain a Collection of instances of the indicated beanClassName, available via DSResponse.getData(). This creates a couple of possibilities:

Add business logic for derived properties, such as computed formulas: For example, declare a DataSourceField named "revenueProjection". By default this field will call getRevenueProjection() on your bean to retrieve the value to send to the client. Your implementation of getRevenueProjection() could apply some kind of formula to other values loaded from the database.
Call business logic on retrieved beans via DMI: By adding a DMI method that calls DSRequest.execute() to retrieve a DSResponse, you have an opportunity to call business logic methods on the beans representing each row affected by the DSRequest. For example, notify a related BPEL process of changes to certain fields.

By using beanClassName on a specific OperationBinding, you can:

Use a bean to represent your data only when it matters; for example, avoid the overhead of using a bean for "fetch" operations, but do use a bean for "update" operations so that you can execute relevant business logic after the update completes.
Skip the use of beans for complex reporting queries that produce results unrelated to your persistent object model. Set beanClassName to blank ("") on a specific operationBinding to override DataSource.beanClassName for that specific operation.
For SQL joins that produce additional data fields, use a special, operation-specific bean that represents a join of multiple entities and contains business logic specific to that joined dataset

Note that setting beanClassName has no effect on the DSRequest. However, DMI has a built-in facility for populating a bean with the inbound data - just declare the bean as a method argument.

For DataSources with serverType "generic"
Visual Builder sets this property when it creates a generic DataSource using the Javabean Wizard. It has no built-in server-side effects.

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

getBeanClassName

public String getBeanClassName()

This property has different meanings depending on the serverType:

Note: If you are intending to use Hibernate as a data-access layer only, you do not need to create Hibernate mappings or Java objects: Smart GWT will generate everything it needs on the fly.

Add business logic for derived properties, such as computed formulas: For example, declare a DataSourceField named "revenueProjection". By default this field will call getRevenueProjection() on your bean to retrieve the value to send to the client. Your implementation of getRevenueProjection() could apply some kind of formula to other values loaded from the database.
Call business logic on retrieved beans via DMI: By adding a DMI method that calls DSRequest.execute() to retrieve a DSResponse, you have an opportunity to call business logic methods on the beans representing each row affected by the DSRequest. For example, notify a related BPEL process of changes to certain fields.

By using beanClassName on a specific OperationBinding, you can:

Use a bean to represent your data only when it matters; for example, avoid the overhead of using a bean for "fetch" operations, but do use a bean for "update" operations so that you can execute relevant business logic after the update completes.
Skip the use of beans for complex reporting queries that produce results unrelated to your persistent object model. Set beanClassName to blank ("") on a specific operationBinding to override DataSource.beanClassName for that specific operation.
For SQL joins that produce additional data fields, use a special, operation-specific bean that represents a join of multiple entities and contains business logic specific to that joined dataset

Note that setting beanClassName has no effect on the DSRequest. However, DMI has a built-in facility for populating a bean with the inbound data - just declare the bean as a method argument.

For DataSources with serverType "generic"
Visual Builder sets this property when it creates a generic DataSource using the Javabean Wizard. It has no built-in server-side effects.

Returns:: String

setCacheAllData

public void setCacheAllData(Boolean cacheAllData)

Set this property to true to have a DataSource fetch all of it's 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 and 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. 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()

Set this property to true to have a DataSource fetch all of it's 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 and 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.






Returns:
Boolean





setCacheData
public void setCacheData(Record[] cacheData)
                  throws IllegalStateException

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.
 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
Throws:
IllegalStateException - this property cannot be changed after the underlying component has been created





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".  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:
ClientDataIntegration overview and related methods, 
Edit and Save Example





getCallbackParam
public String getCallbackParam()

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






Returns:
String
See Also:
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:
DataSourceRelations overview and related methods





getChildrenField
public String getChildrenField()

fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
 Enables loading a
 databound tree as a hierarchical data structure, rather than a flat list of
 nodes linked by foreignKey.


 Note this is an alternative to 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.






Returns:
String
See Also:
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.
 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()

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.






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"





getCriteriaPolicy
public CriteriaPolicy getCriteriaPolicy()

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






Returns:
CriteriaPolicy





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





getDataTransport
public RPCTransport getDataTransport()

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.






Returns:
RPCTransport
See Also:
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





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






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





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





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. 
 If not explicitly
 set, iconField looks for fields named "picture", "thumbnail", "icon", "image" and "img", in that order, and will use any
 of these fields as the iconField if it exists and has type "image".  
 To avoid any field being used as the iconField,
 set iconField to null.






Returns:
String





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





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. 

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






Returns:
String





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





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





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





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





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





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

Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP
 response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog
 appearing for an end user.  If you have a relatively small number of records with a great deal of properties or
 subobjects on each record, and you have not set dropExtraFields to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this
 number lower.






Returns:
int





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

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.






Returns:
Boolean
See Also:
ClientDataIntegration overview and related methods





setServerConstructor
public void setServerConstructor(String serverConstructor)
                          throws IllegalStateException

Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this
 dataSource. This property allows you to write and use custom DataSource  subclasses on the server.  One reason you
 might wish to do this would be to override the validate() method to provide  some arbitrary custom validation (such as
 complex database lookups, validation embedded in  legacy applications, etc).  It is also possible - though obviously a
 more substantial task - to override the execute() method in your custom DataSource.  This is one way of creating  a
 completely customized DataSource implementation. 
 Note: If you use this property, you are responsible for
 making sure that it refers to a valid server-side class that extends
 com.isomorphic.datasource.BasicDataSource. If your implementation relies on methods or state only present
 in certain specialized  subclasses of DataSource (for example, you want the normal behavior and features of a 
 HibernateDataSource, but with a specialized validate() method), then you should extend the  subclass rather than the
 base class.





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





getServerConstructor
public String getServerConstructor()

Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this
 dataSource. This property allows you to write and use custom DataSource  subclasses on the server.  One reason you
 might wish to do this would be to override the validate() method to provide  some arbitrary custom validation (such as
 complex database lookups, validation embedded in  legacy applications, etc).  It is also possible - though obviously a
 more substantial task - to override the execute() method in your custom DataSource.  This is one way of creating  a
 completely customized DataSource implementation. 
 Note: If you use this property, you are responsible for
 making sure that it refers to a valid server-side class that extends
 com.isomorphic.datasource.BasicDataSource. If your implementation relies on methods or state only present
 in certain specialized  subclasses of DataSource (for example, you want the normal behavior and features of a 
 HibernateDataSource, but with a specialized validate() method), then you should extend the  subclass rather than the
 base class.






Returns:
String





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

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






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

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






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

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






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





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






Returns:
String





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





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

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.






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

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.






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





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





getField
public DataSourceField getField(String fieldName)

Return the field definition object.





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





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.











performCustomOperation
public void performCustomOperation(String operationId,
                                   Record data)

Perform a custom DataSource operation against this DataSource.  A custom operation is anything that is not one of the 4
 CRUD operations - generally, something that is more  complex than a fetch or an update to a single record. 
 customOperations  are an alternative to using RPCs; anything
 that can be sent to the server as a plain RPC can instead be framed as a DataSource  customOperation.





Parameters:
operationId - the operation ID
data - data to pass to the server





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

Perform a custom DataSource operation against this DataSource.  A custom operation is anything that is not one of the 4
 CRUD operations - generally, something that is more  complex than a fetch or an update to a single record. 
 customOperations  are an alternative to using RPCs; anything
 that can be sent to the server as a plain RPC can instead be framed as a DataSource  customOperation.





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





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. 
 Cache updates of this kind can also be driven from server-side code - see the related
 server-side API DSResponse.addRelatedUpdate(). 
 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)

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. 
 Cache updates of this kind can also be driven from server-side code - see the related
 server-side API DSResponse.addRelatedUpdate(). 
 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 - 
dsRequest - 





validateData
public void validateData()

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











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





combineCriteria
public static Criteria combineCriteria(Criteria criteria1,
                                       Criteria criteria2,
                                       CriteriaCombineOperator outerOperator,
                                       TextMatchStyle textMatchStyle)

Combines two criteria (either simple criteria objects or AdvancedCriteria) using the  "outerOperator".  Note that the
 combined criteria object will be an AdvancedCriteria unless  both input criteria objects are simple, and
 the "outerOperator" is "and", and
 there is no collision of key names on the two criteria
 





Parameters:
criteria1 - first criteria object
criteria2 - second criteria object
outerOperator - operator to use to combine the criteria.                                           Defaults to "and"
textMatchStyle - style of matching text, if it is necessary to                                          convert a simple criteria object
 to an                                           AdvancedCriteria.  Defaults to "substring"
Returns:
The combined criteria
See Also:
Dynamic Reporting Example





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.





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.





onInit
protected void onInit()


Overrides:
onInit in class BaseClass








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

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






Returns:
the default params





getDataProtocol
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. 
 By default, HTTP requests sent to non-Smart GWT servers do not include DSRequest
 metadata such as DSRequest.startRow, endRow, and oldValues. Only the core datasource protocol data is sent, such
 as the criteria passed to fetchData() or the updated values submitted by form.saveData(). 
 transformRequest()
 allows you to transform dsRequest metadata into a format understood by your server and include it in the HTTP
 request, so that you can integrate DataSource features such as data paging with servers that support such
 features. 
 How the data is actually sent to the URL is controlled by OperationBinding.dataProtocol. If using
 the "getParams" or "postParams" protocol, data is expected to be a JavaScript Object where each property will
 become a GET or POST'd parameter. If using dataProtocol:"soap" or "postXML", data will be serialized as an XML
 message by 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.  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 DSResponse
 passed to this method already has data, which is derived
 differently depending on the dataFormat setting: 

  dataFormat:"xml" : either the recordXPath or  recordName is used to select the
 XML elements that represent DataSource records.  The selected XML elements are passed to recordsFromXML(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" : dsResponse.data is the raw response in String form.
 It must be parsed into an Array of Objects for subsequent processing to work. 
   In addition to
 dsResponse.data, 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: dsResponse.startRow =         isc.XMLTools.selectNumber(xmlData, "//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 - 





getClientOnlyResponse
protected DSResponse getClientOnlyResponse(DSRequest request)

Return a "spoofed" response for a clientOnly DataSource.
 
 The default implementation will testData to provide an appropriate
 response, by using com.smartgwt.client.data.DataSource#applyFilter for a "fetch" request, and
 by modifying the testData 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 provides, such as
 GWT-RPC, HTML5 sockets, or bridges to plug-in based protocols (Java, Flash,
 Silverlight..), use ${isc.DocUtils.linkForRef('DSDataProtocol','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
Returns:
DSResponse





isCreated
public boolean isCreated()


Overrides:
isCreated in class BaseClass








getJsObj
public JavaScriptObject getJsObj()


Overrides:
getJsObj in class BaseClass








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 transformRequest(com.smartgwt.client.data.DSRequest) is called.





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





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





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.  For DataSources bound to WSDL-described web services using serviceNamespace , OperationBindings are
 used to bind each DataSource operationType to an operation of a WSDL-described web service, so that a DataSource can both fetch and save data to a web service. 
 For example,
 this code accomplishes part of the binding to the  SalesForce partner web
 services
 
  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
 isomorphicSDK/examples/databinding/SalesForce. 
 For DataSources that contact non-WSDL-described XML or JSON
 services, OperationBindings can be used to separately configure the URL, HTTP method, input and output processing
 for each operationType.  This makes it possible to fetch JSON data from one URL for the "fetch" operationType and
 save to a web service for the "update" operationType, while appearing as a single integrated DataSource to a DataBoundComponent such as an editable ListGrid. 
 
 If no operationBinding is defined for a given DataSource operation,
 all of the properties which are valid on the operationBinding are checked for on the DataSource itself. 

 This also means that 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: 
 /examples/databinding/rss_databinding.html 

See Also:
  OperationBinding 







Parameters:
operationBindings - the operation bindings
Throws:
IllegalStateException - this property cannot be changed after the underlying component has been created





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





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 mapping from namespace
 prefix to namespace URI, for example: 

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

 

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





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





fetchData
public void fetchData()

Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching
 records.  In contrast to ListGrid.fetchData(), which creates a ResultSet to manage the returned data, calling dataSource.fetchData()
 provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects.  Calling
 dataSource.fetchData() does not automatically update any visual components or caches: code in the
 callback passed to fetchData() decides what to do with the returned data.  
 For example, given a
 ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched
 from
 the DataSource: 
    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");  Unlike
 calling myGrid.fetchData(), which creates a ResultSet, the data
 provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
 directly modify.  This is useful when, for example, a ListGrid is being used as a more sophisticated version of
 HTML's multi-select component.  Disconnected datasets may be used to populate various visual components.  For
 example, while an individual FormItem can be configured to fetch valueMap options from a DataSource via the optionDataSource property, the following code shows storing a dataset to derive valueMaps from later: 
 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 
  You can also create a ResultSet from the data retrieved from
 fetchData(), like so: 
    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 
  This gives you a dataset that supports client-side filtering
 (via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)), can provide  ResultSet.getValueMap(java.lang.String, java.lang.String), will  disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual
 components. 
 See also the server-side com.isomorphic.js.JSTranslater class in the
 ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
 involving dumping data into the page during initial page load.  Note: care should be taken when using this
 approach.  Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets
 that may become very large. 
 Data-Driven Visual Component Creation 

 DataSource.fetchData() can also be used to create Smart GWT components in a data-driven way.  Many
 properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
 dataSource.fetchData() returns.  These include fields, tabs, items, values
 and even fields. 
 For example, if you had a DataSource
 "myFormFields" whose fields included the basic properties of FormItem
 (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
 the "myFormFields" DataSource on the fly: 
    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    )  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.











fetchData
public void fetchData(Criteria criteria)

Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching
 records.  In contrast to ListGrid.fetchData(), which creates a ResultSet to manage the returned data, calling dataSource.fetchData()
 provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects.  Calling
 dataSource.fetchData() does not automatically update any visual components or caches: code in the
 callback passed to fetchData() decides what to do with the returned data.  
 For example, given a
 ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched
 from
 the DataSource: 
    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");  Unlike
 calling myGrid.fetchData(), which creates a ResultSet, the data
 provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
 directly modify.  This is useful when, for example, a ListGrid is being used as a more sophisticated version of
 HTML's multi-select component.  Disconnected datasets may be used to populate various visual components.  For
 example, while an individual FormItem can be configured to fetch valueMap options from a DataSource via the optionDataSource property, the following code shows storing a dataset to derive valueMaps from later: 
 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 
  You can also create a ResultSet from the data retrieved from
 fetchData(), like so: 
    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 
  This gives you a dataset that supports client-side filtering
 (via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)), can provide  ResultSet.getValueMap(java.lang.String, java.lang.String), will  disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual
 components. 
 See also the server-side com.isomorphic.js.JSTranslater class in the
 ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
 involving dumping data into the page during initial page load.  Note: care should be taken when using this
 approach.  Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets
 that may become very large. 
 Data-Driven Visual Component Creation 

 DataSource.fetchData() can also be used to create Smart GWT components in a data-driven way.  Many
 properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
 dataSource.fetchData() returns.  These include fields, tabs, items, values
 and even fields. 
 For example, if you had a DataSource
 "myFormFields" whose fields included the basic properties of FormItem
 (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
 the "myFormFields" DataSource on the fly: 
    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    )  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





fetchData
public void fetchData(Criteria criteria,
                      DSCallback callback)

Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching
 records.  In contrast to ListGrid.fetchData(), which creates a ResultSet to manage the returned data, calling dataSource.fetchData()
 provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects.  Calling
 dataSource.fetchData() does not automatically update any visual components or caches: code in the
 callback passed to fetchData() decides what to do with the returned data.  
 For example, given a
 ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched
 from
 the DataSource: 
    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");  Unlike
 calling myGrid.fetchData(), which creates a ResultSet, the data
 provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
 directly modify.  This is useful when, for example, a ListGrid is being used as a more sophisticated version of
 HTML's multi-select component.  Disconnected datasets may be used to populate various visual components.  For
 example, while an individual FormItem can be configured to fetch valueMap options from a DataSource via the optionDataSource property, the following code shows storing a dataset to derive valueMaps from later: 
 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 
  You can also create a ResultSet from the data retrieved from
 fetchData(), like so: 
    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 
  This gives you a dataset that supports client-side filtering
 (via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)), can provide  ResultSet.getValueMap(java.lang.String, java.lang.String), will  disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual
 components. 
 See also the server-side com.isomorphic.js.JSTranslater class in the
 ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
 involving dumping data into the page during initial page load.  Note: care should be taken when using this
 approach.  Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets
 that may become very large. 
 Data-Driven Visual Component Creation 

 DataSource.fetchData() can also be used to create Smart GWT components in a data-driven way.  Many
 properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
 dataSource.fetchData() returns.  These include fields, tabs, items, values
 and even fields. 
 For example, if you had a DataSource
 "myFormFields" whose fields included the basic properties of FormItem
 (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
 the "myFormFields" DataSource on the fly: 
    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    )  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





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 creates a ResultSet to manage the returned data, calling dataSource.fetchData()
 provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects.  Calling
 dataSource.fetchData() does not automatically update any visual components or caches: code in the
 callback passed to fetchData() decides what to do with the returned data.  
 For example, given a
 ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched
 from
 the DataSource: 
    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");  Unlike
 calling myGrid.fetchData(), which creates a ResultSet, the data
 provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
 directly modify.  This is useful when, for example, a ListGrid is being used as a more sophisticated version of
 HTML's multi-select component.  Disconnected datasets may be used to populate various visual components.  For
 example, while an individual FormItem can be configured to fetch valueMap options from a DataSource via the optionDataSource property, the following code shows storing a dataset to derive valueMaps from later: 
 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 
  You can also create a ResultSet from the data retrieved from
 fetchData(), like so: 
    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 
  This gives you a dataset that supports client-side filtering
 (via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)), can provide  ResultSet.getValueMap(java.lang.String, java.lang.String), will  disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual
 components. 
 See also the server-side com.isomorphic.js.JSTranslater class in the
 ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
 involving dumping data into the page during initial page load.  Note: care should be taken when using this
 approach.  Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets
 that may become very large. 
 Data-Driven Visual Component Creation 

 DataSource.fetchData() can also be used to create Smart GWT components in a data-driven way.  Many
 properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
 dataSource.fetchData() returns.  These include fields, tabs, items, values
 and even fields. 
 For example, if you had a DataSource
 "myFormFields" whose fields included the basic properties of FormItem
 (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
 the "myFormFields" DataSource on the fly: 
    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    )  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)

Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching
 records.  This is identical to fetchData() except that textMatchStyle is set to "substring" to cause case
 insensitive substring matching (if the server respects this setting).





Parameters:
criteria - search criteria





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





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

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 - 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 com.smartgwt.client.data.DataSource#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














  
      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

setAddGlobalId

getAddGlobalId

setAutoCacheAllData

getAutoCacheAllData

setAutoConvertRelativeDates

getAutoConvertRelativeDates

setAutoDeriveSchema

getAutoDeriveSchema

setAutoDeriveTitles

getAutoDeriveTitles

setBeanClassName

getBeanClassName

setCacheAllData

getCacheAllData

setCacheData

getCacheData

setCacheMaxAge

getCacheMaxAge

setCallbackParam

getCallbackParam

setCanMultiSort

getCanMultiSort

setChildrenField

getChildrenField

setClientOnly

getClientOnly

setCriteriaPolicy

getCriteriaPolicy

setDataFormat

getDataFormat

setDataTransport

getDataTransport

setDataURL

getDataURL

setDropExtraFields

getDropExtraFields

setEnumConstantProperty

setEnumOrdinalProperty

setEnumTranslateStrategy

setIconField

getIconField

setJsonPrefix

getJsonPrefix

setJsonSuffix

getJsonSuffix

setPluralTitle

getPluralTitle

setPreventHTTPCaching

getPreventHTTPCaching

setQualifyColumnNames

getQualifyColumnNames

setRecordXPath

getRecordXPath

setRequiredMessage

getRequiredMessage

setResultBatchSize

getResultBatchSize

getSchemaNamespace

setSendExtraFields

getSendExtraFields

setServerConstructor

getServerConstructor

setServiceNamespace

getServiceNamespace

setShowLocalFieldsOnly

getShowLocalFieldsOnly

setShowPrompt

getShowPrompt

setStrictSQLFiltering

getStrictSQLFiltering

setTagName

getTagName

setTitle

getTitle

com.smartgwt.client.data
Class DataSource