Field Detail

• 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 OperationBinding.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

• 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 OperationBinding.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

  See Also:

  DeclarativeSecurity 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

• 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 beanClassName affects what numeric field types will be used for inbound DSRequest data. For fields with numeric types, the record data in DSRequests will automatically be converted to the type of the target field, before the request is received in a DMI. For details, see DsRequestBeanTypes.

  Note that DMI also has a built-in facility for populating a bean with the inbound DSRequest.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.

  The declared Java bean will affect how its properties will be mapped to built-in numeric types, see Hibernate Integration overview for details.

  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 DSResponse), passing the altered list of records. See the server-side Javadocs for DSResponse for details of these two methods.

  Default value is null

  See Also:

  OperationBinding.beanClassName

• auditDataSourceID

  public java.lang.String auditDataSourceID

  For DataSources with auditing enabled, optionally specifies the ID of the audit DataSource. If this property is not specified, the ID of the audit DataSource will be audit_[OriginalDSID]

  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. It is also particularly important that you read the discussion of caching and thread-safety linked to below, as there are special considerations in this area when using Spring.
  • the token "cdi:" followed by a valid CDI bean name, if you wish to instantiate your custom dataSource object using CDI dependency injection. For example, "cdi:MyDataSourceBean".

  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

• dataFormat

  public DSDataFormat dataFormat

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

  Default value is "iscServer"

  See Also:

  ServerDataIntegration overview and related methods

• 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()

• sequenceMode

  public SequenceMode sequenceMode

  For fields of type "sequence" in a dataSource of serverType "sql", indicates the SequenceMode to use. This property has no effect for fields or dataSources of other types.

  You can set a default sequenceMode for all DataSources of a given database type by setting property "sql.{database_type}.default.sequence.mode" in server.properties. You set a global default sequenceMode that applies to all database types by setting property "sql.default.sequence.mode". For example:

      sql.mysql.default.sequence.mode: jdbcDriver
    

  Default value is "native"

• 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

• 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 OperationBinding.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

• script

  public java.lang.String script

  Default scriptlet to be executed on the server for each operation. If OperationBinding.script is specified, it will be executed for the operation binding in question instead of running this scriptlet.

  Scriptlets are used similarly to DMIs configured via serverObject or OperationBinding.serverObject - they can add business logic by modifying the DSRequest before it's executed, modifying the default DSResponse, or taking other, unrelated actions.

  For example:

       <DataSource>
          <script language="groovy">
             ... Groovy code ...
          </script>
         ... other DataSource properties
       </DataSource>
    

  Scriptlets can be written in any language supported by the "JSR 223" standard, including Java itself. See the DMI Script Overview for rules on how to return data, add additional imports, and other settings.

  The following variables are available for DMI scriptlets:

  • requestContext: RequestContext (from com.isomorphic.servlet)
  • dataSource: the current DataSource (same as DSRequest.getDataSource())
  • dsRequest: the current DSRequest
  • criteria: shortcut to DSRequest.getCriteria() (a Map)
  • values: shortcut to DSRequest.getValues() (a Map)
  • oldValues: shortcut to DSRequest.getOldValues() (a Map)
  • sqlConnection: SQLDataSource only: the current SQLConnection object. If using automatic transactions are enabled, this SQLConnection is in the context of the current transaction.
  • rpcManager: the current RPCManager
  • applicationContext: the Spring ApplicationContext (when applicable)
  • beanFactory: the Spring BeanFactory (when applicable)

  Scriptlets also have access to a set of contextual variables related to the Servlets API, as follows:

  • servletRequest: the current ServletRequest
  • session: the current HttpSession
  • servletResponse: the current ServletResponse (advanced use only)
  • servletContext: the current ServletContext(advanced use only)

  As with DMI in general, be aware that if you write scriptlets that depend upon these variables, you preclude your DataSource from being used in the widest possible variety of circumstances. For example, adding a scriptlet that relies on the HttpSession prevents your DataSource from being used in a command-line process.

  Note that if a dataSource configuration has both a <script> block and a specified serverObject for some operation, the script block will be executed, and the serverObject ignored.

  Default value is null

• fileNameField

  public java.lang.String fileNameField

  The native field name used by this DataSource on the server to represent the fileName for FileSource Operations operations. Any extensions to the fileName to indicate type or format (e.g. ".ds.xml") are stored in the fileTypeField and fileFormatField, if specified for this DataSource.

  If not specified for a DataSource, the fileNameField will be inferred on the server as follows:

  • If there is a field named "fileName", "name", or "title", then that field is used.
  • Otherwise, if there is a single primary key, and it has the type "text", then that field is used.
  • Otherwise, an error is logged

  Default value is null

  See Also:

  FileSource overview and related methods

• 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

• resultSetClass

  public java.util.Map 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

• auditUserFieldName

  public java.lang.String auditUserFieldName

  For DataSources with auditing enabled, specifies the field name used to store the user who performed the operation. If empty string is specified as the field name, the audit DataSource will not store this field.

  Default value is "audit_modifier"

• 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 (OperationBinding.serverObject) or customizations to SQL, JQL and HQL queries (OperationBinding.customSQL, OperationBinding.customJQL and OperationBinding.customHQL). See the @see Java Integration samples.

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

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

         DataSource dataSource = new DataSource();
         dataSource.setServiceNamespace("urn:partner.soap.sforce.com");
         OperationBinding fetch = new OperationBinding();
         fetch.setOperationType(DSOperationType.FETCH);
         fetch.setWsOperation("query");
         fetch.setRecordName("sObject");
         OperationBinding add = new OperationBinding();
         add.setOperationType(DSOperationType.ADD);
         add.setWsOperation("create");
         add.setRecordName("SaveResult");
         OperationBinding update = new OperationBinding();
         update.setOperationType(DSOperationType.UPDATE);
         update.setWsOperation("update");
         update.setRecordName("SaveResult");
         OperationBinding remove = new OperationBinding();
         remove.setOperationType(DSOperationType.REMOVE);
         remove.setWsOperation("delete");
         remove.setRecordName("DeleteResult");
         dataSource.setOperationBindings(fetch, add, update, remove);
    

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

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

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

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

  Default value is null

  See Also:

  OperationBinding

• fileTypeField

  public java.lang.String fileTypeField

  The native field name used by this DataSource on the server to represent the fileType for FileSource Operations.

  If the fileTypeField is not configured, then a field named "fileType" will be used, if it exists. Otherwise, the DataSource will not track fileTypes -- this may be acceptable if, for instance, you use a separate DataSource for each fileType.

  The fileType is specified according to the extension that would have been used in the filesystem -- for instance, the fileType for employees.ds.xml would be "ds".

  Default value is null

  See Also:

  FileSource overview and related methods

• 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

• useFlatFields

  public java.lang.Boolean useFlatFields

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

  Default value is null

• 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

• xmlNamespaces

  public java.util.Map xmlNamespaces

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

  Default value is See below

  See Also:

  ClientDataIntegration overview and related methods

• requires

  public VelocityExpression requires

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

  See also OperationBinding.requires.

  Default value is null

  See Also:

  DeclarativeSecurity overview and related methods

• ID

  public java.lang.String ID

  Unique identifier for this DataSource. Required for all DataSources.

  Default value is null

• maxFileVersions

  public java.lang.Integer maxFileVersions

  If automatic file versioning is enabled for a FileSource DataSource, this property configures the maximum number of versions to retain.

  Default value is 20

  See Also:

  fileVersionField, FileSource overview and related methods

• 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

• generateAuditDS

  public boolean generateAuditDS

  For an audited DataSource, controls whether the Framework will attempt to auto-generate the audit DataSource. Note that this property is independent of auditDataSourceID so that, by default, even when the audit DataSource is given a non-default ID, the Framework will still attempt to auto-generate it.

  Default value is true

• 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

• 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

• 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

• 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

• 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

• allowClientRequestedSummaries

  public java.lang.Boolean allowClientRequestedSummaries

  If a DSRequest arrives from the client that requests server-calculated summaries, should it be allowed?

  Note this setting only affects dsRequests that come from the browser (or another client). This setting has no effect on server summaries declared in .ds.xml files or summaries configured in DSRequests created programmatically on the server side, which are always allowed.

  Default value of null means this DataSource will use the system-wide default, which is set via datasources.allowClientRequestedSummaries in server.properties, and defaults to allowing client-requested summaries.

  If client-requested summarization is allowed, but the server-side <operationBinding> provides specific summarization settings, the client-requested summarization is ignored.

  Default value is null

  See Also:

  DataSourceField.allowClientRequestedSummaries, ServerSummaries overview and related methods

• projectFileKey

  public java.lang.String projectFileKey

  For DataSources with type projectFile, looks up the locations to use as projectFileLocations from the project's configuration (i.e. project.properties, server.properties etc.).

  For instance, to look up the value of project.datasources and use it for projectFileLocations, use "datasources" as the projectFileKey.

  If you specify both projectFileKey and projectFileLocations, then both with be used, with the projectFileLocations applied last.

  Default value is null

  See Also:

  projectFileLocations, FileSource 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

• 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

• 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 addData(), updateData() and removeData(), possibly in a transactional queue. Note that 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

