com.sap.cloud.sdk.datamodel.odatav4.core

Class UpdateRequestBuilder<EntityT extends VdmEntity<?>>

java.lang.Object

com.sap.cloud.sdk.datamodel.odatav4.core.UpdateRequestBuilder<EntityT>

Type Parameters:

EntityT - The type of the result entity.

public class UpdateRequestBuilder<EntityT extends VdmEntity<?>>
extends Object

Representation of an OData request as a fluent interface for further configuring the request and executing it.

Constructor Summary

Constructors

Modifier	Constructor and Description
	UpdateRequestBuilder(String servicePath, EntityT entity) Instantiate an UpdateRequestBuilder.
protected	UpdateRequestBuilder(String servicePath, EntityT entity, ODataEntityKey entityKey) Instantiate an UpdateRequestBuilder.

Method Summary

Modifier and Type	Method and Description
UpdateRequestBuilder<EntityT>	disableVersionIdentifier() The update request will ignore any version identifier present on the entity and not send an `If-Match` header.
ModificationResponse<EntityT>	execute(HttpDestinationProperties destination) Execute the OData update request for the provided entity.
protected EntityT	getEntity() The entity object to be updated by calling the execute(HttpDestinationProperties) method.
protected Class<EntityT>	getEntityClass() Returns a class object of the type this fluent helper works with.
protected ODataEntityKey	getEntityKey()
protected Map<String,String>	getHeaders() A map containing the headers to be used only for the actual request of this FluentHelper implementation.
protected List<ODataRequestListener>	getListeners()
protected Map<String,String>	getParametersForRequestOnly() A map containing the custom query parameters to be used only for the actual request of this FluentHelper implementation.
protected String	getServicePath()
protected FluentHelperT	getThis() Get the reference to this instance.
UpdateRequestBuilder<EntityT>	includingFields(Expressions.FieldReference... fields) Allows to explicitly specify entity fields that shall be sent in an update request regardless if the values of these fields have been changed.
UpdateRequestBuilder<EntityT>	matchAnyVersionIdentifier() The update request will ignore any version identifier present on the entity and update the entity, regardless of any changes on the remote entity.
UpdateRequestBuilder<EntityT>	modifyingEntity() Allows to control that the request to update the entity is sent with the HTTP method PATCH and its payload contains the changed fields only.
UpdateRequestBuilder<EntityT>	replacingEntity() Allows to control that the request to update the entity is sent with the HTTP method PUT and its payload contains all fields of the entity, regardless which of them have been changed.
ODataRequestUpdate	toRequest() Creates an instance of the ODataRequestUpdate based on the Entity class.
io.vavr.control.Try<ResultT>	tryExecute(HttpDestinationProperties destination) Safely execute the OData request.
FluentHelperT	withHeader(String key, String value) Gives the option to specify custom HTTP headers.
FluentHelperT	withHeaders(Map<String,String> map) Gives the option to specify a map of custom HTTP headers.
FluentHelperT	withListener(ODataRequestListener listener) An error handling class that implements the error result handler interface can be attached to this fluent helper.
FluentHelperT	withQueryParameter(String key, String value) Gives the option to specify custom query parameters for the request.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UpdateRequestBuilder

public UpdateRequestBuilder(@Nonnull
                            String servicePath,
                            @Nonnull
                            EntityT entity)

Instantiate an UpdateRequestBuilder.

Parameters:

servicePath - The service path.

entity - The entity to update.

UpdateRequestBuilder

protected UpdateRequestBuilder(@Nonnull
                               String servicePath,
                               @Nonnull
                               EntityT entity,
                               @Nonnull
                               ODataEntityKey entityKey)

Instantiate an UpdateRequestBuilder.

Parameters:

servicePath - The service path.

entity - The entity to update.

entityKey - The entity key to be used in request URI.

Method Detail

getEntityClass

@Nonnull
protected Class<EntityT> getEntityClass()

Returns a class object of the type this fluent helper works with.

Returns:

A class object of the handled type.

execute

@Nonnull
public ModificationResponse<EntityT> execute(@Nonnull
                                                      HttpDestinationProperties destination)

Execute the OData update request for the provided entity. Execute the OData request.

Parameters:

destination - The destination to be used as request target.

Returns:

The wrapped service response, exposing response headers, status code and entity references. If the HTTP response is not within healthy bounds, then one of the declared runtime exceptions will be thrown with further details.

toRequest

@Nonnull
 @Beta
public ODataRequestUpdate toRequest()

Creates an instance of the ODataRequestUpdate based on the Entity class.

The following settings are used to build the Request Builder:

• the endpoint URL
• the entity collection name
• the key fields of the entity
• the entity JSON payload
• the update strategy (full update or delta)

Returns:

An initialized ODataRequestUpdate.

Throws:

ODataSerializationException - If entity cannot be serialized for HTTP request.

includingFields

@Nonnull
public final UpdateRequestBuilder<EntityT> includingFields(@Nonnull
                                                                    Expressions.FieldReference... fields)

