abstract class sap.ui.model.Model

Control sample: sap.ui.model.Model
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/model/Model
Application Component: CA-UI5-COR

This is an abstract base class for model objects.


Constructor

Constructor for a new Model.

Every Model is a MessageProcessor that is able to handle Messages with the normal binding path syntax in the target.

new sap.ui.model.Model()

Events Overview

Event Description
parseError

The parseError event is fired when parsing of a model document (e.g. XML response) fails.

propertyChange

The propertyChange event is fired when changes occur to a property value in the model.

The event contains a reason parameter which describes the cause of the property value change. Currently the event is only fired with reason sap.ui.model.ChangeReason.Binding which is fired when two way changes occur to a value of a property binding.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Since: 1.40.

requestCompleted

The requestCompleted event is fired, after a request has been completed (includes receiving a response), no matter whether the request succeeded or not.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

requestFailed

The requestFailed event is fired, when data retrieval from a backend failed.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

requestSent

The requestSent event is fired, after a request has been sent to a backend.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

parseError

The parseError event is fired when parsing of a model document (e.g. XML response) fails.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
errorCode int
url string
reason string
srcText string
line int
linepos int
filepos int

propertyChange

The propertyChange event is fired when changes occur to a property value in the model.

The event contains a reason parameter which describes the cause of the property value change. Currently the event is only fired with reason sap.ui.model.ChangeReason.Binding which is fired when two way changes occur to a value of a property binding.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Since: 1.40.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
reason sap.ui.model.ChangeReason

The cause of the property value change

path string

The path of the property

context sap.ui.model.Context

The binding context (if available)

value object

The current value of the property

requestCompleted

The requestCompleted event is fired, after a request has been completed (includes receiving a response), no matter whether the request succeeded or not.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event

The requestCompleted event

getSource sap.ui.base.EventProvider

The source of the request

getParameters object

The request parameters

url string

URL which was sent to the back end

type string

Type of the request (if available)

success boolean

Whether the request has been successful or not. In case of errors, consult the optional errorobject parameter.

errorobject object

If the request failed the error if any can be accessed in this property.

async boolean

If the request is synchronous or asynchronous (if available)

info string

Additional information for the request (if available) deprecated

infoObject object

Additional information for the request (if available)

requestFailed

The requestFailed event is fired, when data retrieval from a backend failed.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
message string

A text that describes the failure.

statusCode string

HTTP status code returned by the request (if available)

statusText string

The status as a text, details not specified, intended only for diagnosis output

responseText string

Response that has been received for the request, as a text string

requestSent

The requestSent event is fired, after a request has been sent to a backend.

Note: Subclasses might add additional parameters to the event object. Optional parameters can be omitted.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
url string

The url which is sent to the back end

type string

The type of the request (if available)

async boolean

If the request is synchronous or asynchronous (if available)

info string

Additional information for the request (if available) deprecated

infoObject object

Additional information for the request (if available)


Methods Overview

Method Description
attachParseError

Attaches event handler fnFunction to the parseError event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

attachPropertyChange

Attaches event handler fnFunction to the propertyChange event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

attachRequestCompleted

Attaches event handler fnFunction to the requestCompleted event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

attachRequestFailed

Attaches event handler fnFunction to the requestFailed event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

attachRequestSent

Attaches event handler fnFunction to the requestSent event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

bindContext

Create ContextBinding.

bindList
bindProperty
bindTree
checkFilterOperation

Checks whether the given filters contain an unsupported operator.

OData v1, v2 and Client Bindings cannot be filtered with sap.ui.model.FilterOperators, "Any" and "All". The model property mUnsupportedFilterOperators can be configured in each model subclass to describe the unsupported operators.

If any of the given filters contains nested filters, those are checked recursively.

createBindingContext
destroy

Destroys the model and clears the model data.

A model implementation may override this function and perform model-specific cleanup tasks e.g. abort requests, prevent new requests, etc.

References:

  • sap.ui.base.Object.prototype.destroy

destroyBindingContext
detachParseError

Detaches event handler fnFunction from the parseError event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

detachPropertyChange

Detaches event handler fnFunction from the propertyChange event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

detachRequestCompleted

Detaches event handler fnFunction from the requestCompleted event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

detachRequestFailed

Detaches event handler fnFunction from the requestFailed event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

detachRequestSent

Detaches event handler fnFunction from the requestSent event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

sap.ui.model.Model.extend

Creates a new subclass of class sap.ui.model.Model with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.message.MessageProcessor.extend.

fireParseError

Fires event parseError to attached listeners.

firePropertyChange

Fires event propertyChange to attached listeners.

fireRequestCompleted

Fires event requestCompleted to attached listeners.

fireRequestFailed

Fires event requestFailed to attached listeners.

fireRequestSent

Fires event requestSent to attached listeners.

getDefaultBindingMode

Get the default binding mode for the model.

getMessages

Returns messages of this model associated with the given context, that is messages belonging to the object referred to by this context or a child object of that object. The messages are sorted by their type according to the type's severity in a way that messages with highest severity come first.

getMessagesByPath

Returns model messages for which the target matches the given resolved binding path.

sap.ui.model.Model.getMetadata

Returns a metadata object for class sap.ui.model.Model.

getMetaModel

Returns the meta model associated with this model if it is available for the concrete model type.

getObject
getOriginalProperty

Returns the original value for the property with the given path and context.

The original value is the value that was last responded by a server if using a server model implementation.

getProperty
isBindingModeSupported

Check if the specified binding mode is supported by the model.

isLegacySyntax

Returns whether legacy path syntax is used.

Since 1.88.0 legacy path syntax is not supported by most model implementations.
refresh

Refresh the model.

This will check all bindings for updated data and update the controls if data has been changed.

setDefaultBindingMode

Set the default binding mode for the model.

If the default binding mode should be changed, this method should be called directly after model instance creation and before any binding creation. Otherwise it is not guaranteed that the existing bindings will be updated with the new binding mode.

setLegacySyntax

Enables legacy path syntax handling.

This defines, whether relative bindings, which do not have a defined binding context, should be compatible to earlier releases which means they are resolved relative to the root element or handled strict and stay unresolved until a binding context is set.

Since 1.88.0 legacy path syntax is not supported by most model implementations.
setMessages

Sets the messages for this model and notifies the bindings if the new messages differ from the current model messages.

setSizeLimit

Set the maximum number of entries which are used for list bindings.

The default size limit for models is 100.

attachParseError

Attaches event handler fnFunction to the parseError event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.Model itself.

attachPropertyChange

Attaches event handler fnFunction to the propertyChange event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.Model itself

attachRequestCompleted

Attaches event handler fnFunction to the requestCompleted event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.Model itself

attachRequestFailed

Attaches event handler fnFunction to the requestFailed event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.Model itself

attachRequestSent

Attaches event handler fnFunction to the requestSent event of this sap.ui.model.Model.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.model.Model itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.model.Model itself

bindContext

Create ContextBinding.

Param Type DefaultValue Description
sPath string

The path pointing to the property that should be bound

oContext sap.ui.model.Context

The context object for this databinding

mParameters object

Additional model-specific parameters

oEvents object

Event handlers can be passed to the binding ({change:myHandler})

bindList

Param Type DefaultValue Description
sPath string

The path pointing to the list / array that should be bound

oContext sap.ui.model.Context

The context object for this databinding

aSorters sap.ui.model.Sorter sap.ui.model.Sorter[]

Initial sort order (can be either a sorter or an array of sorters)

aFilters sap.ui.model.Filter sap.ui.model.Filter[]

Predefined filter/s (can be either a filter or an array of filters)

mParameters object

Additional model-specific parameters

bindProperty

Param Type DefaultValue Description
sPath string

The path pointing to the property that should be bound

oContext sap.ui.model.Context

The context object for this databinding

mParameters object

Additional model-specific parameters

bindTree

Param Type DefaultValue Description
sPath string

The path pointing to the tree / array that should be bound

oContext sap.ui.model.Context

The context object for this databinding

aFilters sap.ui.model.Filter[]

Predefined filter/s contained in an array

mParameters object

Additional model specific parameters

aSorters sap.ui.model.Sorter[]

Predefined sap.ui.model.sorter/s contained in an array

checkFilterOperation

Checks whether the given filters contain an unsupported operator.

OData v1, v2 and Client Bindings cannot be filtered with sap.ui.model.FilterOperators, "Any" and "All". The model property mUnsupportedFilterOperators can be configured in each model subclass to describe the unsupported operators.

If any of the given filters contains nested filters, those are checked recursively.

Param Type DefaultValue Description
vFilters sap.ui.model.Filter sap.ui.model.Filter[]

Single filter or an array of filter instances

createBindingContext

Param Type DefaultValue Description
sPath string

The path to create the new context from

oContext sap.ui.model.Context

The context which should be used to create the new binding context

mParameters object

The parameters used to create the new binding context

fnCallBack function

The function which should be called after the binding context has been created

bReload boolean

Force reload even if data is already available; for server-side models this should refetch the data from the server

destroy

Destroys the model and clears the model data.

A model implementation may override this function and perform model-specific cleanup tasks e.g. abort requests, prevent new requests, etc.

References:

destroyBindingContext

Param Type DefaultValue Description
oContext sap.ui.model.Context