• defaultBooleanStorageStrategy

  public java.lang.String defaultBooleanStorageStrategy

  For serverType:"sql" DataSources, sets the default sqlStorageStrategy to use for boolean fields where no sqlStorageStrategy has been declared on the field.

  Can also be set system-wide via the Server_properties setting sql.defaultBooleanStorageStrategy, or for a particular database configuration by setting sql.dbName.defaultBooleanStorageStrategy (see Admin Console overview for more information on SQL configuration).

  Note that when this property is unset, the default DataSourceField.sqlStorageStrategy strategy is effectively "string".

  Default value is null

  See Also:

  ServerDataIntegration overview and related methods

• defaultMultiUpdatePolicy

  public MultiUpdatePolicy defaultMultiUpdatePolicy

  Controls when primary keys are required for "update" and "remove" server operations, when allowMultiUpdate has not been explicitly configured on either the operationBinding.allowMultiUpdate or via the server-side API DSRequest.setAllowMultiUpdate().

  Default value of null means this DataSource will use the system-wide default, which is set via datasources.defaultMultiUpdatePolicy in server.properties, and defaults to not allowing multi updates for requests associated with an RPCManager, see MultiUpdatePolicy for details.

  Default value is null

  See Also:

  OperationBinding.allowMultiUpdate

• ignoreTextMatchStyleCaseSensitive

  public java.lang.Boolean ignoreTextMatchStyleCaseSensitive

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

  Default value is false

• 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

• 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

• auditChangedFieldsFieldName

  public java.lang.String auditChangedFieldsFieldName

  For DataSources with auditing enabled, specifies the field name used to store the names of the fields which were updated. If empty string is specified as the field name, the audit DataSource will not store this field.

  Note that this field will only be set for update operations.

  Default value is "audit_changedFields"

• criteriaPolicy

  public CriteriaPolicy criteriaPolicy

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

  Default value is "dropOnShortening"

  See Also:

  DataSource.compareCriteria(com.smartgwt.client.data.Criteria, com.smartgwt.client.data.Criteria)

• 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

• auditTimeStampFieldName

  public java.lang.String auditTimeStampFieldName

  For DataSources with auditing enabled, specifies the field name used to store the timestamp when the operation was performed (in a field of type "datetime"). If empty string is specified as the field name, the audit DataSource will not store this field.

  Default value is "audit_changeTime"

• mockDataCriteria

  public Criteria mockDataCriteria

  When mockMode is enabled, criteria to use in an initial "fetch" DSRequest to retrieve sample data.

  Default value is null

• 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. This may also be prevented on a per-request basis by setting DSRequest.progressiveLoading to false.

  Default value is 200000

  See Also:

  progressiveLoading, DSRequest.getProgressiveLoading(), ProgressiveLoading 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

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

  Note that when dataSource schema is derived by introspecting the Java class or Spring bean the order of derived fields is non-deterministic, so you may find that it changes if you switch JVMs, Java compilers or other parts of your Java toolchain. This means that you need to include the order of all fields that are ultimately client-visible. Otherwise, if you bind a ListGrid or DynamicForm to this DataSource without specifying the order of fields in that grid or form, you could get fields in a different order on each application restart.

  Field types

  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

  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, if the field is an integer type (see discussion below)

  Primary keys, sequences and identity columns

  We attempt to derive information about primary keys from the metadata we have.

  If the metadata source is an SQL table:

  • If the table does not have a native primary key constraint, no attempt is made to identify primary key fields. Otherwise:
  • The column or columns that make up the table's native primary key constraint are identified using the JDBC DatabaseMetaData.getPrimaryKeys() API
  • Each DataSource field that corresponds to one of these native primary key columns is marked primaryKey: true
  • For each of these columns, the metadata returned by DatabaseMetaData.getColumns() is inspected. If the metadata includes IS_AUTOINCREMENT=YES, we mark the corresponding field as type="sequence". This information should be reliably provided by databases that implement "auto-increment" or "identity" column types, such as MySQL or Microsoft SQL Server
  • If the previous step does not identify a column as a sequence, we inspect the ResultSetMetaData obtained by running a dummy query on the table. If the isAutoIncrement() API returns true for that column, we mark the corresponding field as type="sequence"
  • If the previous steps have not identified the column as a sequence, we check the TYPE_NAME in the column metadata. If it is "serial", this means the column is a PostgreSQL "serial" or "serial8" type column. Postgres does not transparently implement auto-increment columns, but it does provide this serial type, which causes the column to be implicitly bound to an underlying sequence. So this type causes us to mark the field type="sequence", and we also set implicitSequence true
  • If the previous steps have not identified the column as a sequence, we check the COLUMN_DEF in the column metadata. If this contains the token "$$ISEQ" and ends with "NEXTVAL", this means the column is an Oracle "GENERATED AS IDENTITY" column. This type of column was introduced in Oracle 12c and is conceptually exactly the same thing as the Postgres "serial" column described above. We treat it the same way: mark it type="sequence" and implicitSequence="true"
  • If the previous steps have not identified the column as a sequence, then you may be using a pure sequence database, such as an Oracle version earlier than 12c, or you may be using a database where both sequences and identity columns are available (Oracle, Postgres, DB2), and a sequence is being used either by design or because the table was created before the database product supported identity columns. In this case, we cannot determine if the column should be a sequence or not. However, in many applications, the fact that the column is an integer and is a primary key would imply that it is also a sequence. Therefore, if the column is an integer and the server.properties flag auto.derive.integer.pk.always.sequence is true, we mark the field as type="sequence"
  • If, after all this, Smart GWT ends up incorrectly marking a primary key field as a sequence (or vice versa), you can always override it on a per-field basis by simply redeclaring the field with the correct type in your .ds.xml file:

       <DataSource serverType="sql" tableName="myTable" autoDeriveSchema="true">
         <fields>
           <!-- This field was incorrectly marked as a sequence -->
           <field name="notASeq" type="integer" />
           <!-- This field was incorrectly marked as an integer when it should be a sequence -->
           <field name="isASeq" type="sequence" />
         </fields>
       </DataSource>

  If the metadata source is Hibernate mappings described in a .hbm.xml file:

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

  If the metadata source is an annotated object (whether JPA, Hibernate or just an annotated POJO):

  • Any field with an @Id annotation is is marked as a primaryKey (this differs from the Hibernate .hbm.xml file case because that is specific to Hibernate, which does support composite keys, but not by specifying multiple <id> tags. Annotations are supported, via annotated POJOs, for any kind of persistence strategy, so multiple @Id fields are perfectly valid)
  • Any field with a @GeneratedValue annotation is either marked as type="sequence" (if it is an integer type) or as autoGenerated="true" (for other field types)

  Finally, if the metadata is a plain, unannotated Java object, no attempt is made to derive primary key fields.

  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 getAutoTitle() to derive a more user-friendly display value.

  Further notes

  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 and beanClassName can be validly specified without implying autoDeriveSchema, so in those cases you must explicitly specify autoDeriveSchema.

  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 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 DataSourceField.fkTableCode/fkColumnCode

  Default value is null

• 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 OperationBinding.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:

  ClientDataIntegration overview and related methods

• fileVersionField

  public java.lang.String fileVersionField

  The native field name used by this DataSource on the server to represent fileVersion for FileSource Operations.

  Automatic file versioning is configured by the presence of this property: if you want automatic versioning for a FileSource DataSource, it is sufficient to simply define a fileVersionField. When automatic versioning is on:

  • Calls to saveFile() will save a new version of the file, retaining previous versions up to the maximum configured by maxFileVersions; when that maximum is reached, the oldest version is overwritten
  • The getFile() API always returns the most recent version
  • The listFiles() API only includes the most recent version of any file
  • You can view and retrieve earlier versions of a file with the listFileVersions() and getFileVersion() APIs. Note that retrieving a previous version of a file and then calling saveFile() goes through the normal process of saving a new version

  The fileVersion field is expected to be of type "datetime", and automatic versioning will not work otherwise. Note, to minimize the possibility of version timestamp collisions, we recommend that fileVersion fields specify storeMilliseconds: true.

  If the fileVersionField is not configured, no automatic file versioning will be done.

  Default value is null

  See Also:

  maxFileVersions, DataSource.listFileVersions(com.smartgwt.client.data.FileSpec, com.smartgwt.client.data.DSCallback), DataSource.getFileVersion(com.smartgwt.client.data.FileSpec, java.util.Date, com.smartgwt.client.callbacks.GetFileVersionCallback), DataSource.removeFileVersion(com.smartgwt.client.data.FileSpec, java.util.Date), FileSource overview and related methods

• 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

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

• 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

• transformMultipleFields

  public java.lang.Boolean transformMultipleFields

  If set to "false", transformation of values for multiple:true fields, normally controlled by DataSourceField.multipleStorage, is instead disabled for this entire 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

• 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

