com.smartgwt.client.data
Class DataSource

java.lang.Object
  extended by com.smartgwt.client.core.BaseClass
      extended by com.smartgwt.client.data.DataSource
All Implemented Interfaces:
HasHandlers, HasHandleErrorHandlers
Direct Known Subclasses:
RestDataSource, WSDataSource, XJSONDataSource

public class DataSource
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 'QuickStart Guide', Chapter 6, Data Binding.

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

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

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

See Also:
DataBoundComponent, ClientOnlyDataSources overview and related methods

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 newRecord)
          Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
 void addData(Record newRecord, DSCallback callback)
           
 void addData(Record newRecord, DSCallback callback, DSRequest requestProperties)
          Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
 void addField(DataSourceField field)
          Add a field to the DataSource
 HandlerRegistration addHandleErrorHandler(HandleErrorHandler handler)
          Add a handleError handler.
 Record[] applyFilter(Record[] records, Criteria criteria)
          Returns records in the passed Record that match the provided filter Criteria.
 Record[] applyFilter(Record[] records, Criteria criteria, DSRequest requestProperties)
          Returns records in the passed Record that match the provided filter Criteria.
static boolean canFlattenCriteria(AdvancedCriteria criteria)
          Returns true if calling DataSource.flattenCriteria on the passed criteria would produce logically equivalent criteria.
static Criteria combineCriteria(Criteria criteria1, Criteria criteria2)
          Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator".
static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator)
           
static Criteria combineCriteria(Criteria criteria1, Criteria criteria2, CriteriaCombineOperator outerOperator, TextMatchStyle textMatchStyle)
          Combines two criteria (either simple criteria objects or AdvancedCriteria) using the "outerOperator".
 int compareCriteria(Criteria newCriteria, Criteria oldCriteria)
          Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.
 int compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties)
           
 int compareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties, String policy)
          Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.
 int compareDates(Date date1, Date date2, String fieldName)
          Convenience method to compare two Date objects appropriately, depending on whether the passed-in fieldName refers to a field of type "datetime" or "date".
static AdvancedCriteria convertCriteria(Criteria criteria)
          Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
static AdvancedCriteria convertCriteria(Criteria criteria, TextMatchStyle textMatchStyle)
          Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
 AdvancedCriteria convertDataSourceCriteria(Criteria criteria)
          Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
 AdvancedCriteria convertDataSourceCriteria(Criteria criteria, TextMatchStyle textMatchStyle)
          Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.
 Criteria convertRelativeDates(Criteria criteria)
          Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.
 Criteria convertRelativeDates(Criteria criteria, String timezoneOffset)
           
 Criteria convertRelativeDates(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek)
           
 Criteria convertRelativeDates(Criteria criteria, String timezoneOffset, Integer firstDayOfWeek, Date baseDate)
          Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.
static Criteria copyCriteria(Criteria criteria)
          Create a copy of a criteria.
 Record copyRecord(Record record)
          Copies all DataSource field values of a Record (including a TreeNode) to a new Record, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.
 Record[] copyRecords(Record... records)
          Copies all DataSource field values of an (Array) of Records (including a TreeNode) to a new array of Records, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.
 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)
           
 void downloadFile(Record data, String fieldName, DSRequest requestProperties)
          Download a file stored in a field of type:"binary" in a DataSource record.
 boolean evaluateCriterion(Record record, Criterion criterion)
          Evaluate the given criterion with respect to the passed record.
 void exportClientData(Object[] data, DSRequest requestProperties)
          Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users.
static void exportClientDataStatic(Object[] data, DSRequest requestProperties)
          Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users.
 void exportData()
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results.
 void exportData(Criteria criteria)
           
 void exportData(Criteria criteria, DSRequest requestProperties)
           
 void exportData(Criteria criteria, DSRequest requestProperties, DSCallback callback)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results.
 void fetchData()
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void fetchData(Criteria criteria)
           
 void fetchData(Criteria criteria, DSCallback callback)
           
 void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void fetchRecord(Object pkValue)
          Fetch a single record from the DataSource by primary key.
 void fetchRecord(Object pkValue, DSCallback callback)
           
 void fetchRecord(Object pkValue, DSCallback callback, DSRequest requestProperties)
          Fetch a single record from the DataSource by primary key.
 boolean fieldMatchesFilter(Object fieldValue, Object filterValue)
          Compares a criteria value to a field value and returns whether they match, as follows: any non-String filter value is directly compared (==) to the field value any String filter value is compared according to textMatchStyle in the passed requestProperties, regardless of the actual field type if the filter value is an Array, the comparison is a logical OR.
 boolean fieldMatchesFilter(Object fieldValue, Object filterValue, DSRequest requestProperties)
          Compares a criteria value to a field value and returns whether they match, as follows: any non-String filter value is directly compared (==) to the field value any String filter value is compared according to textMatchStyle in the passed requestProperties, regardless of the actual field type if the filter value is an Array, the comparison is a logical OR.
 void filterData()
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void filterData(Criteria criteria)
           
 void filterData(Criteria criteria, DSCallback callback)
           
 void filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
static AdvancedCriteria flattenCriteria(AdvancedCriteria criteria)
          Returns new criteria that has at most one top-level LogicalOperator ("and" or "or").
static DataSource get(String ID)
          Synonym of DataSource.getDataSource: Lookup a DataSource by ID.
static DataSource get(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)
          Synonym of DataSource.getDataSource: Lookup a DataSource by ID.
 Boolean getAddGlobalId()
          Whether to make this DataSource available as a global variable for convenience.
static String getAdvancedCriteriaDescription(AdvancedCriteria criteria, DataSource dataSource)
          Returns a human-readable string describing the clauses in this advanced criteria or criterion.
 Boolean getAllowAdvancedCriteria()
          By default, all DataSources are assumed to be capable of handling AdvancedCriteria on fetch or filter type operations.
 Boolean getAutoCacheAllData()
          When a DataSource is not cacheAllData:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch to cacheAllData:true and prevent further server-trips for fetch requests.
 Boolean getAutoConvertRelativeDates()
          Whether to convert relative date values to concrete date values before sending to the server.
 boolean getAutoDeriveTitles()
          If set, titles are automatically derived from field.name for any field that does not have a field.title and is not marked hidden:true, by calling the method DataSource.getAutoTitle.
static String getAutoTitle(String identifier)
          Utility method to derive a reasonable user-visible title from an identifier.
 Boolean getCacheAcrossOperationIds()
          When cacheAllData mode is enabled and a cacheAllOperationId has been set, this flag affects whether cached results are used for all "fetch" requests regardless of their operationId, or are used only for "fetch" requests that use the cacheAllOperationId, allowing other requests to go to server normally.
 Boolean getCacheAllData()
          Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
 String getCacheAllOperationId()
          operationId to use for fetching data in case cacheAllData is true.
 Record[] getCacheData()
          For a cacheAllData or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.
 int getCacheMaxAge()
          The maximum time, in seconds, to maintain the client-side cache.
 String getCallbackParam()
          Applies only to dataFormat: "json" and dataTransport:"scriptInclude".
 boolean getCanMultiSort()
          When true, indicates that this DataSource supports multi-level sorting.
 String getChildrenField()
          fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
 Boolean getClientOnly()
          A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as DSRequests are executed on it.
 void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback)
          Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that inheritsFrom the original DataSource.
 void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties)
           
 void getClientOnlyDataSource(Criteria criteria, ClientOnlyDataSourceCallback callback, DSRequest requestProperties, DataSource dataSourceProperties)
          Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that inheritsFrom the original DataSource.
protected  DSResponse getClientOnlyResponse(DSRequest request, Record... serverData)
          Return a "spoofed" response for a clientOnly or cacheAllData DataSource.
 CriteriaPolicy getCriteriaPolicy()
          Decides under what conditions the ResultSet cache should be dropped when the criteria changes.
 String getDataField()
          Name of the field that has the most pertinent numeric, date, or enum value, for use when a DataBoundComponent needs to show a short summary of a record.
 DSDataFormat getDataFormat()
          Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when DataSource.fetchData is called).
 DSProtocol getDataProtocol()
          Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
static DataSource getDataSource(String ID)
          Lookup a DataSource by ID.
static DataSource getDataSource(String ID, RequestTransformer requestTransformer, ResponseTransformer responseTransformer)
          Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer.
 RPCTransport getDataTransport()
          Transport to use for all operations on this DataSource.
 String getDataURL()
          Default URL to contact to fulfill all DSRequests.
 Map getDefaultParams()
          HTTP parameters that should be submitted with every DSRequest.
 TextMatchStyle getDefaultTextMatchStyle()
          The default textMatchStyle to use for DSRequests that do not explicitly state a textMatchStyle.
 String getDescriptionField()
          Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.
 Object getDisplayValue(String fieldName, Object value)
          Given a fieldName and a dataValue, apply any valueMap for the field and return the display value for the field
 Boolean getDropExtraFields()
          Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.
 Boolean getDropUnknownCriteria()
          If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client.
 String getFetchDataURL(Criteria criteria)
          Returns a URL to DataSource fetch operation.
 String getFetchDataURL(Criteria criteria, DSRequest requestProperties)
          Returns a URL to DataSource fetch operation.
 DataSourceField getField(String fieldName)
          Return the field definition object.
 String getFieldAutoTitle(String identifier)
          Return a reasonable user-visible title given a fieldName.
 Criteria getFieldCriterion(Criteria criterion, String fieldName)
          Returns the depth-first match of a criterion matching the given fieldName.
 DataSourceField getFieldForDataPath(String dataPath)
          Return the field definition object corresponding to the supplied dataPath
 String[] getFieldNames()
          Retrieves the list of fields declared on this DataSource.
 String[] getFieldNames(boolean excludeHidden)
          Retrieves the list of fields declared on this DataSource.
 OperatorId[] getFieldOperators(DataSourceField field)
          Get the list of OperatorId's available for this field.
 OperatorId[] getFieldOperators(String fieldName)
           
 DataSourceField[] getFields()
          The list of fields that compose records from this DataSource.
static Object getFieldValue(DataSourceField field, Record record)
          Given a field definition and a record object, this method will return the field value for the record.
static Object getFieldValue(DetailViewerField field, Record record)
          Given a field definition and a record object, this method will return the field value for the record.
static Object getFieldValue(FormItem field, Record record)
          Given a field definition and a record object, this method will return the field value for the record.
static Object getFieldValue(ListGridField field, Record record)
          Given a field definition and a record object, this method will return the field value for the record.
 String getFileURL(Record data)
          Returns a direct URL to access a file stored in a field of type:"binary".
 String getFileURL(Record data, String fieldName)
           
 String getFileURL(Record data, String fieldName, DSRequest requestProperties)
          Returns a direct URL to access a file stored in a field of type:"binary".
 Map getGlobalNamespaces()
          Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.
 String getIconField()
          Designates a field of type:"image" as the field to use when rendering a record as an image, for example, in a TileGrid.
 Boolean getIgnoreTextMatchStyleCaseSensitive()
          For fields on this dataSource that specify ignoreTextMatchStyle true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values.
 String getInfoField()
          Name of the field that has the second most pertinent piece of textual information in the record, for use when a DataBoundComponent needs to show a short summary of a record.
 String getInheritsFrom()
          ID of another DataSource this DataSource inherits its fields from.
 JavaScriptObject getJsObj()
           
 String getJsonPrefix()
          Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
 String getJsonSuffix()
          Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
 void getLegalChildTags()
          For a DataSource that describes a DOM structure, the list of legal child elements that can be contained by the element described by this DataSource.
 OperationBinding[] getOperationBindings()
          Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
static DataSource getOrCreateRef(JavaScriptObject jsObj)
           
 String getPatternEscapeChar()
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" searchoperator, character that escapes the patternSingleWildcard or patternMultiWildcard if placed before it, so that it is treated as a literal character.
 String getPatternMultiWildcard()
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.
 String[] getPatternMultiWildcardAsString()
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.
 String getPatternSingleWildcard()
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.
 String[] getPatternSingleWildcardAsString()
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.
 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.
 String[] getPrimaryKeyFieldNames()
          Returns a list of the names of this DataSource's primaryKey fields.
 Record getPrimaryKeyFields()
          Returns this DataSource's primaryKey fields as a map of fieldName to field.
 Boolean getProgressiveLoading()
          If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the ResultSet documentation.
 Boolean getQualifyColumnNames()
          For dataSources of serverType "sql", determines whether we qualify column names with table names in any SQL we generate.
 String getRecordXPath()
          See recordXPath.
 DSRequest getRequestProperties()
          Additional properties to pass through to the DSRequests made by this DataSource.
 String getRequiredMessage()
          The required message when a field that has been marked as required is not filled in by the user.
 int getResultBatchSize()
          Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.
 String getResultSetClass()
          Class for ResultSets used by this datasource.
 String getSchemaNamespace()
          For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to.
 Boolean getSendExtraFields()
          Analogous to dropExtraFields, for data sent to the server.
 Boolean getSendParentNode()
          Set this attribute if you need to send the dsRequest.parentNode to the server-side.
 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 in order to block user interactions until the request completes.
static String[] getSortBy(SortSpecifier[] sortSpecifiers)
          Given an array of SortSpecifiers, return a simple list of Strings in the format expected by sortBy.
static String[] getSortSpecifiers(String[] sortBy)
          Return a an array of SortSpecifiers, given an array of Strings in the format expected by sortBy.
 Boolean getStrictSQLFiltering()
          If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.
 String getTagName()
          Tag name to use when serializing to XML.
 Record[] getTestData()
          For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
 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 getTranslatePatternOperators()
          Search operators like "matchesPattern" use patterns like "foo*txt" to match text values.
 Boolean getTrimMilliseconds()
          For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa.
 OperatorId[] getTypeOperators()
          Get the list of OperatorIds available on this DataSource for the given FieldType.
 OperatorId[] getTypeOperators(FieldType typeName)
          Get the list of OperatorIds available on this DataSource for the given FieldType.
 Boolean getUseFlatFields()
          Like useFlatFields, but applies to all DataBound components that bind to this DataSource.
 Boolean getUseHttpProxy()
          Like useHttpProxy, but serves as a default for this DataSource that may be overridden by individual operationBindings.
 Boolean getUseLocalValidators()
          Whether to attempt validation on the client at all for this DataSource.
 Boolean getUseOfflineStorage()
          Whether we store server responses for this DataSource into browser-based offline storage, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server).
 Boolean getUseParentFieldOrder()
          For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.
 Boolean getUseStrictJSON()
          Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.
 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 boolean isFlatCriteria(AdvancedCriteria criteria)
          Returns true if a given AdvancedCriteria is "flat." That is, the criteria consists of either: a top-level "and" or "or" Criterion, where none of the subcriteria use logical operators, hence have no subcriteria of their own a single Criterion that is not a logical operator, hence has no subcriteria
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)
          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.
