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-independant 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 type, validators, foreignKey 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 SmartGWT Relational Database Enterprise Java Beans (EJB) Entity/Relationship Modelling 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 DataBoundComponent can automatically configure themselves for viewing, editing and saving data described by DataSources. DataBinding is covered in the ${isc.DocUtils.linkForDocNode('QuickStartGuide', 'QuickStart Guide')}, Chapter 6, Data Binding.

'Data Integration' is the process by which a DataSource can be connected to server systems such as SQL DataBases, Java Object models, WSDL web services and other data providers. Data Integration comes in two variants: client-side and server-side. 'Server-side integration' uses the SmartGWT Java-based server to connect to data represented by Java Objects or JDBC-accessible databases. 'Client-side integration' connects SmartGWT 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 ListGrid, TreeGrid, DetailViewer, DynamicForm-based DynamicForm.editRecord(com.smartgwt.client.data.Record) and DynamicForm.saveData(), grid-based canEdit and saveByCell, and custom interactions provided by ${isc.DocUtils.linkForExampleId('patternReuse')} custom databinding-capable components.


Field Summary
 
Fields inherited from class com.smartgwt.client.core.BaseClass
config, id
 
Constructor Summary
DataSource()
           
DataSource(com.google.gwt.core.client.JavaScriptObject jsObj)
           
DataSource(java.lang.String dataURL)
           
 
Method Summary
 void addData(Record record)
          Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
 void addData(Record record, DSCallback callback)
          Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
 void addData(Record record, DSCallback callback, DSRequest requestProperties)
          Perform an "add" DataSource operation against this DataSource, to create a new DataSource record.
 void addField(DataSourceField field)
           
 HandlerRegistration addHandleErrorHandler(HandleErrorHandler handler)
          Add a handleError handler.
 com.google.gwt.core.client.JavaScriptObject create()
           
 void fetchData()
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void fetchData(Criteria criteria)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void fetchData(Criteria criteria, DSCallback callback)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void filterData(Criteria criteria)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void filterData(Criteria criteria, DSCallback callback)
          Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records.
 void filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
           
static DataSource get(java.lang.String ID)
          Synonym of getDataSource(java.lang.String): Lookup a DataSource by ID.
 java.lang.Boolean getAddGlobalId()
          Whether to make this DataSource available as a global variable for convenience.
 java.lang.Boolean getAutoDeriveSchema()
          For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from from the SQL table specified in tableName.
 java.lang.Boolean getAutoDeriveTitles()
          If set, titles are automatically derived from name for any field that does not have a title and is not marked hidden:true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle.
 java.lang.String getCallbackParam()
          Applies only to dataFormat: "json".
 java.lang.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 hierachical 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.
 java.lang.Boolean getClientOnly()
          Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might.
protected  DSResponse getClientOnlyResponse(DSRequest request)
          Return a "spoofed" response for a clientOnly DataSource.
 CriteriaPolicy getCriteriaPolicy()
          Decides under what conditions the com.smartgwt.client.data.ResultSet cache should be dropped when the criteria changes
 DSDataFormat getDataFormat()
          Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg fetchData() is called).
 DSProtocol getDataProtocol()
          Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests.
static DataSource getDataSource(java.lang.String ID)
          Lookup a DataSource by ID.
 RPCTransport getDataTransport()
          Transport to use for all operations on this DataSource.
 java.lang.String getDataURL()
          Default URL to contact to fulfill all DSRequests.
 java.lang.String getDbName()
          For DataSources using the 'SmartGWT SQL engine' for persistence, which database configuration to use.
 java.lang.Boolean getDropExtraFields()
          Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.
 DataSourceField getField(java.lang.String fieldName)
          Return the field definition object.
 java.lang.String getIconField()
          Designates a field of FieldType:"image" as the field to use when rendering a record as an image, for example, in a TileGrid.
 com.google.gwt.core.client.JavaScriptObject getJsObj()
           
 java.lang.String getJsonPrefix()
          Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventitive measure against javascript hijacking.
Only applies to responses formatted as json objects.
 java.lang.String getJsonSuffix()
          Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventitive measure against javascript hijacking.
Only applies to responses formatted as json objects.
 void getLegalChildTags()
          For a DataSource that describes a DOM structure, the list legal child elements that can be contained by the element described by this DataSource.