• audit

  public boolean audit

  Enables saving of a log of changes to this DataSource in a second DataSource with the same fields, called the "audit DataSource". NOTE: this feature applies to Enterprise Edition only; for more information on edition-specific features, see http://smartclient.com/product.

  When auditing is enabled, every time a DSRequest modifies this DataSource, a Record is added to the audit DataSource that shows the record as it existed after the change was made (or for a "remove", the values of the record at the time of deletion). In addition, the audit DataSource has the following additional metadata fields:

  • "audit_operationType": type of the change ("update", "add" or "remove")
  • "audit_modifier": username of the user that made the change. The username is determined in the same way that the Declarative Security subsystem determines the current user.
  • "audit_changeTime": a field of type "datetime" recording the timestamp of the change
  • "audit_revision": a field of type "sequence" recording a simple increasing integer value
  • "audit_changedFields": a "multiple" field of type "string". For "update" operations, records which fields have changed; otherwise, null

  If any of the field names above collide with field names of the DataSource being audited, an integer suffix will also be added, starting with 2 (for example, "audit_modifier2", then "audit_modifier3", etc).

  To omit a data field from the automatically generated audit DataSource, just set DataSourceField.audit to false. Audit can be disabled for a given DSRequest via the server-side API DSRequest.setSkipAudit(), or for a specific operation via the operationBinding.skipAudit setting.

  Note: The DataSource audit feature works only with single row operations; operations with allowMultiUpdate enabled are not supported.

  Auto-generated Audit DataSources

  The audit DataSource is normally automatically generated, and unless otherwise specified with auditDataSourceID, the ID of the audit DataSource will be audit_[OriginalDSID].

  By default, the automatically generated audit DataSource will be of the same type as the DataSource being audited, however, if the DataSource being audited is not already a SQLDataSource, we recommend using auditDSConstructor:"sql" to use a SQLDataSource as the audit DataSource. This is because a SQLDataSource used an audit DataSource will automatically generate a SQL table for storing audit data the first time changes are made. JPA would require manual creation of a Java Bean, and Hibernate requires hbm2ddl.auto=update to be set, which is widely considered unsafe for production use.

  Automatically created audit DataSources can be loaded and queried just like other DataSources, using the DataSourceLoader, and using the server-side API DataSource.getAuditDataSource(). However, you must load the DataSource being audited before loading its automatically created audit DataSource.

  Note, that automatic SQL tables creation can be disabled. See autoCreateAuditTable for details.

  Manually created Audit DataSources

  The audit DataSource can also be manually created. In this case, you can can either follow the naming conventions described above for the ID of the audit DataSource and the names of metadata fields, or use the linked properties to assign custom names. If you omit any data fields from the tracked DataSource in your audit DataSource, those fields will be ignored for auditing purposes, exactly as though DataSourceField.audit had been set to false for an automatically-generated audit DataSource.

  Also, note that in case of manually defined audit DataSource, if this DataSource is defined so it inherits the audited DataSource, all the audited DataSource's fields will be inherited, this including the primary keys. Since for the audit DataSource the primary key should be the revision field, in order to prevent the audit DataSource having two primary keys, the inherited DataSource's primary key will have to be declared in audit DataSource, but with the primaryKey attribute omitted (as well not being of type "sequence") in the audit DataSource.

  Default value is false

  See Also:

  ServerDataIntegration overview and related methods

• resultTreeClass

  public java.util.Map resultTreeClass

  Class for ResultTrees used by this datasource. If null, defaults to using ResultTree.

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

  Default value is null

• guestUserId

  public java.lang.String guestUserId

  Value to use for the ownerIdField if no one has authenticated.

  This setting can be overridden at the operationBinding level.

  Default value is null

  See Also:

  ownerIdField, OperationBinding.guestUserId

• recordName

  public java.lang.String recordName

  Provides a default value for OperationBinding.recordName.

  Default value is null

  See Also:

  ClientDataIntegration overview and related methods

• autoCreateAuditTable

  public boolean autoCreateAuditTable

  Setting autoCreateAuditTable to true indicates that audit DataSource will automatically create SQL table when auditing is enabled.

  Note, that autoCreateAuditTable attribute takes effect only if framework setting audit.autoCreateTables in server.properties is set to false, which by default is set to true.

  Default value is true

• 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 OperationBinding.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

• serverOnly

  public java.lang.String serverOnly

  Setting a DataSource to be serverOnly="true" ensures that it will not be visible to the client. Any request through IDACall to this DataSource will return a failure response. Only requests which have been initiated on the server-side will be executed against this DataSource.

  Default value is null

• 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 ServerObject.dropExtraFields.

  Default value is null

  See Also:

  ClientDataIntegration overview and related methods

• 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

• requiresRole

  public java.lang.String requiresRole

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

  Default value is null

  See Also:

  DeclarativeSecurity overview and related methods

