$batch Processing

Clients can search for and change resources exposed by a data service, in a way that each request type maps to a single HTTP request/response exchange. As these request types are based on HTTP, the usual HTTP services are also available, such as caching. In this context clients of a data service can collect or “batch up” several requests and then send that batch to the data service in a single HTTP request.

You can use $batch to collect a fixed number of operations (retrieve, create, update, delete) of an OData service in one single HTTP POST request.

Batch Request

An OData batch request is represented as a multipart MIME v1.0 message (see RFC2046 under http://www.rfc-editor.org/rfc/rfc2046.txt ), a standard format allowing the representation of multiple parts, each of which may have a different content type, within a single request.

Batch requests allow grouping of multiple operations (as described in OData: Operations under http://www.odata.org/documentation/operations ) into a single HTTP request payload.

Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service as described in OData: URI Conventions under http://www.odata.org/documentation/uri-conventions .

The body of a batch request is made up of an ordered series of retrieve operations and/or change sets. A change set is an atomic unit of work that is made up of an unordered group of one or more of the insert, update or delete operations. Change sets cannot contain retrieve requests and cannot be nested, that is, a change set cannot contain a change set.

In the batch request body, each retrieve request and change set is represented as a distinct MIME part and is separated by the boundary marker defined in the Content-Type header of the request. The contents of the MIME part which represents a change set is itself a multipart MIME document with one part for each operation that makes up the change set.

Each MIME part representing a retrieve request or change set within the batch includes both Content-Type and Content-Transfer-Encoding MIME headers as seen in the examples below. The batch request boundary is the name specified in the Content-Type Header for the batch.

For more information, see http://www.odata.org/documentation/operations .

Batch Response

The batch response contains a Content-Type header specifying a content type of multipart/mixed and a batch boundary specification, which may be different from the batch boundary that was used in the corresponding request.

Within the body of the batch response is a response for each retrieve request and change set that was in the associated batch request. The order of responses in the response body must match the order of requests in the batch request. Each response includes a Content-Type header with a value of application/http , and a Content-Transfer-Encoding MIME header with a value of binary .

A response to a retrieve request is formatted exactly as it would have appeared outside of a batch.

The body of a change set response is either a response for all the successfully processed change request within the change set, formatted exactly as it would have appeared outside of a batch, or a single response indicating a failure of the entire change set.

If the set of HTTP request headers of a batch request are valid, the HTTP response status code is always 202 (Accepted). This is irrespective of whether some retrieve operations or change sets within this batch request fail or not.

As defined in the OData specification for batch processing , in case an operation within a change set fails the batch response body contains only one single response for this change set indicating the failure of the entire change set.

For more information, see http://www.odata.org/documentation/operations .

Constraints

At present, content ID referencing in a change set is not supported for $batch.

Handling Operations in Batch Requests

Each retrieve operation such as Read Entry or Read Feed within a $batch request will be transferred separately from the SAP NetWeaver Gateway hub system to the provider application in the backend system for processing.

Every change set is treated as one Logical Unit of Work (LUW), ensuring its “all or nothing” character. All operations of a change set will be sent at once from the SAP NetWeaver Gateway hub system to the provider application in the backend system for processing.

Results of all operations will be collected at the SAP NetWeaver Gateway hub system and sent as one HTTP response to the OData consumer.

Additional Application API for $batch

For retrieve operations there is no special handling required. But to ensure the “all or nothing” character of a change set there are two additional methods for change set handling in interface /IWBEP/IF_MGW_APPL_SRV_RUNTIME :

/IWBEP/IF_MGW_APPL_SRV_RUNTIME~CHANGESET_BEGIN

All operations within a change set must be treated as a logical unit of work. This means all or nothing. Therefore, a provider must not issue COMMIT WORK or ROLLBACK WORK during change set processing. Otherwise, the framework will abandon the change set processing. If the change set contains only one operation, the check of commit or rollback is deactivated.

At the beginning of a change set processing, the provider will be called with this method. It can check the list of all involved entity types and actions contained in this change set and accept the change set handling or reject it by raising a technical exception with exception code CHANGESET_NOT_SUPPORTED . The method has a default implementation which allows only one operation per change set in order to guarantee transactional consistency. If more than one operation is required in a change set the implementation has to be overwritten by the application. The application then needs to ensure transactional consistency, for example not to have any commit or rollback in the chain of requests in a change set.

Additionally, the provider can start collecting the content of a change set in the modifying method calls, for example update entity, and finalize it within the CHANGESET_END method call described below.
/IWBEP/IF_MGW_APPL_SRV_RUNTIME~CHANGESET_END

If the provider only updates all modifications of a change set in internal tables, it can now update the database. A COMMIT WORK will be issued by the framework at the end of this API.

Example

Syntax Syntax

Example 1 for read entity
=========================
Batch Request Header
POST  .../sap/opu/odata/IWFND/RMTSAMPLEFLIGHT/$batch
Content-Type  multipart/mixed;boundary=batch_01869434-0001
Batch Request Body
--batch_01869434-0001
Content-Type: application/http
Content-Transfer-Encoding: binary
<at least one "carriage return line feed">
GET CarrierCollection(carrid='AA') HTTP/1.1
<at least two "carriage return line feed">
--batch_01869434-0001
Content-Type: application/http
Content-Transfer-Encoding: binary
<at least one "carriage return line feed">
GET TravelagencyCollection(agencynum='00001755') HTTP/1.1
<at least two "carriage return line feed">
--batch_01869434-0001--

End of the code.

Syntax Syntax

Example for two changesets with one operation in each changeset
=================================================================
Batch Request Header
POST  .../sap/opu/odata/IWFND/RMTSAMPLEFLIGHT/$batch
Content-Type  multipart/mixed;boundary=batch_01869434-0006
Batch Request Body
--batch_01869434-0006
Content-Type: multipart/mixed; boundary=changeset_01869434-0006-0001
<at least one "carriage return line feed">
--changeset_01869434-0006-0001
Content-Type: application/http
Content-Transfer-Encoding: binary
<at least one "carriage return line feed">
PUT TravelagencyCollection(agencynum='00001755') HTTP/1.1
Content-Type: application/atom+xml
Content-Length: 1021 (This length must be equal to or greater than the real length of the data below)
<at least one "carriage return line feed">
<update data for agencynum='00001755'>
--changeset_01869434-0006-0001--
--batch_01869434-0006
Content-Type: multipart/mixed; boundary=changeset_01869434-0006-0002
<at least one "carriage return line feed">
--changeset_01869434-0006-0002
Content-Type: application/http
Content-Transfer-Encoding: binary
PUT TravelagencyCollection(agencynum='00001756') HTTP/1.1
Content-Type: application/atom+xml
Content-Length: 1021 (This length must be equal to or greater than the real length of the data below)
<at least one "carriage return line feed">
<update data for agencynum='00001756'>
--changeset_01869434-0006-0002--
--batch_01869434-0006--
Batch Response Header
Status Code/Reason  202 (Accepted)
Content-Type  multipart/mixed; boundary=ejjeeffe0
Batch Response Body
--ejjeeffe0
Content-Type: multipart/mixed; boundary=ejjeeffe1
Content-Length:       215
--ejjeeffe1
Content-Type: application/http
Content-Length: 96
content-transfer-encoding: binary
HTTP/1.1 204 No Content
Content-Type: text/html
Content-Length: 0
dataserviceversion: 2.0
--ejjeeffe1--
--ejjeeffe0
Content-Type: multipart/mixed; boundary=ejjeeffe1
Content-Length:       215
--ejjeeffe1
Content-Type: application/http
Content-Length: 96
content-transfer-encoding: binary
HTTP/1.1 204 No Content
Content-Type: text/html
Content-Length: 0
dataserviceversion: 2.0
--ejjeeffe1--