static DataSource getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 java.lang.String getPluralTitle()
          User-visible plural name for this DataSource.
 java.lang.Boolean getPreventHTTPCaching()
          If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.
 DataSourceField getPrimaryKeyField()
          Returns a pointer to the primaryKey field for this DataSource
 java.lang.String getPrimaryKeyFieldName()
          Returns the primary key fieldName for this DataSource
 java.lang.Boolean getQualifyColumnNames()
          For dataSources of serverType "sql", determines whether we qualify column names with table names in any SQL we generate.
 java.lang.String getRecordXPath()
          See recordXPath.
 int getResultBatchSize()
          Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, SmartGWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.
 java.lang.String getSchemaNamespace()
          For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to.
 java.lang.Boolean getSendExtraFields()
          Analagous to dropExtraFields, for data sent to the server.
 java.lang.String getServerConstructor()
          Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource.
 DSServerType getServerType()
          For a DataSource stored in .xml format on the ISC server, indicates what server-side connector to use to execute requests, that is, what happens if you call dsRequest.execute() in server code.
 java.lang.String getServiceNamespace()
          For an XML DataSource, URN of the WebService to use to invoke operations.
 java.lang.Boolean getShowLocalFieldsOnly()
          For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that only the fields listed in this DataSource should be shown.
 java.lang.Boolean getShowPrompt()
          Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset.
 java.lang.Boolean getStrictSQLFiltering()
          [A] If set to true, both client and server-side advanced filtering used by SmartGWT 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 expression are false:
 java.lang.String getTableName()
          For DataSources using the 'SmartGWT SQL engine' for persistence, what database table name to use.
 java.lang.String getTagName()
          Tag name to use when serializing to XML.
 DataClass[] getTestData()
          For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
 java.lang.String getTitle()
          User-visible name for this DataSource.
 java.lang.String getTitleField()
          Best field to use for a user-visible title for an individual record from this dataSource.
 java.lang.Boolean getUseFlatFields()
          Like useFlatFields, but applies to all DataBound components that bind to this DataSource.
 java.lang.Boolean getUseLocalValidators()
          Whether to attempt validation on the client at all for this DataSource.
 java.lang.Boolean getUseParentFieldOrder()
          For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.
 boolean isCreated()
           
protected  void onInit()
           
 void processResponse(java.lang.String requestId, DSResponse responseProperties)
          Process a dsResponse for a request initiated by a DataSource with dataProtocol.
 Record[] recordsFromXML(java.lang.Object elements)
          Transform a list of XML elements to DataSource records.
 void removeData(Record record)
          Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
 void removeData(Record record, DSCallback callback)
          Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
 void removeData(Record record, DSCallback callback, DSRequest requestProperties)
          Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record.
 void setAddGlobalId(java.lang.Boolean addGlobalId)
          Whether to make this DataSource available as a global variable for convenience.
 void setAutoDeriveSchema(java.lang.Boolean autoDeriveSchema)
          For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from from the SQL table specified in tableName.
 void setAutoDeriveTitles(java.lang.Boolean autoDeriveTitles)
          If set, titles are automatically derived from name for any field that does not have a title and is not marked hidden:true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle.
 void setCallbackParam(java.lang.String callbackParam)
          Applies only to dataFormat: "json".
 void setChildrenField(java.lang.String childrenField)
          fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierachical data structure, rather than a flat list of nodes linked by foreignKey.
Note this is an alternative to setting childrenProperty directly on the childrenField object.
 void setClientOnly(java.lang.Boolean clientOnly)
          Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might.
 void setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
          Decides under what conditions the com.smartgwt.client.data.ResultSet cache should be dropped when the criteria changes
 void setDataFormat(DSDataFormat dataFormat)
          Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg 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(java.lang.String dataURL)
          Default URL to contact to fulfill all DSRequests.
 void setDbName(java.lang.String dbName)
          For DataSources using the 'SmartGWT SQL engine' for persistence, which database configuration to use.
 void setDefaultParams(java.util.Map defaultParams)
          HTTP parameters that should be submitted with every DSRequest.
 void setDropExtraFields(java.lang.Boolean dropExtraFields)
          Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.
 void setEnumConstantProperty(java.lang.String enumConstantProperty)
          The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if the EnumTranslateStrategy is set to "bean".
 void setEnumOrdinalProperty(java.lang.String enumOrdinalProperty)
          The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if the EnumTranslateStrategy is set to "bean".
 void setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy)
          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 SmartGWT server
 void setFields(DataSourceField... fields)
          The list of fields that compose records from this DataSource.
 void setIconField(java.lang.String iconField)
          Designates a field of FieldType:"image" as the field to use when rendering a record as an image, for example, in a TileGrid.
 void setInheritsFrom(DataSource inheritsFrom)
          ID of another DataSource this DataSource inherits its DataSource fields from.

Local fields (fields defined in this DataSource) are added to inherited fields to form the full set of fields.
 void setJsonPrefix(java.lang.String jsonPrefix)
          Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventitive measure against javascript hijacking.
Only applies to responses formatted as json objects.
 void setJsonSuffix(java.lang.String jsonSuffix)
          Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventitive measure against javascript hijacking.
Only applies to responses formatted as json objects.
 void setOperationBindings(OperationBinding... operationBindings)
          
Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
 void setPluralTitle(java.lang.String pluralTitle)
          User-visible plural name for this DataSource.
 void setPreventHTTPCaching(java.lang.Boolean preventHTTPCaching)
          If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.
 void setQualifyColumnNames(java.lang.Boolean qualifyColumnNames)
          For dataSources of serverType "sql", determines whether we qualify column names with table names in any SQL we generate.
 void setRecordName(java.lang.String recordName)
          See recordName.
 void setRecordXPath(java.lang.String recordXPath)
          See recordXPath.
 void setRequestProperties(DSRequest requestProperties)
          Additional properties to pass through to the DSRequests made by this DataSource.
 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, SmartGWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.
 void setSendExtraFields(java.lang.Boolean sendExtraFields)
          Analagous to dropExtraFields, for data sent to the server.
 void setServerConstructor(java.lang.String serverConstructor)
          Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource.
 void setServerType(DSServerType serverType)
          For a DataSource stored in .xml format on the ISC server, indicates what server-side connector to use to execute requests, that is, what happens if you call dsRequest.execute() in server code.
 void setServiceNamespace(java.lang.String serviceNamespace)
          For an XML DataSource, URN of the WebService to use to invoke operations.
 void setShowLocalFieldsOnly(java.lang.Boolean showLocalFieldsOnly)
          For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that only the fields listed in this DataSource should be shown.
 void setShowPrompt(java.lang.Boolean showPrompt)
          Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset.
 void setStrictSQLFiltering(java.lang.Boolean strictSQLFiltering)
          [A] If set to true, both client and server-side advanced filtering used by SmartGWT 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 expression are false:
 void setTableName(java.lang.String tableName)
          For DataSources using the 'SmartGWT SQL engine' for persistence, what database table name to use.
 void setTagName(java.lang.String tagName)
          Tag name to use when serializing to XML.
 void setTestData(DataClass[] testData)
          For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.
 void setTitle(java.lang.String title)
          User-visible name for this DataSource.
 void setTitleField(java.lang.String titleField)
          Best field to use for a user-visible title for an individual record from this dataSource.
 void setUseFlatFields(java.lang.Boolean useFlatFields)
          Like useFlatFields, but applies to all DataBound components that bind to this DataSource.
 void setUseLocalValidators(java.lang.Boolean useLocalValidators)
          Whether to attempt validation on the client at all for this DataSource.
 void setUseParentFieldOrder(java.lang.Boolean useParentFieldOrder)
          For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.
 void setXmlNamespaces(XmlNamespaces xmlNamespaces)
          Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions.
 void supportsTextMatchStyle(java.lang.String textMatchStyle)
          Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field.
protected  java.lang.Object transformRequest(DSRequest dsRequest)
          For a dataSource using client-side data integration, return the data that should be sent to the DataSource.dataURL.
protected  void transformResponse(DSResponse response, DSRequest request, java.lang.Object data)
          Modify the DSResponse object derived from the response returned from the dataURL.
 void updateData(Record record)
          Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
 void updateData(Record record, DSCallback callback)
          Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
 void updateData(Record record, DSCallback callback, DSRequest requestProperties)
          Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record.
 java.lang.String xmlSerialize(com.google.gwt.core.client.JavaScriptObject data)
          Serialize a JavaScript object as XML.
 java.lang.String xmlSerialize(com.google.gwt.core.client.JavaScriptObject data, SerializationContext flags)
          Serialize a JavaScript object as XML.
 
Methods inherited from class com.smartgwt.client.core.BaseClass
destroy, doAddHandler, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setID, setProperty, setProperty, setProperty, setProperty
 
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(com.google.gwt.core.client.JavaScriptObject jsObj)

DataSource

public DataSource(java.lang.String dataURL)
Method Detail

getOrCreateRef

public static DataSource getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

create

public com.google.gwt.core.client.JavaScriptObject create()
Specified by:
create in class BaseClass

setAddGlobalId

public void setAddGlobalId(java.lang.Boolean addGlobalId)
                    throws java.lang.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:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getAddGlobalId

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

Returns:
Boolean

setDataFormat

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

Parameters:
dataFormat - dataFormat Default value is "iscServer"
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getDataFormat

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

Returns:
DSDataFormat

setCallbackParam

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

Parameters:
callbackParam - callbackParam Default value is "callback"
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getCallbackParam

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

Returns:
String

setDataTransport

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

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

Parameters:
dataTransport - dataTransport Default value is RPCManager.defaultTransport
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getDataTransport

public RPCTransport getDataTransport()
Transport to use for all operations on this DataSource. Defaults to com.smartgwt.client.rpc.RPCManager#defaultTransport. This would typically only be set to enable "scriptInclude" transport for contacting dataFormat 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

setPreventHTTPCaching

public void setPreventHTTPCaching(java.lang.Boolean preventHTTPCaching)
                           throws java.lang.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 com.smartgwt.client.data.ResultSet.

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

getPreventHTTPCaching

public java.lang.Boolean getPreventHTTPCaching()
If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.

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

Returns:
Boolean

setServerType

public void setServerType(DSServerType serverType)
                   throws java.lang.IllegalStateException
For a DataSource stored in .xml format on the ISC server, indicates what server-side connector to use to execute requests, that is, what happens if you call dsRequest.execute() in server code.

Parameters:
serverType - serverType Default value is "generic"
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getServerType

public DSServerType getServerType()
For a DataSource stored in .xml format on the ISC server, indicates what server-side connector to use to execute requests, that is, what happens if you call dsRequest.execute() in server code.

Returns:
DSServerType

setTableName

public void setTableName(java.lang.String tableName)
                  throws java.lang.IllegalStateException
For DataSources using the 'SmartGWT SQL engine' for persistence, what database table name to use. The default is to use the DataSource ID as the table name.

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

getTableName

public java.lang.String getTableName()
For DataSources using the 'SmartGWT SQL engine' for persistence, what database table name to use. The default is to use the DataSource ID as the table name.

Returns:
String

setDbName

public void setDbName(java.lang.String dbName)
               throws java.lang.IllegalStateException
For DataSources using the 'SmartGWT SQL engine' for persistence, which database configuration to use. Database configurations can be created using the "Databases" tab in the Developer Console. If unset, the default database configuration is used (which also settable using the "Databases" tab).

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

getDbName

public java.lang.String getDbName()
For DataSources using the 'SmartGWT SQL engine' for persistence, which database configuration to use. Database configurations can be created using the "Databases" tab in the Developer Console. If unset, the default database configuration is used (which also settable using the "Databases" tab).

Returns:
String

setJsonPrefix

public void setJsonPrefix(java.lang.String jsonPrefix)
                   throws java.lang.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 preventitive 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 instead and explicitly parse the prefix out as part of transformResponse(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest, java.lang.Object).

Note : This is an advanced setting

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

getJsonPrefix

public java.lang.String getJsonPrefix()
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventitive 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 instead and explicitly parse the prefix out as part of transformResponse(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest, java.lang.Object).

Returns:
String

setJsonSuffix

public void setJsonSuffix(java.lang.String jsonSuffix)
                   throws java.lang.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 preventitive measure against javascript hijacking.
Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.

Note : This is an advanced setting

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

getJsonSuffix

public java.lang.String getJsonSuffix()
Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventitive measure against javascript hijacking.
Only applies to responses formatted as json objects. Does not apply to responses returned via scriptInclude type transport.

Returns:
String

setUseFlatFields

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

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

getUseFlatFields

public java.lang.Boolean getUseFlatFields()
Like useFlatFields, but applies to all DataBound components that bind to this DataSource.

Returns:
Boolean

setShowLocalFieldsOnly

public void setShowLocalFieldsOnly(java.lang.Boolean showLocalFieldsOnly)
                            throws java.lang.IllegalStateException
For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that only the fields listed in this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".

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

getShowLocalFieldsOnly

public java.lang.Boolean getShowLocalFieldsOnly()
For a DataSource that inherits fields from another DataSource (via inheritsFrom), indicates that only the fields listed in this DataSource should be shown. All other inherited parent fields will be marked "hidden:true".

Returns:
Boolean

setUseParentFieldOrder

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

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

getUseParentFieldOrder

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

Returns:
Boolean

setDropExtraFields

public void setDropExtraFields(java.lang.Boolean dropExtraFields)
                        throws java.lang.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 dataFormat 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 com.smartgwt.client..DMI). Setting this property to false disables this filtering for this DataSource only. This setting overrides the configuration in server.properties. This setting can be overridden by dropExtraFields.

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

getDropExtraFields

public java.lang.Boolean getDropExtraFields()
Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.

For dataFormat 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 com.smartgwt.client..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

setSendExtraFields

public void setSendExtraFields(java.lang.Boolean sendExtraFields)
                        throws java.lang.IllegalStateException
Analagous 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 transformRequest(com.smartgwt.client.data.DSRequest) and ultimately sent to the server.

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

getSendExtraFields

public java.lang.Boolean getSendExtraFields()
Analagous 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 transformRequest(com.smartgwt.client.data.DSRequest) and ultimately sent to the server.

Returns:
Boolean

setAutoDeriveSchema

public void setAutoDeriveSchema(java.lang.Boolean autoDeriveSchema)
                         throws java.lang.IllegalStateException
For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from from the SQL table specified in tableName. This causes SmartGWT to create a "super" DataSource, which this dataSource then automatically inheritsFrom. This allows you to override auto-derived schema as required.

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

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

getAutoDeriveSchema

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

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

Returns:
Boolean

setServiceNamespace

public void setServiceNamespace(java.lang.String serviceNamespace)
                         throws java.lang.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(java.lang.String, com.smartgwt.client.data.WSDLLoadCallback), setting serviceNamespace combined with specifying OperationBinding that set wsOperation will cause a DataSource to invoke web service operations to fulfill DataSource requests (DSRequest).

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

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

getServiceNamespace

public java.lang.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(java.lang.String, com.smartgwt.client.data.WSDLLoadCallback), setting serviceNamespace combined with specifying OperationBinding that set wsOperation will cause a DataSource to invoke web service operations to fulfill DataSource requests (DSRequest).

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

Returns:
String

getSchemaNamespace

public java.lang.String getSchemaNamespace()
                                    throws java.lang.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 com.smartgwt.client..SchemaSet#getSchema and WebService.getSchema(java.lang.String). Note : This method should be called only after the underlying component has been created.

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

setRecordXPath

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

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

getRecordXPath

public java.lang.String getRecordXPath()
See recordXPath. recordXPath can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations.

Returns:
String

setDataURL

public void setDataURL(java.lang.String dataURL)
                throws java.lang.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 RPCManager.startQueue() will not be possible.

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

getDataURL

public java.lang.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 RPCManager.startQueue() will not be possible.

Returns:
String

setTagName

public void setTagName(java.lang.String tagName)
                throws java.lang.IllegalStateException
Tag name to use when serializing to XML. If unspecified, the dataSource.ID will be used.

Note : This is an advanced setting

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

getTagName

public java.lang.String getTagName()
Tag name to use when serializing to XML. If unspecified, the dataSource.ID will be used.

Returns:
String

setClientOnly

public void setClientOnly(java.lang.Boolean clientOnly)
                   throws java.lang.IllegalStateException
Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might.

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

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

getClientOnly

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

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

Returns:
Boolean

setCriteriaPolicy

public void setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
Decides under what conditions the com.smartgwt.client.data.ResultSet cache should be dropped when the criteria changes

Note : This is an advanced setting

Parameters:
criteriaPolicy - criteriaPolicy Default value is "dropOnShortening"

getCriteriaPolicy

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

Returns:
CriteriaPolicy

setUseLocalValidators

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

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

Note : This is an advanced setting

Parameters:
useLocalValidators - useLocalValidators Default value is null

getUseLocalValidators

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

setShowPrompt

public void setShowPrompt(java.lang.Boolean showPrompt)
Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset.

Parameters:
showPrompt - showPrompt Default value is true

getShowPrompt

public java.lang.Boolean getShowPrompt()
Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset.

Returns:
Boolean

setEnumTranslateStrategy

public void setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy)
                              throws java.lang.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 SmartGWT server

Note : This is an advanced setting

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

setEnumConstantProperty

public void setEnumConstantProperty(java.lang.String enumConstantProperty)
                             throws java.lang.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 SmartGWT server

Note : This is an advanced setting

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

setEnumOrdinalProperty

public void setEnumOrdinalProperty(java.lang.String enumOrdinalProperty)
                            throws java.lang.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 SmartGWT server

Note : This is an advanced setting

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

setAutoDeriveTitles

public void setAutoDeriveTitles(java.lang.Boolean autoDeriveTitles)
                         throws java.lang.IllegalStateException
If set, titles are automatically derived from name for any field that does not have a title and is not marked hidden:true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle.

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

getAutoDeriveTitles

public java.lang.Boolean getAutoDeriveTitles()
If set, titles are automatically derived from name for any field that does not have a title and is not marked hidden:true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle.

Returns:
Boolean

setTitle

public void setTitle(java.lang.String title)
User-visible name for this DataSource.

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

Defaults to dataSource.ID.

Parameters:
title - title Default value is dataSource.ID

getTitle

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

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

Defaults to dataSource.ID.

Returns:
String

setPluralTitle

public void setPluralTitle(java.lang.String pluralTitle)
                    throws java.lang.IllegalStateException
User-visible plural name for this DataSource.

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

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

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

getPluralTitle

public java.lang.String getPluralTitle()
User-visible plural name for this DataSource.

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

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

Returns:
String

setTitleField

public void setTitleField(java.lang.String titleField)
                   throws java.lang.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 labels an employee record.

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

Parameters:
titleField - titleField Default value is see below
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getTitleField

public java.lang.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 labels 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

setIconField

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

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

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

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

Parameters:
iconField - iconField Default value is see below
Throws:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getIconField

public java.lang.String getIconField()
Designates a field of FieldType:"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