• quoteTableName

  public java.lang.Boolean quoteTableName

  For SQL DataSources, tells the framework whether to surround the associated table name with quotation marks whenever it appears in generated queries. This is only required if you have to connect to a table with a name that is in breach of your database product's naming conventions. For example, some products (eg, Oracle) internally convert all unquoted references to upper case, so if you create a table called myTest, the database actually calls it MYTEST unless you quoted the name in the create command, like this:

    CREATE TABLE "myTest"

  If you do quote the name like this, or if you have to connect to a legacy table that has been named in this way, then you must set this property to tell the SQL engine that it must quote any references to this table name (this requirement depends on the database in use - as noted below, some are not affected by this problem). If you do not, you will see exceptions along the lines of "Table or view 'myTest' does not exist".

  Note, other database products (eg, Postgres) convert unquoted names to lower case, which leads to the same issues. Still others (eg, SQL Server) are not case sensitive and are not affected by this issue.

  Generally, we recommend that you avoid using this property unless you have a specific reason to do so. It is preferable to avoid the issue altogether by simply not quoting table names at creation time, if you are able to do so.

  Default value is null

  See Also:

  tableName, quoteColumnNames, ServerDataIntegration overview and related methods

• fileLastModifiedField

  public java.lang.String fileLastModifiedField

  The native field name used by this DataSource on the server to represent fileLastModified for FileSource Operations.

  If the fileLastModifiedField is not configured, then a field named "fileLastModified" will be used, if it exists. Otherwise, the server will look for a field with a "modifierTimestamp" type. If that is not found, the DataSource will not keep track of the last modified date.

  Default value is null

  See Also:

  FileSource overview and related methods

• compareMetadataForAuditChangeStatus

  public boolean compareMetadataForAuditChangeStatus

  Only applicable to binary fields on audited DataSources.

  When determining if a binary field has changed for auditing purposes, should we compare the metadata values (ie, the associated _filename and _filesize fields) or the actual binary content? If you set this flag to false, this will cause Smart GWT to fetch the existing content of any binary field from the database before any update, and then compare it byte by byte to the new content. You should consider if this will have performance implications for your application, particularly if you store large binary values.

  Note that value comparison of any kind is only performed if the field's DataSourceField.audit setting is "change"

  Default value is true

• 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

• 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

• fileFormatField

  public java.lang.String fileFormatField

  The native field name used by this DataSource on the server to represent the fileFormat for FileSource Operations.

  If the fileFormatField is not configured, then a field named "fileFormat" will be used, if it exists. Otherwise, the DataSource will not track fileFormats -- this may be acceptable if, for instance, the fileFormat is always the same.

  The fileFormat is specified according to the extension that would have been used in the filesystem -- for instance, the fileFormat for employees.ds.xml would be "xml".

  Default value is null

  See Also:

  FileSource overview and related methods

• trimMilliseconds

  public java.lang.Boolean trimMilliseconds

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

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

  Default value is null

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

  Note that if a dataSource configuration has both a <script> block and a specified serverObject for some operation, the script block will be executed, and the serverObject ignored.

  Default value is null

  See Also:

  ServerDataIntegration overview and related methods

• requestProperties

  public DSRequest requestProperties

  Additional properties to pass through to the DSRequests made by this DataSource. This must be set before any DSRequests are issued and before any component is bound to the DataSource.

  These properties are applied before transformRequest() is called.

  Default value is null

  See Also:

  DSRequest, OperationBinding.requestProperties, ServerDataIntegration overview and related methods

• auditTypeFieldName

  public java.lang.String auditTypeFieldName

  For DataSources with auditing enabled, specifies the field name used to store the operationType (in a field of type "text"). If empty string is specified as the field name, the audit DataSource will not store this field.

  Default value is "audit_operationType"

• 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 getAutoTitle().

  Default value is true

• 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

• 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

• 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 OperationBinding.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

• 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

• 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

• tableCode

  public java.lang.String tableCode

  Only applicable to the built-in SQL DataSource

  tableCode and the related properties DataSourceField.columnCode, DataSourceField.fkTableCode and DataSourceField.fkColumnCode are read-only attributes that are secure and unique cryptographic hashes of table and column names used by this DataSource.

  These properties are used automatically by client-side framework code to link dataSources together by foreign key when a foreignKey is not explicitly declared, but is found in the SQL schema via the autoDeriveSchema feature.

  A secure hash is used rather than the actual SQL table or column name for security reasons - sending the actual SQL table or column name to the client could aid in attempted SQL injection attacks.

  This feature can be disabled system-wide via setting datasource.autoLinkFKs to false in server.properties.

  Default value is null

• auditChangedFieldsFieldLength

  public java.lang.Integer auditChangedFieldsFieldLength

  For DataSources with auditing enabled, specifies the length of the field used to store the names of the fields which were updated. See also auditChangedFieldsFieldName

  To set the changedFields field length for all DataSources that do not override the default, set audit.auditChangedFieldsFieldLength in your server.properties file. For example

           audit.auditChangedFieldsFieldLength: 512
    

  Default value is 255

