[Download] | [Documentation Home] | [Release Note]
Boxcarring is a method of grouping a set of service calls together and executing them at once. And also, when applicable, a boxcarring session would work in a transactional manner, for example, when using with an RDBMS data source. WSO2 Data Services Server fascilitates boxcarring by grouping service calls in the server side, so with this, special service clients are not required, and as usual, successive service calls can be made to the server to participate in a boxcarring session.
In order for boxcarring to function, a transport that supports session management must be used, i.e. HTTP. And the service client should also support handling session management, which is, returning back session cookies when sent by the server. Axis2 Service Clients has full support for session management.
By default, boxcarring is disabled in a data service, and has be explicitely enabled in a data service. When using the wizard, at the initial "Service Details" page, select "Enable Boxcarring" to "True".
Figure 1: Enabling Boxcarring in a data service.
When boxcarring is enabled in a data service, the following control operations are automatically added to a data service.
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 inside 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 the above code, we see that in the 2'nd line, we are telling the client, that sessions should be handled. This is required, or else the boxcarring sessions will not be created in the server side. The after the "begin_boxcar" operation is called, the following three operation calls belong to the newly created boxcarring session. Then at the end when "end_boxcar" is being called, the earlier three operations will be executed together as a group, in one transaction.
For a demonstration of the usage of boxcarring, refer to the boxcarring demo in the samples.
This is a feature that must be used in conjunction with boxcarring. What this provides is an approach for individual queries to be executed in a boxcarring session to communicate with each other. The concept is 'exporting' a specific result element so the next calling query will get that result element as a query parameter. So if you've two queries '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 has 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 specially useful in situations where, if in a boxcarring session, some result value of an earlier executed query is required (e.g. a newly created primay key) for the execution of a subsequent query. In a situation like that, the query result export feature can be used.
In Figure 2 shows how a result element can be declared to be exported with a given name.
Figure 2: Exporting a result element from a query.
There are two export types that can be used.
For a demonstration of the usage of query result export, refer to the query result export demo in the samples.