Page tree
Skip to end of metadata
Go to start of metadata

Introduction

The Application Model is supposed to be the single point of access from the UI to the backend layer when using the FPM SPI Integration (FSI).
Internally the Application Model accesses the Service Provider Infrastructure (SPI) and for every instance of the Application Model one instance of the corresponding Service Provider (SP) will be created.
The interface of the Application Model contains all node specific methods that can also be found in the interface of the SP (/PLMB/IF_SPI_APPL_ACCESS).
Whenever one of those methods is getting called the Application Model will access the SPI, which will forward the call to the SP instance that belongs to that model.

There are two different types of Application Models, one is linked to a context and the other one is independent of any context.

Context-dependent Application Models should be used when the data that is accessed by the model is supposed to be displayed in the UI.
For the freestyle UIBBs you need to call the method GET_APPLICATION_MODEL of class /PLMU/CL_FRW_FACTORY (e.g. in the WDDOINIT of the component controller) to get an Application Model that will administer the context:

METHOD wddoinit.

  "Get an Application Model that administers the context
  wd_this->mo_application_model = /plmu/cl_frw_factory=>get_application_model(
    io_context             = wd_context
    iv_abbid               = 'MY_ABBID'
    io_componentcontroller = wd_this ).

ENDMETHOD.

For the GUIBBs every feeder class that inherits from one of our generic feeder classes already contains an instance of the Application Model (MO_APPLICATION_MODEL) that you should use.
So you don't need to create an Application Model instance when implementing a GUIBB feeder.

The usage of a context independent model makes sense when only data that is not displayed in the UI is accessed (e.g. technical data like customizing).
Such an Application Model can be obtained by using method GET_BASIC_APPLICATION_MODEL of class /PLMU/CL_FRW_FACTORY:

"Get a basic Application Model
mo_application_model = /plmu/cl_frw_factory=>get_basic_application_model(
  iv_abbid = 'MY_ABBID' ).

If the instance of an Application Model is no longer needed it can be released via method INVALIDATE_MODEL which can be found at the attribute MO_TOOLS.
This will destroy the whole model instance and the related SPI instances.

Context-Dependent Application Models

Context-dependent Application Models are:

  • /PLMU/IF_FRW_APPL_MODEL is bound to the context of a freestyle UIBB (an instance can be get via /PLMU/CL_FRW_FACTORY)
  • /PLMU/IF_FRW_G_APPL_MODEL is bound to the context of a GUIBB (every GUIBB feeder contains one instance of it)

Those models administer the context of the UIBB they are assigned to:

Context dependent Application Model

Filling the Data Provided by the Service Provider into the Context

Context-dependent Application Models automatically adjust the context data – where necessary – after every successful Service Provider (SP) call. A SP call is considered to be not successful if the EV_FAILED parameter is set to ABAP_TRUE or if for every record that was sent to the SP there is an entry in the ET_INDEX_FAILED table).
This means that if an operation is called via such an Application Model which somehow alters the data of a node that is displayed in this UIBB, the changes will directly be applied to the UIBB.

Per default an ACTION, INSERT, UPDATE and direct RETRIEVE will modify the content of the context, whereas a QUERY and a RETRIEVE by association (by a parent ID) will replace it and a DELETE will remove the respective rows from the context.

Flush Changes of the Context Data to the Service Provider

In every round-trip the application model will analyze the change log of the context and trigger an INSERT or UPDATE of all records whose node data has been changed.
No INSERT or UPDATE will be triggered if only fields were changed that are not part of the node data structure i.e. UI-only fields.

An UPDATE will be triggered if the data of a record has been changed whose node ID was submitted during a SP call i.e. a row that was provided by the backend.
An INSERT will be triggered if the node ID of the changed record was not submitted during a Service Provider (SP) call via the application model i.e. a row that was not provided by the backend but e.g. was added to the context of the UI directly. Also an INSERT will be triggered when the values of the node ID fields were changed by the user input (This should normally not be the case and is often an indicator of wrong node ID definition).

Behavior in Case of an Error during the Flush

