|
|||||||||
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 'field types'
, 'validation rules'
, 'relationships'
to other DataSources, and other metadata.
The abstract object description provided by a DataSource is easily mapped to a variety of backend object models and storage schemes. The following table shows analogous terminology across systems.
Isomorphic Smart GWT | Relational Database | Enterprise Java Beans (EJB) | Entity/Relationship 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 Smart GWT Java-based server to connect to data represented by Java Objects or
JDBC-accessible databases. 'Client-side integration'
connects
Smart GWT DataSources to XML, JSON or other formats accessible via HTTP.
DataSources have a concept of '4 core operations'
("fetch", "add", "update" and "remove") that can be
performed on the set of objects represented by a DataSource. Once a DataSource has been integrated with your data
store, databinding-capable UI components can leverage the 4 core DataSource operations to provide many complete user
interactions without the need to configure how each individual component loads and saves data.
These interactions
include ListGrid
, TreeGrid
, DetailViewer
, DynamicForm
-based DynamicForm.editRecord(com.smartgwt.client.data.Record)
and DynamicForm.saveData()
, grid-based 'editing'
and 'saving'
, 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, scClassName |
Constructor Summary | |
---|---|
DataSource()
|
|
DataSource(JavaScriptObject jsObj)
|
|
DataSource(String dataURL)
|
Method Summary | |
---|---|
void |
addData(Record record)
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record. |
void |
addData(Record record,
DSCallback callback)
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record. |
void |
addData(Record record,
DSCallback callback,
DSRequest requestProperties)
Perform an "add" DataSource operation against this DataSource, to create a new DataSource record. |
void |
addField(DataSourceField field)
Add a field to the DataSource |
HandlerRegistration |
addHandleErrorHandler(HandleErrorHandler handler)
Add a handleError handler. |
JavaScriptObject |
create()
|
void |
downloadFile(Record data)
Download a file stored in a field of type:"binary" in a DataSource record. |
void |
downloadFile(Record data,
String fieldName,
DSRequest requestProperties)
Download a file stored in a field of type:"binary" in a DataSource record. |
void |
fetchData()
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records. |
void |
fetchData(Criteria criteria)
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records. |
void |
fetchData(Criteria criteria,
DSCallback callback)
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records. |
void |
fetchData(Criteria criteria,
DSCallback callback,
DSRequest requestProperties)
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records. |
void |
filterData(Criteria criteria)
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records. |
void |
filterData(Criteria criteria,
DSCallback callback)
Perform a "fetch" DataSource operation against this DataSource, sending search criteria and retrieving matching records. |
void |
filterData(Criteria criteria,
DSCallback callback,
DSRequest requestProperties)
|
static DataSource |
get(String ID)
Synonym of getDataSource(java.lang.String) : Lookup a DataSource by ID. |
Boolean |
getAddGlobalId()
Whether to make this DataSource available as a global variable for convenience. |
Boolean |
getAutoDeriveSchema()
For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from the SQL table specified in tableName . |
Boolean |
getAutoDeriveTitles()
If set, titles are automatically derived from 'field.name' for
any field that does not have a 'field.title' and is not
marked 'hidden' :true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle . |
String |
getBeanClassName()
This property has different meanings depending on the 'serverType' : |
String |
getCallbackParam()
Applies only to dataFormat: "json". |
Boolean |
getCanMultiSort()
When true, indicates that this DataSource supports multi-level sorting. |
String |
getChildrenField()
fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a 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. |
Boolean |
getClientOnly()
Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might. |
protected DSResponse |
getClientOnlyResponse(DSRequest request)
Return a "spoofed" response for a clientOnly DataSource.
|
CriteriaPolicy |
getCriteriaPolicy()
Decides under what conditions the ResultSet cache should be dropped when the criteria changes. |
DSDataFormat |
getDataFormat()
Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when fetchData() is called). |
DSProtocol |
getDataProtocol()
Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. |
static DataSource |
getDataSource(String ID)
Lookup a DataSource by ID. |
RPCTransport |
getDataTransport()
Transport to use for all operations on this DataSource. |
String |
getDataURL()
Default URL to contact to fulfill all DSRequests. |
String |
getDbName()
For DataSources using the 'Smart GWT SQL engine' for persistence, which
database configuration to use. |
Map |
getDefaultParams()
HTTP parameters that should be submitted with every DSRequest. |
Boolean |
getDropExtraFields()
Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded. |
DataSourceField |
getField(String fieldName)
Return the field definition object. |
String[] |
getFieldNames()
Retrieves the list of fields declared on this DataSource. |
String[] |
getFieldNames(boolean excludeHidden)
Retrieves the list of fields declared on this DataSource. |
DataSourceField[] |
getFields()
The list of fields that compose records from this DataSource. |
String |
getIconField()
Designates a field of FieldType :"image" as the field to use when rendering a record as
an image, for example, in a TileGrid . |
JavaScriptObject |
getJsObj()
|
String |
getJsonPrefix()
Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application. The inclusion of such a prefix ensures your code is not directly executable outside of your application, as a preventitive measure against javascript hijacking. |
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. |
void |
getLegalChildTags()
For a DataSource that describes a DOM structure, the list of legal child elements that can be contained by the element described by this DataSource. |
static DataSource |
getOrCreateRef(JavaScriptObject jsObj)
|
String |
getPluralTitle()
User-visible plural name for this DataSource. |
Boolean |
getPreventHTTPCaching()
If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable. |
DataSourceField |
getPrimaryKeyField()
Returns a pointer to the primaryKey field for this DataSource |
String |
getPrimaryKeyFieldName()
Returns the primary key fieldName for this DataSource |
Boolean |
getQualifyColumnNames()
For dataSources of 'serverType' "sql", determines whether we
qualify column names with table names in any SQL we generate. |
Boolean |
getQuoteColumnNames()
If set, tells the SQL engine to quote column names in all generated DML and DDL statements for this dataSource. |
String |
getRecordXPath()
See recordXPath . |
Boolean |
getRequiresAuthentication()
Whether a user must be authenticated in order to access this DataSource. |
String |
getRequiresRole()
Similar to requiresRole , but controls access to
the DataSource as a whole. |
int |
getResultBatchSize()
Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user. |
String |
getSchemaNamespace()
For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to. |
Boolean |
getSendExtraFields()
Analagous to dropExtraFields , for data sent to the
server. |
String |
getServerConstructor()
Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource. |
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. |
String |
getServiceNamespace()
For an XML DataSource, URN of the WebService to use to invoke operations. |
Boolean |
getShowLocalFieldsOnly()
For a DataSource that inherits fields from another DataSource
(via inheritsFrom ), indicates that only the fields listed in
this DataSource should be shown. |
Boolean |
getShowPrompt()
Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset. |
static String[] |
getSortBy(String[] sortSpecifiers)
Given an array of ${isc.DocUtils.linkForRef('object:SortSpecifier')}s, return a simple list of Strings in the format expected by sortBy . |
static String[] |
getSortSpecifiers(String[] sortBy)
Return a an array of ${isc.DocUtils.linkForRef('object:SortSpecifier')}s, given an array of Strings in the format expected by sortBy . |
Boolean |
getStrictSQLFiltering()
[A] If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false: |
String |
getTableName()
For DataSources using the 'Smart GWT SQL engine' for persistence, what
database table name to use. |
String |
getTagName()
Tag name to use when serializing to XML. |
DataClass[] |
getTestData()
For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects. |
String |
getTitle()
User-visible name for this DataSource. |
String |
getTitleField()
Best field to use for a user-visible title for an individual record from this dataSource. |
Boolean |
getUseFlatFields()
Like useFlatFields , but applies to all DataBound
components that bind to this DataSource. |
Boolean |
getUseHttpProxy()
Like useHttpProxy , but serves as a default for this
DataSource that may be overriden by individual operationBindings. |
Boolean |
getUseLocalValidators()
Whether to attempt validation on the client at all for this DataSource. |
Boolean |
getUseParentFieldOrder()
For a DataSource that inherits fields from another DataSource
(via inheritsFrom ), indicates that the parent's field order
should be used instead of the order of the fields as declared in this DataSource. |
Boolean |
getValidateRelatedRecords()
If true, indicates that the Smart GWT Server should automatically apply a com.smartgwt.client..ValidatorTypes#hasRelatedRecord validator to every field on this dataSource that has a 'foreignKey' defined. |
boolean |
isCreated()
|
static void |
load(String[] dsID,
Function callback,
boolean forceReload)
Load a DataSource or an array of DataSources using the DataSourceLoader servlet. |
static void |
load(String dsID,
Function callback,
boolean forceReload)
Load a DataSource or an array of DataSources using the DataSourceLoader servlet. |
protected void |
onInit()
|
void |
processResponse(String requestId,
DSResponse responseProperties)
Process a dsResponse for a request initiated by a DataSource with dataProtocol . |
Record[] |
recordsFromXML(Object elements)
Transform a list of XML elements to DataSource records. |
void |
removeData(Record record)
Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record. |
void |
removeData(Record record,
DSCallback callback)
Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record. |
void |
removeData(Record record,
DSCallback callback,
DSRequest requestProperties)
Perform a "remove" DataSource operation against this DataSource, to delete an existing DataSource record. |
void |
setAddGlobalId(Boolean addGlobalId)
Whether to make this DataSource available as a global variable for convenience. |
void |
setAutoDeriveSchema(Boolean autoDeriveSchema)
For a DataSource with serverType: "sql" or serverType: "hibernate", automatically derive the dataSource's schema (field definitions) from the SQL table specified in tableName . |
void |
setAutoDeriveTitles(Boolean autoDeriveTitles)
If set, titles are automatically derived from 'field.name' for
any field that does not have a 'field.title' and is not
marked 'hidden' :true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle . |
void |
setBeanClassName(String beanClassName)
This property has different meanings depending on the 'serverType' : |
void |
setCallbackParam(String callbackParam)
Applies only to dataFormat: "json". |
void |
setCanMultiSort(Boolean canMultiSort)
When true, indicates that this DataSource supports multi-level sorting. |
void |
setChildrenField(String childrenField)
fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a 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(Boolean clientOnly)
Whether to act as a "client-only" DataSource, which has no permanent storage and never contacts the server, instead using a set of test data to respond to requests in the same manner as a server-based DataSource might. |
void |
setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
Decides under what conditions the ResultSet cache should be dropped when the criteria changes. |
void |
setDataFormat(DSDataFormat dataFormat)
Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when fetchData() is called). |
void |
setDataProtocol(DSProtocol dataProtocol)
Controls the format in which inputs are sent to the dataURL when fulfilling DSRequests. |
void |
setDataTransport(RPCTransport dataTransport)
Transport to use for all operations on this DataSource. |
void |
setDataURL(String dataURL)
Default URL to contact to fulfill all DSRequests. |
void |
setDbName(String dbName)
For DataSources using the 'Smart GWT SQL engine' for persistence, which
database configuration to use. |
void |
setDefaultParams(Map defaultParams)
HTTP parameters that should be submitted with every DSRequest. |
void |
setDropExtraFields(Boolean dropExtraFields)
Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded. |
void |
setEnumConstantProperty(String enumConstantProperty)
The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if the EnumTranslateStrategy is set to "bean". |
void |
setEnumOrdinalProperty(String enumOrdinalProperty)
The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if the EnumTranslateStrategy is set to "bean". |
void |
setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy)
Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript. |
void |
setFields(DataSourceField... fields)
The list of fields that compose records from this DataSource. |
void |
setIconField(String iconField)
Designates a field of 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(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. |
void |
setJsonSuffix(String jsonSuffix)
Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application. The inclusion of such a suffix ensures your code is not directly executable outside of your application, as a preventitive measure against javascript hijacking. |
void |
setOperationBindings(OperationBinding... operationBindings)
Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed. |
void |
setPluralTitle(String pluralTitle)
User-visible plural name for this DataSource. |
void |
setPreventHTTPCaching(Boolean preventHTTPCaching)
If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable. |
void |
setQualifyColumnNames(Boolean qualifyColumnNames)
For dataSources of 'serverType' "sql", determines whether we
qualify column names with table names in any SQL we generate. |
void |
setQuoteColumnNames(Boolean quoteColumnNames)
If set, tells the SQL engine to quote column names in all generated DML and DDL statements for this dataSource. |
void |
setRecordName(String recordName)
See recordName . |
void |
setRecordXPath(String recordXPath)
See recordXPath . |
void |
setRequestProperties(DSRequest requestProperties)
Additional properties to pass through to the DSRequest s made by this DataSource. |
void |
setRequiresAuthentication(Boolean requiresAuthentication)
Whether a user must be authenticated in order to access this DataSource. |
void |
setRequiresRole(String requiresRole)
Similar to requiresRole , but controls access to
the DataSource as a whole. |
void |
setResultBatchSize(int resultBatchSize)
Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user. |
void |
setSendExtraFields(Boolean sendExtraFields)
Analagous to dropExtraFields , for data sent to the
server. |
void |
setServerConstructor(String serverConstructor)
Specifies the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource. |
void |
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(String serviceNamespace)
For an XML DataSource, URN of the WebService to use to invoke operations. |
void |
setShowLocalFieldsOnly(Boolean showLocalFieldsOnly)
For a DataSource that inherits fields from another DataSource
(via inheritsFrom ), indicates that only the fields listed in
this DataSource should be shown. |
void |
setShowPrompt(Boolean showPrompt)
Whether RPCRequests sent by this DataSource should enable showPrompt if it's unset. |
void |
setStrictSQLFiltering(Boolean strictSQLFiltering)
[A] If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false: |
void |
setTableName(String tableName)
For DataSources using the 'Smart GWT SQL engine' for persistence, what
database table name to use. |
void |
setTagName(String tagName)
Tag name to use when serializing to XML. |
void |
setTestData(DataClass[] testData)
For a client-only DataSource, a set of records to use as a dataset, specified as an Array of JavaScript Objects. |
void |
setTitle(String title)
User-visible name for this DataSource. |
void |
setTitleField(String titleField)
Best field to use for a user-visible title for an individual record from this dataSource. |
void |
setUseFlatFields(Boolean useFlatFields)
Like useFlatFields , but applies to all DataBound
components that bind to this DataSource. |
void |
setUseHttpProxy(Boolean useHttpProxy)
Like useHttpProxy , but serves as a default for this
DataSource that may be overriden by individual operationBindings. |
void |
setUseLocalValidators(Boolean useLocalValidators)
Whether to attempt validation on the client at all for this DataSource. |
void |
setUseParentFieldOrder(Boolean useParentFieldOrder)
For a DataSource that inherits fields from another DataSource
(via inheritsFrom ), indicates that the parent's field order
should be used instead of the order of the fields as declared in this DataSource. |
void |
setValidateRelatedRecords(Boolean validateRelatedRecords)
If true, indicates that the Smart GWT Server should automatically apply a com.smartgwt.client..ValidatorTypes#hasRelatedRecord validator to every field on this dataSource that has a 'foreignKey' defined. |
void |
setXmlNamespaces(XmlNamespaces xmlNamespaces)
Optional object declaring namespace prefixes for use in OperationBinding.recordXPath and DataSourceField.valueXPath XPath expressions. |
void |
supportsTextMatchStyle(TextMatchStyle textMatchStyle)
Does this dataSource support the specified "textMatchStyle" when performing a filter operation against a text field. |
protected Object |
transformRequest(DSRequest dsRequest)
For a dataSource using client-side data integration, return the data that should be sent to the DataSource.dataURL. |
protected void |
transformResponse(DSResponse response,
DSRequest request,
Object data)
Modify the DSResponse object derived from the response returned from the dataURL . |
void |
updateData(Record record)
Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record. |
void |
updateData(Record record,
DSCallback callback)
Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record. |
void |
updateData(Record record,
DSCallback callback,
DSRequest requestProperties)
Perform an "update" DataSource operation against this DataSource, to update values in an existing DataSource record. |
void |
viewFile(Record data)
Display a file stored in a field of type:"binary" in a new browser window. |
void |
viewFile(Record data,
String fieldName,
DSRequest requestProperties)
Display a file stored in a field of type:"binary" in a new browser window. |
String |
xmlSerialize(JavaScriptObject data)
Serialize a JavaScript object as XML. |
String |
xmlSerialize(JavaScriptObject data,
SerializationContext flags)
Serialize a JavaScript object as XML. |
Methods inherited from class com.smartgwt.client.core.BaseClass |
---|
destroy, doAddHandler, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, 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(JavaScriptObject jsObj)
public DataSource(String dataURL)
Method Detail |
---|
public static DataSource getOrCreateRef(JavaScriptObject jsObj)
public JavaScriptObject create()
create
in class BaseClass
public void setAddGlobalId(Boolean addGlobalId) throws IllegalStateException
Note : This is an advanced setting
addGlobalId
- addGlobalId Default value is true
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getAddGlobalId()
public void setDataFormat(DSDataFormat dataFormat) throws IllegalStateException
fetchData()
is called).
dataFormat
- dataFormat Default value is "iscServer"
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DSDataFormat getDataFormat()
fetchData()
is called).
public void setUseHttpProxy(Boolean useHttpProxy) throws IllegalStateException
useHttpProxy
, but serves as a default for this
DataSource that may be overriden by individual operationBindings.
useHttpProxy
- useHttpProxy Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getUseHttpProxy()
useHttpProxy
, but serves as a default for this
DataSource that may be overriden by individual operationBindings.
public void setCallbackParam(String callbackParam) throws IllegalStateException
callbackParam
- callbackParam Default value is "callback"
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getCallbackParam()
public void setDataTransport(RPCTransport dataTransport) throws IllegalStateException
com.smartgwt.client.rpc.RPCManager#defaultTransport
. This would typically only be set to enable "scriptInclude"
transport for contacting 'JSON'
web services hosted on servers
other than the origin server. When using the "scriptInclude" transport, be sure to set callbackParam
or callbackParam
to match the name of the query parameter name
expected by your JSON service provider.
dataTransport
- dataTransport Default value is RPCManager.defaultTransport
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 'JSON'
web services hosted on servers
other than the origin server. When using the "scriptInclude" transport, be sure to set callbackParam
or callbackParam
to match the name of the query parameter name
expected by your JSON service provider.
public void setPreventHTTPCaching(Boolean preventHTTPCaching) throws IllegalStateException
Note that this does not disable caching at higher levels in the framework, for example, the caching
performed by ResultSet
.
preventHTTPCaching
- preventHTTPCaching Default value is true
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getPreventHTTPCaching()
Note that this does not disable caching at higher levels in the framework, for example, the caching
performed by ResultSet
.
public void setServerType(DSServerType serverType) throws IllegalStateException
serverType
- serverType Default value is "generic"
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DSServerType getServerType()
public void setTableName(String tableName) throws IllegalStateException
'Smart GWT 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getTableName()
'Smart GWT 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(String dbName) throws IllegalStateException
'Smart GWT 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 is also settable using the "Databases" tab).
dbName
- dbName Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getDbName()
'Smart GWT 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 is also settable using the "Databases" tab).
public void setQuoteColumnNames(Boolean quoteColumnNames) throws IllegalStateException
In general we recommend that you allow the database to use its natural naming scheme
when creating tables (put more simply, just do not quote column names in the CREATE TABLE
statement); if
you do this, you will not need to worry about quoting column names when querying. However, if you are dealing with
pre-existing tables, or do not have control over the database naming conventions used, this property may become
necessary.
Note: Only applicable to dataSources of 'serverType'
"sql".
quoteColumnNames
- quoteColumnNames Default value is true
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getQuoteColumnNames()
In general we recommend that you allow the database to use its natural naming scheme
when creating tables (put more simply, just do not quote column names in the CREATE TABLE
statement); if
you do this, you will not need to worry about quoting column names when querying. However, if you are dealing with
pre-existing tables, or do not have control over the database naming conventions used, this property may become
necessary.
Note: Only applicable to dataSources of 'serverType'
"sql".
public void setJsonPrefix(String jsonPrefix) throws IllegalStateException
'dataFormat:"custom"'
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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getJsonPrefix()
'dataFormat:"custom"'
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(String jsonSuffix) throws IllegalStateException
Note : This is an advanced setting
jsonSuffix
- jsonSuffix Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getJsonSuffix()
public void setUseFlatFields(Boolean useFlatFields) throws IllegalStateException
useFlatFields
, but applies to all DataBound
components that bind to this DataSource.
useFlatFields
- useFlatFields Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getUseFlatFields()
useFlatFields
, but applies to all DataBound
components that bind to this DataSource.
public void setShowLocalFieldsOnly(Boolean showLocalFieldsOnly) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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(Boolean useParentFieldOrder) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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(Boolean dropExtraFields) throws IllegalStateException
For 'JSON'
data, this means extra properties in selected objects are
dropped.
By default, for DMI DSResponses, DSResponse.data is filtered on the server to just the set of fields
defined on the DataSource. This type of filtering can also be enabled for non-DMI DSResponses (see the overview in
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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getDropExtraFields()
For 'JSON'
data, this means extra properties in selected objects are
dropped.
By default, for DMI DSResponses, DSResponse.data is filtered on the server to just the set of fields
defined on the DataSource. This type of filtering can also be enabled for non-DMI DSResponses (see the overview in
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(Boolean sendExtraFields) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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(Boolean autoDeriveSchema) throws IllegalStateException
tableName
. This
causes Smart GWT to create a "super" DataSource, which this dataSource then automatically 'inheritsFrom'
. This allows you to override auto-derived schema
as required. This property is only applicable if you are using the Smart GWT server.
autoDeriveSchema
- autoDeriveSchema Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getAutoDeriveSchema()
tableName
. This
causes Smart GWT to create a "super" DataSource, which this dataSource then automatically 'inheritsFrom'
. This allows you to override auto-derived schema
as required. This property is only applicable if you are using the Smart GWT server.
public void setServiceNamespace(String serviceNamespace) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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 String getSchemaNamespace() throws 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.
IllegalStateException
- if underlying component has not yet been created.public void setRecordXPath(String recordXPath) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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(String dataURL) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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(String tagName) throws IllegalStateException
dataSource.ID
will be used.
Note : This is an advanced setting
tagName
- tagName Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getTagName()
dataSource.ID
will be used.
public void setClientOnly(Boolean clientOnly) throws IllegalStateException
See 'this discussion'
for ways to populate a client-only DataSource with
test data.
clientOnly
- clientOnly Default value is false
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getClientOnly()
See 'this discussion'
for ways to populate a client-only DataSource with
test data.
public void setCriteriaPolicy(CriteriaPolicy criteriaPolicy)
ResultSet
cache should be dropped when the criteria
changes.
Note : This is an advanced setting
criteriaPolicy
- criteriaPolicy Default value is "dropOnShortening"public CriteriaPolicy getCriteriaPolicy()
ResultSet
cache should be dropped when the criteria
changes.
public void setUseLocalValidators(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 Boolean getUseLocalValidators()
Disabling client-side validation entirely is a good way to test server-side validation.
public void setShowPrompt(Boolean showPrompt)
showPrompt
if it's unset.
showPrompt
- showPrompt Default value is truepublic Boolean getShowPrompt()
showPrompt
if it's unset.
public void setEnumTranslateStrategy(EnumTranslateStrategy enumTranslateStrategy) throws IllegalStateException
Note : This is an advanced setting
enumTranslateStrategy
- enumTranslateStrategy Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setEnumConstantProperty(String enumConstantProperty) throws IllegalStateException
EnumTranslateStrategy
is set to "bean". Defaults to "_constant" if
not set. This property is only applicable if you are using the Smart GWT server
Note : This is an advanced setting
enumConstantProperty
- enumConstantProperty Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setEnumOrdinalProperty(String enumOrdinalProperty) throws IllegalStateException
EnumTranslateStrategy
is set to "bean". Defaults to "_ordinal" if
not set. This property is only applicable if you are using the Smart GWT server
Note : This is an advanced setting
enumOrdinalProperty
- enumOrdinalProperty Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setAutoDeriveTitles(Boolean autoDeriveTitles) throws IllegalStateException
'field.name'
for
any field that does not have a 'field.title'
and is not
marked 'hidden'
:true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle
.
autoDeriveTitles
- autoDeriveTitles Default value is true
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getAutoDeriveTitles()
'field.name'
for
any field that does not have a 'field.title'
and is not
marked 'hidden'
:true, by calling the method com.smartgwt.client.data.DataSource#getAutoTitle
.
public void setCanMultiSort(Boolean canMultiSort) throws IllegalStateException
canMultiSort
- canMultiSort Default value is true
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getCanMultiSort()
public void setRequiresAuthentication(Boolean requiresAuthentication) throws IllegalStateException
operationBindings
within the
DataSource may still override this setting by explicitly setting requiresAuthentication
. Whether the user
is authenticated is determined by calling httpServletRequest.getRemoteUser()
, hence works with both simple
J2EE security (realms and form-based authentication) and JAAS (Java Authentication & Authorization Service).
If you
wish to use an authentication scheme that does not make use of the servlet API's standards, Smart GWT Server also
implements the setAuthenticated
method on RPCManager
. You can use this API to tell Smart GWT
that all the requests in the queue currently being processed are associated with an authenticated user; in this case,
Smart GWT will not attempt to authenticate the user via httpServletRequest.getRemoteUser()
You can set the default value for this property via setting "authentication.defaultRequired" in server.properties. This allows you to, for example, cause all DataSources to require authentication for all operations by default.
Note that setting
this property does not automatically cause an authentication mechanism to appear - you still need to separately
configure an authentication system. Likewise, setting requiresAuthentication="false" does not automatically allow users
to bypass your authentication mechanism - you need to set up a URL that will accept DSRequests and process them similar
to the default "IDACall" servlet, and which is not protected by the authentication system. See 'Deploying Smart GWT'
for details on the IDACall servlet.
requiresAuthentication
- requiresAuthentication Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getRequiresAuthentication()
operationBindings
within the
DataSource may still override this setting by explicitly setting requiresAuthentication
. Whether the user
is authenticated is determined by calling httpServletRequest.getRemoteUser()
, hence works with both simple
J2EE security (realms and form-based authentication) and JAAS (Java Authentication & Authorization Service).
If you
wish to use an authentication scheme that does not make use of the servlet API's standards, Smart GWT Server also
implements the setAuthenticated
method on RPCManager
. You can use this API to tell Smart GWT
that all the requests in the queue currently being processed are associated with an authenticated user; in this case,
Smart GWT will not attempt to authenticate the user via httpServletRequest.getRemoteUser()
You can set the default value for this property via setting "authentication.defaultRequired" in server.properties. This allows you to, for example, cause all DataSources to require authentication for all operations by default.
Note that setting
this property does not automatically cause an authentication mechanism to appear - you still need to separately
configure an authentication system. Likewise, setting requiresAuthentication="false" does not automatically allow users
to bypass your authentication mechanism - you need to set up a URL that will accept DSRequests and process them similar
to the default "IDACall" servlet, and which is not protected by the authentication system. See 'Deploying Smart GWT'
for details on the IDACall servlet.
public void setRequiresRole(String requiresRole) throws IllegalStateException
requiresRole
, but controls access to
the DataSource as a whole.
requiresRole
- requiresRole Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getRequiresRole()
requiresRole
, but controls access to
the DataSource as a whole.
public void setTitle(String title)
For example, for the supplyItem DataSource, "Supply Item".
Defaults to
dataSource.ID
.
title
- title Default value is dataSource.IDpublic String getTitle()
For example, for the supplyItem DataSource, "Supply Item".
Defaults to
dataSource.ID
.
public void setPluralTitle(String pluralTitle) throws IllegalStateException
For example, for the supplyItem DataSource, "Supply Items".
Defaults to (dataSource.title
or dataSource.ID
) + "s".
pluralTitle
- pluralTitle Default value is dataSource.ID
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getPluralTitle()
For example, for the supplyItem DataSource, "Supply Items".
Defaults to (dataSource.title
or dataSource.ID
) + "s".
public void setTitleField(String titleField) throws IllegalStateException
For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.
If not explicitly set, titleField looks for fields named "title", "label", "name", and "id" in that order. If a field exists with one of those names, it becomes the titleField. If not, then the first field is designated as the titleField.
titleField
- titleField Default value is see below
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getTitleField()
For example, for a DataSource of employees, a "full name" field would probably most clearly label an employee record.
If not explicitly set, titleField looks for fields named "title", "label", "name", and "id" in that order. If a field exists with one of those names, it becomes the titleField. If not, then the first field is designated as the titleField.
public void setIconField(String iconField) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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(String childrenField) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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(String serverConstructor) throws 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.BasicDataSource
. If your implementation relies on methods or state only present
in certain specialized subclasses of DataSource (for example, you want the normal behavior and features of a
HibernateDataSource, but with a specialized validate() method), then you shoud extend the subclass rather than the base
class.
serverConstructor
- serverConstructor Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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.BasicDataSource
. If your implementation relies on methods or state only present
in certain specialized subclasses of DataSource (for example, you want the normal behavior and features of a
HibernateDataSource, but with a specialized validate() method), then you shoud extend the subclass rather than the base
class.
public void setQualifyColumnNames(Boolean qualifyColumnNames) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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 setValidateRelatedRecords(Boolean validateRelatedRecords) throws IllegalStateException
com.smartgwt.client..ValidatorTypes#hasRelatedRecord
validator to every field on this dataSource that has a 'foreignKey'
defined.
validateRelatedRecords
- validateRelatedRecords Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic Boolean getValidateRelatedRecords()
com.smartgwt.client..ValidatorTypes#hasRelatedRecord
validator to every field on this dataSource that has a 'foreignKey'
defined.
public void setBeanClassName(String beanClassName) throws IllegalStateException
'serverType'
: For DataSources with serverType "hibernate"
The name of the Java bean or POJO class that
is mapped in Hibernate. This will typically be the fully-qualified class name - eg com.foo.MyClass
- but
it may be the simple class name - just MyClass
- or it may be some other value. It all depends on how
your classes have been mapped in Hibernate.
Note: If you are intending to use Hibernate as a data-access layer only, you do not need to create Hibernate mappings or Java objects: Smart GWT will generate everything it needs on the fly.
For DataSources with serverType "sql"
If set, results from the database will be used to create one
instance of the indicated Java bean per database row. Otherwise a Map is used to represent each row retrieved from SQL.
With this feature active, a DSResponse from this DataSource will contain a Collection of instances of the indicated
beanClassName
, available via DSResponse.getData(). This creates a couple of possibilities:
com.smartgwt.client..DMI
method that calls DSRequest.execute() to retrieve a DSResponse, you have an opportunity to
call business logic methods on the beans representing each row affected by the DSRequest. For example, notify a related
BPEL process of changes to certain fields. By using beanClassName
on a specific OperationBinding
, you can:
Note that setting
beanClassName
has no effect on the DSRequest. However, com.smartgwt.client..DMI
has a built-in
facility for populating a bean with the inbound data
- just declare
the bean as a method argument.
For DataSources with serverType "generic"
'Visual Builder'
sets this property when it creates a generic DataSource using
the Javabean Wizard. It has no built-in server-side effects.
beanClassName
- beanClassName Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic String getBeanClassName()
'serverType'
: For DataSources with serverType "hibernate"
The name of the Java bean or POJO class that
is mapped in Hibernate. This will typically be the fully-qualified class name - eg com.foo.MyClass
- but
it may be the simple class name - just MyClass
- or it may be some other value. It all depends on how
your classes have been mapped in Hibernate.
Note: If you are intending to use Hibernate as a data-access layer only, you do not need to create Hibernate mappings or Java objects: Smart GWT will generate everything it needs on the fly.
For DataSources with serverType "sql"
If set, results from the database will be used to create one
instance of the indicated Java bean per database row. Otherwise a Map is used to represent each row retrieved from SQL.
With this feature active, a DSResponse from this DataSource will contain a Collection of instances of the indicated
beanClassName
, available via DSResponse.getData(). This creates a couple of possibilities:
com.smartgwt.client..DMI
method that calls DSRequest.execute() to retrieve a DSResponse, you have an opportunity to
call business logic methods on the beans representing each row affected by the DSRequest. For example, notify a related
BPEL process of changes to certain fields. By using beanClassName
on a specific OperationBinding
, you can:
Note that setting
beanClassName
has no effect on the DSRequest. However, com.smartgwt.client..DMI
has a built-in
facility for populating a bean with the inbound data
- just declare
the bean as a method argument.
For DataSources with serverType "generic"
'Visual Builder'
sets this property when it creates a generic DataSource using
the Javabean Wizard. It has no built-in server-side effects.
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(Boolean strictSQLFiltering) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic 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 Smart GWT right after this method completes.
addHandleErrorHandler
in interface HasHandleErrorHandlers
handler
- the handleError handler
HandlerRegistration
used to remove this handlerpublic DataSourceField getField(String fieldName)
fieldName
- Name of the field to retrieve
public DataSourceField getPrimaryKeyField()
public String getPrimaryKeyFieldName()
public void supportsTextMatchStyle(TextMatchStyle textMatchStyle)
textMatchStyle
- textMatchStyle to check. If passed a null value, assume an exact match is being requested.public static DataSource getDataSource(String ID)
ID
- DataSource ID
public static DataSource get(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 IllegalStateException
dataProtocol
}
dataProtocol
- dataProtocol Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setDefaultParams(Map defaultParams)
defaultParams
- the default paramspublic Map getDefaultParams()
public DSProtocol getDataProtocol()
dataProtocol
}
protected Object transformRequest(DSRequest dsRequest)
dsRequest
- the DSRequest being processed
protected void transformResponse(DSResponse response, DSRequest request, 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 JavaScriptObject getJsObj()
getJsObj
in class BaseClass
public void setRequestProperties(DSRequest requestProperties) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setInheritsFrom(DataSource inheritsFrom) throws 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 and have the
best possible chance of working with future versions of the "employee"dataSource.
inheritsFrom
- the datasource to inherit from
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setFields(DataSourceField... fields) throws IllegalStateException
Each DataSource field can have type, user-visible title, validators, and other metadata attached.
fields
- fields Default value is null
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void addField(DataSourceField field) throws IllegalStateException
field
- the datasource field
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic DataSourceField[] getFields()
Each DataSource field can have type, user-visible title, validators, and other metadata attached.
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 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setRecordName(String recordName) throws 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
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void setXmlNamespaces(XmlNamespaces xmlNamespaces) throws IllegalStateException
xmlNamespaces
- xml namespaces
IllegalStateException
- this property cannot be changed after the underlying component has been createdpublic void fetchData()
In contrast to ListGrid.fetchData()
, which creates a ResultSet
to manage the returned data, calling dataSource.fetchData()
provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects. Calling
dataSource.fetchData()
does not automatically update any visual components or caches: code in the
callback passed to fetchData()
decides what to do with the returned data.
For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:
isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");Unlike calling
myGrid.fetchData()
, which creates a ResultSet
, the data
provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of
HTML's multi-select component. Disconnected datasets may be used to populate various visual components. For
example, while an individual FormItem can be configured to fetch valueMap
options from a DataSource via the optionDataSource
property, the following code shows storing a dataset to derive valueMaps from later:
isc.DataSource.get("countries").fetchData(null, "window.countries = data"); ... later, a form is created dynamically ... function showForm() { isc.DynamicForm.create({ items : [ { name:"country", title:"Pick Country", valueMap: window.countries.getValueMap("countryId", "countryName") }, ...
You can also create a ResultSet from the data retrieved from
fetchData()
, like so:
isc.DataSource.get("countries").fetchData(null, function (dsResponse, data) { isc.ResultSet.create({ dataSource:"countries", allRows:data }) } )
This gives you a dataset that supports client-side filtering
(via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
), can provide ResultSet.getValueMap(java.lang.String, java.lang.String)
, will disableCacheSync
to the DataSource made via other components, and can be re-used with multiple visual
components.
See also the server-side com.isomorphic.js.JSTranslater class in the
${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
involving dumping data into the page during initial page load. Note: care should be taken when using this
approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource
and similar facilities to manage datasets
that may become very large.
Data-Driven Visual Component Creation
DataSource.fetchData()
can also be used to create Smart GWT components in a data-driven way. Many
properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
dataSource.fetchData()
returns. These include fields
, tabs
, items
, values
and even fields
.
For example, if you had a DataSource
"myFormFields" whose fields included the basic properties of FormItem
(name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
the "myFormFields" DataSource on the fly:
isc.DataSource.get("myFormFields").fetchData(null, "isc.DynamicForm.create({ items:data })" )This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also
inheritsFrom
.
public void fetchData(Criteria criteria)
In contrast to ListGrid.fetchData()
, which creates a ResultSet
to manage the returned data, calling dataSource.fetchData()
provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects. Calling
dataSource.fetchData()
does not automatically update any visual components or caches: code in the
callback passed to fetchData()
decides what to do with the returned data.
For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:
isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");Unlike calling
myGrid.fetchData()
, which creates a ResultSet
, the data
provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of
HTML's multi-select component. Disconnected datasets may be used to populate various visual components. For
example, while an individual FormItem can be configured to fetch valueMap
options from a DataSource via the optionDataSource
property, the following code shows storing a dataset to derive valueMaps from later:
isc.DataSource.get("countries").fetchData(null, "window.countries = data"); ... later, a form is created dynamically ... function showForm() { isc.DynamicForm.create({ items : [ { name:"country", title:"Pick Country", valueMap: window.countries.getValueMap("countryId", "countryName") }, ...
You can also create a ResultSet from the data retrieved from
fetchData()
, like so:
isc.DataSource.get("countries").fetchData(null, function (dsResponse, data) { isc.ResultSet.create({ dataSource:"countries", allRows:data }) } )
This gives you a dataset that supports client-side filtering
(via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
), can provide ResultSet.getValueMap(java.lang.String, java.lang.String)
, will disableCacheSync
to the DataSource made via other components, and can be re-used with multiple visual
components.
See also the server-side com.isomorphic.js.JSTranslater class in the
${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
involving dumping data into the page during initial page load. Note: care should be taken when using this
approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource
and similar facilities to manage datasets
that may become very large.
Data-Driven Visual Component Creation
DataSource.fetchData()
can also be used to create Smart GWT components in a data-driven way. Many
properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
dataSource.fetchData()
returns. These include fields
, tabs
, items
, values
and even fields
.
For example, if you had a DataSource
"myFormFields" whose fields included the basic properties of FormItem
(name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
the "myFormFields" DataSource on the fly:
isc.DataSource.get("myFormFields").fetchData(null, "isc.DynamicForm.create({ items:data })" )This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also
inheritsFrom
.
criteria
- search criteriapublic void fetchData(Criteria criteria, DSCallback callback)
In contrast to ListGrid.fetchData()
, which creates a ResultSet
to manage the returned data, calling dataSource.fetchData()
provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects. Calling
dataSource.fetchData()
does not automatically update any visual components or caches: code in the
callback passed to fetchData()
decides what to do with the returned data.
For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:
isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");Unlike calling
myGrid.fetchData()
, which creates a ResultSet
, the data
provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of
HTML's multi-select component. Disconnected datasets may be used to populate various visual components. For
example, while an individual FormItem can be configured to fetch valueMap
options from a DataSource via the optionDataSource
property, the following code shows storing a dataset to derive valueMaps from later:
isc.DataSource.get("countries").fetchData(null, "window.countries = data"); ... later, a form is created dynamically ... function showForm() { isc.DynamicForm.create({ items : [ { name:"country", title:"Pick Country", valueMap: window.countries.getValueMap("countryId", "countryName") }, ...
You can also create a ResultSet from the data retrieved from
fetchData()
, like so:
isc.DataSource.get("countries").fetchData(null, function (dsResponse, data) { isc.ResultSet.create({ dataSource:"countries", allRows:data }) } )
This gives you a dataset that supports client-side filtering
(via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
), can provide ResultSet.getValueMap(java.lang.String, java.lang.String)
, will disableCacheSync
to the DataSource made via other components, and can be re-used with multiple visual
components.
See also the server-side com.isomorphic.js.JSTranslater class in the
${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
involving dumping data into the page during initial page load. Note: care should be taken when using this
approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource
and similar facilities to manage datasets
that may become very large.
Data-Driven Visual Component Creation
DataSource.fetchData()
can also be used to create Smart GWT components in a data-driven way. Many
properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
dataSource.fetchData()
returns. These include fields
, tabs
, items
, values
and even fields
.
For example, if you had a DataSource
"myFormFields" whose fields included the basic properties of FormItem
(name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
the "myFormFields" DataSource on the fly:
isc.DataSource.get("myFormFields").fetchData(null, "isc.DynamicForm.create({ items:data })" )This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also
inheritsFrom
.
criteria
- search criteriacallback
- callback to invoke on completionpublic void fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
In contrast to ListGrid.fetchData()
, which creates a ResultSet
to manage the returned data, calling dataSource.fetchData()
provides the returned data in the callback as a simple JavaScript Array of JavaScript Objects. Calling
dataSource.fetchData()
does not automatically update any visual components or caches: code in the
callback passed to fetchData()
decides what to do with the returned data.
For example, given a ListGrid "myGrid" and a DataSource "employees", the following code would populate "myGrid" with data fetched from the DataSource:
isc.DataSource.get("employees").fetchData(null, "myGrid.setData(data)");Unlike calling
myGrid.fetchData()
, which creates a ResultSet
, the data
provided to the grid is "disconnected" data, unmanaged by Smart GWT's databinding facilities and safe to
directly modify. This is useful when, for example, a ListGrid is being used as a more sophisticated version of
HTML's multi-select component. Disconnected datasets may be used to populate various visual components. For
example, while an individual FormItem can be configured to fetch valueMap
options from a DataSource via the optionDataSource
property, the following code shows storing a dataset to derive valueMaps from later:
isc.DataSource.get("countries").fetchData(null, "window.countries = data"); ... later, a form is created dynamically ... function showForm() { isc.DynamicForm.create({ items : [ { name:"country", title:"Pick Country", valueMap: window.countries.getValueMap("countryId", "countryName") }, ...
You can also create a ResultSet from the data retrieved from
fetchData()
, like so:
isc.DataSource.get("countries").fetchData(null, function (dsResponse, data) { isc.ResultSet.create({ dataSource:"countries", allRows:data }) } )
This gives you a dataset that supports client-side filtering
(via ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
), can provide ResultSet.getValueMap(java.lang.String, java.lang.String)
, will disableCacheSync
to the DataSource made via other components, and can be re-used with multiple visual
components.
See also the server-side com.isomorphic.js.JSTranslater class in the
${isc.DocUtils.linkForDocNode('javaServerReference', 'Java Server Reference')} for other, similar approaches
involving dumping data into the page during initial page load. Note: care should be taken when using this
approach. Large datasets degrade the basic performance of some browsers, so use optionDataSource
and similar facilities to manage datasets
that may become very large.
Data-Driven Visual Component Creation
DataSource.fetchData()
can also be used to create Smart GWT components in a data-driven way. Many
properties on Smart GWT visual components are configured via an Array of Objects - the same data format that
dataSource.fetchData()
returns. These include fields
, tabs
, items
, values
and even fields
.
For example, if you had a DataSource
"myFormFields" whose fields included the basic properties of FormItem
(name, title, type, etc), this example code would create a form based on stored field definitions, loaded from
the "myFormFields" DataSource on the fly:
isc.DataSource.get("myFormFields").fetchData(null, "isc.DynamicForm.create({ items:data })" )This capability to dynamically create visual components from dynamically fetched data provides a foundation for creating interfaces that can be customized by end users. See also
inheritsFrom
.
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 String xmlSerialize(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 Smart GWT reported
in log statements in the Developer Console.
data
- data to be serialized
public String xmlSerialize(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 Smart GWT reported
in log statements in the Developer Console.
data
- data to be serializedflags
- options for the serialization engine
public void processResponse(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 objectresponseProperties
- Configuration for the dsResponsepublic Record[] recordsFromXML(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)
public String[] getFieldNames()
public String[] getFieldNames(boolean excludeHidden)
excludeHidden
- If true, returns only those fields that are not marked as hidden
public void downloadFile(Record data)
This will trigger the browser's "Save As" dialog and allow the user to save the file.
data
- primary key values of record containing the file to download (or the complete record)public void downloadFile(Record data, String fieldName, DSRequest requestProperties)
This will trigger the browser's "Save As" dialog and allow the user to save the file.
data
- primary key values of record containing the file to download (or
the complete record)fieldName
- optional name of the binary field containing the file. If not provided, the
first binary field is usedrequestProperties
- additional properties to set on the DSRequest that will be issuedpublic void viewFile(Record data)
This will open a new browser window to show the file. Depending on the file type, the user's installed plugins and applications, and the user's browser settings, this may cause the file to be actually displayed in the new browser window, or may prompt the user to either launch an external application to view the file or save the file to disk.
data
- primary key values of record containing the file to view (or the complete record)public void viewFile(Record data, String fieldName, DSRequest requestProperties)
This will open a new browser window to show the file. Depending on the file type, the user's installed plugins and applications, and the user's browser settings, this may cause the file to be actually displayed in the new browser window, or may prompt the user to either launch an external application to view the file or save the file to disk.
data
- primary key values of record containing the file to view (or the
complete record)fieldName
- optional name of the binary field containing the file. If not provided, the
first binary field is usedrequestProperties
- additional properties to set on the DSRequest that will be issuedpublic static void load(String dsID, Function callback, boolean forceReload)
To force reloading of DataSources that have already been loaded, pass
true
in the forceReload parameter.
dsID
- DataSource IDcallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loadedpublic static void load(String[] dsID, Function callback, boolean forceReload)
To force reloading of DataSources that have already been loaded, pass
true
in the forceReload parameter.
dsID
- Array of DataSource IDscallback
- Callback to fire after DataSource loading completesforceReload
- Forcibly reload a dataSource if it's already loadedpublic static String[] getSortBy(String[] sortSpecifiers)
sortBy
.
sortSpecifiers
- The list of specifiers to return in sortBy format
sortBy
public static String[] getSortSpecifiers(String[] sortBy)
sortBy
.
sortBy
- A list of sortBy strings in the format expected by sortBy
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |