com.smartgwt.client.docs.serverds

## Class DataSource

- java.lang.Object
- - com.smartgwt.client.docs.serverds.DataSource

-     public class DataSource
      extends java.lang.Object

  This class is not meant to be created and used, it is actually documentation of settings allowed in a DataSource descriptor (.ds.xml file). See `com.smartgwt.client.docs.serverds` for how to use this documentation.

  A DataSource is data-provider-independent description of a set of objects that will be loaded, edited and saved within the user interface of your application.

  Each DataSource consists of a list of `fields` that make up a DataSource `record`, along with `field types`, `validation rules`, `relationships` to other DataSources, and other metadata.

  The abstract object description provided by a DataSource is easily mapped to a variety of backend object models and storage schemes. The following table shows analogous terminology across systems.

  Isomorphic Smart GWT | Relational Database | Enterprise Java Beans (EJB) | Entity/Relationship Modeling | OO/UML | XML Schema/WSDL | LDAP
  DataSource | Table | EJB class | Entity | Class | Element Schema (ComplexType) | Objectclass
  Record | Row | EJB instance | Entity instance | Class instance/Object | Element instance (ComplexType) | Entry
  Field | Column | Property | Attribute | Property/Attribute | Attribute or Element (SimpleType) | Attribute

  DataSources can be `declared` in either JavaScript or XML format, and can also be `imported` from existing metadata formats, including XML Schema.

  Data Binding is the process by which `Data Binding-capable UI components` can automatically configure themselves for viewing, editing and saving data described by DataSources. DataBinding is covered in the 'QuickStart Guide', Chapter 6, Data Binding.

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

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

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

  See Also:
    `DataBoundComponent`, `ClientOnlyDataSources overview and related methods`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `java.lang.Boolean` | `allowAdvancedCriteria` By default, all DataSources are assumed to be capable of handling `AdvancedCriteria` on fetch or filter type operations.
    `java.lang.Boolean` | `autoConvertRelativeDates` Whether to convert relative date values to concrete date values before sending to the server.
    `java.lang.Boolean` | `autoDeriveSchema` This property allows you to specify that your DataSource's schema (field definitions) should be automatically derived from some kind of metadata.
    `boolean` | `autoDeriveTitles` If set, titles are automatically derived from `field.name` for any field that does not have a `field.title` and is not marked `hidden`:true, by calling the method `DataSource.getAutoTitle`.
    `java.lang.Boolean` | `autoJoinTransactions` If true, causes all operations on this DataSource to automatically start or join a transaction; this means that multiple operations sent to the server in a `request queue` will be committed in a single transaction.
    `java.lang.String` | `beanClassName` This property has different meanings depending on the `serverType`:
    `java.lang.String` | `callbackParam` Applies only to dataFormat: "json" and `dataTransport`:"scriptInclude".
    `boolean` | `canMultiSort` When true, indicates that this DataSource supports multi-level sorting.
    `java.lang.String` | `childrenField` fieldName for a field in the dataSource expected to contain an explicit array of child nodes.
    `java.lang.Boolean` | `clientOnly` A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as `DSRequests` are executed on it.
    `java.lang.String` | `configBean` For DataSources of `serverType` "hibernate", the name of a Spring bean to query to obtain Hibernate Configuration for this particular DataSource.
    `java.lang.Boolean` | `creatorOverrides` Indicates that declarative security rules are waived for rows that were created by the current user.
    `CriteriaPolicy` | `criteriaPolicy` Decides under what conditions the `ResultSet` cache should be dropped when the `criteria` changes.
    `java.lang.String` | `dataField` Name of the field that has the most pertinent numeric, date, or enum value, for use when a `DataBoundComponent` needs to show a short summary of a record.
    `DSDataFormat` | `dataFormat` Indicates the format to be used for HTTP requests and responses when fulfilling DSRequests (eg, when `DataSource.fetchData` is called).
    `RPCTransport` | `dataTransport` Transport to use for all operations on this DataSource.
    `java.lang.String` | `dataURL` Default URL to contact to fulfill all DSRequests.
    `java.lang.String` | `dbName` For DataSources using the `Smart GWT SQL engine` for persistence, which database configuration to use.
    `java.lang.String` | `descriptionField` Name of the field that has a long description of the record, or has the primary text data value for a record that represents an email message, SMS, log or similar.
    `java.lang.Boolean` | `dropExtraFields` Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.
    `int` | `endGap` If we are `loading progressively`, indicates the number of extra records Smart GWT Server will advertise as being available, if it detects that there are more records to view (see `lookAhead`).
    `java.lang.String` | `enumConstantProperty` The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean".
    `java.lang.String` | `enumOrdinalProperty` The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean".
    `EnumTranslateStrategy` | `enumTranslateStrategy` Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript.
    `DataSourceField[]` | `fields` The list of fields that compose records from this DataSource.
    `java.lang.Object` | `globalNamespaces` Namespaces definitions to add to the root element of outbound XML messages sent to a web service, as a mapping from namespace prefix to namespace URI.
    `java.lang.String` | `iconField` Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.
    `java.lang.String` | `ID` Unique identifier for this DataSource.
    `java.lang.String` | `idClassName` For JPA and Hibernate DataSources this property indicates, that data source has composite primary key and specifies fully-qualified Java class: with `@EmbeddedId` you have to specify class name of declared id with `@IdClass` you have to specify class specified in annotation declaration
    `java.lang.String` | `infoField` Name of the field that has the second most pertinent piece of textual information in the record, for use when a `DataBoundComponent` needs to show a short summary of a record.
    `DSInheritanceMode` | `inheritanceMode` For dataSources of `serverType` "sql" only, specifies the inheritance mode to use.
    `java.lang.String` | `inheritsFrom` ID of another DataSource this DataSource inherits its `fields` from.
    `java.lang.String` | `jsonPrefix` Allows you to specify an arbitrary prefix string to apply to all json format responses sent from the server to this application.
    `java.lang.String` | `jsonSuffix` Allows you to specify an arbitrary suffix string to apply to all json format responses sent from the server to this application.
    `int` | `lookAhead` If we are `loading progressively`, indicates the number of extra records Smart GWT Server will read beyond the end record requested by the client, in order to establish if there are more records to view.
    `boolean` | `noNullUpdates` When true, indicates that fields in this DataSource will never be positively updated to the null value; they may arrive at null values by being omitted, but we will not send actual null values in update requests.
    `boolean` | `nullBooleanValue` If `noNullUpdates` is set, the value to use for any boolean field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.
    `Date` | `nullDateValue` If `noNullUpdates` is set, the value to use for any date or time field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.
    `float` | `nullFloatValue` If `noNullUpdates` is set, the value to use for any float field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.
    `int` | `nullIntegerValue` If `noNullUpdates` is set, the value to use for any integer field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.
    `java.lang.String` | `nullStringValue` If `noNullUpdates` is set, the value to use for any text field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.
    `boolean` | `omitNullDefaultsOnAdd` When true, and `noNullUpdates` is also true, indicates that "add" requests on this DataSource will have null-valued fields removed from the request entirely before it is sent to the server, as opposed to the default behavior of replacing such null values with defaults.
    `OperationBinding[]` | `operationBindings` Optional array of OperationBindings, which provide instructions to the DataSource about how each DSOperation is to be performed.
    `java.lang.String` | `pluralTitle` User-visible plural name for this DataSource.
    `java.lang.Boolean` | `preventHTTPCaching` If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.
    `java.lang.Boolean` | `progressiveLoading` If true, causes Smart GWT Server to use the "progressive loading" pattern for fetches on this dataSource, as described in the Paging and total dataset length section of the `ResultSet documentation`.
    `int` | `progressiveLoadingThreshold` Indicates the dataset size that will cause Smart GWT Server to automatically switch into `progressive loading mode` for this DataSource.
    `java.lang.Boolean` | `qualifyColumnNames` For dataSources of `serverType` "sql", determines whether we qualify column names with table names in any SQL we generate.
    `java.lang.Boolean` | `quoteColumnNames` If set, tells the SQL engine to quote column names in all generated DML and DDL statements for this dataSource.
    `XPathExpression` | `recordXPath` See `recordXPath`.
    `DSRequest` | `requestProperties` Additional properties to pass through to the `DSRequest`s made by this DataSource.
    `VelocityExpression` | `requires` Indicates that the specified VelocityExpression must evaluate to true for a user to access this DataSource.
    `java.lang.Boolean` | `requiresAuthentication` Whether a user must be authenticated in order to access this DataSource.
    `java.lang.String` | `requiresRole` Similar to `requiresRole`, but controls access to the DataSource as a whole.
    `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.
    `java.lang.Object` | `resultSetClass` Class for ResultSets used by this datasource.
    `java.lang.String` | `schema` This property only applies to the built-in SQL DataSource provided in Pro and better editions of Smart GWT
    `java.lang.String` | `schemaBean` For DataSources that specify `autoDeriveSchema`, this property indicates the name of the Spring bean, Hibernate mapping or fully-qualified Java class to use as parent schema.
    `java.lang.String` | `schemaNamespace` For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to.
    `java.lang.Boolean` | `sendExtraFields` Analogous to `dropExtraFields`, for data sent to the server.
    `java.lang.String` | `serverConstructor` This property allows you to write and use custom DataSource subclasses on the server, by specifying either the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource, or the token "spring:" followed by a valid Spring bean ID, if you wish to instantiate your custom dataSource object using Spring dependency injection.
    `ServerObject` | `serverObject` For Direct Method Invocation (DMI) binding, declares the ServerObject to use as the default target for all `operationBindings`.
    `DSServerType` | `serverType` For a DataSource stored in .xml format on the Smart GWT server, indicates what server-side connector to use to execute requests, that is, what happens if you call dsRequest.execute() in server code.
    `java.lang.String` | `serviceNamespace` For an XML DataSource, URN of the WebService to use to invoke operations.
    `java.lang.Boolean` | `showLocalFieldsOnly` For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that only the fields listed in this DataSource should be shown.
    `java.lang.Boolean` | `showPrompt` Whether RPCRequests sent by this DataSource should enable `showPrompt` in order to block user interactions until the request completes.
    `boolean` | `sparseUpdates` When true, indicates that any updates for this DataSource include only those fields that have actually changed (and primaryKey fields); when false (the default), all field values are included in updates, whether they have changed or not
    `SQLPagingStrategy` | `sqlPaging` The paging strategy to use for this DataSource.
    `java.lang.Boolean` | `sqlUsePagingHint` If explicitly set true or left null, causes the server to use a "hint" in the SQL we generate for paged queries.
    `java.lang.Boolean` | `strictSQLFiltering` If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.
    `java.lang.String` | `tableCode` Only applicable to the built-in SQL DataSource
    `java.lang.String` | `tableName` For DataSources using the `Smart GWT SQL engine` for persistence, what database table name to use.
    `java.lang.String` | `tagName` Tag name to use when serializing to XML.
    `java.lang.String` | `title` User-visible name for this DataSource.
    `java.lang.String` | `titleField` Best field to use for a user-visible title for an individual record from this dataSource.
    `java.lang.Boolean` | `useAnsiJoins` For DataSources using the `Smart GWT SQL engine` for persistence, whether to use ANSI-style joins (ie, joins implemented with JOIN directives in the table clause, as opposed to additional join expressions in the where clause).
    `java.lang.Boolean` | `useFlatFields` Like `useFlatFields`, but applies to all DataBound components that bind to this DataSource.
    `java.lang.Boolean` | `useLocalValidators` Whether to attempt validation on the client at all for this DataSource.
    `java.lang.Boolean` | `useOfflineStorage` Whether we store server responses for this DataSource into `browser-based offline storage`, and then use those stored responses at a later time if we are offline (ie, the application cannot connect to the server).
    `java.lang.Boolean` | `useParentFieldOrder` For a DataSource that inherits `fields` from another DataSource (via `inheritsFrom`), indicates that the parent's field order should be used instead of the order of the fields as declared in this DataSource.
    `java.lang.Boolean` | `useSubselectForRowCount` This property is only applicable to `SQL` DataSources, and only for `operations` that express a `customSQL` clause.
    `java.lang.Object` | `xmlNamespaces` Sets the XML namespace prefixes available for XPaths on a DataSource-wide basied.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataSource()`

  - ### Method Summary

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### inheritsFrom

          public java.lang.String inheritsFrom

      ID of another DataSource this DataSource inherits its `fields` from.

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

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

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

      This feature can be used for:

      - creating a customized view (eg, only certain fields shown) which will be used by multiple `databound components`.
      - adding presentation-specific attributes to metadata that has been automatically derived from `XML Schema` or other metadata formats
      - modeling object subclassing and extension in server-side code and storage systems
      - modeling 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 any fields, and bind all `databound components` to "customizedEmployee". Customizations of fields (including appearance changes, field order, new fields, hiding of fields, and custom validation rules) can be added to "customizedEmployee", so that they are kept separately from the original field data and have the best possible chance of working with future versions of the "employee" dataSource.

      Default value is null

    - #### dataTransport

          public RPCTransport dataTransport

      Transport to use for all operations on this DataSource. Defaults to `defaultTransport`. This would typically only be set to enable "scriptInclude" transport for contacting `JSON` web services hosted on servers other than the origin server.

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

      Default value is RPCManager.defaultTransport

      See Also:
        `RPCTransport`, `callbackParam`, `ClientDataIntegration overview and related methods`

    - #### tableCode

          public java.lang.String tableCode

      Only applicable to the built-in SQL DataSource

      This read-only attribute is a secure and unique hashed version of the name of the table underlying this dataSource. It is used automatically by client-side framework code to link dataSources together by `foreign key`, by matching DataSource `tableCode`s with `fkTableCode`s. This is necessary if we automatically discovered a foreign key relationship by inspecting the database schema, as a result of a DataSource specifying `autoDeriveSchema`: true. We use a secure hash rather than the table name itself for security reasons - sending the actual table name to the client would be considered an information leakage that could encourage attempts at injection attacks.

      Default value is null

      See Also:
        `DataSourceField.fkTableCode`, `DataSourceField.fkColumnCode`

    - #### resultSetClass

          public java.lang.Object resultSetClass

      Class for ResultSets used by this datasource. If null, defaults to using `ResultSet`.

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

      Default value is null

    - #### progressiveLoading

          public java.lang.Boolean progressiveLoading

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

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

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

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

      Default value is null

      See Also:
        `OperationBinding.progressiveLoading`, `progressiveLoadingThreshold`, `lookAhead`, `endGap`, `ProgressiveLoading overview and related methods`

    - #### schema

          public java.lang.String schema

      This property only applies to the built-in SQL DataSource provided in Pro and better editions of Smart GWT

      Defines the name of the schema we use to qualify the `tableName` in generated SQL. If you do not provide this property, table names will not be qualified in generated SQL, and thus the default schema will be used. Support for multiple schemas (or schemata) varies quite significantly across the supported databases, as does the meaning of the phrase "default schema". In addition, some databases allow you to override the default schema in the JDBC connection URL, which is a preferable approach if all your tables are in the same (non-default) schema.

      The following table provides information by product:

      Product | Notes
      DB2 | Arbitrarily named schemas are supported. The default schema is named after the connecting user, though this can be overridden by specifying the "currentSchema" property on the JDBC connection URL
      DB2 for iSeries | Arbitrarily named schemas are supported. "Schema" is synonymous with "library". The default schema depends on the setting of the "naming" connection property. When this is set to "sql", behavior is similar to other DB2 editions: the default schema is named after the connecting user, unless overridden by specifying a library name in the JDBC connection URL. When "naming" is set to "system", the schema of an unqualified table is resolved using a traditional search of the library list; the library list can be provided in the "libraries" property
      Firebird | Firebird does not support the concept of schema at all - all "schema objects" like tables and indexes belong directly to the database. In addition, Firebird actively rejects qualified table names in queries as syntax errors; therefore, you should not set the `schema` property for a DataSource that will be backed by a Firebird database
      HSQLDB | Arbitrarily named schemas are supported. The default schema is auto-created when the database is created; by default it is called "PUBLIC", but can be renamed. It is not possible to set the default schema in the JDBC connection URL
      Informix | Informix databases can be flagged as "ANSI mode" at creation time. ANSI-mode databases behave similarly to DB2 for schema support: arbitrarily named schemas are supported, and the default schema is the one named after the connected user. Non-ANSI databases have no real schema support at all. It is not possible to set the default schema in the JDBC connection URL with either type of database
      Microsoft SQL Server | Prior to SQL Server 2005, schema support is similar to Oracle: "schema" is synonymous with "owner". As of SQL Server 2005, schema is supported as a separate concept, and a user's default schema can be configured (though it still defaults to a schema with the same name as the user). It is not possible to set the default schema in the JDBC connection URL
      MySQL | MySQL does not have a separate concept of "schema"; it treats the terms "schema" and "database" interchangeably. In fact MySQL databases actually behave more like schemas, in that a connection to database X can refer to a table in database Y simply by qualifying the name in the query. Also, because schema and database are the same concept in MySQL, overriding the "default schema" is done implicitly when you specify which database to connect to in your JDBC connection URL
      Oracle | Arbitrarily named schemas are not supported; in Oracle, "schema" is synonymous with "user", so each valid user in the database is associated implicitly with a schema of the same name, and there are no other schemas possible. It is possible to refer to tables in another user's schema (assuming you have the privileges to do so) by simply qualifying the table name. The default schema is always implied by the connecting user and cannot be overridden.
      Postgres | Arbitrarily named schemas are supported. Rather than the concept of a "default schema", Postgres supports the idea of a search path of schemas, whereby unqualified table references cause a search of the list of schemas in order, and the first schema in the path is the "current" one for creation purposes. Unfortunately, there is no way to specify this search path on the JDBC connection URL, so the default schema comes from the user definition, ultimately defaulting to the default "public" schema

      Default value is null

    - #### title

          public java.lang.String title

      User-visible name for this DataSource.

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

      Defaults to `dataSource.ID`.

      Default value is dataSource.ID

    - #### jsonSuffix

          public java.lang.String jsonSuffix

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

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

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

      Default value is null

      See Also:
        `OperationBinding.getDataFormat()`, `OperationBinding.getDataTransport()`

    - #### beanClassName

          public java.lang.String beanClassName

      This property has different meanings depending on the `serverType`:

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

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

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

      By using `beanClassName` on a specific `OperationBinding`, you can:

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

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

      For generic DataSources (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.

      For Hibernate DataSources (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 JPA DataSources (DataSources with serverType "jpa" or "jpa1")
      The fully qualified class name of the JPA annotated entity.

      NOTE for Hibernate and JPA users: When you use JPA, or use Hibernate as a full ORM system (ie, not just allowing Smart GWT Server to drive Hibernate as a data access layer), the beans returned on the server-side are live. This means that if you make any changes to them, the ORM system will persist those changes. This is true even if the beans were created as part of a fetch operation.

      This causes a problem in the common case where you want to use a DMI or custom DataSource implementation to apply some post-processing to the beans fetched from the persistent store. If you change the values in the beans directly, those changes will be persisted.

      If you want to alter the data returned from a JPA or Hibernate persistent store as part of a fetch request just so you can alter what gets sent to the client, you can use the server-side `DSResponse`'s `getRecords()` method. This will return your bean data in "record" format - ie, as a List of Maps. You can alter these records without affecting your persistent store, and then call `setData()` on the `DSResponseDSResponse` for details of these two methods.

      Default value is null

    - #### fields

          public DataSourceField[] fields

      The list of fields that compose records from this DataSource.

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

      Default value is null

      See Also:
        `DataSourceField`

    - #### useParentFieldOrder

          public java.lang.Boolean useParentFieldOrder

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

      Default value is null

    - #### sparseUpdates

          public boolean sparseUpdates

      When true, indicates that any updates for this DataSource include only those fields that have actually changed (and primaryKey fields); when false (the default), all field values are included in updates, whether they have changed or not

      Default value is false

    - #### creatorOverrides

          public java.lang.Boolean creatorOverrides

      Indicates that declarative security rules are waived for rows that were created by the current user. Practically, this means that when a security check fails, instead of a security exception being thrown, we alter the criteria to ensure that the request can only return or affect rows that were created by the current authenticated user. This allows you to create security regimes whereby users can see and edit data they created, but have access to other users' data forbidden or limited.

      In order for this to work, we require two things:

      - The DataSource must specify a field of type "creator" - this field type is described on `this page`
      - The authentication regime in use must include the idea of a "current user". The authentication provided by the Servlet API is an example of such a regime.
      This setting can be overridden at operationBinding and field level, allowing extremely fine-grained control.

      Default value is null

      See Also:
        `OperationBinding.creatorOverrides`, `DataSourceField.creatorOverrides`, `FieldLevelAuth overview and related methods`

    - #### jsonPrefix

          public java.lang.String jsonPrefix

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

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

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

      Default value is null

      See Also:
        `OperationBinding.getDataFormat()`, `OperationBinding.getDataTransport()`

    - #### operationBindings

          public OperationBinding[] operationBindings

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

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

      See Also:
        Java Integration samples.

        For DataSources bound to WSDL-described web services using {@link com.smartgwt.client.docs.serverds.DataSource#serviceNamespace serviceNamespace}, OperationBindings are used to bind each DataSource {@link com.smartgwt.client.docs.serverds.OperationBinding#operationType operationType} to an {@link com.smartgwt.client.data.OperationBinding#getWsOperation operation} of a WSDL-described {@link com.smartgwt.client.data.WebService web service}, so that a DataSource can both fetch and save data to a web service.

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

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

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

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

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

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

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

        Default value is null, `OperationBinding`

    - #### requiresAuthentication

          public java.lang.Boolean requiresAuthentication

      Whether a user must be authenticated in order to access this DataSource. This establishes a default for the DataSource as a whole; individual `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.

      Default value is null

    - #### xmlNamespaces

          public java.lang.Object xmlNamespaces

      Sets the XML namespace prefixes available for XPaths on a DataSource-wide basied. See `xmlNamespaces` for details.

      Default value is See below

      See Also:
        `ClientDataIntegration overview and related methods`

    - #### sendExtraFields

          public java.lang.Boolean sendExtraFields

      Analogous to `dropExtraFields`, for data sent to the server. Setting this attribute to false ensures that for any records in the data object, only fields that correspond to declared dataSource fields will be present on the dsRequest data object passed to `DataSource.transformRequest` and ultimately sent to the server.

      Default value is true

      See Also:
        `ClientDataIntegration overview and related methods`

    - #### dataURL

          public java.lang.String dataURL

      Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis via `dataURL`.

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

      Default value is null

      See Also:
        `ClientDataIntegration overview and related methods`

    - #### progressiveLoadingThreshold

          public int progressiveLoadingThreshold

      Indicates the dataset size that will cause Smart GWT Server to automatically switch into `progressive loading mode` for this DataSource. To prevent automatic switching to progressive loading, set this property to -1.

      Default value is 200000

      See Also:
        `progressiveLoading`, `ProgressiveLoading overview and related methods`

    - #### configBean

          public java.lang.String configBean

      For DataSources of `serverType` "hibernate", the name of a Spring bean to query to obtain Hibernate Configuration for this particular DataSource. Note that this is intended for DataSource-specific configuration overrides for unusual circumstances, such as a DataSource whose physical data store is a completely different database to that used by other DataSources. See the `Integration with Hibernate` article for more information

      Default value is null

      See Also:
        `ServerDataIntegration overview and related methods`

    - #### useLocalValidators

          public java.lang.Boolean useLocalValidators

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

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

      Default value is null

      See Also:
        `Validation overview and related methods`

    - #### autoDeriveTitles

          public boolean autoDeriveTitles

      If set, titles are automatically derived from `field.name` for any field that does not have a `field.title` and is not marked `hidden`:true, by calling the method `DataSource.getAutoTitle`.

      Default value is true

    - #### titleField

          public java.lang.String titleField

      Best field to use for a user-visible title for an individual record from this dataSource.

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

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

      Default value is see below

      See Also:
        `DsSpecialFields overview and related methods`

    - #### serverObject

          public ServerObject serverObject

      For Direct Method Invocation (DMI) binding, declares the ServerObject to use as the default target for all `operationBindings`. Specifying this attribute in an XML DataSource stored on the server enables DMI for this DataSource.

      Default value is null

      See Also:
        `ServerDataIntegration overview and related methods`

    - #### qualifyColumnNames

          public java.lang.Boolean qualifyColumnNames

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

      Default value is true

      See Also:
        `OperationBinding.qualifyColumnNames`

    - #### criteriaPolicy

          public CriteriaPolicy criteriaPolicy

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

      Default value is "dropOnShortening"

      See Also:
        `DataSource.compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)`

    - #### recordXPath

          public XPathExpression recordXPath

      See `recordXPath`. `recordXPath` can be specified directly on the DataSource for a simple read-only DataSource only capable of "fetch" operations.

      Default value is null

      See Also:
        `ClientDataIntegration overview and related methods`

    - #### sqlUsePagingHint

          public java.lang.Boolean sqlUsePagingHint

      If explicitly set true or left null, causes the server to use a "hint" in the SQL we generate for paged queries. If explicitly set false, forces off the use of hints. This property can be overridden per operationBinding - see `sqlUsePagingHint`.

      Note this property is only applicable to `SQL` DataSources, only when a `paging strategy` of "sqlLimit" is in force, and it only has an effect for those specific database products where we employ a native hint in the generated SQL in an attempt to improve performance.

      Default value is null

      See Also:
        `OperationBinding.sqlUsePagingHint`

    - #### schemaBean

          public java.lang.String schemaBean

      For DataSources that specify `autoDeriveSchema`, this property indicates the name of the Spring bean, Hibernate mapping or fully-qualified Java class to use as parent schema.

      Default value is null

      See Also:
        `autoDeriveSchema`

    - #### childrenField

          public java.lang.String childrenField

      fieldName for a field in the dataSource expected to contain an explicit array of child nodes. Enables loading a databound tree as a hierarchical data structure, rather than a flat list of nodes linked by foreignKey.
      Note this is an alternative to setting `childrenProperty` directly on the childrenField object.

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

                 <childrenFieldName>
                     <item name="firstChild" ...>
                     <item name="secondChild" ...>
                 </childrenFieldName>

      However data may also be delivered as a direct list of `childrenFieldName` elements:

                 <childrenFieldName name="firstChild" ...>
                 <childrenFieldName name="secondChild" ...>

      If you want to return your data in this format, you will need to explicitly set `multiple` to false in the appropriate dataSource field definition.

      Default value is null

      See Also:
        `DataSourceField.childrenProperty`, `DataSourceRelations overview and related methods`

    - #### useFlatFields

          public java.lang.Boolean useFlatFields

      Like `useFlatFields`, but applies to all DataBound components that bind to this DataSource.

      Default value is null

    - #### preventHTTPCaching

          public java.lang.Boolean preventHTTPCaching

      If set, the DataSource will ensure that it never uses a cached HTTP response, even if the server marks the response as cacheable.

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

      Default value is true

    - #### inheritanceMode

          public DSInheritanceMode inheritanceMode

      For dataSources of `serverType` "sql" only, specifies the inheritance mode to use. This property has no effect for any other type of DataSource.

      Default value is "full"

      See Also:
        `inheritsFrom`

    - #### quoteColumnNames

          public java.lang.Boolean quoteColumnNames

      If set, tells the SQL engine to quote column names in all generated DML and DDL statements for this dataSource. This will ensure that queries generated against tables that do not follow the database product's natural column-naming conventions will still work.

      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. This property may also be necessary if you are using field/column names that clash with reserved words in the underlying database (these vary by database, but a field called "date" or "timestamp" would have problems with most database products)

      Note: Only applicable to dataSources of `serverType` "sql".

      Default value is null

    - #### endGap

          public int endGap

      If we are `loading progressively`, indicates the number of extra records Smart GWT Server will advertise as being available, if it detects that there are more records to view (see `lookAhead`). This property has no effect if we are not progressive-loading.

      Default value is 20

      See Also:
        `progressiveLoading`, `lookAhead`, `ProgressiveLoading overview and related methods`

    - #### autoJoinTransactions

          public java.lang.Boolean autoJoinTransactions

      If true, causes all operations on this DataSource to automatically start or join a transaction; this means that multiple operations sent to the server in a `request queue` will be committed in a single transaction. Note that this includes fetch operations - setting this property to true has the same effect as a transaction policy of ALL for just this DataSource's operations - see the server-side `RPCManager.setTransactionPolicy()` for details of the different TransactionPolicy settings.

      If this property is explicitly false, this causes all operations on this DataSource to be committed individually - the same as a transaction policy of NONE, just for this DataSource's operations.

      In either case, you can override the setting for individual operations - see `autoJoinTransactions`.

      If this property if null or not defined, we fall back to the default setting for this type of DataSource. These are defined in `server.properties` as follows:

      - Hibernate:`hibernate.autoJoinTransactions`
      - JPA/JPA2:`jpa.autoJoinTransactions`
      - SQL: There is one setting per configured database connection (`dbName`). For example, the setting for the default MySQL connection is `sql.Mysql.autoJoinTransactions`
      If the setting is not defined at the DataSource-type level, we use the system global default, which is defined in `server.properties` as `autoJoinTransactions`.

      At the dbName and global system levels, you can set the autoJoinTransactions attribute to a valid Transaction Policy, rather than a simple true or false (although these values work too - true is the same as ALL, false is the same as NONE). For valid TransactionPolicy values and their meanings, see the server-side Javadoc for `RPCManager.setTransactionPolicy()`

      Note that the configuration settings discussed here can be overridden for a particular queue of requests by setting the server-side RPCManager's transaction policy. Look in the server-side Javadoc for `RPCManager.getTransactionPolicy()`.

      NOTE: Setting this property to true does not cause a transactional persistence mechanism to automatically appear - you have to ensure that your DataSource supports transactions. The Smart GWT built-in SQL, Hibernate and JPA DataSources support transactions, but note that they do so at the provider level. This means that you can combine updates to, say, an Oracle database and a MySQL database in the same queue, but they will be committed in two transactions - one per database. The Smart GWT server will commit or rollback these two transactions as if they were one, so a failure in some Oracle update would cause all the updates to both databases to be rolled back. However, this is not a true atomic transaction; it is possible for one transaction to be committed whilst the other is not - in the case of hardware failure, for example.

      NOTE: Not all the supported SQL databases are supported for transactions. Databases supported in this release are:

      - DB2
      - HSQLDB
      - Firebird
      - Informix
      - Microsoft SQL Server
      - MySQL (you must use InnoDB tables; the default MyISAM storage engine does not support transactions)
      - Oracle
      - PostgreSQL

      Default value is null

      See Also:
        `OperationBinding.autoJoinTransactions`

    - #### tagName

          public java.lang.String tagName

      Tag name to use when serializing to XML. If unspecified, the `dataSource.ID` will be used.

      Default value is null

      See Also:
        `ClientDataIntegration overview and related methods`

    - #### nullStringValue

          public java.lang.String nullStringValue

      If `noNullUpdates` is set, the value to use for any text field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.

      Default value is ""

      See Also:
        `noNullUpdates`, `com.smartgwt.client.docs.serverds.DataSourceField#nullReplacementValue`

    - #### descriptionField

          public java.lang.String descriptionField

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

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

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

      Default value is null

      See Also:
        `DsSpecialFields overview and related methods`

    - #### showLocalFieldsOnly

          public java.lang.Boolean showLocalFieldsOnly

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

      Default value is null

    - #### enumTranslateStrategy

          public EnumTranslateStrategy enumTranslateStrategy

      Sets the strategy this DataSource uses to translate Java enumerated types (objects of type enum) to and from Javascript. This property is only applicable if you are using the Smart GWT server

      Default value is null

    - #### allowAdvancedCriteria

          public java.lang.Boolean allowAdvancedCriteria

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

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

      Default value is null

      See Also:
        `OperationBinding.allowAdvancedCriteria`

    - #### infoField

          public java.lang.String infoField

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

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

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

      Default value is null

      See Also:
        `DsSpecialFields overview and related methods`

    - #### requiresRole

          public java.lang.String requiresRole

      Similar to `requiresRole`, but controls access to the DataSource as a whole.

      Default value is null

    - #### dataFormat

          public DSDataFormat dataFormat

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

      Default value is "iscServer"

      See Also:
        `ClientDataIntegration overview and related methods`

    - #### nullBooleanValue

          public boolean nullBooleanValue

      If `noNullUpdates` is set, the value to use for any boolean field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.

      Default value is false

      See Also:
        `noNullUpdates`, `com.smartgwt.client.docs.serverds.DataSourceField#nullReplacementValue`

    - #### requires

          public VelocityExpression requires

      Indicates that the specified VelocityExpression must evaluate to true for a user to access this DataSource.

      See also `requires`.

      Default value is null

    - #### omitNullDefaultsOnAdd

          public boolean omitNullDefaultsOnAdd

      When true, and `noNullUpdates` is also true, indicates that "add" requests on this DataSource will have null-valued fields removed from the request entirely before it is sent to the server, as opposed to the default behavior of replacing such null values with defaults.

      Default value is false

      See Also:
        `noNullUpdates`

    - #### autoConvertRelativeDates

          public java.lang.Boolean autoConvertRelativeDates

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

      Default value is true

    - #### iconField

          public java.lang.String iconField

      Designates a field of `type`:"image" as the field to use when rendering a record as an image, for example, in a `TileGrid`.

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

      Default value is see below

      See Also:
        `DsSpecialFields overview and related methods`

    - #### showPrompt

          public java.lang.Boolean showPrompt

      Whether RPCRequests sent by this DataSource should enable `showPrompt` in order to block user interactions until the request completes.

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

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

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

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

      Default value is true

    - #### clientOnly

          public java.lang.Boolean clientOnly

      A clientOnly DataSource simulates the behavior of a remote data store by manipulating a static dataset in memory as `DSRequests` are executed on it. Any changes are lost when the user reloads the page or navigates away.

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

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

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

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

      Default value is false

      See Also:
        `ClientOnlyDataSources overview and related methods`

    - #### resultBatchSize

          public int resultBatchSize

      Very advanced: for servers that do not support paging, and must return large numbers of XML records in one HTTP response, Smart GWT breaks up the processing of the response in order to avoid the "script running slowly" dialog appearing for an end user.

      If you have a relatively small number of records with a great deal of properties or subobjects on each record, and you have not set `dropExtraFields` to eliminate unused data, and you see the "script running slowly" dialog, you may need to set this number lower.

      Default value is 150

    - #### sqlPaging

          public SQLPagingStrategy sqlPaging

      The paging strategy to use for this DataSource. If this property is not set, the default paging strategy, specified with the `server.properties` setting `sql.defaultPaging`, is used.

      This setting can be overridden with the `sqlPaging` property.

      NOTE: Operations that involve a `customSQL` clause ignore this property, because customSQL operations usually need to be treated as special cases. For these operations, the paging strategy comes from the `server.properties` setting `sql.defaultCustomSQLPaging` or `sql.defaultCustomSQLProgressivePaging`, depending on whether or not `progressiveLoading` is in force. Note that these can always be overridden by a `sqlPaging` setting on the OperationBinding.

      Default value is null

      See Also:
        `OperationBinding.sqlPaging`

    - #### enumConstantProperty

          public java.lang.String enumConstantProperty

      The name of the property this DataSource uses for constant name when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean". Defaults to "_constant" if not set.

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

      Default value is null

    - #### enumOrdinalProperty

          public java.lang.String enumOrdinalProperty

      The name of the property this DataSource uses for ordinal number when translating Java enumerated types to and from Javascript, if the `EnumTranslateStrategy` is set to "bean". Defaults to "_ordinal" if not set.

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

      Default value is null

    - #### nullFloatValue

          public float nullFloatValue

      If `noNullUpdates` is set, the value to use for any float field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.

      Default value is 0.0

      See Also:
        `noNullUpdates`, `com.smartgwt.client.docs.serverds.DataSourceField#nullReplacementValue`

    - #### pluralTitle

          public java.lang.String pluralTitle

      User-visible plural name for this DataSource.

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

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

      Default value is dataSource.ID

    - #### ID

          public java.lang.String ID

      Unique identifier for this DataSource. Required for all DataSources. DataSources will make themselves available as JavaScript globals under the same name as their ID only if `addGlobalId` is set.

      Default value is null

    - #### tableName

          public java.lang.String tableName

      For DataSources using the `Smart GWT SQL engine` for persistence, what database table name to use. The default is to use the DataSource ID as the table name.

      Default value is null

      See Also:
        `ServerDataIntegration overview and related methods`

    - #### globalNamespaces

          public java.lang.Object globalNamespaces

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

      The default value is:

              globalNamespaces : {
                 xsi: "http://www.w3.org/2001/XMLSchema-instance",
                 xsd: "http://www.w3.org/2001/XMLSchema"
              },

      This default value allows the use of the xsi:type and xsi:nil attributes without further declarations.

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

      Default value is ...

    - #### useOfflineStorage

          public java.lang.Boolean useOfflineStorage

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

      Default value is null

    - #### nullIntegerValue

          public int nullIntegerValue

      If `noNullUpdates` is set, the value to use for any integer field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.

      Default value is 0

      See Also:
        `noNullUpdates`, `com.smartgwt.client.docs.serverds.DataSourceField#nullReplacementValue`

    - #### useSubselectForRowCount

          public java.lang.Boolean useSubselectForRowCount

      This property is only applicable to `SQL` DataSources, and only for `operations` that express a `customSQL` clause. In these circumstances, we generally switch off paging because we are unable to generate a "row count" query that tells the framework the size of the complete, unpaged resultset.

      The `useSubselectForRowCount` flag causes the framework to derive a rowcount query by simply wrapping the entire customSQL clause in a subselect, like so:`
      SELECT COUNT(*) FROM ({customSQL clause here})`

      However, this is not guaranteed to give good results. Because the customSQL clause can contain anything that you can write in SQL, running it inside a subselect in order to count the rows might not work, might have unintended side-effects (if, for example, it is a stored procedure call that performs updates as part of its function), or it might just be a bad idea - for example, if the customSQL query is slow-running, you'll make it twice as slow with this flag, simply because you'll be running it twice. We recommend using this flag with care.

      NOTE: This setting can be overridden per-operation - see `useSubselectForRowCount`. You can also set a global default for this setting, so you don't have to specify it in every dataSource - define `useSubselectForRowCount` as true in your `server.properties` file.

      Default value is null

    - #### dbName

          public java.lang.String dbName

      For DataSources using the `Smart GWT SQL engine` for persistence, which database configuration to use. Database configurations can be created using the `Admin Console`. If unset, the default database configuration is used (which is also settable using the "Databases" tab).

      Default value is null

      See Also:
        `ServerDataIntegration overview and related methods`

    - #### useAnsiJoins

          public java.lang.Boolean useAnsiJoins

      For DataSources using the `Smart GWT SQL engine` for persistence, whether to use ANSI-style joins (ie, joins implemented with JOIN directives in the table clause, as opposed to additional join expressions in the where clause). The default value of null has the same meaning as setting this flag to false.

      Note, outer joins (see `joinType`) only work with certain database products if you choose not to use ANSI joins. Other than that, the join strategies are equivalent.

      If you wish to switch on ANSI-style joins for every DataSource, without the need to manually set this property on all of them, set `server.properties` flag `sql.useAnsiJoins` to true.

      Default value is null

      See Also:
        `ServerDataIntegration overview and related methods`

    - #### serverType

          public DSServerType serverType

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

      Default value is "generic"

      See Also:
        `ServerDataIntegration overview and related methods`

    - #### requestProperties

          public DSRequest requestProperties

      Additional properties to pass through to the `DSRequest`s made by this DataSource.

      These properties are applied before `DataSource.transformRequest` is called.

      Default value is null

      See Also:
        `DSRequest`, `OperationBinding.requestProperties`, `ClientDataIntegration overview and related methods`

    - #### callbackParam

          public java.lang.String callbackParam

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

      Default value is "callback"

      See Also:
        `dataFormat`, `operationBindings`, `OperationBinding.callbackParam`, `ClientDataIntegration overview and related methods`

    - #### idClassName

          public java.lang.String idClassName

      For JPA and Hibernate DataSources this property indicates, that data source has composite primary key and specifies fully-qualified Java class:
      - with `@EmbeddedId` you have to specify class name of declared id
      - with `@IdClass` you have to specify class specified in annotation declaration

      Default value is null

    - #### lookAhead

          public int lookAhead

      If we are `loading progressively`, indicates the number of extra records Smart GWT Server will read beyond the end record requested by the client, in order to establish if there are more records to view. This property has no effect if we are not progressive-loading.

      This property can be tweaked in conjunction with `endGap` to change behavior at the end of a dataset. For example, with the default values of `lookAhead: 1` and `endGap: 20`, we can end up with the viewport shrinking if we get a case where there really was only one more record (because the client was initially told there were 20 more). This is not a problem per se, but it may be surprising to the user. You could prevent this happening (at the cost of larger reads) by setting `lookAhead` to be `endGap+1`.

      Default value is 1

      See Also:
        `progressiveLoading`, `endGap`, `ProgressiveLoading overview and related methods`

    - #### autoDeriveSchema

          public java.lang.Boolean autoDeriveSchema

      This property allows you to specify that your DataSource's schema (field definitions) should be automatically derived from some kind of metadata. This causes Smart GWT to create a special super-DataSource, which is used purely as a source of default schema for this DataSource; this is arranged by causing the autoDerived DataSource to automatically `inherit from` the special super-DataSource. This allows you to auto-derive schema from existing metadata, whilst still being able to override any or all of it as required.

      This property has a different implementation depending upon the `serverType` of the DataSource:

      - For a DataSource with serverType: "sql", automatically derive the dataSource's schema from the Spring bean or Java class specified in `schemaBean`. If `schemaBean` is not specified, derive the schema from the columns in the SQL table specified in `tableName`. More information on SQL DataSources is `here`
      - For a DataSource with serverType: "hibernate", automatically derive the dataSource's schema from the Spring bean, Hibernate mapping or Java class named in the `schemaBean` property. If no such thing exists, derive the schema from the Hibernate mapping or Java class specified in the `beanClassName` property (this allows you to specify schema and mapping separately, in the unusual circumstance that you have a need to do so). Note that the "mappings" referred to here can mean either `.hbm.xml` files or annotated classes; both are supported. If neither of these is successful, derive the schema from the underlying SQL table specified in `tableName`. More information on Hibernate DataSources is `here`
      - For a DataSource with serverType: "jpa1" or "jpa", automatically derive the dataSource's schema from the annotated JPA class named in the `schemaBean` property. If the schemaBean property is not defined, derive the schema from the annotated JPA class named in the `beanClassName` property (as with Hibernate, this allows you to specify schema and mapping separately if you need to do so). JPA DataSource generation relies on annotations (the orm.xml mapping file is not supported). More information on JPA DataSources is `here`
      - For other DataSource types, attempt to find a Spring bean with the name specified in the `schemaBean` property. If no such bean is found (or Spring is not present), attempt to instantiate an object whose fully-qualified class name is the value in the `schemaBean` property. If one of these approaches succeeds, we derive the schema from the discovered object (by treating it as a Java Bean and assuming that each one of its getters corresponds to a like-named field in the DataSource). More information on custom DataSource implementations is `here`.
      The following table shows how SQL types are derived into `DataSource types` when we use an SQL table as a source of metadata for a SQL or Hibernate DataSource:

      SQL type | `DataSource type`
      --- | ---
      CHAR, VARCHAR, LONGVARCHAR, TEXT, CLOB | text
      BIT, TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL*, NUMBER** | integer
      REAL, FLOAT, DOUBLE, DECIMAL*, NUMBER** | float
      DATE | date
      TIME | time
      TIMESTAMP | datetime
      BLOB, BINARY, VARBINARY, LONGVARBINARY | binary

      *For DECIMAL types, we inspect the "DECIMAL_DIGITS" attribute of the JDBC metadata and designate the field type "integer" if that attribute is 0, or "float" if it is some other value.
      **NUMBER is an Oracle-only type that appears in the JDBC metadata as DECIMAL and is handled exactly the same way as DECIMAL

      The following table shows how Java types are derived into DataSource types when we use an unannotated Java class (Spring bean, Hibernate mapping or POJO) as a source of metadata for a SQL, Hibernate or custom DataSource:

      Java type | `DataSource type`
      --- | ---
      boolean, Boolean | boolean
      char, Character, String, Reader | text
      byte, short, int, long, Byte, Short, Integer, Long, BigInteger | integer
      float, double, Float, Double, BigDecimal | float
      Enum | enum (see discussion below)
      InputStream | binary
      java.sql.Date, java.util.Date, java.util.Calendar | date
      java.sql.Time | time
      java.sql.Timestamp | datetime

      We also derive the following information for Hibernate mappings described in `.hbm.xml` files (for Hibernate mappings described in Java annotations, see the next table):

      - The first field we encounter that is described in the mapping with an <id> tag is marked as a primaryKey
      - If that field is marked as being generated, we set its type to "sequence"
      Finally, this table shows how Java types are derived into DataSource types when we use an annotated class as a source of metadata. Note annotated classes are necessary for JPA DataSources, but you can choose to use them for other types of DataSource as well. For Hibernate DataSources, this is very worthwhile because Hibernate will also make use of the annotations as config, meaning you don't need to specify `.hbm.xml` files. For SQL and custom DataSources, there is no benefit at the persistence level, but it may still be worthwhile because the use of an annotated class gives us better metadata and allows us to generate a better, closer-fitting autoDerive DataSource than we can from examination of SQL schema or plain Java Beans:

      Java type | `DataSource type`
      --- | ---
      boolean, Boolean | boolean
      char, Character, String, Reader | text
      byte, short, int, long, Byte, Short, Integer, Long, BigInteger | integer
      float, double, Float, Double, BigDecimal | float
      InputStream | binary
      java.util.Date (with Temporal set to DATE), java.sql.Date | date
      java.util.Date (with Temporal set to TIME), java.sql.Time | time
      java.util.Date (with Temporal set to TIMESTAMP), java.util.Calendar, java.sql.Timestamp | datetime
      Enum (with Enumerated set to STRING) | enum (see discussion below)
      Enum (with Enumerated set to ORDINAL) | intEnum (see discussion below)
      Field with Lob annotation | binary
      Field with GeneratedValue annotation | sequence

      #### enums and valueMaps

      When we come across Java `Enum` properties in plain or annotated classes, as well as setting the field type as noted in the above tables, we also generate a valueMap for the field, based on the `Enum` members.

      For cases where we generate a field of Smart GWT type "enum" (see the above tables), the keys of the valueMap are the result of calling `name()` on each member of the underlying Java Enum (in other words, its value exactly as declared in its enum declaration). For cases where we generate a field of Smart GWT type "intEnum", the keys of the valueMap are strings representing the ordinal number of each member in the Java Enum - "0", "1", etc. Note that this behavior will be overriden by `DataSource.enumTranslateStrategy` if both are set.

      In both of these case, the display values generated for the valueMap are the result of calling `toString()` on each Enum member. If that gives the same value as calling `name()`, the value is passed through `DataTools.deriveTitleFromName()`, which applies the same processing rules as `DataSource.getAutoTitle` to derive a more user-friendly display value.

      NOTE: `schemaBean` implies `autoDeriveSchema`, because it has no other purpose than to name the bean to use for auto-derived schema. Thus, if you specify `schemaBean` you do not need to specify `autoDeriveSchema` as well (though it does no harm to do so). However, `tableName` can be validly specified without implying `autoDeriveSchema`, so in that case you must explicitly specify `autoDeriveSchema`.

      NOTE: The underlying super-DataSource is cached in server memory, so that it does not have to be derived and created each time you need it. However, the cache manager will automatically refresh the cached copy if it detects that the deriving DataSource has changed. Thus, if you change the metadata your DataSource is deriving (if, for example, you add a column to a table), all you need to do is touch the `.ds.xml` file (ie, update its last changed timestamp - you don't actually have to change it) and the cached copy will be refreshed next time it is needed.

      When autoDeriveSchema is set, SQLDataSource will automatically discover foreignKeys and deliver table and column name information to the client in hashed form so that two DataSources that are linked by native SQL foreign keys will automatically discover each other if loaded into the same application, and set dataSourceField.foreignKey automatically. Because the table and column names are delivered as cryptohashes, there is no information leakage, but regardless the feature can be disabled via setting datasource.autoLinkFKs to false in `server.properties`. This hashed linkage information is delivered to the client in properties `tableCode` and `fkTableCode`/`fkColumnCode`

      Default value is null

    - #### serverConstructor

          public java.lang.String serverConstructor

      This property allows you to write and use custom DataSource subclasses on the server, by specifying either
      - the fully-qualified name of the DataSource subclass that should be instantiated server-side for this dataSource, or
      - the token "spring:" followed by a valid Spring bean ID, if you wish to instantiate your custom dataSource object using Spring dependency injection. For example, `"spring:MyDataSourceBean"`. See also `ServerInit` for special concerns with framework initialization when using Spring.

      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`, or to a Spring bean of the same description. If your implementation relies on methods or state only present in certain specialized subclasses of DataSource (for example, you want the normal behavior and features of a HibernateDataSource, but with a specialized validate() method), then you should extend the subclass rather than the base class.

      NOTE: Please take note of the points made in `this discussion` of caching and thread-safety issues in server-side DataSources.

      Default value is null

    - #### nullDateValue

          public Date nullDateValue

      If `noNullUpdates` is set, the value to use for any date or time field that has a null value assigned on an update operation, and does not specify an explicit `nullReplacementValue`.

      Unlike strings and numbers, there is no "natural" choice for a null replacement value for dates. The default value we have chosen is midnight on January 1st 1970, simply because this is "the epoch" - the value that is returned by calling "new Date(0)"

      Default value is See below

      See Also:
        `noNullUpdates`, `com.smartgwt.client.docs.serverds.DataSourceField#nullReplacementValue`

    - #### schemaNamespace

          public java.lang.String schemaNamespace

      For a DataSource derived from WSDL or XML schema, the XML namespace this schema belongs to. This is a read-only attribute automatically present on DataSources returned from SchemaSet.getSchema and `WebService.getSchema`.

      Default value is null

      See Also:
        `WsdlBinding overview and related methods`

    - #### dataField

          public java.lang.String dataField

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

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

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

      Default value is null

      See Also:
        `DsSpecialFields overview and related methods`

    - #### dropExtraFields

          public java.lang.Boolean dropExtraFields

      Indicates that for server responses, for any data being interpreted as DataSource records, only data that corresponds to declared fields should be retained; any extra fields should be discarded.

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

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

      Default value is null

      See Also:
        `ClientDataIntegration overview and related methods`

    - #### strictSQLFiltering

          public java.lang.Boolean strictSQLFiltering

      If set to true, both client and server-side advanced filtering used by Smart GWT will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users. Specifically, when a field has NULL value, all of the following expressions are false:

               field == "someValue"  (normally false)
               field != "someValue"  (normally true)
               not (field == "someValue")   (normally true)
               not (field != "someValue")   (normally false)

      This property can be overridden per-query by specifying `strictSQLFiltering` directly as a property on the `AdvancedCriteria`.

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

      Default value is false

    - #### noNullUpdates

          public boolean noNullUpdates

      When true, indicates that fields in this DataSource will never be positively updated to the null value; they may arrive at null values by being omitted, but we will not send actual null values in update requests. When false (the default), null is not treated in any special way.

      Setting this value causes null-assigned fields to be replaced with the field's `nullReplacementValue`, if one is declared. If no `nullReplacementValue` is declared for the field, the null assignment is replaced with the DataSource's `nullStringValue`, `nullIntegerValue`, `nullFloatValue` or `nullDateValue`, depending on the field type.

      For "add" operations, setting `omitNullDefaultsOnAdd` causes null-valued fields to be removed from the request entirely, rather than replaced with default values as described above.

      Default value is false

    - #### serviceNamespace

          public java.lang.String serviceNamespace

      For an XML DataSource, URN of the WebService to use to invoke operations. This URN comes from the "targetNamespace" attribute of the <wsdl:definitions> element in a WSDL (Web Service Description Language) document, and serves as the unique identifier of the service.

      Having loaded a WebService using `XMLTools.loadWSDL`, setting `serviceNamespace` combined with specifying `operationBindings` that set `wsOperation` will cause a DataSource to invoke web service operations to fulfill DataSource requests (`DSRequests`).

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

      Default value is null

      See Also:
        `WsdlBinding overview and related methods`

    - #### canMultiSort

          public boolean canMultiSort

      When true, indicates that this DataSource supports multi-level sorting.

      Default value is true

  - ### Constructor Detail

    - #### DataSource

          public DataSource()