|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.smartgwt.client.core.BaseClass
com.smartgwt.client.data.DataSource
public class DataSource
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 DSRequest s 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 |
---|
public DataSource()
public DataSource(com.google.gwt.core.client.JavaScriptObject jsObj)
public DataSource(java.lang.String dataURL)
Method Detail |
---|
public static DataSource getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
public com.google.gwt.core.client.JavaScriptObject create()
create
in class BaseClass
public void setAddGlobalId(java.lang.Boolean addGlobalId) throws java.lang.IllegalStateException
Note : This is an advanced setting
addGlobalId
- addGlobalId Default value is true
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getAddGlobalId()
public void setDataFormat(DSDataFormat dataFormat) throws java.lang.IllegalStateException
fetchData()
is called).
dataFormat
- dataFormat Default value is "iscServer"
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DSDataFormat getDataFormat()
fetchData()
is called).
public void setCallbackParam(java.lang.String callbackParam) throws java.lang.IllegalStateException
callbackParam
- callbackParam Default value is "callback"
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getCallbackParam()
public void setDataTransport(RPCTransport dataTransport) throws java.lang.IllegalStateException
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.
dataTransport
- dataTransport Default value is RPCManager.defaultTransport
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic RPCTransport getDataTransport()
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.
public void setPreventHTTPCaching(java.lang.Boolean preventHTTPCaching) throws java.lang.IllegalStateException
Note that this does not disable caching at higher levels in the framework, for example, the
caching performed by com.smartgwt.client.data.ResultSet
.
preventHTTPCaching
- preventHTTPCaching Default value is true
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getPreventHTTPCaching()
Note that this does not disable caching at higher levels in the framework, for example, the
caching performed by com.smartgwt.client.data.ResultSet
.
public void setServerType(DSServerType serverType) throws java.lang.IllegalStateException
serverType
- serverType Default value is "generic"
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DSServerType getServerType()
public void setTableName(java.lang.String tableName) throws java.lang.IllegalStateException
'SmartGWT SQL engine'
for
persistence, what database table name to use. The default is to use the DataSource ID
as the table name.
tableName
- tableName Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getTableName()
'SmartGWT SQL engine'
for
persistence, what database table name to use. The default is to use the DataSource ID
as the table name.
public void setDbName(java.lang.String dbName) throws java.lang.IllegalStateException
'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).
dbName
- dbName Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getDbName()
'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).
public void setJsonPrefix(java.lang.String jsonPrefix) throws java.lang.IllegalStateException
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
jsonPrefix
- jsonPrefix Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getJsonPrefix()
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)
.
public void setJsonSuffix(java.lang.String jsonSuffix) throws java.lang.IllegalStateException
Note : This is an advanced setting
jsonSuffix
- jsonSuffix Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getJsonSuffix()
public void setUseFlatFields(java.lang.Boolean useFlatFields) throws java.lang.IllegalStateException
useFlatFields
, but applies to all DataBound components
that bind to this DataSource.
useFlatFields
- useFlatFields Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getUseFlatFields()
useFlatFields
, but applies to all DataBound components
that bind to this DataSource.
public void setShowLocalFieldsOnly(java.lang.Boolean showLocalFieldsOnly) throws java.lang.IllegalStateException
fields
from another DataSource
(via inheritsFrom
), indicates that only the fields listed in this DataSource
should be shown. All other inherited parent fields will be marked "hidden:true".
showLocalFieldsOnly
- showLocalFieldsOnly Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getShowLocalFieldsOnly()
fields
from another DataSource
(via inheritsFrom
), indicates that only the fields listed in this DataSource
should be shown. All other inherited parent fields will be marked "hidden:true".
public void setUseParentFieldOrder(java.lang.Boolean useParentFieldOrder) throws java.lang.IllegalStateException
fields
from another DataSource
(via inheritsFrom
), indicates that the parent's field order should be used
instead of the order of the fields as declared in this DataSource. New fields, if any,
are placed at the end.
useParentFieldOrder
- useParentFieldOrder Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getUseParentFieldOrder()
fields
from another DataSource
(via inheritsFrom
), indicates that the parent's field order should be used
instead of the order of the fields as declared in this DataSource. New fields, if any,
are placed at the end.
public void setDropExtraFields(java.lang.Boolean dropExtraFields) throws java.lang.IllegalStateException
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
.
dropExtraFields
- dropExtraFields Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getDropExtraFields()
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
.
public void setSendExtraFields(java.lang.Boolean sendExtraFields) throws java.lang.IllegalStateException
dropExtraFields
, for data sent to the server. Setting this
attribute to false ensures that for any records in the data object, only fields that
correspond to declared dataSource fields will be present on the dsRequest data object passed
to transformRequest(com.smartgwt.client.data.DSRequest)
and ultimately sent to the server.
sendExtraFields
- sendExtraFields Default value is true
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getSendExtraFields()
dropExtraFields
, for data sent to the server. Setting this
attribute to false ensures that for any records in the data object, only fields that
correspond to declared dataSource fields will be present on the dsRequest data object passed
to transformRequest(com.smartgwt.client.data.DSRequest)
and ultimately sent to the server.
public void setAutoDeriveSchema(java.lang.Boolean autoDeriveSchema) throws java.lang.IllegalStateException
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.
autoDeriveSchema
- autoDeriveSchema Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getAutoDeriveSchema()
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.
public void setServiceNamespace(java.lang.String serviceNamespace) throws java.lang.IllegalStateException
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".
serviceNamespace
- serviceNamespace Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getServiceNamespace()
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".
public java.lang.String getSchemaNamespace() throws java.lang.IllegalStateException
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.
java.lang.IllegalStateException
- if underlying component has not yet been created.public void setRecordXPath(java.lang.String recordXPath) throws java.lang.IllegalStateException
recordXPath
. recordXPath
can be specified
directly on the DataSource for a simple read-only DataSource only capable of "fetch"
operations.
recordXPath
- recordXPath Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getRecordXPath()
recordXPath
. recordXPath
can be specified
directly on the DataSource for a simple read-only DataSource only capable of "fetch"
operations.
public void setDataURL(java.lang.String dataURL) throws java.lang.IllegalStateException
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.
dataURL
- dataURL Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getDataURL()
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.
public void setTagName(java.lang.String tagName) throws java.lang.IllegalStateException
dataSource.ID
will be used.
Note : This is an advanced setting
tagName
- tagName Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getTagName()
dataSource.ID
will be used.
public void setClientOnly(java.lang.Boolean clientOnly) throws java.lang.IllegalStateException
See 'this discussion'
for ways to populate a
client-only DataSource with test data.
clientOnly
- clientOnly Default value is false
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getClientOnly()
See 'this discussion'
for ways to populate a
client-only DataSource with test data.
public void setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
com.smartgwt.client.data.ResultSet
cache should be dropped when the
criteria
changes
Note : This is an advanced setting
criteriaPolicy
- criteriaPolicy Default value is "dropOnShortening"public CriteriaPolicy getCriteriaPolicy()
com.smartgwt.client.data.ResultSet
cache should be dropped when the
criteria
changes
public void setUseLocalValidators(java.lang.Boolean useLocalValidators)
Disabling client-side validation entirely is a good way to test server-side validation.
Note : This is an advanced setting
useLocalValidators
- useLocalValidators Default value is nullpublic java.lang.Boolean getUseLocalValidators()
Disabling client-side validation entirely is a good way to test server-side validation.
public void setShowPrompt(java.lang.Boolean showPrompt)
showPrompt
if it's unset.
showPrompt
- showPrompt Default value is truepublic java.lang.Boolean getShowPrompt()
showPrompt
if it's unset.
public void setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy) throws java.lang.IllegalStateException
Note : This is an advanced setting
enumTranslateStrategy
- enumTranslateStrategy Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setEnumConstantProperty(java.lang.String enumConstantProperty) throws java.lang.IllegalStateException
EnumTranslateStrategy
is set
to "bean". Defaults to "_constant" if not set.
This property is only applicable if you are using the SmartGWT server
Note : This is an advanced setting
enumConstantProperty
- enumConstantProperty Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setEnumOrdinalProperty(java.lang.String enumOrdinalProperty) throws java.lang.IllegalStateException
EnumTranslateStrategy
is set
to "bean". Defaults to "_ordinal" if not set.
This property is only applicable if you are using the SmartGWT server
Note : This is an advanced setting
enumOrdinalProperty
- enumOrdinalProperty Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setAutoDeriveTitles(java.lang.Boolean autoDeriveTitles) throws java.lang.IllegalStateException
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
.
autoDeriveTitles
- autoDeriveTitles Default value is true
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getAutoDeriveTitles()
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
.
public void setTitle(java.lang.String title)
For example, for the supplyItem DataSource, "Supply Item".
Defaults to dataSource.ID
.
title
- title Default value is dataSource.IDpublic java.lang.String getTitle()
For example, for the supplyItem DataSource, "Supply Item".
Defaults to dataSource.ID
.
public void setPluralTitle(java.lang.String pluralTitle) throws java.lang.IllegalStateException
For example, for the supplyItem DataSource, "Supply Items".
Defaults to (dataSource.title
or dataSource.ID
) + "s".
pluralTitle
- pluralTitle Default value is dataSource.ID
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getPluralTitle()
For example, for the supplyItem DataSource, "Supply Items".
Defaults to (dataSource.title
or dataSource.ID
) + "s".
public void setTitleField(java.lang.String titleField) throws java.lang.IllegalStateException
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.
titleField
- titleField Default value is see below
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getTitleField()
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.
public void setIconField(java.lang.String iconField) throws java.lang.IllegalStateException
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
.
iconField
- iconField Default value is see below
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getIconField()
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
.
public void setChildrenField(java.lang.String childrenField) throws java.lang.IllegalStateException
childrenProperty
directly on
the childrenField object.
By default the children field will be assumed to be multiple
,
for XML databinding. This implies that child data should be delivered in the format:
<childrenFieldName> <item name="firstChild" ...> <item name="secondChild" ...> </childrenFieldName>However data may also be delivered as a direct list of
childrenFieldName
elements:
<childrenFieldName name="firstChild" ...> <childrenFieldName name="secondChild" ...>If you want to return your data in this format, you will need to explicitly set
multiple
to false in the appropriate dataSource field definition.
childrenField
- childrenField Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getChildrenField()
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.
public void setServerConstructor(java.lang.String serverConstructor) throws java.lang.IllegalStateException
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.
serverConstructor
- serverConstructor Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.String getServerConstructor()
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.
public void setQualifyColumnNames(java.lang.Boolean qualifyColumnNames) throws java.lang.IllegalStateException
serverType
"sql", determines whether we qualify column
names with table names in any SQL we generate. This property can be overridden on specific
operationBindings.
qualifyColumnNames
- qualifyColumnNames Default value is true
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getQualifyColumnNames()
serverType
"sql", determines whether we qualify column
names with table names in any SQL we generate. This property can be overridden on specific
operationBindings.
public void setResultBatchSize(int resultBatchSize)
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
resultBatchSize
- resultBatchSize Default value is 150public int getResultBatchSize()
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.
public void setStrictSQLFiltering(java.lang.Boolean strictSQLFiltering) throws java.lang.IllegalStateException
field == "someValue" (normally false) field != "someValue" (normally true) not (field == "someValue") (normally true) not (field != "someValue") (normally false)
strictSQLFiltering
- strictSQLFiltering Default value is false
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic java.lang.Boolean getStrictSQLFiltering()
field == "someValue" (normally false) field != "someValue" (normally true) not (field == "someValue") (normally true) not (field != "someValue") (normally false)
public void getLegalChildTags()
For a DataSource described by XML schema, this is the list of legal subelements of complexType (elements of simpleType become DataSourceFields with atomic type).
Note that currently, if an XML schema file contains ordering constraints, DataSources derived from XML Schema do not capture these constraints.
public HandlerRegistration addHandleErrorHandler(HandleErrorHandler handler)
If you define this method on a DataSource, it will be called whenever the server returns
a DSResponse with a status other than 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.
addHandleErrorHandler
in interface HasHandleErrorHandlers
handler
- the handleError handler
HandlerRegistration
used to remove this handlerpublic DataSourceField getField(java.lang.String fieldName)
fieldName
- Name of the field to retrieve
public DataSourceField getPrimaryKeyField()
public java.lang.String getPrimaryKeyFieldName()
public void supportsTextMatchStyle(java.lang.String textMatchStyle)
textMatchStyle
- textMatchStyle to check. If passed a null value, assume an exact match is being requested.public static DataSource getDataSource(java.lang.String ID)
ID
- DataSource ID
public static DataSource get(java.lang.String ID)
getDataSource(java.lang.String)
: Lookup a DataSource by ID.
ID
- DataSource ID
protected void onInit()
onInit
in class BaseClass
public void setDataProtocol(DSProtocol dataProtocol) throws java.lang.IllegalStateException
dataProtocol
}
dataProtocol
- dataProtocol Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setDefaultParams(java.util.Map defaultParams)
defaultParams
- the default paramspublic DSProtocol getDataProtocol()
dataProtocol
}
protected java.lang.Object transformRequest(DSRequest dsRequest)
dsRequest
- the DSRequest being processed
protected void transformResponse(DSResponse response, DSRequest request, java.lang.Object data)
dataURL
. This is an override point that makes it possible to
use DataSource features such as paging with web services that support such features, by allowing you to fill in
metadata fields in the DSResponse object (such as startRow
) based on service-specific metadata fields contained in the service's response.
The DSResponse
passed to this method already has data
, which is derived
differently depending on the dataFormat
setting:
dataFormat:"xml"
: either the recordXPath
or recordName
is used to select the
XML elements that represent DataSource records. The selected XML elements are passed to recordsFromXML(java.lang.Object)
, which transforms the XML elements to typed JavaScript data
using the DataSource as a schema. dataFormat:"json"
: the recordXPath
, if specified, is used to select records
from the returned JSON data via com.smartgwt.client.util.XMLTools#selectObjects
. valueXPath
is used to derive correctly typed field
values. dataFormat:"custom"
: dsResponse.data
is the raw response in String form.
It must be parsed into an Array of Objects for subsequent processing to work. In addition to
dsResponse.data
, status
is defaulted to 0
(indicating no error), and startRow
is assumed to be
zero, with endRow
and totalRows
both set to dsResponse.data.length - 1
,
that is, the returned data is assumed to be all records that matched the filter criteria.
Examples of using this API include:
startRow
, endRow
and totalRows
to allow paging for a service that supports it. For example, if an XML service returns a
"resultRow" tag that contained the row number of the first row of the returned results:dsResponse.startRow = isc.XMLTools.selectNumber(xmlData, "//resultRow");
status
to recognized ISC error values based on service-specific
errors, in order to trigger standard ISC error handling. For example, setting
dsResponse.status
to RPCResponse.STATUS_VALIDATION_ERROR
and
filling in errors
in order to cause validation errors
to be shown in forms and grids. oldValues
to create cache update
data (whether this is appropriate is application-specific), or setting invalidateCache
. NOTE: this method is NOT an appropriate time to call methods on visual components such
as grids, initiate new DSRequests or RPCRequests, or in general do anything other than fill in fields on the
DSResponse based on data that is already available. Any actions that need to be taken as a result of the web
service response should be implemented exactly as for a DataSource where transformResponse()
has not
been overriden, that is, use the callback passed to high-level methods such as grid.fetchData()
,
and do error handling via either com.smartgwt.client.data.DataSource#handleError
or by setting willHandleError
.
Note: This is an override point
response
- the responserequest
- the requestdata
- protected DSResponse getClientOnlyResponse(DSRequest request)
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
request
- DataSource request to respond to
public boolean isCreated()
isCreated
in class BaseClass
public com.google.gwt.core.client.JavaScriptObject getJsObj()
getJsObj
in class BaseClass
public void setRequestProperties(DSRequest requestProperties) throws java.lang.IllegalStateException
DSRequest
s made by this DataSource.
These properties are applied before transformRequest(com.smartgwt.client.data.DSRequest)
is called.
requestProperties
- requestProperties Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setInheritsFrom(DataSource inheritsFrom) throws java.lang.IllegalStateException
useParentFieldOrder
to instead use the
parent's field order, with new local fields appearing last.showLocalFieldsOnly
to
have all non-local fields hidden.inheritsFrom
XMLTools.loadXMLSchema(String, XSDLoadCallback)
or other metadata formats modelling
object subclassing and extension in server-side code and storage systems modelling relational database joins, and
the equivalents in other systems creating hooks for others to customize your application in a maintainable way.
For example, if you have a dataSource "employee", you can create a
dataSource"customizedEmployee" which inherits from "employee" but does not initially define
anyfields, and bind all databound components to"customizedEmployee". Customizations of fields
(including appearance changes, fieldorder, new fields, hiding of fields, and custom validation rules) can be
added to"customizedEmployee", so that they are kept separtely from the original field data andhave the
best possible chance of working with future versions of the "employee"dataSource.</ul>
inheritsFrom
- the datasource to inherit from
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setFields(DataSourceField... fields)
Each DataSource field can have type, user-visible title, validators, and other metadata attached.
fields
- fields Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void addField(DataSourceField field)
public void setTestData(DataClass[] testData)
See this discussion for ways to populate a client-only DataSource with test data.
testData
- testData Default value is nullpublic DataClass[] getTestData()
See this discussion for ways to populate a client-only DataSource with test data.
public void setOperationBindings(OperationBinding... operationBindings) throws java.lang.IllegalStateException
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
operationBindings
- the operation bindings
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setRecordName(java.lang.String recordName) throws java.lang.IllegalStateException
recordName
. recordName
can be
specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations.
recordName
- Default value is null
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setXmlNamespaces(XmlNamespaces xmlNamespaces) throws java.lang.IllegalStateException
xmlNamespaces
- xml namespaces
java.lang.IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void fetchData()
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
.
public void fetchData(Criteria criteria)
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
.
criteria
- search criteriapublic void fetchData(Criteria criteria, DSCallback callback)
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
.
criteria
- search criteriacallback
- callback to invoke on completionpublic void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
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
.
criteria
- search criteriacallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedpublic void filterData(Criteria criteria)
This is identical to fetchData()
except that textMatchStyle
is set to "substring" to cause case
insensitive substring matching (if the server respects this setting).
criteria
- search criteriapublic void filterData(Criteria criteria, DSCallback callback)
This is identical to fetchData()
except that textMatchStyle
is set to "substring" to cause case
insensitive substring matching (if the server respects this setting).
criteria
- search criteriacallback
- callback to invoke on completionpublic void filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
public void addData(Record record)
record
- new recordpublic void addData(Record record, DSCallback callback)
record
- new recordcallback
- callback to invoke on completionpublic void addData(Record record, DSCallback callback, DSRequest requestProperties)
record
- new recordcallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedpublic void updateData(Record record)
record
- updated recordpublic void updateData(Record record, DSCallback callback)
record
- updated recordcallback
- callback to invoke on completionpublic void updateData(Record record, DSCallback callback, DSRequest requestProperties)
record
- updated recordcallback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedpublic void removeData(Record record)
record
- primary key values of record to delete, (or complete
record)public void removeData(Record record, DSCallback callback)
record
- primary key values of record to delete, (or complete
record)callback
- callback to invoke on completionpublic void removeData(Record record, DSCallback callback, DSRequest requestProperties)
record
- primary key values of record to delete,(or complete record)callback
- callback to invoke on completionrequestProperties
- additional properties to set on the DSRequest that will be issuedpublic java.lang.String xmlSerialize(com.google.gwt.core.client.JavaScriptObject data)
The JavaScript Object passed to xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
element named after the tagName
(or ID
if
tagName is unset). Each property of the object becomes a subElement. For example,
using a DataSource to serialize like this:
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.
data
- data to be serialized
public java.lang.String xmlSerialize(com.google.gwt.core.client.JavaScriptObject data, SerializationContext flags)
The JavaScript Object passed to xmlSerialize(com.google.gwt.core.client.JavaScriptObject)
becomes an XML
element named after the tagName
(or ID
if
tagName is unset). Each property of the object becomes a subElement. For example,
using a DataSource to serialize like this:
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.
data
- data to be serializedflags
- options for the serialization engine
public void processResponse(java.lang.String requestId, DSResponse responseProperties)
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 }
requestId
- requestId attribute from the associated dataSource request objectrequestId
- the request IDrequestId
- Configuration for the dsResponsepublic Record[] recordsFromXML(java.lang.Object elements)
recordsFromXML() will return a List of DataSource Records. The value for each field is extracted from the XML according
to the rules described under valueXPath
.
elements
- XML elements to transform, eg, the result of a call to XMLTools.selectNodes(Object, String)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |