[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.
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();
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.