• auditDSConstructor

  public java.lang.String auditDSConstructor

  For DataSources with auditing enabled, optionally specifies the serverConstructor for the automatically generated audit DataSource. The default is to use the same serverConstructor as the DataSource where audit="true" was declared.

  This property is primarily intended to allow the use of SQLDataSource (serverType:"sql") as an audit DataSource for a DataSource that might be of another type. For example, you might have a DataSource that implements all CRUD operations via Java logic in DMI declaration methods, and so doesn't provide generic storage; by using SQLDataSource as the type of your audit DataSource, you don't need to implement your own scheme for storing and querying audit data, and the necessary audit tables will be automatically generated in the database.

  Similarly, even if you do use a reusable DataSource type such as the built-in JPADataSource, using SQLDataSource for audit DataSources means there's no need to write a JPA bean just to achieve storage of an audit trail.

  To simplify this intended usage, the string "sql" is allowed for auditDSConstructor as a means of specifying that the built-in SQLDataSource class should be used. For any other type, use the fully qualified Java classname, as is normal for serverConstructor.

  Default value is null

• inheritanceMode

  public DSInheritanceMode inheritanceMode

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

  Default value is "full"

  See Also:

  inheritsFrom

• 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

• 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

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

  ClientDataIntegration 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

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

  com.smartgwt.client.data.OperationBinding#getIncludeAnsiJoinsInTableClause, ServerDataIntegration overview and related methods

• auditRevisionFieldName

  public java.lang.String auditRevisionFieldName

  For DataSources with auditing enabled, specifies the field name used to store the revision number for the change (in a field of type "sequence"). If empty string is specified as the field name, the audit DataSource will not store this field.

  Default value is "audit_revision"

• showPrompt

  public java.lang.Boolean showPrompt

  Whether RPCRequests sent by this DataSource should enable RPCRequest.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 fetchData()) will generally have a requestProperties argument allowing showPrompt to be set to false for a specific request.

  Default value is true

• dataURL

  public java.lang.String dataURL

  Default URL to contact to fulfill all DSRequests. Can also be set on a per-operationType basis via OperationBinding.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

• defaultTextMatchStyle

  public TextMatchStyle defaultTextMatchStyle

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

  Default value is "exact"

  See Also:

  ServerDataIntegration 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()

• mockDataRows

  public java.lang.Integer mockDataRows

  When mockMode is enabled, number of rows of data to retrieve via an initial "fetch" DSRequest, for use as sample data. Set to null to retrieve all available rows.

  Default value is 75

• projectFileLocations

  public java.lang.String[] projectFileLocations

  For DataSources with type projectFile, specifies locations for the project files. In XML, each location is expressed with a <location> tag, e.g.:

        <projectFileLocations>
            <location>[WEBROOT]/shared/ds</location>
            <location>ds://datasources</location>
        </projectFileLocations>
    

  Directories should be specified as absolute paths on the server. If you want to construct a webroot-relative path, then prefix the path with [WEBROOT] (unlike in server.properties, where you would use $webRoot as the prefix).

  To specify another DataSource to be used via fileSource operations, use ds://dsName (where "dsName" is the name of the other DataSource).

  A projectFile DataSource uses the standard fileSource field names: fileName, fileType, fileFormat, fileContents, fileSize and fileLastModified. When defining a projectFile DataSource, you can use inheritsFrom with a value of "ProjectFile" to inherit definitions for these fields -- e.g.:

        <DataSource ID="MyDataSources" type="projectFile" inheritsFrom="ProjectFile">
            <projectFileLocations>
                <location>[WEBROOT]/shared/ds</location>
                <location>ds://datasources</location>
            </projectFileLocations>
        </DataSource> 
    

  For directory locations, the fileName is relative to the directory specified. Note that the fileName does not include any extension for type or format. For instance, for "employees.ds.xml", the fileName would be "employees", the fileType would be "ds" and the fileFormat would be "xml".

  A projectFile DataSource executes the various fileSource operations in the following manner. The general rule is that fileName, fileType, and fileFormat are treated as primary keys. If files with the same combination of those attributes exist in more than one of the configured locations, the locations are considered in reverse order, with priority given to the location listed last. When modifying an existing file, the last location which contains the file will be used. When creating a new file, the file will be created in the last configured location.

  listFiles

  Returns a combined list of files from all configured locations. Note that listFiles does not recurse into subdirectories. If the same combination of fileName / fileType / fileFormat exists in more than one configured location, then the data for fileSize and fileLastModified will be taken from the last configured location which contains the file.

  hasFile

  Indicates whether the file exists in any of the configured locations.

  getFile

  Returns file data by searching the locations in reverse order.

  saveFile

  If the file exists, it will be saved in the last location in which it exists. If it is a new file, it will be saved in the last configured location.

  renameFile

  The file will be renamed in the last location in which it exists. Note that if the file exists in more than one location, the rename will not affect other locations. Thus, a subsequent listFiles operation will return the file from the other location (as well as the renamed file).

  removeFile

  The file will be removed from the last location in which it exists. Note that if the file exists in more than one location, the removal will not affect other locations. Thus, a subsequent listFiles operation will return the file from the other location.

  For convenience, a projectFile DataSource also responds to the standard DataSource operations, in the following manner:

  add

  Executes a saveFile operation, either adding the file or updating an existing file.

  fetch

  Executes a listFiles operation. Note that the results will not include the fileContents. In order to obtain the fileContents, you must use a getFile operation.

  update

  Executes a renameFile operation. Note that this will not update the fileContents -- for that, you need to use "add", or a saveFile operation.

  remove

  Executes a removeFile operation.

  If you specify both projectFileKey and projectFileLocations, then both with be used, with the projectFileLocations applied last.

  Default value is null

  See Also:

  projectFileKey, FileSource overview and related methods