The context to destroy

detachParseError

Detaches event handler fnFunction from the parseError event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachPropertyChange

Detaches event handler fnFunction from the propertyChange event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachRequestCompleted

Detaches event handler fnFunction from the requestCompleted event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachRequestFailed

Detaches event handler fnFunction from the requestFailed event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachRequestSent

Detaches event handler fnFunction from the requestSent event of this sap.ui.model.Model.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.ui.model.Model.extend

Creates a new subclass of class sap.ui.model.Model with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.message.MessageProcessor.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireParseError

Fires event parseError to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

errorCode int
url string
reason string
srcText string
line int
linepos int
filepos int

firePropertyChange

Fires event propertyChange to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

reason sap.ui.model.ChangeReason

The reason of the property change

path string

The path of the property

context object

The context of the property

value object

The value of the property

fireRequestCompleted

Fires event requestCompleted to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

url string

The url which was sent to the back end.

type string

The type of the request (if available)

async boolean

If the request was synchronous or asynchronous (if available)

info string

additional information for the request (if available) deprecated

infoObject object

Additional information for the request (if available)

fireRequestFailed

Fires event requestFailed to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

message string

A text that describes the failure.

statusCode string

HTTP status code returned by the request (if available)

statusText string

The status as a text, details not specified, intended only for diagnosis output

responseText string

Response that has been received for the request, as a text string

fireRequestSent

Fires event requestSent to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

url string

The url which is sent to the back end.

type string

The type of the request (if available)

async boolean

If the request is synchronous or asynchronous (if available)

info string

Additional information for the request (if available) deprecated

infoObject object

Additional information for the request (if available)

getDefaultBindingMode

Get the default binding mode for the model.

getMessages

Returns messages of this model associated with the given context, that is messages belonging to the object referred to by this context or a child object of that object. The messages are sorted by their type according to the type's severity in a way that messages with highest severity come first.

Param Type DefaultValue Description
oContext sap.ui.model.Context

The context to retrieve messages for

getMessagesByPath

Returns model messages for which the target matches the given resolved binding path.

Param Type DefaultValue Description
sPath string

The resolved binding path

bPrefixMatch boolean false

Whether also messages with a target starting with the given path are returned, not just the messages with a target identical to the given path

sap.ui.model.Model.getMetadata

Returns a metadata object for class sap.ui.model.Model.

getMetaModel

Returns the meta model associated with this model if it is available for the concrete model type.

getObject

Param Type DefaultValue Description
sPath string

Path to where to read the object

oContext sap.ui.model.Context

Context with which the path should be resolved

mParameters object

Additional model-specific parameters

getOriginalProperty

Returns the original value for the property with the given path and context.

The original value is the value that was last responded by a server if using a server model implementation.

Param Type DefaultValue Description
sPath string

Path/name of the property

oContext sap.ui.model.Context

Context if available to access the property value

getProperty

Param Type DefaultValue Description
sPath string

The path to where to read the attribute value

oContext sap.ui.model.Context

The context with which the path should be resolved

isBindingModeSupported

Check if the specified binding mode is supported by the model.

Param Type DefaultValue Description
sMode sap.ui.model.BindingMode

The binding mode to check

isLegacySyntax

Returns whether legacy path syntax is used.

Since 1.88.0 legacy path syntax is not supported by most model implementations.

refresh

Refresh the model.

This will check all bindings for updated data and update the controls if data has been changed.

Param Type DefaultValue Description
bForceUpdate boolean false

Update controls even if data has not been changed

setDefaultBindingMode

Set the default binding mode for the model.

If the default binding mode should be changed, this method should be called directly after model instance creation and before any binding creation. Otherwise it is not guaranteed that the existing bindings will be updated with the new binding mode.

Param Type DefaultValue Description
sMode sap.ui.model.BindingMode

The default binding mode to set for the model

setLegacySyntax

Enables legacy path syntax handling.

This defines, whether relative bindings, which do not have a defined binding context, should be compatible to earlier releases which means they are resolved relative to the root element or handled strict and stay unresolved until a binding context is set.

Since 1.88.0 legacy path syntax is not supported by most model implementations.
Param Type DefaultValue Description
bLegacySyntax boolean

The path syntax to use

setMessages

Sets the messages for this model and notifies the bindings if the new messages differ from the current model messages.

Param Type DefaultValue Description
mMessages Object<string,sap.ui.core.message.Message[]> {}

The new messages for the model, mapping a binding path to an array of sap.ui.core.message.Message objects

setSizeLimit

Set the maximum number of entries which are used for list bindings.

The default size limit for models is 100.

Param Type DefaultValue Description
iSizeLimit int

Collection size limit