com.smartgwt.client.docs
Interface ServerDataSourceImplementation

public interface ServerDataSourceImplementation

Notes on Server-side DataSource Implementations

NOTE: This section includes references to server-side classes and methods; you can find the documentation for these in the server-side Javadocs.

Bear in mind the following points when working with DataSources (whether custom or built-in) on the Smart GWT Server:

• There is no requirement or expectation that DataSource subclasses be threadsafe. As long as you use documented techniques for creating DataSource instances, the server framework will ensure that no single instance is used concurrently by more than one thread.
• DataSource instances can safely be retained for use multiple times in a given HTTP request; this presents no thread-safety issues unless you specifically introduce them by, eg, creating a new DSRequest and executing it in its own thread
• If the server.properties attribute datasources.pool.enabled is set, DataSource instances are automatically cached in an in-memory pool
• If pooling is not switched on, DataSource instances are constructed new as required, but they are constructed using cached configuration for better performance. The configuration file (.ds.xml file) is read the first time the DataSource is requested; thereafter, we will only re-read the configuration file if its last-changed timestamp changes. This scheme combines the performance benefits of caching with the with the convenience of being able to change a .ds.xml file and pick up the changes without restarting the server.
• The safe way to obtain a DataSource instance is to use RPCManager.getDataSource. If pooling is enabled, this is the only way to obtain a DataSource instance with the guarantee that it will be returned to the pool at the end of request processing.
• If you are using the DynamicDSGenerator to provide DataSources to the framework dynamically:
  • You are expected to use one of the DataSource.fromXML() APIs to construct your DataSources from an XML document or String of XML text
  • Do not use normal Java instantiation techniques like new DataSource(), as this will introduce thread-safety issues
  • Return a new DataSource instance each time - returning the same DataSource twice will introduce thread-safety issues. If you are concerned about performance, ensure pooling is enabled as described above - this will mean that the DataSource you return will be automatically cached and re-used, so your DynamicDSGenerator will only be called enough times to populate the pool. If you are still concerned about performance, cache the XML String that you pass to DataSource.fromXML().