Class sap.ui2.srvc.ODataWrapper

Defined in: ODataWrapper.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	sap.ui2.srvc.ODataWrapper(sBaseUrl, oODataService, bSupportsChangeSets) Constructs a wrapper around `OData`, providing CSRF token handling, caching and generic batch support.

Method Summary
Method Attributes	Method Name and Description
<inner>	addGlobalSapHeaders(oHeaders) Gets an object supposed to be the headers object used for OData requests.
<inner>	addStickySessionHeader(oHeaders) Adds previously detected sticky session headers to the given object (which is supposed to be the headers object used for OData requests).
	check(fnSuccess, fnFailure) Checks that the given callback functions are really functions.
	create(sRelativeUrl, oPayload, fnSuccess, fnFailure) Wrapper around `OData.request` which is able to automatically fetch a CSRF token if required.
	del(vEntity, fnSuccess, fnFailure) Wrapper around `OData.request` which is able to automatically fetch a CSRF token if required.
	enableStickySession() Configures and activates session stickiness.
	getBaseUrl() Returns the wrapper's base URL.
	getODataService() Returns this wrapper's facade to an OData service (which was passed to the constructor sap.ui2.srvc.ODataWrapper).
	isBatchQueueOpen() Checks whether the queue of requests is already open or not
	isStickySessionEnabled() Checks whether session stickyness is configured and enabled
	onError(sMethod, sRequestUrl, fnFailure, oDeferred, oError) Wraps the given generic OData failure handler.
	openBatchQueue() Opens a new queue where all requests are parked until a call to #submitBatchQueue.
	put(sRelativeUrl, oPayload, fnSuccess, fnFailure) executes a put request
	read(sRelativeUrl, fnSuccess, fnFailure, bCache) Wrapper around `OData.read` which supports caching.
	submitBatchQueue(fnBatchAccepted, fnBatchItselfFailed) Submits the current batch queue opened by #openBatchQueue by sending a single "$batch" request to the OData service and deletes the current batch queue immediately.
	toString(bVerbose) Returns this wrapper's string representation.
	update(oEntity, fnSuccess, fnFailure) Generic entity update method.

Class Detail

sap.ui2.srvc.ODataWrapper(sBaseUrl, oODataService, bSupportsChangeSets)

Constructs a wrapper around OData, providing CSRF token handling, caching and generic batch support. The sap-statistics header is automatically added to all requests if the URL query parameter sap-statistics=true is set (see SAP Performance Statistics). If OData is missing, "sap.ui.thirdparty.datajs" is required automatically.

The preferred way to call the constructor is from a "sub-class" of sap.ui2.srvc.ODataService:

  function Service() {
    var oWrapper = new sap.ui2.srvc.ODataWrapper(sBaseUrl, this, bSupportsChangeSets);
    sap.ui2.srvc.ODataService.call(this, oWrapper, fnDefaultFailure);
  }
  var myService = new Service();

This provides public inheritance of sap.ui2.srvc.ODataService methods and private inheritance of sap.ui2.srvc.ODataWrapper methods. In case you are not providing a public "sub-class" of sap.ui2.srvc.ODataService but only want to use methods from sap.ui2.srvc.ODataWrapper, sap.ui2.srvc.createODataWrapper is the preferred way to construct an instance.