As mentioned before the Application Model automatically triggers INSERT or UPDATE calls based on the context change log. In case those calls were not completely successful i.e. are marked as failed by the SP the Application Model will repeat the calls in the next round-trip with all records that were not successfully submitted yet. Please note that the failure of an INSERT or UPDATE does not depend on error messages that are raised by the SP but solely on the ET_INDEX_FAILED/EV_FAILED export parameters of the SP methods (Of course the messages and the failed parameters are normally kept in synch by the SP). As long as there is such a pending INSERT or UPDATE, the attribute GV_UPDATE_ERROR of the Application Model will be set to ABAP_TRUE.

Additionally the Application Model will block any RETRIEVE call that could overwrite data that was not yet successfully inserted or updated.
All other Application Model methods will not get blocked, since they might want to be used to remove the INSERT/UPDATE errors.
So if you want to avoid e.g. an ACTION to be executed in such a situation you need to check the attribute GV_UPDATE_ERROR and avoid calling this method.
The existence of such a flush error also influences the logic of the generic Application Controller as described in the respective chapter.

The Application Model stops repeating the INSERT or UPDATE if one of the following conditions becomes true:

  • The call is accepted by the Service Provider (no ET_INDEX_FAILED/EV_FAILED is set)
  • The user takes back the changes he made (i.e. all attributes are reset to their original value)
  • The record gets changed in the context via coding (e.g. an attribute of the record is changed via the context interface)
  • Another successful SP call submits the record (e.g. an ACTION is successfully triggered for the record)

Errors Due to Data Type Mismatch

If a user enters values that do not fit to the data type of a field e.g. a string is entered into a numeric field, the automatic flush will not get executed at all. Web Dynpro cannot fill such invalid entries into the context, so the data in the context is not consistent with the actual UI data in this case. Triggering an INSERT or UPDATE using the context data would make no sense.
Therefore the automatic flush will be deferred until those kind of errors are resolved

Message Processing

Any Application Model will display all the messages that its corresponding Service Provider (SP) passed to the Collector.
In addition a context-dependent Application Model will also try to link those messages to a context element, which will lead to a link in the UI that allows the user to navigate to the error by clicking on the message. If the message should be linked to a specific field, the name of this field needs to be passed along with the message to the Collector.
For more details regarding the correct forwarding of messages to the Collector please have a look at the respective section of the Collector chapter.

Furthermore the Application Model can of course only link a message to a record when the record the message refers to is contained in the context that the Application Model administers.
Example:
You have two UIBBs called A and B.
UIBB A contains records with the node IDs '1', '2' and '3'.
UIBB B contains records with the node IDs '4', '5' and '6'.
Every UIBB has its own Application Model to access the backend.
Now you are calling the backend with the Application Model of UIBB A and the called SP will pass messages with node ID '2', '3' and '4' to its Collector.
The messages with node ID '2' and '3' will be linked but the messages that refer to node ID '4' won't get linked, since the Application Model that now tries to link the messages only administers context A.

Selection Handling

The application model stores the selection of all administered contexts for two reasons:

  1. When refreshing the data in the UI e.g. via RETRIEVE, all previously selected records will automatically get selected again, if they did not get removed during the refresh of course.
  2. If an error occurs during the flush, the Application Model keeps all selections stable that are relevant for displaying the erroneous data.
    Example:
    In the UI there are two lists. The second list displays data that belongs to the selected record of the first list.
    If now an error occurs in the second list during the flush of the user input (due to a failed INSERT or UPDATE), the selection of the first list will automatically get reset as soon as the user tries to change it.
    This ensures that the error in the second list remains visible and that the selection in the first list fits to the entries of the second list.
    However in the second list the selection can be changed by the user, since this doesn't affect the erroneous entry.
    As soon as the error in the second list is gone, the selection of the first list is changeable again.

Context Independent Application Models

The only context independent Application Model is /PLMU/IF_FRW_BASIC_APPL_MODEL (an instance can be get via /PLMU/CL_FRW_FACTORY).

A context independent Application Model is supposed to be used only where the data that is read or maintained is not supposed to be bound to a context.

Since this model type doesn't administer a context it is also not able to link any messages or properties to the context.
Therefore all messages that are passed to the Collector by the SP that belongs to this model are displayed without any message link.