static void loadWithParents(String[] dsID, Function callback, boolean forceReload)
          Variation of DataSource.load that will also automatically load any DataSources that the requested DataSources inherit from (via {@link com.smartgwt.client.data.DataSource#inheritsFrom DataSource.inheritsFrom))
static void loadWithParents(String dsID, Function callback)
          Variation of DataSource.load that will also automatically load any DataSources that the requested DataSources inherit from (via inheritsFrom).
static void loadWithParents(String dsID, Function callback, boolean forceReload)
          Variation of DataSource.load that will also automatically load any DataSources that the requested DataSources inherit from (via inheritsFrom).
protected  void onInit()
           
 void performCustomOperation(String operationId)
          Invoke an operation declared with operationType "custom".
 void performCustomOperation(String operationId, Record data)
           
 void performCustomOperation(String operationId, Record data, DSCallback callback)
           
 void performCustomOperation(String operationId, Record data, DSCallback callback, DSRequest requestProperties)
          Invoke an operation declared with operationType "custom".
 void processResponse(String requestId, DSResponse dsResponse)
          Process a dsResponse for a request initiated by a DataSource with dataProtocol:"clientCustom".
 boolean recordsAreEqual(Object record1, Object record2)
          Convenience method to test if two records are equal.
 String recordsAsText(Record[] records)
          Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).
 String recordsAsText(Record[] records, TextExportSettings settings)
          Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).
 Record[] recordsFromText(String text)
          Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.
 Record[] recordsFromText(String text, TextImportSettings settings)
          Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.
 Record[] recordsFromXML(Object elements)
          Transform a list of XML elements to DataSource records.
protected  void registerID(String id, boolean skipUniqueJSIdentifierCheck)
           
 void removeData(Record data)
          Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
 void removeData(Record data, DSCallback callback)
           
 void removeData(Record data, DSCallback callback, DSRequest requestProperties)
          Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
 void setAddGlobalId(Boolean addGlobalId)
          Whether to make this DataSource available as a global variable for convenience.
 void setAllowAdvancedCriteria(Boolean allowAdvancedCriteria)
          By default, all DataSources are assumed to be capable of handling AdvancedCriteria on fetch or filter type operations.
 void setAutoCacheAllData(Boolean autoCacheAllData)
          When a DataSource is not cacheAllData:true and a fetch results in the entire dataset being retrieved, this attribute being set to true causes the DataSource to automatically switch to cacheAllData:true and prevent further server-trips for fetch requests.
 void setAutoConvertRelativeDates(Boolean autoConvertRelativeDates)
          Whether to convert relative date values to concrete date values before sending to the server.
 void setAutoDeriveTitles(boolean autoDeriveTitles)
          If set, titles are automatically derived from field.name for any field that does not have a field.title and is not marked hidden:true, by calling the method DataSource.getAutoTitle.
 void setCacheAllData(Boolean cacheAllData)
          Set this property to true to have a DataSource fetch all of its data client-side on the first fetch request.
 void setCacheData(Record... cacheData)
          For a cacheAllData or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.
 void setCacheMaxAge(int cacheMaxAge)
          The maximum time, in seconds, to maintain the client-side cache.
 void setCallbackParam(String callbackParam)
          Applies only to dataFormat: "json" and dataTransport:"scriptInclude".
 void setCanMultiSort(boolean canMultiSort)
          When true, indicates that this DataSource supports multi-level sorting.
 void setChildrenField(String childrenField)
          fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
 void setClientOnly(Boolean clientOnly)
          A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as DSRequests are executed on it.
 void setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
          Decides under what conditions the ResultSet cache should be dropped when the criteria changes.
 void setDataField(String dataField)
          Name of the field that has the most pertinent numeric, date, or enum value, for use when a DataBoundComponent needs to show a short summary of a record.
 void setDataFormat(DSDataFormat dataFormat)
          Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when DataSource.fetchData is called).
 void setDataProtocol(DSProtocol dataProtocol)
          Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
 void setDataTransport(RPCTransport dataTransport)
          Transport to use for all operations on this DataSource.
 void setDataURL(String dataURL)
          Default URL to contact to fulfill all DSRequests.
 void setDefaultParams(Map defaultParams)
          HTTP parameters that should be submitted with every DSRequest.
 void setDefaultTextMatchStyle(TextMatchStyle defaultTextMatchStyle)
          The default textMatchStyle to use for DSRequests that do not explicitly state a textMatchStyle.
 void setDescriptionField(String descriptionField)
          Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.
 void setDropExtraFields(Boolean dropExtraFields)
          Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.
 void setDropUnknownCriteria(Boolean dropUnknownCriteria)
          If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client.
 void setEnumConstantProperty(String enumConstantProperty)
          The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if the EnumTranslateStrategy is set to "bean".
 void setEnumOrdinalProperty(String enumOrdinalProperty)
          The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if the EnumTranslateStrategy is set to "bean".
 void setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy)
          Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript.
 void setFields(DataSourceField... fields)
          The list of fields that compose records from this DataSource.
 void setGlobalNamespaces(Map globalNamespaces)
          Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.
 void setHandleErrorCallback(HandleErrorCallback callback)
          If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other than STATUS_SUCCESS.
 void setIconField(String iconField)
          Designates a field of type:"image" as the field to use when rendering a record as an image, for example, in a TileGrid.
 void setID(String id)
           
 void setIgnoreTextMatchStyleCaseSensitive(Boolean ignoreTextMatchStyleCaseSensitive)
          For fields on this dataSource that specify ignoreTextMatchStyle true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values.
 void setInfoField(String infoField)
          Name of the field that has the second most pertinent piece of textual information in the record, for use when a DataBoundComponent needs to show a short summary of a record.
 void setInheritsFrom(DataSource inheritsFrom)
          ID of another DataSource this DataSource inherits its DataSource fields from.

Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields.
 void setInheritsFrom(String inheritsFrom)
          ID of another DataSource this DataSource inherits its fields from.
 void setJsonPrefix(String jsonPrefix)
          Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
 void setJsonSuffix(String jsonSuffix)
          Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
 void setOperationBindings(OperationBinding... operationBindings)
          Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
 void setPatternEscapeChar(String patternEscapeChar)
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" searchoperator, character that escapes the patternSingleWildcard or patternMultiWildcard if placed before it, so that it is treated as a literal character.
 void setPatternMultiWildcard(String... patternMultiWildcard)
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.
 void setPatternMultiWildcard(String patternMultiWildcard)
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.
 void setPatternSingleWildcard(String... patternSingleWildcard)
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.
 void setPatternSingleWildcard(String patternSingleWildcard)
          When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.
 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 setProgressiveLoading(Boolean progressiveLoading)
          If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the ResultSet documentation.
 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 DSRequests made by this DataSource.
 void setRequiredMessage(String requiredMessage)
          The required message when a field that has been marked as required is not filled in by the user.
 void setResultBatchSize(int resultBatchSize)
          Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.
 void setResultSetClass(String resultSetClass)
          Class for ResultSets used by this datasource.
 void setSendExtraFields(Boolean sendExtraFields)
          Analogous to dropExtraFields, for data sent to the server.
 void setSendParentNode(Boolean sendParentNode)
          Set this attribute if you need to send the dsRequest.parentNode to the server-side.
 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 in order to block user interactions until the request completes.
 void setStrictSQLFiltering(Boolean strictSQLFiltering)
          If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.
 void setTagName(String tagName)
          Tag name to use when serializing to XML.
 void setTestData(Record... cacheData)
          For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
 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 setTranslatePatternOperators(boolean translatePatternOperators)
          Search operators like "matchesPattern" use patterns like "foo*txt" to match text values.
 void setTrimMilliseconds(Boolean trimMilliseconds)
          For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa.
 void setTypeOperators(FieldType typeName, OperatorId[] operators)
          Set the list of OperatorIds valid for a given FieldType.
static void setTypeOperators(String typeName, OperatorId[] operators)
          Set the list of valid OperatorIds for a given FieldType.
 void setUseFlatFields(Boolean useFlatFields)
          Like useFlatFields, but applies to all DataBound components that bind to this DataSource.
 void setUseHttpProxy(Boolean useHttpProxy)
          Like useHttpProxy, but serves as a default for this DataSource that may be overridden by individual operationBindings.
 void setUseLocalValidators(Boolean useLocalValidators)
          Whether to attempt validation on the client at all for this DataSource.
 void setUseOfflineStorage(Boolean useOfflineStorage)
          Whether we store server responses for this DataSource into browser-based offline storage, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server).
 void setUseParentFieldOrder(Boolean useParentFieldOrder)
          For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.
 void setUseStrictJSON(Boolean useStrictJSON)
          Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.
 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.
 Criteria splitCriteria(Criteria criteria, String[] fields)
          Split a criteria apart based on fields.
 Boolean supportsAdvancedCriteria()
          Do fetch and filter operations on this dataSource support being passed AdvancedCriteria?
 void supportsTextMatchStyle(TextMatchStyle textMatchStyle)
          Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.
protected  Object transformRequest(DSRequest dsRequest)
          For a dataSource using client-side data integration, return the data that should be sent to the dataURL.
protected  void transformResponse(DSResponse dsResponse, DSRequest dsRequest, Object data)
          Modify the DSResponse object derived from the response returned from the dataURL.
 void updateCaches(DSResponse dsResponse)
          Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed.
 void updateCaches(DSResponse dsResponse, DSRequest dsRequest)
          Causes any components using this DataSource to be notified of changes that have been made to the remote dataset accessed via this DataSource, as though the provided DSResponse had just successfully completed.
 void updateData(Record updatedRecord)
          Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
 void updateData(Record updatedRecord, DSCallback callback)
           
 void updateData(Record updatedRecord, DSCallback callback, DSRequest requestProperties)
          Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
protected  boolean useOfflineResponse(DSRequest dsRequest, DSResponse dsResponse)
          Override point to allow application code to suppress use of a particular offline response.
 void validateData(Record values)
          Contacts the server to run server-side validation on a DSRequest and either returns errors validation errors or a status code of 0.
 void validateData(Record values, DSCallback callback)
           
 void validateData(Record values, DSCallback callback, DSRequest requestProperties)
          Contacts the server to run server-side validation on a DSRequest and either returns 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)
           
 void viewFile(Record data, String fieldName, DSRequest requestProperties)
          Display a file stored in a field of type:"binary" in a new browser window.
 String xmlSerialize(JavaScriptObject data)
          Serialize a JavaScript object as XML.
 String xmlSerialize(JavaScriptObject data, SerializationContext flags)
          Serialize a JavaScript object as XML.
 String xmlSerialize(Map data, SerializationContext flags)
          Serialize a JavaScript object as XML.
 String xmlSerialize(Record[] data, SerializationContext flags)
          Serialize a JavaScript object as XML.
 String xmlSerialize(Record data, SerializationContext flags)
          Serialize a JavaScript object as XML.
 
Methods inherited from class com.smartgwt.client.core.BaseClass
asSGWTComponent, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getScClassName, hasAutoAssignedID, internalSetID, internalSetID, onBind, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setJavaScriptObject, 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

setAllowAdvancedCriteria

public void setAllowAdvancedCriteria(Boolean allowAdvancedCriteria)
By default, all DataSources are assumed to be capable of handling AdvancedCriteria on fetch or filter type operations. This property may be set to false to indicate that this dataSource does not support advancedCriteria. See DataSource.supportsAdvancedCriteria for further information on this.

NOTE: If you specify this property in a DataSource descriptor (.ds.xml file), it is enforced on the server. This means that if you run a request containing AdvancedCriteria against a DataSource that advertises itself as allowAdvancedCriteria:false, it will be rejected.

Note : This is an advanced setting

Parameters:
allowAdvancedCriteria - Default value is null
See Also:
OperationBinding.setAllowAdvancedCriteria(java.lang.Boolean)

getAllowAdvancedCriteria

public Boolean getAllowAdvancedCriteria()
By default, all DataSources are assumed to be capable of handling AdvancedCriteria on fetch or filter type operations. This property may be set to false to indicate that this dataSource does not support advancedCriteria. See DataSource.supportsAdvancedCriteria for further information on this.

NOTE: If you specify this property in a DataSource descriptor (.ds.xml file), it is enforced on the server. This means that if you run a request containing AdvancedCriteria against a DataSource that advertises itself as allowAdvancedCriteria:false, it will be rejected.

Returns:
Boolean
See Also:
OperationBinding.getAllowAdvancedCriteria()

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.

cacheAllData is automatically enabled in either of these conditions:

Parameters:
autoCacheAllData - Default value is false

getAutoCacheAllData

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

cacheAllData is automatically enabled in either of these conditions:

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

getAutoConvertRelativeDates

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

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

getCacheAcrossOperationIds

public Boolean getCacheAcrossOperationIds()
                                   throws IllegalStateException
When cacheAllData mode is enabled and a cacheAllOperationId has been set, this flag affects whether cached results are used for all "fetch" requests regardless of their operationId, or are used only for "fetch" requests that use the cacheAllOperationId, allowing other requests to go to server normally.

Default of true means that the cacheAllOperationId will be used to fetch all rows, but the resulting cache will be used for all "fetch" operations regardless of the operationId specified on the request.

Switching to "false" effectively creates caching just for one specific operationId - the cacheAllOperationId - while allowing all other requests to go to the server normally.

Note : This method should be called only after the underlying component has been created.

Returns:
Boolean
Throws:
IllegalStateException - if the underlying component has not yet been created.

setCacheAllData

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

You can manually set this attribute after initialization by calling DataSource.setCacheAllData; setting autoCacheAllData:true causes a DataSource to automatically switch to cacheAllData:true when a fetch results in the entire dataset being brought client-side.

To cause automatic cache updates, you can set cacheMaxAge to a number of seconds and once data has been client-side for that length of time, the next fetch causes the cache to be dropped and a new cache retrieved.

Note that multiple operationBindings of type "fetch" which return distinct results will not work with cacheAllData: only one cache is created and is used for all fetch operations, regardless of whether operationId has been set. However, "fetch" operationBindings used as a cacheSyncOperation will work normally, so long as they return all data fields that are returned by the default "fetch" operation, so that the cache can be updated.

To specify which operationId to use for fetching all data, use cacheAllOperationId.

To use the cache only for requests that have the cacheAllOperationId, allowing any other operationId (or absence of an operationId) to contact the server as normal, set cacheAcrossOperationIds.

