This examples page demonstrates how to configure Backbase Data Services to connect client-side widgets to any server-side data provider.

Prerequisites and Intended Audience

Software

The following software is required to build and deploy the example:

• Backbase Data Services (for Java) 1.1
• Backbase Enterprise Ajax 4.2.1 - Client Edition (Backbase_4_2_1.war)
• JDK 1.4.2 (or above)
• Application server that supports Java Servlets 2.3 (or above)

Competencies

Backbase Data Services is intended for web application developers implementing a Backbase Client front-end with an enterprise Java back-end. Experience to the level indicated is required with the following technologies:

• Java beginner
• Java EE beginner

Overview

Backbase Data Services (for Java) is an extendable Java module designed to simplify the process of binding the dataSource widget to data objects on a Java server. This example page describes how to work with a remote data source, using Backbase Data Services to mediate between the client and the remote data provider.

Data-Bound Client Widgets

The Backbase dataSource widget offers a generic way to bind data to the Backbase listGrid and treeGrid widgets, and thereby query, view and update the data. Backbase grid widgets listGrid and treeGrid can be used in combination with either a local or a remote dataSource to display and modify data.

Although designed with the Backbase listGrid and treeGrid widgets in mind, Backbase Data Services offers a server-side Java solution to connect any client technology that complies with the predefined request/response format with any server-side data provider.

Server-Side Data Services

Backbase Data Services is a Java framework that helps you to provide and synchronize your server-side data with Backbase grid widgets. It is a self-contained framework that can be incorporated into any Java Web framework that meets the stated requirements and any client technology that complies with the predefined request/response format. Features include:

• Convenient way to provide server-side data to your widgets
• Easily configured
• Data mapped to server-side data objects
• Client-side CRUD events synchronized with the server-side data provider

Deploying the Data Services JARs

Backbase Data Services is a stand-alone, server-side application that is delivered as two JARs:

• backbase-dataservices-core-1.1.0.jar—core functionality
• backbase-dataservices-servlet-1.1.0.jar—servlet bridge classes

For the Backbase Data Services to be able to process requests, the DatamoduleServlet needs to be declared in the deployment descriptor (web.xml), as follows:

In the listing, the servlet is mapped to /data/*, meaning that any URL with /data/ will map to DatamoduleServlet. In practice, it is likely that a stricter pattern will be defined.

Client-Side Implementation

In this example, Backbase widgets are used in combination with Backbase Data Services, but the procedure is valid for any client technology that supports the predefined request/response format.

Data Source Definition

The dataSource widget connects the client to the Data Services. The connection is established by setting the url attribute. Other attributes are available to define specific aspects of the connection, as follows:

• name—unique identifier that enables other widgets to bind to the dataSource.
• dataType—sets the format in which the data are returned.
• requestType—sets the format of the request parameter.

Although not a requirement, the recommendation is to define a dataSchema (and its corresponding dataField widgets) for the data source. These widgets provide a consistent interface to the data, meaning that changes to the underlying data structure have limited impact on the implementation. In the dataSchema, attributes from the bean representing a row of data are bound to dataFields.

The following listing demonstrates how to implement the dataSource with a corresponding dataSchema:

The url setting includes a actionGroupId=dataServices name / value pair that maps the request to the dataServices action group. This action group is defined in the Data Services configuration file (datamodule-config.xml).

The remoteData behavior enriches the dataSource with the methods, attributes and events needed to process remote data.

On the server side we need to provide a bean class that will represent a row from the listGrid. To bind this bean to the data source we need to provide a dataSchema element. In the dataSchema we will bind the attributes from the bean to a field in dataSource.

Widget Binding

To connect your widget to the remote data, you bind the widget to the dataSource using the dataSource attribute. The value of the attribute must match the name of the dataSource widget, as demonstrated in the listing:

Server-Side Implementation

The Backbase Data Services configuration is defined in the datamodule-config.xml file, which resides in the WEB-INF folder.

The default name of the configuration file is datamodule-config.xml. To use a different configuration file, its name is set in the deployment descriptor.

An actionGroup specifies how to serialize and deserialize a request, and is defined with a unique id.

The configuration supports a defaultActionGroupId attribute to define a default action group to process requests, meaning that if the request does not define the actionGroupId, the default will be used.

An actionGroup contains the following definitions:

• mappings—defines the bean that is bound to the request parameters. The mapping bean is specified by the record element. The attribute element is used to map other custom parameters (sent by the client) to a specific type.
• action—used to specify which ActionHandler class to call when a request is received server-side. It maps a specific class (defined by the class attribute) to a unique identifier (defined by the name attribute). The unique identifier must match the value of the corresponding request parameter action.
• domain—specifies the beans (representing data) that need to be synchronized with the client. The type element specifies the bean to be synchronized. The id specifies an attribute that will identify the row. The field element specifies the name a bean attribute can use in the client code.

To handle client-side events, the required ActionHandler classes must be implemented and declared in datamodule-config.xml file. The following listing shows the implementation of the update action:

In the ActionHandler class, handleRequest() is called by the framework to handle the requests from the client. handleRequest() accepts the following arguments:

• ActionContext—represents information about action being handled, and contains actionGroupId, actionName, and ExternalContext.
• RequestDataSource—contains all the data sent by the client to the server. Data that is mapped as a record can be retrieved (as a List) using reqds.getRecords(). Data that is mapped as an attribute can be retrieved (as a Map) using reqds.getAttributes(), as shown in the listing:
  String pageStr = (String) reqds.getAttributes("page");
• ResponseDataSource—contains all the data sent from the server to the client. Contains every attribute that you want to be sent to the client, as demonstrated in the listing:
  respds.addAttribute("records", updatedIds);

Live Demo

In the following live demo, the functionality implemented in the preceding steps is shown: Data Services Live Demo.

Additional Resources

For more information, please refer to the following documentation, examples and reference material:

• WAR version of this examples page available for download at Data Services WAR
• Client Framework Introduction to the treeGrid
• Client Framework Introduction to the dataSchema and dataField elements
• Client Framework Binding to a Remote Data Source (PHP)