Methods of the Application Model

The interface of every application model contains all node specific methods that can also be found in the interface of the Service Provider (/PLMB/IF_SPI_APPL_ACCESS). The parameters of those methods are identical with the corresponding SP methods:

Transactional operations like CHECK_BEFORE_SAVE, SAVE and CLEAN_UP are not part of the application model interface, as they are handled internally.

Additional service methods can be found at the attribute MO_TOOLS of the Application Model.

Usage of the Application Model during FPM Events

If a Service Provider (SP) operation invalidates a certain node which is also visible in the UI, it is important to refresh this node's data in the UI again. To do so, normally a RETRIEVE is called during the GET_DATA phase of every FPM event.
Therefore it is important that no SP operation which may invalidate any kind of data is triggered during the GET_DATA phase, since this may lead to invalid data of UIBBs whose GET_DATA was already processed.
Instead it is strongly recommended to perform all those operations during the PROCESS_EVENT or FLUSH of the FPM event loop and only read the refreshed data during the GET_DATA.

Retrieve Filter

The RETRIEVE method of the Application Model contains a logic that blocks redundant calls. This increases the UI performance while keeping the application UI logic simple, because the application can simply call the RETRIEVE in every round-trip and the Application Model will decide if the Service Provider (SP) needs to be called or not.
What this logic does is basically filter all node IDs that are not needed to be retrieved again.
When certain node IDs are filtered also the export parameter ET_NODE_DATA will not provide the according data. So if the caller of the RETRIEVE needs the complete result data, the context should be accessed because it will contain the complete data (in case of a context-dependent Application Model), otherwise the result always needs to be buffered by the caller.

There are three boundary conditions for the retrieve filter logic:

  1. The Application Model will always evaluate the side-effect and the node invalidation of the called Service Provider (SP) operations and clear the buffer of already retrieved node IDs accordingly.
    After a CLEAN_UP call all buffers of already retrieved node IDs will be cleared.
    This means that after a node got invalidated via one of those mechanisms, the RETRIEVE will reach the SP again to fetch the up to date data.
    Example:
    You call the RETRIEVE with ID '1' of node A twice, the first time the call will reach the SP, the second time the SP will not get called. Now you call an ACTION which invalidates node A and afterwards you call again the RETRIEVE with ID '1' of node A. Now the RETRIEVE will reach the SP again.
  2. Whenever there are multiple instances of the Application Model that belong to the same Application Building Block ID (ABBID), all calls that modify the data of a node on one of those instances will lead to an adjustment of the retrieve filter of the other instances.
    This means that it is not necessary to use myself side-effects or node invalidation to ensure that data which is accessed by multiple Application Model instances is always up-to-date (e.g. when the same node is displayed in various UIBBs).
    Example:
    You are using two context-dependent Application Models which both belong to the same ABBID, let's call them model A and model B.
    On both models you retrieve node IDs '1', '2' and '3' of the same node.
    When you now UPDATE the data of node ID '1' via model A, you will get the result of that call applied to the corresponding context directly.
    The context of model B however doesn't immediately get adjusted. Therefore the retrieval of ID '1' is required.
    So the Application Model will remove node ID '1' from the retrieve filter of model B and when the next RETRIEVE is called with the same IDs only node ID '2' and '3' will get filtered, but ID '1' will be retrieved again and therefore the context will be refreshed.
    All this happens automatically without any need for side-effects or node invalidation!
  3. The retrieve mode defines the filter logic.
    The default retrieve mode is APPEND_NEW. The only exception is the RETRIEVE by association whose result will be filled by the Application Model into a singleton context node – this kind of RETRIEVE will have the mode EXACT_MATCH as default (every GUIBB context and every root context node of a freestyle UIBB will be treated like a singleton).
    You can change the default mode by using the attribute MO_TOOLS of the Application Model, or via setting the according GUIBB feeder parameters.
    The behavior of the available retrieve modes is the following:
    • APPEND_NEW:
      Filter node IDs that are part of the retrieve filter buffer (i.e. node IDs which were already retrieved before and which were not affected by any side-effect or node invalidation that happened in the meantime) and retrieve the remaining node IDs.
      If a SP RETRIEVE was executed and a context is available all records with new node IDs will be appended to the context and records with node IDs which are already contained in the context will overwrite the existing entries with the new data.
    • EXACT_MATCH:
      Filter node IDs only if they are an exact match of the node IDs of the last RETRIEVE call for this node (if of course no side-effect or node invalidation that affects that node happened in the meantime), otherwise retrieve all node IDs again.
      If a SP RETRIEVE was executed and a context is available the complete content of the context will be replaced with the result of the RETRIEVE.