If this method is called after the component has been drawn/initialized: Call this method to switch cacheAllData on or off after initialization. Passing a shouldCache value of false clears any existing client-side cache, cancels any outstanding requests for a full cache and issues any other pending requests normally.

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 its data client-side on the first fetch request. However, unlike a clientOnly DataSource, this DataSource will still save changes normally, sending remote requests.

You can manually set this attribute after initialization by calling DataSource.setCacheAllData; setting autoCacheAllData:true causes a DataSource to automatically switch to cacheAllData:true when a fetch results in the entire dataset being brought client-side.

To cause automatic cache updates, you can set cacheMaxAge to a number of seconds and once data has been client-side for that length of time, the next fetch causes the cache to be dropped and a new cache retrieved.

Note that multiple operationBindings of type "fetch" which return distinct results will not work with cacheAllData: only one cache is created and is used for all fetch operations, regardless of whether operationId has been set. However, "fetch" operationBindings used as a cacheSyncOperation will work normally, so long as they return all data fields that are returned by the default "fetch" operation, so that the cache can be updated.

To specify which operationId to use for fetching all data, use cacheAllOperationId.

To use the cache only for requests that have the cacheAllOperationId, allowing any other operationId (or absence of an operationId) to contact the server as normal, set cacheAcrossOperationIds.

Returns:
Boolean

getCacheAllOperationId

public String getCacheAllOperationId()
                              throws IllegalStateException
operationId to use for fetching data in case cacheAllData is true. By default a standard fetch operation is used (with no operationId specified).

Note : This method should be called only after the underlying component has been created.

Returns:
String
Throws:
IllegalStateException - if the underlying component has not yet been created.

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 - Default value is 60

getCacheMaxAge

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

Returns:
int

setCallbackParam

public void setCallbackParam(String callbackParam)
                      throws IllegalStateException
Applies only to dataFormat: "json" and dataTransport:"scriptInclude". Specifies the name of the query parameter that tells your JSON service what function to call as part of the response.

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

getCallbackParam

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

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

setCanMultiSort

public void setCanMultiSort(boolean canMultiSort)
                     throws IllegalStateException
When true, indicates that this DataSource supports multi-level sorting.

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

getChildrenField

public String getChildrenField()
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:
DataSourceField.getChildrenProperty(), DataSourceRelations overview and related methods

setClientOnly

public void setClientOnly(Boolean clientOnly)
                   throws IllegalStateException
A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as DSRequests are executed on it. Any changes are lost when the user reloads the page or navigates away.

A clientOnly DataSource will return responses asynchronously, just as a DataSource accessing remote data does. This allows a clientOnly DataSource to be used as a temporary placeholder while a real DataSource is being implemented - if a clientOnly DataSource is replaced by a DataSource that accesses a remote data store, UI code for components that used the clientOnly DataSource will not need be changed.

A clientOnly DataSource can also be used as a shared cache of modifiable data across multiple UI components when immediate saving is not desirable. In this case, several components may interact with a clientOnly DataSource and get the benefit of ResultSet behaviors such as automatic cache sync and in-browser data filtering and sorting. When it's finally time to save, cacheData can be inspected for changes and data can be saved to the original DataSource via DataSource.addData, DataSource.updateData and DataSource.removeData, possibly in a transactional queue. Note that DataSource.getClientOnlyDataSource lets you easily obtain a clientOnly DataSource representing a subset of the data available from a normal DataSource.

See also cacheAllData - a cacheAllData behaves like a write-through cache, performing fetch and filter operations locally while still performing remote save operations immediately.

ClientOnly DataSources can be populated programmatically via cacheData - see this discussion for other ways to populate a client-only DataSource with data.

If this method is called after the component has been drawn/initialized: Switch into clientOnly mode, taking the cache from the cacheAllData ResultSet if it exists.

Parameters:
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()
A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as DSRequests are executed on it. Any changes are lost when the user reloads the page or navigates away.

A clientOnly DataSource will return responses asynchronously, just as a DataSource accessing remote data does. This allows a clientOnly DataSource to be used as a temporary placeholder while a real DataSource is being implemented - if a clientOnly DataSource is replaced by a DataSource that accesses a remote data store, UI code for components that used the clientOnly DataSource will not need be changed.

A clientOnly DataSource can also be used as a shared cache of modifiable data across multiple UI components when immediate saving is not desirable. In this case, several components may interact with a clientOnly DataSource and get the benefit of ResultSet behaviors such as automatic cache sync and in-browser data filtering and sorting. When it's finally time to save, cacheData can be inspected for changes and data can be saved to the original DataSource via DataSource.addData, DataSource.updateData and DataSource.removeData, possibly in a transactional queue. Note that DataSource.getClientOnlyDataSource lets you easily obtain a clientOnly DataSource representing a subset of the data available from a normal DataSource.

See also cacheAllData - a cacheAllData behaves like a write-through cache, performing fetch and filter operations locally while still performing remote save operations immediately.

ClientOnly DataSources can be populated programmatically via cacheData - see this discussion for other ways to populate a client-only DataSource with data.

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 - Default value is "dropOnShortening"
See Also:
compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)

getCriteriaPolicy

public CriteriaPolicy getCriteriaPolicy()
Decides under what conditions the ResultSet cache should be dropped when the criteria changes.

Returns:
CriteriaPolicy
See Also:
compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)

setDataField

public void setDataField(String dataField)
                  throws IllegalStateException
Name of the field that has the most pertinent numeric, date, or enum value, for use when a DataBoundComponent needs to show a short summary of a record.

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

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

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

getDataField

public String getDataField()
Name of the field that has the most pertinent numeric, date, or enum value, for use when a DataBoundComponent needs to show a short summary of a record.

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

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

Returns:
String
See Also:
DsSpecialFields overview and related methods

setDataFormat

public void setDataFormat(DSDataFormat dataFormat)
                   throws IllegalStateException
Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when DataSource.fetchData is called).

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

getDataFormat

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

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

setDataTransport

public void setDataTransport(RPCTransport dataTransport)
                      throws IllegalStateException
Transport to use for all operations on this DataSource. Defaults to defaultTransport. This would typically only be set to enable "scriptInclude" transport for contacting JSON web services hosted on servers other than the origin server.

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

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

getDataTransport

public RPCTransport getDataTransport()
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:
RPCTransport, getCallbackParam(), ClientDataIntegration overview and related methods

setDataURL

public void setDataURL(String dataURL)
                throws IllegalStateException
Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis via dataURL.

NOTE: Best practice is to use the same dataURL for all DataSources which fulfill DSRequests via the server-side RPCManager API. Otherwise, cross-DataSource operation queuing will not be possible.

Parameters:
dataURL - 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

setDefaultTextMatchStyle

public void setDefaultTextMatchStyle(TextMatchStyle defaultTextMatchStyle)
                              throws IllegalStateException
The default textMatchStyle to use for DSRequests that do not explicitly state a textMatchStyle. Note, however, that DSRequests issued by ListGrids and other components will generally have a setting for textMatchStyle on the component itself (see autoFetchTextMatchStyle, for example).

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

getDefaultTextMatchStyle

public TextMatchStyle getDefaultTextMatchStyle()
The default textMatchStyle to use for DSRequests that do not explicitly state a textMatchStyle. Note, however, that DSRequests issued by ListGrids and other components will generally have a setting for textMatchStyle on the component itself (see autoFetchTextMatchStyle, for example).

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

setDescriptionField

public void setDescriptionField(String descriptionField)
                         throws IllegalStateException
Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.

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

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

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

getDescriptionField

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

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

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

Returns:
String
See Also:
DsSpecialFields overview and related methods

setDropExtraFields

public void setDropExtraFields(Boolean dropExtraFields)
                        throws IllegalStateException
Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.

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

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

Parameters:
dropExtraFields - 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

setDropUnknownCriteria

public void setDropUnknownCriteria(Boolean dropUnknownCriteria)
                            throws IllegalStateException
If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client. This property is useful for cases where you custom server logic makes use of criteria values to determine what set of records to return to the client, but the data does not actually have record values for these fields and as such the client-side filtering logic should ignore them.

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

getDropUnknownCriteria

public Boolean getDropUnknownCriteria()
If the criteria applied to a fetch type operation contain fields that are not present in the dataSource, should they be ignored when performing filtering on the client. This property is useful for cases where you custom server logic makes use of criteria values to determine what set of records to return to the client, but the data does not actually have record values for these fields and as such the client-side filtering logic should ignore them.

Returns:
Boolean

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

setGlobalNamespaces

public void setGlobalNamespaces(Map globalNamespaces)
Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.

The default value is:

    globalNamespaces : {
       xsi: "http://www.w3.org/2001/XMLSchema-instance",
       xsd: "http://www.w3.org/2001/XMLSchema"
    },
  
This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.

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

Parameters:
globalNamespaces - Default value is ...

getGlobalNamespaces

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

The default value is:

    globalNamespaces : {
       xsi: "http://www.w3.org/2001/XMLSchema-instance",
       xsd: "http://www.w3.org/2001/XMLSchema"
    },
  
This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.

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

Returns:
Map

setIconField

public void setIconField(String iconField)
                  throws IllegalStateException
Designates a field of type:"image" as the field to use when rendering a record as an image, for example, in a TileGrid.

For example, for a DataSource of employees, a "photo" field of type "image" should be designated as the iconField.

If not explicitly set, iconField looks for fields named "picture", "thumbnail", "icon", "image" and "img", in that order, and will use any of these fields as the iconField if it exists and has type "image".

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

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

getIconField

public String getIconField()
Designates a field of type:"image" as the field to use when rendering a record as an image, for example, in a TileGrid.

For example, for a DataSource of employees, a "photo" field of type "image" should be designated as the iconField.

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
See Also:
DsSpecialFields overview and related methods

setIgnoreTextMatchStyleCaseSensitive

public void setIgnoreTextMatchStyleCaseSensitive(Boolean ignoreTextMatchStyleCaseSensitive)
                                          throws IllegalStateException
For fields on this dataSource that specify ignoreTextMatchStyle true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. This property dictates whether that match is case-sensitive like the "exactCase" textMatchStyle, or case-insensitive like the "exact" textMatchStyle (the default). Please see the TextMatchStyle documentation for a discussion of the nuances of case-sensitive matching.

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

getIgnoreTextMatchStyleCaseSensitive

public Boolean getIgnoreTextMatchStyleCaseSensitive()
For fields on this dataSource that specify ignoreTextMatchStyle true, the prevailing textMatchStyle is ignored and Smart GWT matches exact values. This property dictates whether that match is case-sensitive like the "exactCase" textMatchStyle, or case-insensitive like the "exact" textMatchStyle (the default). Please see the TextMatchStyle documentation for a discussion of the nuances of case-sensitive matching.

Returns:
Boolean

setInfoField

public void setInfoField(String infoField)
                  throws IllegalStateException
Name of the field that has the second most pertinent piece of textual information in the record, for use when a DataBoundComponent needs to show a short summary of a record.

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

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

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

getInfoField

public String getInfoField()
Name of the field that has the second most pertinent piece of textual information in the record, for use when a DataBoundComponent needs to show a short summary of a record.

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

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

Returns:
String
See Also:
DsSpecialFields overview and related methods

setInheritsFrom

public void setInheritsFrom(String inheritsFrom)
                     throws IllegalStateException
ID of another DataSource this DataSource inherits its fields from.

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

The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can set useParentFieldOrder to instead use the parent's field order, with new local fields appearing last. You can set showLocalFieldsOnly to have all non-local fields hidden.

Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other via inheritsFrom.

This feature can be used for:

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

getInheritsFrom

public String getInheritsFrom()
ID of another DataSource this DataSource inherits its fields from.

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:

Returns:
String
See Also:
Schema Chaining Example

setJsonPrefix

public void setJsonPrefix(String jsonPrefix)
                   throws IllegalStateException
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.

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

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

Note : This is an advanced setting

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

getJsonPrefix

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

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

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
See Also:
OperationBinding.getDataFormat(), OperationBinding.getDataTransport()

setJsonSuffix

public void setJsonSuffix(String jsonSuffix)
                   throws IllegalStateException
Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.

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

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

Note : This is an advanced setting

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

getJsonSuffix

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

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

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

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

setOperationBindings

public void setOperationBindings(OperationBinding... operationBindings)
                          throws IllegalStateException
Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.

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

For DataSources bound to WSDL-described web services using serviceNamespace, OperationBindings are used to bind each DataSource operationType to an operation of a WSDL-described web service, so that a DataSource can both fetch and save data to a web service.

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

  isc.DataSource.create({
     serviceNamespace : "urn:partner.soap.sforce.com",
     operationBindings : [
         { operationType:"fetch", wsOperation:"query", recordName: "sObject" },
         { operationType:"update", wsOperation:"update", recordName: "SaveResult" },
         { operationType:"add", wsOperation:"create", recordName: "SaveResult" },
         { operationType:"remove", wsOperation:"delete", recordName: "DeleteResult" }
     ],
     ...
  }); 
  
NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.

For DataSources that contact non-WSDL-described XML or JSON services, OperationBindings can be used to separately configure the URL, HTTP method, input and output processing for each operationType. This makes it possible to fetch JSON data from one URL for the "fetch" operationType and save to a web service for the "update" operationType, while appearing as a single integrated DataSource to a DataBoundComponent such as an editable ListGrid.

If no operationBinding is defined for a given DataSource operation, all of the properties which are valid on the operationBinding are checked for on the DataSource itself.

This also means that for a read-only DataSource, that is, a DataSource only capable of fetch operations, operationBindings need not be specified, and instead all operationBinding properties can be set on the DataSource itself. An example of using OperationBinding properties directly on the DataSource in order to read an RSS feed can be found here:

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

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

getOperationBindings

public OperationBinding[] getOperationBindings()
Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.

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

For DataSources bound to WSDL-described web services using serviceNamespace, OperationBindings are used to bind each DataSource operationType to an operation of a WSDL-described web service, so that a DataSource can both fetch and save data to a web service.

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

  isc.DataSource.create({
     serviceNamespace : "urn:partner.soap.sforce.com",
     operationBindings : [
         { operationType:"fetch", wsOperation:"query", recordName: "sObject" },
         { operationType:"update", wsOperation:"update", recordName: "SaveResult" },
         { operationType:"add", wsOperation:"create", recordName: "SaveResult" },
         { operationType:"remove", wsOperation:"delete", recordName: "DeleteResult" }
     ],
     ...
  }); 
  
NOTE: additional code is required to handle authentication and other details, see the complete code in smartclientSDK/examples/databinding/SalesForce.

For DataSources that contact non-WSDL-described XML or JSON services, OperationBindings can be used to separately configure the URL, HTTP method, input and output processing for each operationType. This makes it possible to fetch JSON data from one URL for the "fetch" operationType and save to a web service for the "update" operationType, while appearing as a single integrated DataSource to a DataBoundComponent such as an editable ListGrid.

