com.smartgwt.client.docs

Interface ServerDataIntegration

public interface ServerDataIntegration

Server DataSource Integration

Server Data Integration means:

• You install the Smart GWT Java Server Framework into any J2SE/J2EE environment, including any existing web application
• You create DataSources via an XML declaration, possibly on-the-fly from existing metadata.
• Server communication for components bound to these DataSources is handled automatically with a highly efficient, compressed protocol. You work with clean Java APIs instead of dealing with the details of XML or JSON over HTTP.
• You can use built-in connectors for SQL, Hibernate and other common data providers without writing any code, or you can easily build your own connectors in Java.
• Whether using the built-in connectors or custom connectors, declarations in your DataSource control a large set of server features that can make common types of business logic entirely declarative

This approach is in contrast to Client-side Data Integration in which client-side DataSources are configured to send and receive HTTP messages containing XML, JSON or other content.

Server-side Request Processing

Client-side DataBoundComponents will send DSRequests to the Smart GWT Server as background communications transparent to the user. Integrating Smart GWT's DataSource layer with your data model is a matter of handling these DSRequests and sending back DSResponses, in order to fulfill the 4 basic operations of the DataSource Protocol.

Out of the box, Smart GWT is set up to route all DSRequests through a special servlet called IDACall. Requests that go through IDACall have the following lifecycle:

• The overall HTTP request is received by the IDACall servlet. Smart GWT supports queuing of transactions, so each HTTP request might contain multiple DSRequests.
• IDACall sets up an instance of RPCManager to manage the processing of the entire queue of transactions. For every DSRequest in the queue, this RPCManager:
• Validates the DSRequest
• Sends the DSRequest through DMI - in other words, your code - if this is configured in the DataSource. As described later in this section, your code can perform some custom logic here: either completely fulfilling the request, or alternatively modifying the request and causing the default processing of the request to continue
• Calls the DataSource's execute method to obtain a DSResponse.
• Having processed all requests, the RPCManager now serializes all the DSResponses and sends them back to the browser as a single HTTP response

This basic request handling flow can be customized at a number of points:

• If you need an overarching authentication service, this is best implemented using servlet Filters to intercept unauthenticated requests before they reach the IDACall servlet
• If you are not using one of the built-in persistence mechanisms (SQL and Hibernate), hook into the IDACall flow by writing a custom DataSource. This approach lets you write and maintain the minimal amount of custom code, while taking full advantage of DataSource-agnostic features of the Smart GWT Server, like validation, queuing, transaction chaining, support for Velocity templating, and so on.
• Custom validation can be added by writing a custom DataSource (extending SQLDataSource or HibernateDataSource if appropriate) and overriding its validate() method, as described here.
• General custom business logic can be added in a number of ways, both declaratively and programmatically:
• The <criteria> and <values> properties of an OperationBinding allow you to dynamically set data values at transaction-processing time, using built-in Velocity support
• Override the execute() method of the DataSource to add extra processing before and/or after the Smart GWT processing
• Use Transaction Chaining to dynamically set data values according to the results of earlier transactions
• For SQL DataSources, use SQL Templating to change, add to or even completely replace the SQL sent to the database, including calling stored procedures
• Use Direct Method Invocation to call directly into your own Java classes. DMIs allow you to modify the DSRequest before it executes, modify the DSResponse before it returns, or take unrelated actions. They can be used to add business logic to a persistence operation without destroying the default behavior
• Use DMI Scripts to add small amounts of business logic right in the <operationBinding> tag. DMI scripts allow you to add business logic just like normal DMIs, but don't require the logic to be in a separate .java file.


• If you need to use a Front Controller servlet for some other reason than authentication - for example, you are using Spring, Struts, or some other similar system which requires that all requests go through some particular servlet - just call RPCManager.processRequest() within your Spring Controller, Struts Action, or whatever the equivalent is in the framework in use.

  However, note carefully that taking this approach is often a sign that the Smart GWT architecture has not been correctly understood. Smart GWT is architected for client-server data communication, as opposed to early web MVC frameworks which do everything on the server. In particular, it is absolutely incorrect to represent every individual DataSource operation - or even every DataSource - as a separate Struts Action or Spring Controller, because this implies different URLs for different operations. All DataSource operations should go through a single URL in order to allow transaction queuing - see these

See Also:

Queuing examples.

For more information on the DMI subsystem, see the {@link com.smartgwt.client.docs.DmiOverview DMI overview}, DMI class and the DMI example in the Feature Explorer.

Note that, as you continue to integrate your prototype with your backend, you can use a mixture of DataSources that have been fully integrated with your backend and DataSources that are running in "client-only" mode (see {@link com.smartgwt.client.docs.ClientOnlyDataSources}).

Important methods for handling DataSource requests

The basic flow of logic for handling DataSource requests is:

1. Determine operation type (Fetch, Add, Update, Remove) for a single request. Not necessary if you follow the recommendations for {@link com.smartgwt.client.docs.WriteCustomDataSource writing a custom DataSource} and provide your implementation via executeFetch(), executeAdd(), et al.	dsRequest.getOperationType()
2. Get inbound values (Add, Update) and/or criteria (Fetch, Update, Remove) for this request.	dsRequest.getFieldValue() dsRequest.getValues() dsRequest.getCriteria()
3. Business logic, validation, calls to data and service tiers... anything you can code.	execute custom logic
4. Set status and data for the response.	dsResponse.setStatus() dsResponse.setData()

For more information, see the {@link com.smartgwt.client.rpc.RPCManager RPCManager documentation}, and the Custom ORM DataSource example., DataSource.getDataFormat(), DataSource.getDataProtocol(), DataSource.getRequestProperties(), com.smartgwt.client.docs.serverds.DataSource#serverType, com.smartgwt.client.docs.serverds.DataSource#tableName, com.smartgwt.client.docs.serverds.DataSource#quoteTableName, com.smartgwt.client.docs.serverds.DataSource#dbName, com.smartgwt.client.docs.serverds.DataSource#configBean, DataSource.getDefaultTextMatchStyle(), com.smartgwt.client.docs.serverds.DataSource#useAnsiJoins, com.smartgwt.client.docs.serverds.DataSource#audit, com.smartgwt.client.data.DataSource#getServerObject, OperationBinding.getRequestProperties(), RestDataSource.getDataProtocol(), DSDataFormat, DSServerType