Attributes of the Application Model

Basic Application Model Attributes

Every Application Model offers the following attributes:

Attribute

Data Type

Description

GV_UPDATE_ERROR

BOOLE_D

Is set to ABAP_TRUE if there exists an error within one of the application models that occurred during an automatic INSERT or UPDATE (flush) or if mandatory fields were not filled.

MV_UNSAVED_DATA

BOOLE_D

Is set to ABAP_TRUE if a save-relevant operation has been triggered since the last SAVE. (Which operations are save-relevant is defined in the Metadata Provider)

MO_METADATA

/PLMB/IF_SPI_METADATA_OUTPUT

Provides an interface to access the Metadata of the corresponding Service Provider

MO_TOOLS

/PLMU/IF_FRW_BASIC_TOOL

Offers services concerning the Application Model

The interface /PLMU/IF_FRW_BASIC_TOOL offers the following methods:

ACTIVATE_SP_CALL_LOG

This method activates a log that traces all SP calls.

Method signature:

Parameter

Data Type

Description

IV_ACTIVATE

BOOLE_D

Flag to (de-)activate the SP call log

GET_RETRIEVE_MODE

This method provides the current RETRIEVE mode.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node Name (mandatory)

EV_DIRECT_RETRIEVE

/PLMU/FRW_RETRIEVE_MODE

Mode of the direct RETRIEVE

EV_RETRIEVE_BY_ASSOCIATION

/PLMU/FRW_RETRIEVE_MODE

Mode of the RETRIEVE by association

GET_SP_CALL_LOG

This method returns the SP call log (and allows you to clear it).

Method signature:

Parameter

Data Type

Description

IV_AND_RESET

BOOLE_D

Allows to reset the SP call log

ET_SP_CALL_LOG

/PLMU/T_FRW_SP_CALL_LOG

Log of SP calls

INVALIDATE_MODEL

This method releases the instance of the Application Model and the corresponding SP (This makes the model instance unusable).

Method signature:

Parameter

Data Type

Description

IV_CHANGES_REVERTED

BOOLE_D

Indicates that all save-relevant data changes were reverted

SET_MESSAGE_MAPPER

This method allows you to define a message mapper for this application model instance that can alter or delete messages before they are forwarded to the UI; the message mapper needs to implement the interface /PLMU/IF_FRW_MESSAGE_MAPPER.

Method signature:

Parameter

Data Type

Description

IO_MESSAGE_MAPPER

/PLMU/IF_FRW_MESSAGE_MAPPER

Message Mapper (mandatory)

The message mapper interface /PLMU/IF_FRW_MESSAGE_MAPPER has only one method called MAP_MESSAGES, which offers the following parameters:

Parameter

Data Type

Description

IO_METADATA

/PLMB/IF_SPI_METADATA_OUTPUT

Metadata output interface

CT_MESSAGE

/PLMB/T_SPI_COLL_MESSAGE_ENH

Message table

SET_RETRIEVE_MODE

This method allows you to alter the default RETRIEVE mode of the direct RETRIEVE and the RETRIEVE by association on node level (use constant /PLMU/IF_FRW_CONSTANTS=>GC_RETRIEVE_MODE)

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_DIRECT_RETRIEVE

/PLMU/FRW_RETRIEVE_MODE

Mode of the direct RETRIEVE

IV_RETRIEVE_BY_ASSOCIATION

/PLMU/FRW_RETRIEVE_MODE

Mode of the RETRIEVE by association

INITIALIZE_RETRIEVE_FILTER