If no operationBinding is defined for a given DataSource operation, all of the properties which are valid on the operationBinding are checked for on the DataSource itself.

This also means that for a read-only DataSource, that is, a DataSource only capable of fetch operations, operationBindings need not be specified, and instead all operationBinding properties can be set on the DataSource itself. An example of using OperationBinding properties directly on the DataSource in order to read an RSS feed can be found here:

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

Returns:
OperationBinding...
See Also:
OperationBinding

setPatternEscapeChar

public void setPatternEscapeChar(String patternEscapeChar)
                          throws IllegalStateException
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" searchoperator, character that escapes the patternSingleWildcard or patternMultiWildcard if placed before it, so that it is treated as a literal character.

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

getPatternEscapeChar

public String getPatternEscapeChar()
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" searchoperator, character that escapes the patternSingleWildcard or patternMultiWildcard if placed before it, so that it is treated as a literal character.

Returns:
String

setPatternMultiWildcard

public void setPatternMultiWildcard(String patternMultiWildcard)
                             throws IllegalStateException
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.

Pass multiple strings to provide multiple alternative wildcards.

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

getPatternMultiWildcard

public String getPatternMultiWildcard()
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.

Pass multiple strings to provide multiple alternative wildcards.

Returns:
String

setPatternMultiWildcard

public void setPatternMultiWildcard(String... patternMultiWildcard)
                             throws IllegalStateException
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.

Pass multiple strings to provide multiple alternative wildcards.

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

getPatternMultiWildcardAsString

public String[] getPatternMultiWildcardAsString()
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches a series of one or more characters.

Pass multiple strings to provide multiple alternative wildcards.

Returns:
String...

setPatternSingleWildcard

public void setPatternSingleWildcard(String patternSingleWildcard)
                              throws IllegalStateException
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.

Pass multiple strings to provide multiple alternative wildcards.

Parameters:
patternSingleWildcard - Default value is ["?","%"]
Throws:
IllegalStateException - this property cannot be changed after the underlying component has been created

getPatternSingleWildcard

public String getPatternSingleWildcard()
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.

Pass multiple strings to provide multiple alternative wildcards.

Returns:
String

setPatternSingleWildcard

public void setPatternSingleWildcard(String... patternSingleWildcard)
                              throws IllegalStateException
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.

Pass multiple strings to provide multiple alternative wildcards.

Parameters:
patternSingleWildcard - Default value is ["?","%"]
Throws:
IllegalStateException - this property cannot be changed after the underlying component has been created

getPatternSingleWildcardAsString

public String[] getPatternSingleWildcardAsString()
When using the "matchesPattern", "iMatchesPattern", "containsPattern" or "iContainsPattern" search operator, character that matches any single character.

Pass multiple strings to provide multiple alternative wildcards.

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

Parameters:
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 + "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 - 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

setProgressiveLoading

public void setProgressiveLoading(Boolean progressiveLoading)
If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the ResultSet documentation. Essentially, this means that we avoid issuing a row count query and instead advertise total rows as being slightly more than the number of rows we have already read (see endGap). This allows users to load more of a dataset by scrolling past the end of the currently-loaded rows, but it prevents them from scrolling directly to the end of the dataset.

Generally, progressive loading is appropriate when you have to deal with very large datasets. Note that by default, a dataSource will switch into progressive loading mode automatically when it detects that it is dealing with a dataset beyond a certain size - see progressiveLoadingThreshold.

This setting can be overridden for individual fetch operations with the progressiveLoading property, and also at the level of the individual DSRequest. You can also specify progressiveLoading on DataBoundComponents and certain types of FormItem - SelectItem and ComboBoxItem.

Currently, this property only applies to users of the built-in SQLDataSource, but you could use it in custom DataSource implementations to trigger the server behavior described in the ResultSet documentation linked to above.

Parameters:
progressiveLoading - Default value is null
See Also:
com.smartgwt.client.docs.serverds.OperationBinding#progressiveLoading, com.smartgwt.client.docs.serverds.DataSource#progressiveLoadingThreshold, com.smartgwt.client.docs.serverds.DataSource#lookAhead, com.smartgwt.client.docs.serverds.DataSource#endGap, ProgressiveLoading overview and related methods

getProgressiveLoading

public Boolean getProgressiveLoading()
If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the ResultSet documentation. Essentially, this means that we avoid issuing a row count query and instead advertise total rows as being slightly more than the number of rows we have already read (see endGap). This allows users to load more of a dataset by scrolling past the end of the currently-loaded rows, but it prevents them from scrolling directly to the end of the dataset.

Generally, progressive loading is appropriate when you have to deal with very large datasets. Note that by default, a dataSource will switch into progressive loading mode automatically when it detects that it is dealing with a dataset beyond a certain size - see progressiveLoadingThreshold.

This setting can be overridden for individual fetch operations with the progressiveLoading property, and also at the level of the individual DSRequest. You can also specify progressiveLoading on DataBoundComponents and certain types of FormItem - SelectItem and ComboBoxItem.

Currently, this property only applies to users of the built-in SQLDataSource, but you could use it in custom DataSource implementations to trigger the server behavior described in the ResultSet documentation linked to above.

Returns:
Boolean
See Also:
com.smartgwt.client.docs.serverds.OperationBinding#progressiveLoading, com.smartgwt.client.docs.serverds.DataSource#progressiveLoadingThreshold, com.smartgwt.client.docs.serverds.DataSource#lookAhead, com.smartgwt.client.docs.serverds.DataSource#endGap, ProgressiveLoading overview and related methods

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 - Default value is true
Throws:
IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:
com.smartgwt.client.docs.serverds.OperationBinding#qualifyColumnNames

getQualifyColumnNames

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

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

setRecordXPath

public void setRecordXPath(String recordXPath)
                    throws IllegalStateException
See recordXPath. recordXPath can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations.

Parameters:
recordXPath - See XPathExpression . 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:
See XPathExpression
See Also:
ClientDataIntegration overview and related methods, XML DataSource Example, JSON XPath Binding Example

setRequestProperties

public void setRequestProperties(DSRequest requestProperties)
                          throws IllegalStateException
Additional properties to pass through to the DSRequests made by this DataSource.

These properties are applied before DataSource.transformRequest is called.

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

getRequestProperties

public DSRequest getRequestProperties()
Additional properties to pass through to the DSRequests made by this DataSource.

These properties are applied before DataSource.transformRequest is called.

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

setRequiredMessage

public void setRequiredMessage(String requiredMessage)
The required message when a field that has been marked as required is not filled in by the user.

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

getRequiredMessage

public String getRequiredMessage()
The required message when a field that has been marked as required is not filled in by the user.

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

setResultSetClass

public void setResultSetClass(String resultSetClass)
                       throws IllegalStateException
Class for ResultSets used by this datasource. If null, defaults to using ResultSet.

This can be set to a custom subclass of ResultSet that, for example, hangs onto to extra information necessary for integration with web services.

Note : This is an advanced setting

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

getResultSetClass

public String getResultSetClass()
Class for ResultSets used by this datasource. If null, defaults to using ResultSet.

This can be set to a custom subclass of ResultSet that, for example, hangs onto to extra information necessary for integration with web services.

Returns:
String

getSchemaNamespace

public String getSchemaNamespace()
                          throws IllegalStateException
For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to. This is a read-only attribute automatically present on DataSources returned from SchemaSet.getSchema and WebService.getSchema.

Note : This method should be called only after the underlying component has been created.

Returns:
String
Throws:
IllegalStateException - if the 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 - 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

setSendParentNode

public void setSendParentNode(Boolean sendParentNode)
Set this attribute if you need to send the dsRequest.parentNode to the server-side.

Note : This is an advanced setting

Parameters:
sendParentNode - Default value is false

getSendParentNode

public Boolean getSendParentNode()
Set this attribute if you need to send the dsRequest.parentNode to the server-side.

Returns:
Boolean

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 - 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 - 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 in order to block user interactions until the request completes.

DataSource requests default to blocking UI interaction because, very often, if the user continues to interact with an application that is waiting for a server response, some kind of invalid or ambiguous situation can arise.

Examples include pressing a "Save" button a second time before the first save completes, making further edits while edits are still being saved, or trying to initiate editing on a grid that hasn't loaded data.

Defaulting to blocking the UI prevents these bad interactions, or alternatively, avoids the developer having to write repetitive code to block invalid interactions on every screen.

If an operation should ever be non-blocking, methods that initiate DataSource requests (such as DataSource.fetchData) will generally have a requestProperties argument allowing showPrompt to be set to false for a specific request.

Parameters:
showPrompt - Default value is true

getShowPrompt

public Boolean getShowPrompt()
Whether RPCRequests sent by this DataSource should enable showPrompt in order to block user interactions until the request completes.

DataSource requests default to blocking UI interaction because, very often, if the user continues to interact with an application that is waiting for a server response, some kind of invalid or ambiguous situation can arise.

Examples include pressing a "Save" button a second time before the first save completes, making further edits while edits are still being saved, or trying to initiate editing on a grid that hasn't loaded data.

Defaulting to blocking the UI prevents these bad interactions, or alternatively, avoids the developer having to write repetitive code to block invalid interactions on every screen.

If an operation should ever be non-blocking, methods that initiate DataSource requests (such as DataSource.fetchData) will generally have a requestProperties argument allowing showPrompt to be set to false for a specific request.

Returns:
Boolean

setStrictSQLFiltering

public void setStrictSQLFiltering(Boolean strictSQLFiltering)
                           throws IllegalStateException
If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:
     field == "someValue"  (normally false)
     field != "someValue"  (normally true)
     not (field == "someValue")   (normally true)
     not (field != "someValue")   (normally false)
  
This property can be overridden per-query by specifying strictSQLFiltering directly as a property on the AdvancedCriteria.

NOTE: On the server side, this property is only applicable if you are using the SQL DataSource; the other built-in types (Hibernate and JPA/JPA2) do not offer this mode.

Note : This is an advanced setting

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

getStrictSQLFiltering

public Boolean getStrictSQLFiltering()
If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:
     field == "someValue"  (normally false)
     field != "someValue"  (normally true)
     not (field == "someValue")   (normally true)
     not (field != "someValue")   (normally false)
  
This property can be overridden per-query by specifying strictSQLFiltering directly as a property on the AdvancedCriteria.

NOTE: On the server side, this property is only applicable if you are using the SQL DataSource; the other built-in types (Hibernate and JPA/JPA2) do not offer this mode.

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

If is unset, getAutoTitle() method will be used with dataSource.ID. value in order to derive a default value for the title.

For example "employee" ID will be derived to "Employee", "team_member" ID will be derived to "Team Member".

Parameters:
title - Default value is dataSource.ID

getTitle

public String getTitle()
User-visible name for this DataSource.

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

If is unset, getAutoTitle() method will be used with dataSource.ID. value in order to derive a default value for the title.

For example "employee" ID will be derived to "Employee", "team_member" ID will be derived to "Team Member".

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 - Default value is see below
Throws:
IllegalStateException - this property cannot be changed after the underlying component has been created
See Also:
DsSpecialFields overview and related methods

getTitleField

public String getTitleField()
Best field to use for a user-visible title for an individual record from this dataSource.

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

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
See Also:
DsSpecialFields overview and related methods

setTranslatePatternOperators

public void setTranslatePatternOperators(boolean translatePatternOperators)
                                  throws IllegalStateException
Search operators like "matchesPattern" use patterns like "foo*txt" to match text values. The patterns are similar to the patterns you use to match names of files in a command-line interface, or to the pattern allowed for the SQL "LIKE" operator.

translatePatternOperators controls whether these pattern operators should be translated to a nested series of "startsWith"/"endsWidth"/"contains" operators before being sent to the server. This allows a server that only implements simple operators like "startsWith" to support pattern operators such as "matchesPattern" and "containsPattern", but with caveats:

Note that since "containsPattern" is essentially equivalent to "matchesPattern" but with "*" wildcards at the beginning and end of every pattern, the second limitation (pattern not really order dependent) may be fairly obvious to users when using this feature. For example, "m*t" will match "we meet" and "we teem".

The following are examples of how patterns are translated to simpler operators. Note that the case sensitive version of the operator is referred to below, but of course "iMatchesPattern" and "iContainsPattern" will be translated to case-insensitive versions of these operators, such as "iStartsWith".

*foo (endsWith)
foo* (startsWith)
*foo* (contains)
*foo*bar (contains and endsWith)
foo*bar* (startsWith and contains)
foo*bar (startsWith and endsWith)
*foo*bar* (multiple contains)

Also supported: one startsWith, multiple contains, one endsWith.

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

getTranslatePatternOperators

public boolean getTranslatePatternOperators()
Search operators like "matchesPattern" use patterns like "foo*txt" to match text values. The patterns are similar to the patterns you use to match names of files in a command-line interface, or to the pattern allowed for the SQL "LIKE" operator.

translatePatternOperators controls whether these pattern operators should be translated to a nested series of "startsWith"/"endsWidth"/"contains" operators before being sent to the server. This allows a server that only implements simple operators like "startsWith" to support pattern operators such as "matchesPattern" and "containsPattern", but with caveats:

Note that since "containsPattern" is essentially equivalent to "matchesPattern" but with "*" wildcards at the beginning and end of every pattern, the second limitation (pattern not really order dependent) may be fairly obvious to users when using this feature. For example, "m*t" will match "we meet" and "we teem".

The following are examples of how patterns are translated to simpler operators. Note that the case sensitive version of the operator is referred to below, but of course "iMatchesPattern" and "iContainsPattern" will be translated to case-insensitive versions of these operators, such as "iStartsWith".

*foo (endsWith)
foo* (startsWith)
*foo* (contains)
*foo*bar (contains and endsWith)
foo*bar* (startsWith and contains)
foo*bar (startsWith and endsWith)
*foo*bar* (multiple contains)

Also supported: one startsWith, multiple contains, one endsWith.

Returns:
boolean

setTrimMilliseconds

public void setTrimMilliseconds(Boolean trimMilliseconds)
                         throws IllegalStateException
For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa. By default, millisecond information is preserved (ie, it is not trimmed). You only need to consider trimming millisecond values if their presence causes a problem - for example, a custom server that is not expecting that extra information and so fails parsing.

Note that there is no inherent support for millisecond precision in Smart GWT widgets; if you need millisecond-precise visibility and editability of values in your client, you must write custom formatters and editors (or sponsor the addition of such things to the framework). Server-side, millisecond-precise values are delivered to and obtained from DataSourcea, so DataSource implementations that are capable of persisting and reading millisecond values should work transparently. Of the built-in DataSource types, the JPA and Hibernate DataSources will transparently handle millisecond-precise values as long as the underlying database supports millisecond precision, and the underlying column is of an appropriate type.

