Boxcarring

Boxcarring is a method of grouping a set of service calls together and executing them at once. When applicable, a boxcarring session works in a transactional manner, when used with an RDBMS data source for example.

The WSO2 Data Services Server facilitates boxcarring by grouping service calls in the server side. As a result, special service clients are not required and as usual, successive service calls can be made to the server to participate in a boxcarring session.

For boxcarring to function, a transport that supports session management, such as HTTP, must be used, The service client should also support session management by returning back session cookies when sent by the server. Axis2 Service Clients have full support for session management.

Boxcarring is disabled in a data service by default. Follow the instructions to enable boxcarring in data services.

1. Log on to the Data Services Server Management Console.

2. Click the Main tab and select the Create link under Data Services.

3. The Create Data Service page appears. Fill in the fields.

The Data Service name is mandatory. Tick the boxcarring check box to enable it.

For more information on adding/editing a data service, refer to section: Create a Data Service Using Various Data Sources.

When boxcarring is enabled, the following control operations get automatically added to a data service.

• begin_boxcar : A boxcarring session must be started by calling this operation. Once this is called, the server is notified that the subsequent operation calls belong to this boxcarring session. The server stores these calls without executing them immediately.
• end_boxcar : After begin_boxcar is called, the actual operations that belong to the boxcarring session follow. The last step is executing the grouped operations and ending the boxcarring session. This is done with the end_boxcar operation. Once this is called, all the grouped operations are executed at once and the boxcarring session ends.
• abort_boxcar : If an error occurs in a boxcarring session, the user can choose to end the session by calling the abort_boxcar operation. This invalidates the boxcarring session and removes all pending operations in it.

After calling end_boxcar, results are not returned to the client since there are multiple service calls executed at once. If there are any results in the operations of the boxcarring session, they will be discarded.

Using Axis2 Service Clients

When using Axis2 Service Clients in executing a boxcarring session, the session management functionality must be enabled. The following code snippet shows the process of enabling session in the client and invoking operations in a boxcarring session.

RDBMSSampleStub stub = new RDBMSSampleStub(epr);
stub._getServiceClient().getOptions().setManageSession(true);
stub.begin_boxcar();
stub.addEmployee(49001, "Smith", "John", "john@test.com", 10000.0);
stub.incrementEmployeeSalary(5000.0, 1002);
stub.incrementEmployeeSalary(4500.0, 1003);
stub.end_boxcar();

In line 2 of the code segment above, the client is requested to handle sessions. This command is required because the boxcarring sessions will not be created in the server side otherwise.

The three operation calls that follow the begin_boxcar operation, belong to the newly created boxcarring session. When end_boxcar is called, the earlier three operations will be executed together as a group, in one transaction.

Also refer to Query Result Export.

A demonstration of the boxcarring facility is found at Boxcarring Demo in the Data Services Server examples section.