This method initializes the RETRIEVE filter for one or all nodes.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name

Attributes of Context-Dependent Application Models

All context-dependent Application Models provide in addition to the basic attributes the following ones:

Attribute

Data Type

Description

MT_CONTEXT_CHANGE_LOG

/PLMU/T_FRW_CHANGE_LOG

Contains a list of all context changes performed by the Application Model

MO_TOOLS

/PLMU/IF_FRW_C_TOOL

Offers in addition to the basic functionality also some more features

The interface /PLMU/IF_FRW_C_TOOL includes interface /PLMU/IF_FRW_BASIC_TOOL and offers in addition the following methods:

PULL_FIELD_PROPERTIES

This method pulls field properties from the Service Provider (if supported) and applies them to the context.

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_TARGET_NODE_NAME

/PLMB/SPI_NODE_NAME

Target node name

IV_REFERENCE_TYPE

/PLMB/SPI_PRPTY_REF_TYPE

Provides the context of the properties in combination with the reference data (mandatory)

IG_REFERENCE_DATA

ANY

Reference data

PULL_OPERATION_PROPERTIES

This method pulls operation properties from the Service Provider (if supported) and applies them to the context.

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_TARGET_NODE_NAME

/PLMB/SPI_NODE_NAME

Target node name

IV_REFERENCE_TYPE

/PLMB/SPI_OPR_PRPTY_REF_TYPE

Provides the context of the properties in combination with the reference data (mandatory)

IG_REFERENCE_DATA

ANY

Reference data

Attributes of Freestyle UIBB Application Models

Application Models that are used to administer the Web Dynpro context of a freestyle UIBB offer in addition to the attributes of the context-dependent Application Models the following attributes:

Attribute

Data Type

Description

MT_REQUIRED_ERROR

/PLMU/T_FRW_NODE_UPD_ERROR_IND

Contains details about all errors that were caused by empty mandatory fields

MT_UPDATE_ERROR

/PLMU/T_FRW_NODE_UPD_ERROR_IND

Contains details about all errors that occurred during an automatic INSERT or UPDATE (flush)

MO_TOOLS

/PLMU/IF_FRW_F_TOOL

Offers in addition to the functionality of all context-dependent Application Models also some more features:

The interface /PLMU/IF_FRW_F_TOOL includes interface /PLMU/IF_FRW_C_TOOL and offers in addition the following methods:

SET_DEFAULT_ROWS

This method allows specifying the amount and optionally the default values of 'empty' rows of your context (which might be bound to a table in a freestyle UIBB) which are used to INSERT new records.

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_NUMBER_OF_ROWS

INT4

Number of Required Default Rows (mandatory)

IS_DEFAULT_ROW

ANY

Content of Default Rows

Usage of Method

This method is only supposed to be called once e.g. during the initialization of the application and afterwards the Application Model will append new rows whenever necessary.
If however the content or number of default rows is supposed to change at runtime this method can be called again. When calling this method again at runtime it is important to know that only newly appended default rows will be affected and no existing default rows will be removed.

SET_OPERATIONS_MAPPING

This method allows defining the mapping of SP operations to a Web Dynpro attribute whose properties will then be set according to the operation properties set by the application. This mapping allows you to e.g. control the visibility of a button via the Collector.

Parameter

Data Type

Description

IT_MAPPING

/PLMU/TS_FRW_OPR_NODE_MAP

Map of SP operations to Web Dynpro node attributes

The mapping table of type /PLMU/TS_FRW_OPR_NODE_MAP that needs to be filled has the following components:

Component

Data Type

Description

ABBID

/PLMB/SPI_ABBID

Application Building Block ID

SP_NODE_NAME

/PLMB/SPI_NODE_NAME

SPI node name

OPERATION_TYPE

/PLMB/SPI_OPERATION_TYPE

Operation type (e.g. UPDATE, ACTION, ...)

ACTION_NAME

/PLMB/SPI_OPERATION_NAME

Operation name (only applicable for ACTION and QUERY)

WD_NODE_NAME

STRING

Web Dynpro context node name

WD_ATTRIBUTE_NAME

STRING

Web Dynpro context node attribute name

  • No labels