The SQLDataSource was designed for accuracy to the nearest second, and making it support millisecond accuracy requires a couple of steps:

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

getTrimMilliseconds

public Boolean getTrimMilliseconds()
For this dataSource, should the millisecond portion of time and datetime values be trimmed off before before being sent from client to server or vice versa. By default, millisecond information is preserved (ie, it is not trimmed). You only need to consider trimming millisecond values if their presence causes a problem - for example, a custom server that is not expecting that extra information and so fails parsing.

Note that there is no inherent support for millisecond precision in Smart GWT widgets; if you need millisecond-precise visibility and editability of values in your client, you must write custom formatters and editors (or sponsor the addition of such things to the framework). Server-side, millisecond-precise values are delivered to and obtained from DataSourcea, so DataSource implementations that are capable of persisting and reading millisecond values should work transparently. Of the built-in DataSource types, the JPA and Hibernate DataSources will transparently handle millisecond-precise values as long as the underlying database supports millisecond precision, and the underlying column is of an appropriate type.

The SQLDataSource was designed for accuracy to the nearest second, and making it support millisecond accuracy requires a couple of steps:

Returns:
Boolean

setUseFlatFields

public void setUseFlatFields(Boolean useFlatFields)
                      throws IllegalStateException
Like useFlatFields, but applies to all DataBound components that bind to this DataSource.

Parameters:
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 - 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 - Default value is null
See Also:
Validation overview and related methods

getUseLocalValidators

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

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

Returns:
Boolean
See Also:
Validation overview and related methods

setUseOfflineStorage

public void setUseOfflineStorage(Boolean useOfflineStorage)
Whether we store server responses for this DataSource into browser-based offline storage, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server). Note that by default we do NOT use offline storage for a dataSource.

Parameters:
useOfflineStorage - Default value is null

getUseOfflineStorage

public Boolean getUseOfflineStorage()
Whether we store server responses for this DataSource into browser-based offline storage, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server). Note that by default we do NOT use offline storage for a dataSource.

Returns:
Boolean

setUseParentFieldOrder

public void setUseParentFieldOrder(Boolean useParentFieldOrder)
                            throws IllegalStateException
For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource. New fields, if any, are placed at the end.

Parameters:
useParentFieldOrder - 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

setUseStrictJSON

public void setUseStrictJSON(Boolean useStrictJSON)
                      throws IllegalStateException
Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.

Only applies to dataSources which send requests to a server and have dataFormat set to "json" or "iscServer".

Note: using strict JSON avoids a known issue in Internet Explorer 9 where datasource transactions can leak memory due to a browser behavior where the native eval() method fails to clean up references when the objects go out of scope. See allowIE9Leak for more on this.

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

getUseStrictJSON

public Boolean getUseStrictJSON()
Should HTTP responses to requests by this dataSource be formatted using the strict JSON subset of the javascript language? If set to true, responses returned by the server should match the format described here.

Only applies to dataSources which send requests to a server and have dataFormat set to "json" or "iscServer".

Note: using strict JSON avoids a known issue in Internet Explorer 9 where datasource transactions can leak memory due to a browser behavior where the native eval() method fails to clean up references when the objects go out of scope. See allowIE9Leak for more on this.

Returns:
Boolean

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 testFileName is specified on the DataSource.

Parameters:
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 testFileName 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 - 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

addData

public void addData(Record newRecord)
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.

NOTE: do not use this method to populate a clientOnly DataSource. Set cacheData instead.

Parameters:
newRecord - new record
See Also:
Operations overview and related methods

addData

public void addData(Record newRecord,
                    DSCallback callback)
See Also:
DataSource#addData()}

addData

public void addData(Record newRecord,
                    DSCallback callback,
                    DSRequest requestProperties)
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.

NOTE: do not use this method to populate a clientOnly DataSource. Set cacheData instead.

Parameters:
newRecord - new record
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

compareCriteria

public int compareCriteria(Criteria newCriteria,
                           Criteria oldCriteria)
Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.

Comparisons between AdvancedCriteria are made via recursively calling Operator.compareCriteria for all criteria involved.

For simple Criteria, by default (CriteriaPolicy:"dropOnShortening"), returns:

For (CriteriaPolicy:"dropOnChange"), returns:

This method is called by ResultSet.compareCriteria to determine whether a change in criteria should cause the cache to be invalidated. You may want to override this method in order to mimic the filtering behavior that your server performs.

Parameters:
newCriteria - new filter criteria
oldCriteria - previous filter criteria
Returns:
0 if the filters are equivalent, 1 if newCriteria is guaranteed more restrictive, and -1 if newCriteria is not guaranteed more restrictive
See Also:
CriteriaPolicy

compareCriteria

public int compareCriteria(Criteria newCriteria,
                           Criteria oldCriteria,
                           DSRequest requestProperties)
See Also:
DataSource#compareCriteria()}

compareCriteria

public int compareCriteria(Criteria newCriteria,
                           Criteria oldCriteria,
                           DSRequest requestProperties,
                           String policy)
Given two sets of criteria, determine whether they are equivalent, the new criteria is guaranteed more restrictive, or the new criteria is not guaranteed more restrictive, returning 0, 1 or -1 respectively.

Comparisons between AdvancedCriteria are made via recursively calling Operator.compareCriteria for all criteria involved.

For simple Criteria, by default (CriteriaPolicy:"dropOnShortening"), returns:

For (CriteriaPolicy:"dropOnChange"), returns:

This method is called by ResultSet.compareCriteria to determine whether a change in criteria should cause the cache to be invalidated. You may want to override this method in order to mimic the filtering behavior that your server performs.

Parameters:
newCriteria - new filter criteria
oldCriteria - previous filter criteria
requestProperties - dataSource request properties
policy - overrides CriteriaPolicy
Returns:
0 if the filters are equivalent, 1 if newCriteria is guaranteed more restrictive, and -1 if newCriteria is not guaranteed more restrictive
See Also:
CriteriaPolicy

compareDates

public int compareDates(Date date1,
                        Date date2,
                        String fieldName)
Convenience method to compare two Date objects appropriately, depending on whether the passed-in fieldName refers to a field of type "datetime" or "date". In the former case, the dates are compared using Date.compareDates; in the latter case, or if the supplied fieldName is null or unknown to this DataSource, the dates are compared using Date.compareLogicalDates.

Parameters:
date1 - First date in comparison
date2 - Second date in comparison
fieldName - The name of the field for which the comparison is being run
Returns:
0 if equal, -1 if first date > second date, 1 if second date > first date

convertDataSourceCriteria

public AdvancedCriteria convertDataSourceCriteria(Criteria criteria)
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object. This instance method differs from the class method DataSource.convertCriteria in that it makes use of the dataSource as schema to help in the conversion. For example, this method is able to honor ignoreTextMatchStyle and use the dataSource's defaultTextMatchStyle rather than assuming "substring"

Parameters:
criteria - simple criteria
Returns:
equivalent AdvancedCriteria object

convertDataSourceCriteria

public AdvancedCriteria convertDataSourceCriteria(Criteria criteria,
                                                  TextMatchStyle textMatchStyle)
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object. This instance method differs from the class method DataSource.convertCriteria in that it makes use of the dataSource as schema to help in the conversion. For example, this method is able to honor ignoreTextMatchStyle and use the dataSource's defaultTextMatchStyle rather than assuming "substring"

Parameters:
criteria - simple criteria
textMatchStyle - default style of matching text. Defaults to the dataSource's defaultTextMatchStyle
Returns:
equivalent AdvancedCriteria object

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)
See Also:
DataSource#convertRelativeDates()}

convertRelativeDates

public Criteria convertRelativeDates(Criteria criteria,
                                     String timezoneOffset,
                                     Integer firstDayOfWeek)
See Also:
DataSource#convertRelativeDates()}

convertRelativeDates

public Criteria convertRelativeDates(Criteria criteria,
                                     String timezoneOffset,
                                     Integer firstDayOfWeek,
                                     Date baseDate)
Takes all relative date values found anywhere within a Criteria / AdvancedCriteria object and converts them to concrete date values, returning the new criteria object.

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

copyRecords

public Record[] copyRecords(Record... records)
Copies all DataSource field values of an (Array) of Records (including a TreeNode) to a new array of Records, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes. This method calls DataSource.copyRecord for each item in the array.

Parameters:
records - The array of Record objects to be copied.
Returns:
A new copy of each record provided in the array argument, with component-specific metata data removed.

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 associated with some record.

Note that if this method is called for a record with no associated file, the download URL may not be functional. By default when dataSources encounter a binary type fields, an additional field, <fieldName>_filename, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to download a file.

See the overview of Binary Fields for more details.

Parameters:
data - Record to download. Only required to have a value for the primary key field.

downloadFile

public void downloadFile(Record data,
                         String fieldName)
See Also:
DataSource#downloadFile()}

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 associated with some record.

Note that if this method is called for a record with no associated file, the download URL may not be functional. By default when dataSources encounter a binary type fields, an additional field, <fieldName>_filename, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to download a file.

See the overview of Binary Fields for more details.

Parameters:
data - Record to download. Only required to have a value for the primary key field.
fieldName - optional name of the binary field containing the file. If not provided, the first binary field is used
requestProperties - additional properties to set on the DSRequest that will be issued

evaluateCriterion

public boolean evaluateCriterion(Record record,
                                 Criterion criterion)
Evaluate the given criterion with respect to the passed record.

Typically called by the condition function of a custom Operator to evaluate sub-criteria.

Parameters:
record - record to evaluate
criterion - criterion to use
Returns:
whether the record meets the supplied Criterion

exportData

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

See Also:
Operations overview and related methods

exportData

public void exportData(Criteria criteria)
See Also:
DataSource#exportData()}

exportData

public void exportData(Criteria criteria,
                       DSRequest requestProperties)
See Also:
DataSource#exportData()}

exportData

public void exportData(Criteria criteria,
                       DSRequest requestProperties,
                       DSCallback callback)
Perform a "fetch" DataSource operation against this DataSource, sending search criteria, retrieving matching records and exporting the results. See exportResults or exportResults and for more information.

Parameters:
criteria - search criteria
requestProperties - additional properties to set on the DSRequest that will be issued
callback - callback to invoke on completion. Note that this parameter only applies where exportToClient is explicitly set to false, because file downloads do not provide ordinary Smart GWT callbacks
See Also:
Operations overview and related methods

fetchData

public void fetchData()
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

NOTE: do not attempt to override this method to create a custom DataSource. For a server-side custom DataSource, use the serverConstructor attribute, and the @see Custom DataSource samples. For a client-side custom DataSource, see dataProtocol:"custom".

In contrast to ListGrid.fetchData, which creates a ResultSet to manage the returned data, calling dataSource.fetchData() provides the returned data in the callback as a RecordList or simple Array of Record objects. Calling dataSource.fetchData() does not automatically update any visual components or caches: code in the callback passed to fetchData() decides what to do with the returned data.

For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:

     
     DataSource.get("employees").fetchData(null, new DSCallback() {
         public void execute(DSResponse response, Object rawData, DSRequest request) {
             myGrid.setData(response.getData());
         }
     });
  
Unlike calling myGrid.fetchData(), which creates a ResultSet, the data provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.

Disconnected datasets may be used to populate various visual components. For example, while an individual FormItem can be configured to fetch valueMap options from a DataSource via the optionDataSource property, the following code shows storing a dataset to derive valueMaps from later:

     
     
       // Assume GlobalStore.allCountries is a public static variable of type RecordList 
       DataSource.get("countries").fetchData(null, new DSCallback(){
          public void execute(DSResponse response, Object rawData, DSRequest request) {
             GlobalStore.allCountries = response.getDataAsRecordList();
          }
       });
       ... later, while a DynamicForm is being created ...    
       SelectItem select = new SelectItem("country", "Pick Country");
       Map valueMap = GlobalStore.countries.getValueMap("countryId", "countryName");
       myItem.setValueMap(new LinkedHashMap(valueMap));
     
  

You can also create a ResultSet from the data retrieved from fetchData(), like so:

     
     
     DataSource.get("countries").fetchData(null, new DSCallback() {
         public void execute(DSResponse response, Object rawData, DSRequest request) {
             ResultSet rs = new ResultSet(DataSource.get("countries"));
             rs.setAllRows(response.getData());
         }
     });
     
  

This gives you a dataset that supports client-side filtering (via setCriteria()), can provide filtered valueMaps, will automatically reflect updates to the DataSource made via other components, and can be re-used with multiple visual components.

See also DataSource.getClientOnlyDataSource and cacheAllData for similar capabilities for dealing with smaller datasets entirely within the browser, or working with modifiable caches representing subsets of the data available from a DataSource.