setChildrenField

public void setChildrenField(java.lang.String childrenField)
                      throws java.lang.IllegalStateException
fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierachical data structure, rather than a flat list of nodes linked by foreignKey.
Note this is an alternative to setting childrenProperty directly on the childrenField object.

By default the children field will be assumed to be multiple, for XML databinding. This implies that child data should be delivered in the format:

      <childrenFieldName>
          <item name="firstChild" ...>
          <item name="secondChild" ...>
      </childrenFieldName>
 
However data may also be delivered as a direct list of childrenFieldName elements:
      <childrenFieldName name="firstChild" ...>
      <childrenFieldName name="secondChild" ...>
 
If you want to return your data in this format, you will need to explicitly set multiple to false in the appropriate dataSource field definition.

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

getChildrenField

public java.lang.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 hierachical 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

setServerConstructor

public void setServerConstructor(java.lang.String serverConstructor)
                          throws java.lang.IllegalStateException
Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource. This property allows you to write and use custom DataSource subclasses on the server.

One reason you might wish to do this would be to override the validate() method to provide some arbitrary custom validation (such as complex database lookups, validation embedded in legacy applications, etc). It is also possible - though obviously a more substantial task - to override the execute() method in your custom DataSource. This is one way of creating a completely customized DataSource implementation.

Note: If you use this property, you are responsible for making sure that it refers to a valid server-side class that extends com.isomorphic.datasource.DataSource. If your implementation relies on methods or state only present in certain specialized subclasses of DataSource (for example, you want the normal behavior and features of a HibernateDataSource, but with a specialized validate() method), then you shoud extend the subclass rather than the base class.

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

getServerConstructor

public java.lang.String getServerConstructor()
Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource. This property allows you to write and use custom DataSource subclasses on the server.

One reason you might wish to do this would be to override the validate() method to provide some arbitrary custom validation (such as complex database lookups, validation embedded in legacy applications, etc). It is also possible - though obviously a more substantial task - to override the execute() method in your custom DataSource. This is one way of creating a completely customized DataSource implementation.

Note: If you use this property, you are responsible for making sure that it refers to a valid server-side class that extends com.isomorphic.datasource.DataSource. If your implementation relies on methods or state only present in certain specialized subclasses of DataSource (for example, you want the normal behavior and features of a HibernateDataSource, but with a specialized validate() method), then you shoud extend the subclass rather than the base class.

Returns:
String

setQualifyColumnNames

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

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

getQualifyColumnNames

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

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, SmartGWT 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 subojects on each record, and you have not set dropExtraFields to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this number lower.

Note : This is an advanced setting

Parameters:
resultBatchSize - resultBatchSize Default value is 150

getResultBatchSize

public int getResultBatchSize()
Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, SmartGWT 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 subojects 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

setStrictSQLFiltering

public void setStrictSQLFiltering(java.lang.Boolean strictSQLFiltering)
                           throws java.lang.IllegalStateException
[A] If set to true, both client and server-side advanced filtering used by SmartGWT 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 expression are false:
    field == "someValue"  (normally false)
    field != "someValue"  (normally true)
    not (field == "someValue")   (normally true)
    not (field != "someValue")   (normally false)
 

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

getStrictSQLFiltering

public java.lang.Boolean getStrictSQLFiltering()
[A] If set to true, both client and server-side advanced filtering used by SmartGWT 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 expression are false:
    field == "someValue"  (normally false)
    field != "someValue"  (normally true)
    not (field == "someValue")   (normally true)
    not (field != "someValue")   (normally false)
 

Returns:
Boolean

getLegalChildTags

public void getLegalChildTags()
For a DataSource that describes a DOM structure, the list 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.


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 RPCResponse.STATUS_SUCCESS. You can use this hook to do DataSource-specific error handling. Unless you return false from this method, com.smartgwt.client.rpc.RPCManager#handleError will be called by SmartGWT right after this method completes.

Specified by:
addHandleErrorHandler in interface HasHandleErrorHandlers
Parameters:
handler - the handleError handler
Returns:
HandlerRegistration used to remove this handler

getField

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

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

getPrimaryKeyField

public DataSourceField getPrimaryKeyField()
Returns a pointer to the primaryKey field for this DataSource

Returns:
primary key field object

getPrimaryKeyFieldName

public java.lang.String getPrimaryKeyFieldName()
Returns the primary key fieldName for this DataSource

Returns:
primary key field name

supportsTextMatchStyle

