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 'Data Service Hosting' feature 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.

1. Log on to the product's management console and select "Data Service -> Create" under the "Main" menu.

2. The Create Data Service page appears. 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 page "Create a Data Service Using Various Data Sources" in section "Data Services Management -> Deploying Data Services."

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.

A demonstration of the boxcarring facility is found in "Boxcarring Demo" of the Data Services Server 2.6.3 Documentation.

Query Result Export

Query Request Export feature must be used in conjunction with boxcarring. It allows individual queries executed in a boxcarring session to communicate with each other. The concept is 'exporting' a specific result element so that the next calling query will get that result element as a query parameter. So, if you've two queries, namely, 'query1' and 'query2' that's executed sequentially in a boxcarring session, and if 'query1' has a specific result element and that element is exported with the name 'foo', then 'query2' also gets a query param named 'foo'. So when this boxcarring session is executed, the query1's exported value will be passed into query2 as an input parameter.

This feature is very useful in situations where the result of an earlier-executed query is required for the execution of a subsequent query (e.g. a newly created primay key).

The following figure shows how a result element can be declared to be exported with a given name when defining a query in a data service.

There are two export types that can be used.

• SCALAR : The single element value is exported. If there are multiple instances of this value, the last one will be exported.
• ARRAY : An array of values will be exported. Each occurrence of the value is added to an array and exported.
  

For a demonstration on the usage of export options, refer to the "Query Result Export demo" in the Data Services Server 2.6.3 Documentation.