• 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

• title

  public java.lang.String title

  User-visible name for this DataSource.

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

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

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

  Default value is dataSource.ID

• ownerIdField

  public java.lang.String ownerIdField

  Requires that the currently authenticated user match the contents of this field, for client-initiated requests (i.e., where DSRequest.isClientRequest() returns true on the server).

  When a new row is added by a client-initiated DSRequest, the ownerIdField will be automatically populated with the currently authenticated user (clobbering any value supplied by the client). Client-initiated attempts to update the ownerIdField will also be prevented.

  If you wish to set the ownerIdField to a different value via an "add" or "update" operation, you can do so in server-side DMI code (possibly consulting DSRequest.getClientSuppliedValues() to get the value that was clobbered).

  For client-initiated "fetch", "update" or "remove" operations, the server will modify client-supplied criteria so that only rows whose ownerIdField matches the currently authenticated user can be read, updated or deleted.

  The ownerIdField setting can be overridden at the OperationBinding.ownerIdField level.

  If ownerIdField is specified, requiresAuthentication will default to true. If requiresAuthentication is explicitly set to false, then unauthenticated users will be able to see all records. To avoid this, you can use guestUserId to specify a default user to apply when no one has authenticated.

  Default value is null

  See Also:

  OperationBinding.ownerIdField, guestUserId

• 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

• 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 DataSourceField.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

• globalNamespaces

  public java.util.Map globalNamespaces

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

  The default value is:

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

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

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

  Default value is ...

• 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 transformRequest() and ultimately sent to the server.

  Default value is true

  See Also:

  ClientDataIntegration overview and related methods

• implicitCriteria

  public Criteria implicitCriteria

  Criteria that are implicitly applied to all fetches made through this DataSource. These criteria are never shown to or edited by the user and are cumulative with any other criteria provided on the DSRequest.

  For example, a DataSource might *always* implicitly limit its fetch results to records owned by the current user's department. Components and ResultSets requesting data from the DataSource can then apply further implicitCriteria of their own, separately from their regular, user-editable criteria.

  For instance, a grid bound to this dataSource might be further limited to implicitly show only the subset of records created by the current user. See DataBoundComponent.implicitCriteria and ResultSet.implicitCriteria for more on these localized options.

  Note that, while implicitCriteria can be declared in a server DataSource file using Component XML, it is an entirely client-side feature, added by client-side components. So it does not affect server-side requests, and will not be added to client-side requests that don't come from a Smart GWT UI (eg RestHandler).

  Default value is null

• 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

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

  Default value is dataSource.ID

• auditedDataSourceID

  public java.lang.String auditedDataSourceID

  For audit DataSources, this required property specifies the ID of the audited DataSource. Automatically populated for auto-generated audit DataSources.

  Default value is varies

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

  quoteTableName, ServerDataIntegration 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

• recordXPath

  public XPathExpression recordXPath

  See OperationBinding.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

• 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 OperationBinding.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

• fileContentsField

  public java.lang.String fileContentsField

  The native field name used by this DataSource on the server to represent the fileContents for FileSource Operations.

  If the fileContentsField is not configured, then a field named "fileContents" or "contents" will be used, if it exists. If not found, the longest text field which is not the fileNameField, fileTypeField or fileFormatField will be used.

  Note that the only method which will actually return the fileContents is getFile() -- the other FileSource methods omit the fileContents for the sake of efficiency.

  Default value is null

  See Also:

  FileSource overview and related methods

• 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

• 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

• 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

• 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

• canMultiSort

  public boolean canMultiSort

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

  Default value is true

Constructor Detail

• DataSource

  public DataSource()