com.smartgwt.client.docs

## Interface DsFacade

-     public interface DsFacade

  ### DataSource Facade pattern

  The DataSource Facade pattern means implementing a DataSource that fulfills its `DSRequests` by passing them on to another DataSource.

  This can be useful for:

  - various testing purposes, such as introducing long delays or intermittent failures to see how your code responds
  - implementing application-specific caching behaviors that go beyond `DataSource.cacheAllData` or automatic caching done by `ResultSet`
  - providing DSResponses that make use of data from two or more DataSources, by sending DSRequests to those other DataSources, waiting for both to respond, then combining the response data (note that for something like a SQL join, you should instead use `DataSourceField.includeFrom` if you have Smart GWT Pro or better)
  - slight modifications of data returned by another DataSource (although consider just using `OperationBinding.operationId` for this)

  This facade pattern can be implemented either server-side or client-side:

  - server-side (Smart GWT Pro or better), implement a custom DataSource (see QuickStart Guide) and implement the server-side API DataSource.execute() by calling DataSource.execute() on some other DataSource, then return the DSResponse that results.
  - client-side, use `dataProtocol:"clientCustom"`. The `FacadeDataSource` provides a specific implementation that is useful for testing purposes. Alternative, the code below shows the simplest possible code for the facade pattern when implemented client-side via `dataProtocol:"clientCustom"` - requests are forwarded to another DataSource, and the responses are returned completely unchanged.
  - When changes are made to the primary DataSource, DBCs that are using the facadeDataSource will not automatically update caches, since they are bound to the facadeDataSource and not to the primary DataSource which was changed. To fix this, add a call to `facadeDataSource.updateCaches()` as shown below

        DataSource facadeDataSource = null;

        DataSource supplyItemDS = DataSource.get("SupplyItem");
        supplyItemDS.addDataChangedHandler(new DataChangedHandler() {
            @Override
            public void onDataChanged(DataChangedEvent event) {
                facadeDataSource.updateCaches(event.getDsResponse());
            }
        });
        facadeDataSource = new DataSource() {
            {
                setDataProtocol(DSProtocol.CLIENTCUSTOM);
                setInheritsFrom(supplyItemDS);
            }

            @Override
            public Object transformRequest(final DSRequest dsRequest) {
                final DataSource superDS = DataSource.get(getInheritsFrom()),
                        selfDS = this;

                final DSRequest derivedDSRequest = cloneDSRequest(dsRequest);
                derivedDSRequest.setShowPrompt(false);
                derivedDSRequest.setCallback(new DSCallback() {
                    @Override
                    public void execute(DSResponse dsResponse, Object data, DSRequest derivedDSRequest) {
                        selfDS.processResponse(dsRequest.getRequestId(), superDS.cloneDSResponse(dsResponse));
                    }
                });

                superDS.execute(derivedDSRequest);

                return dsRequest.getData();
            }
        };

  Check out this example of the DataSource facade pattern being used to create a DataSource that may work with already loaded data, or may use another DataSource to fulfill its requests.