$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.
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.
For more information, see http://www.odata.org/documentation/operations.
At present, content ID referencing in a change set is not supported for $batch.
Custom header ($batch response header) is supported for $batch requests.
A selection of generic HTTP headers for $batch requests are available for the data provider when processing each $batch operation.
Performance improvement for $batch change-set processing when the data providers is able to handle the entire operation of change set at once at end of change set. For this to be possible the data provider must implement the change set handling API to process all change set operations within one API (CHANGESET_PROCESS) and return the consolidated result of all operations to the SAP NetWeaver Gateway framework.
All retrieve operations and change sets of $batch requests are transferred at once from the SAP NetWeaver Gateway hub system to the backend system for processing.
All consecutive retrieve operations (until a change set) are processed in parallel to improve performance. You can use the implementation guide (IMG) to activate or deactivate the parallelization. See also Define Parallelization of Batch Queries.
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.
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.
For more information on the API see the method documentation for CHANGESET_BEGIN and CHANGESET_END of /IWBEP/IF_MGW_APPL_SRV_RUNTIME.
For more information on OData operations, see
http://www.odata.org/documentation/operations.