Parameters:
{string} sBaseUrl: base URL of the OData service, e.g. "/OData/OData.svc"
{sap.ui2.srvc.ODataService} oODataService: facade to any OData service, keeping track of CSRF token and default error handler (see #getODataService)
{boolean} bSupportsChangeSets Optional, Default: false: Whether the OData service supports change sets with multiple operations bundled into a single logical unit of work. Otherwise each modifying operation is isolated in a change set of its own.

Since:: 1.19.0

Method Detail

<inner> {object} addGlobalSapHeaders(oHeaders)

Gets an object supposed to be the headers object used for OData requests. Adds headers set as static properties of sap.ui2.srvc.ODataWrapper. The following headers may be added: - sap-language - sap-statistics - sap-client

Parameters:
{object} oHeaders Optional, Default: {}: optional object supposed to be the headers object used for OData requests

Returns:: {object} returns oHeader (if not given, a new object is created) additional headers may be added as properties to the object.

<inner> {object} addStickySessionHeader(oHeaders)

Adds previously detected sticky session headers to the given object (which is supposed to be the headers object used for OData requests).

Parameters:
{object} oHeaders Optional, Default: {}: optional object supposed to be the headers object used for OData requests

Returns:: {object} returns oHeader (if not given, a new object is created) additional headers may be added as properties to the object.

check(fnSuccess, fnFailure)

Checks that the given callback functions are really functions. This check is useful to "fail fast" because these callbacks are not called immediately.

Parameters:
{function} fnSuccess: success callback
{function} fnFailure: error callback

Since:: 1.19.0

create(sRelativeUrl, oPayload, fnSuccess, fnFailure)

Wrapper around OData.request which is able to automatically fetch a CSRF token if required. It uses POST as a method.

Parameters:
{string} sRelativeUrl: a string containing the relative URL w.r.t. this OData wrapper's base URL, e.g. "Products"
{object} oPayload: payload of the request (in intermediate format)
{function(object)} fnSuccess Optional: callback function that is executed if the request succeeds, taking the processed data
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Defaults to the OData service facade's default error handler

Since:: 1.19.0

del(vEntity, fnSuccess, fnFailure)

Wrapper around OData.request which is able to automatically fetch a CSRF token if required. It uses DELETE as a method.

Parameters:
{string|object} vEntity: either a string containing the relative URL w.r.t. this OData wrapper's base URL, e.g. "Products(1)", or the datajs representation of the entity
{function()} fnSuccess Optional: callback function that is executed if the request succeeds, taking no data
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Defaults to the OData service facade's default error handler

Since:: 1.19.0

enableStickySession()

Configures and activates session stickiness. Session stickiness allows the client to execute OData requests to the same application server. This is achieved by copying a certain sticky session header (found in the OData response from the server) to the OData request made by ODataWrapper, indicating the load balancer that requests should be made against a certain application server. Once detected, the sticky header is automatically shared by all instances of sap.ui2.srvc.ODataWrapper connected to exactly the same base URL. NOTE: The sticky session header sent from the server always overrides the last sticky session header requested. This is to avoid that the feature is disabled if the load balancer returns another value for the sticky session header for some reason (e.g. the application server goes offline). NOTE: In line with sap.ui2.srvc.PageBuildingService, session stickiness is only supported in scopes different from PERS. Currently, session stickiness is affected by the following limitations:

If the client caches the response headers for certain requests, these cached headers will be used instead of the headers sent from the server (as in if cache was disabled).
If initial requests to different URLs that share the same base URL are performed asynchronously (e.g. through multiple instances of ODataWrapper), sticky session may be disabled for a part or all of these initial requests. This is because the requests are made before the first response with a sticky session header is obtained.
This mechanism only guarantees that requests are forwarded to the specified application server. For example, if the application server in turn contacts further load balanced servers, the session may not be maintain and load balancing may still occur.

Since:: 1.30.0

{string} getBaseUrl()

Returns the wrapper's base URL.

Since:: 1.19.0

Returns:: {string} base URL of the OData service, e.g. "/OData/OData.svc/"

{sap.ui2.srvc.ODataService} getODataService()

Returns this wrapper's facade to an OData service (which was passed to the constructor sap.ui2.srvc.ODataWrapper).

Since:: 1.19.1

Returns:: {sap.ui2.srvc.ODataService} this wrapper's facade to an OData service.

{boolean} isBatchQueueOpen()

Checks whether the queue of requests is already open or not

Since:: 1.34.0

Returns:: {boolean} true if batchQueue is already open

See:: #openBatchQueue; #submitBatchQueue

{boolean} isStickySessionEnabled()

Checks whether session stickyness is configured and enabled

Since:: 1.30.0

Returns:: {boolean} whether the sticky session header is configured and active

onError(sMethod, sRequestUrl, fnFailure, oDeferred, oError)

Wraps the given generic OData failure handler. It processes the raw OData error response object, calls the given failure handler with an error message and, since version 1.28.6, an object containing additional technical details. If a Deferred object is given, it is rejected with the same arguments passed to the failure handler call. This method logs technical information to the console if this is available at the time the error occurs.

Parameters:

{string} sMethod

the HTTP method used in the OData request, e.g. "POST"

{string} sRequestUrl

the absolute URL the request is sent to

{function (string|[object])} fnFailure

the wrapped failure handler that will be called synchronously. The first parameter is a human-readable error message containing technical information, including sMethod and sRequestUrl; the second parameter is an optional object containing the complete error information returned in the error value contained in the body of the OData error response object, plus the HTTP response status code. For example, the returned error object has the following structure:

  {
    httpStatus: 404,
    // ... other keys and values from oError.response.body.error
  }

Please refer to the documentation of the specific OData service used for details about keys and values returned in oError.response.body.error.
IMPORTANT: the second parameter may be undefined if the error cannot be parsed or is not returned in the OData error response.
NOTE: the second parameter is returned since version 1.28.6.

{jQuery.Deferred} oDeferred Optional

a jQuery.Deferred object that will be rejected with the same arguments fnFailure is called

{object} oError

error object provided by datajs, should contain the response

Since:: 1.19.0

openBatchQueue()

Opens a new queue where all requests are parked until a call to #submitBatchQueue.

Since:: 1.19.0

See:: #isBatchQueueOpen; #submitBatchQueue

put(sRelativeUrl, oPayload, fnSuccess, fnFailure)

executes a put request

Parameters:
{string} sRelativeUrl: the relative URL to use
{object} oPayload: the payload
{function ()} fnSuccess Optional: callback function that is executed if the request succeeds, taking no data
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Defaults to the OData service facade's default error handler

read(sRelativeUrl, fnSuccess, fnFailure, bCache)

Wrapper around OData.read which supports caching.

Parameters:
{string} sRelativeUrl: a string containing the relative URL w.r.t. this OData wrapper's base URL, e.g. "Products(1)"
{function(object)} fnSuccess: a callback function that is executed if the request succeeds, taking the processed data
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Defaults to the OData service facade's default error handler (sap.ui2.srvc.ODataService#getDefaultErrorHandler)
{boolean} bCache Optional, Default: false: whether the response is cached for further calls (since 1.11.0) in OData.read.$cache, a sap.ui2.srvc.Map from sRequestUrl to a jQuery.Deferred object created on demand; without this flag, the cache is neither written nor read!

Since:: 1.19.0

submitBatchQueue(fnBatchAccepted, fnBatchItselfFailed)

Submits the current batch queue opened by #openBatchQueue by sending a single "$batch" request to the OData service and deletes the current batch queue immediately.

Parameters:
{function()} fnBatchAccepted Optional: A callback function that is executed if the batch request is accepted by the server, no matter whether individual operations fail. It will be called after all success or failure handlers of individual operations.
{function(string|[object])} fnBatchItselfFailed Optional: A callback function that is executed if the batch request itself fails, error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details.
Defaults to the OData service facade's default error handler (sap.ui2.srvc.ODataService#getDefaultErrorHandler).
This is called instead of individual failure handlers in this case!

Since:: 1.19.0

See:: #openBatchQueue; #isBatchQueueOpen

{string} toString(bVerbose)

Returns this wrapper's string representation.

Parameters:
{boolean} bVerbose Optional, Default: false: flag whether to show all properties

Since:: 1.19.0

Returns:: {string} this wrapper's string representation

update(oEntity, fnSuccess, fnFailure)

Generic entity update method.

Parameters:
{object} oEntity: the datajs representation of the entity
{function ()} fnSuccess Optional: callback function that is executed if the request succeeds, taking no data
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Defaults to the OData service facade's default error handler

Since:: 1.19.0

Classes

Class sap.ui2.srvc.ODataWrapper