See also the server-side com.isomorphic.js.JSTranslater class in the ${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. For example, if you had a DataSource "myGridFields" whose fields included the basic properties of ListGridField (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:

    
    DataSource.get("myFormFields").fetchData(null, new DSCallback(){
        public void execute(DSResponse response, Object rawData, DSRequest request) {
           Record[] records = response.getData();
           ListGridField[] fields = new ListGridField[records.length];
           for (Record record in records) {
               ListGridField field = new ListGridField();
               field.setName(record.getAttribute("name"));
               field.setTitle(record.getAttribute("title"));
               field.setType(ListGridFieldType.valueOf(record.getAttribute("type")));
           }
           ListGrid grid = new ListGrid();
           grid.setFields(fields);
        }
    });
  
This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also the server-side API com.isomorphic.datasource.DataSource.addDynamicDSGenerator() for dynamically creating DataSources supporting all server-side DataSource features, and inheritsFrom for sharing field definitions across multiple DataSources.

See Also:
Operations overview and related methods

fetchData

public void fetchData(Criteria criteria)
See Also:
DataSource#fetchData()}

fetchData

public void fetchData(Criteria criteria,
                      DSCallback callback)
See Also:
DataSource#fetchData()}

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.

NOTE: do not attempt to override this method to create a custom DataSource. For a server-side custom DataSource, use the serverConstructor attribute, and the @see Custom DataSource samples. For a client-side custom DataSource, see dataProtocol:"custom".

In contrast to ListGrid.fetchData, which creates a ResultSet to manage the returned data, calling dataSource.fetchData() provides the returned data in the callback as a RecordList or simple Array of Record objects. Calling dataSource.fetchData() does not automatically update any visual components or caches: code in the callback passed to fetchData() decides what to do with the returned data.

For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:

     
     DataSource.get("employees").fetchData(null, new DSCallback() {
         public void execute(DSResponse response, Object rawData, DSRequest request) {
             myGrid.setData(response.getData());
         }
     });
  
Unlike calling myGrid.fetchData(), which creates a ResultSet, the data provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.

Disconnected datasets may be used to populate various visual components. For example, while an individual FormItem can be configured to fetch valueMap options from a DataSource via the optionDataSource property, the following code shows storing a dataset to derive valueMaps from later:

     
     
       // Assume GlobalStore.allCountries is a public static variable of type RecordList 
       DataSource.get("countries").fetchData(null, new DSCallback(){
          public void execute(DSResponse response, Object rawData, DSRequest request) {
             GlobalStore.allCountries = response.getDataAsRecordList();
          }
       });
       ... later, while a DynamicForm is being created ...    
       SelectItem select = new SelectItem("country", "Pick Country");
       Map valueMap = GlobalStore.countries.getValueMap("countryId", "countryName");
       myItem.setValueMap(new LinkedHashMap(valueMap));
     
  

You can also create a ResultSet from the data retrieved from fetchData(), like so:

     
     
     DataSource.get("countries").fetchData(null, new DSCallback() {
         public void execute(DSResponse response, Object rawData, DSRequest request) {
             ResultSet rs = new ResultSet(DataSource.get("countries"));
             rs.setAllRows(response.getData());
         }
     });
     
  

This gives you a dataset that supports client-side filtering (via setCriteria()), can provide filtered valueMaps, will automatically reflect updates to the DataSource made via other components, and can be re-used with multiple visual components.

See also DataSource.getClientOnlyDataSource and cacheAllData for similar capabilities for dealing with smaller datasets entirely within the browser, or working with modifiable caches representing subsets of the data available from a DataSource.

See also the server-side com.isomorphic.js.JSTranslater class in the ${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. For example, if you had a DataSource "myGridFields" whose fields included the basic properties of ListGridField (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:

    
    DataSource.get("myFormFields").fetchData(null, new DSCallback(){
        public void execute(DSResponse response, Object rawData, DSRequest request) {
           Record[] records = response.getData();
           ListGridField[] fields = new ListGridField[records.length];
           for (Record record in records) {
               ListGridField field = new ListGridField();
               field.setName(record.getAttribute("name"));
               field.setTitle(record.getAttribute("title"));
               field.setType(ListGridFieldType.valueOf(record.getAttribute("type")));
           }
           ListGrid grid = new ListGrid();
           grid.setFields(fields);
        }
    });
  
This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also the server-side API com.isomorphic.datasource.DataSource.addDynamicDSGenerator() for dynamically creating DataSources supporting all server-side DataSource features, and inheritsFrom for sharing field definitions across multiple DataSources.

Parameters:
criteria - search criteria
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

fetchRecord

public void fetchRecord(Object pkValue)
Fetch a single record from the DataSource by primary key. This simply calls DataSource.fetchData after creating Criteria that contain the primary key field and value.

If you call this method on a DataSource with a composite primary key - ie, one with multiple primaryKey fields - this method returns the first record where the first defined primary field matches the supplied pkValue; this may or may not be meaningful, depending on your use case. Generally, for DataSources with composite keys, it makes more sense to use fetchData() directly, rather than this convenience method.

Parameters:
pkValue - value for the field marked primaryKey:true in this DataSource (or the first field so marked if there is more than one)

fetchRecord

public void fetchRecord(Object pkValue,
                        DSCallback callback)
See Also:
DataSource#fetchRecord()}

fetchRecord

public void fetchRecord(Object pkValue,
                        DSCallback callback,
                        DSRequest requestProperties)
Fetch a single record from the DataSource by primary key. This simply calls DataSource.fetchData after creating Criteria that contain the primary key field and value.

If you call this method on a DataSource with a composite primary key - ie, one with multiple primaryKey fields - this method returns the first record where the first defined primary field matches the supplied pkValue; this may or may not be meaningful, depending on your use case. Generally, for DataSources with composite keys, it makes more sense to use fetchData() directly, rather than this convenience method.

Parameters:
pkValue - value for the field marked primaryKey:true in this DataSource (or the first field so marked if there is more than one)
callback - callback to invoke on completion
requestProperties - additional properties to set on the DSRequest that will be issued

fieldMatchesFilter

public boolean fieldMatchesFilter(Object fieldValue,
                                  Object filterValue)
Compares a criteria value to a field value and returns whether they match, as follows:

Parameters:
fieldValue - field value to be compared
filterValue - filter value to be compared
Returns:
true if the filter and field values match, false otherwise

fieldMatchesFilter

public boolean fieldMatchesFilter(Object fieldValue,
                                  Object filterValue,
                                  DSRequest requestProperties)
Compares a criteria value to a field value and returns whether they match, as follows:

Parameters:
fieldValue - field value to be compared
filterValue - filter value to be compared
requestProperties - optional dataSource request properties
Returns:
true if the filter and field values match, false otherwise

filterData

public void filterData()
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

This is identical to DataSource.fetchData except that textMatchStyle is set to "substring" to cause case insensitive substring matching (if the server respects this setting).

See Also:
Operations overview and related methods

filterData

public void filterData(Criteria criteria)
See Also:
DataSource#filterData()}

filterData

public void filterData(Criteria criteria,
                       DSCallback callback)
See Also:
DataSource#filterData()}

filterData

public void filterData(Criteria criteria,
                       DSCallback callback,
                       DSRequest requestProperties)
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.

This is identical to DataSource.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
requestProperties - additional properties to set on the DSRequest that will be issued
See Also:
Operations overview and related methods

getClientOnlyDataSource

public void getClientOnlyDataSource(Criteria criteria,
                                    ClientOnlyDataSourceCallback callback)
Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that inheritsFrom the original DataSource.

This clientOnly "copy" can be useful in situations where you want to allow a series of local changes without immediately committing to the server. See also autoSaveEdits for more fine-grained tracking of edits (eg, special styling for uncommitted changes).

The new DataSource is returned via the "callback" argument. If cacheAllData is enabled and DataSource.hasAllData returns true, the new DataSource is synchronously returned as the result of the method. In this case, if a callback was passed, it also is executed synchronously.

Parameters:
criteria - The criteria for the clientOnly DS
callback - The callback to fire passing the clientOnly DS

getClientOnlyDataSource

public void getClientOnlyDataSource(Criteria criteria,
                                    ClientOnlyDataSourceCallback callback,
                                    DSRequest requestProperties)
See Also:
DataSource#getClientOnlyDataSource()}

getClientOnlyDataSource

public void getClientOnlyDataSource(Criteria criteria,
                                    ClientOnlyDataSourceCallback callback,
                                    DSRequest requestProperties,
                                    DataSource dataSourceProperties)
Produces a clientOnly "copy" of a particular subset of data from a normal DataSource, via calling fetchData() to fetch matching rows, and constructing a clientOnly DataSource that inheritsFrom the original DataSource.

This clientOnly "copy" can be useful in situations where you want to allow a series of local changes without immediately committing to the server. See also autoSaveEdits for more fine-grained tracking of edits (eg, special styling for uncommitted changes).

The new DataSource is returned via the "callback" argument. If cacheAllData is enabled and DataSource.hasAllData returns true, the new DataSource is synchronously returned as the result of the method. In this case, if a callback was passed, it also is executed synchronously.

Parameters:
criteria - The criteria for the clientOnly DS
callback - The callback to fire passing the clientOnly DS
requestProperties - optional properties to pass through to the DSRequest
dataSourceProperties - optional properties to pass through to the clientOnly DS

getClientOnlyResponse

protected DSResponse getClientOnlyResponse(DSRequest request,
                                           Record... serverData)
Return a "spoofed" response for a clientOnly or cacheAllData DataSource.

The default implementation will use cacheData to provide an appropriate response, by using client-side filtering for a "fetch" request, and by modifying the 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 providers, such as GWT-RPC, HTML5 sockets, or bridges to plug-in based protocols (Java, Flash, Silverlight..), use dataProtocol:"clientCustom" instead.

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

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

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

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

getFetchDataURL

public String getFetchDataURL(Criteria criteria)
Returns a URL to DataSource fetch operation. This API is intended to return media such as images or videos to the browser.

Note that because the entirety of the request is encoded in the URL, there is an inherent limitation on the amount of data that you can send viat he criteria argument to the server. The actual length depends on your server configuration and other factors such as the size of cookies (if any) being sent to the server and other HTTP headers in use. Conservatively, assume that you have about 2 kilobytes to work with.

Parameters:
criteria - Criteria to be sent to server.
Returns:
a URL that targets the specified fetch operation.

getFetchDataURL

public String getFetchDataURL(Criteria criteria,
                              DSRequest requestProperties)
Returns a URL to DataSource fetch operation. This API is intended to return media such as images or videos to the browser.

Note that because the entirety of the request is encoded in the URL, there is an inherent limitation on the amount of data that you can send viat he criteria argument to the server. The actual length depends on your server configuration and other factors such as the size of cookies (if any) being sent to the server and other HTTP headers in use. Conservatively, assume that you have about 2 kilobytes to work with.

Parameters:
criteria - Criteria to be sent to server.
requestProperties - additional properties to set on the DSRequest that will be issued
Returns:
a URL that targets the specified fetch operation.

getField

public DataSourceField getField(String fieldName)
Return the field definition object.

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

getFieldCriterion

public Criteria getFieldCriterion(Criteria criterion,
                                  String fieldName)
Returns the depth-first match of a criterion matching the given fieldName.

Parameters:
criterion - the criteria to search
fieldName - the fieldName to find criteria for
Returns:
the depth-first matching criterion for the passed fieldName

getFieldForDataPath

public DataSourceField getFieldForDataPath(String dataPath)
Return the field definition object corresponding to the supplied dataPath

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

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

getFileURL

public String getFileURL(Record data)
Returns a direct URL to access a file stored in a field of type:"binary".

This URL can be used as the "src" attribute of an Img widget or <img> tag (if the file is an image), or can be used in an ordinary HTML link (<a> tag) to download the file. However, for the latter use case, see also DataSource.downloadFile and DataSource.viewFile.

The URL returned is not to a static file on disk, rather, the returned URL essentially encodes a DSRequest as URL parameters, in a format understood by the IDACall servlet that comes with the Server Framework.

Hence, this URL will dynamically retrieve whatever file is currently stored in the binary field via executing a normal DSRequest server side. The request will run through normal security checks, so if your application requires authentication, the user must have a valid session and be authorized to access the binary field.

Note that if this method is called for a record with no associated file, the returned URL may not be functional. By default when dataSources encounter a binary type fields, an additional field, <fieldName>_filename, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to retrieve a download URL.

Parameters:
data - Record or value of primary key field for record containing the file to view.
Returns:
a URL to directly access the stored file

getFileURL

public String getFileURL(Record data,
                         String fieldName)
See Also:
DataSource#getFileURL()}

getFileURL

public String getFileURL(Record data,
                         String fieldName,
                         DSRequest requestProperties)
Returns a direct URL to access a file stored in a field of type:"binary".

This URL can be used as the "src" attribute of an Img widget or <img> tag (if the file is an image), or can be used in an ordinary HTML link (<a> tag) to download the file. However, for the latter use case, see also DataSource.downloadFile and DataSource.viewFile.

The URL returned is not to a static file on disk, rather, the returned URL essentially encodes a DSRequest as URL parameters, in a format understood by the IDACall servlet that comes with the Server Framework.

Hence, this URL will dynamically retrieve whatever file is currently stored in the binary field via executing a normal DSRequest server side. The request will run through normal security checks, so if your application requires authentication, the user must have a valid session and be authorized to access the binary field.

Note that if this method is called for a record with no associated file, the returned URL may not be functional. By default when dataSources encounter a binary type fields, an additional field, <fieldName>_filename, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to retrieve a download URL.

Parameters:
data - Record or value of primary key field for record containing the file to view.
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
Returns:
a URL to directly access the stored file

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. If this dataSource has a composite primary key (ie, multiple primaryKey fields), returns just the first primaryKey field.

Returns:
primary key field object
See Also:
getPrimaryKeyFields()

getPrimaryKeyFieldName

public String getPrimaryKeyFieldName()
Returns the primary key fieldName for this DataSource. If this dataSource has a composite primary key (ie, multiple primaryKey fields), returns just the first primaryKey field name.

Returns:
primary key field name
See Also:
getPrimaryKeyFieldNames()

getPrimaryKeyFieldNames

public String[] getPrimaryKeyFieldNames()
Returns a list of the names of this DataSource's primaryKey fields.

Returns:
The list of the names of this datasource's primaryKey fields
See Also:
getPrimaryKeyFields()

getPrimaryKeyFields

public Record getPrimaryKeyFields()
Returns this DataSource's primaryKey fields as a map of fieldName to field.

Returns:
Javascript object containing all this datasource's primaryKey fields, as a map of field name to field
See Also:
getPrimaryKeyField(), getPrimaryKeyFieldNames()

getTypeOperators

public OperatorId[] getTypeOperators()
Get the list of OperatorIds available on this DataSource for the given FieldType.

If DataSource.setTypeOperators has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for the FieldType as specified by validOperators, otherwise, the system-wide set of valid operators for the type as registered via DataSource.addSearchOperator.

Returns:
available Operators

getTypeOperators

public OperatorId[] getTypeOperators(FieldType typeName)
Get the list of OperatorIds available on this DataSource for the given FieldType.

If DataSource.setTypeOperators has been called for this DataSource and FieldType, returns that list, otherwise, returns the set of valid operators for the FieldType as specified by validOperators, otherwise, the system-wide set of valid operators for the type as registered via DataSource.addSearchOperator.

Parameters:
typeName - Defaults to "text" if not passed.
Returns:
available Operators

setHandleErrorCallback

public void setHandleErrorCallback(HandleErrorCallback callback)
If you define this method on a DataSource, it will be called whenever the server returns a DSResponse with a status other than STATUS_SUCCESS. 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.

Parameters:
callback - HandleErrorCallback the callback to set.

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)
Invoke an operation declared with operationType "custom".

This is a rarely used API. If the operation you are performing can be thought of as one of the standard "CRUD" operation types, declare it with a CRUD operationType. For example, if your operation updates a record, declare it with operationType "update" and invoke it via DataSource.updateData - this will cause cache sync to work correctly.

In particular:

Instead, the specific purpose of this API is to bypass all checks and side effects that normally occur for CRUD operations, for example, that a "fetch" requires valid Criteria or that an "update" or "remove" operation contains a valid primary key, or that an "add" operation returns the newly added record. performCustomOperation allows you to pass an arbitrary Record to the server, act on it with custom code, and return arbitray results or even no results.

The "data" parameter becomes dsRequest.data. With the Smart GWT Server Framework, the data is accessible server-side via DSRequest.getValues() and in Velocity templates (such as <customSQL>) as $values.

Note that with SQLDataSource, performCustomOperation must be used if you plan to have a <customSQL> tag in your operationBinding that will execute SQL operations other than SELECT, UPDATE, INSERT, DELETE (such as creating a new table). By declaring operationType "custom" in your .ds.xml file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.

Parameters:
operationId - the operation ID
See Also:
Operations overview and related methods

performCustomOperation

public void performCustomOperation(String operationId,
                                   Record data)
See Also:
DataSource#performCustomOperation()}

performCustomOperation

public void performCustomOperation(String operationId,
                                   Record data,
                                   DSCallback callback)
See Also:
DataSource#performCustomOperation()}

performCustomOperation

public void performCustomOperation(String operationId,
                                   Record data,
                                   DSCallback callback,
                                   DSRequest requestProperties)
Invoke an operation declared with operationType "custom".

This is a rarely used API. If the operation you are performing can be thought of as one of the standard "CRUD" operation types, declare it with a CRUD operationType. For example, if your operation updates a record, declare it with operationType "update" and invoke it via DataSource.updateData - this will cause cache sync to work correctly.

In particular:

Instead, the specific purpose of this API is to bypass all checks and side effects that normally occur for CRUD operations, for example, that a "fetch" requires valid Criteria or that an "update" or "remove" operation contains a valid primary key, or that an "add" operation returns the newly added record. performCustomOperation allows you to pass an arbitrary Record to the server, act on it with custom code, and return arbitray results or even no results.

The "data" parameter becomes dsRequest.data. With the Smart GWT Server Framework, the data is accessible server-side via DSRequest.getValues() and in Velocity templates (such as <customSQL>) as $values.

Note that with SQLDataSource, performCustomOperation must be used if you plan to have a <customSQL> tag in your operationBinding that will execute SQL operations other than SELECT, UPDATE, INSERT, DELETE (such as creating a new table). By declaring operationType "custom" in your .ds.xml file, all checks related to normal CRUD operations will be skipped and your <customSQL> can do arbitrary things.

Parameters:
operationId - the operation ID
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

processResponse

public void processResponse(String requestId,
                            DSResponse dsResponse)
Process a dsResponse for a request initiated by a DataSource with dataProtocol:"clientCustom". requestId parameter should be dsRequest.requestId as found on the dsRequest passed to DataSource.transformRequest.

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
dsResponse - Configuration for the dsResponse

recordsAreEqual

public boolean recordsAreEqual(Object record1,
                               Object record2)
Convenience method to test if two records are equal. Testing is done only for the fields defined in the DataSource, anything else is ignored.

Parameters:
record1 - record to be compared against.
record2 - record to be compared.
Returns:
true if the records are equal, false otherwise.

recordsAsText

public String recordsAsText(Record[] records)
Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).

In addition to the settings parameter for this method, DataSourceField.exportForceText can be set.

If two or more different text exports are needed for the same DataSource creating a conflict for any DataSourceField setting, inheritsFrom can be used to create a child DataSource where these settings can be changed without recapitulating all field definitions.

Parameters:
records - records to convert
Returns:
records as CSV/TSV (separator can be specified)

recordsAsText

public String recordsAsText(Record[] records,
                            TextExportSettings settings)
Converts a list of Records to simple text formats with a Record per line and values separated by a configurable separator, including both tab-separated-values and comma-separated-values (aka CSV).

In addition to the settings parameter for this method, DataSourceField.exportForceText can be set.

If two or more different text exports are needed for the same DataSource creating a conflict for any DataSourceField setting, inheritsFrom can be used to create a child DataSource where these settings can be changed without recapitulating all field definitions.

Parameters:
records - records to convert
settings - settings for the export
Returns:
records as CSV/TSV (separator can be specified)

recordsFromText

public Record[] recordsFromText(String text)
Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.

If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.

Parameters:
text - records as CSV/TSV (separator can be specified)
Returns:
records derived from TSV

recordsFromText

public Record[] recordsFromText(String text,
                                TextImportSettings settings)
Derive a list of Records from Microsoft Excel-compatible tab-separated-values format, using the current DataSource field order, or an explicitly specified list of fields.

If a specified field does not exist in the DataSource, it's assumed the values for that field should end up as Strings.

Parameters:
text - records as CSV/TSV (separator can be specified)
settings - optional settings for the import
Returns:
records derived from TSV

removeData

public void removeData(Record data)
Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.

Parameters:
data - primary key values of record to delete, (or complete record)
See Also:
Operations overview and related methods

removeData

public void removeData(Record data,
                       DSCallback callback)
See Also:
DataSource#removeData()}

removeData

public void removeData(Record data,
                       DSCallback callback,
                       DSRequest requestProperties)
Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.

Parameters:
data - 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
See Also:
Operations overview and related methods

setTypeOperators

public void setTypeOperators(FieldType typeName,
                             OperatorId[] operators)
Set the list of OperatorIds valid for a given FieldType.

Parameters:
typeName -
operators - available Operators

splitCriteria

public Criteria splitCriteria(Criteria criteria,
                              String[] fields)
Split a criteria apart based on fields. A new simple criteria is returned with any criteria applicable to the specified fields. The passed criteria is then modified to remove these fields resulting in two distinct criteria.

Incoming criteria can be a simple or advanced criteria. For an AdvancedCriteria only a single level of criteria with a top-level operator of "and" is supported.

To avoid modifying an original criteria, use DataSource.copyCriteria to make a copy to be passed in.

Parameters:
criteria - criteria to be split. May be modified if criteria is extracted.
fields - list of fields to extract from criteria
Returns:
extracted criteria

supportsAdvancedCriteria

public Boolean supportsAdvancedCriteria()
Do fetch and filter operations on this dataSource support being passed AdvancedCriteria?

For a DataSource to support being passed AdvancedCriteria, it must be clientOnly:true or cacheAllData:true, or have server side logic which can process AdvancedCriteria objects passed from the client.

AdvancedCriteria are supported on the server for standard SQL, Hibernate and JPA DataSources in Smart GWT Enterprise or Power editions (not supported in Smart GWT Pro).

The framework assumes that custom dataSources support AdvancedCriteria; if you have a a custom DataSOurce implementation that does not support AdvancedCriteria, you can set the allowAdvancedCriteria property to false.

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

supportsTextMatchStyle

public void supportsTextMatchStyle(TextMatchStyle textMatchStyle)
Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.

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

transformRequest

protected Object transformRequest(DSRequest dsRequest)
For a dataSource using client-side data integration, return the data that should be sent to the dataURL.

By default, HTTP requests sent to non-Smart GWT servers do not include DSRequest metadata such as 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 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.

As an example, if you have a dataURL that can return paged data given URL parameters "start" and "end", you could implement transformRequest like so:

    isc.DataSource.create({
       ... 
       transformRequest : function (dsRequest) {
          if (dsRequest.operationType == "fetch") {
              var params = {
                 start : dsRequest.startRow,
                 end : dsRequest.endRow
              };
              // combine paging parameters with criteria
              return isc.addProperties({}, dsRequest.data, params);
          }
       }
    });
  
Other reasons to implement transformRequest(): Special case: If the dataProtocol is "clientCustom" the Smart GWT system will not attempt to send data to the server in any way. Instead transformRequest should be implemented such that it accesses or updates the underlying data-set and calls DataSource.processResponse when the operation is complete. This setting allows straightforward integration with non Smart GWT comm mechanisms that directly send requests to the server (such as GWT-RPC), or handle data manipulation without sending HTTP at all (such as Google Gears).

Note: The RestDataSource class overrides transformRequest() to handle xml-serializing the request (including meta data) into a standard format.

Parameters:
dsRequest - the DSRequest being processed
Returns:
data to be sent to the dataURL

transformResponse

protected void transformResponse(DSResponse dsResponse,
                                 DSRequest dsRequest,
                                 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:

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:

NOTE: this method is NOT an appropriate time to call methods on visual components such as grids, initiate new DSRequests or RPCRequests, or in general do anything other than fill in fields on the DSResponse based on data that is already available. Any actions that need to be taken as a result of the web service response should be implemented exactly as for a DataSource where transformResponse() has not been overridden, that is, use the callback passed to high-level methods such as grid.fetchData(), and do error handling via either DataSource.handleError or by setting willHandleError.

Parameters:
dsResponse - default DSResponse derived from the response data
dsRequest - DSRequest object that initiated this request
data - XML document or JSON objects returned by the web service

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.

The provided DSResponse should have operationType "update", "add" or "remove" - there is no way for a "fetch" response to meaningfully update arbitrary caches. However, if you have a list of updated records (possibly retrieved via DataSource.fetchData) you can call updateCaches() multiple times with DSResponses of type "update" formed from the list of records retrieved via fetchData(). For example, if you had a ListGrid bound to the supplyItem sample DataSource, and that ListGrid was showing a Record with itemId 23, and you wanted to update the unitCost field to a new value, you would use the following code:

     // updatedRecord is the record we want to update
     Record record = supplyItemDS.copyRecord(updatedRecord);
     record.setAttribute("unitCost", 500);
     DSResponse dsResponse = new DSResponse();
     dsResponse.setData(record);
     dsResponse.setOperationType(DSOperationType.UPDATE);
     supplyItemDS.updateCaches(dsResponse);

To cause all components that have cache managers to drop their caches, provide a DSResponse with invalidateCache set.

As an alternative to calling updateCaches() directly, if updates to other DataSources occur as a result of server-side logic, you can use the server-side API DSResponse.addRelatedUpdate(DSResponse) (Pro Edition and above), which ultimately calls updateCaches() for you - see that method's documentation for details.

NOTE:: 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 the DSResponse provided to this method 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 - the provided DSResponse must minimally have dataSource, operationType, and data set

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.

The provided DSResponse should have operationType "update", "add" or "remove" - there is no way for a "fetch" response to meaningfully update arbitrary caches. However, if you have a list of updated records (possibly retrieved via DataSource.fetchData) you can call updateCaches() multiple times with DSResponses of type "update" formed from the list of records retrieved via fetchData(). For example, if you had a ListGrid bound to the supplyItem sample DataSource, and that ListGrid was showing a Record with itemId 23, and you wanted to update the unitCost field to a new value, you would use the following code:

     // updatedRecord is the record we want to update
     Record record = supplyItemDS.copyRecord(updatedRecord);
     record.setAttribute("unitCost", 500);
     DSResponse dsResponse = new DSResponse();
     dsResponse.setData(record);
     dsResponse.setOperationType(DSOperationType.UPDATE);
     supplyItemDS.updateCaches(dsResponse);

To cause all components that have cache managers to drop their caches, provide a DSResponse with invalidateCache set.

As an alternative to calling updateCaches() directly, if updates to other DataSources occur as a result of server-side logic, you can use the server-side API DSResponse.addRelatedUpdate(DSResponse) (Pro Edition and above), which ultimately calls updateCaches() for you - see that method's documentation for details.

NOTE:: 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 the DSResponse provided to this method 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 - the provided DSResponse must minimally have dataSource, operationType, and data set
dsRequest - optional dsRequest. If not specified, a DSRequest will be automatically created based on the DataSource and operationType of the DSResponse

updateData

public void updateData(Record updatedRecord)
Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.

Parameters:
updatedRecord - updated record
See Also:
Operations overview and related methods

updateData

public void updateData(Record updatedRecord,
                       DSCallback callback)
See Also:
DataSource#updateData()}

updateData

public void updateData(Record updatedRecord,
                       DSCallback callback,
                       DSRequest requestProperties)
Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.

Parameters:
updatedRecord - updated record
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

validateData

public void validateData(Record values)
Contacts the server to run server-side validation on a DSRequest and either returns errors validation errors or a status code of 0.

A "validate" dsRequest is effectively always willHandleError:true. It is a normal condition for a "validate" DSResponse to have validation errors and the response will never go to system-wide handling for unexpected errors (RPCManager.handleError).

Parameters:
values - record values to validate
See Also:
Operations overview and related methods

validateData

public void validateData(Record values,
                         DSCallback callback)
See Also:
DataSource#validateData()}

validateData

public void validateData(Record values,
                         DSCallback callback,
                         DSRequest requestProperties)
Contacts the server to run server-side validation on a DSRequest and either returns errors validation errors or a status code of 0.

A "validate" dsRequest is effectively always willHandleError:true. It is a normal condition for a "validate" DSResponse to have validation errors and the response will never go to system-wide handling for unexpected errors (RPCManager.handleError).

Parameters:
values - record values to validate
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

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.

Note that if this method is called for a record with no associated file, the target window's new URL may not be functional. By default when dataSources encounter a binary type fields, an additional field, <fieldName>_filename, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to view a file.

See the overview of Binary Fields for details.

Parameters:
data - Record to download. Only required to have a value for the primary key field.

viewFile

public void viewFile(Record data,
                     String fieldName)
See Also:
DataSource#viewFile()}

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.

Note that if this method is called for a record with no associated file, the target window's new URL may not be functional. By default when dataSources encounter a binary type fields, an additional field, <fieldName>_filename, is generated to store the filename for the binary field value. If this field is present in the data source but has no value for this record, developers can assume they're working with a record with no stored file. If this field is not present in some custom dataSource configuration, or the record is not loaded on the client, an additional server transaction may be required to determine whether the record has an associated file before calling this method to view a file.

See the overview of Binary Fields for details.

Parameters:
data - Record to download. Only required to have a value for the primary key field.
fieldName - optional name of the binary field containing the file. If not provided, the first binary field is used
requestProperties - additional properties to set on the DSRequest that will be issued

canFlattenCriteria

public static boolean canFlattenCriteria(AdvancedCriteria criteria)
Returns true if calling DataSource.flattenCriteria on the passed criteria would produce logically equivalent criteria.

Parameters:
criteria - the AdvancedCriteria to check for flatness
Returns:
true if criteria can be flattened without logical change

combineCriteria

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:

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)
See Also:
DataSource#combineCriteria()}

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:

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

convertCriteria

public static AdvancedCriteria convertCriteria(Criteria criteria)
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.

Parameters:
criteria - simple criteria
Returns:
equivalent AdvancedCriteria object

convertCriteria

public static AdvancedCriteria convertCriteria(Criteria criteria,
                                               TextMatchStyle textMatchStyle)
Converts criteria expressed in Smart GWT's simple criteria format to an AdvancedCriteria object.

Parameters:
criteria - simple criteria
textMatchStyle - default style of matching text. Defaults to "substring"
Returns:
equivalent AdvancedCriteria object

copyCriteria

public static Criteria copyCriteria(Criteria criteria)
Create a copy of a criteria.

Parameters:
criteria - criteria to copy
Returns:
copy of criteria

flattenCriteria

public static AdvancedCriteria flattenCriteria(AdvancedCriteria criteria)
Returns new criteria that has at most one top-level LogicalOperator ("and" or "or"). This new criteria will be considered "flat" by DataSource.isFlatCriteria.

Not all AdvancedCriteria can be flattened and remain logically equivalent. When criteria will be logically modified by flattening, all criteria that appear anywhere in the AdvancedCriteria structure will appear under a single top-level operator, which will be the same top-level operator as the passed AdvancedCriteria.

For example, given criteria like this (in the JSON representation of AdvancedCriteria):

       { operator: "and", criteria: [
          { fieldName: "continent", operator: "equals", value: "Europe"},
          { operator: "or", criteria: [
             { fieldName: "countryName", operator: "iEndsWith", value: "land"},
             { fieldName: "population", operator: "lessThan", value: 3000000}
          ]}
         ]
       }
  
The returned criteria would be:
       { operator: "and", criteria: [
          { fieldName: "continent", operator: "equals", value: "Europe"},
          { fieldName: "countryName", operator: "iEndsWith", value: "land"},
          { fieldName: "population", operator: "lessThan", value: 3000000}
        ]}
  
This returned criteria is not logically equivalent to the passed criteria - the "iEndsWith" and "lessThan" criteria that were formerly nested under a logical "or" operator must now both be satisfied instead of either being satisfied. You can use DataSource.canFlattenCriteria to detect whether an AdvancedCriteria is going to be changed by flattenCriteria().

Because the returned criteria may not be logically equivalent, flattenCriteria should not be used as a means of simplifying criteria to make server implementation easier or anything of the kind. The primary purpose of returning logically different criteria is to enable an end user to switch from an interface for editing nested criteria to an interface that can't handle nested criteria and convert the criteria while preserving as much as possible.

Parameters:
criteria - the AdvancedCriteria to flatten
Returns:
flattened criteria

getAdvancedCriteriaDescription

public static String getAdvancedCriteriaDescription(AdvancedCriteria criteria,
                                                    DataSource dataSource)
Returns a human-readable string describing the clauses in this advanced criteria or criterion.

Parameters:
criteria - Criteria to convert to a readable string
dataSource - DataSource to provide definitions of operators
Returns:
Human-readable string describing the clauses in the passed criteria

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.

getSortBy

public static String[] getSortBy(SortSpecifier[] sortSpecifiers)
Given an array of SortSpecifiers, 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 SortSpecifiers, 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 SortSpecifiers equivalent to the passed in string array

isFlatCriteria

public static boolean isFlatCriteria(AdvancedCriteria criteria)
Returns true if a given AdvancedCriteria is "flat." That is, the criteria consists of either:

Parameters:
criteria - the AdvancedCriteria to check for flatness
Returns:
true if criteria is flat

load

public static void load(String dsID,
                        Function callback)
Load a DataSource or an array of DataSources using the DataSourceLoader servlet. When a callback is specified, this is fired after the DataSources are loaded. The callback is passed a single parameter, the dsID list passed into the method. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired immediately.

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

Parameters:
dsID - DataSource ID or Array of DataSource IDs
callback - Callback to fire after DataSource loading completes

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. The callback is passed a single parameter, the dsID list passed into the method. If no loading occurs because the requested DataSource(s) are already loaded, a warning is logged and the callback is fired immediately.

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

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

loadWithParents

public static void loadWithParents(String dsID,
                                   Function callback)
Variation of DataSource.load that will also automatically load any DataSources that the requested DataSources inherit from (via inheritsFrom).

If the parent DataSource is already loaded, calling loadWithParents will not automatically reload them unless the forceReload parameter is passed.

Parameters:
dsID - DataSource ID or Array of DataSource IDs
callback - Callback to fire after DataSource loading completes

loadWithParents

public static void loadWithParents(String dsID,
                                   Function callback,
                                   boolean forceReload)
Variation of DataSource.load that will also automatically load any DataSources that the requested DataSources inherit from (via inheritsFrom).

If the parent DataSource is already loaded, calling loadWithParents will not automatically reload them unless the forceReload parameter is passed.

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

setTypeOperators

public static void setTypeOperators(String typeName,
                                    OperatorId[] operators)
Set the list of valid OperatorIds for a given FieldType.

Parameters:
typeName -
operators - available Operators

onInit

protected void onInit()
Overrides:
onInit in class BaseClass

registerID

protected void registerID(String id,
                          boolean skipUniqueJSIdentifierCheck)
Overrides:
registerID in class BaseClass

setID

public void setID(String id)
Overrides:
setID in class BaseClass

setAddGlobalId

public void setAddGlobalId(Boolean addGlobalId)
                    throws IllegalStateException
Whether to make this DataSource available as a global variable for convenience.

Note : This is an advanced setting

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

getAddGlobalId

public Boolean getAddGlobalId()
Whether to make this DataSource available as a global variable for convenience.

Returns:
Boolean

setDataProtocol

public void setDataProtocol(DSProtocol dataProtocol)
                     throws IllegalStateException
Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. May be overridden for individual request types using dataProtocol}

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

setDefaultParams

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

Parameters:
defaultParams - the default params

getDefaultParams

public Map getDefaultParams()
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

get

public static DataSource get(String ID)
Synonym of DataSource.getDataSource: Lookup a DataSource by ID.

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

get

public static DataSource get(String ID,
                             RequestTransformer requestTransformer,
                             ResponseTransformer responseTransformer)
Synonym of DataSource.getDataSource: Lookup a DataSource by ID.

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

getDataSource

public static DataSource getDataSource(String ID,
                                       RequestTransformer requestTransformer,
                                       ResponseTransformer responseTransformer)
Lookup a DataSource by ID with an optional RequestTransformer and ResponseTransformer. The RequestTransformer and ResponseTransformer parameters provide the equivalent functionality of overriding transformRequest(DSRequest) and transformResponse(DSResponse, DSRequest, Object) when instantiating a DataSource on the client. However when obtaining a DataSource instance from the server using this API, transformRequest(DSRequest) and transformResponse(DSResponse, DSRequest, Object) cannot be overridden and so the requestTransformer and responseTransformer parameters can be passed instead.

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

useOfflineResponse

protected boolean useOfflineResponse(DSRequest dsRequest,
                                     DSResponse dsResponse)
Override point to allow application code to suppress use of a particular offline response. For example, application code may wish to examine the response's offlineTimestamp to make a decision about whether the response is too stale to be useful.

This is an application override point only; there is no default implementation.

Note: This is an override point

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

isCreated

public boolean isCreated()
Overrides:
isCreated in class BaseClass

getJsObj

public JavaScriptObject getJsObj()
Overrides:
getJsObj in class BaseClass

setInheritsFrom

public void setInheritsFrom(DataSource inheritsFrom)
                     throws IllegalStateException
ID of another DataSource this DataSource inherits its DataSource fields from.

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

The default order of the combined fields is new local fields first (including any fields present in the parent DataSource which the local DataSource re-declares), then parent fields. You can set useParentFieldOrder to instead use the parent's field order, with new local fields appearing last.

You can set showLocalFieldsOnly to have all non-local fields hidden.

Note that only fields are inherited - other properties such as dataURL and dataFormat are not. You can use ordinary inheritance, that is, creating a subclass of DataSource, in order to share properties such as dataURL across a series of DataSources that also inherit fields from each other via inheritsFrom

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

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

setFields

public void setFields(DataSourceField... fields)
               throws IllegalStateException
The list of fields that compose records from this DataSource.

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

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

addField

public void addField(DataSourceField field)
              throws IllegalStateException
Add a field to the DataSource

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

getFields

public DataSourceField[] getFields()
The list of fields that compose records from this DataSource.

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

Returns:
array of DataSourceFields

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

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

xmlSerialize

public String xmlSerialize(Record 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

xmlSerialize

public String xmlSerialize(Record[] 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

xmlSerialize

public String xmlSerialize(Map 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

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

copyRecord

public Record copyRecord(Record record)
Copies all DataSource field values of a Record (including a TreeNode) to a new Record, omitting component-specific metadata such as selected state from grids, or parent folders for TreeNodes.

Parameters:
record - The record to be copied.
Returns:
A new copy of the record provided as an argument, with component-specific metata data removed.

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

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

loadWithParents

public static void loadWithParents(String[] dsID,
                                   Function callback,
                                   boolean forceReload)
Variation of DataSource.load that will also automatically load any DataSources that the requested DataSources inherit from (via {@link com.smartgwt.client.data.DataSource#inheritsFrom DataSource.inheritsFrom))

If the parent DataSource is already loaded, calling loadWithParents will not automatically reload them unless the forceReload parameter is passed.

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

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.

If you do not specify an operationId in the requestProperties you pass to this method, it behaves exactly the same as the exportClientDataStatic static classMethod. If you do specify an operationId, the framework expects your DataSource to configure an OperationBinding of operationType DSOperationType.CLIENTEXPORT, with the same operationId. The framework will then send the exportClientData request via the ordinary DSRequest mechanism, which allows you to use normal framework features in the client data export. For example, you could add a DMI declaration to your operationBinding, which would allow you to write server-side code that intervenes in the export process - for instance, by calling the getExportObject() API to do something special with the export document, like saving it to a database table or sending it to an email list.

When you use the specific operationId version of this API, both the SmartClient Server and server-side DataSources are required.

To export unformatted data, see exportData() which does not include client-side formatters, but requires both the Smart GWT server and the presence of server-side DataSources.

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

exportClientDataStatic

public static void exportClientDataStatic(Object[] data,
                                          DSRequest requestProperties)
Exports arbitrary client-side data, with client-side formatters applied, so is suitable for direct display to users. This method can be used to export data formatted outside of any kind of visual component.

Requires the SmartClient server, but does not rely on any server-side DataSources. If you need to intervene in the export process server-side - for example, if you need to do something not directly supported with the exported object, such as attach it to an email - use the exportClientData instance method with an appropriate OperationBinding, as described in the method documentation.

To export unformatted data, see exportData(), which does not include client-side formatters, but requires both the SmartClient server and the presence of server-side DataSources.

Note that field displayFormat is honored for "date" and "datetime" fields when exporting direct to Excel; see the displayFormat docs for details.

NOTE: The "Static" in this method name merely indicates that it is the static version of this method, as opposed to the similar instance method exportClientData. Restrictions of the Java language itself prevent us from giving the instance method and the static method the same name.


setXmlNamespaces

public void setXmlNamespaces(XmlNamespaces xmlNamespaces)
                      throws IllegalStateException
Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions. xmlNamespaces should be specified as a map ping from namespace prefix to namespace URI, for example:

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

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

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

getFieldOperators

public OperatorId[] getFieldOperators(String fieldName)
Parameters:
fieldName - the field name to obtain operators for
Returns:
the available Operators
See Also:
#getFieldOperators(FieldType)

getFieldOperators

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

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

applyFilter

public Record[] applyFilter(Record[] records,
                            Criteria criteria,
                            DSRequest requestProperties)
Returns records in the passed Record that match the provided filter Criteria.

By default:

Parameters:
records - (Record[]) the list of rows
criteria - (Criteria) the filter criteria
requestProperties - (DSRequest Properties) optional dataSource request properties
Returns:
Record[] the list of matching rows

applyFilter

public Record[] applyFilter(Record[] records,
                            Criteria criteria)
Returns records in the passed Record that match the provided filter Criteria.

By default:

Parameters:
records - (Record[]) the list of rows
criteria - (Criteria) the filter criteria
Returns:
Record[] the list of matching rows

setCacheData

public void setCacheData(Record... cacheData)
For a cacheAllData or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.

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

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

getCacheData

public Record[] getCacheData()
For a cacheAllData or client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects representing records.

Returns:
Returns the complete set of data cached by this dataSource. Note that this may have been supplied via cacheData, or may have been fetched from the server for dataSources with cacheAllData set to true.

setTestData

public void setTestData(Record... cacheData)
For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects. Deprecated in favor of cacheData.

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

If this method is called after the component has been drawn/initialized: Call this method to set the data in the client-side test-data after initialization. setCacheData() should be called instead and setTestData() is deprecated and will eventually be removed.

Parameters:
testData - Array of records to apply as the client-side test-data. Default value is null

getTestData

public Record[] getTestData()
For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects. Deprecated in favor of cacheData.

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

Returns:
Record

getFieldAutoTitle

public String getFieldAutoTitle(String identifier)
Return a reasonable user-visible title given a fieldName. Called when autoDeriveTitles is true and by default, calls the class method DataSource.getAutoTitle. Override to provide a different policy for auto-deriving titles for a particular DataSource or subclass of DataSource.

Parameters:
identifier - identifier for which a title is desired.
Returns:
auto-derived title

getAutoTitle

public static String getAutoTitle(String identifier)
Utility method to derive a reasonable user-visible title from an identifier.

The following approach is taken:

Parameters:
identifier - identifier for which a title is desired.
Returns:
auto-derived title

getFieldValue

public static Object getFieldValue(DataSourceField field,
                                   Record record)
Given a field definition and a record object, this method will return the field value for the record.

This method will follow any dataPath specified on the component field if necessary, and will extract atomic values from custom SimpleType fields where this is required.

Parameters:
field - Field definition from a dataSource or dataBoundComponent.
record - data object
Returns:
extracted field value

getFieldValue

public static Object getFieldValue(ListGridField field,
                                   Record record)
Given a field definition and a record object, this method will return the field value for the record.

This method will follow any dataPath specified on the component field if necessary, and will extract atomic values from custom SimpleType fields where this is required.

Parameters:
field - Field definition from a dataSource or dataBoundComponent.
record - data object
Returns:
extracted field value

getFieldValue

public static Object getFieldValue(DetailViewerField field,
                                   Record record)
Given a field definition and a record object, this method will return the field value for the record.

This method will follow any dataPath specified on the component field if necessary, and will extract atomic values from custom SimpleType fields where this is required.

Parameters:
field - Field definition from a dataSource or dataBoundComponent.
record - data object
Returns:
extracted field value

getFieldValue

public static Object getFieldValue(FormItem field,
                                   Record record)
Given a field definition and a record object, this method will return the field value for the record.

This method will follow any dataPath specified on the component field if necessary, and will extract atomic values from custom SimpleType fields where this is required.

Parameters:
field - Field definition from a dataSource or dataBoundComponent.
record - data object
Returns:
extracted field value