Allows to explicitly specify entity fields that shall be sent in an update request regardless if the values of these fields have been changed. This is helpful in case the API requires to send certain fields in any case in an update request.

Parameters:

fields - The fields to be included in the update execution.

Returns:

The same fluent helper which will include the specified fields in an update request.

replacingEntity

@Nonnull
public final UpdateRequestBuilder<EntityT> replacingEntity()

Allows to control that the request to update the entity is sent with the HTTP method PUT and its payload contains all fields of the entity, regardless which of them have been changed.

Returns:

The same fluent helper which will replace the entity in the remote system

modifyingEntity

@Nonnull
public final UpdateRequestBuilder<EntityT> modifyingEntity()

Allows to control that the request to update the entity is sent with the HTTP method PATCH and its payload contains the changed fields only.

Returns:

The same fluent helper which will modify the entity in the remote system.

disableVersionIdentifier

@Nonnull
 @Beta
public UpdateRequestBuilder<EntityT> disableVersionIdentifier()

The update request will ignore any version identifier present on the entity and not send an `If-Match` header.

Warning: This might lead to a response from the remote system that the `If-Match` header is missing.

It depends on the implementation of the remote system whether the `If-Match` header is expected.

Returns:

The same request builder that will not send the `If-Match` header in the update request

matchAnyVersionIdentifier

@Nonnull
 @Beta
public UpdateRequestBuilder<EntityT> matchAnyVersionIdentifier()

The update request will ignore any version identifier present on the entity and update the entity, regardless of any changes on the remote entity.

Warning: Be careful with this option, as this might overwrite any changes made to the remote representation of this object.

Returns:

The same request builder that will ignore the version identifier of the entity to update

getEntity

@Nonnull
protected EntityT getEntity()

The entity object to be updated by calling the execute(HttpDestinationProperties) method.

getEntityKey

@Nonnull
protected ODataEntityKey getEntityKey()

getThis

@Nonnull
protected FluentHelperT getThis()

Get the reference to this instance.

Returns:

The FluentHelper instance.

tryExecute

@Nonnull
public io.vavr.control.Try<ResultT> tryExecute(@Nonnull
                                                        HttpDestinationProperties destination)

Safely execute the OData request.

Parameters:

destination - The destination to be used as request target.

Returns:

The generic OData response result wrapped in a Try block.

withListener

@Nonnull
 @Beta
public FluentHelperT withListener(@Nonnull
                                                  ODataRequestListener listener)

An error handling class that implements the error result handler interface can be attached to this fluent helper. This allows custom logic to be called when an error occurs in the execute method. If this method is not called, then an instance of ODataRequestListener is used. Only one handler can be attached at a time per fluent helper object, so calling this multiple times will replace the handler.

Parameters:

listener - Instance of an error handler class that implements the error result handler interface.

Returns:

The same fluent helper with its error handler set to the provided object.

withHeader

@Nonnull
 @Beta
public FluentHelperT withHeader(@Nonnull
                                                String key,
                                                @Nullable
                                                String value)

Gives the option to specify custom HTTP headers. The returned object allows to specify the requests the headers should be used in.

Parameters:

key - Name of the (first) desired HTTP header parameter.

value - Value of the (first) desired HTTP header parameter.

Returns:

A fluent helper to specify further headers and their intended usage.

withHeaders

@Nonnull
 @Beta
public FluentHelperT withHeaders(@Nonnull
                                                 Map<String,String> map)

Gives the option to specify a map of custom HTTP headers. The returned object allows to specify the requests the headers should be used in.

Parameters:

map - A map of HTTP header key/value pairs.

Returns:

A fluent helper to specify further headers and their intended usage.

withQueryParameter

@Nonnull
 @Beta
public FluentHelperT withQueryParameter(@Nonnull
                                                        String key,
                                                        @Nullable
                                                        String value)

Gives the option to specify custom query parameters for the request.

Note: It is recommended to only use this function for query parameters which are not supported by the VDM by default. Using this function to bypass fluent helper method calls can lead to unsupported response handling. There is no contract on the order or priority of parameters added to the request.

Example: Use the request query option $search to reduce the result set, leaving only entities which match the specified search expression. This feature is supported in protocol OData v4.

 new DefaultBusinessPartnerService().getAllBusinessPartner().withQueryParameter("$search", "Köln OR Cologne")
 

Parameters:

key - Name of the query parameter.

value - Value of the query parameter.

Returns:

The same fluent helper.

getServicePath

@Nonnull
protected String getServicePath()

getHeaders

@Nonnull
protected Map<String,String> getHeaders()

A map containing the headers to be used only for the actual request of this FluentHelper implementation.

getParametersForRequestOnly

@Nonnull
protected Map<String,String> getParametersForRequestOnly()

A map containing the custom query parameters to be used only for the actual request of this FluentHelper implementation.

getListeners

@Nonnull
protected List<ODataRequestListener> getListeners()