public interface WriteCustomDataSource
Note that a majority of the features of the Smart GWT Server framework apply even when using your own persistence mechanism. As with the features supported by Smart GWT's browser-based visual components, Smart GWT's server-side features rely only on the concept of a DataSource and not on the details of the ultimate persistence mechanism. Hence they are usable with a custom DataSource regardless of the final data provider.
We provide a complete working example of a custom
DataSource in the Smart GWT Feature Explorer; you can see it in action here. This
example "ormDataSource" is an adaptor for Hibernate which supports the 4 CRUD operations,
data paging, server-side sort and filter, and which participates correctly in
cache synchronization. The code required is minimal, and
the approaches taken generalize to any ORM system. Studying the Java source code for this
DataSource - which is available in the "ORMDataSource.java" tab in the example linked to above
- is the best way to get a start on implementing your own custom DataSource.
ORMDataSourceis primarily an implementation of four key methods:
executeRemove. All the logic related to the actual CRUD data operation takes place in one of these methods. This is the recommended approach.
executemethod. This is an override of the method that is actually called by the framework, and as such is an appropriate place to set up shared objects that will be used in more than one CRUD operation, and to perform shared pre- and post-processing. As you can see, the example is setting up a Hibernate session and transaction, and then calling
super.execute- this calls back into the framework and ultimately leads to the appropriate data operation method being called.
executeXxxmethods conforms to the
DataSource protocol. To take
executeFetchas an example, note how it:
batchSizevalues. This is only necessary for a DataSource that intends to support automatic data paging.
sortByFieldsfrom the supplied
DSrequest, and uses that value to change the order of the resultset. This is only necessary for a DataSource that intends to support server-side sorting.
datamember with the list of objects retrieved by the Hibernate call.
The DataSource descriptor
Once your custom DataSource is implemented, you need to to create a descriptor for each instance of the DataSource. As noted above, it is generally possible to write one custom DataSource class that is capable of handling all data access for a particular persistence mechanism. DataSource descriptors, on the other hand, are written per entity.
A DataSource descriptor is an XML file with the special suffix
.ds.xml. The descriptor for a custom DataSource is, for the most part, identical
to the descriptor for a built-in DataSource: it is the central place where you describe the
DataSource instance to the system - its fields, validations, security constraints, special data
operations, transaction chaining expressions and so on (see the
DataSource docs for full details).
One property that
is always required for a custom DataSource is
fully-qualified class name tells Smart GWT what to instantiate when data operations for this
DataSource arrive on the server - in other words, it is how you tell Smart GWT to use your
custom class. In the ORM DataSource example, on the
you will see how we use this property to tie the
instance to the
ormDataSource DataSource implementation.
Finally, if your data model is based on Javabeans, or on POJOs that broadly follow the
Javabean conventions (basically, if they have private state variables accessible via public
getters and setters), Smart GWT can automatically generate basic DataSource definitions for
your beans that will only need minimal change (ie, specifying a
serverConstructor) to be fully operational. Both the Visual
Builder Javabean Wizard and the Batch DataSource Generator can create DataSource
descriptors from existing beans.
Server framework features relevant to custom DataSources
The vast majority of the Smart GWT Server framework's key features are not
specific to the built-in SQL and Hibernate connectors, and still apply even when using a custom
persistence mechanism. See
overview of which features apply when using a custom persistence mechanism and how best to
leverage those features.