com.smartgwt.client.docs
Interface WriteCustomDataSource


public interface WriteCustomDataSource

Integrating the Smart GWT Server framework with custom Java persistence logic

Out of the box, and with no code to write, Smart GWT supports SQL and Hibernate for persistence. For other Java-based persistence systems, such as EJB, JPA, or systems proprietary to your company, you write a custom DataSource class in Java. In most cases, it is possible to write a single, generic DataSource class that provides access to all data that is a available from a given persistence mechanism; for example, a single DataSource class can typically be written for accessing all Entity Beans available via EJB.

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 ${isc.DocUtils.linkForExampleId('ormDataSource', '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 ResultSet. 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.


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 for full details).

One property that is always required for a custom DataSource is 'serverConstructor'. This 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 ${isc.DocUtils.linkForExampleId('ormDataSource', 'ORM DataSource example')}, on the ormDataSource_country tab, you will see how we use this property to tie the ormDataSource_country DataSource 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 ${isc.DocUtils.linkForExampleId('javabeanWizard', '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 'this overview' of which features apply when using a custom persistence mechanism and how best to leverage those features.