Package 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`.

Note that the Smart GWT SDK includes detailed Javadoc reference for this servlet and all shipped Smart GWT Java server classes.

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
- Checks the DataSource configuration for customizations implemented via `server scripting` or `DMI` - in other words, your code - and passes the request to this logic.

  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
- The `DataSource.serverType` specification within your `.ds.xml` configuration file is used to specify a standard server-side connector to service your requests.
- 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 modify the dataSource request dynamically at transaction-processing time, using built-in `Velocity support`.
  Note this feature also allows developers to use `Transaction Chaining` to dynamically set data values according to the results of earlier transactions.
- For editing, standard `DataSourceField.validators` defined in the `.ds.xml` file will be processed on both the client and the server. In addition to the built-in validator types, entirely custom server validation logic may be implemented using `"serverCustom" type validators`.
- For SQL DataSources, use `SQL Templating` to change, add to or even completely replace the SQL sent to the database, including calling stored procedures
- The `DataSource.serverConstructor` allows you to specify an explicit custom DataSource subclass to create as your DataSource instance. This must be a subclass of `BasicDataSource`.
  When requests are recieved by the `IDACall` servlet, they will be passed to standard methods on this DataSource, which can be overridden for custom behavior.
  Validation is performed via a call to the `validate()` method.
  The request is processed by the `execute()`, method which can be overridden directly, or developers may override the operation-specific methods `executeFetch()`, `executeAdd()`, `executeUpdate`, or `executeRemove()` called from the standard `execute()` implementation.
  This approach allows you to either extend one of the built-in persistence mechanisms by subclassing a shipped class such as `SQLDataSource`, or create an entirely custom implementation from scratch.
  A custom dataSource will still take full advantage of DataSource-agnostic features of the Smart GWT Server, like validation, queuing, transaction chaining, support for Velocity templating, and so on.
  For more information see the `custom server dataSource overview`
- Use `Direct Method Invocation` to call directly into your own Java classes. An operation configured to use DMI will invoke the specified method instead of running through the standard DataSource `execute()` method directly - the DMI implementation can then use `dsRequest.execute()` to call the default behavior. This means DMIs allow you to modify the `DSRequest` before it executes, modify the `DSResponse` before it returns, or replace the default behavior with unrelated actions. Note that DMI can be applied `to all operations`, or to `individual operation bindings`, and can be used in conjunction with a `custom dataSource`.
- Use `server scripting` to add small amounts of business logic right in your `.ds.xml` file (either `per operation`, or as standard handling for `all operations`). 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 some other similar system which requires that all requests go through some particular servlet - just call `RPCManager.processRequest()` within your Spring Controller 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 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 Queuing examples.

For more information on the DMI subsystem, see the `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 `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 `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 `RPCManager documentation`, and the Custom ORM DataSource example.

See Also:
  - `DSDataFormat`
  - `DSServerType`
  - `DataSource.getDataFormat()`
  - `DataSource.getDataProtocol()`
  - `DataSource.getRequestProperties()`
  - `DataSource.serverType`
  - `DataSource.tableName`
  - `DataSource.quoteTableName`
  - `DataSource.dbName`
  - `DataSource.configBean`
  - `DataSource.forceSort`
  - `OperationBinding.forceSort`
  - `DataSource.defaultSortField`
  - `DataSource.getDefaultTextMatchStyle()`
  - `DataSource.getArrayCriteriaForceExact()`
  - `OperationBinding.getArrayCriteriaForceExact()`
  - `DSRequest.getArrayCriteriaForceExact()`
  - `DataSource.defaultBooleanStorageStrategy`
  - `DataSource.useAnsiJoins`
  - `DataSource.audit`
  - `com.smartgwt.client.data.DataSource#getServerObject`
  - `OperationBinding.getRequestProperties()`
  - `DataSource.suppressManualAggregation`
  - `RestDataSource.getDataProtocol()`