public void supportsTextMatchStyle(java.lang.String 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.

getDataSource

public static DataSource getDataSource(java.lang.String ID)
Lookup a DataSource by ID.

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

get

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

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

onInit

protected void onInit()
Overrides:
onInit in class BaseClass

setDataProtocol

public void setDataProtocol(DSProtocol dataProtocol)
                     throws java.lang.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:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

setDefaultParams

public void setDefaultParams(java.util.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

getDataProtocol

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

Returns:
DSDataProtocol

transformRequest

protected java.lang.Object transformRequest(DSRequest dsRequest)
For a dataSource using client-side data integration, return the data that should be sent to the DataSource.dataURL.
By default, HTTP requests sent to non-SmartGWT servers do not include DSRequest metadata such as DSRequest.startRow, endRow, and oldValues. Only the core datasource protocol data is sent, such as the criteria passed to fetchData() or the updated values submitted by form.saveData().
transformRequest() allows you to transform dsRequest metadata into a format understood by your server and include it in the HTTP request, so that you can integrate DataSource features such as data paging with servers that support such features.
How the data is actually sent to the URL is controlled by OperationBinding.dataProtocol. If using the "getParams" or "postParams" protocol, data is expected to be a JavaScript Object where each property will become a GET or POST'd parameter. If using dataProtocol:"soap" or "postXML", data will be serialized as an XML message by DataSource.xmlSerialize().
Other reasons to implement transformRequest():

transformResponse

protected void transformResponse(DSResponse response,
                                 DSRequest request,
                                 java.lang.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 overriden, that is, use the callback passed to high-level methods such as grid.fetchData(), and do error handling via either com.smartgwt.client.data.DataSource#handleError or by setting willHandleError.

Note: This is an override point

Parameters:
response - the response
request - the request
data -

getClientOnlyResponse

protected DSResponse getClientOnlyResponse(DSRequest request)
Return a "spoofed" response for a clientOnly DataSource.

The default implementation will testData to provide an appropriate response, by using com.smartgwt.client.data.DataSource#applyFilter for a "fetch" request, and by modifying the testData for other requests.

Override this method to provide simulations of other server-side behavior, such as modifying other records, or to implement synchronous client-side data providers (such as Google Gears). For asynchronous third-party data provides, such as GWT-RPC, HTML5 sockets, or bridges to plug-in based protocols (Java, Flash, Silverlight..), use ${isc.DocUtils.linkForRef('DSDataProtocol','dataProtocol:"clientCustom"')} instead.

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

Note: This is an override point

Parameters:
request - DataSource request to respond to
Returns:
DSResponse

isCreated

public boolean isCreated()
Overrides:
isCreated in class BaseClass

getJsObj

public com.google.gwt.core.client.JavaScriptObject getJsObj()
Overrides:
getJsObj in class BaseClass

setRequestProperties

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

These properties are applied before transformRequest(com.smartgwt.client.data.DSRequest) is called.

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

setInheritsFrom

public void setInheritsFrom(DataSource inheritsFrom)
                     throws java.lang.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 <b>only fields are inherited</b> - 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 andhave the best possible chance of working with future versions of the "employee"dataSource.</ul>

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

setFields

public void setFields(DataSourceField... fields)
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:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

addField

public void addField(DataSourceField field)

setTestData

public void setTestData(DataClass[] testData)
For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects.

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

Parameters:
testData - testData Default value is null

getTestData

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

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

Returns:
the test data

setOperationBindings

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

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

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

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

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

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

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

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

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

/examples/databinding/rss_databinding.html 

See Also:
  OperationBinding

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

setRecordName

public void setRecordName(java.lang.String recordName)
                   throws java.lang.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:
java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

setXmlNamespaces

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

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

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

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

fetchData

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

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

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

    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)"); 
Unlike calling myGrid.fetchData(), which creates a com.smartgwt.client.data.ResultSet, the data provided to the grid is "disconnected" data, unmanaged by SmartGWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.

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

 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 

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

    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 

This gives you a dataset that supports client-side filtering (via com.smartgwt.client.data.ResultSet#setCriteria), can provide com.smartgwt.client.data.ResultSet#getValueMap, will disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual components.

See also the server-side com.isomorphic.js.JSTranslater class in the ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches involving dumping data into the page during initial page load. Note: care should be taken when using this approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets that may become very large.

Data-Driven Visual Component Creation

DataSource.fetchData() can also be used to create SmartGWT components in a data-driven way. Many properties on SmartGWT visual components are configured via an Array of Objects - the same data format that dataSource.fetchData() returns. These include fields, tabs, items, values and even fields.

For example, if you had a DataSource "myFormFields" whose fields included the basic properties of FormItem (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:

    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    ) 
This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also inheritsFrom.


fetchData

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

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

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

    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)"); 
Unlike calling myGrid.fetchData(), which creates a com.smartgwt.client.data.ResultSet, the data provided to the grid is "disconnected" data, unmanaged by SmartGWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.

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

 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 

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

    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 

This gives you a dataset that supports client-side filtering (via com.smartgwt.client.data.ResultSet#setCriteria), can provide com.smartgwt.client.data.ResultSet#getValueMap, will disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual components.

See also the server-side com.isomorphic.js.JSTranslater class in the ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches involving dumping data into the page during initial page load. Note: care should be taken when using this approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets that may become very large.

Data-Driven Visual Component Creation

DataSource.fetchData() can also be used to create SmartGWT components in a data-driven way. Many properties on SmartGWT visual components are configured via an Array of Objects - the same data format that dataSource.fetchData() returns. These include fields, tabs, items, values and even fields.

For example, if you had a DataSource "myFormFields" whose fields included the basic properties of FormItem (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:

    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    ) 
This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also inheritsFrom.

Parameters:
criteria - search criteria

fetchData

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

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

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

    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)"); 
Unlike calling myGrid.fetchData(), which creates a com.smartgwt.client.data.ResultSet, the data provided to the grid is "disconnected" data, unmanaged by SmartGWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.

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

 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 

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

    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 

This gives you a dataset that supports client-side filtering (via com.smartgwt.client.data.ResultSet#setCriteria), can provide com.smartgwt.client.data.ResultSet#getValueMap, will disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual components.

See also the server-side com.isomorphic.js.JSTranslater class in the ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches involving dumping data into the page during initial page load. Note: care should be taken when using this approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets that may become very large.

Data-Driven Visual Component Creation

DataSource.fetchData() can also be used to create SmartGWT components in a data-driven way. Many properties on SmartGWT visual components are configured via an Array of Objects - the same data format that dataSource.fetchData() returns. These include fields, tabs, items, values and even fields.

For example, if you had a DataSource "myFormFields" whose fields included the basic properties of FormItem (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:

    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    ) 
This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also inheritsFrom.

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

fetchData

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

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

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

    isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)"); 
Unlike calling myGrid.fetchData(), which creates a com.smartgwt.client.data.ResultSet, the data provided to the grid is "disconnected" data, unmanaged by SmartGWT's databinding facilities and safe to directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of HTML's multi-select component.

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

 isc.DataSource.get("countries").fetchData(null, "window.countries = data");    ... later, a form is created
 dynamically ...    function showForm() {       isc.DynamicForm.create({           items : [              {
 name:"country", title:"Pick Country",                valueMap: window.countries.getValueMap("countryId",
 "countryName")              },       ... 

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

    isc.DataSource.get("countries").fetchData(null,        function
 (dsResponse, data) {           isc.ResultSet.create({              dataSource:"countries",
 allRows:data           })        }    ) 

This gives you a dataset that supports client-side filtering (via com.smartgwt.client.data.ResultSet#setCriteria), can provide com.smartgwt.client.data.ResultSet#getValueMap, will disableCacheSync to the DataSource made via other components, and can be re-used with multiple visual components.

See also the server-side com.isomorphic.js.JSTranslater class in the ${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches involving dumping data into the page during initial page load. Note: care should be taken when using this approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource and similar facilities to manage datasets that may become very large.

Data-Driven Visual Component Creation

DataSource.fetchData() can also be used to create SmartGWT components in a data-driven way. Many properties on SmartGWT visual components are configured via an Array of Objects - the same data format that dataSource.fetchData() returns. These include fields, tabs, items, values and even fields.

For example, if you had a DataSource "myFormFields" whose fields included the basic properties of FormItem (name, title, type, etc), this example code would create a form based on stored field definitions, loaded from the "myFormFields" DataSource on the fly:

    isc.DataSource.get("myFormFields").fetchData(null,
 "isc.DynamicForm.create({ items:data })"    ) 
This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also inheritsFrom.

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

filterData

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

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

Parameters:
criteria - search criteria

filterData

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

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

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

filterData

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

addData

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

Parameters:
record - new record

addData

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

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

addData

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

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

updateData

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

Parameters:
record - updated record

updateData

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

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

updateData

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

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

removeData

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

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

removeData

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

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

removeData

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

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

xmlSerialize

public java.lang.String xmlSerialize(com.google.gwt.core.client.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 SmartGWT reported in log statements in the Developer Console.

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

xmlSerialize

public java.lang.String xmlSerialize(com.google.gwt.core.client.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 SmartGWT reported in log statements in the Developer Console.

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

processResponse

public void processResponse(java.lang.String requestId,
                            DSResponse responseProperties)
Process a dsResponse for a request initiated by a DataSource with dataProtocol. requestId parameter should be dsRequest.requestId as found on the dsRequest passed to transformRequest(com.smartgwt.client.data.DSRequest).

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

 { status : -1 } 

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

recordsFromXML

public Record[] recordsFromXML(java.lang.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